@waaskey/sdk 0.3.1 → 0.3.2

package/dist/index.d.cts

@@ -245,7 +245,11 @@ interface DeviceSignParams extends CeremonyParams {
 }
 /** Result of the device half of sign. */
 interface DeviceSignResult {
-    /** The cggmp24 signature (JSON). */
+    /**
+     * The signature as LOW-S–normalized compact `r ‖ s` hex (128 chars, no `0x`) — byte-identical to
+     * what the platform's own party produces, so the backend can cross-check the two before embedding
+     * one into a transaction, and chain adapters can slice `r`/`s` by offset.
+     */
     signature: string;
 }
 /**
@@ -570,7 +574,7 @@ declare class WasmMpcCore implements MpcCore {
  * exact, optional peer dependency in `package.json` — so an app that installs `@waaskey/client-wasm`
  * alongside the SDK runs the real ed25519 create/send path end to end.
  */
-declare const CLIENT_WASM_VERSION = "0.2.1";
+declare const CLIENT_WASM_VERSION = "0.2.2";
 /**
  * Verify the integrity of raw wasm bytes against an expected **SHA-384** hash, in
  * Subresource-Integrity (`sha384-<base64>`) form (issue #40).
@@ -1299,24 +1303,33 @@ interface SendResult {
  * signing quorum roster (`roles` in `participants` order) and the WHOLE `message` bytes (ed25519 signs
  * the message, not a digest).
  */
