Support Relayfile per-user governance contract

[khaliqgant]

Context

Relayfile now has a draft cross-repo spec for mapping MCP-style per-user governance onto Relayfile's filesystem model:

• Source repo: AgentWorkforce/relayfile
• Branch: codex/productized-cloud-mount-relayfile
• Spec path: docs/per-user-governance-contract.md

The core framing is:

MCP governs per-user tool calls. Relayfile governs per-user filesystem paths and writeback operations.

This issue tracks the relayauth side of that contract.

Why this matters

The Scalekit-style MCP-vs-CLI argument is right that customer-facing agents need governance properties that plain CLI does not provide:

• per-user authorization
• tenant isolation
• explicit boundaries
• revocation
• structured audit
• attribution back to a human sponsor

Relayfile can provide those properties through file paths rather than MCP tool calls, but only if relayauth is the authority for agent identity, scoped tokens, delegation, policy, revocation, and audit semantics.

Relayauth-owned requirements

Relayauth owns identity, token, scope, RBAC, policy, revocation, and audit semantics.

Required changes from the spec:

1. Ensure token format supports org, wks, sponsorId, sponsorChain, jti, aud, exp, and delegated parentTokenId.
2. Ensure scope matching supports all Relayfile scope families used by the governance contract:
   • relayfile:fs:*:<path>
   • relayfile:ops:*:<path>
   • relayfile:sync:*:<path>
   • relayfile:integration:*:<path>
