@synoi/sraid 0.2.0

package/dist/attestation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @synoi/sraid — attestation.ts
+ *
+ * L2 attestation layer: a DSSE (Dead Simple Signing Envelope) profile that
+ * carries one or more detached signatures over a SRAID object's canonical
+ * payload, with the payload TYPE structurally bound into the signed bytes.
+ *
+ * Why this exists (SRAID F7 / Adversary A4, SRAID_FOUNDATION_PUNCHLIST A3,
+ * OBJECT_MODEL_CLEANSHEET §3.2): the legacy `SignatureEnvelope` signs the
+ * bare canonical bytes with NO payload-type binding. Because every SRAID
+ * object shape (decision receipt, capability grant, memory record, identity
+ * disclosure, supply-chain attestation, …) is signed identically over its
+ * canonical bytes, a signature minted for one type could be replayed as a
+ * valid signature for a different type whose canonical bytes happen to match
+ * — a cross-type / confused-deputy hazard. DSSE closes this by signing the
+ * Pre-Authentication Encoding (PAE), which prepends the payloadType and the
+ * lengths of both fields, so the type is part of what is signed.
+ *
+ * SynOI policy (the AND rule): a SRAID attestation MUST carry BOTH an
+ * `ed25519` and an `ml-dsa-65` signature over the SAME PAE, and the verifier
+ * here requires BOTH to verify before returning `valid: true`. DSSE itself
+ * is an OR-of-signatures envelope; the both-required rule lives in this
+ * verifier and in the SRAID spec, not in DSSE. This preserves the hybrid
+ * classical + post-quantum property of the legacy scheme.
+ *
+ * Profile: JSON (`payloadType` is a media type string; `payload` is the
+ * canonical UTF-8 string). A future CBOR profile would use COSE (RFC 9052);
+ * it is reserved, not implemented here.
+ *
+ * Identity stability: signatures live in a detached `signatures[]` array and
+ * are NEVER part of the OID hash input (see `cdroContentCore` in oid.ts), so
+ * adding, rotating, or replacing a signature never changes the object's OID.
+ */
+import type { AttestationEnvelope } from './types.js';
+/** The single supported algorithm identifiers for the JSON profile. */
+export declare const ALG_ED25519 = "ed25519";
+export declare const ALG_ML_DSA_65 = "ml-dsa-65";
+/**
+ * The DSSE Pre-Authentication Encoding (PAE).
+ *
+ * Per the DSSE spec:
+ *
+ *   PAE(type, body) = "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * where:
+ *   - SP is a single ASCII space (0x20),
+ *   - LEN(x) is the ASCII-decimal byte length of x's UTF-8 encoding,
+ *   - type and body are the raw UTF-8 bytes (NOT base64).
+ *
+ * Binding the payloadType (and both lengths) into the signed bytes is what
+ * makes a signature non-transferable across object types. Returns the raw
+ * bytes to be signed/verified.
+ */
+export declare function pae(payloadType: string, payload: string | Uint8Array): Uint8Array;
+export interface VerifyAttestationInput {
+    /**
+     * The DSSE attestation envelope to verify. Its `payloadType` is bound into
+     * the PAE; its `payload` is the canonical UTF-8 string that was signed.
+     */
+    envelope: AttestationEnvelope;
+    /** Raw 32-byte Ed25519 public key. */
+    ed25519_pub: Uint8Array;
+    /** Raw ML-DSA-65 public key bytes. */
+    ml_dsa_pub: Uint8Array;
+    /**
+     * Optional. If supplied, the verifier asserts the envelope's `payloadType`
+     * equals this value before verifying signatures — an explicit type-pinning
+     * check on top of the structural PAE binding. A mismatch fails with
+     * `payload-type-mismatch`.
+     */
+    expectedPayloadType?: string;
+}
+export interface VerifyAttestationResult {
+    /** True only when BOTH required signatures verified over the same PAE. */
+    valid: boolean;
+    /**
+     * Human-readable failure reasons. Empty when valid. Possible values:
+     * 'envelope-malformed', 'payload-type-mismatch', 'missing-ed25519',
+     * 'missing-ml-dsa-65', 'ed25519-malformed', 'ml-dsa-malformed',
+     * 'ed25519-invalid', 'ml-dsa-invalid'.
+     */
+    reasons: string[];
+}
+/**
+ * Verify a hybrid DSSE attestation envelope. Returns `valid: true` only when
+ * the envelope carries BOTH an `ed25519` and an `ml-dsa-65` signature and
+ * BOTH verify against the supplied public keys over `PAE(payloadType,
+ * payload)`. The payloadType is bound into the signed bytes, so a signature
+ * minted for a different payloadType will not verify.
+ */
+export declare function verifyAttestation(input: VerifyAttestationInput): VerifyAttestationResult;
+//# sourceMappingURL=attestation.d.ts.map

