@cavos/kit 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,529 @@
+import { Account, Signer, ArraySignatureType } from 'starknet';
+import { D as DevicePublicKey, S as StarknetNetwork, a as DeviceSigner, C as ChainCall, b as DeviceSignature, c as ChainAdapter, d as ComputeAddressParams } from './constants-C530TZFF.js';
+export { e as DEVICE_ACCOUNT_CLASS_HASH, f as STARKNET_NETWORKS, U as UDC_ADDRESS } from './constants-C530TZFF.js';
+
+/**
+ * Identity for a Cavos wallet. Login (email / social / OTP) only ever produces a
+ * stable `userId`; that's all the wallet needs to derive its address. Auth never
+ * touches signing — the device key does that, silently.
+ *
+ * Privy-style UX: the user "logs in" and the wallet is provisioned behind the
+ * scenes (device key + auto-deployed smart account). The app never handles keys.
+ */
+interface Identity {
+    /** Stable, backend-managed user identifier. */
+    userId: string;
+    /** Optional metadata (email, provider) for display only. */
+    email?: string;
+    provider?: "google" | "apple" | "email" | "otp" | string;
+}
+/**
+ * Authenticates a user and returns their stable identity. Implementations:
+ * - `CavosAuth` (hosted, mirrors `@cavos/react`: Google/Apple/email/OTP via the
+ *   Cavos backend) — the default, Privy-like experience.
+ * - any custom provider (the app already authenticated the user elsewhere).
+ */
+interface AuthProvider {
+    authenticate(): Promise<Identity>;
+}
+/** Trivial provider when the app already has the user's stable id. */
+declare class StaticIdentity implements AuthProvider {
+    private readonly identity;
+    constructor(identity: Identity);
+    authenticate(): Promise<Identity>;
+}
+
+/**
+ * Off-chain map of `user_id -> wallet`. Because the account address is
+ * `f(identity, first_device_pubkey)` (unforgeable, secure), it is NOT derivable
+ * from the identity alone on a new device. The backend is the source of truth
+ * for "does this user already have a wallet?" — enabling multi-device:
+ *
+ *   - First device, unknown user  -> deploy a new wallet, then `register`.
+ *   - Same user, new device        -> `lookup` returns the existing wallet; the
+ *                                      new device is added as a signer (recovery
+ *                                      approval), NOT a new wallet.
+ *
+ * The backend implements this (it already manages the user<->address binding).
+ */
+interface WalletRegistry {
+    /** The user's existing wallet, or null if they don't have one yet. */
+    lookup(userId: string): Promise<RegisteredWallet | null>;
+    /** Record a freshly deployed wallet for the user (first device). */
+    register(params: {
+        userId: string;
+        address: string;
+        initialSigner: DevicePublicKey;
+    }): Promise<void>;
+    /** Note an additional device signer for the user's wallet (after approval). */
+    addDevice?(params: {
+        userId: string;
+        address: string;
+        signer: DevicePublicKey;
+    }): Promise<void>;
+}
+interface RegisteredWallet {
+    address: string;
+    /** Public keys of the devices registered on this wallet (if tracked). */
+    devices?: DevicePublicKey[];
+}
+/** Simple in-memory registry for demos / tests. */
+declare class InMemoryWalletRegistry implements WalletRegistry {
+    private wallets;
+    lookup(userId: string): Promise<RegisteredWallet | null>;
+    register(params: {
+        userId: string;
+        address: string;
+        initialSigner: DevicePublicKey;
+    }): Promise<void>;
+    addDevice(params: {
+        userId: string;
+        address: string;
+        signer: DevicePublicKey;
+    }): Promise<void>;
+}
+
+/**
+ * Multi-device / recovery flow (roadmap §1.2). A new device requests addition;
+ * the backend emails an approval prompt styled as a login request; the user
+ * approves on an ALREADY-registered device, which signs `add_signer` for the
+ * new pubkey. There is no legacy JWT path — recovery is purely device-signer
+ * based.
+ *
+ * The backend lives outside this repo; this is the client contract the kit
+ * speaks to. Provide an implementation (HTTP, etc.) when wiring an app.
+ */
+interface RecoveryClient {
+    /**
+     * Step 1 (new device): request that this pubkey be added to the user's
+     * account. Triggers the approval email. Returns a request id to poll.
+     */
+    requestDeviceAddition(params: {
+        userId: string;
+        accountAddress: string;
+        newSigner: DevicePublicKey;
+        /** Owner email to send the approval link to (the SDK has it from login). */
+        email?: string;
+        /** Optional device label (browser/UA) shown in the approval email. */
+        deviceLabel?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    /**
+     * Step 3-4 (existing device): fetch a pending addition request so the
+     * registered device can approve it by signing `add_signer`.
+     */
+    getPendingRequest(requestId: string): Promise<PendingDeviceRequest | null>;
+    /** Mark a request approved after the `add_signer` tx is submitted. */
+    confirmDeviceAddition(params: {
+        requestId: string;
+        txHash: string;
+    }): Promise<void>;
+}
+interface PendingDeviceRequest {
+    requestId: string;
+    appId?: string;
+    userId: string;
+    accountAddress: string;
+    newSigner: DevicePublicKey;
+    createdAt: string;
+    status: "pending" | "approved" | "expired";
+}
+
+interface ConnectOptions {
+    network: StarknetNetwork;
+    /** Authenticated user (pass `identity` directly, or an `auth` provider). */
+    auth?: AuthProvider;
+    identity?: Identity;
+    appSalt: string;
+    /**
+     * Cavos App ID. When set (with `backendUrl`), the kit uses the hosted
+     * WalletRegistry + RecoveryClient by default for real multi-device support.
+     */
+    appId?: string;
+    /** Cavos backend base URL. Defaults to https://cavos.xyz. */
+    backendUrl?: string;
+    /**
+     * Off-chain user_id -> wallet map. Defaults to the hosted HttpWalletRegistry
+     * when `appId` is set, else an in-memory registry (single-device only).
+     */
+    registry?: WalletRegistry;
+    /**
+     * Device-approval relay. Defaults to HttpRecoveryClient when `appId` is set;
+     * used to request addition of this device when it isn't an authorized signer.
+     */
+    recovery?: RecoveryClient;
+    /** Cavos paymaster API key (sponsors deploy + execute). */
+    paymasterApiKey: string;
+    paymasterUrl?: string;
+    rpcUrl?: string;
+    classHash?: string;
+    /** Override the device signer factory (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+}
+/** Whether this device can already operate the wallet, or needs to be added. */
+type ConnectStatus = "ready" | "needs-device-approval";
+/** Options for recovering an account after losing every device signer. */
+interface RecoveryOptions {
+    /** The recovery code the user stored when they ran setupRecovery. */
+    code: string;
+    /** Authenticated identity (same user who owns the account). */
+    identity: Identity;
+    network: StarknetNetwork;
+    appSalt: string;
+    paymasterApiKey: string;
+    appId?: string;
+    backendUrl?: string;
+    rpcUrl?: string;
+    paymasterUrl?: string;
+    classHash?: string;
+    /** Off-chain user_id -> wallet map. Defaults to the hosted registry. */
+    registry?: WalletRegistry;
+    /** Override the new device's signer (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+}
+/**
+ * High-level Cavos wallet. One call logs the user in and returns a ready, gas-
+ * sponsored smart account controlled by a silent device key.
+ *
+ *   const cavos = await Cavos.connect({ network, identity, appSalt, registry, paymasterApiKey });
+ *   if (cavos.status === "ready") await cavos.execute(calls);
+ *
+ * The account address is `f(identity, device_pubkey)` — unforgeable, so it can't
+ * be hijacked. The `registry` recognizes returning users across devices: a new
+ * device on an existing account is flagged `needs-device-approval` (add it via
+ * an already-registered device) instead of creating a second wallet.
+ */
+declare class Cavos {
+    readonly identity: Identity;
+    readonly address: string;
+    readonly status: ConnectStatus;
+    readonly account: Account;
+    private readonly adapter;
+    private readonly devicePubkey;
+    /** Request id of the pending device-addition, when status is needs-device-approval. */
+    pendingRequestId: string | null;
+    private constructor();
+    static connect(opts: ConnectOptions): Promise<Cavos>;
+    /** This device's public key (e.g. to request addition to an existing wallet). */
+    get publicKey(): DevicePublicKey;
+    /** Execute a sponsored (gasless) multicall, signed silently by the device. */
+    execute(calls: ChainCall[]): Promise<{
+        transactionHash: string;
+    }>;
+    /** Authorize an additional device signer (sponsored). Self-submitted. */
+    addSigner(pubkey: DevicePublicKey): Promise<{
+        transactionHash: string;
+    }>;
+    /**
+     * Register a self-custodial backup signer derived from `code`, so the account
+     * can be recovered after the user loses every device. Idempotent: if the
+     * derived backup key is already an authorised signer, this is a no-op.
+     *
+     * The code never leaves the device — only its deterministic public key is
+     * added on-chain as an ordinary signer. Sponsor this like any other
+     * add_signer (gasless). Returns the transaction hash (or undefined when the
+     * backup was already set up).
+     */
+    setupRecovery(code: string): Promise<{
+        transactionHash: string;
+    } | undefined>;
+    /**
+     * Recover an account after losing every device signer. Derives the backup key
+     * from `code`, uses it (not the new device key) to sign an `add_signer` for
+     * the new device, and returns a ready Cavos bound to the new device. The
+     * account address is unchanged.
+     *
+     * Self-custodial: only someone holding the code (i.e. the rightful owner) can
+     * re-derive the backup key. The backend never sees the code.
+     */
+    static recover(opts: RecoveryOptions): Promise<Cavos>;
+}
+
+interface CavosAuthOptions {
+    /** Cavos backend base URL. Defaults to the hosted service (same as @cavos/react). */
+    backendUrl?: string;
+    /** App identifier registered with Cavos (the `appId` from the dashboard). */
+    appId?: string;
+}
+/**
+ * Hosted login (Privy-like) backed by the Cavos backend — same endpoints
+ * `@cavos/react` uses (Google / Apple OAuth + Firebase email OTP). Login only
+ * resolves a stable `userId` (the OAuth `sub` claim); it never touches signing.
+ * Feed the returned `Identity` to `Cavos.connect`.
+ *
+ *   const auth = new CavosAuth({ appId });
+ *   // social: open the returned URL; user returns, then:
+ *   const identity = await auth.handleCallback(window.location.search);
+ *   // or email OTP:
+ *   await auth.sendOtp(email); const identity = await auth.verifyOtp(email, code);
+ *   const cavos = await Cavos.connect({ network, appSalt, identity, paymasterApiKey });
+ *
+ * Device-signer model note: the backend issues a Cavos JWT (the same one react
+ * uses for on-chain RSA verification). Here we only need the stable `sub` claim
+ * from it — the RSA/JWKS/nonce machinery react relies on is dead weight for the
+ * device model, because the device key (not the JWT) authorizes on-chain calls.
+ * We still send a `nonce` (Poseidon over random bytes) since the backend expects
+ * it on the request; the value itself is irrelevant to us.
+ */
+declare class CavosAuth implements AuthProvider {
+    private readonly opts;
+    private readonly backendUrl;
+    /** Most recent nonce sent to the backend (for the pending OAuth/OTP request). */
+    private pendingNonce;
+    private last;
+    constructor(opts?: CavosAuthOptions);
+    /** Redirect URL for Google login (open it; user returns to your redirectUri). */
+    getGoogleOAuthUrl(redirectUri?: string): Promise<string>;
+    /** Redirect URL for Apple login. */
+    getAppleOAuthUrl(redirectUri?: string): Promise<string>;
+    private oauthUrl;
+    /**
+     * Resolve the identity from an OAuth callback. The auth data is carried in the
+     * `auth_data` (or `zk_auth_data`) query param on return. We only extract `sub`.
+     */
+    handleCallback(authDataOrSearch: string): Promise<Identity>;
+    /** Send a one-time code to an email (Firebase OTP). */
+    sendOtp(email: string): Promise<void>;
+    /** Send a passwordless magic-link sign-in email (Firebase). */
+    sendMagicLink(email: string): Promise<void>;
+    /** Verify the OTP and resolve the identity. */
+    verifyOtp(email: string, code: string): Promise<Identity>;
+    /** AuthProvider: returns the identity resolved by the last login step. */
+    authenticate(): Promise<Identity>;
+    /**
+     * Build an `Identity` from whatever the backend returned. The Cavos backend
+     * wraps the user id in a JWT (its `sub` claim); for the device model we only
+     * need that stable id — the signature is never checked on-chain.
+     */
+    private identityFromAuthData;
+    /** Generate (and remember) the nonce the Cavos backend expects on requests. */
+    private freshNonce;
+    /** Return the pending nonce (for the verify step), clearing it. */
+    private consumeNonce;
+    private remember;
+    private get;
+    private post;
+}
+
+/**
+ * The address seed binds a wallet to a stable, backend-managed user identity.
+ * The deterministic account address is derived from this seed + salt ONLY — never
+ * from a device pubkey — so the same user resolves to the same wallet on any
+ * device. The backend owns the user_id <-> address mapping off-chain.
+ */
+interface IdentityInput {
+    /** Stable, backend-managed user identifier (e.g. from email / magic link). */
+    userId: string;
+    /** Per-app salt, so the same user has distinct wallets across apps. */
+    appSalt: string;
+}
+/** Derive the felt `address_seed` passed to the contract constructor. */
+declare function deriveAddressSeed({ userId, appSalt }: IdentityInput): bigint;
+
+interface HttpWalletRegistryOptions {
+    /** Cavos backend base URL (e.g. https://cavos.xyz). */
+    baseUrl: string;
+    /** The Cavos App ID — authenticates the SDK calls (verifyAppId). */
+    appId: string;
+    /** Network the wallet lives on (e.g. "sepolia"). */
+    network: string;
+}
+/**
+ * WalletRegistry backed by the Cavos backend (`/api/wallets`). This is the
+ * persistent, cross-device source of truth for `user_id -> wallet`. The backend
+ * stores authorized device signers in `wallet_devices`; the registry maps a
+ * backend `userId` (the OAuth `sub`) onto that wallet row.
+ */
+declare class HttpWalletRegistry implements WalletRegistry {
+    private readonly opts;
+    constructor(opts: HttpWalletRegistryOptions);
+    lookup(userId: string): Promise<RegisteredWallet | null>;
+    register(params: {
+        userId: string;
+        address: string;
+        initialSigner: DevicePublicKey;
+    }): Promise<void>;
+    addDevice?(params: {
+        userId: string;
+        address: string;
+        signer: DevicePublicKey;
+    }): Promise<void>;
+}
+
+interface HttpRecoveryClientOptions {
+    /** Cavos backend base URL (e.g. https://cavos.xyz). */
+    baseUrl: string;
+    /** The Cavos App ID — authenticates SDK calls. */
+    appId: string;
+}
+/**
+ * RecoveryClient backed by the Cavos backend's device-approval relay
+ * (`/api/devices/request`). The relay holds NO keys — it stores the pending
+ * request, emails the wallet owner, and mirrors the on-chain `add_signer` once a
+ * registered device confirms.
+ */
+declare class HttpRecoveryClient implements RecoveryClient {
+    private readonly opts;
+    constructor(opts: HttpRecoveryClientOptions);
+    requestDeviceAddition(params: {
+        userId: string;
+        accountAddress: string;
+        newSigner: DevicePublicKey;
+        email?: string;
+        deviceLabel?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    getPendingRequest(requestId: string): Promise<PendingDeviceRequest | null>;
+    confirmDeviceAddition(params: {
+        requestId: string;
+        txHash: string;
+    }): Promise<void>;
+}
+
+/**
+ * Generate a fresh, human-readable recovery code. The caller MUST present this
+ * to the user exactly once and never persist it server-side. ~128 bits of
+ * entropy encoded as words from a fixed wordlist (BIP39-style but our own list,
+ * so we don't pull a dependency on a BIP39 wordfile).
+ */
+declare function generateRecoveryCode(): string;
+/**
+ * Deterministically derive a secp256r1 keypair from a recovery code. Pure
+ * function: the same normalised code always yields the same keypair, on any
+ * runtime. Returns the raw 32-byte private key (so it can be wrapped in a
+ * `BackupSigner` or fed to any chain adapter) plus the public key coordinates
+ * the contract stores as an authorised signer.
+ *
+ * Normalisation trims surrounding whitespace and collapses runs of spaces, so
+ * "a  b" and "a b" derive the same key regardless of how the code was pasted.
+ */
+declare function deriveBackupKey(code: string): {
+    privateKey: Uint8Array;
+    publicKey: DevicePublicKey;
+};
+/**
+ * A `DeviceSigner` backed by an in-memory backup key derived from a recovery
+ * code. Used transiently during recovery to sign the `add_signer` that
+ * authorises a new device — it is NOT persisted and should not be reused as a
+ * device signer. The key material lives only for the duration of the recovery
+ * transaction.
+ */
+declare class BackupSigner implements DeviceSigner {
+    private readonly privateKey;
+    private readonly publicKeyValue;
+    constructor(privateKey: Uint8Array, publicKey: DevicePublicKey);
+    /** Build a signer from a recovery code (derive + wrap in one step). */
+    static fromCode(code: string): BackupSigner;
+    getPublicKey(): Promise<DevicePublicKey>;
+    sign(txHash: Uint8Array): Promise<DeviceSignature>;
+}
+
+interface WebCryptoSignerOptions {
+    /**
+     * Storage key for the device's private key (e.g. the account address). One
+     * silent key per (this value, browser profile).
+     */
+    keyId: string;
+}
+/**
+ * Silent, device-bound signer for the browser. Generates a non-extractable
+ * secp256r1 (P-256) key via WebCrypto and stores the `CryptoKey` in IndexedDB.
+ * The private key is never exposed to JS and signing produces NO UI — there is
+ * no passkey, no Face ID / Touch ID prompt. To the user it is invisible; they
+ * only ever see the OAuth / email login used to derive their address.
+ */
+declare class WebCryptoSigner implements DeviceSigner {
+    private readonly privateKey;
+    private readonly publicKey;
+    readonly keyId: string;
+    private constructor();
+    /** Create a fresh device key (first run on this device) and persist it. */
+    static create(opts: WebCryptoSignerOptions): Promise<WebCryptoSigner>;
+    /** Load an existing device key from storage, or null if none exists yet. */
+    static load(opts: WebCryptoSignerOptions): Promise<WebCryptoSigner | null>;
+    /** Load the device key, creating one on first use. */
+    static loadOrCreate(opts: WebCryptoSignerOptions): Promise<WebCryptoSigner>;
+    getPublicKey(): Promise<DevicePublicKey>;
+    sign(txHash: Uint8Array): Promise<DeviceSignature>;
+}
+
+interface StarknetAdapterOptions {
+    classHash: string;
+    /** Read provider for `isAuthorizedSigner`. Optional for build-only usage. */
+    provider?: {
+        callContract(call: {
+            contractAddress: string;
+            entrypoint: string;
+            calldata: string[];
+        }): Promise<string[]>;
+    };
+    /** Signer used to sign outgoing transactions. */
+    signer?: DeviceSigner;
+}
+/** Starknet implementation of the device-signer account adapter. */
+declare class StarknetAdapter implements ChainAdapter {
+    private readonly opts;
+    readonly chain: "starknet";
+    constructor(opts: StarknetAdapterOptions);
+    computeAddress({ addressSeed, initialSigner, salt }: ComputeAddressParams): string;
+    /** Single UDC deploy; the constructor registers the first device signer, so
+     * the account is ready the moment it is deployed (fits the paymaster's
+     * deploy + execute_from_outside bundle). */
+    buildDeploy(params: ComputeAddressParams): ChainCall[];
+    /** Constructor calldata: [address_seed, pub_x_low, pub_x_high, pub_y_low, pub_y_high]. */
+    constructorCalldata(addressSeed: bigint, initialSigner: DevicePublicKey): string[];
+    buildAddSigner(accountAddress: string, signer: DevicePublicKey): ChainCall;
+    buildRemoveSigner(accountAddress: string, signer: DevicePublicKey): ChainCall;
+    isAuthorizedSigner(accountAddress: string, signer: DevicePublicKey): Promise<boolean>;
+    buildSignature(txHash: bigint): Promise<string[]>;
+}
+
+/**
+ * A starknet.js `SignerInterface` backed by a device signer. Extends the base
+ * `Signer` so all transaction/declare hash computation (v3) is reused; only the
+ * raw hash-signing primitive is overridden to sign silently with the device key.
+ *
+ * Usage:
+ *   const account = new Account(provider, address, new StarknetDeviceSigner(device), "1");
+ *   await account.execute(calls); // DeviceAccount validates the device signature
+ *
+ * For gasless flows, hand this signer to your paymaster SDK (e.g. AVNU) the same
+ * way you would any starknet.js signer.
+ */
+declare class StarknetDeviceSigner extends Signer {
+    private readonly device;
+    constructor(device: DeviceSigner);
+    /** Device accounts are not controlled by a single Stark pubkey. */
+    getPubKey(): Promise<string>;
+    /** Sign the computed tx hash silently with the device signer. */
+    protected signRaw(msgHash: string): Promise<ArraySignatureType>;
+}
+
+/**
+ * Serialize a device signature to the felt array for `tx_info.signature`:
+ *   [ r_low, r_high, s_low, s_high, y_parity ]
+ * exactly what DeviceAccount.__validate__ decodes.
+ */
+declare function signatureToFelts(sig: DeviceSignature): bigint[];
+/**
+ * Recover the parity bit of an (r, s) signature over `digest` for a known
+ * pubkey. WebCrypto/Secure Enclave don't return a recovery id, so we derive it
+ * by trying both candidates and matching the device's public key.
+ */
+declare function recoverYParity(r: bigint, s: bigint, digest: Uint8Array, pubkey: DevicePublicKey): boolean;
+
+/**
+ * Low-level encoding helpers shared across the kit.
+ */
+/** Split a u256 into the `[low, high]` felt pair Cairo expects. */
+declare function u256ToFelts(value: bigint): [bigint, bigint];
+/** Big-endian bytes -> bigint. */
+declare function bytesToBigInt(bytes: Uint8Array): bigint;
+declare function bytesToHex(bytes: Uint8Array): string;
+declare function hexToBytes(hex: string): Uint8Array;
+/** A felt/bigint -> 32-byte big-endian Uint8Array (the tx-hash width). */
+declare function bigIntTo32Bytes(value: bigint): Uint8Array;
+
+export { type AuthProvider, BackupSigner, Cavos, CavosAuth, type CavosAuthOptions, ChainAdapter, ChainCall, ComputeAddressParams, type ConnectOptions, type ConnectStatus, DevicePublicKey, DeviceSignature, DeviceSigner, HttpRecoveryClient, type HttpRecoveryClientOptions, HttpWalletRegistry, type HttpWalletRegistryOptions, type Identity, type IdentityInput, InMemoryWalletRegistry, type PendingDeviceRequest, type RecoveryClient, type RecoveryOptions, type RegisteredWallet, StarknetAdapter, type StarknetAdapterOptions, StarknetDeviceSigner, StarknetNetwork, StaticIdentity, type WalletRegistry, WebCryptoSigner, type WebCryptoSignerOptions, bigIntTo32Bytes, bytesToBigInt, bytesToHex, deriveAddressSeed, deriveBackupKey, generateRecoveryCode, hexToBytes, recoverYParity, signatureToFelts, u256ToFelts };