Add RFC 7523 client_credentials grant (private_key_jwt, EdDSA) for headless agent auth

[tps-flint]

Problem

Headless agents (no browser, no human at request time) need to authenticate as themselves
to a Harper MCP server's /mcp endpoint. The plugin today issues MCP tokens only via the
authorization-code + refresh flow — both assume an interactive human consent step. There is no
grant an autonomous agent can complete on its own.

Proposed solution — the standards path

RFC 7523 private_key_jwt client authentication + a client_credentials grant. This is the
current, preferred standard for "a named client authenticates as itself" (it's what the MCP
client-credentials extension and WorkOS/Scalekit agent-auth build on). No browser, no human, ever.

Add to the token endpoint:

• grant_type=client_credentials with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  and a client_assertion JWT (RFC 7523 §2.2).
• Assertion verification:
  • alg: EdDSA (Ed25519, RFC 8037). The plugin's current jsonwebtoken dep cannot verify
    EdDSA, but this needs no new dependency — Node's built-in crypto does it natively:
    crypto.verify(null, signingInput, publicKey, sig) over the JWT's header.payload, with the
    key reconstructed via crypto.createPublicKey({key: jwk, format: 'jwk'}). Verified end-to-end
    (correct key → true, tampered payload → false) on Node 25. ~15 lines of JWT plumbing, zero deps.
  • Verify against the registered client's public key.
  • Required claims: iss = sub = client_id; aud = the token endpoint; short exp
    (recommend ≤ 60s); jti (replay guard); iat.
• Issued token: unchanged RS256 Bearer from the existing tokenIssuer machinery; aud = the
  MCP resource; short TTL (see security reqs).

Client registration

Each agent is registered as an MCP client whose registered credential is its Ed25519 public
key as a JWK ({kty:"OKP", crv:"Ed25519", x:"…"}) — the format crypto.createPublicKey consumes
directly. Ideally reuses the existing clientStore / dcr path. The agent's single long-lived
Ed25519 key then serves as both its identity and its client-assertion signing key — no new key
material.

Security requirements (from an internal security design review — please carry into the grant)

1. Assertion replay guard: enforce exp ≤ 60s and a jti nonce store (reject a re-seen
   jti within the window). Timestamp-only is insufficient.
2. Issued-token TTL ≤ 5 minutes. Re-mint on 401; no refresh token needed. Limits leak blast radius.
3. Audience binding fail-closed: issued aud MUST exactly equal the MCP resource — no prefix/wildcard.
4. Audit log every issuance: client_id, audience, timestamp, jti.
5. Rate-limit the grant (defense-in-depth).
6. No Basic-admin shortcut: obtaining an agent token must require proving possession of the
   client's private key — a human/service Basic super_user must not be able to mint a token as
   an agent. (client_credentials + private_key_jwt gives this for free; flagging so it stays true.)

Division of responsibility

• Plugin (this repo): the grant, assertion verification (incl. EdDSA), client registration of a
  public key, the 6 security reqs above.
• Consumer side (separate, ours): registering each agent as a client with its existing Ed25519
  pubkey, and a small helper that builds + signs the assertion and does the round-trip. No
  consumer code reaches into plugin internals — putting the grant in the plugin is what makes
  that clean, versus a consumer-built token endpoint poking at the plugin's key table.

Decided (design constraints)

• No new dependency. EdDSA verify via built-in node:crypto (proven end-to-end), not jose.
• Standards spine: RFC 7523 (client_assertion) + RFC 8037 (EdDSA/Ed25519) + OAuth 2.1
  client_credentials. Nothing bespoke.
• Key format: Ed25519 public key as a JWK OKP in the client record.

Open coordination question

1. Client registration through the existing DCR path, or a new admin-gated registration
   command? Leans admin-gated for a fixed fleet, but that's a call on the plugin's registration model.

[heskew]

This is useful and directionally complete — the headless-agent gap is real (the concrete consumer is Flair cloud agents talking to a Harper MCP server directly), and RFC 7523 + RFC 8037 + client_credentials is the right spine. This merges two review passes (Claude + Codex); the following contract details should be settled here so implementation doesn't have to guess.

Registration

