@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/resources/Relationship.js

@@ -1,7 +1,11 @@
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { localInstanceId } from "./instance-identity.js";
+import { buildProvenance } from "./provenance.js";
 const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 /**
  * Relationship resource — entity-to-entity relationships with temporal validity.
  *
@@ -16,7 +20,7 @@ const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { s
 export class Relationship extends databases.flair.Relationship {
     /**
      * 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). Closes the same P0 leak: Harper routes
      * `GET /Relationship/<id>` to get() and the collection describe
      * (`GET /Relationship`) outside search(), so neither was gated before this
@@ -85,18 +89,73 @@ export class Relationship extends databases.flair.Relationship {
             operator: "and",
         });
     }
+    /**
+     * ─── Auth reconcile (relationship-write-path, folded K&S refinement) ──────
+     *
+     * Upgraded from the older `request.tpsAgent`-direct pattern to
+     * `resolveAgentAuth` — matching Memory.post()/put() — so this write path
+     * gets the SAME three-way verdict handling (anonymous denied, verified
+     * agent stamped from the SIGNATURE never the body, internal/admin
+     * unfiltered) instead of a parallel, easy-to-drift auth mechanism. K&S both
+     * flagged this as a real divergence (the previous code had no
+     * internal/admin verdict paths at all — see the doc below for why that
+     * never actually bit anyone in practice, but was still the wrong shape to
+     * build the new ergonomic write surfaces on top of).
+     *
+     * - `anonymous` → 401, same as before.
+     * - `agent` + non-admin: a body-supplied `agentId` that MISMATCHES the
+     *   verified identity is rejected outright (403) rather than silently
+     *   overwritten — a clearer signal than Memory.post()'s "validate, don't
+     *   stamp" idiom. `content.agentId` is then ALWAYS set from `auth.agentId`
+     *   (never left as whatever the body claimed, even when it already
+     *   matched) — the non-negotiable "agentId comes from the verdict, never
+     *   the body" rule, applied unconditionally rather than only on mismatch.
+     * - `agent` + admin: `content.agentId` passes through UNFILTERED, matching
+     *   the existing admin-bypass idiom already used by get()/search()/
+     *   delete() below (an admin/migration tool may legitimately write on
+     *   another agent's behalf).
+     * - `internal` (no HTTP request at all — a trusted in-process call):
+     *   `content.agentId` also passes through unchanged. No in-process
+     *   Relationship writer exists today (openclaw's integration writes via a
+     *   real signed HTTP PUT, landing on the `agent` branch above), so this is
+     *   forward-looking parity with Memory.post()/put() rather than a path
+     *   this PR's callers actually exercise — but it closes the SAME latent gap
+     *   the old code had: `request?.tpsAgent` was falsy for BOTH an anonymous
+     *   HTTP caller and a true internal call, so an internal caller would have
+     *   been wrongly 401'd too. resolveAgentAuth distinguishes the two.
+     */
     async put(content) {
         const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const authAgent = request?.tpsAgent;
-        if (!authAgent) {
-            return new Response(JSON.stringify({ error: "authentication required" }), {
-                status: 401, headers: { "content-type": "application/json" },
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous") {
+            return UNAUTH();
+        }
+        if (auth.kind === "agent") {
+            if (!auth.isAdmin) {
+                if (content?.agentId && content.agentId !== auth.agentId) {
+                    return FORBIDDEN("cannot write a relationship owned by another agent");
+                }
+                content.agentId = auth.agentId;
+            }
+            // admin: content.agentId left as provided (unfiltered) — see doc above.
+        }
+        // internal: content.agentId left as provided (unfiltered) — see doc above.
+        if (!content.agentId || typeof content.agentId !== "string") {
+            return new Response(JSON.stringify({ error: "agentId is required" }), {
+                status: 400, headers: { "content-type": "application/json" },
             });
         }
-        const rl = checkRateLimit(authAgent);
-        if (!rl.allowed)
-            return rateLimitResponse(rl.retryAfterMs, "relationship");
+        // Rate limit keyed on the RESOLVED agentId (never a client-supplied one)
+        // — matches Memory.post()'s intent, extended to cover every
+        // resolveAgentAuth path (credentialed super_user, verifyAgentRequest
+        // fallback), not just the gate's own `tpsAgent` annotation. Internal
+        // calls have no per-agent identity to key on and are trusted, so they're
+        // exempt — same as Memory.post()'s `if (authenticatedAgent)` guard.
+        if (auth.kind === "agent") {
+            const rl = checkRateLimit(auth.agentId);
+            if (!rl.allowed)
+                return rateLimitResponse(rl.retryAfterMs, "relationship");
+        }
         // Validate required fields
         if (!content.subject || typeof content.subject !== "string") {
             return new Response(JSON.stringify({ error: "subject is required (string)" }), {
@@ -113,9 +172,9 @@ export class Relationship extends databases.flair.Relationship {
                 status: 400, headers: { "content-type": "application/json" },
             });
         }
-        // Normalize
+        // Normalize — lowercasing is load-bearing: MemoryBootstrap.ts's attention
+        // read matches lowercased predicted subjects against subject/object.
         const now = new Date().toISOString();
-        content.agentId = authAgent;
         content.subject = content.subject.toLowerCase();
         content.predicate = content.predicate.toLowerCase();
         content.object = content.object.toLowerCase();
@@ -124,26 +183,49 @@ export class Relationship extends databases.flair.Relationship {
         content.validFrom = content.validFrom || now;
         // validTo left as null/undefined for active relationships
         content.confidence = content.confidence ?? 1.0;
+        // Write-time provenance stamp (relationship-write-path, folded K&S
+        // refinement) — reuses Memory's buildProvenance EXACTLY (./provenance.ts),
+        // same `{v, verified, claimed?}` shape, no Relationship-specific format.
+        // Additive/nullable on the schema side (schemas/memory.graphql) — a
+        // pre-existing row with no provenance field reads back `undefined`,
+        // unchanged behavior (migration-equivalence gate).
+        content.provenance = buildProvenance(auth, content.createdAt, content);
+        // 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.put(content);
     }
+    /**
+     * Same auth reconcile as put() above — resolveAgentAuth replaces the
+     * `request.tpsAgent`-direct pattern. K&S both independently caught that
+     * delete() had the identical divergence the spec text only named on
+     * put(): anonymous and true-internal calls were indistinguishable (both
+     * read as a falsy `authAgent`), and there was no admin/internal verdict
+     * handling. Ownership-check logic (own-agent-or-admin) is otherwise
+     * unchanged — see test/integration/relationship-delete-authz.test.ts's doc
+     * comment for why calling `super.get()` with no target argument still
+     * resolves the URL-bound target record (a Harper Table-resource
+     * invariant), not an empty/collection result.
+     */
     async delete(_) {
         const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const authAgent = request?.tpsAgent;
-        const isAdminAgent = request?.tpsAgentIsAdmin ?? false;
-        if (!authAgent) {
-            return new Response(JSON.stringify({ error: "authentication required" }), {
-                status: 401, headers: { "content-type": "application/json" },
-            });
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous") {
+            return UNAUTH();
         }
-        // Non-admin: verify ownership before delete
-        if (!isAdminAgent) {
-            const existing = await super.get();
-            if (existing?.agentId && existing.agentId !== authAgent) {
-                return new Response(JSON.stringify({ error: "cannot delete another agent's relationship" }), {
-                    status: 403, headers: { "content-type": "application/json" },
-                });
-            }
+        // Trusted internal call or admin agent — unfiltered, unchanged behavior.
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+            return super.delete(_);
+        }
+        // Non-admin agent: verify ownership before delete.
+        const existing = await super.get();
+        if (existing?.agentId && existing.agentId !== auth.agentId) {
+            return FORBIDDEN("cannot delete another agent's relationship");
         }
         return super.delete(_);
     }