@motebit/crypto 1.1.0 → 1.2.1

package/dist/merkle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Merkle inclusion-proof verifier — binary tree with odd-leaf
+ * promotion (no duplication). One canonical primitive across every
+ * Merkle-anchored artifact in motebit.
+ *
+ * Permissive floor (Apache-2.0). Zero monorepo deps. Same algorithm
+ * as `@motebit/encryption/merkle.ts` — kept here so `@motebit/crypto`
+ * stays self-contained for browser-side re-verification.
+ *
+ * Consumers:
+ *   - `credential-anchor.ts` — credential-anchor proof verification
+ *     (`spec/credential-anchor-v1.md` §6).
+ *   - `witness-omission-dispute.ts` — `inclusion_proof` evidence
+ *     against a horizon cert's `federation_graph_anchor.merkle_root`.
+ */
+/**
+ * Verify a Merkle inclusion proof against an expected root.
+ *
+ * Binary tree with odd-leaf promotion (no duplication). Siblings are
+ * ordered leaf-to-root; `layerSizes` lets the verifier detect odd-leaf
+ * promotion at each level (when `siblingPos` falls outside the layer,
+ * `current` passes through unchanged without consuming a sibling).
+ *
+ * Returns `false` on any malformed input or hash mismatch — never
+ * throws. Same fail-closed contract as `verifyBySuite`.
+ *
+ * @param leaf - hex-encoded SHA-256 leaf hash
+ * @param index - leaf position in the bottom layer (0-based)
+ * @param siblings - hex-encoded sibling hashes, leaf-to-root order
+ * @param layerSizes - bottom-up layer cardinalities
+ * @param expectedRoot - hex-encoded SHA-256 root the proof must reconstruct
+ */
+export declare function verifyMerkleInclusion(leaf: string, index: number, siblings: string[], layerSizes: number[], expectedRoot: string): Promise<boolean>;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyBH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAiClB"}

