@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/lib/launchd-management.js

@@ -0,0 +1,328 @@
+/**
+ * launchd-management.ts — "is this instance actually under launchd?", and
+ * "why did launchd refuse to run it?" (flair#1022).
+ *
+ * `flair upgrade` on macOS restarts through launchd and falls back to a plain
+ * detached spawn when a launchd operation fails. The fallback is the right
+ * behaviour — a running instance beats a down one — but it changes a load
+ * bearing property of the install that nothing was measuring: the process is no
+ * longer owned by a service manager, so it does not come back after a reboot.
+ * The reported incident ended in `verified: healthy, authenticated, running
+ * <new version>`, every word of which was true, while the instance had just
+ * been orphaned. **Healthy and managed are different claims** and only the
+ * first was being made.
+ *
+ * Two things live here, and the split matters:
+ *
+ *   1. `assessLaunchdManagement()` — an OBSERVATION taken after the fact.
+ *      Deliberately not a flag threaded down from whichever function did the
+ *      falling back: `flair upgrade` hands its restart to the NEWLY INSTALLED
+ *      CLI in a child process (flair#905), so no in-process bookkeeping
+ *      survives the boundary. Asking launchd directly, at verification time,
+ *      is the only form of this check that works on both the delegated and
+ *      the in-process path — and it also catches a detachment this run did
+ *      not cause.
+ *
+ *   2. `diagnoseLaunchdPlistPaths()` — a PRE-FLIGHT taken before the fact, and
+ *      the reason the incident took two minutes to produce no information.
+ *      **`launchctl load` and `launchctl start` both exit 0 for a job whose
+ *      program does not exist.** Measured on macOS 15, not assumed: loading a
+ *      plist whose ProgramArguments[0] points at a deleted path succeeds,
+ *      `start` succeeds, and the only evidence of the failure is a nonzero
+ *      `LastExitStatus` and a missing `PID` in `launchctl list <label>` after
+ *      the fact. So the CLI's launchd path cannot learn anything from
+ *      launchctl's exit codes; it waits the full startup budget for a port
+ *      that was never going to open, and then falls back.
+ *
+ *      A plist records absolute paths — the node binary (`process.execPath` at
+ *      `flair init` time), Harper's entrypoint under that same install's
+ *      `node_modules`, and the package working directory. Switch Node runtimes
+ *      with a version manager and every one of them can move. That is knowable
+ *      from a `readFileSync` and an `existsSync`, in microseconds, and it names
+ *      both the stale path and the fix.
+ *
+ * Never logs plist CONTENTS. The plist embeds HDB_ADMIN_PASSWORD; only
+ * extracted program/working-directory paths ever reach a message, and the
+ * extractor below reads exactly those keys rather than returning the document.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { unescapeXml } from "./xml-escape.js";
+/**
+ * Ceiling on the `launchctl list` spawn. A status query answers instantly when
+ * launchd is reachable; this only exists so an unreachable service manager
+ * cannot turn a post-upgrade summary line into a hang. Same reasoning as
+ * scheduler-platform's STATUS_CHECK_TIMEOUT_MS.
+ */
+export const LAUNCHCTL_QUERY_TIMEOUT_MS = 5_000;
+/**
+ * Extract ONLY the exec-related paths from a plist: ProgramArguments and
+ * WorkingDirectory.
+ *
+ * Regex rather than a plist parser for the same reason `readPlistRootPath`
+ * uses one — this reads documents `buildLaunchdPlist` wrote, the shape is
+ * fixed, and a parser would pull the whole `EnvironmentVariables` dict
+ * (including the admin password) into memory to answer a question about two
+ * keys. Values are XML-escaped on the way in, so they are unescaped on the way
+ * out; a path containing `&` is stored as `&amp;` and returned as `&`.
+ *
+ * Returns null when the file cannot be read at all. A readable plist with
+ * neither key returns an empty/null refs object, which callers treat as "no
+ * evidence" rather than "broken" — a hand-written plist that uses `Program`
+ * instead of `ProgramArguments` is not ours to judge.
+ */
+export function readPlistProgramRefs(plistPath, read = (p) => readFileSync(p, "utf-8")) {
+    let raw;
+    try {
+        raw = read(plistPath);
+    }
+    catch {
+        return null;
+    }
+    const programArguments = [];
+    const argsBlock = raw.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (argsBlock) {
+        for (const m of argsBlock[1].matchAll(/<string>([^<]*)<\/string>/g)) {
+            programArguments.push(unescapeXml(m[1]));
+        }
+    }
+    const wd = raw.match(/<key>WorkingDirectory<\/key>\s*<string>([^<]*)<\/string>/);
+    return { programArguments, workingDirectory: wd ? unescapeXml(wd[1]) : null };
+}
+/**
+ * Does this plist still point at things that exist?
+ *
+ * Only ABSOLUTE paths are checked. `ProgramArguments` for a Flair service is
+ * `[<node>, <harper entrypoint>, "run", "."]` — the trailing literals are
+ * arguments, not paths, and an install whose plist was hand-edited to use a
+ * relative program is resolved by launchd against WorkingDirectory in a way
+ * this check has no business second-guessing. A missing absolute path, by
+ * contrast, is not ambiguous: launchd cannot exec it, and will not say so.
+ *
+ * The remedy is `flair init` because init unconditionally rewrites the plist
+ * from `process.execPath` and the currently-resolved Harper entrypoint — it is
+ * what re-points a service at the Node the operator is actually using now —
+ * followed by a restart to bring the job up under the rewritten plist.
+ */
+export function diagnoseLaunchdPlistPaths(plistPath, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    const refs = readPlistProgramRefs(plistPath, deps.read);
+    if (!refs)
+        return null;
+    const remedy = ["flair init", "flair restart"];
+    const rewriteNote = "`flair init` rewrites the plist against the Node runtime in use now, and `flair restart` " +
+        "brings the job back up under it.";
+    for (const arg of refs.programArguments) {
+        if (!arg.startsWith("/"))
+            continue;
+        if (exists(arg))
+            continue;
+        return {
+            kind: "ProgramArguments",
+            stalePath: arg,
+            message: `the launchd plist at ${plistPath} runs ${arg}, which no longer exists. ` +
+                `launchd cannot exec a missing program and reports no error for it — ` +
+                `load and start both succeed and the service never comes up. ` +
+                `A plist commonly goes stale like this after switching Node runtimes, ` +
+                `which moves both the node binary and the globally installed package tree. ` +
+                rewriteNote,
+            remedy,
+        };
+    }
+    const wd = refs.workingDirectory;
+    if (wd && wd.startsWith("/") && !exists(wd)) {
+        return {
+            kind: "WorkingDirectory",
+            stalePath: wd,
+            message: `the launchd plist at ${plistPath} sets WorkingDirectory to ${wd}, which no longer exists. ` +
+                `launchd refuses to spawn a job whose working directory is missing, and reports no error for it — ` +
+                `load and start both succeed and the service never comes up. ` +
+                rewriteNote,
+            remedy,
+        };
+    }
+    return null;
+}
+/**
+ * Parse `launchctl list <label>` output.
+ *
+ * The output is a plist-ish dict of `"Key" = value;` lines. The two that
+ * matter: `"PID"` is present ONLY while the job is running, and
+ * `"LastExitStatus"` records how the last run ended. A job whose program is
+ * missing has no PID and a nonzero LastExitStatus — that combination is the
+ * signature of the failure this module exists to name.
+ */
+export function parseLaunchctlList(output) {
+    const pidMatch = output.match(/"PID"\s*=\s*(\d+)\s*;/);
+    const exitMatch = output.match(/"LastExitStatus"\s*=\s*(-?\d+)\s*;/);
+    return {
+        pid: pidMatch ? Number(pidMatch[1]) : null,
+        lastExitStatus: exitMatch ? Number(exitMatch[1]) : null,
+    };
+}
+export function readLaunchctlJobState(label, list) {
+    let res;
+    try {
+        res = list(label);
+    }
+    catch {
+        return { registered: false, pid: null, lastExitStatus: null };
+    }
+    if (res.code !== 0)
+        return { registered: false, pid: null, lastExitStatus: null };
+    const { pid, lastExitStatus } = parseLaunchctlList(res.stdout);
+    return { registered: true, pid, lastExitStatus };
+}
+/**
+ * Which PID to treat as "the process serving this instance".
+ *
+ * Harper's own `hdb.pid` is preferred — it is written by the serving process on
+ * every boot regardless of who spawned it, so it is the same number on the
+ * launchd path and on the direct-spawn fallback, which is what makes comparing
+ * it against launchd's reported PID a real comparison.
+ *
+ * The liveness check is the part that is easy to leave out and expensive to
+ * omit. A `hdb.pid` left behind by a process that is gone names a PID that
+ * matches nothing, and a mismatch is what this module reports as DETACHED — so
+ * a stale file would produce a loud, wrong warning on a perfectly healthy
+ * launchd install. A check that cries wolf on healthy installs is worse than no
+ * check at all, because it is the reason the real warning gets skipped. A dead
+ * PID is no evidence, so it is discarded and the port listener answers instead.
+ */
+export function pickInstancePid(input) {
+    const { pidFilePid, isAlive, listeningPids } = input;
+    if (pidFilePid !== null && isAlive(pidFilePid))
+        return pidFilePid;
+    return listeningPids.length > 0 ? listeningPids[0] : null;
+}
+/** True when the instance is running outside the service manager that is registered to own it. */
+export function isDetached(m) {
+    return m.state === "detached";
+}
+/**
+ * Is this instance under launchd right now?
+ *
+ * The evidence, in the order it is weighed:
+ *
+ *   - Not darwin, or no plist for this data dir ⇒ nothing claims to manage it,
+ *     and there is no degradation to report. `no-service` is deliberately NOT
+ *     an alarm: an instance that was never registered has not lost anything,
+ *     and warning about it on every run is how a real warning gets ignored.
+ *   - `launchctl list <label>` cannot find the label, although the plist is on
+ *     disk ⇒ **detached**. The service exists but is not loaded.
+ *   - launchd reports no PID for the label ⇒ **detached**. The registered job
+ *     is not running, so whatever is serving the port is not launchd's.
+ *     `LastExitStatus` is carried into the detail because it is the difference
+ *     between "never started" and "started and died".
+ *   - launchd reports a PID that is not the instance's PID ⇒ **detached**, and
+ *     this is the exact shape the incident produced: launchd holds a job that
+ *     is failing, while a directly-spawned process answers on the port.
+ *   - launchd reports a PID and we cannot read the instance's own ⇒ **managed**.
+ *     A live job under this instance's label is positive evidence; refusing to
+ *     believe it because `hdb.pid` was unreadable would warn on healthy
+ *     installs, which is its own defect.
+ *
+ * A parent-process check is NOT used, and that is worth stating because it is
+ * the obvious first idea: the direct-start fallback spawns `detached: true` and
+ * `unref()`s, so once the CLI exits its child is reparented to PID 1 — exactly
+ * like a launchd-managed job. Both paths look identical from the parent PID,
+ * so the parent PID cannot distinguish them.
+ */
+export function assessLaunchdManagement(input) {
+    const { platform, label, plistPath, instancePid, plistExists, list } = input;
+    if (platform !== "darwin") {
+        return { state: "not-applicable", detail: `${platform} does not use launchd` };
+    }
+    if (!plistExists(plistPath)) {
+        return { state: "no-service", detail: `no launchd service is registered for this instance (${plistPath})` };
+    }
+    const job = readLaunchctlJobState(label, list);
+    const diagnose = input.diagnose ?? ((p) => diagnoseLaunchdPlistPaths(p));
+    const detachedRemedy = () => {
+        const stale = diagnose(plistPath);
+        if (!stale) {
+            return {
+                remedy: ["flair restart"],
+                because: "",
+            };
+        }
+        return { remedy: stale.remedy, because: ` Cause: ${stale.message}` };
+    };
+    if (!job.registered) {
+        const { remedy, because } = detachedRemedy();
+        return {
+            state: "detached",
+            label,
+            detail: `the launchd service ${label} is registered on disk but not loaded, so launchd is not managing this instance.${because}`,
+            remedy,
+        };
+    }
+    if (job.pid === null) {
+        const { remedy, because } = detachedRemedy();
+        const exit = job.lastExitStatus === null
+            ? ""
+            : ` launchd's last run of it exited ${job.lastExitStatus}.`;
+        return {
+            state: "detached",
+            label,
+            detail: `the launchd job ${label} is loaded but not running, so whatever is serving this instance was not started by launchd.${exit}${because}`,
+            remedy,
+        };
+    }
+    if (instancePid !== null && instancePid !== job.pid) {
+        const { remedy, because } = detachedRemedy();
+        return {
+            state: "detached",
+            label,
+            detail: `this instance is served by process ${instancePid}, but launchd's job ${label} is process ${job.pid} — ` +
+                `the running instance is not the one launchd manages.${because}`,
+            remedy,
+        };
+    }
+    return { state: "managed", label, detail: `launchd job ${label} is running as process ${job.pid}` };
+}
+/**
+ * The lines to print for a degraded (detached) outcome.
+ *
+ * Kept here rather than at the two call sites so `flair restart` and `flair
+ * upgrade` cannot drift into saying different things about the same condition,
+ * and so the wording is assertable in a unit test without running either
+ * command. Deliberately says what is WRONG (not managed), what it COSTS (no
+ * restart after reboot), and what to DO — an operator who reads only the first
+ * line still knows they have to act.
+ */
+export function renderDetachedWarning(m, headline) {
+    const lines = [`⚠️  ${headline}`, `   ${m.detail}`];
+    lines.push("   This instance will NOT come back after a reboot until launchd manages it again.");
+    // One paste-able line, not one command per line: an operator copying a fix
+    // out of a warning copies a line, and a two-step fix pasted as one step is
+    // how half a remedy gets applied.
+    if (m.remedy?.length)
+        lines.push(`   Fix: ${m.remedy.join(" && ")}`);
+    return lines;
+}
+/**
+ * The final status line of a successful `flair upgrade`, given what the probe
+ * found AND what launchd is doing.
+ *
+ * This is the reported defect reduced to a function, on purpose. The bug was
+ * never in the probe — `healthy, authenticated, running <version>` was true —
+ * it was that those three facts were rendered as an unqualified ✅ while a
+ * fourth, unmeasured fact (the instance had been dropped out of its process
+ * manager) was the one that mattered. Deciding it here rather than inline in
+ * the command means the decision is testable without performing an upgrade,
+ * which on the darwin path nothing else can do: no CI lane runs it.
+ *
+ * The verified facts are still reported in the degraded case. The upgrade DID
+ * land, and hiding that would swap one misleading summary for another; what
+ * changes is the marker and the sentence around it.
+ */
+export function renderVerifiedSummary(version, m) {
+    const facts = `healthy, authenticated${version ? `, running ${version}` : ""}`;
+    if (!isDetached(m)) {
+        return { degraded: false, lines: [`✅ verified: ${facts}`] };
+    }
+    return {
+        degraded: true,
+        lines: renderDetachedWarning(m, `upgrade landed (${facts}) but the instance is NOT running under launchd.`),
+    };
+}

