@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/resources/rate-limit.js

@@ -0,0 +1,400 @@
+/**
+ * rate-limit.ts — throttling for the OAuth authorization-server surface and the
+ * OAuth-guarded `/mcp` surface.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `/OAuthToken` accepts three grant types on one unauthenticated endpoint;
+ * `/OAuthRegister` creates a durable row; `/OAuthAuthorize` mints authorization
+ * codes; `/mcp` runs tools for anyone holding a valid token. None of them were
+ * throttled. Authentication is not a rate limit: a *valid* token can hammer the
+ * tool surface just as effectively as an invalid one can hammer the token
+ * endpoint.
+ *
+ * ── PER-NODE, IN-MEMORY. Say it out loud. ───────────────────────────────────
+ * The counter is a process-local Map. Flair runs on Harper Fabric with more than
+ * one node behind a GTM, and components hot-reload. So, precisely:
+ *
+ *   - The EFFECTIVE ceiling is `limit x <number of nodes serving the origin>`,
+ *     not `limit`. A caller cannot choose their node, but repeated attempts do
+ *     spread across them.
+ *   - The counter RESETS on component reload/restart. Reload is operator-
+ *     initiated, so this is not something a caller can trigger — but a deploy
+ *     does clear every bucket.
+ *   - A fixed window admits up to `2 x limit` across a window boundary.
+ *
+ * The alternative — a Harper table-backed counter — is cluster-visible but is
+ * the wrong trade here, and not merely because of latency:
+ *
+ *   1. A flair table is REPLICATED. Every counted request would become a
+ *      durable write fanned out to every node. An attacker sending N requests
+ *      would generate N cluster-wide replicated writes. That is write
+ *      amplification on the exact hot path the limiter exists to protect — a
+ *      strictly worse DoS shape than the one being defended against.
+ *   2. Replication is eventually consistent, so the shared counter would not be
+ *      accurate for a burst anyway. It would buy correctness at the timescale of
+ *      replication lag, which is the timescale a burst has already finished in.
+ *
+ * And the security value does not hinge on the exact multiplier. This is a
+ * BRUTE-FORCE control, not a capacity control: what matters is that the number
+ * of guesses per unit time is bounded and small, against secrets with 256 bits
+ * of entropy (`randomBytes(32)` — resources/OAuth.ts). Whether the ceiling is
+ * 30/min or 60/min is immaterial to that; whether it is bounded at all is not.
+ *
+ * WHAT WOULD CHANGE THIS ANSWER: a guessable-secret space small enough that a
+ * small constant multiplier matters; a node count large enough that `limit x N`
+ * stops being meaningfully bounded; or Harper gaining a shared, NON-replicated
+ * cache primitive (a counter that is cluster-visible without becoming durable
+ * replicated storage), at which point the per-node argument stops being the
+ * honest one.
+ *
+ * WHAT THIS DOES NOT PROTECT AGAINST, stated plainly:
+ *   - A distributed botnet. Per-IP keying is defeated by enough distinct source
+ *     addresses; nothing here changes that.
+ *   - Aggregate cluster capacity. This is a per-node, per-key control.
+ *   - Anything at all if the operator sets `FLAIR_RATE_LIMIT=off`.
+ *
+ * ── The counter is consumed BEFORE any credential is looked at ──────────────
+ * `checkHttpRateLimit` runs at the top of auth-middleware, before the request
+ * body is parsed and before any grant, code, secret or token is evaluated. That
+ * is deliberate and it is a security property, not an implementation detail: if
+ * the limiter only counted FAILURES, then "did this attempt consume budget"
+ * would answer "was that credential valid" — an enumeration oracle strictly
+ * better than the 400 the endpoint already returns. Counting unconditionally
+ * means a 429 carries no information about the credential that accompanied it,
+ * and a valid credential and a garbage one are byte-identical once limited.
+ *
+ * For the same reason nothing here emits `RateLimit-Limit`/`RateLimit-Remaining`
+ * on a request that was ALLOWED. Those headers are conventional and harmless on
+ * an ordinary API; on a credential endpoint they hand a caller a free pacing
+ * oracle for staying just under the threshold. `Retry-After` on the 429 itself
+ * is the one hint we give, because a client that cannot back off correctly is a
+ * client that retries in a tight loop.
+ */
+// ─── Configuration ──────────────────────────────────────────────────────────
+/** One-shot log guard — a warning per request would be its own amplification. */
+const warnedOnce = new Set();
+function warnOnce(tag, message) {
+    if (warnedOnce.has(tag))
+        return;
+    warnedOnce.add(tag);
+    console.error(`[rate-limit] ${message}`);
+}
+/** Test-only: forget which one-shot warnings have fired. */
+export function __resetWarningsForTest() {
+    warnedOnce.clear();
+}
+/**
+ * Master switch. Enabled unless `FLAIR_RATE_LIMIT` is exactly `off`/`0`/`false`
+ * (case-insensitive). Deliberately opt-OUT: a limiter that has to be discovered
+ * and switched on is a limiter that is off on every instance that most needs it.
+ *
+ * An unrecognised value is treated as ENABLED and warned about, so a typo
+ * (`FLAIR_RATE_LIMIT=disabled`) cannot silently disable the control.
+ */
+export function rateLimitEnabled() {
+    const raw = (process.env.FLAIR_RATE_LIMIT ?? "").trim().toLowerCase();
+    if (raw === "")
+        return true;
+    if (raw === "off" || raw === "0" || raw === "false" || raw === "no") {
+        warnOnce("disabled", "DISABLED by FLAIR_RATE_LIMIT — the OAuth and /mcp surfaces are unthrottled.");
+        return false;
+    }
+    if (raw === "on" || raw === "1" || raw === "true" || raw === "yes")
+        return true;
+    warnOnce("bad-master", `FLAIR_RATE_LIMIT is set to an unrecognised value — keeping rate limiting ENABLED. ` +
+        `Use FLAIR_RATE_LIMIT=off to disable it.`);
+    return true;
+}
+/**
+ * Read a positive-integer limit from the environment, falling back to `dflt`.
+ *
+ * Zero and negatives are REJECTED rather than honoured. A limit of 0 would mean
+ * "reject everything", which is not a rate limit an operator arrives at by
+ * intent — it is what a shell that expanded an unset variable produces. Every
+ * rejection is warned about by NAME so a typo is visible rather than silently
+ * swapped for the default.
+ */
+export function envLimit(name, dflt) {
+    const raw = (process.env[name] ?? "").trim();
+    if (raw === "")
+        return dflt;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        warnOnce(`bad-limit:${name}`, `${name} is not a positive integer — using the default of ${dflt}.`);
+        return dflt;
+    }
+    return n;
+}
+/**
+ * Limits, and why each number.
+ *
+ * `/OAuthToken`, `/OAuthAuthorize`, `/OAuthRevoke` — 30 per minute per caller.
+ * A real authorization flow is a handful of requests per user per hour: one
+ * authorize, one code exchange, one refresh per access-token lifetime (1 hour,
+ * resources/OAuth.ts). 30/min leaves roughly two orders of magnitude of headroom
+ * over legitimate use while capping a guessing run at 1800/hour/node against a
+ * 256-bit space.
+ *
+ * `/OAuthRegister` — 5 per five minutes. Registration is a once-per-client
+ * event, and each one creates a durable, replicated row. This is the table-
+ * pollution ceiling. (Registration is additionally gated; see the DCR work.)
+ *
+ * `/mcp` — 120 per minute per verified token subject. An agent doing real work
+ * makes many tool calls in a burst; this is sized to be invisible to genuine use
+ * and to stop one token from monopolising the surface.
+ */
+export function policyFor(bucket) {
+    switch (bucket) {
+        case "register":
+            return { bucket: "register", limit: envLimit("FLAIR_OAUTH_REGISTER_RATE_LIMIT", 5), windowMs: 300_000 };
+        case "mcp":
+            return { bucket: "mcp", limit: envLimit("FLAIR_MCP_RATE_LIMIT", 120), windowMs: 60_000 };
+        case "oauth":
+        default:
+            return { bucket: "oauth", limit: envLimit("FLAIR_OAUTH_RATE_LIMIT", 30), windowMs: 60_000 };
+    }
+}
+/** Paths this module throttles, and which policy each uses. Nothing else is touched. */
+const PATH_POLICY = {
+    "/OAuthToken": "oauth",
+    "/OAuthAuthorize": "oauth",
+    "/OAuthRevoke": "oauth",
+    "/OAuthRegister": "register",
+};
+/**
+ * Which policy applies to a pathname, or null for "not throttled".
+ *
+ * Exact match only. A prefix test would pull in unrelated sibling routes, and
+ * the OAuth endpoints are addressed by their exact resource path.
+ */
+export function policyForPath(pathname) {
+    const kind = PATH_POLICY[pathname];
+    return kind ? policyFor(kind) : null;
+}
+/**
+ * Hard cap on tracked keys. Without one, a caller rotating source addresses
+ * turns the limiter itself into a memory-exhaustion primitive — the classic way
+ * a rate limiter becomes the DoS. 20 000 entries is far above any legitimate key
+ * count for a single instance and costs on the order of a megabyte.
+ *
+ * Eviction is LRU (see `consume`: a touched key is re-inserted at the back of
+ * the Map). That ordering matters and is the right way round: a caller hammering
+ * one key keeps it hot, so it is the LAST thing evicted and stays limited; the
+ * entries evicted under pressure are idle ones, which had unspent budget anyway.
+ *
+ * Named trade-off: at the cap, an evicted key gets a fresh budget. Bounded
+ * memory is worth more than a perfectly-retained counter, and a caller able to
+ * fill 20 000 distinct keys is already distributed across 20 000 sources, which
+ * per-key limiting was never the control for.
+ */
+export const MAX_TRACKED_KEYS = 20_000;
+const buckets = new Map();
+/** Test-only: drop all counters so cases don't inherit each other's state. */
+export function __resetBucketsForTest() {
+    buckets.clear();
+}
+/** Test-only: how many keys are currently tracked. */
+export function __trackedKeyCountForTest() {
+    return buckets.size;
+}
+/**
+ * Count one request against `key` and decide.
+ *
+ * ALWAYS consumes, including when the answer is "limited" — a caller that keeps
+ * hammering keeps the window pinned rather than trickling through at exactly the
+ * limit. Callers must invoke this before evaluating any credential; see the
+ * module header for why that is a security property.
+ */
+export function consume(key, policy, now = Date.now()) {
+    const existing = buckets.get(key);
+    let bucket;
+    if (!existing || now - existing.windowStart >= policy.windowMs) {
+        bucket = { windowStart: now, count: 1 };
+    }
+    else {
+        bucket = { windowStart: existing.windowStart, count: existing.count + 1 };
+    }
+    // delete-then-set moves the key to the back of the Map's insertion order,
+    // which is what makes the eviction below LRU rather than first-seen.
+    buckets.delete(key);
+    buckets.set(key, bucket);
+    if (buckets.size > MAX_TRACKED_KEYS)
+        evictOldest(now, policy.windowMs);
+    const elapsed = now - bucket.windowStart;
+    return {
+        limited: bucket.count > policy.limit,
+        limit: policy.limit,
+        retryAfterSec: Math.max(1, Math.ceil((policy.windowMs - elapsed) / 1000)),
+    };
+}
+/**
+ * Bring the Map back under the cap: drop expired windows first (they carry no
+ * information), then the least-recently-used entries.
+ *
+ * Not a periodic sweep. A timer in a Harper component outlives nothing useful
+ * and has to be torn down on reload; doing the work only when the cap is
+ * actually reached keeps the steady state at zero cost.
+ */
+function evictOldest(now, windowMs) {
+    for (const [k, b] of buckets) {
+        if (buckets.size <= MAX_TRACKED_KEYS)
+            break;
+        if (now - b.windowStart >= windowMs)
+            buckets.delete(k);
+    }
+    for (const k of buckets.keys()) {
+        if (buckets.size <= MAX_TRACKED_KEYS)
+            break;
+        buckets.delete(k);
+    }
+}
+// ─── Caller identity ────────────────────────────────────────────────────────
+/**
+ * How many proxy hops in front of this instance are trusted, or 0 for "none".
+ *
+ * `FLAIR_TRUSTED_PROXY` — unset/`0` means the socket peer address is the only
+ * thing used. A positive integer N means the instance genuinely sits behind N
+ * trusted reverse proxies that append to `X-Forwarded-For`.
+ *
+ * DEFAULT OFF, and that direction is the point: `X-Forwarded-For` is a request
+ * header, so an instance that trusts it without a proxy in front lets any caller
+ * mint a fresh bucket per request by rotating the header — a limiter that is
+ * bypassable by anyone who has read this file. Trusting it has to be a decision
+ * an operator makes about their own topology.
+ */
+export function trustedProxyHops() {
+    const raw = (process.env.FLAIR_TRUSTED_PROXY ?? "").trim().toLowerCase();
+    if (raw === "" || raw === "0" || raw === "off" || raw === "false" || raw === "no")
+        return 0;
+    if (raw === "on" || raw === "true" || raw === "yes")
+        return 1;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0) {
+        warnOnce("bad-proxy", `FLAIR_TRUSTED_PROXY is not a non-negative integer — treating it as 0 (no proxy trusted).`);
+        return 0;
+    }
+    return n;
+}
+/** Sentinel used when no caller address can be determined. See `callerKey`. */
+export const UNKNOWN_CALLER = "addr:unknown";
+/**
+ * The rate-limit key component identifying the caller.
+ *
+ * Sources, in order:
+ *  1. `X-Forwarded-For`, but ONLY when `FLAIR_TRUSTED_PROXY` is set, and then
+ *     the entry `hops` from the RIGHT — never the leftmost. Each proxy appends
+ *     the peer it saw, so the rightmost entries are the ones written by the
+ *     trusted hops; the leftmost is whatever the original caller chose to send
+ *     and is worth nothing. Taking the left entry is the classic way this
+ *     control is made bypassable.
+ *  2. Harper's `request.ip` — the socket peer address. On a Fabric UDS listener
+ *     Harper substitutes the real client address from the PROXY v1 header when
+ *     one is present (harper/dist/server/http.js).
+ *  3. `UNKNOWN_CALLER`, warned about once.
+ *
+ * Step 3 collapses every caller into ONE bucket, which is deliberately the
+ * fail-SAFE direction — over-restrictive, never unthrottled. It is also loud:
+ * silently not limiting would be an unrun check that looks like a pass, and an
+ * operator who never learns the limiter degraded cannot fix it.
+ */
+export function callerKey(request) {
+    const hops = trustedProxyHops();
+    if (hops > 0) {
+        const raw = request?.headers?.get?.("x-forwarded-for") ??
+            request?.headers?.asObject?.["x-forwarded-for"] ??
+            "";
+        if (typeof raw === "string" && raw.trim() !== "") {
+            const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+            // The trusted hops appended the last `hops` entries; the one the nearest
+            // trusted proxy observed as its own peer sits at length - hops.
+            const idx = parts.length - hops;
+            if (idx >= 0 && parts[idx])
+                return `xff:${parts[idx]}`;
+            // Fewer entries than trusted hops: the chain is shorter than configured, so
+            // no entry in it was written by a trusted hop. Fall through to the socket
+            // peer rather than trust a caller-supplied value.
+        }
+    }
+    const ip = request?.ip;
+    if (typeof ip === "string" && ip !== "")
+        return `addr:${ip}`;
+    warnOnce("no-addr", "no client address available on the request — every caller now shares ONE bucket per endpoint, " +
+        "which throttles more than intended. If this instance sits behind a reverse proxy that sets " +
+        "X-Forwarded-For, set FLAIR_TRUSTED_PROXY to the number of trusted hops.");
+    return UNKNOWN_CALLER;
+}
+// ─── Responses ──────────────────────────────────────────────────────────────
+/**
+ * The 429 body. Identical for every endpoint, every key and every grant type,
+ * and it echoes nothing back — no client_id, no address, no grant type, no
+ * remaining count. `slow_down` is a real OAuth error code (RFC 8628 s3.5) and
+ * means exactly this, so a spec-aware client already knows what to do with it.
+ */
+export const LIMITED_BODY = JSON.stringify({
+    error: "slow_down",
+    error_description: "too many requests",
+});
+export function limitedHeaders(decision) {
+    return {
+        "content-type": "application/json",
+        "retry-after": String(decision.retryAfterSec),
+        // Do not add RateLimit-Limit/Remaining here or on the success path; see the
+        // module header on why a pacing oracle is not wanted on a credential endpoint.
+        "cache-control": "no-store",
+    };
+}
+/** A 429 as a `Response` — for the default dispatch chain (auth-middleware). */
+export function limitedResponse(decision) {
+    return new Response(LIMITED_BODY, { status: 429, headers: limitedHeaders(decision) });
+}
+// ─── Entry points ───────────────────────────────────────────────────────────
+/**
+ * The auth-middleware hook. Returns a 429 `Response` to short-circuit with, or
+ * null to continue.
+ *
+ * Must be called before the public-path passthrough and before anything reads
+ * the body: the three OAuth endpoints this covers all sit on that passthrough,
+ * so a hook placed after it would never run for them.
+ */
+export function checkHttpRateLimit(request, pathname) {
+    if (!rateLimitEnabled())
+        return null;
+    const policy = policyForPath(pathname);
+    if (!policy)
+        return null;
+    const decision = consume(`${policy.bucket}|${callerKey(request)}`, policy);
+    return decision.limited ? limitedResponse(decision) : null;
+}
+/**
+ * The `/mcp` hook. Keyed on the RS256-verified token subject (and `client_id`
+ * when present), never on an address: `/mcp` is authenticated, so the strongest
+ * available identity is the one the authorization server signed. That also makes
+ * this limit survive a caller changing address, which per-IP keying does not.
+ *
+ * Returns a Harper listener result (`{ status, body, headers }`) to short-circuit
+ * with, or null to continue. Runs INSIDE `withMCPAuth`, so `request.mcp` is
+ * populated; an unverified request never reaches here because the guard fails
+ * closed ahead of it.
+ */
+export function checkMcpRateLimit(request) {
+    if (!rateLimitEnabled())
+        return null;
+    const policy = policyFor("mcp");
+    const sub = typeof request?.mcp?.sub === "string" ? request.mcp.sub : "";
+    const clientId = typeof request?.mcp?.client_id === "string" ? request.mcp.client_id : "";
+    // No verified subject should be impossible here (withMCPAuth fails closed), but
+    // if it ever were, fall back to the caller address rather than to no limit.
+    const identity = sub ? `sub:${sub}|cid:${clientId}` : callerKey(request);
+    const decision = consume(`${policy.bucket}|${identity}`, policy);
+    if (!decision.limited)
+        return null;
+    return {
+        status: 429,
+        headers: limitedHeaders(decision),
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32029, message: "too many requests" },
+        }),
+    };
+}

