attenu-guard 0.1.0

package/dist/esm/audit.js

@@ -0,0 +1,189 @@
+/**
+ * Hash-chained audit log — the open, verifiable record of every authority decision.
+ *
+ * Each event is appended as one JSON line whose `hash` covers the event plus the
+ * previous line's hash. Any insertion, deletion or reordering breaks the chain
+ * and is detectable offline by anyone, with no vendor in the loop.
+ *
+ * The schema is versioned and published as `schema/agent-audit.schema.json` in
+ * the Python distribution, so other tools (SIEMs, observability) can ingest it.
+ * The hashes computed here are byte-identical to the Python library's for
+ * identical content — see `canonical.ts` for how that is guaranteed.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { canonicalBytes, parseJson, pyJsonDumps, toPlain, } from "./canonical.js";
+export const SCHEMA_VERSION = 1;
+export const GENESIS = "0".repeat(64);
+/** `sha256(prev_hash || canonical(event-without-hash))`, as hex. */
+export function hashEntry(prevHash, payload) {
+    const h = createHash("sha256");
+    h.update(Buffer.from(prevHash, "utf8"));
+    h.update(canonicalBytes(payload));
+    return h.digest("hex");
+}
+function asNumber(value) {
+    const plain = toPlain(value);
+    return typeof plain === "number" ? plain : undefined;
+}
+function withoutHash(entry) {
+    const out = {};
+    for (const [k, v] of Object.entries(entry)) {
+        if (k !== "hash")
+            out[k] = v;
+    }
+    return out;
+}
+/** Append-only, hash-chained decision log. */
+export class AuditLog {
+    path;
+    sinks;
+    prev = GENESIS;
+    seq = 0;
+    _entries = [];
+    /**
+     * Timestamps are injected by the caller (the `Guard` uses a monotonic
+     * counter) so the log stays deterministic in tests and reproducible in
+     * replay. In production the runtime supplies a trusted timestamp.
+     */
+    constructor(init = {}) {
+        const opts = typeof init === "string" || init === null ? { path: init } : init;
+        this.path = opts.path ?? null;
+        this.sinks = opts.sinks ?? [];
+        if (this.path) {
+            mkdirSync(dirname(this.path), { recursive: true });
+            writeFileSync(this.path, ""); // fresh log
+        }
+    }
+    append(event, ts, fields = {}) {
+        const payload = {
+            v: SCHEMA_VERSION,
+            seq: this.seq,
+            ts,
+            event,
+            ...fields,
+            prev_hash: this.prev,
+        };
+        payload["hash"] = hashEntry(this.prev, payload);
+        this.prev = payload["hash"];
+        this.seq += 1;
+        this._entries.push(payload);
+        if (this.path) {
+            // Python writes the ledger with `json.dumps(payload, sort_keys=True)` —
+            // its DEFAULT separators, not the compact pair the hash is taken over.
+            appendFileSync(this.path, pyJsonDumps(payload) + "\n");
+        }
+        for (const sink of this.sinks)
+            sink.write(payload);
+        return payload;
+    }
+    get entries() {
+        return this._entries.slice();
+    }
+    get length() {
+        return this._entries.length;
+    }
+    [Symbol.iterator]() {
+        return this.entries[Symbol.iterator]();
+    }
+    // ---- verification -----------------------------------------------------
+    /** `[seq, hash]` of the last entry — the chain head; `[-1, GENESIS]` if empty. */
+    head() {
+        if (this._entries.length === 0)
+            return [-1, GENESIS];
+        const last = this._entries[this._entries.length - 1];
+        return [asNumber(last["seq"]), last["hash"]];
+    }
+    chainIdHint() {
+        return chainIdOf(this._entries);
+    }
+    /**
+     * A signed external COMMITMENT to the chain head. Publish it out of band; a
+     * later `verifyAnchor` then catches a log that was fully rewritten and
+     * re-hashed, which plain `verify` cannot — a consistent rewrite reproduces
+     * its own hashes. The signed head hash is the fixed point.
+     */
+    anchor(signer, ts = 0) {
+        const [seq, head] = this.head();
+        const body = { v: SCHEMA_VERSION, chain_id: this.chainIdHint(), seq, head, ts };
+        return {
+            ...body,
+            kid: signer.kid ?? null,
+            sig: signer.sign(canonicalBytes(body)).toString("hex"),
+        };
+    }
+    /** The chain reproduces AND its head matches a SIGNED anchor. */
+    static verifyAnchor(entries, anchor, signer) {
+        const a = anchor ?? {};
+        const body = {};
+        for (const k of ["v", "chain_id", "seq", "head", "ts"])
+            body[k] = a[k] ?? null;
+        const sigHex = toPlain(a["sig"]) ?? "";
+        if (typeof sigHex !== "string" || !/^(?:[0-9a-fA-F]{2})*$/.test(sigHex)) {
+            return [false, "anchor signature not hex"];
+        }
+        const sig = Buffer.from(sigHex, "hex");
+        const kid = toPlain(a["kid"]);
+        if (!signer.verify(canonicalBytes(body), sig, kid)) {
+            return [false, "anchor signature invalid"];
+        }
+        const [ok, err] = AuditLog.verify(entries);
+        if (!ok)
+            return [false, err];
+        if (entries.length === 0)
+            return [asNumber(a["seq"]) === -1, null];
+        const last = entries[entries.length - 1];
+        if (last["hash"] !== toPlain(a["head"]) || asNumber(last["seq"]) !== asNumber(a["seq"])) {
+            return [false, "anchor head does not match the ledger head (ledger rewritten?)"];
+        }
+        return [true, null];
+    }
+    /** Recompute the chain. Returns `[ok, firstBadReason]`. */
+    static verify(entries) {
+        let prev = GENESIS;
+        let expectedSeq = 0;
+        for (const e of entries) {
+            const seq = asNumber(e["seq"]);
+            if (seq !== expectedSeq) {
+                return [false, `seq gap at ${expectedSeq} (got ${formatSeq(e["seq"])})`];
+            }
+            const stored = e["hash"];
+            const payload = withoutHash(e);
+            if (toPlain(payload["prev_hash"]) !== prev) {
+                return [false, `prev_hash mismatch at seq ${expectedSeq}`];
+            }
+            if (hashEntry(prev, payload) !== stored) {
+                return [false, `hash mismatch at seq ${expectedSeq}`];
+            }
+            prev = stored;
+            expectedSeq += 1;
+        }
+        return [true, null];
+    }
+    /** Read a `.jsonl` ledger, keeping every number's original literal. */
+    static load(path) {
+        return AuditLog.parseLines(readFileSync(path, "utf8"));
+    }
+    /** Parse `.jsonl` text into entries. Blank lines are skipped. */
+    static parseLines(text) {
+        return text
+            .split(/\r?\n/)
+            .filter((line) => line.trim() !== "")
+            .map((line) => parseJson(line));
+    }
+}
+function formatSeq(value) {
+    const plain = toPlain(value);
+    return plain === undefined || plain === null ? "None" : String(plain);
+}
+/** The first `chain_id` any entry carries, or `"chain"`. */
+export function chainIdOf(entries) {
+    for (const e of entries) {
+        const id = toPlain(e["chain_id"]);
+        if (typeof id === "string" && id)
+            return id;
+    }
+    return "chain";
+}
+//# sourceMappingURL=audit.js.map