• Answering the open question: extend the existing DCR path, but gate it. Open DCR is tolerable today only because the auth-code flow still requires a human upstream login; with client_credentials, registration alone yields tokens. Any registration whose grant_types includes client_credentials must require the configured initialAccessToken (present + match) even when DCR is otherwise open — and it should be an error to register one when no initialAccessToken is configured.
• Shape: token_endpoint_auth_method: "private_key_jwt", grant_types: ["client_credentials"], key material in the standard RFC 7591 jwks field — a JWK Set of public OKP/Ed25519 keys only (reject any key carrying a private d). client_credentials-only clients need no redirect_uris (currently required unconditionally in DCR) and no response_types.
• Open (lean, not decided): jwks by value vs jwks_uri. Lean jwks-only for v1 — a fixed agent fleet doesn't host keys, and jwks_uri adds an outbound fetch (SSRF surface, availability coupling) for no benefit here. Defer jwks_uri until a key-rotation story needs it.

Assertion validation (RFC 7523 §3, strict)

• client_id required in the form body; must equal assertion iss and sub.
• aud must equal the exact resolved token-endpoint URL — and the resolution rule (configured issuer + token path) must be defined so proxy/origin variance can't create ambiguous comparisons.
• Header alg must be exactly EdDSA, fail closed on anything else (no none, no RS/HS confusion); key selected from the registered JWK Set (kid required if the set has more than one key).
• exp required and ≤ 60s out; iat required and not in the future; jti required.

Replay guard — Harper-shaped

• Shared Harper table keyed by jti with a short TTL (≥ the max assertion window); reject any re-seen jti. A per-process cache does not satisfy this in a cluster.
• Caveat to carry in the code, not hide: Harper has no atomic compare-and-set and replication is async, so a narrow concurrent-replay race exists — the same documented, accepted race as the auth-code single-use consume, bounded here by the ≤ 60s exp. Spec the shared-table guard with the documented race; don't spec atomicity the platform can't provide.

Resource binding

• There is no /authorize step to carry the audience, so the token request must supply it explicitly: accept the RFC 8707 resource parameter, defaulting to the configured canonical resource. Validate exact-match, fail-closed (req 3 — no prefix/wildcard) against the resources the client is registered for. Without this, any registered agent is implicitly valid for every resource the server ever hosts.

Issued-token contract

• sub = client_id (RFC 9068 §2.2 convention). Document loudly: for this grant the token's sub is a client identity, not an end user — the MCP resource decides what principal/permissions that maps to.
• The ≤ 5 min TTL needs its own knob (e.g. mcp.clientCredentials.accessTokenTtl, default 300). The global accessTokenTtl default (1h) serves human sessions and must not change.
• No refresh token, ever, for this grant (re-mint on 401 as the issue says) — and registration validation should reject client_credentials combined with refresh_token in grant_types.

Audit & hooks

• Reuse the existing oauth.mcp.token.issued audit event (req 4 then comes free via the existing mint path). The token-issued hook's type field gains a third value ('client_credentials') — that's public plugin API surface, so it must be documented as part of this change, not an incidental.

Rate limiting (req 5)

• Nothing in the plugin rate-limits anything today; this is new infrastructure and inherently per-node unless table-backed. Recommend scoping it explicitly as per-node, in-memory defense-in-depth — or splitting it into a follow-up so it doesn't gate the grant.

Threat-model ceiling on req 6

• "No Basic-admin shortcut" holds at the OAuth endpoint layer, and private_key_jwt gives it for free there. But the signing private key lives in a Harper table, so a Harper super_user can read it and self-mint arbitrary tokens via the operations API. That's consistent with Harper's admins-are-trusted model — req 6 just shouldn't be stated as a stronger guarantee than that.

Discovery, tests, docs

• AS metadata: add client_credentials to grant_types_supported, private_key_jwt to token_endpoint_auth_methods_supported, and advertise token_endpoint_auth_signing_alg_values_supported: ["EdDSA"].
• Test matrix: DCR key registration (including private-d rejection and gate enforcement), assertion verify success, wrong alg, wrong key, tampered payload, expired/future assertion, aud mismatch, client_id/iss/sub mismatch, replayed jti, no refresh token issued, resource exact-match, TTL knob honored, audit/hook emission.

Terminology nits

• OAuth 2.1 is still a draft — frame the normative floor as RFC 6749 + 7523 + 7591 + 8037 with OAuth 2.1-compatible behavior.
• private_key_jwt is the token-endpoint auth method name; RFC 7523 defines the assertion parameters and processing behind it.

---

🤖 Merged review by Claude (Fable 5) + Codex (gpt-5.5), posted on Nathan's behalf