package/docs/auth.md

@@ -62,22 +62,72 @@ Flair includes a built-in OAuth 2.1 authorization server for client integrations
 
 ### Dynamic Client Registration
 
-Clients register automatically on first connection:
+**Registration is off by default.** `POST /OAuthRegister` answers `403
+access_denied`, and the discovery documents do not advertise a
+`registration_endpoint`. Nothing needs doing to be in this state — it is what a
+fresh install does, and it is what an internet-reachable instance should stay in
+unless there is a reason otherwise.
+
+`OAuthClient` rows are durable and replicated, and every one of them is a
+`client_id` that `/OAuthAuthorize` will subsequently honour, so an open
+registration endpoint on a public instance means anyone can fill that table.
+
+To turn registration on, set an initial access token (RFC 7591 §3.1):
+
+```sh
+FLAIR_OAUTH_DCR_TOKEN=$(openssl rand -base64 32)
+```
+
+That one variable is the whole interface. There is no separate "enable" switch,
+which is the point: enabling registration and supplying the credential that
+guards it are the same act, so "on, and open to the internet" is not a state you
+can reach by forgetting a setting — it does not exist in the configuration. A
+token outside 32–508 characters is refused and registration stays **off**, with
+a warning naming the variable; a weak shared secret on an unauthenticated public
+endpoint is nearer to open than to closed.
+
+Registration is also rate limited, and the limiter runs **in front of** this
+gate: refused attempts spend budget too, so a flood against a closed endpoint is
+answered `429`, not `403`. That is deliberate — the limiter is the cheaper check
+and the one bounding volume — but it means a client retrying hard against an
+instance that has not opted in sees `429` and should read it as "stop", not as a
+different answer to the same question. The budget is 5 per five minutes by
+default (`FLAIR_OAUTH_REGISTER_RATE_LIMIT`).
+
+Keep the token in the process environment. Do not put it in a component `.env`
+for `flair deploy` to ship — a deploy payload is stored in Harper's deployment
+record and replicated to every node. `flair deploy` refuses to generate one
+containing this key, and warns if your own file assigns it.
+
+Clients then present it in a request header:
 
 ```
 POST /OAuthRegister
 Content-Type: application/json
+X-Flair-Initial-Access-Token: <the token>
 
 {
   "client_name": "Claude Desktop",
-  "redirect_uris": ["http://localhost:3000/callback"],
+  "redirect_uris": ["https://claude.com/api/mcp/auth_callback"],
   "grant_types": ["authorization_code"],
   "response_types": ["code"],
   "token_endpoint_auth_method": "none"
 }
 ```
 