package/dist/esm/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/esm/authority.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Authority — the core value object.
+ *
+ * An Authority is an immutable capability: a set of scopes plus typed `Ceiling`
+ * bounds and a TTL. The single most important operation is `meet`: the greatest
+ * authority that is within BOTH a parent's authority and a requested one. A
+ * child of a delegation can never hold more than the meet — attenuation is a
+ * lattice operation, enforced in code, not a convention.
+ *
+ * The guarantee everything else rests on:
+ *
+ *     meet(parent, requested) <= parent   for ALL requested.
+ *
+ * There is no code path by which a derived child authority can exceed its
+ * parent. That is what makes model-proposed authority safe to accept: the
+ * proposal is only ever an input to `meet`, and `meet` can only shrink.
+ *
+ * `isNarrowerThan` is exactly the wire protocol's subsumption relation
+ * (draft-asor-wimse-agent-delegation-chain-00), so a chain that verifies offline
+ * is one the library would have permitted, and the reverse.
+ */
+import { type CJson, type Json } from "./canonical.js";
+import { type Ceiling, type Context } from "./ceilings.js";
+import { Decision } from "./reasons.js";
+/**
+ * Raised for STRUCTURAL failures — bad input or invalid chain state, such as
+ * delegating from a revoked or expired node, or a depth/fanout overflow.
+ * Deliberately distinct from a policy denial: a denial is a normal outcome,
+ * expressed as a `Decision`. A structural error means the caller did something
+ * invalid; a denial means the caller asked for something the authority model
+ * legitimately refuses.
+ */
+export declare class AuthorityError extends Error {
+    readonly reason: string;
+    readonly detail: Record<string, Json>;
+    constructor(message: string, reason: string, detail?: Record<string, Json>);
+}
+export interface AuthorityInit {
+    scopes?: Iterable<string>;
+    ceilings?: Iterable<Ceiling>;
+    /** Seconds this authority remains valid from issuance; `null` is unbounded. */
+    ttl?: number | null;
+}
+/** The wire form of an Authority. */
+export interface AuthorityWire {
+    scopes: string[];
+    constraints: Record<string, Json>[];
+    ttl: number | null;
+    [key: string]: CJson;
+}
+export declare class Authority {
+    /**
+     * Permission strings, e.g. `crm.read`. Scopes support one level of prefix
+     * wildcard: `crm.*` covers `crm.read` and `crm.write`. A child requesting
+     * `crm.read` under a parent holding `crm.*` is allowed; the reverse is not.
+     */
+    readonly scopes: ReadonlySet<string>;
+    /**
+     * At most one ceiling per `key` (last one wins), sorted by key for a
+     * deterministic wire form and integrity seal. A dimension with no ceiling is
+     * unbounded on that dimension unless a parent in the chain bounds it —
+     * attenuation can only add or tighten bounds, never remove one.
+     */
+    readonly ceilings: readonly Ceiling[];
+    /** Seconds from issuance. `null` is unbounded (discouraged). */
+    readonly ttl: number | null;
+    constructor(init?: AuthorityInit);
+    private byKey;
+    /** The ceiling bound to `key`, or `undefined`. */
+    ceiling(key: string): Ceiling | undefined;
+    /** Does a held scope cover a requested scope? Supports one `x.*` wildcard. */
+    static scopeCovers(held: string, requested: string): boolean;
+    coversScope(requested: string): boolean;
+    /**
+     * The greatest authority within BOTH `this` and `other` — the attenuation.
+     * This is the only way a child authority is constructed. It is commutative
+     * and can only ever shrink relative to either input.
+     */
+    meet(other: Authority): Authority;
+    /**
+     * `this <= other`: is `this` provably no more powerful than `other` in every
+     * dimension? True iff:
+     *
+     *   1. every scope of `this` is covered by `other` (wildcard-aware);
+     *   2. for every ceiling in `other` there is a ceiling of the same key in
+     *      `this` that `other`'s ceiling subsumes. A ceiling present in `other`
+     *      and ABSENT here means `this` is unbounded on that dimension, i.e. more
+     *      powerful, so the relation is false. This holds for any ceiling key,
+     *      including ones outside the built-in registry, which is what makes the
+     *      relation sound for custom ceilings too;
+     *   3. `this.ttl` is not null and (`other.ttl` is null or `this.ttl <= other.ttl`).
+     *
+     * This is exactly the wire subsumption relation: the library relation and the
+     * token relation are the same relation.
+     */
+    isNarrowerThan(other: Authority): boolean;
+    /**
+     * Is `scope` permitted under this authority, given a request context such as
+     * `{rows: 5000, egress: "none"}`?
+     *
+     * Checks scope coverage AND every ceiling this authority holds, collecting
+     * every failing reason — not just the first — so a single evaluation can
+     * explain everything wrong with a request. A ceiling whose context field is
+     * absent is not asserting anything on this call and is treated as satisfied.
+     */
+    permits(scope: string, ctx?: Context | null): Decision;
+    withTtl(ttl: number): Authority;
+    toWire(): AuthorityWire;
+    static fromWire(wire: CJson): Authority;
+    /** A stable, human-readable one-liner. */
+    describe(): string;
+    toString(): string;
+}
+//# sourceMappingURL=authority.d.ts.map

