leviathan-crypto 2.1.0 → 3.0.0

package/dist/ecdsa/der.js

@@ -0,0 +1,192 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ecdsa/der.ts
+//
+// ECDSA signature DER ↔ raw r||s conversion utility, RFC 3279 §2.2.3,
+// ECDSA Signature Algorithm.
+//
+//   Ecdsa-Sig-Value ::= SEQUENCE {
+//       r  INTEGER,
+//       s  INTEGER
+//   }
+//
+// The library's WASM ABI consumes and produces raw 64-byte r || s
+// signatures. DER is a side utility for callers who need X.509 / JWS /
+// TLS interop. The encoder / decoder is hand-rolled against X.690 §8.3
+// (INTEGER) and §8.9 (SEQUENCE); leviathan-crypto is zero-dependency
+// so no external ASN.1 parser is used.
+//
+// Strict DER (not BER). The decoder rejects:
+//   - non-minimal length encodings (long-form length when short-form
+//     would suffice; X.690 §10.1, definite-length encoding)
+//   - excess leading-zero bytes inside INTEGER content (X.690 §8.3.2)
+//   - negative INTEGERs (sign bit set on the leading content octet
+//     without a 0x00 sign-pad; ECDSA r, s ∈ [1, n-1] are positive)
+//   - INTEGER content longer than 33 bytes (32-byte BE scalar plus an
+//     optional 0x00 sign-pad)
+//   - trailing bytes after the outer SEQUENCE
+//   - wrong tags (outer 0x30 SEQUENCE, inner 0x02 INTEGER)
+//
+// The from-DER path never throws on a semantic value problem
+// (r = 0, s = 0, high-s, off-range); those are verify-time rejections
+// in the WASM. Only DER syntax violations throw.
+import { SigningError } from '../errors.js';
+const SEQUENCE_TAG = 0x30;
+const INTEGER_TAG = 0x02;
+function reject(detail) {
+    throw new SigningError('sig-malformed-input', `leviathan-crypto: ecdsa-p256 DER signature ${detail}`);
+}
+/**
+ * Encode a positive 32-byte BE scalar (r or s component) as a DER
+ * INTEGER TLV. Strips leading zero bytes to the minimal encoding per
+ * X.690 §8.3.2, then prepends a single 0x00 if the high bit of the
+ * resulting first content byte is set, so the INTEGER remains positive.
+ *
+ * The component length is at most 33 bytes (32-byte scalar + optional
+ * sign-pad), so the DER length octet always fits in short-form.
+ */
+function encodeInteger(scalarBE) {
+    let start = 0;
+    while (start < scalarBE.length - 1 && scalarBE[start] === 0)
+        start++;
+    const stripped = scalarBE.subarray(start);
+    const needsPad = (stripped[0] & 0x80) !== 0;
+    const contentLen = stripped.length + (needsPad ? 1 : 0);
+    const out = new Uint8Array(2 + contentLen);
+    out[0] = INTEGER_TAG;
+    out[1] = contentLen;
+    if (needsPad) {
+        out[2] = 0;
+        out.set(stripped, 3);
+    }
+    else {
+        out.set(stripped, 2);
+    }
+    return out;
+}
+/**
+ * Decode one DER INTEGER TLV starting at `start`. Returns the strict-DER
+ * minimal content bytes (with any leading 0x00 sign-pad stripped) and
+ * the offset immediately past the INTEGER. Throws SigningError on any
+ * DER syntax violation.
+ */
+function decodeInteger(der, start) {
+    if (start + 2 > der.length)
+        reject(`has a truncated INTEGER header at offset ${start}`);
+    if (der[start] !== INTEGER_TAG)
+        reject(`INTEGER tag at offset ${start} is 0x${der[start].toString(16).padStart(2, '0')}, expected 0x02`);
+    const lenByte = der[start + 1];
+    // Strict DER: ECDSA-P256 INTEGER content is at most 33 bytes, so the
+    // length octet is always short-form (high bit clear, value 1..127).
+    if (lenByte & 0x80)
+        reject(`INTEGER at offset ${start} uses long-form length encoding (forbidden for content < 128 bytes)`);
+    // Zero-length INTEGER content has no representable value; ASN.1
+    // requires at least one content octet (X.690 §8.3.1).
+    if (lenByte === 0)
+        reject(`INTEGER at offset ${start} has zero-length content`);
+    const contentStart = start + 2;
+    const contentEnd = contentStart + lenByte;
+    if (contentEnd > der.length)
+        reject(`INTEGER at offset ${start} extends past the outer SEQUENCE end`);
+    const content = der.subarray(contentStart, contentEnd);
+    // Minimal encoding: a leading 0x00 octet is permitted only when the
+    // next byte's high bit is set (sign-pad). Otherwise the 0x00 is
+    // excess per X.690 §8.3.2.
+    if (content[0] === 0x00 && content.length > 1 && (content[1] & 0x80) === 0)
+        reject(`INTEGER at offset ${start} has excess leading zero byte (non-minimal DER)`);
+    // ECDSA r, s ∈ [1, n-1] are positive integers. A first content
+    // octet with the high bit set means the ASN.1 INTEGER decodes as a
+    // negative two's-complement value; reject.
+    if ((content[0] & 0x80) !== 0)
+        reject(`INTEGER at offset ${start} is negative (high bit set on first content byte); ECDSA r, s are positive`);
+    const value = (content[0] === 0x00) ? content.subarray(1) : content;
+    return { value, next: contentEnd };
+}
+/**
+ * Convert a 64-byte raw r || s signature to DER per RFC 3279 §2.2.3.
+ * Output length is variable: 8 bytes minimum (r = s = 1 byte each, no
+ * sign-pad), 72 bytes maximum (both components 32 bytes with high bit
+ * set, each picking up a 0x00 sign-pad).
+ *
+ * @throws TypeError if `sig` is not a Uint8Array
+ * @throws RangeError if `sig.length !== 64`
+ */
+export function ecdsaSignatureToDer(sig) {
+    if (!(sig instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 raw signature must be a Uint8Array');
+    if (sig.length !== 64)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 raw signature must be 64 bytes r||s (got ${sig.length})`);
+    const r = encodeInteger(sig.subarray(0, 32));
+    const s = encodeInteger(sig.subarray(32, 64));
+    const contentLen = r.length + s.length;
+    // SEQUENCE content is at most 2 * 35 = 70 bytes, so the SEQUENCE
+    // length octet is always short-form.
+    const out = new Uint8Array(2 + contentLen);
+    out[0] = SEQUENCE_TAG;
+    out[1] = contentLen;
+    out.set(r, 2);
+    out.set(s, 2 + r.length);
+    return out;
+}
+/**
+ * Convert a DER ECDSA-P256 signature to 64-byte raw r || s. Rejects
+ * any DER syntax violation via SigningError('sig-malformed-input'):
+ * see the file-level header for the rejection rules.
+ *
+ * Semantic value rejections (r = 0, s = 0, high-s, off-range) are
+ * deferred to the WASM verify path; this function only enforces DER
+ * structure.
+ *
+ * @throws TypeError if `der` is not a Uint8Array
+ * @throws SigningError('sig-malformed-input') on any DER syntax error
+ */
+export function ecdsaSignatureFromDer(der) {
+    if (!(der instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 DER signature must be a Uint8Array');
+    // 8 bytes is the absolute minimum: SEQUENCE(2) + INTEGER(0x01 0x01)
+    // + INTEGER(0x01 0x01) = 8. Anything shorter cannot represent two
+    // non-empty INTEGER components.
+    if (der.length < 8)
+        reject(`is shorter than the 8-byte minimum (got ${der.length} bytes)`);
+    if (der[0] !== SEQUENCE_TAG)
+        reject(`outer tag is 0x${der[0].toString(16).padStart(2, '0')}, expected 0x30 (SEQUENCE)`);
+    const seqLen = der[1];
+    // ECDSA-P256 SEQUENCE content is at most 70 bytes; strict DER
+    // requires short-form length encoding when < 128.
+    if (seqLen & 0x80)
+        reject('uses long-form length encoding for the outer SEQUENCE (forbidden for content < 128 bytes)');
+    if (2 + seqLen !== der.length)
+        reject(`outer SEQUENCE length ${seqLen} does not match input size (${der.length} bytes total)`);
+    const { value: r, next: afterR } = decodeInteger(der, 2);
+    const { value: s, next: end } = decodeInteger(der, afterR);
+    if (end !== der.length)
+        reject('has trailing bytes after the second INTEGER');
+    // Each component must fit in 32 bytes BE (P-256 scalar size).
+    if (r.length > 32)
+        reject(`r component is ${r.length} bytes, exceeds the 32-byte scalar size`);
+    if (s.length > 32)
+        reject(`s component is ${s.length} bytes, exceeds the 32-byte scalar size`);
+    const out = new Uint8Array(64);
+    out.set(r, 32 - r.length);
+    out.set(s, 64 - s.length);
+    return out;
+}

package/dist/ecdsa/ecprivatekey-der.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Encode a 32-byte P-256 secret scalar as DER `ECPrivateKey` per
+ * RFC 5915 §3. Output length is exactly 51 bytes; version is 1, the
+ * named-curve OID for secp256r1 (`1.2.840.10045.3.1.7`,
+ * SP 800-186 §3.2.1.3) is included in `parameters [0]`, and the
+ * `publicKey [1]` field is omitted.
+ *
+ * Byte-stable: same input scalar produces byte-identical output. No
+ * canonicalisation pass needed because every field has a single legal
+ * DER encoding under the strict-DER rules of X.690 §10.
+ *
+ * @throws TypeError if `scalar` is not a Uint8Array
+ * @throws RangeError if `scalar.length !== 32`
+ */
+export declare function encodeEcPrivateKey(scalar: Uint8Array): Uint8Array;
+/**
+ * Decode a DER `ECPrivateKey` (RFC 5915 §3) and return the 32-byte
+ * raw P-256 secret scalar.
+ *
+ * Strict-DER per X.690 §10 (Restrictions on the BER). Rejects the
+ * cases enumerated in the file-level header. Accepts (and ignores)
+ * an optional `publicKey [1]` field per RFC 5915 §3 lenient input;
+ * the scalar is the only return value.
+ *
+ * Any curve OID inside `parameters [0]` other than secp256r1
+ * (`1.2.840.10045.3.1.7`) is rejected. Decoders that need other
+ * curves must use a different parser; this library is P-256 only.
+ *
+ * @throws TypeError if `der` is not a Uint8Array
+ * @throws Error on any DER syntax violation or unsupported parameter
+ */
+export declare function decodeEcPrivateKey(der: Uint8Array): Uint8Array;

package/dist/ecdsa/ecprivatekey-der.js

@@ -0,0 +1,230 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ecdsa/ecprivatekey-der.ts
+//
+// DER `ECPrivateKey` (RFC 5915 §3, Elliptic Curve Private Key Structure)
+// codec for P-256. The library's WASM ABI stores secrets as 32-byte raw
+// scalars; DER `ECPrivateKey` is the X.509 / PKCS#8-adjacent wire form
+// some interop contexts require (PKCS#8 wraps an ECPrivateKey OCTET
+// STRING inside its `privateKey` field; X.509 self-signed certs reference
+// it through their algorithm OID).
+//
+//   ECPrivateKey ::= SEQUENCE {
+//       version        INTEGER (1),
+//       privateKey     OCTET STRING,
+//       parameters [0] EXPLICIT ECParameters OPTIONAL,
+//       publicKey  [1] EXPLICIT BIT STRING OPTIONAL
+//   }
+//
+// Encoder side: emits the exact 51-byte DER form with version 1, the
+// 32-byte raw scalar in `privateKey`, and the named-curve OID
+// `1.2.840.10045.3.1.7` (secp256r1, SP 800-186 §3.2.1.3) wrapped in
+// `parameters [0]`. `publicKey` is omitted; consumers that need the
+// public key alongside should re-derive via `EcdsaP256.keygenDerand` and
+// the SEC 1 §2.3.4 uncompressed encoding (see `pointDecompress` in
+// `./index.ts`). Byte-stable: same scalar in, same DER out.
+//
+// Decoder side: accepts any conforming RFC 5915 `ECPrivateKey` (not just
+// leviathan's exact byte layout). Strict-DER posture per X.690 §10
+// (Restrictions on the BER) rejects:
+//   - non-minimal length encodings (long-form when short-form suffices)
+//   - non-minimal INTEGER encodings on the `version` field
+//   - SEQUENCE / OCTET STRING / parameters [0] / publicKey [1] length
+//     prefixes that disagree with the on-the-wire content size
+//   - any curve OID inside `parameters [0]` other than secp256r1
+//   - trailing bytes after the outer SEQUENCE
+//   - wrong tags or missing required fields
+//
+// Lenient on `publicKey [1]`: some encoders include the derived pk
+// alongside the scalar; the decoder skips past the field after a
+// minimal-length check. The scalar is the only return value; callers
+// who need the embedded pk should parse the DER themselves.
+//
+// No third-party ASN.1 library. Hand-rolled against X.690 §8.1 (TLV
+// structure), §8.3 (INTEGER), §8.7 (OCTET STRING), §8.14 (tagged types),
+// §10 (DER restrictions), mirroring the strict-parser hygiene of
+// `./der.ts` (Ecdsa-Sig-Value codec).
+const SEQUENCE_TAG = 0x30;
+const INTEGER_TAG = 0x02;
+const OCTET_STRING_TAG = 0x04;
+const OID_TAG = 0x06;
+const TAG_PARAMETERS_0 = 0xA0; // [0] EXPLICIT, constructed
+const TAG_PUBLIC_KEY_1 = 0xA1; // [1] EXPLICIT, constructed
+// DER OID for secp256r1: 1.2.840.10045.3.1.7. X.690 §8.19 collapses the
+// first two arcs (1.2) into a single byte 0x2A (= 1 * 40 + 2); the
+// remaining arcs (840, 10045, 3, 1, 7) base-128 encode as 86 48, CE 3D,
+// 03, 01, 07. Wrapped in the OBJECT IDENTIFIER TLV (tag 0x06, len 0x08).
+const SECP256R1_OID_DER = new Uint8Array([
+    OID_TAG, 0x08, 0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x07,
+]);
+// Exact 51-byte DER shape for a P-256 ECPrivateKey with no embedded
+// public key:
+//   30 31                          SEQUENCE, 49 bytes content
+//   02 01 01                       INTEGER, version = 1
+//   04 20 <32 bytes scalar>        OCTET STRING, 32 bytes
+//   A0 0A                          [0] EXPLICIT, 10 bytes content
+//   06 08 2A 86 48 CE 3D 03 01 07  OBJECT IDENTIFIER, secp256r1
+const ENCODED_LEN = 51;
+const SEQUENCE_CONTENT_LEN = 49;
+const SCALAR_LEN = 32;
+// Absolute minimum input size that exposes every required field's TLV
+// header without index-out-of-bounds on the parser side. SEQUENCE
+// header (2) + version INTEGER TLV (3) + OCTET STRING tag + len byte
+// (2) = 7. The decoder's field-level checks surface more specific
+// rejections beyond this floor (wrong scalar length, missing required
+// fields, etc).
+const MIN_INPUT_LEN = 7;
+function reject(detail) {
+    throw new Error(`leviathan-crypto: ecdsa-p256 ECPrivateKey DER ${detail}`);
+}
+/**
+ * Encode a 32-byte P-256 secret scalar as DER `ECPrivateKey` per
+ * RFC 5915 §3. Output length is exactly 51 bytes; version is 1, the
+ * named-curve OID for secp256r1 (`1.2.840.10045.3.1.7`,
+ * SP 800-186 §3.2.1.3) is included in `parameters [0]`, and the
+ * `publicKey [1]` field is omitted.
+ *
+ * Byte-stable: same input scalar produces byte-identical output. No
+ * canonicalisation pass needed because every field has a single legal
+ * DER encoding under the strict-DER rules of X.690 §10.
+ *
+ * @throws TypeError if `scalar` is not a Uint8Array
+ * @throws RangeError if `scalar.length !== 32`
+ */
+export function encodeEcPrivateKey(scalar) {
+    if (!(scalar instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 ECPrivateKey scalar must be a Uint8Array');
+    if (scalar.length !== SCALAR_LEN)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 ECPrivateKey scalar must be ${SCALAR_LEN} bytes (got ${scalar.length})`);
+    const out = new Uint8Array(ENCODED_LEN);
+    let p = 0;
+    // SEQUENCE header
+    out[p++] = SEQUENCE_TAG;
+    out[p++] = SEQUENCE_CONTENT_LEN;
+    // version INTEGER (1)
+    out[p++] = INTEGER_TAG;
+    out[p++] = 0x01;
+    out[p++] = 0x01;
+    // privateKey OCTET STRING (32 bytes)
+    out[p++] = OCTET_STRING_TAG;
+    out[p++] = SCALAR_LEN;
+    out.set(scalar, p);
+    p += SCALAR_LEN;
+    // parameters [0] EXPLICIT { secp256r1 OID }
+    out[p++] = TAG_PARAMETERS_0;
+    out[p++] = SECP256R1_OID_DER.length;
+    out.set(SECP256R1_OID_DER, p);
+    // p + SECP256R1_OID_DER.length now equals ENCODED_LEN by construction.
+    return out;
+}
+/**
+ * Decode a DER `ECPrivateKey` (RFC 5915 §3) and return the 32-byte
+ * raw P-256 secret scalar.
+ *
+ * Strict-DER per X.690 §10 (Restrictions on the BER). Rejects the
+ * cases enumerated in the file-level header. Accepts (and ignores)
+ * an optional `publicKey [1]` field per RFC 5915 §3 lenient input;
+ * the scalar is the only return value.
+ *
+ * Any curve OID inside `parameters [0]` other than secp256r1
+ * (`1.2.840.10045.3.1.7`) is rejected. Decoders that need other
+ * curves must use a different parser; this library is P-256 only.
+ *
+ * @throws TypeError if `der` is not a Uint8Array
+ * @throws Error on any DER syntax violation or unsupported parameter
+ */
+export function decodeEcPrivateKey(der) {
+    if (!(der instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 ECPrivateKey DER must be a Uint8Array');
+    // Floor at the bytes needed for the SEQUENCE header + version
+    // INTEGER TLV + privateKey OCTET STRING TLV header (no content
+    // required at the floor). Specific field-level checks below
+    // surface more accurate rejections beyond this.
+    if (der.length < MIN_INPUT_LEN)
+        reject(`is shorter than the ${MIN_INPUT_LEN}-byte minimum (got ${der.length} bytes)`);
+    if (der[0] !== SEQUENCE_TAG)
+        reject(`outer tag is 0x${der[0].toString(16).padStart(2, '0')}, expected 0x30 (SEQUENCE)`);
+    const seqLen = der[1];
+    // Strict DER short-form: outer SEQUENCE content for a P-256
+    // ECPrivateKey is at most 51 - 2 = 49 bytes with no public key, or
+    // roughly 51 + 67 - 2 = 116 with a publicKey [1] field; both fit
+    // in short-form. Long-form here would be a non-minimal encoding
+    // for content < 128 bytes.
+    if (seqLen & 0x80)
+        reject('uses long-form length encoding for the outer SEQUENCE (forbidden for content < 128 bytes)');
+    if (2 + seqLen !== der.length)
+        reject(`outer SEQUENCE length ${seqLen} does not match input size (${der.length} bytes total)`);
+    let off = 2;
+    // version INTEGER (1). Strict: exactly `02 01 01`. Any other
+    // length, leading-zero pad, or value rejects.
+    if (der[off] !== INTEGER_TAG)
+        reject(`version tag at offset ${off} is 0x${der[off].toString(16).padStart(2, '0')}, expected 0x02 (INTEGER)`);
+    if (der[off + 1] !== 0x01)
+        reject(`version length at offset ${off + 1} is ${der[off + 1]}, expected 1 (single-byte INTEGER)`);
+    if (der[off + 2] !== 0x01)
+        reject(`version value at offset ${off + 2} is ${der[off + 2]}, expected 1`);
+    off += 3;
+    // privateKey OCTET STRING (32 bytes for P-256).
+    if (der[off] !== OCTET_STRING_TAG)
+        reject(`privateKey tag at offset ${off} is 0x${der[off].toString(16).padStart(2, '0')}, expected 0x04 (OCTET STRING)`);
+    const skLen = der[off + 1];
+    if (skLen & 0x80)
+        reject(`privateKey OCTET STRING at offset ${off + 1} uses long-form length encoding (forbidden for content < 128 bytes)`);
+    if (skLen !== SCALAR_LEN)
+        reject(`privateKey OCTET STRING length at offset ${off + 1} is ${skLen}, expected ${SCALAR_LEN} (P-256 scalar)`);
+    if (off + 2 + skLen > der.length)
+        reject('privateKey OCTET STRING content extends past the outer SEQUENCE end');
+    const scalar = der.slice(off + 2, off + 2 + skLen);
+    off += 2 + skLen;
+    // Optional parameters [0] EXPLICIT. Per RFC 5915 §3 this field is
+    // OPTIONAL; when present it carries the curve OID. We require
+    // secp256r1 specifically; any other OID rejects.
+    if (off < der.length && der[off] === TAG_PARAMETERS_0) {
+        const paramLen = der[off + 1];
+        if (paramLen & 0x80)
+            reject(`parameters [0] at offset ${off + 1} uses long-form length encoding (forbidden for content < 128 bytes)`);
+        if (off + 2 + paramLen > der.length)
+            reject('parameters [0] content extends past the outer SEQUENCE end');
+        if (paramLen !== SECP256R1_OID_DER.length)
+            reject(`parameters [0] content is ${paramLen} bytes, expected ${SECP256R1_OID_DER.length} `
+                + '(secp256r1 OID TLV); other curves are not supported');
+        for (let i = 0; i < paramLen; i++) {
+            if (der[off + 2 + i] !== SECP256R1_OID_DER[i])
+                reject('parameters [0] OID does not match secp256r1 (1.2.840.10045.3.1.7); '
+                    + 'other curves are not supported');
+        }
+        off += 2 + paramLen;
+    }
+    // RFC 5915 §3 OPTIONAL: skip past after minimal length check.
+    if (off < der.length && der[off] === TAG_PUBLIC_KEY_1) {
+        const pkLen = der[off + 1];
+        if (pkLen & 0x80)
+            reject(`publicKey [1] at offset ${off + 1} uses long-form length encoding (forbidden for content < 128 bytes)`);
+        if (off + 2 + pkLen > der.length)
+            reject('publicKey [1] content extends past the outer SEQUENCE end');
+        off += 2 + pkLen;
+    }
+    // No trailing bytes after the (optional) tail fields.
+    if (off !== der.length)
+        reject(`has ${der.length - off} trailing byte(s) after the optional fields`);
+    return scalar;
+}

package/dist/ecdsa/embedded.d.ts

@@ -0,0 +1 @@
+export { WASM_GZ_BASE64 as p256Wasm, WASM_GZ_BASE64 as ecdsaP256Wasm, } from '../embedded/p256.js';

package/dist/ecdsa/embedded.js

@@ -0,0 +1,25 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/ecdsa/embedded.ts
+//
+// `p256Wasm` canonical, `ecdsaP256Wasm` alias.
+export { WASM_GZ_BASE64 as p256Wasm, WASM_GZ_BASE64 as ecdsaP256Wasm, } from '../embedded/p256.js';

package/dist/ecdsa/index.d.ts

@@ -0,0 +1,124 @@
+import { isInitialized } from '../init.js';
+import type { WasmSource } from '../wasm-source.js';
+import type { EcdsaP256KeyPair } from './types.js';
+/**
+ * Initialise the p256 WASM module. Loads the underlying binary
+ * (scalar, no SIMD) into the `p256` slot.
+ */
+export declare function ecdsaP256Init(source: WasmSource): Promise<void>;
+export type { WasmSource };
+export type { EcdsaP256KeyPair, EcdsaP256Exports } from './types.js';
+export { isInitialized };
+export { encodeEcPrivateKey, decodeEcPrivateKey } from './ecprivatekey-der.js';
+/**
+ * Decompress a 33-byte SEC 1 §2.3.3 compressed P-256 public key to the
+ * 65-byte SEC 1 §2.3.4 uncompressed encoding `0x04 || X || Y`.
+ *
+ * The compressed form encodes only the affine x coordinate plus a
+ * single parity bit (in the prefix byte: 0x02 even-y, 0x03 odd-y).
+ * Recovery of y solves the curve equation
+ * `y² = x³ - 3x + b mod p` (SP 800-186 §3.2.1.3, P-256 has a = -3)
+ * and selects the y root whose parity matches the prefix. The
+ * substrate runs the modular square root inside the p256 WASM
+ * (`feSqrt` via the p ≡ 3 (mod 4) shortcut, x^((p+1)/4)); rejecting
+ * invalid inputs that have no square root or whose recovered (x, y)
+ * lies off-curve.
+ *
+ * Rejection cases (all throw `SigningError('sig-malformed-input')`):
+ *   - prefix byte not in {0x02, 0x03}
+ *   - x coordinate is not the x of any on-curve point (no quadratic
+ *     residue exists for `x³ - 3x + b mod p`)
+ *
+ * Length / shape rejections throw `TypeError` / `RangeError` per the
+ * usual leviathan-crypto contract-violation posture.
+ *
+ * Requires `init({ p256: ... })`. Uses the same p256 module singleton
+ * as `EcdsaP256`; concurrency-safe alongside non-stateful uses (the
+ * `_assertNotOwned` check fires if a stateful instance is holding
+ * the module).
+ *
+ * @param pk33 33-byte compressed pk per SEC 1 §2.3.3
+ * @returns    65-byte uncompressed pk per SEC 1 §2.3.4 (0x04 || X || Y)
+ */
+export declare function pointDecompress(pk33: Uint8Array): Uint8Array;
+export declare class EcdsaP256 {
+    constructor();
+    private get mx();
+    /**
+     * Deterministic ECDSA-P256 key generation from a 32-byte seed.
+     * d = seed mod n per FIPS 186-5 §A.4.2 (testing-candidates style,
+     * single candidate). pk = [d]G compressed to 33 bytes per SEC 1
+     * §2.3.3. The vanishingly rare seed mod n == 0 case traps in the
+     * WASM and surfaces as a SigningError here.
+     *
+     * @param seed 32-byte BE input
+     * @returns 33-byte compressed pk and a fresh 32-byte copy of the
+     *          secret scalar d (sk === seed for this derivation, the
+     *          caller may use either as the private value).
+     */
+    keygenDerand(seed: Uint8Array): EcdsaP256KeyPair;
+    /** Random ECDSA-P256 key generation, wraps `keygenDerand` with `randomBytes(32)`. */
+    keygen(): EcdsaP256KeyPair;
+    /**
+     * Key generation that returns the public key in the 65-byte SEC 1
+     * §2.3.4 uncompressed encoding `0x04 || X || Y`, rather than the
+     * 33-byte compressed form `keygen` / `keygenDerand` return. The
+     * secret-key half is the same 32-byte raw scalar `d`.
+     *
+     * Internally runs `keygen` (or `keygenDerand` if a seed is supplied)
+     * to obtain the compressed pk, then `pointDecompress` to expand it.
+     * The compressed intermediate is wiped before return.
+     *
+     * @param seed Optional 32-byte seed; passes through to `keygenDerand`
+     *             when present, falls back to `keygen` (CSPRNG seed) when
+     *             omitted.
+     */
+    keygenUncompressed(seed?: Uint8Array): EcdsaP256KeyPair;
+    /**
+     * Hedged-or-deterministic ECDSA-P256 sign per FIPS 186-5 §6.4 with
+     * RFC 6979 §3.5 low-S normalisation. The K nonce is derived per
+     * RFC 6979 §3.2 (deterministic) when `rnd` is all-zero, or per
+     * draft-irtf-cfrg-det-sigs-with-noise-05 (hedged) otherwise. The
+     * hedged path is the recommended default; pass `randomBytes(32)`.
+     *
+     * The WASM re-derives pk = [d]G internally and compares it against
+     * the caller-supplied `pk`. A mismatch traps via `unreachable` and
+     * is rethrown as `SigningError('sig-malformed-input')`. This
+     * defends against fault injection that would bias the per-signature
+     * randomness derivation by forcing the caller to also know pk.
+     *
+     * @param sk       32-byte secret scalar d
+     * @param pk       33-byte compressed or 65-byte uncompressed pk;
+     *                 cross-checked by WASM after derivation
+     * @param msgHash  32-byte SHA-256(M) digest (caller-computed)
+     * @param rnd      32-byte per-call entropy Z; all-zero selects
+     *                 deterministic RFC 6979 §3.2, non-zero selects
+     *                 the hedged path
+     * @returns 64-byte raw r || s signature, low-S normalised
+     * @throws  SigningError('sig-malformed-input') on pk-mismatch
+     *          (fault-injection trap)
+     */
+    sign(sk: Uint8Array, pk: Uint8Array, msgHash: Uint8Array, rnd: Uint8Array): Uint8Array;
+    /**
+     * Suite-only: hedged-or-deterministic sign that derives pk
+     * internally and skips the fault-injection cross-check. See
+     * AGENTS.md "SignatureSuite lifecycle". Underscore-prefixed,
+     * not part of the public API.
+     */
+    _signInternalPk(sk: Uint8Array, msgHash: Uint8Array, rnd: Uint8Array): Uint8Array;
+    /**
+     * Strict ECDSA-P256 verify per FIPS 186-5 §6.5 with low-S
+     * enforcement (RFC 6979 §3.5). Returns `true` on success, `false`
+     * on every signature failure mode: off-curve / identity pk, r or
+     * s out of [1, n-1], high-S, or the signature equation failing.
+     * Throws only on caller-side contract violations (wrong-length
+     * inputs).
+     *
+     * @param pk       33-byte compressed or 65-byte uncompressed pk
+     * @param msgHash  32-byte SHA-256(M) digest
+     * @param sig      64-byte raw r || s (use `ecdsaSignatureFromDer`
+     *                 to convert DER-encoded signatures first)
+     */
+    verify(pk: Uint8Array, msgHash: Uint8Array, sig: Uint8Array): boolean;
+    dispose(): void;
+}