@tpsdev-ai/flair 0.51.2 → 0.53.0

package/dist/resources/record-owner-guard.js

@@ -51,6 +51,21 @@
  * resources — they answer a different question, "may you attribute a NEW record
  * to someone else", which this guard does not address.
  *
+ * ─── The owner field is immutable to a non-admin ─────────────────────────────
+ *
+ * Owning a row grants writing its ordinary fields, not rewriting the field that
+ * decides who owns it. Left alone, a caller that legitimately owns a row could
+ * use a later write to re-point that field at another principal — handing the
+ * row away, or attributing its content to someone else after the fact, past the
+ * create-time no-forge check each resource applies only on creation. So
+ * `isForbiddenOwnerFieldChange` refuses any non-admin write whose owner value
+ * differs from the stored one, comparing against STORED STATE exactly as above.
+ * It cannot run in the middleware — Harper's middleware Request has no parsed
+ * body — so it is enforced at the resource layer via a single shared delegate
+ * (resources/owner-field-guard.ts) called by each principal-owning resource's
+ * put() and patch(), the same shape resources/Agent.ts uses for the principal
+ * table's admin-status field.
+ *
  * ─── Keeping this honest as the codebase grows ───────────────────────────────
  *
  * OWNER_FIELDS below is static and PR-reviewed, matching the posture of
