@motebit/crypto 0.8.0 → 1.1.0

package/dist/signing.d.ts

@@ -2,8 +2,9 @@
  * Protocol signing primitives — Ed25519, encoding, canonical JSON, signed tokens.
  *
  * These are the cryptographic building blocks that any protocol participant
- * needs to produce valid Motebit artifacts. Moved from BSL @motebit/crypto
- * to MIT @motebit/crypto so the protocol's signing format is open.
+ * needs to produce valid Motebit artifacts. Moved from BSL @motebit/encryption
+ * to the permissive floor in @motebit/crypto (Apache-2.0) so the protocol's
+ * signing format is open.
  *
  * Zero monorepo dependencies — only @noble/ed25519 for cryptography.
  */
@@ -20,7 +21,20 @@ export interface SignedTokenPayload {
     jti: string;
     /** Audience claim — binds token to a specific endpoint/operation. Prevents cross-endpoint replay. */
     aud: string;
+    /**
+     * Cryptosuite identifier. Always `"motebit-jwt-ed25519-v1"` for this
+     * token shape today. Present in the signed payload so verifiers
+     * dispatch primitive verification through `verifyBySuite` rather
+     * than assuming Ed25519. Missing or unknown values are rejected
+     * fail-closed — no legacy-no-suite path.
+     */
+    suite: "motebit-jwt-ed25519-v1";
 }
