@int-loop/core 0.1.0 → 0.3.0

package/dist/der.js

@@ -0,0 +1,246 @@
+// A minimal DER (ASN.1 Distinguished Encoding Rules) reader and writer: just enough for
+// RFC 3161 timestamp requests and responses, the CMS signatures inside them and the
+// X.509 certificates that sign them. Written here rather than taken from a library so
+// the Apache-2.0 verifier has no dependencies beyond zod (DECISIONS.md, 2026-11-09).
+//
+// Strict: definite lengths only, minimal length encoding, no trailing bytes. Anything
+// else throws, and every caller turns a throw into a failed verification.
+import { concatBytes } from "./hash.js";
+export const TAG = {
+    BOOLEAN: 0x01,
+    INTEGER: 0x02,
+    BIT_STRING: 0x03,
+    OCTET_STRING: 0x04,
+    NULL: 0x05,
+    OID: 0x06,
+    UTF8_STRING: 0x0c,
+    PRINTABLE_STRING: 0x13,
+    IA5_STRING: 0x16,
+    UTC_TIME: 0x17,
+    GENERALIZED_TIME: 0x18,
+    SEQUENCE: 0x30,
+    SET: 0x31,
+};
+export const contextTag = (n, constructed = true) => 0x80 | (constructed ? 0x20 : 0) | n;
+/** Reads exactly one element filling `bytes`. */
+export function readDer(bytes) {
+    const { element, end } = readOne(bytes, 0);
+    if (end !== bytes.length)
+        throw new Error("trailing bytes after DER element");
+    return element;
+}
+/** The elements inside a constructed element (a SEQUENCE, SET or explicit tag). */
+export function children(el) {
+    if ((el.tag & 0x20) === 0)
+        throw new Error(`tag 0x${el.tag.toString(16)} is not constructed`);
+    const out = [];
+    let pos = 0;
+    while (pos < el.content.length) {
+        const { element, end } = readOne(el.content, pos);
+        out.push(element);
+        pos = end;
+    }
+    return out;
+}
+function readOne(bytes, start) {
+    let pos = start;
+    const tag = bytes[pos++];
+    if (tag === undefined)
+        throw new Error("DER element truncated");
+    if ((tag & 0x1f) === 0x1f)
+        throw new Error("high-numbered DER tags are not supported");
+    const first = bytes[pos++];
+    if (first === undefined)
+        throw new Error("DER length truncated");
+    let length;
+    if (first < 0x80) {
+        length = first;
+    }
+    else {
+        const count = first & 0x7f;
+        if (count === 0)
+            throw new Error("indefinite DER length");
+        if (count > 4)
+            throw new Error("DER length too large");
+        length = 0;
+        for (let i = 0; i < count; i++) {
+            const b = bytes[pos++];
+            if (b === undefined)
+                throw new Error("DER length truncated");
+            if (i === 0 && b === 0)
+                throw new Error("non-minimal DER length");
+            length = length * 256 + b;
+        }
+        if (length < 0x80)
+            throw new Error("non-minimal DER length");
+    }
+    const end = pos + length;
+    if (end > bytes.length)
+        throw new Error("DER element truncated");
+    return { element: { tag, raw: bytes.slice(start, end), content: bytes.slice(pos, end) }, end };
+}
+export function expectTag(el, tag, what) {
+    if (el === undefined)
+        throw new Error(`${what} is missing`);
+    if (el.tag !== tag)
+        throw new Error(`${what}: expected tag 0x${tag.toString(16)}, found 0x${el.tag.toString(16)}`);
+    return el;
+}
+/** The elements of a SEQUENCE (or SET), checking its tag. */
+export function seq(el, what, tag = TAG.SEQUENCE) {
+    return children(expectTag(el, tag, what));
+}
+// ---- Primitive values ---------------------------------------------------------
+export function readOid(el, what = "object identifier") {
+    const c = expectTag(el, TAG.OID, what).content;
+    if (c.length === 0)
+        throw new Error(`${what} is empty`);
+    const parts = [];
+    let value = 0;
+    for (let i = 0; i < c.length; i++) {
+        const b = c[i];
+        if (value === 0 && b === 0x80)
+            throw new Error(`${what}: non-minimal encoding`);
+        value = value * 128 + (b & 0x7f);
+        if (value > Number.MAX_SAFE_INTEGER)
+            throw new Error(`${what}: arc too large`);
+        if ((b & 0x80) === 0) {
+            parts.push(value);
+            value = 0;
+        }
+        else if (i === c.length - 1) {
+            throw new Error(`${what} truncated`);
+        }
+    }
+    const [head, ...rest] = parts;
+    const firstArc = head < 40 ? 0 : head < 80 ? 1 : 2;
+    return [firstArc, head - firstArc * 40, ...rest].join(".");
+}
+/** An INTEGER's two's-complement bytes, checked for minimal encoding. */
+export function readIntegerBytes(el, what = "integer") {
+    const c = expectTag(el, TAG.INTEGER, what).content;
+    if (c.length === 0)
+        throw new Error(`${what} is empty`);
+    if (c.length > 1 && ((c[0] === 0 && (c[1] & 0x80) === 0) || (c[0] === 0xff && (c[1] & 0x80) !== 0))) {
+        throw new Error(`${what}: non-minimal encoding`);
+    }
+    return c;
+}
+/** A small non-negative INTEGER (a version number, a status). */
+export function readSmallInt(el, what = "integer") {
+    const c = readIntegerBytes(el, what);
+    if (c.length > 4 || (c[0] & 0x80) !== 0)
+        throw new Error(`${what} out of range`);
+    return c.reduce((n, b) => n * 256 + b, 0);
+}
+export function readBoolean(el, what = "boolean") {
+    const c = expectTag(el, TAG.BOOLEAN, what).content;
+    if (c.length !== 1 || (c[0] !== 0 && c[0] !== 0xff))
+        throw new Error(`${what}: invalid DER boolean`);
+    return c[0] === 0xff;
+}
+export function readOctetString(el, what = "octet string") {
+    return expectTag(el, TAG.OCTET_STRING, what).content;
+}
+/** A BIT STRING with no unused bits (keys and signatures always are). */
+export function readBitStringBytes(el, what = "bit string") {
+    const c = expectTag(el, TAG.BIT_STRING, what).content;
+    if (c.length === 0 || c[0] !== 0)
+        throw new Error(`${what}: unused bits are not supported here`);
+    return c.slice(1);
+}
+/** UTCTime or GeneralizedTime, to milliseconds since the epoch. Only the Z (UTC) forms DER allows. */
+export function readTime(el, what = "time") {
+    if (el === undefined)
+        throw new Error(`${what} is missing`);
+    const text = new TextDecoder("ascii").decode(el.content);
+    let m;
+    let year;
+    if (el.tag === TAG.UTC_TIME) {
+        m = /^(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/.exec(text);
+        if (!m)
+            throw new Error(`${what}: invalid UTCTime`);
+        const yy = Number(m[1]);
+        year = yy >= 50 ? 1900 + yy : 2000 + yy;
+    }
+    else if (el.tag === TAG.GENERALIZED_TIME) {
+        // RFC 3161 allows fractional seconds, with no trailing zeros.
+        m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:\.(\d*[1-9]))?Z$/.exec(text);
+        if (!m)
+            throw new Error(`${what}: invalid GeneralizedTime`);
+        year = Number(m[1]);
+    }
+    else {
+        throw new Error(`${what}: expected a UTCTime or GeneralizedTime`);
+    }
+    const fraction = el.tag === TAG.GENERALIZED_TIME && m[7] ? Number(`0.${m[7]}`) : 0;
+    const ms = Date.UTC(year, Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6])) + Math.floor(fraction * 1000);
+    const check = new Date(ms);
+    if (check.getUTCMonth() !== Number(m[2]) - 1 || check.getUTCDate() !== Number(m[3]) || Number(m[4]) > 23 || Number(m[5]) > 59 || Number(m[6]) > 59) {
+        throw new Error(`${what}: not a real date and time`);
+    }
+    return ms;
+}
+// ---- Writing ------------------------------------------------------------------
+function encodeLength(length) {
+    if (length < 0x80)
+        return Uint8Array.of(length);
+    const bytes = [];
+    for (let n = length; n > 0; n = Math.floor(n / 256))
+        bytes.unshift(n & 0xff);
+    return Uint8Array.of(0x80 | bytes.length, ...bytes);
+}
+export function encode(tag, ...content) {
+    const body = concatBytes(...content);
+    return concatBytes(Uint8Array.of(tag), encodeLength(body.length), body);
+}
+export const encodeSequence = (...items) => encode(TAG.SEQUENCE, ...items);
+export const encodeNull = () => encode(TAG.NULL);
+export const encodeBoolean = (value) => encode(TAG.BOOLEAN, Uint8Array.of(value ? 0xff : 0));
+export const encodeOctetString = (bytes) => encode(TAG.OCTET_STRING, bytes);
+/** A non-negative INTEGER from big-endian unsigned bytes, minimally encoded. */
+export function encodeUnsignedInteger(bytes) {
+    let start = 0;
+    while (start < bytes.length - 1 && bytes[start] === 0)
+        start++;
+    const trimmed = bytes.length === 0 ? Uint8Array.of(0) : bytes.subarray(start);
+    return encode(TAG.INTEGER, (trimmed[0] & 0x80) !== 0 ? concatBytes(Uint8Array.of(0), trimmed) : trimmed);
+}
+export function encodeSmallInt(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error("expected a non-negative safe integer");
+    const bytes = [];
+    for (let n = value; n > 0; n = Math.floor(n / 256))
+        bytes.unshift(n & 0xff);
+    return encodeUnsignedInteger(Uint8Array.from(bytes.length ? bytes : [0]));
+}
+export function encodeOid(oid) {
+    const arcs = oid.split(".").map((a) => {
+        if (!/^(0|[1-9]\d*)$/.test(a))
+            throw new Error(`invalid OID ${oid}`);
+        return Number(a);
+    });
+    if (arcs.length < 2 || arcs[0] > 2 || (arcs[0] < 2 && arcs[1] >= 40))
+        throw new Error(`invalid OID ${oid}`);
+    const out = [];
+    for (const arc of [arcs[0] * 40 + arcs[1], ...arcs.slice(2)]) {
+        const chunk = [arc & 0x7f];
+        for (let n = Math.floor(arc / 128); n > 0; n = Math.floor(n / 128))
+            chunk.unshift(0x80 | (n & 0x7f));
+        out.push(...chunk);
+    }
+    return encode(TAG.OID, Uint8Array.from(out));
+}
+/** Decodes the base64 body of every PEM block of the given label (default CERTIFICATE). */
+export function fromPem(text, label = "CERTIFICATE") {
+    const out = [];
+    const re = new RegExp(`-----BEGIN ${label}-----([\\s\\S]*?)-----END ${label}-----`, "g");
+    for (const m of text.matchAll(re)) {
+        const b64 = m[1].replace(/\s+/g, "");
+        if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64))
+            throw new Error("invalid PEM base64");
+        const bin = atob(b64);
+        out.push(Uint8Array.from(bin, (ch) => ch.charCodeAt(0)));
+    }
+    return out;
+}