-Returns `client_id` and `client_secret` (if applicable).
+Returns `client_id`. A missing or wrong token answers `401 invalid_token`.
+
+**Why a header and not `Authorization: Bearer`,** which is what RFC 7591 §3.1
+specifies: Harper's own auth layer claims every `Authorization: Bearer …` header
+and validates it as a Harper operation token, so a Bearer-carrying request to
+`/OAuthRegister` is answered `401 {"error":"invalid token"}` before any Flair
+code runs. Measured, not assumed — no header returns 200, `Bearer <anything>`
+returns 401, a custom header returns 200.
+
+Registering clients ahead of time and leaving this off is the better shape where
+it is workable — the surface exists to serve one known client shape, and the
+`@harperfast/oauth` authorization server used by the `/mcp` surface takes CIMD
+rather than registration.
 
 ### Authorization Code Flow with PKCE
 
@@ -93,10 +143,77 @@ Standard OAuth 2.1 authorization code flow:
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/OAuthRegister` | POST | Dynamic client registration |
+| `/OAuthRegister` | POST | Dynamic client registration — off unless `FLAIR_OAUTH_DCR_TOKEN` is set |
 | `/OAuthAuthorize` | GET/POST | Authorization endpoint |
 | `/OAuthToken` | POST | Token endpoint |
-| `/.well-known/oauth-authorization-server` | GET | Server metadata |
+| `/.well-known/oauth-authorization-server` | GET | Authorization server metadata (RFC 8414) |
+| `/.well-known/oauth-protected-resource` | GET | Protected resource metadata (RFC 9728) |
+| `/OAuthMetadata` | GET | Alias of `/.well-known/oauth-authorization-server` |
+
+Both well-known documents are public — RFC 8414 §3 and RFC 9728 §3 require them
+to be retrievable without authentication — and are served with
+`Access-Control-Allow-Origin: *` so browser-based MCP clients can read them.
+
+The protected-resource document is also served at the RFC 9728 §3.1
+path-appended URL `/.well-known/oauth-protected-resource/mcp`, which is the form
+MCP clients construct from the resource identifier.
+
+### Rate limiting
+
+The OAuth endpoints and the OAuth-guarded `/mcp` surface are rate limited. This
+is on by default; nothing needs configuring for it to apply.
+
+| Surface | Default | Window | Keyed on |
+|---------|---------|--------|----------|
+| `/OAuthToken`, `/OAuthAuthorize`, `/OAuthRevoke` (one shared budget) | 30 | 60s | Caller address |
+| `/OAuthRegister` | 5 | 300s | Caller address |
+| `/mcp` | 120 | 60s | The verified token subject |
+
+A rejected request gets `429` with a `Retry-After`, and a body that echoes
+nothing back. The counter is consumed *before* any credential is examined, so a
+`429` says nothing about the credential that came with it — a valid
+authorization code and a garbage one get byte-identical responses once a bucket
+is spent. No `RateLimit-*` headers are emitted on requests that are allowed;
+publishing a live remaining-count on a credential endpoint is a pacing aid for
+exactly the caller you don't want to help.
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `FLAIR_RATE_LIMIT` | on | Set to `off` to disable rate limiting entirely. An unrecognised value leaves it **enabled**. |
+| `FLAIR_OAUTH_RATE_LIMIT` | `30` | Requests per 60s for the token/authorize/revoke budget. |
+| `FLAIR_OAUTH_REGISTER_RATE_LIMIT` | `5` | Registrations per 300s. |
+| `FLAIR_MCP_RATE_LIMIT` | `120` | `/mcp` calls per 60s per token subject. |
+| `FLAIR_TRUSTED_PROXY` | `0` | Number of trusted reverse-proxy hops in front of this instance. |
+
+A limit set to `0`, a negative number, or anything non-numeric is refused and the
+default is used, with a warning naming the variable — so a shell that expanded an
+unset variable cannot silently switch the control off.
+
+**`FLAIR_TRUSTED_PROXY` and NAT.** By default the key is the socket peer address
+and `X-Forwarded-For` is ignored completely, because that header is caller-supplied:
+an instance that honours it with no proxy in front can be bypassed by anyone
+willing to vary a header. Set `FLAIR_TRUSTED_PROXY` to the number of proxies that
+genuinely sit in front and append to `X-Forwarded-For`, and the key becomes the
+entry those hops wrote (counted from the right — never the leftmost entry, which
+the original caller controls). Keying on an address means a busy NAT shares one
+budget; the defaults leave roughly two orders of magnitude of headroom over real
+usage, and raising them is a one-variable change.
+
+**This limiter is per node.** The counter lives in the serving process. On a
+multi-node deployment the effective ceiling is the configured limit times the
+number of nodes, and the counters reset when a component reloads. That is a
+deliberate trade: a cluster-shared counter in a Harper table would make every
+counted request a durable replicated write on an authentication hot path, which
+is a worse denial-of-service shape than the one being defended against. The
+control here bounds how fast a caller can guess against 256-bit secrets, and a
+small constant multiplier does not change that. It does **not** defend against a
+distributed botnet, and it is not a capacity control.
+
+Every URL in every one of these documents derives from `FLAIR_PUBLIC_URL`,
+falling back to the loopback bind address. **Set `FLAIR_PUBLIC_URL` on any
+deployment reachable at something other than localhost** — otherwise the
+documents are well-formed and every URL in them points at the *client's* own
+localhost. See [deploying-on-fabric.md](deploying-on-fabric.md).
 
 ## XAA (Enterprise-Managed Authorization)
 

package/docs/deploying-on-fabric.md

@@ -78,8 +78,41 @@ export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
 flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
 ```
 
