@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/n8n.md

@@ -0,0 +1,122 @@
+# Flair + n8n
+
+Use Flair as the memory backend for n8n's AI Agent. The same memories are readable from Claude Code, OpenClaw, and any other Flair client — that's the point.
+
+## When to use Flair vs n8n's built-in memory connectors
+
+n8n ships memory connectors for Postgres, MongoDB, and Redis. Those are real, persistent, and work fine for **conversation-buffer** use cases inside a single n8n instance.
+
+Flair is the right pick when you want:
+
+| | Flair | n8n built-ins |
+|---|---|---|
+| **Shape** | Tagged + typed memories with semantic search, plus chat-buffer compatibility | Conversation-buffer only (LangChain `BaseMessage` records) |
+| **Cross-orchestrator** | Same memory readable from Claude Code, OpenClaw, n8n | n8n-internal schema; nothing else reads it |
+| **Cross-instance** | Hub-spoke federation built-in (local ↔ Fabric, etc.) | Single-instance unless you self-build replication |
+| **Identity** | Ed25519 per-agent (planned) or admin-token (v1) | n8n credential per workflow |
+
+If your AI Agent only needs to remember the last N turns of a single chat in a single n8n instance, Postgres-as-memory is fine. If you want the same memory to inform a Claude Code conversation tomorrow, or to persist across n8n redeploys via federated Flair, this package is the path.
+
+## Setup (5 minutes)
+
+### 1. Install Flair (if not already running)
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+This starts a local Flair server on `http://localhost:19926`. For shared/team setups, see [Deployment](./deployment.md).
+
+### 2. Install the n8n community node
+
+In n8n: **Settings → Community Nodes → Install** → enter `@tpsdev-ai/n8n-nodes-flair` → confirm and restart.
+
+### 3. Create the credential
+
+In n8n: **Credentials → New → Flair API**. Fill in:
+
+| Field | Value |
+|---|---|
+| **Base URL** | `http://localhost:19926` (or your team's Flair URL) |
+| **Agent ID** | Logical identity that will own memories from this n8n workspace. Workflows that share an Agent ID share memory ownership. Use distinct IDs when isolation matters. |
+| **Admin Password** | Your Flair admin password (in `~/.flair/admin-pass` for local installs). **Sensitive** — see [Security](#security). |
+
+Click **Test** — if the test request to `/Memory` returns 200, the credential is good.
+
+### 4. Wire the nodes
+
+Three nodes ship in the package:
+
+- **Flair Chat Memory** — connects to an AI Agent's `Memory` socket. Stores chat history in Flair, scoped by Subject. Defaults to per-workflow memory; set the optional Session Sub-Key to `={{ $execution.id }}` for per-run isolation.
+- **Flair Search** — connects to an AI Agent's `Tool` socket. Two operations:
+  - *Semantic Search* — agent calls `flair_search({ query })`, gets memories ranked by similarity.
+  - *Get By Subject* — agent calls `flair_get_by_subject()`, gets memories under a config-time-bound subject.
+- **Flair Write** — a regular Main-input/Main-output pipeline node (not wired to the AI Agent's Tool socket). Takes an incoming item and writes its content as a Flair memory, with Subject, Tags, and Durability fields. For operator-driven capture-and-archive flows (mail → memory, webhook → memory, parsed-doc → memory) where the write is the workflow author's choice, not the LLM's.
+
+A typical workflow:
+
+```
+[Webhook] → [AI Agent]
+              ├─ Model: Claude / OpenAI / etc.
+              ├─ Memory: Flair Chat Memory (Subject: customer-support)
+              ├─ Tool: Flair Search (Operation: Semantic Search)
+              └─ Tool: HTTP Request (etc.)
+```
+
+The agent now answers using both its current chat history (from Flair Chat Memory) and any relevant historical memories it pulls in via Flair Search.
+
+## Subject and SessionId guidance
+
+n8n memory connectors expose a `sessionKey` parameter that scopes the chat history. Flair has a richer model:
+
+- **Subject** (required) — the entity / conversation / topic the memory is about. Indexed in Flair's schema; efficient to filter on. Default: `={{ $workflow.name }}`.
+- **Session Sub-Key** (optional) — appended to the subject as `<subject>:<sessionKey>`. Use the n8n execution id (`={{ $execution.id }}`) for per-run isolation, or a customer/user id for per-customer scoping, or leave blank to share across runs.
+
+Patterns:
+
+- **"This assistant remembers"** — set Subject to a stable string (`customer-support`, `daily-standup`). Leave Session Sub-Key blank. All runs share memory.
+- **Per-conversation isolation** — set Subject to the conversation owner (`customer:1234`), leave Session Sub-Key blank. Each conversation is isolated by subject.
+- **Per-execution isolation** — set Session Sub-Key to `={{ $execution.id }}`. Each n8n run gets its own memory window. (This is most similar to n8n's default `sessionKey={{ $execution.id }}`.)
+
+## Security
+
+> **The admin password gives every workflow with this credential read/write access to the entire Flair instance**, not just the configured Agent ID. The blast radius is the whole memory store. Treat the credential as highly sensitive: n8n encrypts credentials at rest, but any n8n admin or backup restore can extract it.
+
+For production deployments where untrusted workflow inputs reach Flair, wait for **Ed25519 per-agent authentication** (planned). v1 (admin password) is appropriate when:
+
+- The n8n instance is single-tenant and operator-controlled
+- Workflow inputs are trusted (your own CRM, your own webhook source)
+- Memory leakage between agents is acceptable for the use case
+
+If any of those don't hold, use Flair's CLI / SDK clients (which support per-agent Ed25519 today) and wait for the n8n credential update.
+
+## Get By Tag — coming soon
+
+The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter (tracked in the [n8n-node spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6). Workaround for now: use Semantic Search and let the model filter results by tags in the response.
+
+## Worked examples
+
+Two example workflows are coming in a follow-up release; they're authored inside a real n8n instance and round-tripped via Export so they import cleanly:
+
+- **`chat-memory-demo.json`** — Webhook → AI Agent (Claude + Flair Chat Memory) → Respond. Demonstrates the conversation-buffer use case. Run twice with the same input to see memory replay.
+- **`knowledge-search-demo.json`** — Schedule → AI Agent (Claude + Flair Chat Memory + Flair Search as Tool) → action. Demonstrates the structured-knowledge-search use case.
+
+In the interim, follow the [Setup](#setup-5-minutes) and [Subject and SessionId guidance](#subject-and-sessionid-guidance) sections — wiring is straightforward without an example file.
+
+## Compared to other Flair surfaces
+
+| Surface | Use case | Setup |
+|---|---|---|
+| [Claude Code](./claude-code.md) | Personal AI assistant memory across CLI sessions | npm install + `flair init` |
+| [OpenClaw](./openclaw.md) | Multi-agent OpenClaw deployments | OpenClaw plugin install |
+| [MCP](./mcp-clients.md) | Any MCP client (Claude Desktop, etc.) | MCP server registration |
+| **n8n (this doc)** | Workflow-engine AI Agents | n8n community-node install |
+
+Same Flair instance, same memories, different surfaces.
+
+## See also
+
+- [Spec — `@tpsdev-ai/n8n-nodes-flair`](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) — implementation plan, design decisions, anti-patterns
+- [Bridges](./bridges.md) — how Flair memories flow between hosts and instances
+- [Federation](./federation.md) — hub-and-spoke replication

package/docs/notes/adk-spike-findings-2026-05-05.md

@@ -0,0 +1,331 @@
+# Google ADK Spike — Plugin Contract Findings
+
+**Date:** 2026-05-05
+**Investigator:** Ember
+**Scope:** Verify plugin contract for a `flair-adk-py` adapter
+
+---
+
+## Q1: ADK Basics — Exists? Open-source? Python?
+
+**Yes.** Google ADK is a real, open-source, Python-first framework.
+
+| Field | Value |
+|---|---|
+| **Package** | `google-adk` on PyPI |
+| **Current version** | 1.32.0 (released 2026-04-30) |
+| **Repo** | https://github.com/google/adk-python |
+| **License** | Apache 2.0 |
+| **Docs** | https://google.github.io/adk-docs/ |
+| **Language** | Python (primary). Java, Go, and TypeScript ports exist at `google/adk-java`, `google/adk-go`, `waldzellai/adk-typescript` |
+| **Samples** | https://github.com/google/adk-samples |
+
+From `pyproject.toml`:
+```toml
+name = "google-adk"
+```
+
+---
+
+## Q2: Memory Contract — Abstract Class for Custom Backends
+
+ADK defines `BaseMemoryService(ABC)` in `google/adk/memory/base_memory_service.py`. This is the contract custom memory backends implement — equivalent to LangChain's `BaseChatMemory` or n8n's `BaseListChatMessageHistory`.
+
+### Interface signature
+
+```python
+class BaseMemoryService(ABC):
+    """Base class for memory services."""
+
+    # --- REQUIRED (abstract) methods ---
+
+    @abstractmethod
+    async def add_session_to_memory(self, session: Session) -> None:
+        """Ingest a full session's events into memory.
+        
+        Called periodically or on-demand to persist conversation history.
+        Session may be added multiple times during its lifetime.
+        """
+
+    @abstractmethod
+    async def search_memory(
+        self, *,
+        app_name: str,
+        user_id: str,
+        query: str,
+    ) -> SearchMemoryResponse:
+        """Semantic/text search over ingested memories for a user.
+        
+        Returns SearchMemoryResponse containing list[MemoryEntry].
+        """
+
+    # --- OPTIONAL (default: raise NotImplementedError) ---
+
+    async def add_events_to_memory(
+        self, *,
+        app_name: str,
+        user_id: str,
+        events: Sequence[Event],
+        session_id: str | None = None,
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Incremental delta: add a subset of events, not the full session.
+        
+        Implementations should treat `events` as incremental, not replacing
+        the full session. custom_metadata keys are service-specific.
+        """
+
+    async def add_memory(
+        self, *,
+        app_name: str,
+        user_id: str,
+        memories: Sequence[MemoryEntry],
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Direct write: add explicit MemoryEntry objects (not from events).
+        
+        For services that support writing memory facts directly.
+        """
+```
+
+### Key data types
+
+```python
+class MemoryEntry(BaseModel):
+    """Represent one memory entry."""
+    content: types.Content          # google.genai.types.Content (parts: text, inline_data, etc.)
+    custom_metadata: dict[str, Any] = Field(default_factory=dict)
+    id: Optional[str] = None
+    author: Optional[str] = None
+    timestamp: Optional[str] = None   # ISO 8601 preferred
+
+class SearchMemoryResponse(BaseModel):
+    memories: list[MemoryEntry] = Field(default_factory=list)
+
+class Session(BaseModel):
+    id: str
+    app_name: str
+    user_id: str
+    state: dict[str, Any]
+    events: list[Event]          # conversation events
+    last_update_time: float
+```
+
+### Scoping model
+
+All memory operations are scoped to `(app_name, user_id)`. There is no global memory. `session_id` is an optional partition within `add_events_to_memory`.
+
+### How memory is consumed by agents
+
+ADK ships two built-in memory tools:
+
+- **`LoadMemoryTool`** — reactive. The model decides when to call `load_memory(query)`, which calls `tool_context.search_memory(query)`. Only available when `FeatureName.JSON_SCHEMA_FOR_FUNC_DECL` is enabled.
+- **`PreloadMemoryTool`** — automatic. On every LLM request, searches memory using the user's query text and prepends a `<PAST_CONVERSATIONS>` system instruction block. No model decision needed.
+
+Both are `tools` added to an agent's `tool_executor`, not part of the `BaseMemoryService` interface.
+
+### Memory is wired through `InvocationContext`
+
+```python
+class InvocationContext(BaseModel):
+    # ...
+    memory_service: Optional[BaseMemoryService] = None
+    # ...
+```
+
+And agents access it via `Context` (the tool/tool call context):
+
+```python
+# In agent tools / callbacks:
+ctx = Context(...)  # = ToolContext
+await ctx.search_memory("what did user ask yesterday?")
+await ctx.add_session_to_memory()
+await ctx.add_events_to_memory(events=[...])
+await ctx.add_memory(memories=[MemoryEntry(...)])
+```
+
+---
+
+## Q3: Persistence Contract — "Memory" vs "Knowledge" / "Session"
+
+**Yes, ADK explicitly separates these concepts into two distinct abstractions:**
+
+### Session Service — `BaseSessionService`
+
+Location: `google/adk/sessions/base_session_service.py`
+
+Handles **conversation history** (ordered events within a session). Think "chat transcript".
+
+```python
+class BaseSessionService(abc.ABC):
+    @abc.abstractmethod
+    async def create_session(self, *, app_name, user_id, state=None, session_id=None) -> Session
+    @abc.abstractmethod
+    async def get_session(self, *, app_name, user_id, session_id, config=None) -> Optional[Session]
+    @abc.abstractmethod
+    async def list_sessions(self, *, app_name, user_id=None) -> ListSessionsResponse
+    @abc.abstractmethod
+    async def delete_session(self, *, app_name, user_id, session_id) -> None
+    
+    # non-abstract: append_event (adds events in-memory, updates session state)
+```
+
+Shipped implementations:
+- `InMemorySessionService` — volatile, for prototyping
+- `SqliteSessionService` — file-based SQLite
+- `DatabaseSessionService` — generic SQL (supports PostgreSQL, MySQL)
+- `VertexAiSessionService` — stores sessions in Vertex AI
+
+### Memory Service — `BaseMemoryService`
+
+Location: `google/adk/memory/base_memory_service.py`
+
+Handles **searchable, cross-session knowledge** derived from conversation events. Think "vector store / RAG".
+
+```python
+class BaseMemoryService(ABC):
+    @abstractmethod
+    async def add_session_to_memory(self, session: Session) -> None
+    @abstractmethod
+    async def search_memory(self, *, app_name, user_id, query) -> SearchMemoryResponse
+    # + optional add_events_to_memory, add_memory (see Q2)
+```
+
+Shipped implementations:
+- `InMemoryMemoryService` — keyword matching, prototyping only
+- `VertexAiMemoryBankService` — Google Cloud's managed Memory Bank (vector + LLM-summarized)
+- `VertexAiRagMemoryService` — Vertex AI RAG corpora
+
+### Retrieval tools — `BaseRetrievalTool`
+
+A third concern: **external knowledge retrieval** (files, RAG corpora, databases).
+
+Location: `google/adk/tools/retrieval/base_retrieval_tool.py`
+
+This is a `Tool` (callable by the agent model), not a service. Shipped implementations:
+- `FilesRetrieval` — local file-based retrieval
+- `LlamaIndexRetrieval` — LlamaIndex-backed retrieval
+- `VertexAiRagRetrieval` — Vertex AI RAG as a tool
+
+**Summary:** ADK has a clean 3-way split:
+1. **Sessions** = ordered conversation history (persist per-session)
+2. **Memory** = searchable, cross-session knowledge (persist per-user)
+3. **Retrieval** = external document/knowledge access (tool-based)
+
+---
+
+## Q4: Reference Implementations — Shipped & Community
+
+### Shipped with ADK (in `google.adk.memory`)
+
+| Implementation | Source | Description |
+|---|---|---|
+| `InMemoryMemoryService` | `google/adk/memory/in_memory_memory_service.py` | Keyword matching, thread-safe, dev/testing only |
+| `VertexAiMemoryBankService` | `google/adk/memory/vertex_ai_memory_bank_service.py` | Google Cloud Memory Bank — uses `memories.ingest_events` + `memories.generate` + `memories.retrieve`. Supports TTL, revision tracking, metadata consolidation |
+| `VertexAiRagMemoryService` | `google/adk/memory/vertex_ai_rag_memory_service.py` | Vertex AI RAG corpora — uploads session events as temp JSON files, retrieves via `rag.retrieval_query` |
+
+### Community packages
+
+| Package | Source | Description |
+|---|---|---|
+| `google-adk-redis` (0.0.4) | https://github.com/redis-developer/adk-redis | Redis integration — implements Memory, Sessions, and Search tools |
+| `google-adk-community` (0.4.1) | PyPI | Community extensions (specifics unknown without install) |
+
+### Shipped session backends (for reference)
+
+| Implementation | Source |
+|---|---|
+| `InMemorySessionService` | `google/adk/sessions/in_memory_session_service.py` |
+| `SqliteSessionService` | `google/adk/sessions/sqlite_session_session_service.py` |
+| `DatabaseSessionService` | `google/adk/sessions/database_session_service.py` |
+| `VertexAiSessionService` | `google/adk/sessions/vertex_ai_session_service.py` |
+
+---
+
+## Q5: Auth / Config Conventions
+
+### LLM configuration
+
+ADK uses the `google-genai` SDK client for model calls. Config conventions:
+
+```python
+# Standard Gemini (AI Studio API key):
+from google.adk.models.google_llm import Gemini
+model = Gemini(model="gemini-2.5-flash")
+# Needs: GOOGLE_API_KEY env var
+
+# Vertex AI (project + location):
+model = Gemini(model="gemini-2.5-flash")  # same constructor
+# Needs: GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION env vars
+# Or: google.auth default credentials (Application Default Credentials)
+```
+
+Key env vars:
+| Env var | Purpose |
+|---|---|
+| `GOOGLE_API_KEY` | AI Studio API key (Express Mode) |
+| `GOOGLE_GENAI_USE_VERTEXAI` | If `true`/`1`, routes to Vertex AI instead of AI Studio |
+| `GOOGLE_CLOUD_PROJECT` | GCP project ID for Vertex AI |
+| `GOOGLE_CLOUD_LOCATION` | GCP region for Vertex AI |
+| `APIGEE_PROXY_URL` | Apigee proxy URL (for `ApigeeLlm`) |
+
+### Memory service configuration
+
+Services take explicit constructor params — no env var convention for memory backends:
+
+```python
+# VertexAiMemoryBankService — requires agent engine ID
+from google.adk.memory import VertexAiMemoryBankService
+memory = VertexAiMemoryBankService(
+    project="my-project",
+    location="us-central1",
+    agent_engine_id="456",
+)
+
+# VertexAiRagMemoryService — requires RAG corpus
+from google.adk.memory import VertexAiRagMemoryService
+memory = VertexAiRagMemoryService(
+    rag_corpus="projects/.../ragCorpora/my-corpus",
+    similarity_top_k=5,
+)
+```
+
+### Server wiring
+
+In the ADK CLI web server (`adk web`), memory_service is injected at the server level:
+
+```python
+```python
+# WARNING: FastApiAdkRunner class name requires verification — not located in adk-python @ v1.32.0.
+# The adk-python main branch has `Runner` and `InMemoryRunner` in `google/adk/runners.py`,
+# and `adk_web_server.py` handles the HTTP entry point without a FastAPI-specific runner class.
+# The memory_service injection pattern (runner → InvocationContext → ctx) is correct,
+# but the specific class name may be internal, renamed, or from a different ADK version.
+# Verified against: https://github.com/google/adk-python (main branch, 2026-05-05)
+```
+
+The runner pattern injects `memory_service` into each `InvocationContext`, making it available to all agents via `ctx.search_memory()`, `ctx.add_session_to_memory()`, etc.
+
+### Session-scoped config
+
+There is **no per-session memory config**. Memory is configured at the app/server level (one `BaseMemoryService` instance per runner). The `(app_name, user_id)` tuple in each call acts as the scope.
+
+---
+
+## Adapter Design Notes for `flair-adk-py`
+
+Based on this investigation, a `flair-adk-py` adapter would:
+
+1. **Subclass `BaseMemoryService`** — implement `add_session_to_memory()` and `search_memory()`. Optionally implement `add_events_to_memory()` and `add_memory()`.
+
+2. **Handle `Event` → Flair event conversion** — ADK events use `google.genai.types.Content` (parts-based). Need to map `Content.parts[i].text` → Flair events.
+
+3. **Handle Flair event → `MemoryEntry` conversion** — for `search_memory()`, return `SearchMemoryResponse(memories=[MemoryEntry(content=..., author=..., timestamp=...)])`.
+
+4. **Inject via `InvocationContext`** — the adapter instance is passed as `memory_service=MyFlairMemoryService()` when constructing the runner.
+
+5. **Scope mapping** — ADK scopes to `(app_name, user_id)`. Map `app_name` → Flair space, `user_id` → Flair user/agent.
+
+6. **Session vs Memory** — ADK already handles session persistence separately via `BaseSessionService`. The adapter only needs to handle the memory/search side.
+
+No implementation was done — this is a research report.

package/docs/notes/mcp-agent-auth-consumer.md

@@ -0,0 +1,229 @@
+# Headless agent-auth to MCP — the Flair/consumer half
+
+> **Status:** complete against the published `@harperfast/oauth@2.2.0`, with
+> one explicitly-drawn boundary: the full over-network CIMD fetch + token
+> mint cannot be exercised end-to-end against a loopback Harper (the
+> plugin's unconditional SSRF gate forbids it — by design, see
+> [the SSRF/loopback boundary](#the-ssrfloopback-boundary) below). That last
+> hop is deferred to a follow-up e2e against a real public HTTPS host;
+> `bench.tps.harperfabric.com` is the planned venue.
+
+This is the Flair-side consumer for RFC 7523 `client_credentials` +
+`private_key_jwt` agent-auth: a headless Flair agent authenticating *as
+itself* — no browser, no human — to a Harper MCP `/mcp` endpoint, using its
+existing Ed25519 identity key. Plugin side:
+[HarperFast/oauth#159](https://github.com/HarperFast/oauth/issues/159)
+(parent issue, decomposed into 4 parts — all shipped, see below).
+
+## Upstream state (as of 2026-07-12)
+
+| # | What | State |
+|---|------|-------|
+| #160 / PR #165 | client-assertion primitives (strict EdDSA verify + `jti` replay store) | **SHIPPED** (merged @ `d48c3b2`) |
+| #161 / #167 | CIMD-first client resolution & validation for `private_key_jwt` agents (SSRF-guarded fetch, validation, cache) | **SHIPPED** in 2.2.0 via PR #170 |
+| #162 / PR #170 | token-endpoint grant — assertion + resolved client + RFC 8707 resource binding | **SHIPPED** in 2.2.0 |
+| #163 / PR #171 | token-issuance rate limiting (per verified client_id, post-auth debit) | **SHIPPED** in 2.2.0 |
+
+Every claim below about plugin behavior is read from the **published 2.2.0
+package source** (`node_modules/@harperfast/oauth/dist/lib/mcp/*.js`) and,
+where testable, proven against that real code — not mirrored, not guessed.
+(History note: a 2026-07-09 revision of this doc corrected an earlier false
+"#167 merged" claim; #167 has since genuinely shipped as part of 2.2.0.)
+
+## 1. Assertion signing + live token mint — `flair mcp token`
+
+`src/mcp-client-assertion.ts` builds + signs the `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
+the plugin's own approach and this repo's existing `flair-client.mjs` /
+`buildEd25519Auth` signing style). The claim shape is pinned to what PR #165
+(`src/lib/mcp/clientAssertion.ts`) verifies, and
+`test/unit/mcp-client-credentials-live-package.test.ts` proves assertions
+this module signs pass the plugin's **real** `verifyClientAssertion` —
+including negative cases (wrong signing key, tampered payload).
+
+Key loading (`resolveAgentKeyPath` / `loadEd25519PrivateKeyFromFile`) mirrors
+`src/cli.ts`'s existing `resolveKeyPath` / `buildEd25519Auth` (used by the
+TPS-Ed25519 REST-auth path) exactly: same search order (`--keys-dir` /
+`FLAIR_KEY_DIR` / `~/.flair/keys` / `~/.tps/secrets/flair`), same format
+cascade (raw 32-byte seed, base64 seed, base64 PKCS8 DER, PEM fallback). No
+new key material, no new on-disk format.
+
+### The live round-trip (formerly stubbed — now real)
+
+`requestMcpAccessToken` POSTs the `client_credentials` grant to the token
+endpoint (`/oauth/mcp/token`) and returns the minted token. Its error
+behavior is deliberate:
+
+- **429 `slow_down`** (the #171/#163 issuance rate limit): honors the
+  `Retry-After` header with **full jitter** (sleep a random duration in
+  `[0, Retry-After]`), retrying up to `maxRetries` (default 3 — an
+  assertion is only valid ≤ 60s, so unbounded retry would outlive it).
+  A missing `Retry-After` falls back to capped exponential backoff — never
+  hammer, even a non-conformant server.
+- **Any other non-2xx** throws `McpTokenRequestError` (status + OAuth error
+  code preserved) with **no retry** — those responses mean the request
+  itself is wrong, and retrying identically would just burn a fresh `jti`.
+
+`getMcpAccessToken` wraps it with the consumer-side requirements the 2.2.0
+rate limiter creates (pinned in flair#663's tracking thread): **mint
+sparingly** — tokens are cached per `(clientId, tokenEndpoint, resource)`
+and reused until within a refresh margin (default 30s) of expiry, because
+the limiter debits per *mint*, not per use. `forceRefresh` bypasses the
+cache (e.g. after an unexpected 401).
+
+CLI: `flair mcp token --agent-id <id>` now performs the real mint by
+default; `--dry-run` restores the old sign-and-print behavior.
+`--client-id`/`--token-endpoint`/`--resource` default to this instance's own
+oauth surface (derived from `FLAIR_MCP_ISSUER` / `FLAIR_PUBLIC_URL`,
+matching `resources/mcp-oauth-flag.ts`) but are fully overridable — an
+agent can authenticate to a **different** Harper MCP server; identity is
+portable.
+
+### RFC 8707 `resource`
+
+`buildTokenRequestForm` carries an optional `resource` field, pass-through
+only (it never invents a value). The CLI supplies the default:
+`${FLAIR_MCP_ISSUER}/mcp`, the same canonical resource identifier
+`resources/mcp-oauth-flag.ts`'s `mcpResource()` uses for this instance's own
+`/mcp` audience binding — exact-match, fail-closed on the AS side. The
+`resource` is part of the token-cache key: a token minted for one resource
+never serves another.
+
+## 2. CIMD publish — `resources/MCPClientMetadata.ts`
+
+Each agent's Client ID Metadata Document is **served**, not just generated:
+`GET /MCPClientMetadata/{agentId}` (public, unauthenticated — mirrors
+`AgentCard.ts`'s A2A-card posture). `client_id` = that URL itself (derived
+from `mcpIssuer()`, same env vars as above); `jwks` = the agent's existing
+`Agent.publicKey` re-expressed as a JWK OKP.
+
+Why served rather than exported for external hosting: Flair already
+publishes public agent-discovery metadata this way (`AgentCard.ts`), CIMD is
+explicitly the **stateless** registration path (no DCR row to replicate
+across Fabric nodes), and the agent's public key is already Flair's source
+of truth. Serving it keeps that single source of truth instead of
+introducing a second, externally-hosted copy that could drift.
+
+Field logic lives in `resources/mcp-client-metadata-fields.ts` (Harper-free,
+mirrors `agentcard-fields.ts`'s pattern), shape-pinned to oauth#161:
+
+- `grant_types: ["client_credentials"]`; `token_endpoint_auth_method:
+  "private_key_jwt"`.
+- `jwks` = a JWK Set containing exactly one PUBLIC OKP/Ed25519 key.
+  `buildCimdDocument` rejects non-OKP/non-Ed25519 keys, a missing/malformed
+  `x`, and any JWK carrying a private `d` component (defensive runtime
+  check; the TS type has no `d` field).
+- `redirect_uris` and `response_types` are BOTH omitted — neither exists on
+  the `CimdDocument` type, so neither can leak back in. This is the
+  conditional shape #161 specifies for client_credentials-only clients.
+
+This document is proven against the plugin's **real published pipeline**:
+`test/unit/mcp-client-credentials-live-package.test.ts` drives 2.2.0's
+actual `resolveCimdClient` (fetch → SSRF gate → validate → cache) via its
+exported `_setDnsLookup`/`_setFetch` test hooks and confirms the document
+resolves end-to-end, plus the fail-closed negatives: no
+`clientIdMetadataDocuments.allowedHosts` configured → rejected even though
+the fetch succeeded, and a document with leaked private-key material →
+rejected by the plugin's validator even if our own build-time guard were
+bypassed.
+
+## 3. Test evidence — three layers, strongest available at each boundary
+
+1. **Mirror unit tests** (`test/unit/mcp-client-assertion.test.ts`) — our
+   signer vs. a local mirror of #165's verification contract, all negative
+   cases; plus the full `requestMcpAccessToken`/`getMcpAccessToken` behavior
+   matrix (429 backoff with and without `Retry-After`, retry exhaustion,
+   non-JSON responses, cache reuse/expiry/`forceRefresh`/per-resource
+   isolation) against an injected fetch.
+2. **Live-package unit tests**
+   (`test/unit/mcp-client-credentials-live-package.test.ts`) — no mirrors:
+   the REAL published 2.2.0 `verifyClientAssertion`, `resolveCimdClient`,
+   and `createRateLimiter` composed in-process. Includes the
+   post-auth-debit ordering proof (#171/#163): a forged assertion never
+   reaches the rate limiter, so it cannot drain a real client's bucket; and
+   the exact-`Retry-After` handshake between the plugin's limiter and our
+   client backoff.
+3. **Live-Harper e2e**
+   (`test/integration/mcp-client-credentials-e2e.test.ts`) — an ephemeral
+   Harper (via `test/helpers/harper-lifecycle.ts`) running
+   `@harperfast/oauth@2.2.0` as a real mounted component. Proves, over real
+   HTTP: the AS discovery document advertises
+   `client_credentials`/`private_key_jwt`/`EdDSA`; our CIMD document is
+   served correctly; a real grant naming our agent reaches CIMD resolution
+   and is rejected **only** by the SSRF/DNS gate (distinguishable from both
+   shape errors and the allowlist gate, which is proven live and distinct);
+   and our client helper surfaces the rejection as a typed error.
+
+## The SSRF/loopback boundary
+
+Read this before trying to "finish" the e2e locally — the wall is real and
+it is the plugin working as designed, not a bug:
+
+`@harperfast/oauth@2.2.0`'s CIMD document fetch (`dist/lib/mcp/cimd.js`)
+enforces an **unconditional SSRF gate**: the `client_id` URL must be
+`https://` (no loopback carve-out — contrast `mcp.issuer`'s explicit
+loopback TLS exception, which has no analog here), and every DNS-resolved
+address is checked against the full IANA private/loopback/link-local ranges
+with **no override or allowlist knob**. A CIMD document served by a
+loopback/private-network Harper can therefore never be fetched by the AS
+over a real network hop. Consequences, all verified empirically while
+building this slice:
+
+- The plugin's `_setDnsLookup`/`_setFetch` injection hooks only help when
+  the test and the plugin run in the **same process**. A spawned Harper
+  (the `harper-lifecycle.ts` pattern) does not share the test's module
+  registry.
+- Harper's component loader gives each `package:`-declared component an
+  **isolated module graph even within the same process** — a same-process
+  JS resource that deep-imports `cimd.js` and arms the hooks on its own
+  import instance does not affect the module instance the plugin's
+  `/oauth/mcp/token` route uses (confirmed by direct experiment: the
+  harness's own `resolveClient` call succeeded against the mocked
+  transport; the live HTTP endpoint, hit immediately after, still failed
+  with the identical SSRF rejection).
+- Seeding the DCR client store is not a bypass either:
+  `MCPClientStore`'s `encodeRecord`/`decodeRecord`
+  (`dist/lib/mcp/clientStore.js`) persist no `jwks`/`_cimd` fields, so a
+  stored client can never satisfy `handleClientCredentialsGrant`'s
+  `client._cimd !== true` gate — confirmed by reading the published source.
+
+So the local e2e drives the live grant as far as it can physically go —
+into CIMD resolution, stopped only by the DNS gate — and the remaining
+behavior (the plugin's real fetch of our served document, followed by a
+200 token mint over the network) is covered in-process by the live-package
+tests instead. **The genuine end-to-end over-network mint is deferred** to
+an environment where this Flair instance's CIMD route is served from a
+real, publicly-resolvable HTTPS host. Planned follow-up: run exactly
+`test/integration/mcp-client-credentials-e2e.test.ts`'s happy path against
+`bench.tps.harperfabric.com` (our public bench host) with
+`clientIdMetadataDocuments.allowedHosts` pointed at it — at which point the
+SSRF-gate rejection assertion flips into a 200-mint assertion. Until that
+runs, "token mints over a real network hop" remains **inferred** from the
+in-process proof, not measured; everything else above is measured.
+
+## Deployment coordination note
+
+Whoever owns the AS-side `@harperfast/oauth` config for a given Harper
+instance MUST add this Flair instance's `MCPClientMetadata` host to
+`clientIdMetadataDocuments.allowedHosts`. That host is derived from
+`FLAIR_MCP_ISSUER` (or `FLAIR_PUBLIC_URL` as fallback) — the same env var
+`mcpIssuer()` in `resources/mcp-oauth-flag.ts` and `defaultMcpClientId()` in
+`src/mcp-client-assertion.ts` both read. If the allowlist isn't updated,
+`/mcp` client_credentials auth for this agent fails closed (by design; the
+e2e proves the "Unknown client" rejection live). This is an operational
+step, not a code change; flag it explicitly when coordinating a rollout.
+The AS must also be able to fetch that host over public HTTPS — see the
+SSRF boundary above.
+
+## What's NOT in this slice
+
+- The over-network CIMD fetch + 200 token mint e2e — deferred to the
+  public-host follow-up described above.
+- `flair agent register-mcp-client` — not needed for the CIMD path (#161
+  replaced the DCR-shaped registration gate with the AS-side host
+  allowlist); only worth revisiting if DCR back-compat ever matters.
+- Wiring the minted access token into an actual MCP client session
+  (`Authorization: Bearer` against `/mcp`) — the token is minted and
+  cached; consuming it is the natural next slice.