attenu-guard 0.1.0

package/dist/cjs/authority.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Authority = exports.AuthorityError = void 0;
+const canonical_js_1 = require("./canonical.js");
+const ceilings_js_1 = require("./ceilings.js");
+const reasons_js_1 = require("./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.
+ */
+class AuthorityError extends Error {
+    reason;
+    detail;
+    constructor(message, reason, detail = {}) {
+        super(message);
+        this.name = "AuthorityError";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+exports.AuthorityError = AuthorityError;
+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(canonical_js_1.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(canonical_js_1.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 reasons_js_1.Reason(reasons_js_1.ReasonCode.SCOPE_NOT_GRANTED, {
+                requested: scope,
+                message: `scope '${scope}' not covered by held scopes [${(0, canonical_js_1.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 ? reasons_js_1.Decision.deny(reasons) : reasons_js_1.Decision.allow();
+    }
+    withTtl(ttl) {
+        return new Authority({ scopes: this.scopes, ceilings: this.ceilings, ttl });
+    }
+    // ---- wire form --------------------------------------------------------
+    toWire() {
+        return {
+            scopes: (0, canonical_js_1.sortedStrings)(this.scopes),
+            constraints: this.ceilings.map((c) => c.toWire()),
+            ttl: this.ttl,
+        };
+    }
+    static fromWire(wire) {
+        const d = (0, canonical_js_1.toPlain)(wire) ?? {};
+        const scopes = d["scopes"] ?? [];
+        const constraints = d["constraints"] ?? [];
+        const ttl = d["ttl"];
+        return new Authority({
+            scopes,
+            ceilings: constraints.map((c) => (0, ceilings_js_1.ceilingFromWire)(c)),
+            ttl: typeof ttl === "number" ? ttl : null,
+        });
+    }
+    /** A stable, human-readable one-liner. */
+    describe() {
+        const scopes = (0, canonical_js_1.sortedStrings)(this.scopes).join(", ");
+        const cs = this.ceilings.map((c) => (0, ceilings_js_1.describe)(c)).sort(canonical_js_1.compareCodePoints).join(", ");
+        return `scopes=[${scopes}] ceilings=[${cs}] ttl=${this.ttl}`;
+    }
+    toString() {
+        return `Authority(${this.describe()})`;
+    }
+}
+exports.Authority = Authority;
+//# sourceMappingURL=authority.js.map

package/dist/cjs/authority.js.map

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

package/dist/cjs/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/cjs/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"}