package/dist/lib/mcp-enable.js

@@ -559,6 +559,25 @@ export async function selfVerifyMcpMetadata(issuer, deps = {}) {
             detail: `${url} responded but the metadata shape is unexpected (issuer/registration_endpoint/token_endpoint) — got issuer=${JSON.stringify(body?.issuer)}`,
         };
     }
+    // flair#1000: this path is now served by flair ITSELF when FLAIR_MCP_OAUTH is
+    // off, so a 200 no longer proves the plugin answered. flair's own document
+    // (resources/oauth-discovery.ts) is identifiable by its token endpoint —
+    // `<issuer>/OAuthToken`, where the plugin's is `<issuer>/oauth/mcp/token`.
+    // Name the real cause here: before this existed the operator got a 404 whose
+    // message already asked the right question, and falling through to the CIMD
+    // branch would send them to a plugin knob that is not the problem.
+    if (body.token_endpoint === `${normalizedIssuer}/OAuthToken`) {
+        return {
+            ok: false,
+            issuer: body.issuer,
+            registrationEndpoint: body.registration_endpoint,
+            tokenEndpoint: body.token_endpoint,
+            detail: `${url} answered with flair's OWN OAuth 2.1 authorization server, not the MCP one ` +
+                `(token_endpoint=${body.token_endpoint}) — the /mcp surface is NOT enabled on that instance. ` +
+                `Is FLAIR_MCP_OAUTH actually set on the restarted instance, and is the '@harperfast/oauth' ` +
+                `component declared in its config.yaml?`,
+        };
+    }
     // flair#756: confirm CIMD is actually advertised (node_modules/@harperfast/
     // oauth/dist/lib/mcp/wellKnown.js:129-165's buildAuthorizationServerMetadata:
     // `client_id_metadata_document_supported` is set only when