+/** The one suite this token shape uses. Exported as a const so the
+ * signer emits exactly this value and the verifier checks for exactly
+ * this value — no string drift risk.
+ */
+export declare const SIGNED_TOKEN_SUITE: "motebit-jwt-ed25519-v1";
 /**
  * Deterministic JSON serialization with sorted keys (recursive).
  * Produces identical output regardless of insertion order.
@@ -53,30 +67,51 @@ export declare function didKeyToPublicKey(did: string): Uint8Array;
 export declare function publicKeyToDidKey(publicKey: Uint8Array): string;
 export declare function hexPublicKeyToDidKey(hexPublicKey: string): string;
 export declare function hash(data: Uint8Array): Promise<string>;
-/** SHA-256 returning raw bytes (used by credential signing). */
-export declare function sha256(data: Uint8Array): Promise<Uint8Array>;
-export declare function generateKeypair(): Promise<KeyPair>;
 /**
- * Sign a message with an Ed25519 private key.
+ * Canonical-bytes hash. Convenience wrapper over `canonicalJson` + SHA-256
+ * for diagnostic and audit use: lets a producer and a verifier deterministically
+ * agree on (or disagree about) the exact bytes a signature was computed over,
+ * without re-implementing the canonicalization recipe at the call site.
  *
- * Named `ed25519Sign` to avoid conflict with the artifact-level `verify()`
- * function exported from this package. Crypto re-exports as `sign`.
- */
-export declare function ed25519Sign(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
-/**
- * Verify an Ed25519 signature.
+ * Returns the hex SHA-256 of the UTF-8 bytes of `canonicalJson(obj)`. Stable
+ * across processes, machines, and Node versions — same input ⇒ same output,
+ * always. The only requirement on `obj` is that it be a JSON-serializable
+ * value (no functions, no symbols, no cycles).
  *
- * Named `ed25519Verify` to avoid conflict with the artifact-level `verify()`
- * function exported from this package. Crypto re-exports as `verify`.
+ * Primary use case: when a signed-artifact verification fails, both ends of
+ * the pipeline can log `canonicalSha256(body)` and the producer can confirm
+ * whether the bytes the verifier reproduced match the bytes the producer
+ * signed. A hash mismatch localizes the bug to the wire path; a hash match
+ * localizes it to the signature primitive (which is far less likely).
  */
-export declare function ed25519Verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+export declare function canonicalSha256(obj: unknown): Promise<string>;
+/** SHA-256 returning raw bytes (used by credential signing). */
+export declare function sha256(data: Uint8Array): Promise<Uint8Array>;
+export { ed25519Sign, ed25519Verify, generateEd25519Keypair, getPublicKeyBySuite, signBySuite, verifyBySuite, } from "./suite-dispatch.js";
+export declare function generateKeypair(): Promise<KeyPair>;
 /**
  * Create a signed token: base64url(payload) + "." + base64url(signature).
  * Default expiry: 5 minutes from now.
+ *
+ * The payload includes a fixed `suite` field (`SIGNED_TOKEN_SUITE`) so
+ * the verifier can dispatch primitive verification explicitly rather
+ * than implicitly assuming Ed25519. Callers MUST supply every other
+ * required payload field; this function does not fill defaults for
+ * `mid` / `did` / `iat` / `exp` / `jti` / `aud`.
  */
-export declare function createSignedToken(payload: SignedTokenPayload, privateKey: Uint8Array): Promise<string>;
+export declare function createSignedToken(payload: Omit<SignedTokenPayload, "suite">, privateKey: Uint8Array): Promise<string>;
 /**
- * Verify a signed token. Returns the parsed payload if valid and not expired, null otherwise.
+ * Verify a signed token. Returns the parsed payload if valid and not
+ * expired, null otherwise.
+ *
+ * Rejects fail-closed on:
+ *   - malformed token string (no dot separator, invalid base64url),
+ *   - missing `suite` field,
+ *   - `suite` value other than `SIGNED_TOKEN_SUITE`,
+ *   - signature mismatch,
+ *   - expired token,
+ *   - missing `jti` (replay defense),
+ *   - missing `aud` (cross-endpoint replay defense).
  */
 export declare function verifySignedToken(token: string, publicKey: Uint8Array): Promise<SignedTokenPayload | null>;
 /**

package/dist/signing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;CACb;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAMlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMpD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQrD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAczD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAoBvD;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAezD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAS/D;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAID,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGlE;AAID,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAGxD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAID;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmCpC;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAehF"}
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,wBAAwB,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAG,wBAAiC,CAAC;AAIpE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAclD;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAMlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMpD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQrD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAczD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAoBvD;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAezD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAS/D;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAID,wBAAsB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGlE;AAaD,OAAO,EACL,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAExD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoCpC;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQxD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAehF"}

package/dist/suite-dispatch.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Cryptosuite dispatch — the single entry point for signature primitive
+ * verification in @motebit/crypto.
+ *
+ * Every `verify*` function that checks a signed motebit artifact MUST
+ * route through `verifyBySuite`. Direct calls to `ed.verifyAsync`,
+ * `ed.signAsync`, or any other primitive outside this file are a
+ * drift-gate violation — see `scripts/check-suite-dispatch.ts`.
+ *
+ * Rationale: the suite value on a wire artifact names a complete
+ * verification recipe (algorithm + canonicalization + encoding). The
+ * dispatcher's job is to map `suite` → primitive. Encoding of the
+ * signature and public key stays at the artifact layer (every artifact
+ * already has its own encoding convention — see `spec/<artifact>-v1.md`
+ * `#### Wire format (foundation law)` subsections); the dispatcher
+ * receives already-decoded bytes and returns already-produced bytes.
+ * This keeps the Ed25519 switch arm honest: it does one thing, and the
+ * PQ switch arms that follow in 2026+ will do the same one thing for
+ * ML-DSA / SLH-DSA.
+ *
+ * Fail-closed throughout:
+ *   - unknown `SuiteId` → `verifyBySuite` returns `false`, `signBySuite` throws.
+ *   - unsupported algorithm in the switch (PQ placeholder) → throws with
+ *     a clear message so the call site doesn't silently succeed.
+ *   - primitive-level exception → `verifyBySuite` returns `false`.
+ *
+ * No legacy-no-suite path. A caller that reaches this function without
+ * a valid `SuiteId` has already lost; the function enforces that
+ * contract at the boundary.
+ */
+import type { SuiteId } from "@motebit/protocol";
+/**
+ * Verify an already-decoded signature over `canonicalBytes` using the
+ * primitive named by `suite`. The caller is responsible for:
+ *   1. canonicalization (the bytes are already the signing input per
+ *      the suite's canonicalization rule);
+ *   2. signature and public-key decoding (hex → Uint8Array, base64url
+ *      → Uint8Array, multibase → Uint8Array per the suite's
+ *      `signatureEncoding` / `publicKeyEncoding`).
+ *
+ * Returns `false` on unknown or unsupported suite, on primitive-level
+ * exception, and on signature mismatch. Never throws in the Ed25519
+ * path. Throws only on PQ suites (placeholder until implementation
+ * lands), because a misconfigured dispatcher there would silently
+ * pass every verification.
+ */
+export declare function verifyBySuite(suite: SuiteId, canonicalBytes: Uint8Array, signatureBytes: Uint8Array, publicKeyBytes: Uint8Array): Promise<boolean>;
+/**
+ * Produce a signature over `canonicalBytes` using the primitive named
+ * by `suite`. Mirrors `verifyBySuite`: caller provides already-
+ * canonicalized bytes; caller encodes the returned `Uint8Array` per
+ * the suite's `signatureEncoding` at the artifact boundary.
+ *
+ * Throws on unknown or unsupported suite (fail-closed). Signers that
+ * catch and swallow this exception would ship unsigned artifacts,
+ * which is a worse failure mode than a loud throw.
+ */
+export declare function signBySuite(suite: SuiteId, canonicalBytes: Uint8Array, privateKeyBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Lowest-level Ed25519 primitives. These are the functions callers
+ * should use when they genuinely need the primitive — for example,
+ * generating a keypair at identity bootstrap, or computing a
+ * succession-chain signature where the caller has already dispatched
+ * by suite. Exported from this file so the drift gate's scan rule is
+ * simple: "`ed.*` lives only in `suite-dispatch.ts`."
+ */
+export declare function ed25519Sign(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
+export declare function ed25519Verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+export declare function generateEd25519Keypair(): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}>;
+/**
+ * Derive the matching public key from a private key, dispatched by suite.
+ *
+ * For Ed25519 suites this is deterministic seed expansion (hash the seed,
+ * derive the curve point). Callers that have a private key in hand and
+ * need the public key — sovereign delegation paths, identity bootstrap
+ * after a seed import, recovery flows — go through here so the noble
+ * call doesn't escape the dispatcher.
+ *
+ * Throws on unknown or unsupported suite (fail-closed). PQ arms will
+ * land alongside their `verifyBySuite` / `signBySuite` counterparts.
+ */
+export declare function getPublicKeyBySuite(privateKey: Uint8Array, suite: SuiteId): Promise<Uint8Array>;
+/**
+ * Verify a P-256 ECDSA-SHA256 signature.
+ *
+ * - `publicKeyCompressedHex` — P-256 public key in compressed-point
+ *   hex encoding (33 bytes, `02`/`03` prefix). Uncompressed keys
+ *   (65 bytes, `04` prefix) also accepted — noble handles both.
+ * - `messageBytes` — the bytes that were signed. noble internally
+ *   SHA-256 hashes before verification, so callers pass the
+ *   un-pre-hashed payload.
+ * - `signatureDerBytes` — DER-encoded ECDSA signature as emitted by
+ *   Apple SE / Security.framework.
+ *
+ * Returns `false` on any failure (bad key, bad DER, bad signature,
+ * mismatch). Never throws — matches the `verifyBySuite` contract so
+ * callers don't need a try/catch.
+ */
+export declare function verifyP256EcdsaSha256(publicKeyCompressedHex: string, messageBytes: Uint8Array, signatureDerBytes: Uint8Array): boolean;
+//# sourceMappingURL=suite-dispatch.d.ts.map

package/dist/suite-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-dispatch.d.ts","sourceRoot":"","sources":["../src/suite-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAkBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AASjD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,EAC1B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,UAAU,EAC1B,eAAe,EAAE,UAAU,GAC1B,OAAO,CAAC,UAAU,CAAC,CASrB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC;IACtD,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CAGD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC,CASrB;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,sBAAsB,EAAE,MAAM,EAC9B,YAAY,EAAE,UAAU,EACxB,iBAAiB,EAAE,UAAU,GAC5B,OAAO,CAQT"}