-interface EddsaSendSession {
+interface SendSessionResponse {
     /** The pending signing-activity row id — echoed back to the ASSEMBLE phase to finalize the signed tx. */
     txId: string;
     /** Relay websocket URL the device connects to. */
     relayUrl: string;
     /** Relay session id shared by the device + server parties. */
     sessionId: string;
-    /** The FROST signing quorum's relay roles, in `participants` order (`roles[i]` ↔ `participants[i]`), e.g. `['device','server']`. */
+    /** The wallet's curve — it decides which payload field below is populated and how `participants` is numbered. */
+    curve: WalletCurve;
+    /** The signing quorum's relay roles, in `participants` order (`roles[i]` ↔ `participants[i]`), e.g. `['device','server']`. */
     roles: string[];
-    /** The 1-based FROST identifiers of the quorum, parallel to {@link roles} (e.g. `[1, 2]`). */
+    /**
+     * The quorum's party identifiers, parallel to {@link roles} — **numbered per curve**: ed25519
+     * (FROST) uses 1-based identifiers (`[1, 2]`), secp256k1 (cggmp24) 0-based keygen indices (`[0, 1]`).
+     */
     participants: number[];
     /** This device's own 0-based slot into {@link roles} (its position in the quorum). */
     signerPosition: number;
-    /** The raw message bytes to sign, hex (`0x` prefix optional) — the chain adapter's serialized tx message. */
-    message: string;
+    /** The raw message bytes to sign, hex — **ed25519 only** (FROST signs the message, not a hash). */
+    message?: string;
+    /** The 32-byte tx digest to sign, hex — **secp256k1 only** (cggmp24 signs a digest). */
+    digest?: string;
     /** Short-lived relay token (JWT) the device presents to join this session; present only when relay auth is enabled. */
     relayToken?: string;
 }
+/** @deprecated Use {@link SendSessionResponse} — the shape is curve-agnostic (secp256k1 + ed25519). */
+type EddsaSendSession = SendSessionResponse;
 /** Body of the ASSEMBLE phase (`POST …/send-session/:txId/assemble`) — the aggregated ed25519 signature the backend embeds into the wire tx (backend `AssembleEddsaTxRequest`). */
 interface EddsaAssembleRequest {
     /** The 64-byte RFC 8032 ed25519 signature (hex) the device + server co-produced. */
@@ -1524,33 +1537,37 @@ interface OnrampWidgetUrl {
 /** The recovery factors a wallet enrols (backend `RecoveryFactor`). */
 type RecoveryFactor = 'recovery_code' | 'totp' | 'email_otp';
 /**
- * Enrolment of one factor at register time (backend `FactorEnrollment`).
+ * Enrolment of one factor at register time (backend `FactorEnrollmentDto`).
+ *
+ * The wire field is `credential` for EVERY factor — the API's DTO declares exactly
+ * `{ type, credential }` and its validation pipe rejects any other property.
  *
  * Contract A: the recovery code is a client-side **sealing secret** and must never
- * reach the server, so the `recovery_code` factor enrols `credentialHash` (the
- * lowercase-hex SHA-256 of the code), never the code itself. `totp` / `email_otp`
- * enrol their non-sealing `credential` (base32 secret / email) as before.
+ * reach the server, so for `recovery_code` the `credential` carries the lowercase-hex
+ * SHA-256 of the code, never the code itself (the SDK hashes it in
+ * {@link buildRecoveryRegistration}). `totp` / `email_otp` enrol their non-sealing
+ * credential (base32 secret / email address) verbatim.
  */
 interface FactorEnrollment {
     type: RecoveryFactor;
-    /** totp → base32 secret; email_otp → email address. Omitted for `recovery_code`. */
-    credential?: string;
-    /** recovery_code → lowercase-hex SHA-256 of the recovery code (the raw code never leaves the client). */
-    credentialHash?: string;
+    /** recovery_code → lowercase-hex SHA-256 of the code; totp → base32 secret; email_otp → email address. */
+    credential: string;
 }
 /**
- * One factor's proof at recovery time (backend `FactorVerification`).
+ * One factor's proof at recovery time (backend `FactorVerificationDto`).
+ *
+ * The wire field is `token` for EVERY factor — the API's DTO declares exactly
+ * `{ type, token }` and its validation pipe rejects any other property.
  *
- * Contract A: `recovery_code` proves possession with `credentialHash` (the same
- * SHA-256 the server stored), never the plaintext code — the server compares the
- * hash in constant time and can never derive the code to unseal the ciphertext.
+ * Contract A: a `recovery_code` proof is sent as the same lowercase-hex SHA-256 the
+ * server stored, never the plaintext code — the server compares the hash in constant
+ * time and can never derive the code to unseal the ciphertext. Callers pass the
+ * PLAINTEXT code here; the SDK hashes it before the request leaves the device.
  */
 interface FactorVerification {
     type: RecoveryFactor;
-    /** totp → current 6-digit OTP; email_otp → the emailed OTP. Omitted for `recovery_code`. */
-    token?: string;
-    /** recovery_code → lowercase-hex SHA-256 of the code (matches the enrolled hash). */
-    credentialHash?: string;
+    /** recovery_code → the plaintext code (the SDK sends its SHA-256); totp → current 6-digit OTP; email_otp → the emailed OTP. */
+    token: string;
 }
 /** A registered recovery record's metadata (backend `RecoveryShareResponse`). */
 interface RecoveryShareInfo {
@@ -2088,14 +2105,35 @@ declare class Wallet {
      */
     sign(digest: string, options?: SignOptions): Promise<string>;
     /**
-     * Start this device's half of a secp sign ceremony when the wallet's sign quorum requires it.
-     * The quorum is the first `threshold` roles of the wallet's party list (#292) — for the default
-     * `[device, server, recovery]`/2 that is `[device, server]`, so the device MUST be online and
-     * co-signing. Returns `undefined` when the quorum is platform-only (or the wallet is not secp) —
-     * the POST then completes alone, unchanged. A device-present quorum without the device deps or
-     * stored share fails fast with a typed error instead of a guaranteed server-side timeout.
+     * The roles that will actually sign — the first `threshold` of the wallet's party list (#292),
+     * mirroring the signer's own derivation. `undefined` when the topology is unknown (a legacy
+     * wallet record), which callers treat as "let the server decide".
+     */
+    private signQuorum;
+    /**
+     * Everything this device needs to join a ceremony, resolved BEFORE one is started (#89): the MPC
+     * core, the routed-sign capability a >2-party quorum needs, and the stored key share.
+     *
+     * Each failure is a typed error thrown straight to the caller, and the ordering is the point: a
+     * device that cannot co-sign must never leave the platform party waiting on the relay for a
+     * counterpart that will never arrive. That wait ends at the party-runner timeout (~210s) and
+     * reaches the caller as an opaque 5xx — minutes after a knowable, local cause.
+     */
+    private loadDeviceParty;
+    /**
+     * Normalize a sign-session descriptor into the shared {@link DeviceCeremony}. The 2-party roster
+     * comes from the descriptor's own `role`/`peerRole` (authoritative — the relay token is bound to
+     * that role); a larger quorum carries no server-sent roster, so the wallet's own party slice — the
+     * same slice the signer derives — supplies it.
+     */
+    private toSignCeremony;
+    /**
+     * Run this device's half of a started ceremony. A 2-party quorum uses the plain single-peer
+     * transport; anything larger MUST be roster-routed, or the transport attributes every inbound
+     * message to the one configured peer and the protocol aborts on the third party's first message
+     * (waas-core#131).
      */
-    private startDeviceCoSign;
+    private runDeviceSign;
     /**
      * Send a transaction from this wallet. The platform builds the chain-specific transaction
      * and co-signs it with the 2-of-3 MPC quorum, returning the **signed raw transaction**.
@@ -2111,13 +2149,34 @@ declare class Wallet {
      * server-side). Alternatively supply a pre-built assertion via `options.passkeyAssertion`.
      */
     send(params: SendParams, options?: SendOptions): Promise<SendResult>;
+    /**
+     * Device-co-signed send for a secp wallet — the cggmp24 counterpart of {@link sendEd25519}:
+     *
+     * 1. **START** (`POST …/send-session`): the platform runs the transfer gates, builds the unsigned
+     *    tx, puts its own party on the relay in the background, and returns the 32-byte digest plus
+     *    the relay coordination. It does NOT wait for the ceremony.
+     * 2. **CO-SIGN**: this device runs its half over the relay with its stored share; cggmp24 hands
+     *    the completed signature to both parties.
+     * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the platform verifies the signature
+     *    (recovers to the wallet key AND equals its own party's) and embeds it into the wire tx.
+     *
+     * Every device-side precondition is resolved BEFORE the START (see {@link loadDeviceParty}), so a
+     * device that cannot co-sign costs nothing: no tx is built and no platform party is left waiting.
+     *
+     * **A co-sign that fails after a successful START rejects with its typed error.** START is not the
+     * commit point — it yields an *unsigned* tx and a pending session, and nothing broadcastable exists
+     * until ASSEMBLE returns a `signedTx` — so there is no result to salvage by swallowing the failure,
+     * and no fallback to `POST /send` (the platform cannot reach the threshold on this wallet alone, so
+     * a retry there would only hang). The backend expires the abandoned session and fails the tx row.
+     */
+    private sendWithDevice;
     /**
      * Device-co-signed send for an ed25519 (FROST) wallet (#110) — the browser holds the device FROST
      * share and co-signs 2-party with the backend `server` party over the relay:
      *
      * 1. **START** (`POST …/send-session`): the backend builds the unsigned tx (chain adapter), starts
      *    its server FROST party on the relay in the background, and returns the raw `message` bytes to
-     *    sign + the relay coordination ({@link EddsaSendSession}).
+     *    sign + the relay coordination ({@link SendSessionResponse}).
      * 2. **CO-SIGN**: the device runs `signEddsa` over the relay with its stored `{keyPackage,
      *    publicKeyPackage}` share; the two parties aggregate the RFC 8032 signature (returned locally).
      * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the backend embeds the aggregated

package/dist/index.d.ts

@@ -245,7 +245,11 @@ interface DeviceSignParams extends CeremonyParams {
 }
 /** Result of the device half of sign. */
 interface DeviceSignResult {
-    /** The cggmp24 signature (JSON). */
+    /**
+     * The signature as LOW-S–normalized compact `r ‖ s` hex (128 chars, no `0x`) — byte-identical to
+     * what the platform's own party produces, so the backend can cross-check the two before embedding
+     * one into a transaction, and chain adapters can slice `r`/`s` by offset.
+     */
     signature: string;
 }
 /**
@@ -570,7 +574,7 @@ declare class WasmMpcCore implements MpcCore {
  * exact, optional peer dependency in `package.json` — so an app that installs `@waaskey/client-wasm`
  * alongside the SDK runs the real ed25519 create/send path end to end.
  */
-declare const CLIENT_WASM_VERSION = "0.2.1";
+declare const CLIENT_WASM_VERSION = "0.2.2";
 /**
  * Verify the integrity of raw wasm bytes against an expected **SHA-384** hash, in
  * Subresource-Integrity (`sha384-<base64>`) form (issue #40).
@@ -1299,24 +1303,33 @@ interface SendResult {
  * signing quorum roster (`roles` in `participants` order) and the WHOLE `message` bytes (ed25519 signs
  * the message, not a digest).
  */
-interface EddsaSendSession {
+interface SendSessionResponse {
     /** The pending signing-activity row id — echoed back to the ASSEMBLE phase to finalize the signed tx. */
     txId: string;
     /** Relay websocket URL the device connects to. */
     relayUrl: string;
     /** Relay session id shared by the device + server parties. */
     sessionId: string;
-    /** The FROST signing quorum's relay roles, in `participants` order (`roles[i]` ↔ `participants[i]`), e.g. `['device','server']`. */
+    /** The wallet's curve — it decides which payload field below is populated and how `participants` is numbered. */
+    curve: WalletCurve;
+    /** The signing quorum's relay roles, in `participants` order (`roles[i]` ↔ `participants[i]`), e.g. `['device','server']`. */
     roles: string[];
-    /** The 1-based FROST identifiers of the quorum, parallel to {@link roles} (e.g. `[1, 2]`). */
+    /**
+     * The quorum's party identifiers, parallel to {@link roles} — **numbered per curve**: ed25519
+     * (FROST) uses 1-based identifiers (`[1, 2]`), secp256k1 (cggmp24) 0-based keygen indices (`[0, 1]`).
+     */
     participants: number[];
     /** This device's own 0-based slot into {@link roles} (its position in the quorum). */
     signerPosition: number;
-    /** The raw message bytes to sign, hex (`0x` prefix optional) — the chain adapter's serialized tx message. */
-    message: string;
+    /** The raw message bytes to sign, hex — **ed25519 only** (FROST signs the message, not a hash). */
+    message?: string;
+    /** The 32-byte tx digest to sign, hex — **secp256k1 only** (cggmp24 signs a digest). */
+    digest?: string;
     /** Short-lived relay token (JWT) the device presents to join this session; present only when relay auth is enabled. */
     relayToken?: string;
 }
+/** @deprecated Use {@link SendSessionResponse} — the shape is curve-agnostic (secp256k1 + ed25519). */
+type EddsaSendSession = SendSessionResponse;
 /** Body of the ASSEMBLE phase (`POST …/send-session/:txId/assemble`) — the aggregated ed25519 signature the backend embeds into the wire tx (backend `AssembleEddsaTxRequest`). */
 interface EddsaAssembleRequest {
     /** The 64-byte RFC 8032 ed25519 signature (hex) the device + server co-produced. */
@@ -1524,33 +1537,37 @@ interface OnrampWidgetUrl {
 /** The recovery factors a wallet enrols (backend `RecoveryFactor`). */
 type RecoveryFactor = 'recovery_code' | 'totp' | 'email_otp';
 /**
- * Enrolment of one factor at register time (backend `FactorEnrollment`).
+ * Enrolment of one factor at register time (backend `FactorEnrollmentDto`).
+ *
+ * The wire field is `credential` for EVERY factor — the API's DTO declares exactly
+ * `{ type, credential }` and its validation pipe rejects any other property.
  *
  * Contract A: the recovery code is a client-side **sealing secret** and must never
- * reach the server, so the `recovery_code` factor enrols `credentialHash` (the
- * lowercase-hex SHA-256 of the code), never the code itself. `totp` / `email_otp`
- * enrol their non-sealing `credential` (base32 secret / email) as before.
+ * reach the server, so for `recovery_code` the `credential` carries the lowercase-hex
+ * SHA-256 of the code, never the code itself (the SDK hashes it in
+ * {@link buildRecoveryRegistration}). `totp` / `email_otp` enrol their non-sealing
+ * credential (base32 secret / email address) verbatim.
  */
 interface FactorEnrollment {
     type: RecoveryFactor;
-    /** totp → base32 secret; email_otp → email address. Omitted for `recovery_code`. */
-    credential?: string;
-    /** recovery_code → lowercase-hex SHA-256 of the recovery code (the raw code never leaves the client). */
-    credentialHash?: string;
+    /** recovery_code → lowercase-hex SHA-256 of the code; totp → base32 secret; email_otp → email address. */
+    credential: string;
 }
 /**
- * One factor's proof at recovery time (backend `FactorVerification`).
+ * One factor's proof at recovery time (backend `FactorVerificationDto`).
+ *
+ * The wire field is `token` for EVERY factor — the API's DTO declares exactly
+ * `{ type, token }` and its validation pipe rejects any other property.
  *
- * Contract A: `recovery_code` proves possession with `credentialHash` (the same
- * SHA-256 the server stored), never the plaintext code — the server compares the
- * hash in constant time and can never derive the code to unseal the ciphertext.
+ * Contract A: a `recovery_code` proof is sent as the same lowercase-hex SHA-256 the
+ * server stored, never the plaintext code — the server compares the hash in constant
+ * time and can never derive the code to unseal the ciphertext. Callers pass the
+ * PLAINTEXT code here; the SDK hashes it before the request leaves the device.
  */
 interface FactorVerification {
     type: RecoveryFactor;
-    /** totp → current 6-digit OTP; email_otp → the emailed OTP. Omitted for `recovery_code`. */
-    token?: string;
-    /** recovery_code → lowercase-hex SHA-256 of the code (matches the enrolled hash). */
-    credentialHash?: string;
+    /** recovery_code → the plaintext code (the SDK sends its SHA-256); totp → current 6-digit OTP; email_otp → the emailed OTP. */
+    token: string;
 }
 /** A registered recovery record's metadata (backend `RecoveryShareResponse`). */
 interface RecoveryShareInfo {
@@ -2088,14 +2105,35 @@ declare class Wallet {
      */
     sign(digest: string, options?: SignOptions): Promise<string>;
     /**
-     * Start this device's half of a secp sign ceremony when the wallet's sign quorum requires it.
-     * The quorum is the first `threshold` roles of the wallet's party list (#292) — for the default
-     * `[device, server, recovery]`/2 that is `[device, server]`, so the device MUST be online and
-     * co-signing. Returns `undefined` when the quorum is platform-only (or the wallet is not secp) —
-     * the POST then completes alone, unchanged. A device-present quorum without the device deps or
-     * stored share fails fast with a typed error instead of a guaranteed server-side timeout.
+     * The roles that will actually sign — the first `threshold` of the wallet's party list (#292),
+     * mirroring the signer's own derivation. `undefined` when the topology is unknown (a legacy
+     * wallet record), which callers treat as "let the server decide".
+     */
+    private signQuorum;
+    /**
+     * Everything this device needs to join a ceremony, resolved BEFORE one is started (#89): the MPC
+     * core, the routed-sign capability a >2-party quorum needs, and the stored key share.
+     *
+     * Each failure is a typed error thrown straight to the caller, and the ordering is the point: a
+     * device that cannot co-sign must never leave the platform party waiting on the relay for a
+     * counterpart that will never arrive. That wait ends at the party-runner timeout (~210s) and
+     * reaches the caller as an opaque 5xx — minutes after a knowable, local cause.
+     */
+    private loadDeviceParty;
+    /**
+     * Normalize a sign-session descriptor into the shared {@link DeviceCeremony}. The 2-party roster
+     * comes from the descriptor's own `role`/`peerRole` (authoritative — the relay token is bound to
+     * that role); a larger quorum carries no server-sent roster, so the wallet's own party slice — the
+     * same slice the signer derives — supplies it.
+     */
+    private toSignCeremony;
+    /**
+     * Run this device's half of a started ceremony. A 2-party quorum uses the plain single-peer
+     * transport; anything larger MUST be roster-routed, or the transport attributes every inbound
+     * message to the one configured peer and the protocol aborts on the third party's first message
+     * (waas-core#131).
      */
-    private startDeviceCoSign;
+    private runDeviceSign;
     /**
      * Send a transaction from this wallet. The platform builds the chain-specific transaction
      * and co-signs it with the 2-of-3 MPC quorum, returning the **signed raw transaction**.
@@ -2111,13 +2149,34 @@ declare class Wallet {
      * server-side). Alternatively supply a pre-built assertion via `options.passkeyAssertion`.
      */
     send(params: SendParams, options?: SendOptions): Promise<SendResult>;
+    /**
+     * Device-co-signed send for a secp wallet — the cggmp24 counterpart of {@link sendEd25519}:
+     *
+     * 1. **START** (`POST …/send-session`): the platform runs the transfer gates, builds the unsigned
+     *    tx, puts its own party on the relay in the background, and returns the 32-byte digest plus
+     *    the relay coordination. It does NOT wait for the ceremony.
+     * 2. **CO-SIGN**: this device runs its half over the relay with its stored share; cggmp24 hands
+     *    the completed signature to both parties.
+     * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the platform verifies the signature
+     *    (recovers to the wallet key AND equals its own party's) and embeds it into the wire tx.
+     *
+     * Every device-side precondition is resolved BEFORE the START (see {@link loadDeviceParty}), so a
+     * device that cannot co-sign costs nothing: no tx is built and no platform party is left waiting.
+     *
+     * **A co-sign that fails after a successful START rejects with its typed error.** START is not the
+     * commit point — it yields an *unsigned* tx and a pending session, and nothing broadcastable exists
+     * until ASSEMBLE returns a `signedTx` — so there is no result to salvage by swallowing the failure,
+     * and no fallback to `POST /send` (the platform cannot reach the threshold on this wallet alone, so
+     * a retry there would only hang). The backend expires the abandoned session and fails the tx row.
+     */
+    private sendWithDevice;
     /**
      * Device-co-signed send for an ed25519 (FROST) wallet (#110) — the browser holds the device FROST
      * share and co-signs 2-party with the backend `server` party over the relay:
      *
      * 1. **START** (`POST …/send-session`): the backend builds the unsigned tx (chain adapter), starts
      *    its server FROST party on the relay in the background, and returns the raw `message` bytes to
-     *    sign + the relay coordination ({@link EddsaSendSession}).
+     *    sign + the relay coordination ({@link SendSessionResponse}).
      * 2. **CO-SIGN**: the device runs `signEddsa` over the relay with its stored `{keyPackage,
      *    publicKeyPackage}` share; the two parties aggregate the RFC 8032 signature (returned locally).
      * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the backend embeds the aggregated