@tpsdev-ai/flair 0.22.1 → 0.23.0

package/dist/resources/mcp-tools.js

@@ -123,13 +123,20 @@ async function memoryStore(agent, args) {
     // agentId is the RESOLVED agent — Memory.post also re-checks ownership via
     // resolveAgentAuth, so a mismatched body agentId would 403 anyway; we set it
     // to the verified id so the write is correctly owned.
-    return unwrap(await h.post({
+    const body = {
         agentId: agent.agentId,
         content: args?.content,
         type: args?.type ?? "session",
         durability: args?.durability ?? "standard",
         tags: args?.tags,
-    }));
+    };
+    // flair#718 authorship-provenance: forward the resolved OAuth client_id
+    // (never a tool argument — no forging) as claimedClient; Memory.post()
+    // folds it into provenance.claimed.client and strips it from the row.
+    // Omitted entirely when the token carried no client_id.
+    if (agent.clientId)
+        body.claimedClient = agent.clientId;
+    return unwrap(await h.post(body));
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -175,12 +182,20 @@ async function memoryUpdate(agent, args) {
         delete record.validFrom;
         delete record.validTo;
         delete record.archivedAt;
+        // flair#718 authorship-provenance — see memoryStore's comment: forward
+        // the resolved OAuth client_id (never forgeable via args) so the NEW
+        // version's provenance records which client authored this update.
+        if (agent.clientId)
+            record.claimedClient = agent.clientId;
         h.isCollection = true;
         return unwrap(await h.post(record));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
     delete merged.embeddingModel;
+    // flair#718 authorship-provenance — see memoryStore's comment above.
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
     return unwrap(await h.put(merged));
 }
 async function memoryGet(agent, args) {
@@ -287,6 +302,38 @@ async function recordUsage(agent, args) {
         : typeof args?.memoryId === "string" ? [args.memoryId] : undefined;
     return unwrap(await h.post({ memoryIds, attribution: args?.attribution }));
 }
+/**
+ * Verb→tool-name overrides — the three naming quirks where the shipped tool
+ * name isn't record-types.ts's default `${toolPrefix}_${verb}` shape (see
+ * that module's `mcp` header doc, and RECORD_TYPES.<Table>.mcp itself,
+ * record-types slice 3, flair#520). Keyed by table name + verb; consumed by
+ * `mcpToolName()` below and by test/unit/mcp-surface-tripwire.test.ts to
+ * compute the expected tool name for every declared registry verb.
+ *
+ * Placement here (not in record-types.ts) is deliberate — per Kern/
+ * Sherlock's unanimous slice-3 verdict, the registry declares WHAT is
+ * exposed (capability: toolPrefix + verbs); this map declares HOW that
+ * capability's tool is actually named (presentation). Coupling names into
+ * the registry would mix the policy layer with the presentation layer,
+ * exactly what the registry's separation is meant to avoid.
+ */
+export const TOOL_NAME_OVERRIDES = {
+    Soul: { store: "soul_set" },
+    WorkspaceState: { store: "flair_workspace_set" },
+    OrgEvent: { store: "flair_orgevent" },
+};
+/**
+ * Resolve the actual `TOOLS` key for a declared (table, verb) pair: the
+ * `TOOL_NAME_OVERRIDES` entry if one exists, else the default
+ * `${toolPrefix}_${verb}` shape. `toolPrefix` is passed in (rather than
+ * looked up from RECORD_TYPES here) so this stays a pure naming function —
+ * both this module and the tripwire test call it with the registry's own
+ * `toolPrefix` value, keeping the naming rule in exactly one place.
+ */
+export function mcpToolName(table, toolPrefix, verb) {
+    const override = TOOL_NAME_OVERRIDES[table]?.[verb];
+    return override ?? `${toolPrefix}_${verb}`;
+}
 export const TOOLS = {
     memory_search: {
         def: {
@@ -489,7 +536,7 @@ export const TOOLS = {
         impl: recordUsage,
     },
 };
-/** The tool definitions for a tools/list response (exactly the 9 curated tools). */
+/** The tool definitions for a tools/list response (exactly the 12 curated tools). */
 export function listToolDefs() {
     return Object.values(TOOLS).map((t) => t.def);
 }

package/dist/resources/provenance.js

@@ -1,5 +1,36 @@
 /**
- * ─── Write-time provenance stamp (memory-provenance slice 1) ────────────────
+ * Sanitize an optional, unverified `claimed.*` passthrough value (memory-
+ * provenance slice 1 + flair#718 authorship-provenance). Shared by BOTH
+ * `claimed.model` and `claimed.client` — same authority level, same
+ * discipline, one implementation so they can't drift:
+ *
+ *   1. Must be a `string` — anything else (number, object, array) is dropped.
+ *   2. Control characters (C0 + DEL, `\x00`-`\x1F`,`\x7F`) are stripped —
+ *      this is caller-supplied, unverified data landing in a stored JSON
+ *      blob; no newlines/nulls smuggled into logs or downstream renders.
+ *   3. Trimmed.
+ *   4. Length-capped at 200 chars (truncated, not rejected — a label this
+ *      long is almost certainly malformed, but the write must never fail
+ *      because of it).
+ *   5. Dropped (returns `undefined`) if empty after the above — an
+ *      all-control-chars or all-whitespace input is treated as absent, not
+ *      stamped as `""`.
+ *
+ * Sherlock flair#718 review: `claimed.model` previously had only a
+ * truthiness check (no cap, no sanitize) — folded into this same function
+ * "while touching the same code" per that review's non-blocking recommendation.
+ */
+function sanitizeClaim(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const cleaned = value.replace(/[\x00-\x1F\x7F]/g, "").trim();
+    if (cleaned.length === 0)
+        return undefined;
+    return cleaned.length > 200 ? cleaned.slice(0, 200) : cleaned;
+}
+/**
+ * ─── Write-time provenance stamp (memory-provenance slice 1; claimed.client
+ * added by flair#718 authorship-provenance) ──────────────────────────────────
  *
  * Foundational capture for an emergent-trust model: every write gets a
  * structured, versioned `provenance` JSON blob recording what the server can
@@ -8,7 +39,7 @@
  *
  *   { v: 1,
  *     verified: { agentId: <string|null>, timestamp: <ISO string> },
- *     claimed?: { model: <string> } }
+ *     claimed?: { model?: <string>, client?: <string> } }
  *
  * - `verified.agentId` comes from the ALREADY-RESOLVED auth verdict
  *   (resolveAgentAuth) — never from anything the caller can forge on the
@@ -23,10 +54,25 @@
  *   `embeddingModel = getModelId()` stamp in resources/Memory.ts.
  * - `claimed.model` is an OPTIONAL, UNVERIFIED passthrough: included only
  *   when the incoming write payload itself already carries a non-empty
- *   string `model` field. No client/CLI sets one today — this just means the
- *   server won't discard it if/when a future write path does. Never
- *   invented, never defaulted, and the `claimed` key is omitted entirely
- *   (not stamped as `{}`) when absent.
+ *   string `model` field (sanitized via sanitizeClaim above). Never
+ *   invented, never defaulted.
+ * - `claimed.client` (flair#718) is the SAME kind of OPTIONAL, UNVERIFIED
+ *   passthrough, sourced from `content.claimedClient` (a deliberately
+ *   distinct body-field name from the output key — see the write paths in
+ *   resources/Memory.ts / resources/Relationship.ts, which strip this field
+ *   from the row after calling buildProvenance so it is NEVER persisted
+ *   outside this provenance blob). Records WHICH CLIENT authored a write
+ *   under one shared principal (the personal deployment shape — see
+ *   docs/auth.md "Deployment shapes"). `claimed` — never `verified` —
+ *   because this is self-reported by an authenticated principal, not
+ *   independently corroborated: it MUST grant zero authority anywhere
+ *   (never read for access control, attribution weighting, or dedup
+ *   decisions — Sherlock flair#718 binding refinement). On the native /mcp
+ *   OAuth path, the caller is required to source this from the verified
+ *   `client_id` token claim, never the user-controlled `client_name` — see
+ *   resources/mcp-handler.ts's handleToolCall for that stamp site.
+ * - The `claimed` key is omitted entirely (not stamped as `{}`) when both
+ *   `model` and `client` are absent.
  *
  * Originally introduced in resources/Memory.ts (Memory.post()/Memory.put());
  * extracted here so Relationship.ts (and any future write path) can reuse the
@@ -43,8 +89,14 @@ export function buildProvenance(auth, createdAt, content) {
             timestamp: createdAt,
         },
     };
-    if (typeof content?.model === "string" && content.model.length > 0) {
-        provenance.claimed = { model: content.model };
+    const model = sanitizeClaim(content?.model);
+    const client = sanitizeClaim(content?.claimedClient);
+    if (model !== undefined || client !== undefined) {
+        provenance.claimed = {};
+        if (model !== undefined)
+            provenance.claimed.model = model;
+        if (client !== undefined)
+            provenance.claimed.client = client;
     }
     return JSON.stringify(provenance);
 }

package/dist/resources/record-type-kit.js

@@ -0,0 +1,253 @@
+/**
+ * record-type-kit.ts — shared, parameterized building blocks for a flair
+ * table's agent-identity / read-scope / no-forge-attribution machinery
+ * (record-types slice 1: kit extraction, flair#520).
+ *
+ * ─── What this is ────────────────────────────────────────────────────────
+ * Five flair-owned tables — Memory, Relationship, WorkspaceState, OrgEvent,
+ * Soul — each independently hand-copied ~150-250 lines of near-identical
+ * auth/scoping code: call resolveAgentAuth(getContext()), branch on the
+ * three-way verdict (internal / agent / anonymous), 404 a non-owner by-id
+ * read (never 403, so ids can't be enumerated), stamp agentId/authorId from
+ * the verified identity rather than the request body ("no-forge
+ * attribution"). Every allowRead() docstring in those five files literally
+ * says "same pattern as X.ts" — this module makes that pattern real code
+ * instead of a comment convention that can drift.
+ *
+ * ─── What this is NOT (scope discipline for slice 1) ─────────────────────
+ * This is a PURE REFACTOR extracting what is IDENTICAL across the five
+ * existing tables today. It is deliberately conservative, not the full
+ * `applyRecordTypeKit(policy)` composition sketched in the record-types
+ * design doc's §5 (that shape is for slice 2/3's registry, generating a
+ * COMPLETE {allowRead, get, search, post, put, delete} bundle for a
+ * brand-new consumer type with no bespoke logic). The five EXISTING tables
+ * genuinely diverge in real, load-bearing ways that must be preserved
+ * byte-for-byte, not papered over by a one-size bundle:
+ *   - search()'s query-merge shape differs per table (Memory detaches the
+ *     transaction and falls through differently on a bare query object than
+ *     WorkspaceState's in-place mutation than Relationship's nested-wrap);
+ *   - the no-forge attribution idiom differs not just per table but per
+ *     METHOD within a table (WorkspaceState.post() unconditionally stamps
+ *     with no mismatch check at all, while WorkspaceState.put() rejects a
+ *     mismatch and never stamps — see stampAttribution's mode doc below);
+ *   - delete() diverges the most: Memory.delete() doesn't even use
+ *     resolveAgentAuth (raw tpsAgent + isAdmin(), gated on the `permanent`
+ *     durability flag, no ownership check at all for non-permanent rows);
+ *     Soul has no delete() override; the other three each fetch the
+ *     pre-existing record with a different super.get() call signature.
+ *   - OrgEvent and Soul have NO get()/search() overrides at all (org events
+ *     and souls are readable by any verified agent, unscoped by owner) —
+ *     this module does not force them into a scope they never had.
+ * Each of those divergences stays inline in its resource file as visible,
+ * type-specific business logic. What THIS module extracts is only the
+ * genuinely-identical primitives underneath: the auth-gate three-way
+ * dispatch, the two read-scope condition/predicate shapes, the no-forge
+ * attribution idioms (named and parameterized, not merged into one), and
+ * the canonical error-response builders.  `buildProvenance` itself
+ * (./provenance.ts) is already table-agnostic and is reused as-is — this
+ * module does not wrap it, it re-exports it for a single import surface.
+ *
+ * Design lineage: flair#520 design draft (issue comment, 2026-07-13),
+ * Kern's DESIGN REVIEW ("the makeAuthGate/makeReadScope/buildProvenance
+ * as-is extraction is the right factoring... each class keeps its
+ * type-specific business logic visibly, loses only the copied
+ * boilerplate"). `stampEmbedding` (the design's 4th cut-line) is OUT of
+ * scope here — no table this module composes writes an embedding today
+ * (only Memory does, and Memory's embedding logic is dedup-gate-entangled,
+ * not part of the five-table auth/scope/provenance duplication this slice
+ * targets); it belongs to the registry/new-capability slice.
+ */
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { buildProvenance } from "./provenance.js";
+export { buildProvenance };
+// ─── Canonical error responses ─────────────────────────────────────────────
+// Byte-for-byte the same bodies every one of the five files hand-rolled
+// (Memory/Relationship/WorkspaceState/OrgEvent each defined their own
+// FORBIDDEN/UNAUTH/NOT_FOUND consts identically; Soul only needed
+// FORBIDDEN/UNAUTH). Header-key casing is normalized here to "Content-Type"
+// — HTTP header names are case-insensitive (and Harper/undici's Headers
+// object normalizes on read), so this is not an observable behavior change
+// from the two files (Memory.ts, Relationship.ts) whose inline copies used
+// a lowercase "content-type" key.
+export const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+export const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+export const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+// ─── (a) Identity gating — makeAuthGate ────────────────────────────────────
+/**
+ * Produces the `allowRead()` override every one of the five tables hand-
+ * wrote identically:
+ *   `allowRead() { return allowVerified((this as any).getContext?.()); }`
+ * Self-authorizes now that the global gate is non-rejecting (the
+ * memory-soul-read-gate family fix): Harper routes `GET /<Table>/<id>` to
+ * get() and the collection describe (`GET /<Table>`) to a path outside
+ * search(), so neither was gated before that fix landed — closes the same
+ * P0 leak (an anonymous caller getting a 200 with full record content) for
+ * every table that composes this. Per-record/collection scoping is still
+ * each table's own get()/search() responsibility below this gate.
+ *
+ * `allowVerified()` itself (permit verified agents, admins/super_user, and
+ * trusted internal calls; deny anonymous HTTP) already lives in
+ * ./agent-auth.ts and is reused unmodified — this factory exists only to
+ * remove the identical one-line method body duplicated five times, not to
+ * change what it does.
+ *
+ * MUST be composed as a genuine prototype method, never a class-field
+ * assignment (`allowRead = makeAuthGate();`). Harper's Table.js has a code
+ * path (`relatedTable.prototype.allowRead.call(null, user, property,
+ * context)`, used when a query's `select` traverses a GraphQL relationship
+ * into one of these tables under Harper's native attribute-level RBAC) that
+ * reads `allowRead` off the CLASS PROTOTYPE directly, not off a resource
+ * instance. A class field is an own-instance property — invisible to that
+ * lookup — so a class-field assignment would silently fall back to Harper's
+ * default RBAC-based `allowRead` for that one relationship-traversal path
+ * while every direct/primary call (`this.allowRead(...)`, always
+ * instance-invoked) kept working, making the gap easy to miss. Every
+ * caller of this factory MUST wire it as `allowRead() { return
+ * gate.call(this); }` (see Memory.ts/Relationship.ts/WorkspaceState.ts/
+ * OrgEvent.ts/Soul.ts for the exact pattern), not `allowRead =
+ * makeAuthGate();`.
+ */
+export function makeAuthGate() {
+    return function allowRead() {
+        return allowVerified(this.getContext?.());
+    };
+}
+export async function resolveAuthGate(ctx, denyResponse) {
+    const auth = await resolveAgentAuth(ctx);
+    if (auth.kind === "anonymous")
+        return { kind: "denied", response: denyResponse };
+    if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+        return { kind: "unfiltered" };
+    return { kind: "scoped", agentId: auth.agentId };
+}
+/** owner-only: `agentId === authAgentId`, full stop — the model
+ *  Relationship.ts and WorkspaceState.ts hand-rolled identically for their
+ *  get()/search() overrides (`{attribute: ownerField, comparator: "equals",
+ *  value: authAgentId}` / `record[ownerField] !== authAgentId`). No
+ *  visibility field, no org-open exception — a real, legitimate read-scope
+ *  shape in its own right (per Kern/Sherlock's review), not a lesser
+ *  version of Memory's model. */
+function ownerOnlyReadScope(ownerField) {
+    return async (authAgentId) => ({
+        condition: { attribute: ownerField, comparator: "equals", value: authAgentId },
+        isAllowed: (record) => !!record && record[ownerField] === authAgentId,
+    });
+}
+/**
+ * Resolve the read-scope resolver for a table, by mode:
+ *   - "owner-only": own records only, scoped on `ownerField` (defaults to
+ *     "agentId" — every current owner-only caller uses that field; the
+ *     parameter exists so a future owner-only type using a different field,
+ *     the way OrgEvent's WRITE path uses "authorId", isn't hardcoded out).
+ *   - "open-within-org": delegates to the EXACT existing
+ *     resolveReadScope()/PRIVATE_VISIBILITY semantics in
+ *     ./memory-read-scope.ts — Memory's own module, untouched, not
+ *     reimplemented here. `ownerField` is ignored for this mode:
+ *     resolveReadScope() is hardcoded to "agentId" (the only table that
+ *     uses this mode today), matching the task's instruction to delegate to
+ *     that module "as the exact existing" implementation rather than
+ *     generalizing it in this slice.
+ *
+ * The returned resolver is tagged with its own `.mode`/`.ownerField` (record-
+ * types slice 2, flair#520) — harmless own-properties on the function object,
+ * never read by any caller of the resolver itself in production. Pinned by
+ * test/unit/record-type-kit.test.ts directly (mock-free — this primitive
+ * touches no `databases` mock). The registry's own drift tripwire
+ * (test/unit/record-types-registry.test.ts) verifies the five resource files
+ * draw their kit parameters from RECORD_TYPES via a source-text scan instead
+ * of importing them (see that test file's header for why — importing
+ * multiple of Memory.ts/Relationship.ts/WorkspaceState.ts together risks a
+ * cross-file Harper-mock module-cache collision); this tagging exists so a
+ * FUTURE single-resource-file behavior test (the pattern every existing
+ * table's own read-gate test already uses in isolation) can also assert
+ * `<table>ReadScope.mode === RECORD_TYPES.<Table>.readScope` directly against
+ * a live, exported resolver without re-deriving it.
+ */
+export function makeReadScope(mode, ownerField = "agentId") {
+    const resolve = mode === "open-within-org"
+        ? (authAgentId) => resolveReadScope(authAgentId)
+        : ownerOnlyReadScope(ownerField);
+    return Object.assign(resolve, { mode, ownerField });
+}
+/**
+ * By-id read-gate factory for get() overrides that scope a single-record
+ * read the same way search() scopes a collection read (Memory.ts,
+ * Relationship.ts, WorkspaceState.ts — NOT OrgEvent/Soul, which have no
+ * get() override at all and are intentionally left alone, see file header).
+ * Never distinguishes "doesn't exist" from "exists but not yours" — both
+ * return 404, never 403, so a denied caller can't use get() to enumerate
+ * other agents' record ids.
+ *
+ * `superGet` is a caller-supplied closure so the class's own `super.get()`
+ * (which cannot be referenced from outside the class body) stays exactly
+ * where it was.
+ */
+export function makeByIdReadGate(readScope) {
+    return async function byIdReadGate(target, superGet) {
+        // Collection / query reads arrive as a RequestTarget with
+        // `isCollection === true`, and are governed by search() (same owner
+        // scoping). Only a genuine by-id get is ownership-checked below.
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        // Anonymous by-id read is already blocked at the allowRead() gate (403);
+        // this is defense-in-depth if get() is ever reached directly.
+        if (auth.kind === "anonymous")
+            return NOT_FOUND();
+        // Trusted internal call or admin agent — unfiltered, unchanged behavior.
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+            return superGet(target);
+        }
+        // Non-admin agent: scoped per the table's own read-scope model.
+        const record = await superGet(target);
+        if (!record)
+            return NOT_FOUND();
+        const scope = await readScope(auth.agentId);
+        if (!scope.isAllowed(record))
+            return NOT_FOUND();
+        return record;
+    };
+}
+export function stampAttribution(auth, content, field, mode, forbiddenMessage) {
+    if (auth.kind !== "agent")
+        return {}; // internal → always passthrough
+    if (auth.isAdmin) {
+        if (mode === "stamp-default")
+            content[field] ||= auth.agentId;
+        // every other mode: admin passthrough, untouched
+        return {};
+    }
+    // non-admin agent
+    switch (mode) {
+        case "validate-truthy":
+            if (content?.[field] && content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            return {};
+        case "validate-strict":
+            if (content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            return {};
+        case "stamp-default":
+            content[field] = auth.agentId;
+            return {};
+        case "stamp-strict":
+            if (content?.[field] && content[field] !== auth.agentId) {
+                return { denied: FORBIDDEN(forbiddenMessage) };
+            }
+            content[field] = auth.agentId;
+            return {};
+    }
+}
+// ─── (d) Provenance wiring ──────────────────────────────────────────────────
+// buildProvenance itself is already table-agnostic (./provenance.ts) and is
+// re-exported above, unmodified, for a single kit import surface. Per
+// Kern/Sherlock's DESIGN REVIEW verdict (Q4): stamp the identical shape
+// everywhere it's wired, never a table-specific format — and per this
+// slice's explicit behavior-preservation bar, do NOT wire it onto
+// WorkspaceState/OrgEvent, which don't stamp it today (only Memory and
+// Relationship do). See Memory.ts/Relationship.ts for the call sites.