-Also set `FLAIR_PUBLIC_URL` to that URL in the component's environment — OAuth metadata
-and A2A discovery advertise it, or clients see a loopback address.
+### `FLAIR_PUBLIC_URL` — set for you, and how to override it
+
+OAuth metadata and A2A discovery advertise `FLAIR_PUBLIC_URL`; with it unset, every
+URL a client is handed points at loopback and no remote client can authorize.
+
+`flair deploy` ships it. The deploy already knows the URL — it is the target it
+verifies the served API against immediately afterwards — so it writes
+`FLAIR_PUBLIC_URL=<target>` into a `.env` in the component payload, and then checks
+`GET <target>/OAuthMetadata` really does advertise a non-loopback issuer. That check
+fails the deploy if it does not.
+
+To advertise something other than the deploy target — a CDN, a reverse proxy, a
+vanity domain — put your own `.env` in the package root:
+
+```
+FLAIR_PUBLIC_URL=https://flair.example.com
+```
+
+A value you set is never overwritten; the deploy prints the disagreement and keeps
+yours. Any other keys in that file are carried through untouched.
+
+Three things worth knowing about that file:
+
+- Harper reads a component's `.env` **only** because flair's `config.yaml` declares
+  its `loadEnv` plugin, above `jsResource`. Without that declaration the file is
+  present and inert.
+- A variable already set in the instance's **process environment** outranks the
+  file. Harper's `loadEnv` skips any key already present in `process.env` (and logs
+  an "Environment variable conflict" warning) unless `override` is declared, which
+  flair does not declare. So a value you set through Fabric's own environment
+  mechanism is what the instance uses, and a deploy cannot replace it.
+- The deploy payload is stored in Harper's deployment record and replicated to every
+  node, so anything in `.env` is persisted cluster-wide. flair puts no credential
+  there. `HDB_ADMIN_PASSWORD` in particular cannot work from a component `.env` at
+  all — Harper composes its own configuration before component env files load.
 
 ---
 