package/dist/evidence-pack.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type AnchorReport } from "./anchor.ts";
 import { LedgerEntry } from "./schema/ledger.ts";
 import { type VerificationFailure } from "./verify.ts";
 export declare const EVIDENCE_PACK_FORMAT = "int-loop-evidence-pack";
@@ -33,7 +34,7 @@ export declare const PackKeys: z.ZodObject<{
 export type PackKeys = z.infer<typeof PackKeys>;
 /** The hashes of free text a ledger entry references, which the pack should carry. */
 export declare function referencedTextHashes(entry: LedgerEntry): string[];
-export declare const PACK_README = "# int-loop evidence pack\n\nThis archive is a complete, signed record of decisions made through int-loop for one\ntenant. You can check it without trusting int-loop.\n\nRun:\n\n    npx @int-loop/verify pack.zip\n\nor, to confirm the service keys are really int-loop's, download\nhttps://int-loop.com/.well-known/int-loop-keys.json and run:\n\n    npx @int-loop/verify pack.zip --keys int-loop-keys.json\n\nThe verifier checks that:\n\n1. Every ledger entry links to the one before it (a SHA-256 hash chain from a zero genesis hash).\n2. Every entry carries a valid Ed25519 signature from an int-loop service key.\n3. Every passkey decision (L2 and above) carries a WebAuthn assertion from a passkey enrolled\n   earlier in this ledger, by the person the decision names, over a challenge that commits to\n   exactly what was displayed, the option chosen, and any reason, conditions or question typed.\n4. Every text in texts.jsonl matches the hash the ledger records for it.\n\nTexts marked \"erased\" were removed under the tenant's retention policy. Their hashes stay in\nthe ledger, so the chain still verifies.\n\nThe verifier is open source (Apache-2.0). This pack is evidence for your own assessment. It is\nnot legal advice and does not on its own show that any regulation is met.\n";
+export declare const PACK_README = "# int-loop evidence pack\n\nThis archive is a complete, signed record of decisions made through int-loop for one\ntenant. You can check it without trusting int-loop.\n\nRun:\n\n    npx @int-loop/verify pack.zip\n\nor, to confirm the service keys are really int-loop's, download\nhttps://int-loop.com/.well-known/int-loop-keys.json and run:\n\n    npx @int-loop/verify pack.zip --keys int-loop-keys.json\n\nThe verifier checks that:\n\n1. Every ledger entry links to the one before it (a SHA-256 hash chain from a zero genesis hash).\n2. Every entry carries a valid Ed25519 signature from an int-loop service key.\n3. Every passkey decision (L2 and above) carries a WebAuthn assertion from a passkey enrolled\n   earlier in this ledger, by the person the decision names, over a challenge that commits to\n   exactly what was displayed, the option chosen, and any reason, conditions or question typed.\n4. Every text in texts.jsonl matches the hash the ledger records for it.\n5. Every anchor (an anchor.created entry) holds RFC 3161 timestamps from independent\n   timestamp authorities, over a Merkle root that includes the anchored entry. Each\n   timestamp must verify against a trusted timestamp authority root. This shows the\n   ledger up to that entry existed, unchanged, no later than the stamped time.\n   The verifier trusts a short built-in list of roots; pass --tsa-roots roots.pem to\n   use your own.\n\nTexts marked \"erased\" were removed under the tenant's retention policy. Their hashes stay in\nthe ledger, so the chain still verifies.\n\nThe verifier is open source (Apache-2.0). This pack is evidence for your own assessment. It is\nnot legal advice and does not on its own show that any regulation is met.\n";
 export declare function crc32(data: Uint8Array): number;
 export declare function buildZip(files: {
     name: string;
@@ -49,11 +50,19 @@ export type PackReport = {
     texts_checked: number;
     texts_erased: number;
     keys_source: "pack" | "trusted";
+    anchors_checked: number;
+    /** The newest anchored entry, and the earliest time an independent TSA vouches for it. */
+    anchored_through: AnchorReport["anchored_through"];
+    tsa_roots_source: "default" | "supplied";
     failures: VerificationFailure[];
 };
+export type PackVerifyOptions = {
+    /** Trusted timestamp authority roots, as DER certificates. Default: KNOWN_TSA_ROOTS. */
+    tsaRoots?: readonly Uint8Array[];
+};
 /**
  * Verifies an evidence pack. With `trustedKeys` (from int-loop's published key list),
  * the pack's own keys.json must agree with them; without, the report says the keys came
  * only from the pack.
  */
-export declare function verifyEvidencePack(zip: Uint8Array, trustedKeys?: PackKeys): Promise<PackReport>;
+export declare function verifyEvidencePack(zip: Uint8Array, trustedKeys?: PackKeys, options?: PackVerifyOptions): Promise<PackReport>;

package/dist/evidence-pack.js

@@ -10,9 +10,11 @@
 // The zip is stored, not compressed, with fixed timestamps: the same records always
 // produce the same bytes, and the reader needs no decompressor.
 import { z } from "zod";
+import { verifyAnchors } from "./anchor.js";
 import { bytesEqual, fromBase64Url, sha256Hex, utf8 } from "./hash.js";
 import { Base64Url, Sha256Hex, TenantId, Timestamp } from "./schema/common.js";
 import { LedgerEntry, ServiceKeyId } from "./schema/ledger.js";
+import { knownTsaRootsDer } from "./tsa-roots.js";
 import { verifyLedger } from "./verify.js";
 export const EVIDENCE_PACK_FORMAT = "int-loop-evidence-pack";
 export const PackManifest = z.strictObject({
@@ -75,6 +77,12 @@ The verifier checks that:
    earlier in this ledger, by the person the decision names, over a challenge that commits to
    exactly what was displayed, the option chosen, and any reason, conditions or question typed.
 4. Every text in texts.jsonl matches the hash the ledger records for it.
+5. Every anchor (an anchor.created entry) holds RFC 3161 timestamps from independent
+   timestamp authorities, over a Merkle root that includes the anchored entry. Each
+   timestamp must verify against a trusted timestamp authority root. This shows the
+   ledger up to that entry existed, unchanged, no later than the stamped time.
+   The verifier trusts a short built-in list of roots; pass --tsa-roots roots.pem to
+   use your own.
 
 Texts marked "erased" were removed under the tenant's retention policy. Their hashes stay in
 the ledger, so the chain still verifies.
@@ -201,7 +209,7 @@ export function readZip(zip) {
  * the pack's own keys.json must agree with them; without, the report says the keys came
  * only from the pack.
  */
-export async function verifyEvidencePack(zip, trustedKeys) {
+export async function verifyEvidencePack(zip, trustedKeys, options = {}) {
     const failures = [];
     const report = (extra) => ({
         ok: false,
@@ -211,6 +219,9 @@ export async function verifyEvidencePack(zip, trustedKeys) {
         texts_checked: 0,
         texts_erased: 0,
         keys_source: trustedKeys ? "trusted" : "pack",
+        anchors_checked: 0,
+        anchored_through: null,
+        tsa_roots_source: options.tsaRoots ? "supplied" : "default",
         failures,
         ...extra,
     });
@@ -329,5 +340,16 @@ export async function verifyEvidencePack(zip, trustedKeys) {
             if (!present.has(h))
                 fail("texts", `entry ${e.seq} references text ${h}, which is not in the pack`, e.seq);
     }
-    return report({ ok: failures.length === 0, manifest, entries_checked: ledger.entries_checked, decisions_checked: ledger.decisions_checked, texts_checked, texts_erased });
+    const anchors = await verifyAnchors(parsed, options.tsaRoots ?? knownTsaRootsDer());
+    failures.push(...anchors.failures);
+    return report({
+        ok: failures.length === 0,
+        manifest,
+        entries_checked: ledger.entries_checked,
+        decisions_checked: ledger.decisions_checked,
+        texts_checked,
+        texts_erased,
+        anchors_checked: anchors.anchors_checked,
+        anchored_through: anchors.anchored_through,
+    });
 }

package/dist/index.d.ts

@@ -2,11 +2,19 @@ export * from "./jcs.ts";
 export * from "./hash.ts";
 export * from "./cbor.ts";
 export * from "./binding.ts";
+export * from "./comprehension.ts";
 export * from "./webauthn.ts";
 export * from "./ledger.ts";
 export * from "./verify.ts";
 export * from "./evidence-pack.ts";
 export * from "./receipt.ts";
+export * from "./der.ts";
+export * from "./x509.ts";
+export * from "./tsp.ts";
+export * from "./tsa-roots.ts";
+export * from "./anchor.ts";
+export * from "./controls.ts";
+export * from "./report.ts";
 export * from "./schema/common.ts";
 export * from "./schema/request.ts";
 export * from "./schema/directory.ts";

package/dist/index.js

@@ -2,11 +2,19 @@ export * from "./jcs.js";
 export * from "./hash.js";
 export * from "./cbor.js";
 export * from "./binding.js";
+export * from "./comprehension.js";
 export * from "./webauthn.js";
 export * from "./ledger.js";
 export * from "./verify.js";
 export * from "./evidence-pack.js";
 export * from "./receipt.js";
+export * from "./der.js";
+export * from "./x509.js";
+export * from "./tsp.js";
+export * from "./tsa-roots.js";
+export * from "./anchor.js";
+export * from "./controls.js";
+export * from "./report.js";
 export * from "./schema/common.js";
 export * from "./schema/request.js";
 export * from "./schema/directory.js";

package/dist/report.d.ts

@@ -0,0 +1,92 @@
+import { type AssuranceLevel } from "./schema/common.ts";
+import type { LedgerEntry } from "./schema/ledger.ts";
+import { Pack, type Obligation } from "./schema/pack.ts";
+export declare const REPORT_FORMAT = "int-loop.oversight-report";
+export type ReportInput = {
+    /** The tenant's ledger from entry 1, in order. Entries after `throughSeq` are ignored. */
+    entries: readonly LedgerEntry[];
+    /** Texts by hash, as the evidence pack holds them; null for an erased text. */
+    texts: ReadonlyMap<string, string | null>;
+    /** The pack to report against, as `id@version`. It must have been activated in the ledger. */
+    packRef: string;
+    /** Inclusive UTC dates, YYYY-MM-DD. */
+    period: {
+        from: string;
+        to: string;
+    };
+    generatedAt: string;
+    /** The last entry the report considers. Default: the last entry given. */
+    throughSeq?: number;
+};
+export type ControlEvidence = {
+    id: string;
+    name: string;
+    status: "available" | "not_yet_available";
+    evidence: string[];
+};
+export type ObligationSection = Pick<Obligation, "id" | "citation" | "summary" | "applies_from" | "coverage" | "coverage_note"> & {
+    controls: ControlEvidence[];
+};
+export type ReportGap = {
+    kind: string;
+    message: string;
+    seqs: number[];
+};
+export type OversightReport = {
+    format: typeof REPORT_FORMAT;
+    format_version: 1;
+    scope_statement: string[];
+    tenant_id: string;
+    generated_at: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    pack: Pick<Pack, "id" | "version" | "title" | "jurisdiction" | "status" | "review" | "sources"> & {
+        ref: string;
+        hash: string;
+    };
+    ledger: {
+        through_seq: number;
+        through_hash: string;
+        period_first_seq: number | null;
+        period_last_seq: number | null;
+        /** The first anchor recorded after the period that covers its last entry, as recorded. int-loop-verify checks the tokens. */
+        anchor: {
+            anchor_seq: number;
+            anchored_seq: number;
+            tsas: string[];
+            gen_times: string[];
+        } | null;
+    };
+    policy_hashes: string[];
+    summary: {
+        requests_in_scope: number;
+        decisions_in_scope: number;
+        distinct_approvers: number;
+        outcomes: Record<string, number>;
+        assurance: Record<AssuranceLevel, number>;
+        assurance_floor: AssuranceLevel | null;
+        decisions_at_or_above_floor: number;
+        training_floor: string[];
+        training_on_decision_day: {
+            met: number;
+            not_met: number;
+            unknown: number;
+        };
+        median_time_spent_ms: number | null;
+    };
+    obligations: {
+        in_force: ObligationSection[];
+        not_yet_in_force: ObligationSection[];
+        date_to_confirm: ObligationSection[];
+    };
+    gaps: ReportGap[];
+    out_of_scope: string[];
+    notes: string[];
+};
+export declare class ReportError extends Error {
+}
+export declare function buildOversightReport(input: ReportInput): Promise<OversightReport>;
+/** Plain text, for the terminal and for reading. The JSON is the record. */
+export declare function renderReportText(r: OversightReport): string;