@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/resources/AdminMemory.js

@@ -21,7 +21,7 @@ import { allowAdmin } from "./agent-auth.js";
  * makes that legible: every memory shows where it came from, what it derived
  * from, what it superseded, and which peer it synced from.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts — this
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts — this
  * page surfaces full memory content across ALL agents, so the gap it closes
  * matters more here than on the other Admin* pages.
  */
@@ -31,7 +31,7 @@ export class AdminMemory extends Resource {
     }
     async get() {
         // Harper v5 does not populate this.request on Resource subclasses —
-        // getContext() is the only reliable path (ops-sal4: the previous
+        // getContext() is the only reliable path (the previous
         // `(this as any).request` read was always undefined, so query params
         // (?id=, ?q=, ?subject=, ?limit=) were always ignored).
         const ctx = this.getContext?.();

package/dist/resources/AdminPrincipals.js

@@ -4,7 +4,7 @@ import { allowAdmin } from "./agent-auth.js";
 /**
  * GET /AdminPrincipals — list all principals with kind, trust, status.
  *
- * allowRead()=allowAdmin (ops-oox7 defense-in-depth): see Admin.ts.
+ * allowRead()=allowAdmin (defense-in-depth): see Admin.ts.
  */
 export class AdminPrincipals extends Resource {
     async allowRead() {

package/dist/resources/Agent.js

@@ -1,5 +1,6 @@
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth, allowVerified, allowAdmin } from "./agent-auth.js";
+import { localInstanceId } from "./instance-identity.js";
 /**
  * Agent resource — serves as the Principal table in 1.0.
  *
@@ -40,6 +41,14 @@ export class Agent extends databases.flair.Agent {
         }
         content.createdAt = now;
         content.updatedAt = now;
+        // Write-time originatorInstanceId stamp (federation-edge-hardening slice
+        // 1) — see resources/Memory.ts's stampOriginatorInstanceId doc for the
+        // full contract. No-op if already set (never fires for a genuine local
+        // write; a federation-synced record never reaches this method — the
+        // merge path writes via the raw table object, bypassing this class).
+        if (content.originatorInstanceId == null) {
+            content.originatorInstanceId = await localInstanceId();
+        }
         return super.post(content, context);
     }
     async put(content) {
@@ -64,6 +73,11 @@ export class Agent extends databases.flair.Agent {
         // Protect immutable fields
         delete content.createdAt;
         delete content.publicKey; // key rotation goes through dedicated endpoint
+        // Write-time originatorInstanceId stamp — see post() above / Memory.ts's
+        // stampOriginatorInstanceId doc. No-op if already set.
+        if (content.originatorInstanceId == null) {
+            content.originatorInstanceId = await localInstanceId();
+        }
         return super.put(content);
     }
 }

package/dist/resources/AgentCard.js

@@ -29,7 +29,7 @@ export class AgentCard extends Resource {
         return {
             name: String(agent.name ?? agent.id ?? agentId),
             // Only an explicit kind="description" soul publishes — no private-soul
-            // fallback (ops-vz6j). See agentcard-fields.ts for the security rationale.
+            // fallback. See agentcard-fields.ts for the security rationale.
             description: selectPublicDescription(souls),
             url: String(agent.url ?? ""),
             version: String(agent.version ?? "1.0.0"),

package/dist/resources/AgentSeed.js

@@ -40,7 +40,7 @@ export class AgentSeed extends Resource {
     }
     async post(data) {
         // Harper v5 does not populate this.request on Resource subclasses —
-        // getContext() is the only reliable path (ops-sal4: the previous
+        // getContext() is the only reliable path (the previous
         // `(this as any).request` read was always undefined, so actorId was always
         // undefined and this belt-and-suspenders check fail-closed every request,
         // even from a real admin already verified by allowCreate()).

package/dist/resources/AttentionQuery.js

@@ -0,0 +1,356 @@
+/**
+ * AttentionQuery.ts — entity-scoped attention query (flair#677).
+ *
+ * POST /AttentionQuery — "what touches entity E in the last N days?", grouped
+ * by source across the five surfaces the attention plane spans: Memory,
+ * Relationship, WorkspaceState, Presence, OrgEvent. Spec:
+ * FLAIR-ATTENTION-PLANE.md ("Phase 1 — the query" + the K&S verdict's
+ * refinements). Builds on the entity vocabulary + `entities[]` fields shipped
+ * in flair#675/#676 (resources/entity-vocab.ts, schemas/*.graphql).
+ *
+ * Deliberately NOT built here (separate follow-up, FLAIR-ATTENTION-PLANE.md
+ * Phase 2): collision surfacing (joining a CALLER's own current task/
+ * WorkspaceState against teammates' for overlap), semantic/embedding
+ * matching, or a Relationship write path. This is read-only, exact-match,
+ * index-pushdown across the five sources — nothing more.
+ *
+ * ─── Per-source read-scoping (binding, per the K&S verdict) ──────────────────
+ *
+ * - Memory: through resolveReadScope() (resources/memory-read-scope.ts) — the
+ *   SAME centralized open-within-org-minus-private rule Memory.search()/
+ *   SemanticSearch.ts/MemoryBootstrap.ts use. No new scoping logic.
+ * - Relationship: mirrors Relationship.ts's OWN search() scoping (own agentId
+ *   for non-admin, unfiltered for admin/internal) — the entity condition is
+ *   ANDed with that same rule, never replacing it. Relationship carries no
+ *   visibility field yet (unlike Memory's open-within-org reframe), so the
+ *   conservative, least-surprising choice is "the same rows a direct
+ *   `POST /Relationship` search from this caller would already return."
+ * - WorkspaceState: Sherlock's Option 1 (K&S verdict, binding). WorkspaceState
+ *   is normally strictly per-agent-scoped (403 cross-agent via the exported
+ *   `WorkspaceState` resource class — see resources/WorkspaceState.ts). This
+ *   query needs teammates' WorkspaceState, so it reads the RAW generated table
+ *   object directly (`(databases as any).flair.WorkspaceState`), the same
+ *   "internal path" idiom already used elsewhere in this codebase (e.g.
+ *   OrgEvent.post()/put() call `(databases as any).flair.OrgEvent.put(...)`
+ *   directly rather than through the exported subclass) — NEVER through the
+ *   exported `WorkspaceState` class, which would just re-apply the per-agent
+ *   403 for the caller's own identity. This does NOT broaden WorkspaceState's
+ *   general read model (a plain `GET /WorkspaceState` from a non-admin agent
+ *   still 403s cross-agent, unchanged) — it is a narrow, server-computed join
+ *   scoped to one caller-supplied, validated entity string + a bounded day
+ *   window, returning only rows that matched. The exposed field set mirrors
+ *   exactly what FLAIR-ATTENTION-PLANE.md's Phase 2 write-up already names as
+ *   the intended surfaced shape (`summary`, `taskId`, `filesChanged`,
+ *   `entities`) plus bare identifiers (`id`, `agentId`, `ref`, `phase`,
+ *   `timestamp`) — never `metadata` (an undocumented free-form JSON blob with
+ *   no spec-blessed exposure here).
+ * - Presence: via the exported `Presence` resource's get() (preserves its
+ *   verified-agent currentTask content gate, #592) — never the raw table.
+ *   Presence.get()'s gate keys off a fresh TPS-Ed25519 SIGNATURE
+ *   (verifyAgentRequest), not an annotation, specifically to close the
+ *   authorizeLocal-forged-identity vector (flair#610) — so this resource
+ *   cannot just re-run resolveAgentAuth's verdict through it. Instead it
+ *   pre-seeds verifyAgentRequest's OWN per-request memoization cache
+ *   (`request._flairAgentAuth` — see resources/agent-auth.ts's
+ *   verifyAgentRequest doc: "memoized... including null... we verify once and
+ *   cache the result on the request") with the verdict THIS request already
+ *   established via resolveAgentAuth. This is not a forgery: by the time this
+ *   helper runs, `auth.kind` is already constrained to "agent" (a real
+ *   Ed25519 signature verified upstream by auth-middleware.ts/agent-auth.ts)
+ *   or "internal" (a trusted in-process call, unauthenticated-HTTP calls
+ *   never reach this point — see the top-level anonymous gate below) — it
+ *   relays an already-established fact instead of re-running a doomed second
+ *   signature check (the original request's nonce was already consumed by
+ *   auth-middleware.ts, so re-verifying the SAME raw request would collide
+ *   with the shared nonce store and spuriously read as a replay).
+ * - OrgEvent: OrgEvent's own read model has no per-agent scoping override at
+ *   all (resources/OrgEvent.ts only gates allowRead() to allowVerified() —
+ *   any verified agent/admin already reads every OrgEvent org-wide). The raw
+ *   table is queried directly purely to avoid instantiating an unneeded
+ *   Resource subclass; the effective access is identical either way.
+ *
+ * No source here EVER receives a global/unscoped entity scan: every query
+ * carries EITHER the source's own read-scope condition (Memory,
+ * Relationship, OrgEvent's already-org-open model) OR a narrowly-targeted,
+ * validated single-entity + bounded-window condition (WorkspaceState), OR
+ * goes through the source's own content-gated resource (Presence).
+ */
+import { Resource, databases } from "@harperfast/harper";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { isValidEntity } from "./entity-vocab.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { withDetachedTxn } from "./table-helpers.js";
+import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { wrapUntrusted } from "./content-safety.js";
+import { getPresenceRoster } from "./presence-internal.js";
+// ─── Tunables ─────────────────────────────────────────────────────────────────
+export const DEFAULT_WINDOW_DAYS = 7;
+const MAX_WINDOW_DAYS = 365;
+// Per-source result cap. The attention view is meant to surface "what's
+// touching this entity right now", not paginate a full history — a hot
+// entity (e.g. a widely-referenced repo) is capped rather than returning an
+// unbounded payload. Each source is independently capped (not a shared total).
+const MAX_RESULTS_PER_SOURCE = 25;
+const JSON_HEADERS = { "Content-Type": "application/json" };
+function badRequest(error, detail) {
+    return new Response(JSON.stringify({ error, ...(detail ? { detail } : {}) }), {
+        status: 400,
+        headers: JSON_HEADERS,
+    });
+}
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: JSON_HEADERS });
+function parseQueryInput(data) {
+    const entity = data?.entity;
+    if (typeof entity !== "string" || entity.length === 0) {
+        return badRequest("invalid_entity", "entity is required (a vocabulary string, e.g. 'repo:owner/name')");
+    }
+    // Exact match on the full type:value string — the SAME validator every
+    // write path (Memory/WorkspaceState/OrgEvent) gates `entities` writes
+    // through (resources/entity-vocab.ts). Rejects anything not drawn from the
+    // closed, documented type set / grammar — never a prefix/regex match, so
+    // this stays a plain indexed equality lookup, never a scan.
+    if (!isValidEntity(entity)) {
+        return badRequest("invalid_entity", `'${entity}' is not a well-formed vocabulary string (type:value, closed type set)`);
+    }
+    let days = DEFAULT_WINDOW_DAYS;
+    if (data?.days !== undefined && data?.days !== null) {
+        const n = Number(data.days);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+            return badRequest("invalid_days", "days must be a positive integer");
+        }
+        days = Math.min(n, MAX_WINDOW_DAYS);
+    }
+    const sinceIso = new Date(Date.now() - days * 24 * 3600_000).toISOString();
+    return { entity, days, sinceIso };
+}
+async function queryMemory(ctx, entity, auth) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "archived", comparator: "not_equal", value: true },
+    ];
+    // Same centralized scope every other cross-agent Memory read path uses
+    // (Memory.search()/SemanticSearch.ts/MemoryBootstrap.ts) — own records (any
+    // visibility) + any other agent's non-private record, org-open. Admin/
+    // internal callers are unfiltered, matching those same call sites.
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        const scope = await resolveReadScope(auth.agentId);
+        conditions.unshift(scope.condition);
+    }
+    const query = {
+        conditions,
+        select: [
+            "id", "agentId", "content", "summary", "subject", "tags", "durability",
+            "visibility", "createdAt", "updatedAt", "entities", "_safetyFlags",
+        ],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+    const callerAgent = auth.kind === "agent" ? auth.agentId : undefined;
+    const hits = [];
+    for await (const r of rows) {
+        const isFlagged = Array.isArray(r._safetyFlags) && r._safetyFlags.length > 0;
+        const fromOther = callerAgent !== undefined && r.agentId !== callerAgent;
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            content: isFlagged ? wrapUntrusted(r.content, fromOther ? r.agentId : undefined) : r.content,
+            summary: r.summary ?? null,
+            subject: r.subject ?? null,
+            tags: Array.isArray(r.tags) ? r.tags : null,
+            durability: r.durability ?? null,
+            visibility: r.visibility ?? null,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt ?? null,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryRelationship(ctx, entity, auth) {
+    const entityCondition = {
+        operator: "or",
+        conditions: [
+            { attribute: "subject", comparator: "equals", value: entity },
+            { attribute: "object", comparator: "equals", value: entity },
+        ],
+    };
+    const conditions = [entityCondition];
+    // Mirror Relationship.ts's search(): non-admin agents are scoped to their
+    // own agentId; admin/internal calls are unfiltered. Never broader than what
+    // a direct POST /Relationship search from this same caller would return.
+    if (auth.kind === "agent" && !auth.isAdmin) {
+        conditions.unshift({ attribute: "agentId", comparator: "equals", value: auth.agentId });
+    }
+    const rows = withDetachedTxn(ctx, () => databases.flair.Relationship.search({ conditions }));
+    const hits = [];
+    for await (const r of rows) {
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            subject: r.subject,
+            predicate: r.predicate,
+            object: r.object,
+            confidence: typeof r.confidence === "number" ? r.confidence : null,
+            validFrom: r.validFrom ?? null,
+            validTo: r.validTo ?? null,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt ?? null,
+        });
+    }
+    hits.sort((a, b) => (b.updatedAt || b.createdAt || "").localeCompare(a.updatedAt || a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryWorkspaceState(ctx, entity, sinceIso) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "timestamp", comparator: "greater_than_equal", value: sinceIso },
+    ];
+    // INTERNAL server-side path (Sherlock Option 1, binding): the RAW generated
+    // table object, never the exported `WorkspaceState` resource class — that
+    // class's search() re-applies strict per-agent scoping keyed off THIS
+    // caller's own identity, which would just filter every teammate's row back
+    // out. See this file's module doc for the full rationale + why this is not
+    // a broadening of WorkspaceState's general (still per-agent, still 403)
+    // read model.
+    const query = {
+        conditions,
+        select: ["id", "agentId", "ref", "phase", "taskId", "summary", "filesChanged", "timestamp", "entities"],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.WorkspaceState.search(query));
+    const hits = [];
+    for await (const r of rows) {
+        hits.push({
+            id: r.id,
+            agentId: r.agentId,
+            ref: r.ref,
+            phase: r.phase ?? null,
+            taskId: r.taskId ?? null,
+            summary: r.summary ?? null,
+            filesChanged: Array.isArray(r.filesChanged) ? r.filesChanged : null,
+            timestamp: r.timestamp,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.timestamp || "").localeCompare(a.timestamp || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+// Presence roster fetch (the synthetic delegation-context trick) now lives in
+// resources/presence-internal.ts, shared with MemoryBootstrap.ts's collision
+// surfacing (flair#681) — see that file's module doc for the full security
+// rationale (why this isn't a forgery, why a fresh signature re-verify isn't
+// possible). This file's own "Presence" doc section above still applies; it
+// just no longer duplicates the code.
+async function queryPresence(auth, entity) {
+    const roster = await getPresenceRoster(auth); // fail-open (empty) — never fail the whole attention query
+    // Bounded scan: Presence carries exactly one row per agent (org-wide agent
+    // count is small), so a free-text substring match here is the pushdown-free
+    // exception the K&S verdict explicitly blesses ("Presence is a bounded
+    // scan, one row/agent, tiny") — unlike the other four sources, currentTask
+    // is unstructured prose with no indexed entities field to push down on.
+    const hits = [];
+    for (const row of roster) {
+        if (typeof row?.currentTask !== "string" || row.currentTask.length === 0)
+            continue;
+        if (!row.currentTask.includes(entity))
+            continue;
+        hits.push({
+            agentId: row.id,
+            displayName: row.displayName,
+            activity: row.activity,
+            currentTask: row.currentTask,
+            presenceStatus: row.presenceStatus,
+            lastHeartbeatAt: row.lastHeartbeatAt,
+        });
+    }
+    hits.sort((a, b) => {
+        const av = typeof a.lastHeartbeatAt === "number" ? a.lastHeartbeatAt : 0;
+        const bv = typeof b.lastHeartbeatAt === "number" ? b.lastHeartbeatAt : 0;
+        return bv - av;
+    });
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+async function queryOrgEvent(ctx, entity, sinceIso) {
+    const conditions = [
+        { attribute: "entities", comparator: "equals", value: entity },
+        { attribute: "createdAt", comparator: "greater_than_equal", value: sinceIso },
+    ];
+    const query = {
+        conditions,
+        select: ["id", "authorId", "kind", "scope", "summary", "detail", "targetIds", "createdAt", "expiresAt", "entities"],
+    };
+    const rows = withDetachedTxn(ctx, () => databases.flair.OrgEvent.search(query));
+    const now = Date.now();
+    const hits = [];
+    for await (const r of rows) {
+        // Skip expired events (mirrors OrgEventCatchup.ts's in-process expiry filter).
+        if (r.expiresAt && new Date(r.expiresAt).getTime() < now)
+            continue;
+        hits.push({
+            id: r.id,
+            authorId: r.authorId,
+            kind: r.kind,
+            scope: r.scope ?? null,
+            summary: r.summary,
+            detail: r.detail ?? null,
+            targetIds: Array.isArray(r.targetIds) ? r.targetIds : null,
+            createdAt: r.createdAt,
+            entities: Array.isArray(r.entities) ? r.entities : null,
+        });
+    }
+    hits.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+    return hits.slice(0, MAX_RESULTS_PER_SOURCE);
+}
+// ─── Resource ─────────────────────────────────────────────────────────────────
+export class AttentionQuery extends Resource {
+    // Self-authorize (allowVerified: any verified agent/admin/internal call;
+    // anonymous denied). Per-source scoping is applied inside post() — see the
+    // module doc above for each source's rule.
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async post(data) {
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent") {
+            const rl = checkRateLimit(auth.agentId, "general");
+            if (!rl.allowed)
+                return rateLimitResponse(rl.retryAfterMs, "attention");
+        }
+        const parsed = parseQueryInput(data);
+        if (parsed instanceof Response)
+            return parsed;
+        const { entity, days, sinceIso } = parsed;
+        // Sequential, not Promise.all: each helper wraps its table read in
+        // withDetachedTxn (save/clear/call/restore ctx.transaction around a
+        // SYNCHRONOUS search() call — see table-helpers.ts's doc). Running five
+        // of these concurrently over the SAME shared `ctx` would risk one call's
+        // save/restore interleaving with another's in-flight generator iteration
+        // in ways Harper's transaction chaining isn't documented to tolerate.
+        // Every other multi-table resource in this codebase (Memory.ts,
+        // SemanticSearch.ts, MemoryBootstrap.ts) sequences its cross-table reads
+        // for the same reason — this query is an internal/coordination read, not
+        // a latency-critical hot path, so the small sequential cost is the safe
+        // trade.
+        const memory = await queryMemory(ctx, entity, auth);
+        const relationship = await queryRelationship(ctx, entity, auth);
+        const workspaceState = await queryWorkspaceState(ctx, entity, sinceIso);
+        const presence = await queryPresence(auth, entity);
+        const orgEvent = await queryOrgEvent(ctx, entity, sinceIso);
+        return {
+            entity,
+            windowDays: days,
+            since: sinceIso,
+            groups: { memory, relationship, workspaceState, presence, orgEvent },
+            counts: {
+                memory: memory.length,
+                relationship: relationship.length,
+                workspaceState: workspaceState.length,
+                presence: presence.length,
+                orgEvent: orgEvent.length,
+                total: memory.length + relationship.length + workspaceState.length + presence.length + orgEvent.length,
+            },
+        };
+    }
+}

package/dist/resources/Credential.js

@@ -1,5 +1,5 @@
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 /**
  * Credential resource — authentication surfaces for Principals.
@@ -13,6 +13,16 @@ import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
  * are never returned in responses).
  */
 export class Credential extends databases.flair.Credential {
+    /**
+     * Self-authorize (mirrors Soul.ts/Relationship.ts/WorkspaceState.ts). Harper
+     * routes some request shapes (e.g. collection-describe `GET /Credential`)
+     * OUTSIDE get()/search() entirely, so those in-method checks alone don't
+     * cover every path — Credential was the one sibling in this sensitive class
+     * missing this gate (#556/#557 swept the others). Deny anonymous/unverified
+     * here; get()/search() below still enforce per-agent ownership scoping on
+     * top of this for the paths they do see.
+     */
+    allowRead() { return allowVerified(this.getContext?.()); }
     async search(query) {
         const auth = await resolveAgentAuth(this.getContext?.());
         // Anonymous HTTP must NOT read credentials. (Previously `!authAgent` was

package/dist/resources/Federation.js

@@ -1,16 +1,42 @@
 import { Resource, databases, server } from "@harperfast/harper";
 import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
-import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, createNonceStore, generateNonce, } from "./federation-crypto.js";
+import { allowAdmin } from "./agent-auth.js";
+import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce, } from "./federation-crypto.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
+import { createPersistentNonceStore, initNonceStoreCleanup } from "./federation-nonce-store.js";
 import { classifyRecord } from "./federation-classify.js";
 export { classifyRecord } from "./federation-classify.js";
 // Module-level nonce store for federation anti-replay.
 // Shared across FederationPair + FederationSync — nonces are globally unique
 // (generated by signBodyFresh per request with 128-bit random nonces).
-const federationNonceStore = createNonceStore();
+//
+// Backed by the `Nonce` table (federation-edge-hardening slice 4) so a
+// process restart doesn't wipe recently-seen nonces within the ±30s
+// freshness window — see federation-nonce-store.ts for the full design.
+// The NonceStore interface (has/set/evict) stays synchronous, so this swap
+// requires NO change to verifyBodySignatureFresh or its 2 call sites below.
+const federationNonceStore = createPersistentNonceStore();
 // Re-export for consumers that import from Federation.ts
 export { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce };
+// ─── Per-record signature enforcement mode (federation-edge-hardening slice 3b) ──
+/**
+ * Whether FederationSync.post requires EVERY record to carry a valid
+ * per-record signature (§3a), skipping unsigned ones (`missing_signature`),
+ * vs. the default "verify-if-present" mode where an unsigned record still
+ * merges (relying on the batch-level signature already verified above it).
+ *
+ * Default OFF (verify-if-present) — pre-3a spokes don't sign individual
+ * records yet, and their batch is already authenticated. Turning this ON
+ * is an OPERATOR decision, never auto-flipped by this code: flip it only
+ * once every paired peer has been confirmed sending per-record signatures
+ * (e.g. by checking SyncLog for unsigned records / peer versions). Flipping
+ * it before every peer has upgraded silently starts dropping that peer's
+ * records instead of merging them.
+ */
+function requireRecordSignatures() {
+    return (process.env.FLAIR_FEDERATION_REQUIRE_RECORD_SIGNATURES ?? "").toLowerCase() === "true";
+}
 // ─── Conflict resolution ─────────────────────────────────────────────────────
 /**
  * Field-level Last-Write-Wins merge.
@@ -36,8 +62,21 @@ function mergeRecord(local, remote) {
 /**
  * GET /FederationInstance — return this instance's identity.
  * Used by peers during pairing and by the admin UI.
+ *
+ * allowRead()=allowAdmin (defense-in-depth, authorizeLocal-escalation-class
+ * follow-up to #601/#604/#609/#612 — flair#614's backstop found this one had
+ * NO allow* at all, so Harper's own default — `user?.role.permission.
+ * super_user`, satisfiable only by a genuine admin OR authorizeLocal's forged
+ * loopback super_user — was silently standing in). Same idiom as
+ * AdminInstance.ts/AdminDashboard.ts: this is an admin-view endpoint (peers
+ * never call it during pairing — FederationPair.post() reads the Instance
+ * table directly server-side to hand a peer our identity; this HTTP GET is
+ * CLI tooling only).
  */
 export class FederationInstance extends Resource {
+    async allowRead() {
+        return allowAdmin(this.getContext?.());
+    }
     async get() {
         // Find or create instance identity
         let instance = null;
@@ -293,6 +332,61 @@ export class FederationSync extends Resource {
                     recordSkip(decision.reason);
                     continue;
                 }
+                // ── Per-record signature verification (federation-edge-hardening slice 3b) ──
+                // classifyRecord's "merge" verdict above only proves the record is
+                // STRUCTURALLY eligible (known table, self-originated OR the sender
+                // is a hub, not stale, not a no-op) — that hub bypass trusts the
+                // BATCH-level signature (verifyBodySignatureFresh above, verified
+                // against the SENDER's pinned key). It does NOT prove the record's
+                // *claimed* originator actually produced it — a hub relaying on
+                // behalf of many spokes could otherwise forge a record under any
+                // originatorInstanceId it likes, and the receiver had no way to
+                // tell. This gate closes that hole: verify the record's own
+                // signature (§3a, set at push-time by the ORIGINATOR, never by
+                // whoever relayed it) against the ORIGINATOR's pinned instance key
+                // — never the sender's key.
+                //
+                // A bad/unverifiable signature skips ONLY this record, never the
+                // batch — rejecting the whole batch on one bad record would be a
+                // DoS vector (one forged/garbled record could blackhole every other
+                // legitimate record riding along in the same POST).
+                const originator = decision.originator;
+                if (record.signature) {
+                    const originatorPublicKey = originator === instanceId
+                        ? peer.publicKey
+                        : (await databases.flair.Peer.get(originator))?.publicKey;
+                    if (!originatorPublicKey) {
+                        recordSkip("unknown_originator_key");
+                        continue;
+                    }
+                    // CONTRACT — must match src/cli.ts runFederationSyncOnce's signing
+                    // payload byte-for-byte: keys { v, table, id, data, updatedAt,
+                    // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
+                    // doesn't matter, but the field SET and values do. `v: 1` versions
+                    // the canonical form itself — bump it on BOTH sides together if the
+                    // signed field set ever changes, so an old signature fails closed
+                    // instead of silently mis-verifying under a new form.
+                    const signatureValid = verifyBodySignature({
+                        v: 1,
+                        table: record.table,
+                        id: record.id,
+                        data: record.data,
+                        updatedAt: record.updatedAt,
+                        originatorInstanceId: originator,
+                        signature: record.signature,
+                    }, originatorPublicKey);
+                    if (!signatureValid) {
+                        recordSkip("invalid_signature");
+                        continue;
+                    }
+                }
+                else if (requireRecordSignatures()) {
+                    // require-mode: unsigned records are no longer trusted on
+                    // batch-level auth alone. Default mode (verify-if-present) falls
+                    // through here and merges — see requireRecordSignatures() above.
+                    recordSkip("missing_signature");
+                    continue;
+                }
                 const mergedData = mergeRecord(local, record);
                 mergedData._originatorInstanceId = decision.originator;
                 mergedData._syncedFrom = instanceId;
@@ -372,8 +466,17 @@ export class FederationSync extends Resource {
 }
 /**
  * GET /FederationPeers — list known peers (admin view).
+ *
+ * allowRead()=allowAdmin (defense-in-depth, authorizeLocal-escalation-class
+ * follow-up to #601/#604/#609/#612 — flair#614's backstop found this one had
+ * NO allow* at all). The docstring already called this "(admin view)" — this
+ * closes the gap between the documented/intended access model and what was
+ * actually enforced (nothing).
  */
 export class FederationPeers extends Resource {
+    async allowRead() {
+        return allowAdmin(this.getContext?.());
+    }
     async get() {
         const peers = [];
         try {
@@ -405,5 +508,21 @@ if (typeof setTimeout !== "undefined") {
             // Swallow — in test/resource-env the Harper databases may not be bound.
             // In production, initFederationCleanup handles its own error paths.
         });
+        // Nonce store hydration (slice 4) — load nonces persisted by a previous
+        // process (if any) before this instance starts guarding live traffic.
+        // Runs on the same deferred tick as the cleanup sweep above; there is a
+        // narrow window between process start and hydration completing during
+        // which a pre-restart nonce isn't yet visible — an accepted tradeoff
+        // consistent with this file's existing deferred-init pattern (see the
+        // cleanup sweep comment above).
+        federationNonceStore.hydrate().catch((err) => {
+            // Swallow — in test/resource-env the Harper databases may not be bound.
+        });
+        // Nonce table eviction sweep — runs on every instance (both hub and
+        // spoke can be the receiving/verifying side of a signed federation
+        // request), unlike PairingToken cleanup which is hub-only.
+        initNonceStoreCleanup().catch((err) => {
+            // Swallow — in test/resource-env the Harper databases may not be bound.
+        });
     }, 0);
 }

package/dist/resources/Integration.js

@@ -15,7 +15,7 @@ export class Integration extends databases.flair.Integration {
     }
     /**
      * Self-authorize now that the global gate is non-rejecting (memory-soul-
-     * read-gate family fix, ops-oox7 — same pattern as Memory.ts/Soul.ts/
+     * read-gate family fix — same pattern as Memory.ts/Soul.ts/
      * WorkspaceState.ts/Relationship.ts). Closes the same P0 leak: Harper
      * routes `GET /Integration/<id>` to get() and the collection describe
      * (`GET /Integration`) outside search(), so neither was gated before this