@sema-agent/core 5.21.0 → 5.22.0

package/dist/core/permission-rule-store.js

@@ -1,5 +1,8 @@
 import { canonicalize } from "./canonical-json.js";
-import { isRuleLive } from "./permission-rule-model.js";
+import { isRuleLive, parseAllowRuleText } from "./permission-rule-model.js";
+export function sameRuleOwner(a, b) {
+    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
+}
 export const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
 export function writerOf(store) {
     const w = store[PERMISSION_RULE_WRITER];
@@ -43,6 +46,280 @@ export function assertDeleteDeltaCarriesNoAdd(delta) {
         throw new Error("a tighten-delete must carry a tombstone naming at least one observed add dot");
     }
 }
+function isValidScope(scope) {
+    const sc = scope;
+    return sc?.kind === "global" || (sc?.kind === "project" && typeof sc.root === "string" && sc.root !== "");
+}
+function isValidDot(dot) {
+    const d = dot;
+    return typeof d?.actor === "string" && d.actor !== "" && typeof d.counter === "number" && Number.isFinite(d.counter);
+}
+function scopeKey(scope) {
+    return JSON.stringify(scope.kind === "global" ? ["g"] : ["p", scope.root]);
+}
+function dotKey(dot) {
+    return JSON.stringify([dot.actor, dot.counter]);
+}
+function ruleIdentityKey(rule, scope) {
+    return JSON.stringify([rule, scopeKey(scope)]);
+}
+function compareDots(a, b) {
+    return a.actor < b.actor ? -1 : a.actor > b.actor ? 1 : a.counter - b.counter;
+}
+export function dotAtOrBelowFrontier(dot, frontier) {
+    const cap = frontier[dot.actor];
+    return typeof cap === "number" && Number.isFinite(cap) && dot.counter <= cap;
+}
+export function ruleSyncVector(state) {
+    const out = {};
+    const feed = (dot) => {
+        const cur = out[dot.actor];
+        if (cur === undefined || dot.counter > cur)
+            out[dot.actor] = dot.counter;
+    };
+    for (const r of state.rules)
+        for (const a of r.adds)
+            feed(a.dot);
+    for (const t of state.tombstones) {
+        feed(t.deletedBy);
+        for (const d of t.removedDots)
+            feed(d);
+    }
+    return out;
+}
+export function joinFrontiers(a, b) {
+    const out = { ...a };
+    for (const [actor, counter] of Object.entries(b)) {
+        const cur = out[actor];
+        if (cur === undefined || counter > cur)
+            out[actor] = counter;
+    }
+    return out;
+}
+export function normalizePersistedRule(r) {
+    const parsed = parseAllowRuleText(r.rule);
+    if ("reject" in parsed)
+        return { reject: "invalid_rule_text" };
+    const p = parsed.rule;
+    if (p.rule !== r.rule)
+        return { reject: "invalid_rule_text" };
+    if (r.tool !== p.tool || r.match !== p.match || r.command !== p.command)
+        return { reject: "metadata_mismatch" };
+    return { rule: r };
+}
+export function screenRuleSyncState(state) {
+    const rejected = [];
+    const rules = [];
+    for (const r of state.rules) {
+        if (!Array.isArray(r.adds) || r.adds.length === 0)
+            continue;
+        const n = normalizePersistedRule(r);
+        if ("reject" in n) {
+            for (const a of r.adds)
+                rejected.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: n.reject });
+            continue;
+        }
+        rules.push(r);
+    }
+    return { state: { rules, tombstones: state.tombstones }, rejected };
+}
+export function joinRuleStates(a, b) {
+    const sa = screenRuleSyncState(a).state;
+    const sb = screenRuleSyncState(b).state;
+    const ruleGroups = new Map();
+    for (const r of [...sa.rules, ...sb.rules]) {
+        const key = ruleIdentityKey(r.rule, r.scope);
+        const existing = ruleGroups.get(key);
+        if (existing === undefined) {
+            ruleGroups.set(key, { ...r, adds: [...r.adds] });
+            continue;
+        }
+        for (const add of r.adds) {
+            const i = existing.adds.findIndex((x) => sameDot(x.dot, add.dot));
+            if (i === -1)
+                existing.adds.push({ ...add });
+            else if (canonicalize(add) < canonicalize(existing.adds[i]))
+                existing.adds[i] = { ...add };
+        }
+    }
+    const rules = [...ruleGroups.values()]
+        .map((r) => ({ ...r, adds: [...r.adds].sort((x, y) => compareDots(x.dot, y.dot)) }))
+        .sort((x, y) => (x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : scopeKey(x.scope) < scopeKey(y.scope) ? -1 : scopeKey(x.scope) > scopeKey(y.scope) ? 1 : 0));
+    const tombGroups = new Map();
+    for (const t of [...sa.tombstones, ...sb.tombstones]) {
+        if (!Array.isArray(t.removedDots) || t.removedDots.length === 0)
+            continue;
+        const key = JSON.stringify([t.rule, scopeKey(t.scope), dotKey(t.deletedBy)]);
+        const existing = tombGroups.get(key);
+        if (existing === undefined) {
+            tombGroups.set(key, { ...t, removedDots: [...t.removedDots] });
+            continue;
+        }
+        for (const d of t.removedDots)
+            if (!existing.removedDots.some((x) => sameDot(x, d)))
+                existing.removedDots.push(d);
+    }
+    const tombstones = [...tombGroups.values()]
+        .map((t) => ({ ...t, removedDots: [...t.removedDots].sort(compareDots) }))
+        .sort((x, y) => x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : scopeKey(x.scope) < scopeKey(y.scope) ? -1 : scopeKey(x.scope) > scopeKey(y.scope) ? 1 : compareDots(x.deletedBy, y.deletedBy));
+    return { rules, tombstones };
+}
+export function collectBelowFrontier(state, frontier) {
+    const collectable = state.tombstones.filter((t) => dotAtOrBelowFrontier(t.deletedBy, frontier) && t.removedDots.every((d) => dotAtOrBelowFrontier(d, frontier)));
+    if (collectable.length === 0)
+        return { state, collectedTombstones: 0 };
+    const keep = state.tombstones.filter((t) => !collectable.includes(t));
+    const rules = state.rules
+        .map((r) => {
+        const covered = collectable.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        return covered.length === 0 ? r : { ...r, adds: r.adds.filter((a) => !covered.some((d) => sameDot(d, a.dot))) };
+    })
+        .filter((r) => r.adds.length > 0);
+    return { state: { rules, tombstones: keep }, collectedTombstones: collectable.length };
+}
+export function applySyncJoin(cur, delta, nowMs) {
+    if (delta.kind !== "sync-join" || delta.inbound === null || typeof delta.inbound !== "object" || !Array.isArray(delta.inbound.rules) || !Array.isArray(delta.inbound.tombstones)) {
+        throw new Error("a sync-join delta must carry an inbound state with rules and tombstones arrays");
+    }
+    for (const t of delta.inbound.tombstones) {
+        if (!Array.isArray(t?.removedDots) || t.removedDots.length === 0) {
+            throw new Error("an inbound tombstone must name at least one observed add dot — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)");
+        }
+        if (!isValidScope(t.scope) || !isValidDot(t.deletedBy) || !t.removedDots.every(isValidDot)) {
+            throw new Error("an inbound tombstone carries a malformed scope or dot — refusing the whole sync-join (a tombstone that cannot identity-match what it deletes would land its covered adds live)");
+        }
+        const canonicalTomb = parseAllowRuleText(t.rule);
+        if ("reject" in canonicalTomb || canonicalTomb.rule.rule !== t.rule) {
+            throw new Error(`an inbound tombstone names a non-canonical or invalid rule text ("${t.rule}") — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)`);
+        }
+    }
+    const droppedInbound = [];
+    const quarantinedNow = [];
+    const screened = screenRuleSyncState(delta.inbound);
+    droppedInbound.push(...screened.rejected);
+    const forgedDot = (dot) => dot.actor === cur.actor && dot.counter > cur.counter;
+    const dotIdentity = new Map();
+    for (const r of cur.rules)
+        for (const a of r.adds)
+            dotIdentity.set(dotKey(a.dot), ruleIdentityKey(r.rule, r.scope));
+    for (const q of cur.quarantined)
+        dotIdentity.set(dotKey(q.add.dot), ruleIdentityKey(q.rule, q.scope));
+    const inboundClaims = new Map();
+    for (const r of screened.state.rules) {
+        const identity = ruleIdentityKey(r.rule, r.scope);
+        for (const a of r.adds) {
+            const claims = inboundClaims.get(dotKey(a.dot)) ?? new Set();
+            claims.add(identity);
+            inboundClaims.set(dotKey(a.dot), claims);
+        }
+    }
+    const inboundTombstones = screened.state.tombstones.filter((t) => {
+        const forged = forgedDot(t.deletedBy) ? t.deletedBy : t.removedDots.find(forgedDot);
+        if (forged === undefined)
+            return true;
+        droppedInbound.push({ rule: t.rule, scope: t.scope, dot: forged, reason: "own_actor_forged" });
+        return false;
+    });
+    const tombstoneRejected = inboundTombstones.length !== screened.state.tombstones.length;
+    let withheldAdds = 0;
+    const inboundRules = [];
+    for (const r of screened.state.rules) {
+        if (tombstoneRejected) {
+            withheldAdds += r.adds.length;
+            continue;
+        }
+        if (!isValidScope(r.scope)) {
+            for (const a of r.adds)
+                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
+            continue;
+        }
+        const identity = ruleIdentityKey(r.rule, r.scope);
+        const kept = r.adds.filter((a) => {
+            if (!isValidDot(a.dot)) {
+                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
+                return false;
+            }
+            if (forgedDot(a.dot)) {
+                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "own_actor_forged" });
+                return false;
+            }
+            const known = dotIdentity.get(dotKey(a.dot));
+            if ((known !== undefined && known !== identity) || (inboundClaims.get(dotKey(a.dot))?.size ?? 0) > 1) {
+                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "dot_identity_conflict" });
+                return false;
+            }
+            return true;
+        });
+        if (kept.length > 0)
+            inboundRules.push({ ...r, adds: kept });
+    }
+    const inbound = { rules: inboundRules, tombstones: inboundTombstones };
+    const localScreen = screenRuleSyncState({ rules: cur.rules, tombstones: cur.tombstones });
+    const quarantined = [...cur.quarantined];
+    const quarantineKey = (rule, scope, dot) => JSON.stringify([rule, scopeKey(scope), dotKey(dot)]);
+    const pushQuarantine = (rule, scope, add, reason) => {
+        if (quarantined.some((q) => q.rule === rule && sameScope(q.scope, scope) && sameDot(q.add.dot, add.dot)))
+            return;
+        quarantined.push({ rule, scope, add, reason, atMs: nowMs });
+        quarantinedNow.push({ rule, scope, dot: add.dot, reason });
+    };
+    for (const rej of localScreen.rejected) {
+        const row = cur.rules.find((r) => r.rule === rej.rule && sameScope(r.scope, rej.scope));
+        const add = row?.adds.find((a) => sameDot(a.dot, rej.dot));
+        if (add !== undefined && (rej.reason === "invalid_rule_text" || rej.reason === "metadata_mismatch")) {
+            pushQuarantine(rej.rule, rej.scope, add, rej.reason);
+        }
+    }
+    let joined = joinRuleStates(localScreen.state, inbound);
+    let collectedTombstones = 0;
+    if (delta.gcFrontier !== undefined) {
+        const collected = collectBelowFrontier(joined, delta.gcFrontier);
+        joined = collected.state;
+        collectedTombstones = collected.collectedTombstones;
+        const inboundDots = new Set(inbound.rules.flatMap((r) => r.adds.map((a) => dotKey(a.dot))));
+        const live = applyTombstones(joined.rules, joined.tombstones);
+        for (const r of live) {
+            for (const a of r.adds) {
+                if (dotAtOrBelowFrontier(a.dot, delta.gcFrontier) && !inboundDots.has(dotKey(a.dot))) {
+                    pushQuarantine(r.rule, r.scope, a, "below_gc_frontier");
+                }
+            }
+        }
+    }
+    for (const q of delta.quarantine ?? []) {
+        for (const dot of q.dots) {
+            if (joined.tombstones.some((t) => sameDot(t.deletedBy, dot))) {
+                throw new Error("a quarantine instruction may not touch a tombstone — it moves adds only");
+            }
+            const row = joined.rules.find((r) => r.rule === q.rule && sameScope(r.scope, q.scope));
+            const add = row?.adds.find((a) => sameDot(a.dot, dot));
+            if (add === undefined)
+                continue;
+            pushQuarantine(q.rule, q.scope, add, q.reason);
+        }
+    }
+    const quarantinedRows = new Set(quarantined.map((q) => quarantineKey(q.rule, q.scope, q.add.dot)));
+    const rules = joined.rules
+        .map((r) => ({ ...r, adds: r.adds.filter((a) => !quarantinedRows.has(quarantineKey(r.rule, r.scope, a.dot))) }))
+        .filter((r) => r.adds.length > 0);
+    return {
+        next: {
+            actor: cur.actor,
+            counter: cur.counter,
+            rules,
+            tombstones: joined.tombstones,
+            quarantined,
+            observedVector: delta.observedVector !== undefined ? joinFrontiers(cur.observedVector ?? {}, delta.observedVector) : cur.observedVector,
+        },
+        report: { droppedInbound, quarantined: quarantinedNow, collectedTombstones, withheldAdds },
+    };
+}
+export function assertRedemptionNotQuarantined(quarantined, delta) {
+    const hit = quarantined.find((q) => sameDot(q.add.dot, delta.add.dot));
+    if (hit !== undefined) {
+        throw new Error(`this approval's add (dot ${delta.add.dot.actor}#${delta.add.dot.counter}) was quarantined (${hit.reason}) — replaying the old record cannot revive it; a new consent (a new ask, a new record, a new dot) is required`);
+    }
+}
 export async function ruleStoreChecksum(payload) {
     const { createHash } = await import("node:crypto");
     return `sha256:${createHash("sha256").update(canonicalize(payload), "utf8").digest("hex")}`;
@@ -110,14 +387,18 @@ export const EMPTY_RULE_STORE = {
 };
 export class InMemoryPermissionRuleStore {
     actor;
+    now;
     durability = "process-local";
     fidelity = "structured-clone";
     rules = [];
     tombstones = [];
+    quarantinedRows = [];
+    observedVector;
     rev = 0;
     counter = 0;
-    constructor(actor = `mem-${Math.random().toString(36).slice(2, 10)}`) {
+    constructor(actor = `mem-${Math.random().toString(36).slice(2, 10)}`, now = Date.now) {
         this.actor = actor;
+        this.now = now;
     }
     async list() {
         return {
@@ -126,18 +407,47 @@ export class InMemoryPermissionRuleStore {
             rev: this.rev,
         };
     }
+    async quarantined() {
+        return structuredClone(this.quarantinedRows);
+    }
     [PERMISSION_RULE_WRITER] = {
         nextDot: async () => ({ actor: this.actor, counter: ++this.counter }),
+        readRaw: async () => structuredClone({
+            actor: this.actor,
+            counter: this.counter,
+            rev: this.rev,
+            rules: this.rules,
+            tombstones: this.tombstones,
+            ...(this.observedVector !== undefined ? { observedVector: this.observedVector } : {}),
+            quarantined: this.quarantinedRows,
+        }),
         apply: async (delta, opts) => {
             if (opts.expectedRev !== this.rev)
                 return { conflict: true, rev: this.rev };
             if (delta.kind === "redemption-add") {
+                assertRedemptionNotQuarantined(this.quarantinedRows, delta);
                 this.rules = foldDelta(this.rules, delta);
             }
-            else {
+            else if (delta.kind === "tighten-delete") {
                 assertDeleteDeltaCarriesNoAdd(delta);
                 this.tombstones = [...this.tombstones, delta.tombstone];
             }
+            else {
+                const { next, report } = applySyncJoin({
+                    actor: this.actor,
+                    counter: this.counter,
+                    rules: this.rules,
+                    tombstones: this.tombstones,
+                    quarantined: this.quarantinedRows,
+                    ...(this.observedVector !== undefined ? { observedVector: this.observedVector } : {}),
+                }, delta, this.now());
+                this.rules = next.rules;
+                this.tombstones = next.tombstones;
+                this.quarantinedRows = next.quarantined;
+                this.observedVector = next.observedVector;
+                this.rev += 1;
+                return { rev: this.rev, sync: report };
+            }
             this.rev += 1;
             return { rev: this.rev };
         },

package/dist/core/permission-rule-sync.d.ts

@@ -0,0 +1,131 @@
+/**
+ * design/182 §4 — the cloud-sync client for persisted allow rules.
+ *
+ * One round = one RTT, full state both directions. The data model is already a state CRDT (OR-Set:
+ * per-add dots + observed-remove tombstones), so sync is the JOIN of two states — no cursors, no
+ * baselines, no three-way reconcile, and the whole cursor-retention/prefill/echo family of defenses the
+ * memory sync face carries is structurally absent here (a registered, deliberate divergence). What IS
+ * inherited from that face is the contract style: an injected transport (core bundles no fetch), the
+ * transport running BEFORE any local write (a throw aborts the round with zero local effects), a
+ * picked-not-spread response parse, and a pure join both ends share.
+ *
+ * The safety polarity is the opposite of memory's: a memory sync bug loses data; a rule sync bug
+ * WIDENS what runs without asking. Every ambiguous call here therefore resolves toward the tightening
+ * side — the tighten-only partial application (§4.3), the frontier fence (§5.2), and the rule that a
+ * LOCAL row only ever leaves the live view through an explicit, disclosed quarantine instruction.
+ *
+ * ## Trust domain (stated, not defended against)
+ *
+ * Connecting a principal's store to a sync endpoint merges that principal's devices, the server and
+ * every device's transport into ONE consent trust domain: any compromised member can mint persisting
+ * allow rules for the whole domain (an injected add rides the next full-state exchange everywhere).
+ * Per-add provenance keeps the minting replica auditable, resurrection/landing disclosures keep changes
+ * visible, and the single validator still refuses every illegal SHAPE from the wire — but the
+ * "one human click behind every add" guarantee is domain-level, not device-level, until the
+ * privilege-separation ticket adds device-bound signatures. Deployments should connect knowing which
+ * level they are buying.
+ */
+import type { PersistedAllowRule, RuleDot, RuleScope, RuleTombstone } from "./permission-rule-model.js";
+import type { PermissionRuleStoreProvider, RuleOwner, RuleSyncDrop, RuleSyncFrontier, RuleSyncState } from "./permission-rule-store.js";
+/** The injected HTTP seam — core never bundles a fetch. The deployment owns base URL, auth, TLS and
+ *  retries; a non-2xx / network failure should THROW (the round then aborts with zero local effects —
+ *  the transport runs before any local write). */
+export type PermissionRuleSyncTransport = (path: string, body: unknown) => Promise<unknown>;
+/** The one wire path of this protocol. */
+export declare const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
+/** The wire request: the local raw state, whole. `replica` is this store's actor id — an observation /
+ *  frontier-accounting fact, NEVER an identity input; `principal` is an envelope echo — authentication
+ *  lives on the transport's authenticated channel, and the server must never trust this field. */
+export interface RuleSyncRequestBody {
+    principal: string;
+    replica: string;
+    state: RuleSyncState;
+    observedVector?: RuleSyncFrontier;
+}
+/** The wire response (server twin: join its persisted state with the request state, answer the whole
+ *  merged form). `gcFrontier` is the COLLECTED watermark (§5.1) — absent in v2.0 by protocol. */
+export interface RuleSyncResponseBody {
+    principal: string;
+    merged: RuleSyncState;
+    gcFrontier?: RuleSyncFrontier;
+    dropped?: Array<{
+        rule: string;
+        scope: RuleScope;
+        dot: RuleDot;
+        reason: string;
+    }>;
+}
+export interface PermissionRuleSyncResult {
+    /** True ⟺ the round landed with zero drops, zero quarantines and zero warnings. */
+    ok: boolean;
+    /** Local set sizes at push time (full-state protocol: the wire carries the whole set). */
+    pushed: {
+        addDots: number;
+        tombstones: number;
+    };
+    /** What the landing added relative to the local pre-state. */
+    landed: {
+        newAdds: number;
+        newTombstones: number;
+    };
+    /** (rule, scope) pairs that went removed → live in this round — add-wins made visible (§4.6). */
+    resurrected: Array<{
+        rule: string;
+        scope: RuleScope;
+        byDot: RuleDot;
+    }>;
+    /** Inbound refusals and local quarantine moves, typed (closed reason set, governance-codes family). */
+    dropped: RuleSyncDrop[];
+    /** The store revision after landing (the pre-round revision when nothing landed). */
+    rev: number;
+    /** Honest disclosures for tolerated protocol irregularities (withheld adds, unshapeable entries…). */
+    warnings?: string[];
+}
+/** A typed, DISCRIMINABLE refusal: a local-owner bucket has no cloud home until it is adopted. Distinct
+ *  by `code` from a missing principal, so "not signed in" and "this bucket cannot sync" never collapse
+ *  into one indistinguishable failure shape. */
+export declare const LOCAL_OWNER_UNSYNCABLE_CODE = "permission_rules.local_owner_unsyncable";
+/**
+ * Run one sync round for one principal's bucket.
+ *
+ * Order of operations is the contract: read raw → transport (no local write yet; a throw aborts with
+ * zero local effects) → validate the response (picked-not-spread; principal echo mismatch throws) →
+ * partition tighten-only (§4.3) → land the WHOLE round as ONE `sync-join` delta under optimistic
+ * concurrency — a conflict re-reads and RE-JOINS (the join's commutativity/idempotence makes the
+ * recompute correct by construction; adds and tombstones that landed during the RTT survive it).
+ */
+export declare function syncPermissionRules(opts: {
+    provider: PermissionRuleStoreProvider;
+    principal: string;
+    /** Accepted only as `kind: "principal"` (and it must agree with `principal`). A local-owner value is
+     *  refused with the typed {@link LOCAL_OWNER_UNSYNCABLE_CODE} error — see design/182 §4.5. */
+    owner?: RuleOwner;
+    transport: PermissionRuleSyncTransport;
+    /** Injected clock — observation timestamps only, never adjudication input. */
+    now?: () => number;
+}): Promise<PermissionRuleSyncResult>;
+interface ParsedRuleSyncResponse {
+    principal: string;
+    merged: {
+        rules: PersistedAllowRule[];
+        tombstones: Array<RuleTombstone | undefined>;
+    };
+    gcFrontier?: RuleSyncFrontier;
+    dropped: Array<{
+        rule: string;
+        scope: RuleScope;
+        dot: RuleDot;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+/**
+ * Parse one wire response. Envelope violations (missing/mistyped principal, echo mismatch, no merged
+ * state, an unparseable frontier) THROW — a protocol error aborts the round with zero local effects.
+ * ENTRY-level violations degrade per §4.3: an unshapeable rule/add is skipped with a warning (it never
+ * reaches the local disk); an unshapeable tombstone is surfaced as `undefined` so the caller's
+ * tighten-only partitioning withholds the round's adds. Unknown keys never flow anywhere — every field
+ * below is PICKED off the response, the object itself is discarded.
+ */
+export declare function parseRuleSyncResponse(raw: unknown, expectedPrincipal: string): ParsedRuleSyncResponse;
+export {};