@tpsdev-ai/flair 0.51.1 → 0.52.0

package/dist/resources/Asset.js

@@ -0,0 +1,203 @@
+import { createBlob, databases } from "harper";
+import { resolveAgentAuth } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
+import { FORBIDDEN, UNAUTH, makeAuthGate, makeByIdReadGate, makeReadScope, resolveAuthGate, stampAttribution, } from "./record-type-kit.js";
+import { RECORD_TYPES } from "./record-types.js";
+// Kit parameters read FROM RECORD_TYPES.Asset (single source of truth), same
+// composition MemoryCandidate.ts uses.
+const assetReadScope = makeReadScope(RECORD_TYPES.Asset.readScope, RECORD_TYPES.Asset.ownerField);
+const assetByIdReadGate = makeByIdReadGate(assetReadScope);
+const assetAuthGate = makeAuthGate();
+/**
+ * Asset — a binary blob (screenshot/image) owned by an agent and linked to a
+ * Memory. Storage slice (images-in-Flair slice 1): lets a spoke (e.g. the
+ * Visual Memory Vault) write image bytes into the hub as a Harper Blob and read
+ * them back, owner-scoped. No MCP surface yet (RECORD_TYPES.Asset carries no
+ * `mcp` field); serving assets through `/mcp` is a separate, security-reviewed
+ * slice.
+ *
+ * Read: identity-gated (anonymous HTTP denied) AND owner-only (an agent sees
+ * only its own assets; by-id reads 404-never-403 to avoid an id oracle).
+ * Write: self-enforcing — a non-admin agent may create/modify/delete only its
+ * own assets (`agentId` no-forge attribution, same idiom as WorkspaceState:
+ * stamp on create, validate on update). Admin/internal calls pass unfiltered.
+ *
+ * Blob handling: a base64 `data` string is decoded and wrapped with
+ * `createBlob(..., { type: contentType })` so the bytes are stored decoded and
+ * out-of-record, not as the literal base64 text Harper's string coercion would
+ * otherwise persist. Write-time gates (Sherlock STOP, this slice): decoded
+ * size is capped at MAX_ASSET_DECODED_BYTES, and `contentType` must be an
+ * allowlisted `image/*` (XML/SVG subtypes rejected) so a mistyped or
+ * unbounded blob cannot land. Non-string `data` without a readable size is
+ * rejected (400) rather than persisted unbounded.
+ *
+ * Lifecycle (Kern P1, this slice): an Asset is retained until its owner
+ * deletes the row. Deleting or superseding the parent Memory does not sweep
+ * linked blobs — no GC here. Slice 2's serving tool must 404 a dangling
+ * memoryId/assetId; the GC sweep lands with that slice. `updatedAt` is
+ * stamped on every write so that sweep can key on recency without a second
+ * schema change. Harper unlinks blob files when the Asset row is deleted.
+ *
+ * `memoryId` is an unvalidated, mutable string this slice (exist-and-owned
+ * check deferred). Harmless for owner-only reads; slice 2's OAuth-scoped
+ * asset URL in memory_search must not assume the parent Memory still exists
+ * or is owned by the writer.
+ */
+export class Asset extends databases.flair.Asset {
+    allowRead() { return assetAuthGate.call(this); }
+    async get(target) {
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        return assetByIdReadGate.call(this, target, (t) => super.get(t));
+    }
+    async search(query) {
+        const ctx = this.getContext?.();
+        const gate = await resolveAuthGate(ctx, UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
+            return super.search(query);
+        const scope = await assetReadScope(gate.agentId);
+        const agentCondition = scope.condition;
+        if (!query?.conditions) {
+            return super.search({ conditions: [agentCondition], ...(query || {}) });
+        }
+        return super.search({
+            ...query,
+            conditions: [agentCondition, { conditions: query.conditions, operator: query.operator || "and" }],
+            operator: "and",
+        });
+    }
+    async post(content) {
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        const attr = stampAttribution(auth, content, RECORD_TYPES.Asset.ownerField, RECORD_TYPES.Asset.attribution.post, "forbidden: cannot store an asset for another agent");
+        if (attr.denied)
+            return attr.denied;
+        const blobDenial = _coerceBlob(content);
+        if (blobDenial)
+            return blobDenial;
+        content.createdAt ||= new Date().toISOString();
+        content.updatedAt = new Date().toISOString();
+        return super.post(content);
+    }
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, RECORD_TYPES.Asset.ownerField);
+        if (denial)
+            return denial;
+        const blobDenial = _coerceBlob(content);
+        if (blobDenial)
+            return blobDenial;
+        content.updatedAt = new Date().toISOString();
+        return super.patch(content, query);
+    }
+    async put(content) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, RECORD_TYPES.Asset.ownerField);
+        if (denial)
+            return denial;
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        const attr = stampAttribution(auth, content, RECORD_TYPES.Asset.ownerField, RECORD_TYPES.Asset.attribution.put, "forbidden: cannot modify an asset owned by another agent");
+        if (attr.denied)
+            return attr.denied;
+        const blobDenial = _coerceBlob(content);
+        if (blobDenial)
+            return blobDenial;
+        content.updatedAt = new Date().toISOString();
+        return super.put(content);
+    }
+    async delete(id, context) {
+        const ctx = this.getContext?.();
+        const gate = await resolveAuthGate(ctx, UNAUTH());
+        if (gate.kind === "denied")
+            return gate.response;
+        if (gate.kind === "unfiltered")
+            return super.delete(id, context);
+        const record = await super.get(id);
+        if (!record)
+            return super.delete(id, context);
+        if (record[RECORD_TYPES.Asset.ownerField] !== gate.agentId) {
+            return FORBIDDEN("forbidden: cannot delete an asset owned by another agent");
+        }
+        return super.delete(id, context);
+    }
+}
+/** Decoded payload cap. Screenshots fit; a multi-GB write is a DoS, not a photo. */
+export const MAX_ASSET_DECODED_BYTES = 10 * 1024 * 1024;
+const MAX_ASSET_BASE64_CHARS = Math.ceil(MAX_ASSET_DECODED_BYTES * 4 / 3) + 8;
+const BAD_REQUEST = (msg) => new Response(JSON.stringify({ error: msg }), { status: 400, headers: { "Content-Type": "application/json" } });
+/**
+ * Allow `image/*` except XML/SVG subtypes (XSS-capable). Parameters after `;`
+ * are stripped; `image/jpg` normalizes to `image/jpeg`.
+ */
+function normalizeAssetContentType(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let base = raw.split(";", 1)[0].trim().toLowerCase();
+    if (base === "image/jpg")
+        base = "image/jpeg";
+    if (!base.startsWith("image/"))
+        return null;
+    const subtype = base.slice("image/".length);
+    if (!subtype || subtype.includes("/") || subtype === "svg+xml" || subtype.endsWith("+xml"))
+        return null;
+    return base;
+}
+function decodedSizeOf(data) {
+    if (typeof data?.byteLength === "number")
+        return data.byteLength;
+    if (typeof data?.length === "number")
+        return data.length;
+    if (typeof data?.size === "number")
+        return data.size;
+    return undefined;
+}
+/**
+ * Decode a base64 `data` string into a Harper Blob with the record's MIME type.
+ * A caller may also pass an already-created Blob/Buffer, which is left as-is for
+ * Harper's own coercion (size still capped when readable). No-op when `data`
+ * is absent and `contentType` is not being written.
+ *
+ * Returns a 400 Response when the write would persist an unbounded or
+ * mistyped blob; otherwise undefined.
+ */
+function _coerceBlob(content) {
+    if (!content)
+        return;
+    const hasType = content.contentType != null && content.contentType !== "";
+    if (hasType) {
+        const normalized = normalizeAssetContentType(content.contentType);
+        if (!normalized) {
+            return BAD_REQUEST("invalid contentType: must be an allowlisted image MIME type");
+        }
+        content.contentType = normalized;
+    }
+    if (content.data == null)
+        return;
+    if (!hasType) {
+        return BAD_REQUEST("contentType is required when writing asset data");
+    }
+    if (typeof content.data === "string") {
+        if (content.data.length > MAX_ASSET_BASE64_CHARS) {
+            return BAD_REQUEST(`asset exceeds ${MAX_ASSET_DECODED_BYTES} byte decoded size cap`);
+        }
+        const decoded = Buffer.from(content.data, "base64");
+        if (decoded.length > MAX_ASSET_DECODED_BYTES) {
+            return BAD_REQUEST(`asset exceeds ${MAX_ASSET_DECODED_BYTES} byte decoded size cap`);
+        }
+        content.data = createBlob(decoded, { type: content.contentType });
+        return;
+    }
+    const size = decodedSizeOf(content.data);
+    if (typeof size !== "number") {
+        return BAD_REQUEST("asset data must be a base64 string or a sized binary payload");
+    }
+    if (size > MAX_ASSET_DECODED_BYTES) {
+        return BAD_REQUEST(`asset exceeds ${MAX_ASSET_DECODED_BYTES} byte decoded size cap`);
+    }
+}

