@ziffer-io/verify 0.1.1 → 0.2.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAa,MAAM,YAAY,CAAC;AACjE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,GAKb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,cAAc,EACd,YAAY,EACZ,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,QAAQ,EACR,aAAa,GAId,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAa,MAAM,YAAY,CAAC;AACjE,OAAO,EACL,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,QAAQ,EACR,eAAe,GAGhB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,UAAU,EACV,aAAa,EACb,WAAW,EACX,YAAY,GAOb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EACzB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,GAKb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,cAAc,EACd,YAAY,EACZ,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,QAAQ,EACR,aAAa,GAId,MAAM,aAAa,CAAC"}

package/dist/quorum.d.ts

@@ -0,0 +1,245 @@
+/**
+ * §9.3 step 7b -- the AT-* quorum and §8.6b's AB-*, run in the CUSTOMER's own
+ * process against the CUSTOMER's own signed bundle.
+ *
+ * # Why this exists (ACP-406 gap 1)
+ *
+ * Until this module, a customer verifying a ZIFFER receipt checked the
+ * signature and the bindings and **trusted us for the approvals**: the header
+ * table in `verify.ts` said "7b -- NO, needs the attester registry". A
+ * compromised receipt-signing substrate could therefore emit a floor-HIGH
+ * receipt carrying fabricated `attestation_digests`, and every customer-side
+ * verifier would accept it. The registry is in the customer's OWN signed
+ * bundle -- the tree they already load for `policy_bundle_hash` -- so nothing
+ * about that trust was necessary. This is the third implementation of the
+ * step, after `reference/src/acp_executor.py::_verify_quorum` and
+ * `crates/acp-decision/src/quorum.rs`, and the clause names are theirs.
+ *
+ * # AT-9 is TWO requirements and they fail closed on disjoint inputs
+ *
+ * 1. The threshold is **recomputed** from the signed bundle's `quorum_k`
+ *    (PB-6) and never read from an attestation. Through v1.3.14 the reference
+ *    read `entries[0].required_count` -- asking the party under verification
+ *    how many signatures to demand -- and one compromised attester key signing
+ *    one object carrying `required_count: 1` executed a floor-HIGH action.
+ * 2. **Every** entry's `required_count` must equal `quorum_k`. That is a
+ *    CONSENT check (AT-3), not a threshold one: two humans approving while both
+ *    objects say `3` means they approved believing a third reviewer existed.
+ *
+ * Deleting (2) cannot lower a quorum; deleting (1) cannot detect an attester
+ * who signed under a different stated threshold. Keeping only (1) satisfies
+ * INV-1-HIGH while silently executing actions no attester agreed to.
+ *
+ * # What this CANNOT check customer-side, and why -- read before trusting a pass
+ *
+ * These are absences, not agreements. Each one is a step of §9.3 this package
+ * does not run, and each is disclosed here rather than approximated:
+ *
+ * - **Whether a quorum was required at all.** §9.3 step 7 recomputes the
+ *   floor-only risk from the bundle's `floors.json` and `risk_functions.json`;
+ *   this package does not grade, so it cannot know that a receipt carrying an
+ *   EMPTY attestation list should have carried a quorum. A receipt with no
+ *   attestations passes 7b vacuously (AB-1's own note covers the legitimate
+ *   LOW/MEDIUM case) and {@link verifyQuorum} returns `null` so the caller can
+ *   see that nothing was verified. **Reading `risk_level_floor_only` off the
+ *   receipt instead would be X1 -- the defect where a compromised issuer
+ *   asserting `LOW` suppressed attestation entirely** -- so it is not read.
+ * - **`obj.floor_only_risk` against the recomputed grade** (7b(iii), TR-8), for
+ *   the same reason: there is no recomputed grade here to compare against.
+ * - **Single-use of the recomputed `attestation_id`** (7b(v), CL-3). That needs
+ *   a linearizable Consumption Ledger and this package holds none. Replay
+ *   protection that forgets is not replay protection, so it is named rather
+ *   than half-built.
+ * - **HM-4 (f)'s stored signature counter** is `T` at this boundary: the caller
+ *   hands in what it stored and MUST persist what {@link QuorumOutcome}
+ *   returns. A caller passing an empty map every time has switched (f) off for
+ *   a credential that has signed before.
+ *
+ * # One deliberate NARROWING beyond both engine implementations
+ *
+ * AT-1 says role membership "is resolved against the attester registry", and
+ * neither engine implementation resolves it: `quorum.rs` records that
+ * `AttesterRole` is generated and read by nothing, and the Python reference has
+ * no role field at all. This one does, because the customer's registry carries
+ * `role` and their bundle is the authority on who may approve: an entry counts
+ * toward the quorum only if its attester's REGISTRY role is named in the
+ * object's `required_roles`. An empty list means the rule demanded a quorum and
+ * named no role, so any enrolled attester satisfies it (AT-1 as amended in
+ * v1.3.32, ACP-308) -- which is byte-for-byte the engine's behaviour, and is the
+ * case every ZIFFER deployment is in today except where the policy engine sets
+ * `["approver"]`.
+ *
+ * This is a NARROWER acceptance, never a wider one, and it is stated because a
+ * third implementation that refuses what the other two accept is a divergence
+ * even when it is the safer side. Its strength is bounded and that is disclosed
+ * too: `required_roles` is read from the OBJECT (class **B** -- signed by the
+ * attester, evidence of what they were shown), because the bundle names no
+ * per-rule role list for it to be recomputed from. A compromised issuer that
+ * writes an empty list degrades this check to the engine's behaviour and no
+ * further.
+ *
+ * # Suite 12 classification -- R / B / T for every control input read here
+ *
+ * | input | class | why |
+ * | --- | :---: | --- |
+ * | `quorumK` | **R** | from the signed bundle, never an attestation (AT-9) |
+ * | attester keys and credentials | **R** | read out of the signed registry after the bundle's own signature checked; `rpId` above all, because HM-4 (c) compares the assertion's origin against THIS and an origin taken from the assertion would compare a value with itself |
+ * | `floor` | **R** | the signed manifest's `min_suite` (CR-4) |
+ * | `policyBundleHash`, `bundleEpoch` | **R** | the bundle the caller trusts; the object's copies are compared against them (7b(iii)) |
+ * | the eleven AT-1 fields | **B** | the attester signature covers the derived id, which covers the whole object |
+ * | `obj.proposal_hash` | **B** | and compared against the hash this verifier recomputed from the caller's own proposal bytes (Y1) |
+ * | `obj.required_count` | **B** | and compared against `quorumK` (AT-9's consent half) |
+ * | `obj.required_roles` | **B** | signed, and resolved against the registry; see the narrowing above for what it does NOT prove |
+ * | `entry.attester` | **B** | a name SELECTS a key; the signature establishes identity (ACK-4) |
+ * | `entry.attestation_id` | **R** | derived; a transmitted value is compared, never used (Y1b) |
+ * | `attestation_digests` | **B** | inside the signed receipt body (AB-5), and each entry's digest is recomputed from the received bytes (AB-1) |
+ * | `entry.kind` | **B** | bound by the entry digest under the receipt signature (AB-1). **NARROWED RESIDUAL, not closed**: the attester does not sign `kind`, so the ISSUER still chooses per entry whose signature counts as an approval |
+ * | `webauthnCounters` | **T** | the caller's stored counters; this package holds no ledger and says so above |
+ */
+import { type Suite } from './suite.js';
+/**
+ * AT-8b: the Attestation Object schema is CLOSED. Exactly this field set, no
+ * more and no less.
+ *
+ * An unknown field is refused rather than ignored and a missing one is never
+ * defaulted (Z4). Normalising either would let an issuer add a field a future
+ * verifier reads, or drop one this verifier checks, without invalidating a
+ * signature that covers only what is present.
+ */
+export declare const AT1_FIELDS: readonly string[];
+/** A machine attester's hybrid pair, decoded from the signed registry. */
+export interface HybridAttester {
+    readonly kind: 'hybrid';
+    /** Ed25519 verification key, 32 raw bytes. */
+    readonly classical: Uint8Array;
+    /** ML-DSA-65 verification key, 1,952 raw bytes. */
+    readonly pq: Uint8Array;
+    /** The registry's `role`, or null where the entry declares none. */
+    readonly role: string | null;
+}
+/**
+ * HM-1 -- a human attester's enrolled credential, as the SIGNED registry
+ * carries it.
+ *
+ * No private key is reachable from here: `publicKey` is the COSE_Key the
+ * authenticator returned at registration and the private half is on the
+ * person's phone or security key. That is the strongest custody statement in
+ * this package, and the one a software key file could never make.
+ */
+export interface WebauthnAttester {
+    readonly kind: 'webauthn';
+    /** The approval origin's host. Signed policy (HM-4 (c), (d)). */
+    readonly rpId: string;
+    /** What the Consumption Ledger keys the signature counter by (HM-4 (f)). */
+    readonly credentialId: string;
+    /** The COSE_Key bytes, base64-decoded by the caller's bundle loader. */
+    readonly publicKey: Uint8Array;
+    /** `webauthn-es256` or `webauthn-ed25519` (HM-1). */
+    readonly alg: string;
+    /** The registry's `role`, or null where the entry declares none. */
+    readonly role: string | null;
+}
+/**
+ * One registry identity: a machine's hybrid pair or a person's WebAuthn
+ * credential.
+ *
+ * A TAGGED union here because it is a tagged union in the signed document
+ * (`attesters.schema.json`, v1.3.30). A kind guessed from which fields are
+ * present is how a machine entry that lost its `pq` leg reads as a human.
+ */
+export type AttesterCredential = HybridAttester | WebauthnAttester;
+/**
+ * The quorum policy. **Every field comes from the customer's SIGNED bundle**,
+ * and nothing here may be sourced from the receipt or from an Attestation
+ * Object -- that is AT-9 for `quorumK`, PB-KEY for `attesters`, CR-4 for the
+ * floor (taken from the {@link import('./verify.js').TrustAnchor}'s `minSuite`,
+ * so the package has one definition of the floor and not two).
+ */
+export interface QuorumPolicy {
+    /** PB-6. The number of DISTINCT approvals a floor-HIGH action requires. */
+    readonly quorumK: number;
+    /**
+     * The attester registry: identity -> credential. PB-7 distinctness over the
+     * keys is the BUNDLE LOADER's obligation and is assumed to have run; a second
+     * copy here would be two definitions of one rule, so this module depends on
+     * that check rather than restating it.
+     */
+    readonly attesters: ReadonlyMap<string, AttesterCredential>;
+    /** AT-10: per-identity enrolled assurance, from the signed registry. */
+    readonly assurances: ReadonlyMap<string, string>;
+    /** AT-10: the registry's floor (`min_attester_assurance`). */
+    readonly minAssurance: string;
+    /** Step 4's trusted bundle hash, compared against each object's (7b(iii)). */
+    readonly policyBundleHash: string;
+    /** Step 4's trusted bundle epoch, compared against each object's (7b(iii)). */
+    readonly bundleEpoch: number;
+    /**
+     * HM-4 (f): the signature counter this verifier has STORED per
+     * `credential_id`. **T at this package's boundary** -- see the module header.
+     * A credential absent from the map reads as 0, which is what a credential
+     * that has never been seen has.
+     */
+    readonly webauthnCounters?: ReadonlyMap<string, number>;
+}
+/** What {@link verifyQuorum} concluded. */
+export interface QuorumOutcome {
+    /** The operator, from the VERIFIED objects (Y4) -- never the receipt body. */
+    readonly operator: string;
+    /** The distinct attesters whose approvals were counted, sorted. */
+    readonly approvals: readonly string[];
+    /**
+     * HM-4 (f): the counter each credential's assertion carried, by
+     * `credential_id`. **The caller MUST persist these**; a verifier that accepts
+     * an assertion and does not advance the stored counter has accepted the same
+     * assertion twice.
+     */
+    readonly webauthnCounters: ReadonlyMap<string, number>;
+}
+/** The values every attestation is checked against, established by the caller. */
+export interface DecisionBasis {
+    /** The hash this verifier recomputed from the caller's own proposal bytes. */
+    readonly proposalHash: string;
+    /** The receipt's `issued_at`, already parsed at step 5, epoch seconds. */
+    readonly receiptIssuedAt: number;
+    /** The CR-4 floor from the signed manifest, as a parsed suite. */
+    readonly floor: Suite;
+}
+/**
+ * AT-8a -- derive an Attestation Object's id from its canonical bytes.
+ * **Derived, never read**: the id names a binding, and a transmitted name for a
+ * binding is not evidence of one (Y1b).
+ */
+export declare function attestationId(obj: unknown): string;
+/**
+ * AB-1 -- the receipt's commitment to ONE attestation entry.
+ *
+ * ENTRY-SCOPED, NEVER OBJECT-SCOPED, and this is the whole trap.
+ * {@link attestationId} already exists and is `h(obj)` -- reusing it here is the
+ * obvious move and it is wrong. {@link AT1_FIELDS} is closed over the OBJECT: it
+ * contains no `kind`, no `attester` and no `sig`. Quorum composition reads
+ * `kind` and `attester` from the ENTRY and the attester signs neither, so an
+ * object-scoped digest lets an attacker on the transport path flip `kind` from
+ * `confirmation` to `approval` while every digest still matches.
+ *
+ * The two identifiers MUST NOT be merged: `attestation_id` is what a ledger
+ * consumes for single-use under CL-3, because the same object replayed inside a
+ * different entry is still a replay. This digest is what the receipt authorised,
+ * byte for byte.
+ */
+export declare function entryDigest(entry: unknown): string;
+/**
+ * §9.3 step 7b over the attestations travelling beside one receipt.
+ *
+ * @param policy   the customer's own signed-bundle quorum policy.
+ * @param basis    the values recomputed by `verifyReceipt` before this runs.
+ * @param entries  `receipt.attestations`, as parsed JSON.
+ * @param digests  `receipt.attestation_digests`, as parsed JSON.
+ * @returns the outcome, or `null` when no attestations travelled and none were
+ *          committed to -- the vacuous LOW/MEDIUM case of AB-1's own note.
+ *          `null` means "nothing was verified", never "a quorum held": see the
+ *          module header on why this package cannot tell that a quorum was
+ *          REQUIRED.
+ * @throws  {@link Refusal} with the engine's clause names.
+ */
+export declare function verifyQuorum(policy: QuorumPolicy, basis: DecisionBasis, entries: unknown, digests: unknown): QuorumOutcome | null;
+//# sourceMappingURL=quorum.d.ts.map

package/dist/quorum.d.ts.map

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