package/docs/deployment.md

@@ -180,7 +180,7 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 
 | Variable | What it does | When to set it |
 |----------|--------------|----------------|
-| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on (e.g. `https://flair.example.com`). Surfaced in the AdminInstance pane's Endpoints table and used by OAuth metadata + A2A discovery so external clients see a reachable URL. | **Always set on remote / Fabric / VPS deployments.** Local-only installs can leave it unset. |
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on (e.g. `https://flair.example.com`). Surfaced in the AdminInstance pane's Endpoints table and used by OAuth metadata + A2A discovery so external clients see a reachable URL. | **Always set on remote / VPS deployments** — unset means every URL a client is handed points at loopback. On Fabric, `flair deploy` sets it from the deploy target and verifies the result; see [deploying-on-fabric.md](deploying-on-fabric.md). Local-only installs can leave it unset. |
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth; rotate via the Harper ops API, not by changing this env var. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase used to derive the AES-256-GCM key that wraps federation private-key seeds at rest. Auto-generated to `~/.flair/keys/.passphrase` if unset. | Set explicitly for production federation deployments so the passphrase isn't auto-generated and lost on disk wipe. |
 | `HTTP_PORT` | Override the Harper HTTP port. Useful for sandboxes; production deployments should configure the port in `config.yaml` instead. | Rare. |