3. Provide APIs for child-token issuance with subset enforcement.
4. Reject delegation attempts where child scopes exceed the parent token/effective identity boundary.
5. Emit audit events for attempted delegation escalation.
6. Expose token, session, and identity revocation APIs that Relayfile can honor.
7. Keep public @relayauth/* packages platform-agnostic; Cloudflare storage, KV, D1, and Durable Object implementations belong in AgentWorkforce/cloud under packages/relayauth.

Token shape expected by Relayfile

{
  "sub": "agent_review_bot",
  "org": "org_acme",
  "wks": "ws_acme_support",
  "sponsorId": "user_jane",
  "sponsorChain": ["user_jane", "agent_lead", "agent_review_bot"],
  "scopes": [
    "relayfile:fs:read:/github/repos/acme/api/pulls/*",
    "relayfile:fs:write:/github/repos/acme/api/pulls/*/reviews/*",
    "relayfile:ops:read:/github/*"
  ],
  "aud": ["relayfile"],
  "exp": 1772004000,
  "jti": "tok_example",
  "parentTokenId": "tok_parent_if_delegated"
}

Delegation acceptance case

Given a lead token with:

relayfile:fs:read:/github/*
relayfile:fs:write:/github/*/reviews/*

When the lead invites a sub-agent requesting:

relayfile:fs:read:/github/repos/acme/api/pulls/*

Then relayauth should issue a child token with:

• narrowed scopes
• expiry no later than the parent token
• sponsor chain extended with the child agent
• parentTokenId set
• audit event recording issuance

Delegation denial case

Given the same lead token, when the lead invites a sub-agent requesting:

relayfile:fs:write:/slack/*

Then relayauth must reject issuance and emit an audit event for attempted escalation.

Audit fields Relayfile needs

For each token issuance, validation, scope check, denial, and revocation, Relayfile needs enough audit context to correlate with its own VFS/writeback logs:

interface GovernanceAuditContext {
  requestId: string;
  correlationId: string;
  orgId: string;
  workspaceId: string;
  agentId: string;
  sponsorId: string;
  sponsorChain: string[];
  tokenId: string;
  requestedScope: string;
  matchedScope?: string;
  result: "allowed" | "denied" | "error";
  reason?: string;
}

Open questions for relayauth

1. Are relayfile:ops, relayfile:sync, and relayfile:integration valid resource families under the existing scope parser, or do they need explicit resource/action validation updates?
2. Should child-token issuance be modeled as a token endpoint option, a dedicated delegation endpoint, or an identity lifecycle operation?
3. What is the expected revocation propagation SLA Relayfile should document for local mounts?
4. Should attempted provider-connection access denials be represented as relayauth scope.denied events, Relayfile audit events, or both?

Cross-repo follow-up

The Relayfile spec assigns work across:

• AgentWorkforce/relayfile: filesystem enforcement, writeback metadata, generated _PERMISSIONS.md
• AgentWorkforce/relayauth: identity, scopes, delegation, revocation, audit
• AgentWorkforce/cloud: hosted provider connections and Cloudflare relayauth deployment
• AgentWorkforce/relayfile-providers: provider credential resolution
• AgentWorkforce/relayfile-adapters: writeback policy definitions
• AgentWorkforce/relaycast: identity/correlation in invites

[khaliqgant]

Scoping audit (cross-referencing existing code)

1. Token claim shape

Today: RelayAuthTokenClaims at packages/types/src/token.ts:12-38 already declares sub, org, wks, sponsorId, sponsorChain, jti, aud, exp, and an optional parentTokenId. isValidClaims in packages/server/src/routes/tokens.ts:611-626 enforces shape on the verifier side.
Gap: parentTokenId is on the type but never populated. issueTokenPair at packages/server/src/routes/tokens.ts:324-388 constructs access/refresh claims without setting it, and the POST /tokens body type (IssueTokenRequest at line 12) has no parent-token field. aud defaults to [scope-plane] via normalizeAudience (line 639-653), so a Relayfile-targeted token requires the caller to pass audience: ["relayfile"] explicitly.

2. Scope matcher

Today: Parser at packages/sdk/typescript/src/scope-parser.ts accepts the relayfile plane and any resource matching ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, so ops, sync, integration parse without changes. relayfile:fs:*:<path> gets special treatment via normalizeFsPath (lines 31-73).
Gap: Path-prefix matching (/foo/* granted matches /foo/bar requested) is gated to relayfile+fs only — see matchPath at packages/sdk/typescript/src/scope-matcher.ts:16-31. For relayfile:ops:read:/github/*, relayfile:sync:trigger:/github/*, relayfile:integration:manage:/github/*, only exact path equality or universal * match. Path normalization (POSIX, .. rejection, trailing-only /*) also runs only for fs. Both conditionals need to broaden to the four contract resource families.

3. Child-token issuance API with subset enforcement

Today: validateSubset and isSubsetOf exist in packages/sdk/typescript/src/scope-matcher.ts:98-128. POST /v1/api-keys calls validateSubset(auth.claims.scopes, scopes) at packages/server/src/routes/api-keys.ts:65. POST /v1/identities extends sponsorChain: [...auth.claims.sponsorChain, id] (routes/identities.ts:448).
Gap: No dedicated child-token endpoint. POST /v1/tokens (routes/tokens.ts:100-150) uses scopesWithinGrant(accessScopes, identity.scopes) (line 127) — i.e. it narrows against the target identity's stored scopes, not the caller's parent token. There is no flow that takes a parent token + requested child scopes + child agent and emits a token with narrowed scopes, capped expiry (min(parentExp, requestedExp)), parentTokenId set, and sponsorChain extended. The pieces exist; nothing wires them together.

4. Reject delegation when child scope exceeds parent

Today: POST /v1/identities (routes/identities.ts:403-469) accepts arbitrary body.scopes via normalizeStringList with no subset check against auth.claims.scopes. A caller with relayauth:identity:manage:* can mint a child identity with relayfile:fs:write:* regardless of their own scope grant.
Gap: Identity creation needs the validateSubset(auth.claims.scopes, body.scopes) guard that already protects api-key creation. Token issuance needs the same guard against the caller's token, not just the target identity's stored scopes. Without these, requirement 3's subset enforcement is bypassable.

5. Audit events for delegation escalation attempts

Today: scope.escalation_denied is a first-class action in the audit type union (packages/types/src/audit.ts:20, packages/server/src/storage/interface.ts:27, engine/audit-logger.ts:14,46,211, routes/audit-query.ts:79, webhook dispatcher list). Storage and queries accept it.
Gap: Zero call sites emit it. routes/api-keys.ts:67-68 catches the RelayAuthError("scope_escalation") and returns 403 without calling storage.audit.write({action: "scope.escalation_denied", ...}). Identity-create doesn't check at all. The action exists in name only.

6. Token / session / identity revocation APIs

Today: POST /v1/tokens/revoke (routes/tokens.ts:230-283) accepts tokenId | identityId | sessionId and writes a token.revoked audit row. POST /v1/identities/:id/suspend (routes/identities.ts:263-334) cascade-revokes child identities (storage.identities.listChildIds) and their active tokens. Refresh-token reuse triggers cascadeRevokeSession (lines 507-550). RevocationStorage.isRevoked is checked in introspect and refresh flows.
Gap: Mostly covered. No public "is this token revoked" endpoint Relayfile can poll without bearer auth on /introspect; whatever revocation-propagation SLA Relayfile mounts need (open question 3 in the issue) is not documented. Provider-connection revocation lives in cloud, not relayauth.

7. Platform-agnostic packages

Today: Production source under packages/server/src/ and packages/sdk/typescript/src/ has no cloudflare:workers or D1Database runtime imports — only __tests__/*.test.ts reference D1Database as a structural type. Cloud-side adapters live at cloud/packages/relayauth/src/storage/cloudflare/ and cloud/packages/relayauth/src/durable-objects/identity-do.ts.
Gap: None. The split is currently respected. Watch for new storage interface methods added for delegation/revocation that need a corresponding cloud adapter update.

Recommended next steps

• Wire validateSubset into both POST /v1/identities and POST /v1/tokens against auth.claims.scopes, and emit scope.escalation_denied audit rows from the catch blocks. Smallest unit, unblocks 3-5.
• Generalize matchPath and normalizeFsPath in scope-matcher.ts / scope-parser.ts from resource === "fs" to the four contract resource families (fs, ops, sync, integration), with tests covering relayfile:ops:read:/github/* and friends.
• Add a dedicated child-token issuance flow (either a new endpoint or a parentTokenId option on POST /v1/tokens) that: narrows scopes via validateSubset(parentClaims.scopes, requested), caps exp at min(parentExp, requestedExp), extends sponsorChain, persists parentTokenId, and writes token.issued audit with parent linkage.