package/dist/resources/AutoPromoteCandidates.js

@@ -1,3 +1,4 @@
+import { stampMemoryPromotionIsolated } from "./promotion-stamp.js";
 /**
  * POST /AutoPromoteCandidates  (#1205b-2 — the UNATTENDED promotion path)
  *
@@ -147,10 +148,6 @@ export class AutoPromoteCandidates extends Resource {
                 // scopeTag FIRST — the per-user access-control boundary (Req 2).
                 tags: buildAutoPromotedTags(c.id, decision.scopeTag),
                 derivedFrom: Array.isArray(c.sourceMemoryIds) ? c.sourceMemoryIds : [],
-                promotionStatus: "approved",
-                promotedAt: decidedAt,
-                // Req 4 — non-impersonating machine reviewerId.
-                promotedBy: decision.reviewerId,
                 createdAt: decidedAt,
             };
             // ── The write — MEMORY ONLY ────────────────────────────────────────────
@@ -174,6 +171,7 @@ export class AutoPromoteCandidates extends Resource {
                 skipped.push({ id: c.id, reason: `memory_write_rejected:${writeRes.status}` });
                 continue;
             }
+            await stampMemoryPromotionIsolated(memId, decision.reviewerId, decidedAt, ctx);
             // ── Mark the candidate promoted (commit point) ─────────────────────────
             // Ordered AFTER the Memory write, matching the human promote path: the
             // safe failure state is a promoted Memory whose candidate is still pending

package/dist/resources/Credential.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { stampAttribution, UNAUTH } from "./record-type-kit.js";
 /**
@@ -115,7 +116,20 @@ export class Credential extends databases.flair.Credential {
         const { tokenHash, ...safe } = result;
         return safe;
     }
+    // PATCH routes past put(), so the owner-field rule below is enforced on both
+    // verbs via the one shared delegate. principalId owns a credential; a non-admin
+    // may rotate a token on its OWN credential but never re-point it at another
+    // principal. (Self-update stays legitimate — update:true is retained.)
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "principalId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content) {
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "principalId");
+        if (__ownerDenial)
+            return __ownerDenial;
         const auth = await resolveAgentAuth(this.getContext?.());
         if (auth.kind === "anonymous") {
             return new Response(JSON.stringify({ error: "authentication required" }), {

package/dist/resources/Federation.js

@@ -3,6 +3,9 @@ import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
 import { allowAdmin } from "./agent-auth.js";
 import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, generateNonce, } from "./federation-crypto.js";
+import { reconcileState } from "./relay-lib.js";
+import { isSkillWrite } from "./skill-write.js";
+import { noteWriteStamp } from "./embedding-space-guard.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
 import { createPersistentNonceStore, initNonceStoreCleanup } from "./federation-nonce-store.js";
 import { classifyRecord, reconstructRecordVerifyBody, checkPrincipalEntitlement, } from "./federation-classify.js";
@@ -69,6 +72,30 @@ function mergeRecord(local, remote) {
     }
     return merged;
 }
+/**
+ * embedding-space-guard slice 1 (the raw-writer-coverage hole K&S found in
+ * review #1554): the sync-in merge persists Memory rows via the RAW table
+ * handle, bypassing Memory.post()/put(). An LWW remote-win copies the REMOTE
+ * `embeddingModel` into `mergedData`, so a memory synced from a spoke on a
+ * different engine/model lands a FOREIGN-space vector. Without tripping the
+ * vector-space guard's latch, the next recall's O(1) "uniform" consult would
+ * cosine that foreign vector = mixed-space garbage — exactly the failure the
+ * guard exists to kill. Trip the latch here.
+ *
+ * `noteWriteStamp` no-ops for a current/bare stamp (a self-originated or
+ * same-space sync) and for a non-Memory table (no `embeddingModel`), so only a
+ * genuinely foreign Memory sync trips it. Kept as a note-ONLY helper — the raw
+ * `table.put(mergedData)` stays INLINE at the call site so the raw-writer
+ * coverage gates (authority-field-guard.test.ts / memory-embedding-writer-
+ * coverage.test.ts) still enumerate the Memory writer — while the trip decision
+ * itself is unit-testable without standing up the full signed sync-in path (see
+ * test/unit-isolated/embedding-space-guard-federation.test.ts).
+ */
+export function noteFederationMergedMemory(recordTable, mergedData) {
+    if (recordTable === "Memory") {
+        noteWriteStamp(mergedData.embeddingModel);
+    }
+}
 // ─── Instance identity ───────────────────────────────────────────────────────
 /**
  * GET /FederationInstance — return this instance's identity.
@@ -379,6 +406,21 @@ export class FederationSync extends Resource {
             Soul: databases.flair.Soul,
             Agent: databases.flair.Agent,
             Relationship: databases.flair.Relationship,
+            // Flair Relay (flair#1521). Registered so the policy + owner-field land now
+            // (the design's ship-order). No spoke pushes Message records in S1 — this is the
+            // RECEIVE side only; the absorbing-state guard below keeps an incoming
+            // Message merge from ever regressing a locally-consumed row (§12 P0-3).
+            //
+            // S2 COMMENT-PIN (Kern P1-4, flair#1521): the receive-only carve-out means
+            // an incoming Message record is verified only at the RECORD level (batch
+            // signature, per-record originator signature, principalId == `from`) — the
+            // ENVELOPE's own signature + contentHash (relay-lib.ts verifyMessageSignature)
+            // NEVER runs on this merge path. Correct for S1 (nothing pushes Message).
+            // But the FIRST hub that pushes Message would merge unverified envelope
+            // content silently: S2 MUST add envelope verification here (or an explicit
+            // trust delegation to the originator's send-time check) alongside adding
+            // Message to the push list — do not inherit this as a silent gap.
+            Message: databases.flair.Message,
         };
         const knownTables = new Set(Object.keys(tableMap));
         for (const record of records) {
@@ -454,10 +496,48 @@ export class FederationSync extends Resource {
                     continue;
                 }
                 const mergedData = mergeRecord(local, record);
+                // ── flair#1542: skills are not federated ──
+                // A skill-tagged Memory is a local, gated artifact (SkillScan + forced
+                // durability on the write path). Merging a pushed skill-tagged row RAW
+                // would land an unscanned, possibly non-persistent skill — bypassing the
+                // gate. Skip it: skills are written locally via skill_store, never synced.
+                if (record.table === "Memory" && isSkillWrite(mergedData)) {
+                    recordSkip("skill_not_federated");
+                    continue;
+                }
+                // Absorbing-state guard for the Message table (flair#1521 §12 P0-3).
+                // Generic newer-wins LWW would let a deadline-sweep `failed` (or any
+                // other state) written on a peer overwrite a locally-CONSUMED message,
+                // telling the sender "failed" about a message the recipient actually
+                // consumed — the exact inversion Relay exists to kill. `consumed` is
+                // absorbing: reconcileState pins it regardless of updatedAt. The guard
+                // lives HERE, in the raw-put apply path, because sync-in bypasses the
+                // Message resource's methods (Federation.ts uses table.put directly).
+                if (record.table === "Message") {
+                    const reconciled = reconcileState(local?.state, mergedData.state);
+                    mergedData.state = reconciled;
+                    // P1-3 (flair#1521): reconcile the SATELLITE lifecycle fields too, not
+                    // just `state`. Generic LWW keeps the incoming (newer) record's
+                    // failureReason/consumedAt, so a locally-CONSUMED row could end up
+                    // `consumed` while carrying a remote `failureReason: "deadline"` — the
+                    // sender-visible "failed" about a message the recipient actually
+                    // consumed, the exact inversion the absorbing rule exists to kill. A
+                    // consumed row NEVER has a failureReason; keep the consumed row's own
+                    // consumedAt (local's when local was the consumer).
+                    if (reconciled === "consumed") {
+                        mergedData.failureReason = null;
+                        mergedData.consumedAt = local?.consumedAt ?? mergedData.consumedAt ?? null;
+                    }
+                }
                 mergedData._originatorInstanceId = decision.originator;
                 mergedData._syncedFrom = instanceId;
                 mergedData._syncedAt = new Date().toISOString();
                 await table.put(mergedData);
+                // embedding-space-guard slice 1: a federation-merged Memory can carry a
+                // FOREIGN embeddingModel (LWW remote-win) — trip the guard's latch so
+                // recall/dedup degrade instead of cosining a foreign vector. See
+                // noteFederationMergedMemory's doc.
+                noteFederationMergedMemory(record.table, mergedData);
                 merged++;
             }
             catch (err) {

package/dist/resources/Integration.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -89,7 +90,18 @@ export class Integration extends databases.flair.Integration {
         }
         return super.post(content, context);
     }
+    // PATCH routes past put(), so agentId immutability is enforced on both verbs
+    // via the one shared delegate.
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content, context) {
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (__ownerDenial)
+            return __ownerDenial;
         const auth = await this._auth();
         if (auth.kind === "anonymous")
             return UNAUTH();