package/docs/embedding-in-a-harper-app.md

@@ -21,6 +21,7 @@ Embedding *adds* the in-process path; `rest: true` keeps serving MCP clients and
 **2. Import the facade and write a memory.**
 
 ```javascript
+import { server } from "harper";
 import { Flair } from "@tpsdev-ai/flair";
 
 const flair = new Flair(server);
@@ -61,6 +62,8 @@ console.log([...server.resources.keys()].sort());   // what Flair registered
 
 One handle per Harper instance. Resolves resources lazily on first use — no lookup at construction time.
 
+**The handle owns nothing.** It holds a reference to the Harper server the caller already owns and acquires no timers, connections, or file handles. There is no `close()` or `dispose()` method. If a future version acquires something releasable, that is a breaking change and will be versioned as one.
+
 ### `flair.as(agentId)`
 
 Returns an `AgentHandle` scoped to that agent. The `agentId` is runtime-validated: missing, empty, blank, or non-string throws `InProcessContextError`.
@@ -85,6 +88,8 @@ planner.agentId;  // "planner"
 
 Admin operations — unfiltered reads, cross-agent writes. Every call site is greppable via `git grep "flair.admin"`.
 
+**The handle is cached** — `flair.admin === flair.admin` is `true`. Access it once and reuse the reference, or access it inline; either is fine.
+
 | Method | Description |
 |---|---|
 | `flair.admin.registerAgent(id, opts?)` | Register an agent through the Agent resource (full Principal shape). |
@@ -301,7 +306,7 @@ The facade wraps a lower-level API that is still available for callers who need
 import { agentContext, adminContext, internalContext, collectionResource } from "@tpsdev-ai/flair/server";
 ```
 
-This is the same seam Flair's own MCP handler and internal tooling use. You should not need it for ordinary agent operations — the facade covers those. Use the primitives when you are building your own abstraction on top of Flair's resources.
+This is the same seam Flair's own MCP handler and internal tooling use. **You should not need it for ordinary agent operations** — the facade covers those. Reach for the primitives when you are building your own abstraction on top of Flair's resources, or when you need the context helpers (`agentContext`, `adminContext`, `internalContext`) to pass into a resource call directly.
 
 ### Resolving a resource
 

package/docs/hosted-on-fabric.md

@@ -53,7 +53,7 @@ On Fabric, configuration goes through the component's environment, not a local `
 
 | Variable | What it does | When to set it |
 |----------|--------------|----------------|
-| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on. Surfaced in OAuth metadata and A2A discovery. | **Always set** — or clients see a loopback address. |
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on. Surfaced in OAuth metadata and A2A discovery. | **`flair deploy` sets it** to the deploy target, in the component's `.env`. Set it yourself only to advertise a different host (CDN / proxy / vanity domain) — a value you set is never overwritten. |
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. | Set at install time. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase for federation key encryption. | Set for production federation deployments. |