package/dist/attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../src/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAwB,MAAM,YAAY,CAAA;AAE3E,uEAAuE;AACvE,eAAO,MAAM,WAAW,YAAY,CAAA;AACpC,eAAO,MAAM,aAAa,cAAc,CAAA;AAExC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAYjF;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,sCAAsC;IACtC,WAAW,EAAE,UAAU,CAAA;IACvB,sCAAsC;IACtC,UAAU,EAAE,UAAU,CAAA;IACtB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAA;IACd;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,uBAAuB,CAsExF"}

package/dist/attestation.js

@@ -0,0 +1,155 @@
+/**
+ * @synoi/sraid — attestation.ts
+ *
+ * L2 attestation layer: a DSSE (Dead Simple Signing Envelope) profile that
+ * carries one or more detached signatures over a SRAID object's canonical
+ * payload, with the payload TYPE structurally bound into the signed bytes.
+ *
+ * Why this exists (SRAID F7 / Adversary A4, SRAID_FOUNDATION_PUNCHLIST A3,
+ * OBJECT_MODEL_CLEANSHEET §3.2): the legacy `SignatureEnvelope` signs the
+ * bare canonical bytes with NO payload-type binding. Because every SRAID
+ * object shape (decision receipt, capability grant, memory record, identity
+ * disclosure, supply-chain attestation, …) is signed identically over its
+ * canonical bytes, a signature minted for one type could be replayed as a
+ * valid signature for a different type whose canonical bytes happen to match
+ * — a cross-type / confused-deputy hazard. DSSE closes this by signing the
+ * Pre-Authentication Encoding (PAE), which prepends the payloadType and the
+ * lengths of both fields, so the type is part of what is signed.
+ *
+ * SynOI policy (the AND rule): a SRAID attestation MUST carry BOTH an
+ * `ed25519` and an `ml-dsa-65` signature over the SAME PAE, and the verifier
+ * here requires BOTH to verify before returning `valid: true`. DSSE itself
+ * is an OR-of-signatures envelope; the both-required rule lives in this
+ * verifier and in the SRAID spec, not in DSSE. This preserves the hybrid
+ * classical + post-quantum property of the legacy scheme.
+ *
+ * Profile: JSON (`payloadType` is a media type string; `payload` is the
+ * canonical UTF-8 string). A future CBOR profile would use COSE (RFC 9052);
+ * it is reserved, not implemented here.
+ *
+ * Identity stability: signatures live in a detached `signatures[]` array and
+ * are NEVER part of the OID hash input (see `cdroContentCore` in oid.ts), so
+ * adding, rotating, or replacing a signature never changes the object's OID.
+ */
+import { verifyEd25519 } from './ed25519.js';
+import { decodeBase64Strict } from './internal/base64.js';
+import { verifyMlDsa65 } from './mldsa.js';
+/** The single supported algorithm identifiers for the JSON profile. */
+export const ALG_ED25519 = 'ed25519';
+export const ALG_ML_DSA_65 = 'ml-dsa-65';
+/**
+ * The DSSE Pre-Authentication Encoding (PAE).
+ *
+ * Per the DSSE spec:
+ *
+ *   PAE(type, body) = "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * where:
+ *   - SP is a single ASCII space (0x20),
+ *   - LEN(x) is the ASCII-decimal byte length of x's UTF-8 encoding,
+ *   - type and body are the raw UTF-8 bytes (NOT base64).
+ *
+ * Binding the payloadType (and both lengths) into the signed bytes is what
+ * makes a signature non-transferable across object types. Returns the raw
+ * bytes to be signed/verified.
+ */
+export function pae(payloadType, payload) {
+    const enc = new TextEncoder();
+    const typeBytes = enc.encode(payloadType);
+    const bodyBytes = typeof payload === 'string' ? enc.encode(payload) : payload;
+    const prefix = enc.encode(`DSSEv1 ${typeBytes.length} ${payloadType} ${bodyBytes.length} `);
+    const out = new Uint8Array(prefix.length + bodyBytes.length);
+    out.set(prefix, 0);
+    out.set(bodyBytes, prefix.length);
+    return out;
+}
+/**
+ * Verify a hybrid DSSE attestation envelope. Returns `valid: true` only when
+ * the envelope carries BOTH an `ed25519` and an `ml-dsa-65` signature and
+ * BOTH verify against the supplied public keys over `PAE(payloadType,
+ * payload)`. The payloadType is bound into the signed bytes, so a signature
+ * minted for a different payloadType will not verify.
+ */
+export function verifyAttestation(input) {
+    const reasons = [];
+    const env = input.envelope;
+    if (env === null ||
+        typeof env !== 'object' ||
+        typeof env.payloadType !== 'string' ||
+        env.payloadType.length === 0 ||
+        typeof env.payload !== 'string' ||
+        !Array.isArray(env.signatures)) {
+        return { valid: false, reasons: ['envelope-malformed'] };
+    }
+    if (input.expectedPayloadType !== undefined &&
+        env.payloadType !== input.expectedPayloadType) {
+        return { valid: false, reasons: ['payload-type-mismatch'] };
+    }
+    // The signed bytes: PAE binds payloadType + payload together.
+    const message = pae(env.payloadType, env.payload);
+    // Find the required hybrid pair. The AND policy: both must be present.
+    const edEntry = findSig(env.signatures, ALG_ED25519);
+    const mlEntry = findSig(env.signatures, ALG_ML_DSA_65);
+    if (!edEntry)
+        reasons.push('missing-ed25519');
+    if (!mlEntry)
+        reasons.push('missing-ml-dsa-65');
+    let edOk = false;
+    let mlOk = false;
+    if (edEntry) {
+        let edSig = null;
+        try {
+            edSig = fromBase64(edEntry.sig);
+        }
+        catch {
+            reasons.push('ed25519-malformed');
+        }
+        if (edSig) {
+            try {
+                edOk = verifyEd25519(edSig, message, input.ed25519_pub);
+            }
+            catch {
+                edOk = false;
+            }
+            if (!edOk)
+                reasons.push('ed25519-invalid');
+        }
+    }
+    if (mlEntry) {
+        let mlSig = null;
+        try {
+            mlSig = fromBase64(mlEntry.sig);
+        }
+        catch {
+            reasons.push('ml-dsa-malformed');
+        }
+        if (mlSig) {
+            try {
+                mlOk = verifyMlDsa65(mlSig, message, input.ml_dsa_pub);
+            }
+            catch {
+                mlOk = false;
+            }
+            if (!mlOk)
+                reasons.push('ml-dsa-invalid');
+        }
+    }
+    return { valid: edOk && mlOk && !!edEntry && !!mlEntry, reasons };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function findSig(sigs, alg) {
+    for (const s of sigs) {
+        if (s && typeof s === 'object' && s.alg === alg && typeof s.sig === 'string') {
+            return s;
+        }
+    }
+    return undefined;
+}
+// Strict standard base64. Throws Error('base64-malformed') on any deviation
+// (illegal char, bad length, bad padding) rather than silently truncating.
+// Both call sites wrap this in try/catch and map the throw to a *-malformed
+// reason, so verifyAttestation never throws.
+function fromBase64(s) {
+    return decodeBase64Strict(s);
+}
+//# sourceMappingURL=attestation.js.map

package/dist/attestation.js.map

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

package/dist/authority.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @synoi/sraid — authority.ts
+ *
+ * L4 authority VERIFIER for CDRO objects (the authorized axis).
+ *
+ * This is deliberately more than a shape check. Per the Adversary review
+ * (panel A6: "ship a verifier, not just a schema"), an attacker who can
+ * attach any well-shaped `authority` block to an object would otherwise
+ * forge authorization for free. So this module verifies, locally and
+ * offline, the parts of authorization that ARE locally checkable:
+ *
+ *   1. STRUCTURE  — the object carries a present, well-formed authority
+ *      block (grant reference present; decision verb, if any, is a valid
+ *      GAP verb; intent ref well-formed).
+ *   2. BINDING    — the object's authority block actually references the
+ *      supplied grant (the grant's OID matches `authority.grant_oid`),
+ *      AND the grant is itself a hash-honest CDRO whose recomputed OID
+ *      equals its claimed OID (so the grant body cannot be swapped under
+ *      a fixed OID reference).
+ *   3. SIGNATURE  — the grant carries a valid hybrid (Ed25519 + ML-DSA-65)
+ *      signature over its own content core, when grant signing material
+ *      and verifier public keys are supplied. A grant with no/invalid
+ *      signature does not authorize.
+ *   4. COVERAGE   — the grant's capability scopes cover the requested
+ *      object type / action (dotted-taxonomy match with segment-boundary
+ *      wildcards), and the grant has not expired relative to the object's
+ *      creation time. Both are computable from the bytes in hand.
+ *
+ * What this module does NOT and CANNOT do offline — stated honestly,
+ * never silently assumed (CLAIMS_DISCIPLINE):
+ *
+ *   - LIVE REVOCATION  — whether the grant has since been revoked.
+ *   - EXISTENCE        — whether the grant OID actually resolves to a
+ *                        published, retrievable grant at all (when the
+ *                        caller did not supply the grant material).
+ *
+ * Both require the OID Resolver, which is presently undeployed
+ * (SRAID_FOUNDATION_PUNCHLIST C). This module DEFINES the resolver
+ * interface (`AuthorityResolver`) and, when a resolver is supplied, calls
+ * it and folds its answer into the result — but when no resolver is
+ * supplied, the result is explicitly marked `revocation_checked: false`
+ * and `existence_checked: false` so a caller can never mistake a
+ * locally-passing verification for a live one.
+ *
+ * DELEGATION CHAINS (`verifyDelegationChain`, K2) — VERIFY-ONLY. This module
+ * also carries a synchronous, offline delegation-chain verifier. It is
+ * deliberately scoped to verification with NO enforcement wiring and NO
+ * resolver: the caller supplies the ordered ancestors and the per-link
+ * verifier keys, and the function makes NO live claim. It ALWAYS returns
+ * `revocation_checked: false`, `not_revoked: false`, and
+ * `existence_checked: false` — those fields are LITERAL-TYPED `false` so the
+ * type system itself forbids a future edit from quietly asserting a live,
+ * resolver-backed claim from an offline function (CLAIMS_DISCIPLINE made
+ * structural). Synchronicity is intentional: with no Promise overload there is
+ * no place for a resolver call, which is what makes the no-live-claim
+ * guarantee structural rather than merely documented.
+ */
+import type { CDRO } from './types.js';
+/**
+ * Match a capability `target` against a grant `pattern`. Pure string logic,
+ * re-stated here so L0 stays dependency-free (the same rule lives in
+ * `@synoi/gap-types` `capabilityMatches`; L0 must not depend on L3).
+ *
+ *   - exact match → true
+ *   - '*' → match-all
+ *   - 'skill.*' matches 'skill.create' and deeper (segment-boundary only).
+ *     A non-boundary 'admin.us*' must NOT match 'admin.users.delete'
+ *     (privilege-escalation footgun) — only a '.'-anchored '*' is a wildcard.
+ */
+export declare function capabilityCovers(pattern: string, target: string): boolean;
+/**
+ * The live-state interface that the OID Resolver implements. It is the ONLY
+ * source of truth for the two properties that cannot be checked offline:
+ * whether a grant currently exists (resolves) and whether it has been
+ * revoked. RESOLVER-DEPENDENT: undeployed today
+ * (SRAID_FOUNDATION_PUNCHLIST C). Defined here so callers and a future
+ * resolver agree on the contract; verifyAuthority works without it but
+ * marks the corresponding result fields as not-checked.
+ */
+export interface AuthorityResolver {
+    /**
+     * Resolve a grant OID to its current status. Implementations should
+     * return `{ exists: false }` for an unknown OID and `{ exists: true,
+     * revoked: true, revoked_at_ms }` for a revoked one.
+     */
+    resolveGrantStatus(grantOid: string): Promise<GrantStatus> | GrantStatus;
+}
+export interface GrantStatus {
+    /** Whether the grant OID resolves to a known, published grant. */
+    exists: boolean;
+    /** Whether the grant has been revoked. Only meaningful when `exists`. */
+    revoked?: boolean;
+    /** When the revocation took effect, if revoked. */
+    revoked_at_ms?: number;
+}
+export interface VerifyAuthorityInput {
+    /**
+     * The object whose authority block is being verified. Its `authority`
+     * field is read; the object's `type` is used as the action target for the
+     * coverage check unless `action` overrides it.
+     */
+    object: CDRO;
+    /**
+     * The capability / action the object claims to perform, for the coverage
+     * check. Defaults to `object.type`. For an Althing receipt this is
+     * typically the invoked capability (e.g. `email.bulk_delete`).
+     */
+    action?: string;
+    /**
+     * The authorizing grant CDRO, when available. Supplying it enables the
+     * BINDING, SIGNATURE, and COVERAGE checks. Omit it to do STRUCTURE-only
+     * verification (then `grant_supplied: false`).
+     */
+    grant?: CDRO<GrantBodyShape>;
+    /** Verifier public keys for the grant's hybrid signature. */
+    grant_ed25519_pub?: Uint8Array;
+    grant_ml_dsa_pub?: Uint8Array;
+    /**
+     * Expected DSSE payloadType for the grant's attestation envelope. Defaults
+     * to `'application/vnd.synoi.sraid+json'`. Override when the grant was
+     * issued with a custom media type.
+     */
+    grant_payload_type?: string;
+    /**
+     * Optional live-state resolver. When supplied, revocation + existence are
+     * checked and folded into the result; when omitted those remain
+     * explicitly unchecked (resolver-dependent).
+     */
+    resolver?: AuthorityResolver;
+}
+/**
+ * The minimum grant body shape this verifier reads for coverage + expiry.
+ * A superset of `@synoi/gap-types` `CapabilityGrantBody`; kept structural so
+ * L0 does not depend on L3.
+ */
+export interface GrantBodyShape {
+    capability_scopes?: Array<{
+        capability?: unknown;
+    }>;
+    expires_at_ms?: number | null;
+    /**
+     * Issuer of this grant. Mirrors the gateway `CapabilityGrantBody.granted_by`
+     * (synoi-gateway/src/gap/types.ts). VERIFY-ONLY: read by
+     * `verifyDelegationChain` to check that a child's issuer equals its parent's
+     * grantee. Kept OPTIONAL/structural so L0 stays L3-independent.
+     */
+    granted_by?: string;
+    /**
+     * Subject this grant is issued to. Mirrors the gateway
+     * `CapabilityGrantBody.grantee.actor_oid`. VERIFY-ONLY: a child grant chains
+     * under this grant iff `child.granted_by === this.grantee.actor_oid`.
+     */
+    grantee?: {
+        actor_oid?: string;
+    };
+    /**
+     * OID of the parent grant in a delegation chain. Absent/null = a root grant.
+     * VERIFY-ONLY linkage field; it is NOT consulted for any enforcement here.
+     * The chain order and ancestry are caller-supplied to `verifyDelegationChain`
+     * (the verifier never fetches), so this is informational/auditable, not a
+     * resolution hook.
+     */
+    parent_grant_oid?: string | null;
+}
+export interface VerifyAuthorityResult {
+    /**
+     * True only when every LOCALLY CHECKABLE step that was attempted passed.
+     * NOTE: this is `false` for `valid` does NOT imply the grant is revoked;
+     * read the per-check fields. Crucially, `authorized === true` from this
+     * function means "locally authorized" — it is NOT a claim about live
+     * revocation unless `revocation_checked` is also true.
+     */
+    authorized: boolean;
+    /** Structure check: authority block present + well-formed. */
+    structure_ok: boolean;
+    /** Whether a grant was supplied (enables binding/signature/coverage). */
+    grant_supplied: boolean;
+    /** Binding check: object.authority.grant_oid === grant's recomputed OID. */
+    binding_ok: boolean;
+    /** Signature check: grant carries a valid hybrid signature (when keys given). */
+    signature_ok: boolean;
+    /** Whether signature was actually checked (keys + grant present). */
+    signature_checked: boolean;
+    /** Coverage check: grant scope covers the action AND grant not expired. */
+    coverage_ok: boolean;
+    /** RESOLVER-DEPENDENT — true only if a resolver confirmed the grant exists. */
+    existence_checked: boolean;
+    existence_ok: boolean;
+    /** RESOLVER-DEPENDENT — true only if a resolver confirmed not-revoked. */
+    revocation_checked: boolean;
+    not_revoked: boolean;
+    /** Human-readable failure reasons. Empty when fully authorized. */
+    reasons: string[];
+}
+/**
+ * Verify the authority of a CDRO object. Synchronous local checks plus an
+ * optional resolver call. When a resolver is supplied this returns a
+ * Promise; otherwise it returns the result directly.
+ */
+export declare function verifyAuthority(input: VerifyAuthorityInput & {
+    resolver?: undefined;
+}): VerifyAuthorityResult;
+export declare function verifyAuthority(input: VerifyAuthorityInput & {
+    resolver: AuthorityResolver;
+}): Promise<VerifyAuthorityResult>;
+/**
+ * Hard cap on delegation depth. Checked BEFORE any hashing or signature work,
+ * so an over-long chain is a cheap rejection (DoS guard) and never triggers
+ * crypto. A chain of `links.length > MAX_DELEGATION_DEPTH` fails closed.
+ */
+export declare const MAX_DELEGATION_DEPTH = 8;
+/** The hybrid verifier public keys for one link's issuer. */
+export interface LinkPubkeys {
+    /** Raw 32-byte Ed25519 public key. */
+    ed25519: Uint8Array;
+    /** Raw ML-DSA-65 public key bytes. */
+    ml_dsa: Uint8Array;
+}
+/**
+ * Per-hop result. Index `i` describes child `links[i]` verified UNDER parent
+ * `links[i+1]`. The terminal link (root) has no parent hop, so `per_hop` has
+ * `depth - 1` entries.
+ */
+export interface HopResult {
+    /** Index of the child link in the leaf->root `links` array. */
+    child_index: number;
+    /** child.body.granted_by === parent.body.grantee.actor_oid. */
+    granted_by_ok: boolean;
+    /** Every child scope is covered by some parent scope (no widening). */
+    attenuation_ok: boolean;
+    /** Child expiry does not widen the parent's (monotone narrowing). */
+    expiry_ok: boolean;
+}
+export interface VerifyDelegationChainInput {
+    /** The leaf grant (most-attenuated, end of the chain). */
+    leaf: CDRO<GrantBodyShape>;
+    /**
+     * Ancestors, ordered leaf-adjacent -> root: the leaf's parent first, the
+     * root grant last. The full chain is `links = [leaf, ...ancestors]`, so
+     * `links[i]` is the child of `links[i+1]` and `links[links.length-1]` is the
+     * terminal root grant.
+     */
+    ancestors: CDRO<GrantBodyShape>[];
+    /**
+     * Hybrid verifier keys, index-aligned to `links` (so `linkPubkeys[i]` is the
+     * issuer key of `links[i]`). Caller-supplied: the verifier never fetches
+     * keys. `linkPubkeys[links.length-1]` MUST equal `rootPubkeys`.
+     */
+    linkPubkeys: LinkPubkeys[];
+    /**
+     * The trusted root principal's keys. The terminal link's signer key MUST
+     * deep-equal these, else the chain does not anchor to a known root.
+     */
+    rootPubkeys: LinkPubkeys;
+    /**
+     * Pin the DSSE payloadType for every link. Defaults to the SRAID grant
+     * media type.
+     */
+    attestationPayloadType?: string;
+    /**
+     * Optional requested action. When supplied, the leaf grant's capability
+     * scopes MUST cover this action (GATE 5). If uncovered, `authorized` is
+     * false and `action_ok` is false. When omitted, GATE 5 is skipped and
+     * `action_checked` is false (vacuous pass — existing callers unaffected).
+     */
+    action?: string;
+}
+/**
+ * Result of `verifyDelegationChain`. Mirrors `VerifyAuthorityResult`'s
+ * honesty discipline: the three live-claim fields are LITERAL-TYPED `false`
+ * so the type system itself forbids a future edit from quietly asserting a
+ * resolver-backed claim from this offline, verify-only function.
+ */
+export interface VerifyDelegationChainResult {
+    /** True iff every hop check, every link signature, and the root anchor passed. */
+    authorized: boolean;
+    /** Number of grants in the chain (`links.length`). */
+    depth: number;
+    /** depth >= 1 && depth <= MAX_DELEGATION_DEPTH. Checked before any crypto. */
+    depth_ok: boolean;
+    /** Every child.granted_by === parent.grantee.actor_oid. */
+    links_ok: boolean;
+    /** Every child scope covered by some parent scope, all hops (no widening). */
+    attenuation_ok: boolean;
+    /** Monotone expiry narrowing, all hops. */
+    expiry_ok: boolean;
+    /** Every link carried a valid hybrid DSSE attestation over its content core. */
+    signatures_ok: boolean;
+    /** False if any link lacked an attestation, or if no crypto ran (over-depth). */
+    signatures_checked: boolean;
+    /** Every link OID is hash-honest (recomputed === claimed). */
+    oids_ok: boolean;
+    /** Terminal link signer key == rootPubkeys. */
+    root_ok: boolean;
+    /**
+     * True iff the requested action is covered by some leaf scope.
+     * When `action` was not supplied, this is true (vacuous pass).
+     */
+    action_ok: boolean;
+    /**
+     * True when an `action` was supplied and GATE 5 ran; false when the caller
+     * omitted `action` (GATE 5 skipped).
+     */
+    action_checked: boolean;
+    /** ALWAYS false — verify-only, no live revocation claim (literal type). */
+    revocation_checked: false;
+    /** ALWAYS false — verify-only (literal type). */
+    not_revoked: false;
+    /** ALWAYS false — no resolver, no existence claim (literal type). */
+    existence_checked: false;
+    /** Per-hop breakdown; index i = child links[i] under parent links[i+1]. */
+    per_hop: HopResult[];
+    /** Human-readable failure reasons. Empty when fully authorized. */
+    reasons: string[];
+}
+/**
+ * Verify a delegation chain OFFLINE (K2). VERIFY-ONLY: there is no enforcement
+ * wiring and no resolver — the caller supplies the ordered ancestors and the
+ * per-link verifier keys, and this function makes NO live claim. It ALWAYS
+ * returns `revocation_checked: false` and `existence_checked: false`; those
+ * remain RESOLVER-DEPENDENT (SRAID_FOUNDATION_PUNCHLIST C) and are explicitly
+ * out of scope here. The function is synchronous (no Promise overload), which
+ * is what makes "no live claim" structural rather than merely documented.
+ *
+ * The gate runs in this fixed order; DEPTH is checked BEFORE any crypto:
+ *
+ *   GATE 0  DEPTH CAP    — depth in [1, MAX_DELEGATION_DEPTH]; else return with
+ *                          NO hashing or signature work (cheap DoS guard).
+ *   GATE 1  OID HONESTY  — every link's recomputed content-core OID equals its
+ *                          claimed `oid` (rejects a body swapped under a fixed
+ *                          OID reference).
+ *   GATE 2  PER-HOP      — for each child links[i] under parent links[i+1]:
+ *                          (a) granted_by linkage, (b) scope attenuation (every
+ *                          child scope covered by some parent scope; empty
+ *                          child scopes = FAIL — a grant of nothing is not
+ *                          vacuously attenuated), (c) expiry monotone narrowing
+ *                          (null parent = unbounded; null child under a bounded
+ *                          parent = widening = FAIL).
+ *   GATE 3  SIGNATURES   — every link carries a hybrid DSSE attestation
+ *                          (ed25519 AND ml-dsa-65) over PAE(payloadType,
+ *                          payload), and the attestation payload equals
+ *                          canonicalize(cdroContentCore(link)) (payload-swap
+ *                          guard). A missing attestation sets signatures_checked
+ *                          false for that link and fails.
+ *   GATE 4  ROOT ANCHOR  — the terminal link's issuer key deep-equals
+ *                          rootPubkeys.
+ *
+ * `authorized` is the AND of every gate.
+ */
+export declare function verifyDelegationChain(input: VerifyDelegationChainInput): VerifyDelegationChainResult;
+//# sourceMappingURL=authority.d.ts.map

package/dist/authority.d.ts.map

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