@@ -69,12 +84,18 @@
  * being absent on the day someone adds one.
  */
 export const OWNER_FIELDS = Object.freeze({
+    Asset: "agentId",
     Credential: "principalId",
     Integration: "agentId",
     Memory: "agentId",
     MemoryCandidate: "agentId",
     MemoryGrant: "ownerId",
     MemoryUsage: "agentId",
+    // The Message envelope's owning principal is the SENDER (`from`), not
+    // `agentId` — the per-table owner field, matching federation-classify's
+    // PRINCIPAL_OWNER_FIELD. `from` is not one of OWNER_COLUMN_NAMES, so the
+    // coverage test verifies it against the schema block directly.
+    Message: "from",
     OAuthAuthCode: "principalId",
     OAuthToken: "principalId",
     OrgEvent: "authorId",
@@ -134,16 +155,61 @@ export function resolveGuardedRecord(pathname) {
  * Decide whether a caller may mutate an already-stored record.
  *
  * Pure, so the decision is testable without a Harper instance — the middleware
- * supplies the record it loaded. A record that does not exist, or that carries
- * no owner value, is NOT refused here: the first is a create (or a 404 the
- * resource will produce), and the second is a row with nothing to own, neither
- * of which this rule is about.
+ * supplies the record it loaded. A record that does not EXIST is not refused:
+ * that is a create (or a 404 the resource will produce), which this rule leaves
+ * to each resource's own attribution check.
+ *
+ * A record that exists but carries NO owner value is refused for a non-admin.
+ * Nobody owns such a row, so no non-admin agent id can match it, and the safe
+ * reading of "no owner" is "not yours" rather than "everyone's" — the guard
+ * fails closed. For the tables whose owner column is required by schema this is
+ * unreachable in practice, but a table with a nullable owner column (or a row
+ * that predates one becoming required) must not become a shared write surface.
  */
 export function isForbiddenOwnerMutation(record, ownerField, callerAgentId) {
     if (!record)
         return false;
     const owner = record[ownerField];
     if (owner == null || owner === "")
-        return false;
+        return true;
     return owner !== callerAgentId;
 }
+/**
+ * Decide whether a caller may CHANGE the owner field of an already-stored record.
+ *
+ * The ownership rule above answers "may you write this row"; it does not answer
+ * "may you rewrite the field that decides who owns it". Those are different
+ * questions, and a caller that legitimately owns a row today can still use a
+ * write to re-point that row at another principal — handing the row away, or
+ * attributing its content to someone else after the fact, past the create-time
+ * no-forge attribution each resource enforces only on creation.
+ *
+ * So the owner field is immutable to a non-admin: any write whose owner value
+ * differs from the stored one is refused. This mirrors resources/Agent.ts's
+ * shared write-authorization helper, which compares the RESULTING value against
+ * the stored one across both put() and patch() — a merged-vs-stored comparison,
+ * so a partial write that never names the field, or a no-op restatement of the
+ * current owner, is not a spurious denial.
+ *
+ * Pure and body-aware: `requested` is the request content (the caller's claim),
+ * `record` is the stored row (the ground truth). A create (`record` absent) is
+ * not this rule's business — attribution on creation belongs to the resource.
+ * Enforced at the RESOURCE layer (see resources/owner-field-guard.ts), because
+ * Harper's middleware Request exposes no parsed body — the same reason Agent.ts
+ * enforces its analogous rule in the resource rather than the middleware.
+ */
+export function isForbiddenOwnerFieldChange(record, requested, ownerField, 
+// Deliberately caller-agnostic: the rule is "does this write CHANGE the owner
+// field", which is decided purely by requested-vs-stored and never depends on
+// WHO is asking (the caller's authority is decided one layer up, in
+// owner-field-guard.ts). The parameter is kept only for signature symmetry
+// with isForbiddenOwnerMutation; it is intentionally unused.
+_callerAgentId) {
+    if (!record)
+        return false;
+    if (requested == null || typeof requested !== "object")
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(requested, ownerField))
+        return false;
+    return requested[ownerField] !== record[ownerField];
+}

package/dist/resources/record-types.js

@@ -107,12 +107,10 @@
  * The stamped attribute name is always `ownerField` above — no type uses a
  * different field for attribution vs. ownership scoping.
  *
- * `provenance` — true only for Memory and Relationship (the two tables that
+ * `provenance` — true for Memory, Relationship and Soul (the tables that
  * call `buildProvenance()` today and carry a nullable `provenance: String`
- * schema field). WorkspaceState/OrgEvent/Soul are `false`: not an oversight
- * — nobody wired it, and none of the three declare the schema field, so
- * flipping this to `true` without a schema migration would be a lie the
- * registry tells about what actually gets stamped.
+ * schema field). Soul additionally stamps its authenticated source class.
+ * WorkspaceState and OrgEvent do not declare or stamp provenance.
  *
  * `embedding` — set only for Memory (`content` is the embedded field; the
  * type has its own exposed semantic-search tool today — `memory_search` /
@@ -254,6 +252,28 @@
 // `makeReadScope()`/`stampAttribution()` (which expect the narrow literal
 // unions, not the wide ones) with no runtime cast or non-null assertion.
 export const RECORD_TYPES = {
+    // Asset — binary blobs (images/screenshots) owned by an agent, linked to a
+    // Memory. images-in-Flair slice 1 (storage): owner-only read scope (standard
+    // review bar — an agent's assets are private to it, like Relationship/
+    // WorkspaceState), no embedding (binary, no recall surface), no `mcp`
+    // (absent = no MCP exposure; serving assets over /mcp is a later reviewed
+    // slice). `federation: "excluded"` is MANDATORY for any new type per this
+    // file's header (Sherlock DESIGN REVIEW Q6): Federation.ts's push table
+    // list is unchanged, so Asset blobs never leave the instance — a Memory that
+    // does federate carries only the assetId reference, not the bytes.
+    // Lifecycle: orphans retained until the owner deletes the Asset row; no
+    // Memory-delete GC this slice. Slice 2 serving 404s dangling refs; GC
+    // sweep + memoryId exist-and-owned validation deferred to slice 2.
+    Asset: {
+        table: "Asset",
+        ownerField: "agentId",
+        identity: "gated",
+        readScope: "owner-only",
+        attribution: { post: "stamp-default", put: "validate-strict" },
+        provenance: false,
+        remEligible: false,
+        federation: "excluded",
+    },
     Memory: {
         table: "Memory",
         ownerField: "agentId",
@@ -310,7 +330,7 @@ export const RECORD_TYPES = {
         // intentionally readable by any verified agent. See header doc.
         readScope: "none",
         attribution: { post: "validate-truthy", put: "validate-truthy" },
-        provenance: false,
+        provenance: true,
         remEligible: false,
         federation: "included",
         mcp: { toolPrefix: "soul", readVerbs: ["get"], writeVerbs: ["store"] },
@@ -363,8 +383,11 @@ export const RECORD_TYPES = {
 //   record_usage — usage-signal resource (RecordUsage.ts), not a table verb
 //   memory_basement — archive action (flair#1472), not a table verb
 //   memory_restore  — un-archive action (flair#1472), not a table verb
+//   skill_store     — skill-tagged Memory write (flair#1542), not a table verb
+//   skill_search    — skill-tagged Memory recall (flair#1546), rides SemanticSearch
+//   skill_get       — full skill read by id (flair#1546), rides Memory.get
 //
-export const COMPOSITE_MCP_TOOLS = ["bootstrap", "attention", "record_usage", "memory_basement", "memory_restore"];
+export const COMPOSITE_MCP_TOOLS = ["bootstrap", "attention", "record_usage", "memory_basement", "memory_restore", "skill_store", "skill_search", "skill_get"];
 // ─── Runtime immutability ───────────────────────────────────────────────────
 // Belt-and-suspenders backstop for the "static, compiled" invariant (see
 // header doc). TypeScript's `as const satisfies` already gives compile-time

package/dist/resources/relay-lib.js

@@ -0,0 +1,205 @@
+/**
+ * relay-lib.ts — Flair Relay S1 pure logic (no Harper imports).
+ *
+ * Extracted from the Message resource the same way federation-classify.ts is
+ * extracted from Federation.ts: the load-bearing decisions (canonical signing
+ * body, contentHash, inbox cap + per-sender sub-cap, and the absorbing
+ * state machine) are pure functions that can be unit-tested without spinning
+ * a Harper instance, and are the single source of truth shared by the
+ * Message resource (send/inbox/consume/sweep) and the federation apply path.
+ *
+ * Design + review amendments: Flair Relay S1 (flair#1521) §4 (envelope +
+ * delivery) and §12 (binding review amendments — P0-3 absorbing state, P0-4
+ * contentHash, P0(S) per-sender sub-caps + server-resolved orgScope, P1-5 seq).
+ */
+import { createHash } from "node:crypto";
+import { canonicalize, signBody, verifyBodySignature } from "./federation-crypto.js";
+/**
+ * `consumed` is ABSORBING (§12 P0-3): once a message is consumed, no later
+ * write — a deadline sweep, a redelivered original, a federation merge — may
+ * regress it. The sender must never be told "failed" about a message the
+ * recipient actually consumed. That inversion is the exact bug this design
+ * exists to kill.
+ */
+export const ABSORBING_STATE = "consumed";
+// ─── Caps (§12 P0(S) — DoS lever) ───────────────────────────────────────────
+//
+// A global cap alone lets one hostile sender pin a recipient's whole inbox and
+// lock everyone else out. The per-sender sub-cap bounds any single sender well
+// below the global cap, so a flooding sender only ever fills its own slice.
+// Env-overridable for operators; defaults are deliberately generous.
+export const DEFAULT_INBOX_CAP = 1000;
+export const DEFAULT_PER_SENDER_CAP = 100;
+export function inboxCap() {
+    return positiveIntEnv(process.env.FLAIR_RELAY_INBOX_CAP, DEFAULT_INBOX_CAP);
+}
+export function perSenderCap() {
+    return positiveIntEnv(process.env.FLAIR_RELAY_PER_SENDER_CAP, DEFAULT_PER_SENDER_CAP);
+}
+function positiveIntEnv(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+/**
+ * Server-resolved org sentinel for an instance that has never federated (no
+ * Instance row). The org scope is always the instance itself (single-tenant:
+ * "an org/instance is one shared knowledge base") — resolved server-side,
+ * NEVER trusted from the message body. Callers pass `localInstanceId() ?? this`.
+ */
+export const LOCAL_ORG_SENTINEL = "local";
+// ─── Canonical bodies ───────────────────────────────────────────────────────
+//
+// TWO field sets, both pure functions of the envelope so sender and server
+// compute byte-identical inputs:
+//
+//   contentHash — a stable fingerprint of the message CONTENT. Excludes `id`
+//   and `createdAt` (a retry may restamp either) so an identical resend
+//   dedups; includes `seq` so distinct messages in a thread never collide.
+//
+//   signed body — everything the signature covers: the content PLUS `id`,
+//   `createdAt` and `contentHash`. Excludes only the mutable server/lifecycle
+//   fields (`state`, `deliveredAt`, `consumedAt`, `failureReason`) and the
+//   `signature` itself.
+// `inReplyTo`/`parentContentHash` are the reply-linkage of the envelope
+// (design §4.2). They land in S1 (though "understood" reply semantics are S3)
+// and are CONTENT — two messages that differ only in what they reply to are
+// distinct, so they belong in the contentHash (dedup key) AND under the
+// signature (SIGNED_BODY_FIELDS), never trusted unsigned.
+export const CONTENT_HASH_FIELDS = [
+    "from",
+    "to",
+    "threadId",
+    "seq",
+    "kind",
+    "body",
+    "orgScope",
+    "deadline",
+    "inReplyTo",
+    "parentContentHash",
+    "senderModel",
+    "senderProvider",
+    "senderRunId",
+];
+export const SIGNED_BODY_FIELDS = [
+    "id",
+    "from",
+    "to",
+    "threadId",
+    "seq",
+    "kind",
+    "body",
+    "orgScope",
+    "deadline",
+    "inReplyTo",
+    "parentContentHash",
+    "createdAt",
+    "contentHash",
+    "senderModel",
+    "senderProvider",
+    "senderRunId",
+];
+/**
+ * Pick only the named keys whose value is neither undefined nor null. Dropping
+ * null/undefined (rather than emitting them) keeps canonicalization stable
+ * across "field absent" vs "field explicitly null" — both sign the same bytes.
+ */
+function pick(obj, fields) {
+    const out = {};
+    for (const f of fields) {
+        const v = obj[f];
+        if (v !== undefined && v !== null)
+            out[f] = v;
+    }
+    return out;
+}
+/** sha256 (hex) over the canonical content — retry-dedup key + integrity check. */
+export function computeContentHash(msg) {
+    const canonical = canonicalize(pick(msg, CONTENT_HASH_FIELDS));
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** The exact object the ed25519 signature is taken over (no `signature` key). */
+export function signedBody(msg) {
+    return pick(msg, SIGNED_BODY_FIELDS);
+}
+/**
+ * Seal a message for sending: stamp contentHash over the content, then sign the
+ * full signed body (which now includes that contentHash) with the sender's
+ * ed25519 secret key. Sender-side + test helper — the server never signs.
+ */
+export function sealMessage(msg, secretKey) {
+    const contentHash = computeContentHash(msg);
+    const withHash = { ...msg, contentHash };
+    const signature = signBody(signedBody(withHash), secretKey);
+    return { ...withHash, signature };
+}
+/**
+ * Server-side envelope verification:
+ *   1. signature present,
+ *   2. the sender-supplied contentHash actually matches the content (a second
+ *      integrity check under the signature — §12 P0-4),
+ *   3. the ed25519 signature verifies over the signed body against the
+ *      sender's pinned public key.
+ * Any tampered signed field flips (3); a forged contentHash flips (2).
+ */
+export function verifyMessageSignature(msg, publicKeyB64url) {
+    if (!msg.signature)
+        return { ok: false, reason: "missing_signature" };
+    const expectedHash = computeContentHash(msg);
+    if (msg.contentHash !== expectedHash)
+        return { ok: false, reason: "content_hash_mismatch" };
+    const body = { ...signedBody(msg), signature: msg.signature };
+    if (!verifyBodySignature(body, publicKeyB64url))
+        return { ok: false, reason: "invalid_signature" };
+    return { ok: true };
+}
+/**
+ * Backpressure that fails LOUD: the send is rejected synchronously when the
+ * recipient inbox is at the global cap OR this sender is at its sub-cap. The
+ * sub-cap is checked first so a hostile sender is told exactly why, and a
+ * recipient at the global cap because of ONE sender never masks a well-behaved
+ * sender that still has room (their sub-cap is independent).
+ */
+export function capDecision(counts, caps = { inbox: inboxCap(), perSender: perSenderCap() }) {
+    if (counts.senderUnconsumed >= caps.perSender) {
+        return { ok: false, reason: "inbox_full", scope: "sender" };
+    }
+    if (counts.recipientUnconsumed >= caps.inbox) {
+        return { ok: false, reason: "inbox_full", scope: "recipient" };
+    }
+    return { ok: true };
+}
+// ─── Absorbing state machine (§12 P0-3) ─────────────────────────────────────
+/** A message is still in the inbox (redeliverable) until consumed or failed. */
+export function isUnconsumed(state) {
+    return state === "submitted" || state === "delivered";
+}
+/**
+ * Reconcile a would-be new state against the local one under the absorbing
+ * rule. `consumed` always wins (over anything, in either position); `failed`
+ * yields only to `consumed`. This is the single guard both the deadline sweep
+ * and the federation merge path consult, so the invariant cannot drift between
+ * them.
+ */
+export function reconcileState(localState, incomingState) {
+    if (localState === "consumed" || incomingState === "consumed")
+        return "consumed";
+    if (localState === "failed")
+        return "failed";
+    return incomingState;
+}
+/**
+ * Deadline sweep decision for one row at time `now`. Fails an unconsumed row
+ * whose deadline has passed; NEVER touches a consumed row (absorbing) and
+ * never re-fails an already-failed one, and never fails a row with no deadline.
+ */
+export function sweepDecision(row, now) {
+    if (!isUnconsumed(row.state))
+        return { fail: false };
+    if (!row.deadline)
+        return { fail: false };
+    if (new Date(row.deadline).getTime() > now.getTime())
+        return { fail: false };
+    return { fail: true, failureReason: "deadline" };
+}