@motebit/crypto 1.1.0 → 1.2.0

package/dist/deletion-certificate.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Deletion certificate — sign + verify for the three retention shapes.
+ *
+ * Permissive floor (Apache-2.0). Zero monorepo dependencies — types
+ * mirror `@motebit/protocol`'s discriminated union; primitives route
+ * through `@motebit/crypto/suite-dispatch`.
+ *
+ * Three arms in one union (`@motebit/protocol :: DeletionCertificate`):
+ *
+ *   - `mutable_pruning` and `consolidation_flush` — multi-signature
+ *     certs (subject / operator / delegate / guardian, at-least-one
+ *     required by the reason-table). Each present signature covers the
+ *     same canonical bytes: `canonicalJson(cert minus all *_signature
+ *     fields)`. Pattern matches identity-v1 §3.8.1 dual-signature
+ *     succession (one canonical payload, multiple verifiable signers).
+ *
+ *   - `append_only_horizon` — single-issuer signature plus witness
+ *     signatures. Both the issuer and every witness sign the same
+ *     `canonicalJson(cert minus signature)`. Witness array is part of
+ *     the signed body — a forged witness fails verification.
+ *
+ * Verification dispatches by `kind`. Reason × signer × mode table
+ * (decision 5) gates which signer compositions are admissible. Each
+ * admissible signature is then cryptographically verified through
+ * `verifyBySuite`.
+ */
+import type { DeletionCertificate, HorizonWitness, HorizonWitnessRequestBody, SuiteId } from "@motebit/protocol";
+/** The cryptosuite every deletion certificate signs under today. */
+export declare const DELETION_CERTIFICATE_SUITE: SuiteId;
+/**
+ * Filing window for `WitnessOmissionDispute` (retention phase 4b-3).
+ * A dispute MUST be filed within 24h of the cert's `issued_at`;
+ * `verifyWitnessOmissionDispute` rejects beyond this window. Mirrors
+ * the 24h cadence of `spec/dispute-v1.md` §7.5 (filing / withdrawal /
+ * appeal windows).
+ */
+export declare const WITNESS_OMISSION_DISPUTE_WINDOW_MS: number;
+type DeploymentMode = "sovereign" | "mediated" | "enterprise";
+/** Result of verifying a deletion certificate. Fail-closed: any failure → `valid: false`. */
+export interface DeletionCertificateVerifyResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    /** Per-step breakdown — useful for debugging and audit display. */
+    readonly steps: {
+        readonly reason_table_satisfied: boolean;
+        readonly subject_signature_valid: boolean | null;
+        readonly operator_signature_valid: boolean | null;
+        readonly delegate_signature_valid: boolean | null;
+        readonly guardian_signature_valid: boolean | null;
+        /** Horizon-arm only: issuer signature on the cert body. */
+        readonly horizon_issuer_signature_valid: boolean | null;
+        /** Horizon-arm only: count of witness signatures that verified. */
+        readonly horizon_witnesses_valid_count: number | null;
+        /** Horizon-arm only: count of witness signatures present. */
+        readonly horizon_witnesses_present_count: number | null;
+    };
+}
+/**
+ * Resolver context for the verifier. Callers supply the public-key
+ * resolution paths the cert's signers reference. Resolvers return
+ * `null` when the key cannot be resolved (unknown id, registry miss);
+ * the verifier rejects fail-closed in that case.
+ *
+ * The guardian signature embeds its own public key (`guardian_public_key`),
+ * so no guardian resolver is needed — the verifier does cross-check that
+ * the embedded key matches the motebit's declared guardian via the
+ * `validateGuardianBinding` callback when supplied.
+ */
+export interface DeletionCertificateVerifyContext {
+    /** Resolve a motebit's identity Ed25519 public key (32 bytes). */
+    readonly resolveMotebitPublicKey: (motebitId: string) => Promise<Uint8Array | null>;
+    /** Resolve an operator's Ed25519 public key (32 bytes). */
+    readonly resolveOperatorPublicKey: (operatorId: string) => Promise<Uint8Array | null>;
+    /**
+     * Optional cross-check that an embedded `guardian_public_key` actually
+     * is the declared guardian for the cert's subject motebit. When
+     * absent, the verifier verifies the signature against the embedded
+     * key without checking the binding.
+     */
+    readonly validateGuardianBinding?: (targetMotebitId: string | undefined, guardianPublicKeyHex: string) => Promise<boolean>;
+    /**
+     * Optional declared deployment mode. When supplied, the verifier
+     * additionally checks the cert's reason against
+     * `REASON_TABLE[reason].modes`. When absent, mode-checking is skipped
+     * (the reason × signer table still applies).
+     */
+    readonly deploymentMode?: DeploymentMode;
+}
+/**
+ * Compute the canonical signing bytes for a `mutable_pruning` or
+ * `consolidation_flush` cert. Strips every `*_signature` field so all
+ * present signers sign identical bytes — matches identity-v1 §3.8.1's
+ * dual-signature canonical payload.
+ */
+export declare function canonicalizeMultiSignatureCert(cert: Extract<DeletionCertificate, {
+    kind: "mutable_pruning" | "consolidation_flush";
+}>): Uint8Array;
+/**
+ * Compute the canonical signing bytes for an `append_only_horizon`
+ * cert's ISSUER signature. Strips only `signature`. The issuer commits
+ * to the full body — including every witness's signature in
+ * `witnessed_by` — so a forged witness fails verification at the
+ * issuer signature step (the body the issuer signed no longer matches
+ * the post-tampering body).
+ */
+export declare function canonicalizeHorizonCert(cert: Extract<DeletionCertificate, {
+    kind: "append_only_horizon";
+}>): Uint8Array;
+/**
+ * Compute the canonical signing bytes for a WITNESS signature on an
+ * `append_only_horizon` cert. Strips both `signature` and
+ * `witnessed_by` so witnesses can co-sign asynchronously without
+ * needing to know each other's signatures.
+ *
+ * Witness's identity is bound to the signature via the public key
+ * used at verification (resolved from `witnessed_by[i].motebit_id`).
+ * The cert body's other fields (subject, store_id, horizon_ts,
+ * issued_at, federation_graph_anchor) make two distinct horizon
+ * advances produce distinct signing bytes, so a witness signature
+ * cannot be relayed to a different cert.
+ *
+ * The issuer's separate signature commits to the assembled witness
+ * array — that's the binding that makes a forged or substituted
+ * witness detectable.
+ */
+export declare function canonicalizeHorizonCertForWitness(cert: Extract<DeletionCertificate, {
+    kind: "append_only_horizon";
+}>): Uint8Array;
+/**
+ * Sign a `mutable_pruning` or `consolidation_flush` cert as the
+ * subject (motebit identity key). Adds the `subject_signature` block.
+ *
+ * Callers compose: sign as subject → optionally sign as operator → emit.
+ * Each signing step appends a signature block; the canonical bytes are
+ * recomputed from the body each time, so signatures are commutative
+ * (any signing order produces identical bytes for every signer).
+ */
+export declare function signCertAsSubject<T extends Extract<DeletionCertificate, {
+    kind: "mutable_pruning" | "consolidation_flush";
+}>>(cert: T, motebitId: string, privateKey: Uint8Array): Promise<T>;
+/** Sign a multi-signature cert as the operator. */
+export declare function signCertAsOperator<T extends Extract<DeletionCertificate, {
+    kind: "mutable_pruning" | "consolidation_flush";
+}>>(cert: T, operatorId: string, privateKey: Uint8Array): Promise<T>;
+/** Sign a multi-signature cert as a delegate (multi-hop authorization). */
+export declare function signCertAsDelegate<T extends Extract<DeletionCertificate, {
+    kind: "mutable_pruning" | "consolidation_flush";
+}>>(cert: T, delegateMotebitId: string, delegationReceiptId: string, privateKey: Uint8Array): Promise<T>;
+/** Sign a multi-signature cert as the guardian (enterprise custody). */
+export declare function signCertAsGuardian<T extends Extract<DeletionCertificate, {
+    kind: "mutable_pruning" | "consolidation_flush";
+}>>(cert: T, guardianPublicKey: Uint8Array, privateKey: Uint8Array): Promise<T>;
+/**
+ * Sign an `append_only_horizon` cert as the issuer. The issuer is the
+ * subject named by the discriminator — motebit identity key for
+ * per-motebit horizons, operator key for operator-wide horizons.
+ */
+export declare function signHorizonCertAsIssuer(cert: Omit<Extract<DeletionCertificate, {
+    kind: "append_only_horizon";
+}>, "suite" | "signature">, privateKey: Uint8Array): Promise<Extract<DeletionCertificate, {
+    kind: "append_only_horizon";
+}>>;
+/**
+ * Add a witness signature to an `append_only_horizon` cert. Witness
+ * signs the same canonical body as the issuer; the witness array is
+ * part of the signed body, so once the issuer has signed, the witness
+ * additions are appended without re-signing the issuer side.
+ *
+ * Note: the issuer's signature is over the body INCLUDING the
+ * witness array as it stood when the issuer signed. Witnesses added
+ * after issuer-signing invalidate the issuer signature. Production
+ * flow: build the witness array first → issuer signs last. This
+ * function is here for tests and offline witness aggregation.
+ */
+export declare function signHorizonWitness(cert: Extract<DeletionCertificate, {
+    kind: "append_only_horizon";
+}>, witnessMotebitId: string, privateKey: Uint8Array, inclusionProof?: HorizonWitness["inclusion_proof"]): Promise<HorizonWitness>;
+/**
+ * Compute the canonical signing bytes for a `HorizonWitnessRequestBody`.
+ * Byte-equal to `canonicalizeHorizonCertForWitness` over the
+ * corresponding full cert (since the function strips
+ * `witnessed_by[]` + `signature`); exposed as a separate helper so
+ * call sites pass the wire-shaped request body directly without
+ * synthesizing a full cert.
+ */
+export declare function canonicalizeHorizonWitnessRequestBody(body: HorizonWitnessRequestBody): Uint8Array;
+/**
+ * Sign a `HorizonWitnessRequestBody` — produces a base64url-encoded
+ * Ed25519 signature over the canonical bytes. Used by BOTH:
+ *
+ *   - the issuer, for `WitnessSolicitationRequest.issuer_signature`
+ *     (attests authenticity of the solicitation request before any
+ *     peer signs as witness),
+ *   - each peer witness, for `WitnessSolicitationResponse.signature`
+ *     (the per-witness signature copied verbatim into
+ *     `cert.witnessed_by[].signature`).
+ *
+ * Both roles sign byte-equal canonical bytes by design (session-3
+ * sub-decision: issuer-signature payload IS witness-signature payload).
+ * The peer's verify-issuer + sign-as-witness paths share canonical-bytes
+ * derivation through this primitive — drift-impossible.
+ */
+export declare function signHorizonWitnessRequestBody(body: HorizonWitnessRequestBody, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify the issuer's `issuer_signature` on a
+ * `WitnessSolicitationRequest`. Peer-side fail-closed gate before the
+ * peer signs as a witness over the same bytes. Returns `false` on any
+ * malformed signature, suite mismatch, or hash failure — never throws.
+ */
+export declare function verifyHorizonWitnessRequestSignature(body: HorizonWitnessRequestBody, signatureBase64Url: string, issuerPublicKey: Uint8Array): Promise<boolean>;
+/**
+ * Verify a deletion certificate. Single entry point — dispatches by
+ * `kind` to the per-arm verifier. Fail-closed throughout: any
+ * verification step that errors or returns false → `valid: false`.
+ *
+ * The verifier checks, in order:
+ *   1. Reason × signer × mode table is satisfied (decision 5).
+ *   2. Each present signature is cryptographically valid against the
+ *      cert's canonical signing bytes.
+ *   3. (Horizon arm only) the issuer signature and each witness
+ *      signature verify.
+ *   4. (Optional, when `validateGuardianBinding` supplied) the
+ *      embedded guardian public key matches the subject motebit's
+ *      declared guardian.
+ */
+export declare function verifyDeletionCertificate(cert: DeletionCertificate, ctx: DeletionCertificateVerifyContext): Promise<DeletionCertificateVerifyResult>;
+import type { RetentionManifest } from "@motebit/protocol";
+/** Result of verifying a retention manifest. Fail-closed: any failure → `valid: false`. */
+export interface RetentionManifestVerifyResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    /** The parsed manifest if signature verified, else `null`. */
+    readonly manifest: RetentionManifest | null;
+}
+/**
+ * Verify a retention manifest published at
+ * `/.well-known/motebit-retention.json`. The manifest's signature
+ * covers `canonicalJson(manifest minus signature)`, signed by the
+ * operator's identity key under `motebit-jcs-ed25519-hex-v1` —
+ * sibling to the operator-transparency manifest's signing flow.
+ *
+ * Browser-side re-verifier per docs/doctrine/retention-policy.md
+ * §"Self-attesting transparency". Composes existing primitives —
+ * `canonicalJson` from signing.ts, `verifyBySuite` from
+ * suite-dispatch.ts. Same shape as the `verifySkillBundle`
+ * (87e2f174) browser primitive.
+ *
+ * The verifier accepts the operator's public key directly — callers
+ * resolve it from the operator-transparency manifest at
+ * `/.well-known/motebit-transparency.json` (its `relay_public_key`
+ * field), so a single manifest fetch + verify pair gives users a
+ * full retention claim audit.
+ */
+export declare function verifyRetentionManifest(manifest: RetentionManifest, operatorPublicKey: Uint8Array): Promise<RetentionManifestVerifyResult>;
+export {};
+//# sourceMappingURL=deletion-certificate.d.ts.map

package/dist/deletion-certificate.d.ts.map

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