# Rhiz Protocol — Agent Authentication and Interface Contract

This document tells an autonomous agent what Rhiz exposes today, how current credentials are bounded, and which machine-interface direction is canonical.

Rhiz represents humans, Organizations, Workspaces, and autonomous agents as distinct but linkable actors. **Authentication is never sufficient authority by itself. Context and scope still govern access and consequential action.**

## Identity

- **Service:** Rhiz Protocol
- **Site:** https://rhiz.network
- **MCP doorway:** https://rhiz.network/api/mcp
- **Protocol family:** Rhiz/RCP, CLI-first agent interface, HTTP, MCP, A2A discovery

## Machine-interface doctrine

Rhiz uses **one semantic command/capability kernel with multiple adapters**.

For an authorized agent with a trustworthy shell, the target preferred doorway is the `rhiz` CLI. Direct HTTP and MCP remain valid remote adapters when the host, authorization model, tenancy boundary, or deployment environment requires them. The CLI does not create authority, and MCP does not create a second Rhiz ontology.

The CLI-first public command surface is **sequenced work, not a live product claim yet**. Current live machine access is through the authenticated HTTP/PAT and MCP seams described below.

Current authority:

- `https://rhiz.network/docs/canon/decisions/2026-08-23-cli-first-agent-interface-and-command-kernel.md` in the repository for interface doctrine;
- Rhiz Context/permission/approval rules for authority;
- executable source and tests for what is live.

## Discovery

| Document | Path |
| --- | --- |
| A2A agent card | `https://rhiz.network/.well-known/agent.json` |
| Protected resource metadata | `https://rhiz.network/.well-known/oauth-protected-resource` |
| Authorization server metadata | not served — Rhiz is not an authorization server yet |
| This contract | `https://rhiz.network/auth.md` |

Discovery metadata can describe sequenced endpoints as unavailable. Treat source and the Status section below as the executable-truth boundary.

## Live personal-agent credentials

A signed-in Rhiz member connects an AI client and grants it Rhiz capability at `https://rhiz.network/console/connections`. A verified credential alone -- PAT or OAuth token -- carries no Rhiz authority until that grant exists.

Personal Access Token issuance, listing and revocation is sequenced work, not a live TypeScript surface yet. Treat the Status section below as the executable-truth boundary for what is live today.

## Live MCP surface

There is **one** MCP endpoint:

`POST https://rhiz.network/api/mcp`

- **Transport:** Streamable HTTP, stateless. One request, one transport, no server-held session that could become a second identity.
- **Protocol version:** `2025-06-18`.
- **Credential:** a Clerk OAuth access token (`delegated`), or a `rhiz_*` Personal Access Token (`pat`). Neither carries Rhiz capability by itself.
- **No client-asserted header.** The acting client is whatever the credential itself proves -- none for a PAT, Clerk's signer for a delegated token -- so the doorway reads no app-id header a caller could name for itself.
- **Required scope:** `mcp.access` on every tool. There is no per-tool scope in this model; a tool's own authority decisions are made by the command it calls, not by the transport.
- **Tool discovery:** `tools/list` on the endpoint is authoritative. The agent card lists the same set for clients deciding whether to connect.

The retired Python MCP transport, and its superseded two-route SSE pair before it, are gone: the whole Python MCP router is deleted, not merely unmounted. `scripts/check_discovery_honesty.mts` fails the build if any served document names a retired MCP path again.

The current MCP security boundary:

- fails closed without a bound authenticated principal;
- binds execution to the canonical owner identity;
- applies `mcp.access` and rate limits;
- binds each request's dispatch to the principal authenticated for that request;
- binds database sessions to the caller before graph queries;
- collapses not-found and not-visible where required to avoid private existence leaks;
- emits no assumption that account/tool access implies permission for consequential action.

### OAuth

Authorization is delegated to **`https://clerk.rhiz.network`**, named in `authorization_servers` in the protected-resource metadata. Rhiz does not serve authorization-server metadata of its own and never will: it is a resource server, and restating someone else's endpoints only creates a copy that can go stale. Read them from the authorization server's own `/.well-known/` documents.

An uncredentialed request to the MCP doorway answers **401** with `WWW-Authenticate: Bearer resource_metadata="…"`, so a conformant client is pointed at that document without needing to know where to look.

**Two vocabularies, deliberately separate.**

`scopes_supported` in the protected-resource metadata is what the authorization server will actually issue: `openid`, `profile`, `email`, `offline_access`. Those establish **who** the member is and let a connector refresh.