package/dist/skills.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Skill manifest + envelope signing and verification — spec/skills-v1.md.
+ *
+ * Skills are motebit-internal protocol artifacts. They install locally,
+ * verify on motebit runtimes, and are signed by their author's motebit
+ * identity using `motebit-jcs-ed25519-b64-v1` — the same suite used for
+ * execution receipts, tool invocation receipts, settlement anchors, and
+ * migration artifacts. NOT W3C `eddsa-jcs-2022` (that suite is reserved for
+ * credentials, identity files, and presentations needing third-party W3C
+ * interop).
+ *
+ * Signature recipe (spec §5.1):
+ *
+ *   manifest_bytes = JCS(manifest_with_signature_value_removed) || 0x0A || lf_body
+ *   envelope_bytes = JCS(envelope_with_signature_value_removed)
+ *   signature = Ed25519.sign(bytes, privateKey)  -- routed through verifyBySuite
+ *
+ * Verification is offline: no relay, no registry, no external service. Per
+ * @motebit/crypto/CLAUDE.md rule 4, third-party verifiers using only this
+ * package and the signer's public key can validate any motebit-signed skill.
+ */
+import type { SkillEnvelope, SkillManifest, SkillSignature } from "@motebit/protocol";
+/** The suite skills sign under in v1. Mirrors EXECUTION_RECEIPT_SUITE. */
+export declare const SKILL_SIGNATURE_SUITE: "motebit-jcs-ed25519-b64-v1";
+/** Failure reasons surfaced by `verifySkillManifestDetailed` / `verifySkillEnvelopeDetailed`. */
+export type SkillVerifyReason = "ok" | "no_signature" | "wrong_suite" | "bad_public_key" | "bad_signature_value" | "ed25519_mismatch";
+export interface SkillVerifyDetail {
+    valid: boolean;
+    reason: SkillVerifyReason;
+}
+/**
+ * Compute the canonical bytes that a SkillManifest signature is computed over.
+ * `body` is the LF-normalized SKILL.md body bytes (everything after the
+ * closing `---` delimiter), with CRLF/CR converted to LF, no BOM, UTF-8.
+ *
+ * Caller is responsible for body normalization. The reference parser in
+ * @motebit/skills (BSL) does the normalization at file-read time.
+ *
+ * The manifest's `motebit.signature.value` is removed before canonicalization;
+ * `suite` and `public_key` are preserved (they are signature-bound).
+ */
+export declare function canonicalizeSkillManifestBytes(manifest: SkillManifest, body: Uint8Array): Uint8Array;
+/**
+ * Compute the canonical bytes that a SkillEnvelope signature is computed
+ * over. Sibling to manifest canonicalization; envelope is pure JSON so no
+ * body concatenation.
+ */
+export declare function canonicalizeSkillEnvelopeBytes(envelope: SkillEnvelope): Uint8Array;
+/**
+ * Sign a SkillManifest, returning the signed manifest with `motebit.signature`
+ * populated. Caller provides the LF-normalized body bytes; signing recipe is
+ * spec §5.1.
+ *
+ * The returned manifest's `motebit.signature.public_key` is hex-encoded and
+ * `motebit.signature.value` is base64url-encoded, matching the suite contract.
+ */
+export declare function signSkillManifest(unsigned: Omit<SkillManifest, "motebit"> & {
+    motebit: Omit<SkillManifest["motebit"], "signature">;
+}, privateKey: Uint8Array, publicKey: Uint8Array, body: Uint8Array): Promise<SkillManifest>;
+/**
+ * Sign a SkillEnvelope, returning the signed envelope. Sibling to
+ * `signSkillManifest`. Envelope canonicalization is pure JSON (§5.1).
+ */
+export declare function signSkillEnvelope(unsigned: Omit<SkillEnvelope, "signature">, privateKey: Uint8Array, publicKey: Uint8Array): Promise<SkillEnvelope>;
+/**
+ * Verify a SkillManifest's signature against the provided public key and
+ * LF-normalized body bytes. Returns `false` on any failure path:
+ *
+ *  - manifest is unsigned (`motebit.signature` absent)
+ *  - suite mismatch (only `motebit-jcs-ed25519-b64-v1` accepted in v1)
+ *  - public_key in the signature doesn't match the supplied public key
+ *  - signature value fails base64url decode
+ *  - Ed25519 verification fails
+ *
+ * Per CLAUDE.md rule 4, this is the third-party self-verification entry
+ * point. Only this package + the signer's public key are required.
+ */
+export declare function verifySkillManifest(manifest: SkillManifest, body: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Companion to `verifySkillManifest` that returns a categorized failure
+ * reason for observability. Same recipe; same fail-closed behavior.
+ */
+export declare function verifySkillManifestDetailed(manifest: SkillManifest, body: Uint8Array, publicKey: Uint8Array): Promise<SkillVerifyDetail>;
+/**
+ * Verify a SkillEnvelope's signature. Sibling to `verifySkillManifest` —
+ * same suite, same fail-closed semantics. Note: envelope verification does
+ * NOT cross-check `body_hash` or `files[].hash` against on-disk bytes; the
+ * caller (install-time logic in the registry) is responsible for that pass
+ * after signature verification succeeds.
+ */
+export declare function verifySkillEnvelope(envelope: SkillEnvelope, publicKey: Uint8Array): Promise<boolean>;
+export declare function verifySkillEnvelopeDetailed(envelope: SkillEnvelope, publicKey: Uint8Array): Promise<SkillVerifyDetail>;
+/** Decode a hex public key from a SkillSignature for caller convenience. */
+export declare function decodeSkillSignaturePublicKey(sig: SkillSignature): Uint8Array;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAWtF,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAG,4BAAqC,CAAC;AAE3E,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GACzB,IAAI,GACJ,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,qBAAqB,GACrB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,UAAU,GACf,UAAU,CAiBZ;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,aAAa,GAAG,UAAU,CAOlF;AAMD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG;IACzC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,CAAC;CACtD,EACD,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,aAAa,CAAC,CA+BxB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,EAC1C,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,aAAa,CAAC,CAoBxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAmB5B;AAeD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,CAE7E"}

package/dist/witness-omission-dispute.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Witness-omission dispute — sign + verify (retention phase 4b-3).
+ *
+ * Permissive floor (Apache-2.0). Zero monorepo deps beyond
+ * `@motebit/protocol` types. Routes signing through
+ * `@motebit/crypto/suite-dispatch`.
+ *
+ * Path A quorum's soft-accountability layer for `append_only_horizon`
+ * certs: a peer who believes `cert.witnessed_by[]` wrongly omits them
+ * files this dispute within 24h of `cert.issued_at`. Two evidence
+ * shapes:
+ *
+ *   - `inclusion_proof` — disputant proves their peer pubkey is in
+ *     the cert's `federation_graph_anchor.merkle_root` via a Merkle
+ *     inclusion proof. The verifier reconstructs against the cert's
+ *     anchor root.
+ *
+ *   - `alternative_peering` — disputant supplies a signed peering
+ *     artifact from the cert issuer (today: a federation Heartbeat,
+ *     `motebit-concat-ed25519-hex-v1`) whose timestamp window covers
+ *     `cert.horizon_ts ± 5 min` (mirrors heartbeat suspension
+ *     threshold). The cert's published anchor is claimed incomplete.
+ *
+ * The verifier returns a per-step result; certificates remain
+ * TERMINAL per `retention-policy.md` decision 5 — a sustained dispute
+ * is a reputation hit on the issuer, not a cert invalidation.
+ */
+import type { DeletionCertificate, WitnessOmissionDispute } from "@motebit/protocol";
+/** Result of verifying a witness-omission dispute. Fail-closed: any failure → `valid: false`. */
+export interface WitnessOmissionDisputeVerifyResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    /** Per-step breakdown — useful for adjudication audit display. */
+    readonly steps: {
+        /**
+         * Window check (two gates, both must pass):
+         *   A. `now - cert.issued_at <= WITNESS_OMISSION_DISPUTE_WINDOW_MS`
+         *   B. `dispute.filed_at ∈ [cert.issued_at, cert.issued_at + WINDOW_MS]`
+         */
+        readonly window_open: boolean;
+        /** Dispute pins the disputed cert (`cert_issuer` + `cert_signature` match). */
+        readonly cert_binding_valid: boolean;
+        /** Disputant's Ed25519 signature over the dispute body. */
+        readonly disputant_signature_valid: boolean;
+        /** Evidence-shape verification. `null` when prior checks already failed. */
+        readonly evidence_valid: boolean | null;
+    };
+}
+/**
+ * Resolver context for `verifyWitnessOmissionDispute`. The caller
+ * supplies the cert (resolved from its local store via the dispute's
+ * `cert_signature` pointer), the issuer's pubkey (for verifying the
+ * cert binding and any alternative-peering artifact), the disputant's
+ * pubkey, and a `now` clock.
+ */
+export interface WitnessOmissionDisputeVerifyContext {
+    /** The disputed cert, resolved by the caller from `dispute.cert_signature`. */
+    readonly cert: Extract<DeletionCertificate, {
+        kind: "append_only_horizon";
+    }>;
+    /** Cert issuer's Ed25519 public key (32 bytes). */
+    readonly issuerPublicKey: Uint8Array;
+    /** Disputant peer's Ed25519 public key (32 bytes). `null` → unknown disputant, fail-closed. */
+    readonly disputantPublicKey: Uint8Array | null;
+    /** Wall-clock at validation time, in unix ms. */
+    readonly now: number;
+}
+/**
+ * Compute the canonical signing bytes for a `WitnessOmissionDispute`.
+ * Strips `signature` so the disputant signs every other field —
+ * including `cert_signature`, `cert_issuer`, and the evidence body.
+ */
+export declare function canonicalizeWitnessOmissionDispute(dispute: WitnessOmissionDispute): Uint8Array;
+/**
+ * Sign a `WitnessOmissionDispute` as the disputant. Caller provides
+ * the unsigned body (everything except `suite` and `signature`); this
+ * function appends both.
+ */
+export declare function signWitnessOmissionDispute(body: Omit<WitnessOmissionDispute, "suite" | "signature">, privateKey: Uint8Array): Promise<WitnessOmissionDispute>;
+/**
+ * Verify a `WitnessOmissionDispute` against the disputed cert.
+ *
+ * Step ladder (fail-closed throughout):
+ *   1. Window: `now - cert.issued_at <= WINDOW` AND
+ *      `filed_at ∈ [cert.issued_at, cert.issued_at + WINDOW]`.
+ *   2. Cert binding: `dispute.cert_signature === cert.signature` and
+ *      `dispute.cert_issuer` matches the cert's subject.
+ *   3. Disputant signature over `canonicalJson(dispute minus signature)`.
+ *   4. Evidence: dispatched by `evidence.kind` —
+ *      - `inclusion_proof`: requires cert has a `federation_graph_anchor`;
+ *        verifies the Merkle proof against `anchor.merkle_root`.
+ *      - `alternative_peering`: dispatches on `peering_artifact`'s
+ *        self-described shape (today: federation Heartbeat); verifies
+ *        the embedded signature against the issuer pubkey and the
+ *        timestamp window covers `cert.horizon_ts`.
+ */
+export declare function verifyWitnessOmissionDispute(dispute: WitnessOmissionDispute, ctx: WitnessOmissionDisputeVerifyContext): Promise<WitnessOmissionDisputeVerifyResult>;
+//# sourceMappingURL=witness-omission-dispute.d.ts.map