package/dist/resources/AdminInstance.js

@@ -1,5 +1,6 @@
 import { Resource } from "harper";
-import { layout, htmlResponse } from "./admin-layout.js";
+import { layout, htmlResponse, esc } from "./admin-layout.js";
+import { mcpRouteState } from "./mcp-oauth.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -98,6 +99,23 @@ export class AdminInstance extends Resource {
         const ctx = this.getContext?.() ?? {};
         const request = ctx.request ?? ctx;
         const publicUrl = resolvePublicUrl(request);
+        // The MCP row (flair#1001). Every other row in the Endpoints table is a
+        // route this component always registers; `/mcp` is the one that may not be
+        // there — it is default-OFF, and even with FLAIR_MCP_OAUTH on it does not
+        // mount without an issuer. This page used to print the URL unconditionally,
+        // so a default install advertised an endpoint that 404s.
+        //
+        // The state comes from the router itself (mcp-oauth.ts records the outcome
+        // of its own mount decision) rather than from a second read of the flag
+        // here — a second read is a second source of truth, which is this bug one
+        // level up. The row is kept, not dropped: a missing row tells an operator
+        // nothing, while a named status and the variable that changes it is
+        // actionable and still teaches them the surface exists.
+        const mcp = mcpRouteState();
+        const mcpCell = mcp.mounted
+            ? `<code>${publicUrl}/mcp</code>`
+            : `<span class="badge badge-gray">${esc(mcp.status)}</span>` +
+                `<div style="margin-top:4px;color:#666;font-size:0.9em">${esc(mcp.reason)}</div>`;
         // Try to read instance public key
         let publicKey = "—";
         const keyDir = join(homedir(), ".flair", "keys");
