feat(mcp): agent-auth consumer — assertion signing + CIMD publish (flair#623-adjacent / #159 consumer)

[tps-flint]

Summary

Flair-side consumer for headless agent-auth to a Harper MCP /mcp endpoint (RFC 7523 client_credentials + private_key_jwt). Built against the actual plugin contracts read directly from HarperFast/oauth's merged PRs — not guessed. Two of the three pieces are fully built + tested; the third (the live token round-trip) is a deliberate, clearly-marked stub because its upstream contract isn't final yet.

Design docs: ~/ops/FLAIR-AGENT-AUTH-CONSUMER-SPEC.md, ~/ops/FLAIR-CLOUD-AGENT-BETA-ALIGNMENT.md. Full writeup: docs/notes/mcp-agent-auth-consumer.md (added in this PR).

What's built + tested

1. Assertion signing — flair mcp token (src/mcp-client-assertion.ts)

• Builds + signs the RFC 7523 client_assertion JWT: header {alg:"EdDSA", typ:"JWT"}, claims iss=sub=client_id, aud=token endpoint, exp-iat <= 60s (hard-capped, not just defaulted), iat, random jti. Signed with node:crypto alone — no new dependency, matching this repo's existing signing style (flair-client.mjs, src/cli.ts's buildEd25519Auth).
• Claim shape is pinned to what HarperFast/oauth PR Hash-based embedding fallback provides no semantic quality #165 (src/lib/mcp/clientAssertion.ts, merged @ d48c3b2) verifies — read directly from the PR diff. test/unit/mcp-client-assertion.test.ts includes a mirror of Hash-based embedding fallback provides no semantic quality #165's verification (alg pinning, iss/sub/aud exact match, exp/iat window, jti presence, Ed25519 signature check) and proves our assertions pass it, plus negative cases: tampered payload, wrong aud, wrong signing key, expired assertion.
• Key loading (resolveAgentKeyPath/loadEd25519PrivateKeyFromFile) mirrors src/cli.ts's existing resolveKeyPath/buildEd25519Auth exactly — same search order (--keys-dir/FLAIR_KEY_DIR/~/.flair/keys/~/.tps/secrets/flair), same format cascade (raw seed, base64 seed, base64 PKCS8 DER, PEM fallback). No new key material.
• CLI verified end-to-end with a throwaway test key (assertion signs, round-trips through the mirror verifier, error paths for missing key / missing issuer config both fail closed with clear messages).

2. CIMD publish — resources/MCPClientMetadata.ts

• Serves each agent's Client ID Metadata Document at GET /MCPClientMetadata/{agentId} (public, unauthenticated — mirrors AgentCard.ts's A2A-card posture). client_id = that URL itself; jwks = the agent's existing Agent.publicKey re-expressed as a JWK OKP.
• Chose to serve it (vs. external hosting) because Flair already publishes public agent metadata this way, CIMD is explicitly the stateless/Fabric-native registration path (no DCR row to replicate across nodes), and it keeps the agent's public key as the single source of truth.
• Field logic (resources/mcp-client-metadata-fields.ts) is Harper-free and tested against a mirror of HarperFast/oauth PR chore: upgrade Harper to 5.0.0-beta.6 #167's validateCimdDocument (src/lib/mcp/cimd.ts, merged @ f0da8a1).

What's stubbed — pending #162

requestMcpAccessToken always throws, clearly marked pending #162. The token-endpoint grant (grant_type=client_credentials) is tracked as HarperFast/oauth issue #162 — an open issue, not yet a PR, so its exact request/response contract isn't final. buildTokenRequestForm (pure, tested) shows the shape the design docs call for; wiring a live POST now would mean guessing and re-doing it once #162 lands, so the seam is left explicit instead.

Also not in this slice (deferred, see docs/notes): flair agent register-mcp-client (the admin-gated Credential-writing command from the consumer spec) — its shape depends on open questions below — and the end-to-end/negative-path tests against a real spawned Harper (needs the live grant to exist first).

Contract questions for #162 (read directly against #167's merged code, not guessed)

Our CIMD document intentionally targets the shape our agents actually need (grant_types: ["client_credentials"], token_endpoint_auth_method: "private_key_jwt"), which today's merged #167 validator does not yet accept:

1. clientValidator.ts's SUPPORTED_GRANT_TYPES is {authorization_code, refresh_token} — will client_credentials be added as part of docs: add custom ports note to README #162, or a separate follow-up?
2. cimd.ts hardcodes CIMD clients to token_endpoint_auth_method === 'none' (its own comment says private_key_jwt activates with Add test coverage for CLI commands #159) — same question.
3. redirect_uris is required + non-empty today (inherited from the DCR-shaped validator) — meaningless for a pure client_credentials agent that never does a redirect flow. We deliberately omitted it rather than invent a placeholder (which could get silently accepted onto an unintended surface if a future validator loosens without dropping this requirement) — will it become optional for private_key_jwt + client_credentials-only CIMD clients?

Fetching our document against today's deployed AS fails closed (400, missing/invalid field) rather than silently degrading to a weaker auth method — intentional interim behavior, not a bug.

Test plan

• bun test test/unit/mcp-client-assertion.test.ts test/unit/mcp-client-metadata-fields.test.ts — 35 new tests, all pass
• bun test test/unit — full suite, 1971 pass / 0 fail (no regressions)
• tsc -p tsconfig.cli.json --noEmit and tsc -p tsconfig.json --noEmit — clean (one pre-existing, unrelated error in auth-middleware.ts confirmed present on origin/main before this change)
• npm run build && npm run build:cli — production build succeeds, emits dist/mcp-client-assertion.js, dist/resources/MCPClientMetadata.js, dist/resources/mcp-client-metadata-fields.js
• Manual CLI verification: flair mcp token with a throwaway Ed25519 test key — signs, prints the assertion + claims, correctly derives --client-id/--token-endpoint/--resource defaults from FLAIR_MCP_ISSUER, and fails closed with clear errors when the key or issuer config is missing

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

[tps-flint]

Dependency fully published: @harperfast/oauth@2.2.0 is on npm (2026-07-12T00:07Z) and contains the complete #159 train — #170 (client_credentials + RFC7523 private_key_jwt, the shape this issue consumes) and #171 (issuance + CIMD rate limiting). Nothing upstream blocks this issue anymore.

Two consumer requirements the 2.2.0 rate limiter (#171) adds to this client, fold into the spec:

1. Token caching is mandatory — mint sparingly and reuse until expiry. Issuance is limited per verified client_id (mcp.clientCredentials.rateLimit, default 30/min); per-request minting would burn the bucket for no reason.
2. Handle 429 {"error":"slow_down"} on the token endpoint — honor Retry-After with jittered backoff, never hammer. (Post-auth debit means only holders of the private key can spend our identities' buckets — a forged-assertion flood cannot 429 our agents.)

🤖 Generated with Claude Code