package/dist/witness-omission-dispute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness-omission-dispute.d.ts","sourceRoot":"","sources":["../src/witness-omission-dispute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EAEvB,MAAM,mBAAmB,CAAC;AAuB3B,iGAAiG;AACjG,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE;QACd;;;;WAIG;QACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;QAC9B,+EAA+E;QAC/E,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;QACrC,2DAA2D;QAC3D,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;QAC5C,4EAA4E;QAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;KACzC,CAAC;CACH;AAID;;;;;;GAMG;AACH,MAAM,WAAW,mCAAmC;IAClD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;IAC7E,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,kBAAkB,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/C,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAID;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU,CAI9F;AAID;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,WAAW,CAAC,EACzD,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,sBAAsB,CAAC,CASjC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,sBAAsB,EAC/B,GAAG,EAAE,mCAAmC,GACvC,OAAO,CAAC,kCAAkC,CAAC,CA4F7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motebit/crypto",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Sign and verify every Motebit artifact — identity files, execution receipts, credentials, delegations, succession records, credential anchors. Ed25519 today, cryptosuite-agile for post-quantum tomorrow. Apache-2.0, zero monorepo dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,7 +64,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0",
-    "@motebit/protocol": "1.1.0"
+    "@motebit/protocol": "1.2.0"
   },
   "engines": {
     "node": ">=20"