package/dist/esm/authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.d.ts","sourceRoot":"","sources":["../../src/authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA6C,KAAK,KAAK,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAgD,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,QAAQ,EAAsB,MAAM,cAAc,CAAC;AAE5D;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM;CAM/E;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;IACpC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAGnB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB;AAED,qBAAa,SAAS;IACpB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEhB,IAAI,GAAE,aAAkB;IAUpC,OAAO,CAAC,KAAK;IAMb,kDAAkD;IAClD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAMzC,8EAA8E;IAC9E,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAM5D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IASvC;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS;IAsCjC;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAkBzC;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,OAAO,GAAG,IAAW,GAAG,QAAQ;IA0B5D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAM/B,MAAM,IAAI,aAAa;IAQvB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAYvC,0CAA0C;IAC1C,QAAQ,IAAI,MAAM;IAMlB,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/esm/authority.js

@@ -0,0 +1,233 @@
+/**
+ * Authority — the core value object.
+ *
+ * An Authority is an immutable capability: a set of scopes plus typed `Ceiling`
+ * bounds and a TTL. The single most important operation is `meet`: the greatest
+ * authority that is within BOTH a parent's authority and a requested one. A
+ * child of a delegation can never hold more than the meet — attenuation is a
+ * lattice operation, enforced in code, not a convention.
+ *
+ * The guarantee everything else rests on:
+ *
+ *     meet(parent, requested) <= parent   for ALL requested.
+ *
+ * There is no code path by which a derived child authority can exceed its
+ * parent. That is what makes model-proposed authority safe to accept: the
+ * proposal is only ever an input to `meet`, and `meet` can only shrink.
+ *
+ * `isNarrowerThan` is exactly the wire protocol's subsumption relation
+ * (draft-asor-wimse-agent-delegation-chain-00), so a chain that verifies offline
+ * is one the library would have permitted, and the reverse.
+ */
+import { compareCodePoints, sortedStrings, toPlain } from "./canonical.js";
+import { ceilingFromWire, describe as describeCeiling } from "./ceilings.js";
+import { Decision, Reason, ReasonCode } from "./reasons.js";
+/**
+ * Raised for STRUCTURAL failures — bad input or invalid chain state, such as
+ * delegating from a revoked or expired node, or a depth/fanout overflow.
+ * Deliberately distinct from a policy denial: a denial is a normal outcome,
+ * expressed as a `Decision`. A structural error means the caller did something
+ * invalid; a denial means the caller asked for something the authority model
+ * legitimately refuses.
+ */
+export class AuthorityError extends Error {
+    reason;
+    detail;
+    constructor(message, reason, detail = {}) {
+        super(message);
+        this.name = "AuthorityError";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+export class Authority {
+    /**
+     * Permission strings, e.g. `crm.read`. Scopes support one level of prefix
+     * wildcard: `crm.*` covers `crm.read` and `crm.write`. A child requesting
+     * `crm.read` under a parent holding `crm.*` is allowed; the reverse is not.
+     */
+    scopes;
+    /**
+     * At most one ceiling per `key` (last one wins), sorted by key for a
+     * deterministic wire form and integrity seal. A dimension with no ceiling is
+     * unbounded on that dimension unless a parent in the chain bounds it —
+     * attenuation can only add or tighten bounds, never remove one.
+     */
+    ceilings;
+    /** Seconds from issuance. `null` is unbounded (discouraged). */
+    ttl;
+    constructor(init = {}) {
+        this.scopes = new Set(init.scopes ?? []);
+        const byKey = new Map();
+        for (const c of init.ceilings ?? [])
+            byKey.set(String(c.key), c);
+        this.ceilings = Array.from(byKey.keys())
+            .sort(compareCodePoints)
+            .map((k) => byKey.get(k));
+        this.ttl = init.ttl ?? null;
+    }
+    byKey() {
+        const m = new Map();
+        for (const c of this.ceilings)
+            m.set(String(c.key), c);
+        return m;
+    }
+    /** The ceiling bound to `key`, or `undefined`. */
+    ceiling(key) {
+        return this.byKey().get(key);
+    }
+    // ---- scope helpers ----------------------------------------------------
+    /** Does a held scope cover a requested scope? Supports one `x.*` wildcard. */
+    static scopeCovers(held, requested) {
+        if (held === requested)
+            return true;
+        if (held.endsWith(".*"))
+            return requested.startsWith(held.slice(0, -1)); // keep the dot
+        return false;
+    }
+    coversScope(requested) {
+        for (const held of this.scopes) {
+            if (Authority.scopeCovers(held, requested))
+                return true;
+        }
+        return false;
+    }
+    // ---- the lattice ------------------------------------------------------
+    /**
+     * The greatest authority within BOTH `this` and `other` — the attenuation.
+     * This is the only way a child authority is constructed. It is commutative
+     * and can only ever shrink relative to either input.
+     */
+    meet(other) {
+        // Scopes: keep a requested scope only if this side covers it, and keep this
+        // side's own concrete scopes that the other covers. The net effect is a
+        // wildcard-aware intersection, never larger than either side's coverage.
+        const merged = new Set();
+        for (const s of other.scopes)
+            if (this.coversScope(s))
+                merged.add(s);
+        for (const s of this.scopes)
+            if (other.coversScope(s))
+                merged.add(s);
+        // Remove only REDUNDANT scopes: one covered by a broader wildcard that is
+        // also present. This keeps the broadest legitimately-granted authority and
+        // only trims duplicates, so a wildcard granted by both sides survives.
+        const wildcards = Array.from(merged).filter((s) => s.endsWith(".*"));
+        const pruned = new Set(Array.from(merged).filter((s) => !wildcards.some((w) => w !== s && Authority.scopeCovers(w, s))));
+        // Ceilings: union of keys. Where BOTH sides bound a key, narrow it; where
+        // only one side bounds it, carry that bound through unchanged. A ceiling
+        // therefore only ever appears or tightens across a meet, never disappears —
+        // exactly the property `isNarrowerThan` checks.
+        const mine = this.byKey();
+        const theirs = other.byKey();
+        const keys = Array.from(new Set([...mine.keys(), ...theirs.keys()])).sort(compareCodePoints);
+        const ceilings = [];
+        for (const k of keys) {
+            const a = mine.get(k);
+            const b = theirs.get(k);
+            ceilings.push(a !== undefined && b !== undefined ? a.narrow(b) : (a ?? b));
+        }
+        const ttls = [this.ttl, other.ttl].filter((t) => t !== null);
+        const ttl = ttls.length > 0 ? Math.min(...ttls) : null;
+        return new Authority({ scopes: pruned, ceilings, ttl });
+    }
+    /**
+     * `this <= other`: is `this` provably no more powerful than `other` in every
+     * dimension? True iff:
+     *
+     *   1. every scope of `this` is covered by `other` (wildcard-aware);
+     *   2. for every ceiling in `other` there is a ceiling of the same key in
+     *      `this` that `other`'s ceiling subsumes. A ceiling present in `other`
+     *      and ABSENT here means `this` is unbounded on that dimension, i.e. more
+     *      powerful, so the relation is false. This holds for any ceiling key,
+     *      including ones outside the built-in registry, which is what makes the
+     *      relation sound for custom ceilings too;
+     *   3. `this.ttl` is not null and (`other.ttl` is null or `this.ttl <= other.ttl`).
+     *
+     * This is exactly the wire subsumption relation: the library relation and the
+     * token relation are the same relation.
+     */
+    isNarrowerThan(other) {
+        for (const s of this.scopes) {
+            if (!other.coversScope(s))
+                return false;
+        }
+        const mine = this.byKey();
+        for (const [k, otherCeiling] of other.byKey()) {
+            const selfCeiling = mine.get(k);
+            if (selfCeiling === undefined)
+                return false; // unbounded here where other bounds
+            if (!otherCeiling.subsumes(selfCeiling))
+                return false;
+        }
+        if (other.ttl !== null) {
+            if (this.ttl === null || this.ttl > other.ttl)
+                return false;
+        }
+        return true;
+    }
+    // ---- policy evaluation ------------------------------------------------
+    /**
+     * Is `scope` permitted under this authority, given a request context such as
+     * `{rows: 5000, egress: "none"}`?
+     *
+     * Checks scope coverage AND every ceiling this authority holds, collecting
+     * every failing reason — not just the first — so a single evaluation can
+     * explain everything wrong with a request. A ceiling whose context field is
+     * absent is not asserting anything on this call and is treated as satisfied.
+     */
+    permits(scope, ctx = null) {
+        const context = ctx ?? {};
+        const reasons = [];
+        if (!this.coversScope(scope)) {
+            reasons.push(new Reason(ReasonCode.SCOPE_NOT_GRANTED, {
+                requested: scope,
+                message: `scope '${scope}' not covered by held scopes [${sortedStrings(this.scopes)
+                    .map((s) => `'${s}'`)
+                    .join(", ")}]`,
+            }));
+        }
+        // Reserved key so scoped ceilings can tell whether they apply.
+        const cctx = { ...context };
+        if (!("_scope" in cctx))
+            cctx["_scope"] = scope;
+        for (const c of this.ceilings) {
+            const decision = c.permits(cctx);
+            if (!decision.allowed)
+                reasons.push(...decision.reasons);
+        }
+        return reasons.length > 0 ? Decision.deny(reasons) : Decision.allow();
+    }
+    withTtl(ttl) {
+        return new Authority({ scopes: this.scopes, ceilings: this.ceilings, ttl });
+    }
+    // ---- wire form --------------------------------------------------------
+    toWire() {
+        return {
+            scopes: sortedStrings(this.scopes),
+            constraints: this.ceilings.map((c) => c.toWire()),
+            ttl: this.ttl,
+        };
+    }
+    static fromWire(wire) {
+        const d = toPlain(wire) ?? {};
+        const scopes = d["scopes"] ?? [];
+        const constraints = d["constraints"] ?? [];
+        const ttl = d["ttl"];
+        return new Authority({
+            scopes,
+            ceilings: constraints.map((c) => ceilingFromWire(c)),
+            ttl: typeof ttl === "number" ? ttl : null,
+        });
+    }
+    /** A stable, human-readable one-liner. */
+    describe() {
+        const scopes = sortedStrings(this.scopes).join(", ");
+        const cs = this.ceilings.map((c) => describeCeiling(c)).sort(compareCodePoints).join(", ");
+        return `scopes=[${scopes}] ceilings=[${cs}] ttl=${this.ttl}`;
+    }
+    toString() {
+        return `Authority(${this.describe()})`;
+    }
+}
+//# sourceMappingURL=authority.js.map

package/dist/esm/authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority.js","sourceRoot":"","sources":["../../src/authority.ts"],"names":[],"mappings":"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"}

package/dist/esm/canonical.d.ts

@@ -0,0 +1,91 @@
+/**
+ * canonical.ts — byte-exact interoperability with the Python implementation.
+ *
+ * Every hash, seal and signature in Attenu is taken over a canonical JSON
+ * serialisation. The Python library produces those bytes with
+ * `json.dumps(obj, sort_keys=True, separators=(",", ":"))`, whose defaults
+ * include `ensure_ascii=True`. `JSON.stringify` differs from that in three
+ * ways that would each silently break cross-language verification:
+ *
+ *   1. key order — `JSON.stringify` preserves insertion order, Python sorts;
+ *   2. non-ASCII — Python escapes every code point above U+007E as `\uXXXX`
+ *      (astral characters as a surrogate pair), `JSON.stringify` emits them raw;
+ *   3. numbers — Python distinguishes `int` from `float` (`100` vs `100.0`) and
+ *      switches to exponential notation at different magnitudes than JavaScript
+ *      (`1e-05` where `String()` gives `0.00001`).
+ *
+ * (1) and (2) are handled by `canonicalJson` below. (3) cannot be solved by a
+ * serialiser alone, because a JavaScript `number` has forgotten whether the
+ * document said `100` or `100.0`. So a document that is going to be re-hashed —
+ * a ledger or a bundle produced elsewhere — is read with `parseJson`, which
+ * keeps each number's original literal alongside its value as a `RawNumber`.
+ * `canonicalJson` re-emits that literal verbatim, so a Python-written entry
+ * hashes to the byte-identical digest here. Values created in this library are
+ * plain numbers, and `pyNumber` formats them the way Python's `json` would, so
+ * the reverse direction round-trips too.
+ */
+/** A number as it was written in the source document, plus its parsed value. */
+export declare class RawNumber {
+    readonly raw: string;
+    readonly value: number;
+    constructor(raw: string, value: number);
+    valueOf(): number;
+    toJSON(): number;
+}
+/** A JSON value that may still carry original number literals. */
+export type CJson = null | boolean | number | string | RawNumber | CJson[] | {
+    [key: string]: CJson;
+};
+/** A plain JSON value — what the rest of the library works with. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Compare two strings by Unicode code point, as Python's `sorted` does. */
+export declare function compareCodePoints(a: string, b: string): number;
+/** Sort strings by code point (Python's `sorted(list_of_str)`). */
+export declare function sortedStrings(values: Iterable<string>): string[];
+/**
+ * Format a number the way Python's `json.dumps` would.
+ *
+ * Integral values are emitted without a decimal point, matching a Python `int`.
+ * A TypeScript number cannot record that it was meant to be the float `100.0`,
+ * so such a value serialises as `100`; Python reads that back as an `int` and
+ * re-emits `100`, which keeps the chain verifiable in both directions. Values
+ * with a fractional part follow CPython's `repr`: shortest round-tripping
+ * digits, exponential notation when the decimal exponent is below -4 or at
+ * least 16, a two-digit signed exponent, and always a decimal point otherwise.
+ */
+export declare function pyNumber(n: number): string;
+/** Escape a string the way Python's `json.dumps(ensure_ascii=True)` does. */
+export declare function pyString(s: string): string;
+/**
+ * Serialise to the exact bytes Python's
+ * `json.dumps(obj, sort_keys=True, separators=(",", ":"))` produces:
+ * sorted keys, no incidental whitespace, ASCII-escaped strings.
+ *
+ * Object entries whose value is `undefined` are omitted, matching a Python dict
+ * that simply never held the key. `null` is kept — it is a value.
+ */
+export declare function canonicalJson(value: CJson | undefined): string;
+/**
+ * Serialise with sorted keys and ASCII escaping, choosing the separators.
+ *
+ * `canonicalJson` uses the compact `(",", ":")` pair every hash is taken over.
+ * The `.jsonl` ledger on disk is written with Python's DEFAULT separators
+ * (`", "` and `": "`), so a line read back by either language re-serialises to
+ * the same bytes its writer produced.
+ */
+export declare function pyJsonDumps(value: CJson | undefined, itemSeparator?: string, keySeparator?: string): string;
+/** The canonical bytes — what every hash, seal and signature is taken over. */
+export declare function canonicalBytes(value: CJson | undefined): Buffer;
+/** Strip `RawNumber` wrappers, yielding ordinary JavaScript values. */
+export declare function toPlain<T = Json>(value: CJson | undefined): T;
+/**
+ * Parse JSON, keeping every number's original literal.
+ *
+ * `JSON.parse` is not used: it discards the literal, and with it the ability to
+ * reproduce the bytes the writer hashed. Objects preserve their key order for
+ * readability; canonical serialisation sorts them anyway.
+ */
+export declare function parseJson(text: string): CJson;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/esm/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,qBAAa,SAAS;IAElB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBADb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM;IAExB,OAAO,IAAI,MAAM;IAGjB,MAAM,IAAI,MAAM;CAGjB;AAED,kEAAkE;AAClE,MAAM,MAAM,KAAK,GACb,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,GACT,KAAK,EAAE,GACP;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,CAAC;AAE7B,oEAAoE;AACpE,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEvF,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU9D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAEhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1C;AA2BD,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,aAAa,SAAO,EACpB,YAAY,SAAO,GAClB,MAAM,CAwBR;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,CAE/D;AAED,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,CAAC,CAS7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAO7C"}