Canonical Rhiz capabilities — `mcp.access`, `identity.read`, `graph.read` and their siblings — are **not OAuth scopes**. The authorization server cannot issue them; requesting one returns `invalid_scope`. They are granted by the member, per client, and held in Rhiz. So a valid OAuth token proves who is calling and which client is acting, and carries **no Rhiz authority on its own**: a member who has authenticated but not granted a client anything gets a **403** telling them to connect it, never a quiet read.

That separation is why connecting an AI client cannot widen what it may do. Authentication is not authorization, and the second question is answered here rather than by the identity provider.

A PAT remains supported unchanged: mint one from a signed-in Rhiz session and present it as a bearer token. No app-id header is read for either credential kind.

MCP is a remote-governance adapter over the shared capability kernel. New product semantics should not be implemented only inside MCP.

## REST/API access

PAT-backed callers resolve into the same Rhiz authentication context used by protected HTTP routes. Route-level scopes, Row-Level Security, capability entitlement, Context authority, and approval requirements continue to apply.

No agent receives raw database access as a supported product contract.

## Consequential action

An agent credential never implies permission to publish, send, pay, modify identity/permission, use sensitive data outside its Context, or perform another consequential effect.

Consequential operations must continue through the applicable Rhiz approval/authorization, correlation, idempotency, Evidence, Receipt, and Outcome seams.

## Provider authentication

When a local product such as Claude Code or Codex eventually invokes the `rhiz` CLI, that product should keep its provider-native authentication. Rhiz authenticates the Rhiz principal and Rhiz action. Rhiz does not need to copy the provider's consumer credential merely because the provider's agent can execute a local command.

Remote multi-user deployments may require OAuth/OIDC, managed workload identity, tenant policy, or another stronger authorization boundary. CLI efficiency never overrides user/tenant authority.

## Sequenced work

The current CLI-first plan sequences:

1. one versioned Rhiz command/capability kernel;
2. a small `rhiz` executable with concise help and runtime schema discovery;
3. authenticated `rhiz login` / agent setup using revocable Rhiz credentials;
4. bounded Context reads before a wide command catalog;
5. canonical Capture/internal writes with idempotent receipts;
6. approval-gated consequential action;
7. tiny persistent agent discovery hints plus focused Rhiz Skills;
8. HTTP/MCP adapters derived from the same capability contracts;
9. cross-agent continuity and interface benchmarks before public portability claims.

The detailed execution plan is `docs/plans/2026-08-23-001-feat-cli-first-rhiz-everywhere.md` in the Rhiz Protocol repository.

## Still not live

Do not assume these are available merely because they are part of the architecture:

- the canonical public `rhiz` CLI command surface;
- generalized `rhiz setup agent` installation across Claude Code, Codex, and other agents;
- user-claimed email/OTP autonomous-agent registration;
- trusted-provider ID-JAG;
- full OAuth authorization-server control plane for arbitrary third-party agents;
- broad ChatGPT/Claude/Perplexity memory import;
- generalized autonomous money/identity mutation;
- a broad connector or agent marketplace.

## Trust boundaries

Important boundaries include:

- human account session → per-client capability grant at `https://rhiz.network/console/connections`;
- PAT or OAuth-delegated token → normalized Rhiz auth context;
- auth context → Context participation and scoped resources;
- MCP/HTTP/CLI adapter → shared capability handler;
- proposed consequential action → explicit approval/authorization;
- executor result → normalized Evidence/Receipt/Outcome;
- external provider memory → provenance-bearing candidate, never automatic Rhiz truth.

Half-built work across these boundaries must fail closed.

## Status

**Live today:**

- this `/auth.md` contract;
- A2A agent card and protected-resource metadata (no authorization-server document: there is no authorization server);
- PAT resolution into Rhiz auth/RLS context;
- OAuth-delegated resolution into Rhiz auth context via Clerk;
- the authenticated MCP doorway at `https://rhiz.network/api/mcp`, Streamable HTTP, protocol `2025-06-18`;
- explicit `mcp.access` enforcement and per-client capability grants at `https://rhiz.network/console/connections`;
- owner-scoped MCP execution and rate limiting.

**Active direction:**

- CLI-first machine interface;
- one shared command/capability kernel;
- Harness convergence behind that kernel;
- thin HTTP/MCP adapters;
- cross-agent continuity and measured interface routing.

## Out of scope for this contract

- replacing the human web-session identity provider;
- granting agents broad admin access by default;
- ambient shell credentials as Rhiz permission;
- agent mutation of money paths, payment settings, or membership entitlements without separate review;
- browser automation, CAPTCHA bypass, or scraping human signup pages as an auth strategy;
- a second CLI-only authority, memory, event, Mission, approval, or receipt system.

## Contact

Issues, security reports, and integration questions: file at the Rhiz Protocol repository, or email `is@werhiz.com`.

---

_Last updated: 2026-09-25._