@@ -139,7 +157,7 @@ export class AdminInstance extends Resource {
         <h3>Endpoints</h3>
         <table style="box-shadow:none">
           <tr><td>API</td><td><code>${publicUrl}/</code></td></tr>
-          <tr><td>MCP</td><td><code>${publicUrl}/mcp</code></td></tr>
+          <tr><td>MCP</td><td>${mcpCell}</td></tr>
           <tr><td>OAuth Discovery</td><td><code>${publicUrl}/OAuthMetadata</code></td></tr>
           <tr><td>OAuth Authorize</td><td><code>${publicUrl}/OAuthAuthorize</code></td></tr>
           <tr><td>OAuth Token</td><td><code>${publicUrl}/OAuthToken</code></td></tr>

package/dist/resources/Memory.js

@@ -243,8 +243,27 @@ async function runDedupGate(ctx, content) {
     return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
 }
 /** Build the final write response: always `written: true`, always includes
- *  `id`, and layers the dedup collision signal on top when present. Never a
- *  code path where a match suppresses these base fields. */
+ *  `id`, `visibility`, and layers the dedup collision signal on top when
+ *  present. Never a code path where a match suppresses these base fields.
+ *
+ *  ── Why `visibility` is in the write response (flair#991) ──────────────────
+ *  Visibility is the one field on a memory the caller most often does NOT
+ *  set and yet most needs to know: the durability-keyed default above stamps
+ *  `private` for a bare write and `shared` for a permanent/persistent one, so
+ *  "who can read this" is decided by a rule the writer never typed. Returning
+ *  it makes the landed value observable on EVERY write surface at once —
+ *  `flair memory add`'s printed JSON, the REST response, the native /mcp
+ *  `memory_store` result, and packages/flair-mcp's `effectiveVisibility` line
+ *  (which read this field all along and had nothing to read, so it always
+ *  rendered "(server default)").
+ *
+ *  Read from `content`, not from `base`: `content.visibility` is the value
+ *  that was actually persisted a few lines earlier, and assigning after the
+ *  `...base` spread means the persisted value wins over anything the storage
+ *  layer echoes back. Omitted (not `null`) when unset, which happens only on
+ *  the put()-over-an-existing-record path where a partial merge carried no
+ *  visibility — reporting `null` there would read as "no one but the owner",
+ *  the opposite of what an absent field means to `isPrivateVisibility()`. */
 function buildWriteResponse(content, result, dedupMatch) {
     const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
     const response = {
@@ -253,6 +272,9 @@ function buildWriteResponse(content, result, dedupMatch) {
         written: true,
         deduplicated: !!dedupMatch,
     };
+    if (content.visibility !== undefined && content.visibility !== null) {
+        response.visibility = content.visibility;
+    }
     if (dedupMatch) {
         response.matchedId = dedupMatch.matchedId;
         response.matchConfidence = { cosine: dedupMatch.cosine, lexical: dedupMatch.lexical };

package/dist/resources/OAuth.js

@@ -2,11 +2,13 @@ import { Resource, databases } from "harper";
 import { createHash, randomBytes } from "node:crypto";
 import { handleJwtBearerGrant } from "./XAA.js";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { decideRegistration } from "./dcr-gate.js";
+import { buildAuthorizationServerMetadata } from "./oauth-discovery.js";
 /**
  * OAuth 2.1 Authorization Server for Flair.
  *
  * Endpoints (all mapped via Harper's resource routing):
- *   GET  /OAuthMetadata           → /.well-known/oauth-authorization-server
+ *   GET  /OAuthMetadata           → alias of /.well-known/oauth-authorization-server
  *   POST /OAuthRegister           → /oauth/register (DCR)
  *   GET  /OAuthAuthorize          → /oauth/authorize (consent screen)
  *   POST /OAuthToken              → /oauth/token (token exchange)
@@ -57,6 +59,19 @@ function redirectTo(url, status = 302) {
     return new Response(null, { status, headers: { Location: url } });
 }
 // ─── Discovery metadata ──────────────────────────────────────────────────────
+/**
+ * `/OAuthMetadata` — an ALIAS of `/.well-known/oauth-authorization-server`
+ * (flair#1000), not a second implementation.
+ *
+ * The document body moved verbatim to `buildAuthorizationServerMetadata()` in
+ * resources/oauth-discovery.ts and BOTH paths now call it. The well-known path
+ * is the one RFC 8414 defines and the one every client probes; this path is
+ * kept because it is what shipped, is referenced by docs/auth.md and by
+ * deployed callers, and costs one delegating line. Keeping it as an alias
+ * rather than as an independent handler is the whole point: two endpoints that
+ * can drift apart is the failure mode, and after this change there is no code
+ * path that can produce one document without producing the other.
+ */
 export class OAuthMetadata extends Resource {
     // OAuth discovery metadata is intentionally public — RFC 8414 § 3 requires
     // it be accessible without authentication so clients can bootstrap their
@@ -65,30 +80,7 @@ export class OAuthMetadata extends Resource {
     // of a 401 from Harper's intrinsic auth layer. Same pattern as Health (#386).
     allowRead() { return true; }
     async get() {
-        const baseUrl = process.env.FLAIR_PUBLIC_URL || `http://127.0.0.1:${process.env.HTTP_PORT || 19926}`;
-        return {
-            issuer: baseUrl,
-            authorization_endpoint: `${baseUrl}/OAuthAuthorize`,
-            token_endpoint: `${baseUrl}/OAuthToken`,
-            registration_endpoint: `${baseUrl}/OAuthRegister`,
-            revocation_endpoint: `${baseUrl}/OAuthRevoke`,
-            response_types_supported: ["code"],
-            grant_types_supported: [
-                "authorization_code",
-                "refresh_token",
-                "urn:ietf:params:oauth:grant-type:jwt-bearer",
-            ],
-            token_endpoint_auth_methods_supported: ["none", "client_secret_basic"],
-            code_challenge_methods_supported: ["S256"],
-            scopes_supported: [
-                "memory:read", "memory:write", "memory:admin",
-                "principal:read", "principal:admin",
-                "connector:read", "connector:admin",
-            ],
-            extensions_supported: [
-                "io.modelcontextprotocol/enterprise-managed-authorization",
-            ],
-        };
+        return buildAuthorizationServerMetadata();
     }
 }
 // ─── Dynamic Client Registration (RFC 7591) ──────────────────────────────────
@@ -96,8 +88,32 @@ export class OAuthRegister extends Resource {
     // Dynamic Client Registration (RFC 7591) — clients must be able to register
     // anonymously to bootstrap. Validation (redirect_uri allow-list, etc.)
     // happens in post(). Pattern matches FederationPair.allowCreate (#299).
+    //
+    // This stays `true` — it is Harper's ROLE gate, and returning false here would
+    // answer with Harper's own 403 body instead of an RFC 7591-shaped error. WHO
+    // may register is decided in post() via resources/dcr-gate.ts, in one place.
+    // Deliberately not enforced in both: one condition in two places is how the
+    // two drift apart.
     allowCreate() { return true; }
     async post(data) {
+        // Registration gate FIRST — before the redirect-URI policy is applied,
+        // before anything is read off the body, and before any write. A caller who
+        // may not register learns only that; running the redirect-URI check first
+        // would turn a closed endpoint into a probe for what this server accepts.
+        const decision = decideRegistration(this.getContext?.()?.request ?? this.getContext?.());
+        if (!decision.allowed) {
+            if (decision.reason === "disabled") {
+                return new Response(JSON.stringify({
+                    error: "access_denied",
+                    error_description: "dynamic client registration is not enabled on this server " +
+                        "(set FLAIR_OAUTH_DCR_TOKEN to enable it)",
+                }), { status: 403, headers: { "content-type": "application/json" } });
+            }
+            return new Response(JSON.stringify({
+                error: "invalid_token",
+                error_description: "a valid initial access token is required to register a client",
+            }), { status: 401, headers: { "content-type": "application/json" } });
+        }
         const redirectUris = data?.redirect_uris ?? [];
         const clientName = data?.client_name ?? "Unknown Client";
         // 1.0: only claude.com redirect URI permitted

package/dist/resources/auth-middleware.js

@@ -5,6 +5,7 @@ import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 import { isForbiddenOwnerMutation, resolveGuardedRecord } from "./record-owner-guard.js";
+import { checkHttpRateLimit } from "./rate-limit.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -65,6 +66,26 @@ async function backfillEmbedding(memoryId) {
 // ─── HTTP middleware ──────────────────────────────────────────────────────────
 server.http(async (request, nextLayer) => {
     const url = new URL(request.url, "http://" + (request.headers.get("host") || "localhost"));
+    // ── Rate limiting, FIRST ───────────────────────────────────────────────────
+    // Before the public-path passthrough below (the OAuth endpoints all sit on it,
+    // so a hook placed after it would never run for them), and before anything
+    // reads a credential.
+    //
+    // Ordering is a security property, not tidiness. The counter is consumed for
+    // every request to a throttled endpoint whether or not the credential that
+    // came with it was any good — if only failures were counted, "did this consume
+    // budget" would answer "was that credential valid", which is a cleaner
+    // enumeration oracle than the 400 the endpoint already returns. Because the
+    // decision is made here, a limited request carries no information about what
+    // it was carrying: a valid authorization code and a garbage one get the same
+    // 429 and the same body.
+    //
+    // Only the OAuth endpoints named in rate-limit.ts's PATH_POLICY are affected.
+    // Every other path — /Memory, /Presence, /FederationSync, everything agents
+    // actually use — returns null here and is untouched.
+    const limited = checkHttpRateLimit(request, url.pathname);
+    if (limited)
+        return limited;
     // A2A discovery endpoints: GET returns public agent-card metadata (per
     // A2A spec, cards are intentionally public). POST invokes JSON-RPC
     // actions (message/send writes OrgEvents on behalf of agents,
@@ -91,6 +112,11 @@ server.http(async (request, nextLayer) => {
         url.pathname === "/OAuthAuthorize" ||
         url.pathname === "/OAuthToken" ||
         url.pathname === "/OAuthRevoke" ||
+        // Belt-and-braces since flair#1000: `/.well-known/oauth-authorization-server`
+        // is served from its OWN urlPath mount (resources/oauth-wellknown.ts), which
+        // gets its own dispatch chain — this middleware never sees a request for it.
+        // The entry stays so the path is still public if that mount ever moves back
+        // onto the default chain.
         url.pathname === "/.well-known/oauth-authorization-server" ||
         url.pathname === "/OAuthMetadata" ||
         // Presence roster is public-safe (field-allowlisted); GET serves the