@int-loop/core 0.1.0 → 0.3.0

package/dist/anchor.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import type { LedgerEntry } from "./schema/ledger.ts";
+import type { VerificationFailure } from "./verify.ts";
+export declare const ANCHOR_LEAF_TYPE = "int-loop.anchor-leaf/1";
+export declare const AnchorTimestamp: z.ZodObject<{
+    tsa: z.ZodString;
+    token: z.ZodString;
+    gen_time: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AnchorTimestamp = z.infer<typeof AnchorTimestamp>;
+export declare const AnchorCreatedPayload: z.ZodObject<{
+    anchored: z.ZodObject<{
+        seq: z.ZodNumber;
+        entry_hash: z.ZodString;
+    }, z.core.$strict>;
+    merkle: z.ZodObject<{
+        root: z.ZodString;
+        leaf_index: z.ZodNumber;
+        tree_size: z.ZodNumber;
+        path: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    timestamps: z.ZodArray<z.ZodObject<{
+        tsa: z.ZodString;
+        token: z.ZodString;
+        gen_time: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AnchorCreatedPayload = z.infer<typeof AnchorCreatedPayload>;
+export type AnchorLeaf = {
+    tenant_id: string;
+    seq: number;
+    entry_hash: string;
+};
+export declare const AnchorLeafSchema: z.ZodObject<{
+    tenant_id: z.ZodString;
+    seq: z.ZodNumber;
+    entry_hash: z.ZodString;
+}, z.core.$strict>;
+export declare function anchorLeafHash(leaf: AnchorLeaf): Promise<Uint8Array<ArrayBuffer>>;
+export declare function merkleRoot(leafHashes: readonly Uint8Array[]): Promise<Uint8Array<ArrayBuffer>>;
+/** The inclusion path for leaf `index`, nearest sibling first. */
+export declare function merklePath(leafHashes: readonly Uint8Array[], index: number): Promise<Uint8Array<ArrayBuffer>[]>;
+/** Recomputes the root from a leaf and its path (RFC 9162 2.1.3.2), or null if the path does not fit the tree. */
+export declare function rootFromPath(leafHash: Uint8Array, index: number, size: number, path: readonly Uint8Array[]): Promise<Uint8Array | null>;
+/**
+ * The tree for one anchoring round: one leaf per tenant, in tenant order. Returns the root
+ * to stamp, and each tenant's anchor.created payload once the stamps are in.
+ */
+export declare function anchorTree(leaves: readonly AnchorLeaf[]): Promise<{
+    root: Uint8Array<ArrayBuffer>;
+    payload: (tenantId: string, timestamps: AnchorTimestamp[]) => Promise<AnchorCreatedPayload>;
+}>;
+/** How far a TSA's clock may disagree with int-loop's before the verifier objects. */
+export declare const ANCHOR_CLOCK_TOLERANCE_MS: number;
+export type AnchorReport = {
+    anchors_checked: number;
+    /** The newest anchored entry and the earliest time a TSA vouches it existed. */
+    anchored_through: {
+        seq: number;
+        gen_time: string;
+        tsas: string[];
+    } | null;
+    failures: VerificationFailure[];
+};
+/**
+ * Checks every anchor.created entry: the anchored entry is in the ledger with that hash,
+ * its leaf leads to the stamped root, and every timestamp token verifies against `roots`
+ * for that root, at a time consistent with when the entries were recorded.
+ */
+export declare function verifyAnchors(entries: readonly LedgerEntry[], roots: readonly Uint8Array[]): Promise<AnchorReport>;

package/dist/anchor.js

@@ -0,0 +1,201 @@
+// Anchoring: once an hour, each tenant's latest ledger entry is timestamped by
+// independent RFC 3161 timestamp authorities, so not even int-loop can rewrite
+// history afterwards without it showing.
+//
+// One stamp covers every tenant. The heads are the leaves of a Merkle tree (RFC 9162
+// hashing, domain-separated leaves and nodes); the TSAs stamp the root, and each
+// tenant's anchor.created entry records its own leaf's path to that root. A tenant's
+// evidence pack therefore proves its own chain head existed at the stamped time and
+// reveals nothing about other tenants beyond opaque sibling hashes.
+import { z } from "zod";
+import { canonicalise } from "./jcs.js";
+import { concatBytes, fromBase64Url, fromHex, sha256, toHex, utf8 } from "./hash.js";
+import { Base64Url, Sha256Hex, TenantId, Timestamp } from "./schema/common.js";
+import { verifyTimestampToken } from "./tsp.js";
+export const ANCHOR_LEAF_TYPE = "int-loop.anchor-leaf/1";
+export const AnchorTimestamp = z.strictObject({
+    /** Which TSA, e.g. "freetsa". Informational: trust comes from the token's certificate chain. */
+    tsa: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),
+    /** The DER TimeStampToken. */
+    token: Base64Url,
+    /** The time inside the token, repeated for readers; the verifier checks they agree. */
+    gen_time: Timestamp,
+});
+export const AnchorCreatedPayload = z.strictObject({
+    anchored: z.strictObject({ seq: z.number().int().positive(), entry_hash: Sha256Hex }),
+    merkle: z.strictObject({
+        root: Sha256Hex,
+        leaf_index: z.number().int().nonnegative(),
+        tree_size: z.number().int().positive(),
+        path: z.array(Sha256Hex).max(64),
+    }),
+    timestamps: z.array(AnchorTimestamp).min(1).max(8),
+});
+export const AnchorLeafSchema = z.strictObject({ tenant_id: TenantId, seq: z.number().int().positive(), entry_hash: Sha256Hex });
+// ---- Merkle tree (RFC 9162 section 2.1) ----------------------------------------------
+export async function anchorLeafHash(leaf) {
+    const body = utf8(canonicalise({ type: ANCHOR_LEAF_TYPE, tenant_id: leaf.tenant_id, seq: leaf.seq, entry_hash: leaf.entry_hash }));
+    return sha256(concatBytes(Uint8Array.of(0), body));
+}
+const node = (left, right) => sha256(concatBytes(Uint8Array.of(1), left, right));
+/** The largest power of two smaller than n (n > 1). */
+const split = (n) => 2 ** Math.floor(Math.log2(n - 1));
+export async function merkleRoot(leafHashes) {
+    if (leafHashes.length === 0)
+        throw new Error("a Merkle tree needs at least one leaf");
+    if (leafHashes.length === 1)
+        return new Uint8Array(leafHashes[0]);
+    const k = split(leafHashes.length);
+    return node(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
+}
+/** The inclusion path for leaf `index`, nearest sibling first. */
+export async function merklePath(leafHashes, index) {
+    if (index < 0 || index >= leafHashes.length)
+        throw new Error("leaf index out of range");
+    if (leafHashes.length === 1)
+        return [];
+    const k = split(leafHashes.length);
+    return index < k
+        ? [...(await merklePath(leafHashes.slice(0, k), index)), await merkleRoot(leafHashes.slice(k))]
+        : [...(await merklePath(leafHashes.slice(k), index - k)), await merkleRoot(leafHashes.slice(0, k))];
+}
+/** Recomputes the root from a leaf and its path (RFC 9162 2.1.3.2), or null if the path does not fit the tree. */
+export async function rootFromPath(leafHash, index, size, path) {
+    if (index >= size)
+        return null;
+    let fn = index;
+    let sn = size - 1;
+    let r = leafHash;
+    for (const p of path) {
+        if (sn === 0)
+            return null;
+        if (fn % 2 === 1 || fn === sn) {
+            r = await node(p, r);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            r = await node(r, p);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 ? r : null;
+}
+/**
+ * The tree for one anchoring round: one leaf per tenant, in tenant order. Returns the root
+ * to stamp, and each tenant's anchor.created payload once the stamps are in.
+ */
+export async function anchorTree(leaves) {
+    const sorted = [...leaves].map((l) => AnchorLeafSchema.parse(l)).sort((a, b) => (a.tenant_id < b.tenant_id ? -1 : a.tenant_id > b.tenant_id ? 1 : 0));
+    for (let i = 1; i < sorted.length; i++)
+        if (sorted[i].tenant_id === sorted[i - 1].tenant_id)
+            throw new Error(`two leaves for ${sorted[i].tenant_id}`);
+    const hashes = await Promise.all(sorted.map((l) => anchorLeafHash(l)));
+    const root = await merkleRoot(hashes);
+    return {
+        root,
+        payload: async (tenantId, timestamps) => {
+            const index = sorted.findIndex((l) => l.tenant_id === tenantId);
+            if (index < 0)
+                throw new Error(`no leaf for ${tenantId}`);
+            const leaf = sorted[index];
+            return AnchorCreatedPayload.parse({
+                anchored: { seq: leaf.seq, entry_hash: leaf.entry_hash },
+                merkle: { root: toHex(root), leaf_index: index, tree_size: sorted.length, path: (await merklePath(hashes, index)).map(toHex) },
+                timestamps,
+            });
+        },
+    };
+}
+// ---- Verification -----------------------------------------------------------------------
+/** How far a TSA's clock may disagree with int-loop's before the verifier objects. */
+export const ANCHOR_CLOCK_TOLERANCE_MS = 5 * 60_000;
+/**
+ * Checks every anchor.created entry: the anchored entry is in the ledger with that hash,
+ * its leaf leads to the stamped root, and every timestamp token verifies against `roots`
+ * for that root, at a time consistent with when the entries were recorded.
+ */
+export async function verifyAnchors(entries, roots) {
+    const failures = [];
+    const bySeq = new Map(entries.map((e) => [e.seq, e]));
+    let anchors_checked = 0;
+    let anchored_through = null;
+    for (const entry of entries) {
+        if (entry.type !== "anchor.created")
+            continue;
+        anchors_checked++;
+        const fail = (check, message) => failures.push({ seq: entry.seq, check, message });
+        try {
+            const parsed = AnchorCreatedPayload.safeParse(entry.payload);
+            if (!parsed.success) {
+                fail("anchor", parsed.error.issues.map((i) => i.message).join("; "));
+                continue;
+            }
+            const p = parsed.data;
+            const anchored = bySeq.get(p.anchored.seq);
+            if (p.anchored.seq >= entry.seq) {
+                fail("anchor", "an anchor can only cover entries recorded before it");
+                continue;
+            }
+            if (!anchored) {
+                fail("anchor", `anchored entry ${p.anchored.seq} is not in this ledger`);
+                continue;
+            }
+            if (anchored.entry_hash !== p.anchored.entry_hash) {
+                fail("anchor", `anchored hash does not match entry ${p.anchored.seq}`);
+                continue;
+            }
+            const leaf = await anchorLeafHash({ tenant_id: entry.tenant_id, seq: p.anchored.seq, entry_hash: p.anchored.entry_hash });
+            const root = await rootFromPath(leaf, p.merkle.leaf_index, p.merkle.tree_size, p.merkle.path.map(fromHex));
+            if (root === null || toHex(root) !== p.merkle.root) {
+                fail("anchor", "the anchored entry is not in the stamped Merkle tree");
+                continue;
+            }
+            // Labels are the recorder's word; independence is judged by the root each token chains to.
+            const tsas = new Set();
+            const rootsUsed = new Map();
+            const verified = [];
+            let earliest = null;
+            for (const ts of p.timestamps) {
+                const problems = [];
+                if (tsas.has(ts.tsa))
+                    problems.push(`two timestamps from ${ts.tsa}`);
+                tsas.add(ts.tsa);
+                const result = await verifyTimestampToken(fromBase64Url(ts.token), { digest: fromHex(p.merkle.root), roots });
+                if (!result.ok) {
+                    fail("timestamp", `${ts.tsa}: ${result.reason}`);
+                    continue;
+                }
+                const at = Date.parse(result.gen_time);
+                if (at !== Date.parse(ts.gen_time))
+                    problems.push(`recorded time ${ts.gen_time} differs from the token's ${result.gen_time}`);
+                if (at < Date.parse(anchored.recorded_at) - ANCHOR_CLOCK_TOLERANCE_MS)
+                    problems.push(`stamped before entry ${anchored.seq} was recorded`);
+                if (at > Date.parse(entry.recorded_at) + ANCHOR_CLOCK_TOLERANCE_MS)
+                    problems.push("stamped after the anchor itself was recorded");
+                const sameRoot = rootsUsed.get(result.root_sha256);
+                if (sameRoot !== undefined)
+                    problems.push(`chains to the same root as ${sameRoot}, so it is not an independent timestamp`);
+                rootsUsed.set(result.root_sha256, ts.tsa);
+                // Only a timestamp with nothing wrong counts towards what the anchor proves.
+                if (problems.length) {
+                    for (const m of problems)
+                        fail("timestamp", `${ts.tsa}: ${m}`);
+                    continue;
+                }
+                verified.push(ts.tsa);
+                earliest = earliest === null ? at : Math.min(earliest, at);
+            }
+            if (earliest !== null && (anchored_through === null || p.anchored.seq >= anchored_through.seq)) {
+                anchored_through = { seq: p.anchored.seq, gen_time: new Date(earliest).toISOString(), tsas: verified };
+            }
+        }
+        catch (err) {
+            fail("internal", err instanceof Error ? err.message : String(err));
+        }
+    }
+    return { anchors_checked, anchored_through, failures };
+}

package/dist/comprehension.d.ts

@@ -0,0 +1,12 @@
+import type { Fact } from "./schema/request.ts";
+export type ComprehensionQuestion = {
+    question_id: string;
+    fact_key: string;
+    prompt: string;
+    /** Formatted values, in display order. Exactly one is correct. */
+    choices: string[];
+    answer: string;
+};
+/** Facts a question can be built from: values with plausible wrong answers. */
+export declare function comprehensionFacts(facts: readonly Fact[]): Fact[];
+export declare function comprehensionQuestion(facts: readonly Fact[], seed: string, format: (f: Fact) => string): Promise<ComprehensionQuestion | null>;

package/dist/comprehension.js

@@ -0,0 +1,81 @@
+// L4 comprehension questions. Built deterministically from one structured fact, never
+// from the narrative and never by a model (hard rule 8): "What does the request say
+// for Estimated monthly cost?" with the real value and distractors derived from it.
+//
+// Pure. The seed (request, version, approver) chooses the fact and the order of the
+// choices, so the same inputs always give the same question and anyone holding the
+// facts can rebuild it. Display formatting is passed in, so the choices read exactly
+// as the facts do on the page.
+import { hashCanonical } from "./hash.js";
+const MAX_DISTRACTORS = 3;
+/** Facts a question can be built from: values with plausible wrong answers. */
+export function comprehensionFacts(facts) {
+    return facts.filter((f) => f.type === "money" || f.type === "count" || f.type === "date" || (f.type === "enum" && (f.choices ?? []).some((c) => c !== f.value)));
+}
+export async function comprehensionQuestion(facts, seed, format) {
+    const eligible = comprehensionFacts(facts);
+    if (eligible.length === 0)
+        return null;
+    const bytes = await hashCanonical({ purpose: "int-loop comprehension", seed });
+    // Start at the seeded fact; if formatting leaves it no distinct wrong answers, use the next one.
+    for (let k = 0; k < eligible.length; k++) {
+        const fact = eligible[(bytes[0] + k) % eligible.length];
+        const answer = format(fact);
+        const seen = new Set([answer]);
+        const distractors = [];
+        for (const candidate of variants(fact)) {
+            const text = format(candidate);
+            if (seen.has(text))
+                continue;
+            seen.add(text);
+            distractors.push(text);
+            if (distractors.length === MAX_DISTRACTORS)
+                break;
+        }
+        if (distractors.length > 0)
+            return build(fact, answer, distractors, bytes);
+    }
+    return null;
+}
+function build(fact, answer, distractors, bytes) {
+    // Deterministic shuffle (Fisher-Yates driven by the seed's bytes).
+    const choices = [answer, ...distractors];
+    for (let i = choices.length - 1; i > 0; i--) {
+        const j = bytes[1 + i] % (i + 1);
+        [choices[i], choices[j]] = [choices[j], choices[i]];
+    }
+    return {
+        question_id: `${fact.key}#${Array.from(bytes.slice(0, 4), (b) => b.toString(16).padStart(2, "0")).join("")}`,
+        fact_key: fact.key,
+        prompt: `What does the request say for “${fact.label}”?`,
+        choices,
+        answer,
+    };
+}
+/** Wrong values of the same type, nearest-looking first. */
+function variants(f) {
+    switch (f.type) {
+        case "money": {
+            const v = f.value.amount_minor;
+            const amounts = v === 0 ? [100, 1_000, 10_000] : [v * 10, Math.round(v / 10), v * 2, Math.round(v / 2), v * 3];
+            return amounts.filter((a) => a !== v && a > 0 && Number.isSafeInteger(a)).map((a) => ({ ...f, value: { ...f.value, amount_minor: a } }));
+        }
+        case "count": {
+            const v = f.value;
+            const counts = v === 0 ? [1, 10, 100] : [v * 10, Math.floor(v / 10), v * 2, v + 1, v - 1, v * 3];
+            return counts.filter((c) => c !== v && c >= 0 && Number.isSafeInteger(c)).map((c) => ({ ...f, value: c }));
+        }
+        case "date": {
+            const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(f.value);
+            const base = Date.parse(dateOnly ? `${f.value}T00:00:00Z` : f.value);
+            return [7, -7, 30, -30, 365].map((days) => {
+                const iso = new Date(base + days * 86_400_000).toISOString();
+                return { ...f, value: dateOnly ? iso.slice(0, 10) : iso.replace(".000Z", "Z") };
+            });
+        }
+        case "enum":
+            return (f.choices ?? []).filter((c) => c !== f.value).map((c) => ({ ...f, value: c }));
+        default:
+            return [];
+    }
+}

package/dist/controls.d.ts

@@ -0,0 +1,9 @@
+export type Control = {
+    id: string;
+    name: string;
+    implemented_by: string;
+    phase: 1 | 2 | 3;
+    retired?: true;
+};
+export declare const CONTROLS: readonly Control[];
+export declare const CONTROL_IDS: ReadonlySet<string>;

package/dist/controls.js

@@ -0,0 +1,19 @@
+// The control catalogue. IDs are permanent: a retired control keeps its ID and
+// gains `retired`. Packs may only reference controls listed here. Lives in core so
+// evidence reports can be rebuilt offline (DECISIONS.md, 2026-11-10).
+export const CONTROLS = [
+    { id: "CTL-OVERRIDE", name: "Every request can be denied, and approvers can attach conditions", implemented_by: "Request validation (exactly one deny), approve_with_conditions", phase: 1 },
+    { id: "CTL-MORE-INFO", name: "Approvers can ask for more information before deciding", implemented_by: "more_info flow", phase: 1 },
+    { id: "CTL-FACTS-FIRST", name: "Structured facts shown before the AI-written narrative, which is labelled", implemented_by: "Approval page", phase: 1 },
+    { id: "CTL-ATTENTION", name: "Time spent and context viewed are recorded; rubber-stamp patterns flagged", implemented_by: "Evidence capture; oversight reports (Phase 2)", phase: 1 },
+    { id: "CTL-RATIONALE", name: "Written rationale captured and bound to the decision", implemented_by: "L3", phase: 1 },
+    { id: "CTL-COMPREHENSION", name: "Deterministic comprehension question answered", implemented_by: "L4", phase: 2 },
+    { id: "CTL-IDENTITY", name: "Decision bound to a passkey held by a named, enrolled person", implemented_by: "L2+ binding", phase: 1 },
+    { id: "CTL-QUORUM-2", name: "At least two distinct qualified people decide", implemented_by: "Policy quorum, L4", phase: 1 },
+    { id: "CTL-SOD", name: "The agent's owner cannot approve its requests", implemented_by: "Policy engine", phase: 1 },
+    { id: "CTL-ATTR-REQUIRED", name: "Only approvers with the required authority and current training can decide", implemented_by: "Directory attributes, stage requires", phase: 1 },
+    { id: "CTL-LEDGER", name: "Tamper-evident record anyone can verify offline", implemented_by: "Ledger, int-loop-verify", phase: 1 },
+    { id: "CTL-RETENTION", name: "Records kept for at least the strictest active floor", implemented_by: "Retention rule", phase: 1 },
+    { id: "CTL-CONTEST", name: "People affected by a decision can ask for a human to review it", implemented_by: "Contest flow", phase: 3 },
+];
+export const CONTROL_IDS = new Set(CONTROLS.map((c) => c.id));

package/dist/der.d.ts

@@ -0,0 +1,53 @@
+export declare const TAG: {
+    readonly BOOLEAN: 1;
+    readonly INTEGER: 2;
+    readonly BIT_STRING: 3;
+    readonly OCTET_STRING: 4;
+    readonly NULL: 5;
+    readonly OID: 6;
+    readonly UTF8_STRING: 12;
+    readonly PRINTABLE_STRING: 19;
+    readonly IA5_STRING: 22;
+    readonly UTC_TIME: 23;
+    readonly GENERALIZED_TIME: 24;
+    readonly SEQUENCE: 48;
+    readonly SET: 49;
+};
+/** One element. `tag` is the whole identifier octet (class, constructed bit and number). */
+export type Der = {
+    tag: number;
+    /** The complete encoding, header included: what a signature or hash covers. */
+    raw: Uint8Array<ArrayBuffer>;
+    /** The contents, without the header. */
+    content: Uint8Array<ArrayBuffer>;
+};
+export declare const contextTag: (n: number, constructed?: boolean) => number;
+/** Reads exactly one element filling `bytes`. */
+export declare function readDer(bytes: Uint8Array): Der;
+/** The elements inside a constructed element (a SEQUENCE, SET or explicit tag). */
+export declare function children(el: Der): Der[];
+export declare function expectTag(el: Der | undefined, tag: number, what: string): Der;
+/** The elements of a SEQUENCE (or SET), checking its tag. */
+export declare function seq(el: Der | undefined, what: string, tag?: number): Der[];
+export declare function readOid(el: Der | undefined, what?: string): string;
+/** An INTEGER's two's-complement bytes, checked for minimal encoding. */
+export declare function readIntegerBytes(el: Der | undefined, what?: string): Uint8Array<ArrayBuffer>;
+/** A small non-negative INTEGER (a version number, a status). */
+export declare function readSmallInt(el: Der | undefined, what?: string): number;
+export declare function readBoolean(el: Der | undefined, what?: string): boolean;
+export declare function readOctetString(el: Der | undefined, what?: string): Uint8Array<ArrayBuffer>;
+/** A BIT STRING with no unused bits (keys and signatures always are). */
+export declare function readBitStringBytes(el: Der | undefined, what?: string): Uint8Array<ArrayBuffer>;
+/** UTCTime or GeneralizedTime, to milliseconds since the epoch. Only the Z (UTC) forms DER allows. */
+export declare function readTime(el: Der | undefined, what?: string): number;
+export declare function encode(tag: number, ...content: Uint8Array[]): Uint8Array<ArrayBuffer>;
+export declare const encodeSequence: (...items: Uint8Array[]) => Uint8Array<ArrayBuffer>;
+export declare const encodeNull: () => Uint8Array<ArrayBuffer>;
+export declare const encodeBoolean: (value: boolean) => Uint8Array<ArrayBuffer>;
+export declare const encodeOctetString: (bytes: Uint8Array) => Uint8Array<ArrayBuffer>;
+/** A non-negative INTEGER from big-endian unsigned bytes, minimally encoded. */
+export declare function encodeUnsignedInteger(bytes: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare function encodeSmallInt(value: number): Uint8Array<ArrayBuffer>;
+export declare function encodeOid(oid: string): Uint8Array<ArrayBuffer>;
+/** Decodes the base64 body of every PEM block of the given label (default CERTIFICATE). */
+export declare function fromPem(text: string, label?: string): Uint8Array<ArrayBuffer>[];