@chipi-stack/backend 14.15.0 → 14.16.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { ChipiTransactions } from './transactions.mjs';
 import { ChipiSkuPurchases } from './skuPurchases.mjs';
 import { ChipiSkus } from './skus.mjs';
 import { C as ChipiClient } from './client-D6SDBu5p.mjs';
-import { Call, ProviderInterface, Account } from 'starknet';
+import { Call, TypedData, ProviderInterface, Account } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -649,9 +649,13 @@ declare class ChipiAi {
      * session key: a USDC `transfer` to the offer's `payTo`, then the same call
      * again with `X-PAYMENT`. The price must be at most `maxAmount`, `model`
      * must be payable and the input within `maxPromptBytes`, all checked before
-     * paying. The session must whitelist `transfer` and cap USDC. A payment
-     * that was made but not served is reported in `error.details.xPayment`;
-     * pass it back as `options.xPayment` to retry without paying again.
+     * paying. The wallet must be a wallet of the organization that owns the
+     * `sk_`: the first request names it in `X-PAYER`, and when the API answers
+     * that a payment from it would be refused, nothing is paid
+     * (`X402_PAYER_NOT_IN_ORG`). The session must whitelist `transfer` and cap
+     * USDC. A payment that was made but not served is reported in
+     * `error.details.xPayment`; pass it back as `options.xPayment` to retry
+     * without paying again.
      *
      * @example
      * ```typescript
@@ -751,11 +755,18 @@ declare class X402Facilitator {
      * Verify a payment signature is valid (doesn't execute the transfer).
      *
      * Checks:
-     * 1. Nonce has not been used (replay protection)
-     * 2. Payment has not expired (validUntil > now)
-     * 3. Asset is USDC mainnet
-     * 4. Amount is positive
-     * 5. Addresses are non-empty
+     * 1. x402 version is 1
+     * 2. Network is starknet-mainnet
+     * 3. Nonce has not been used (replay protection)
+     * 4. Payment has not expired (validUntil > now)
+     * 5. Asset is USDC mainnet
+     * 6. Amount is positive
+     * 7. Addresses are non-empty
+     * 8. Signature: with a `provider`, the payer account's `is_valid_signature`
+     *    must return 'VALID'. Without one, only its presence is checked (not a
+     *    cryptographic check). SHHH payloads must sign exactly one transfer
+     *    of `amount` of `asset` to `toAddress`; their signature is checked
+     *    on-chain at settle.
      */
     verify(payment: PaymentPayload): Promise<VerifyResponse>;
     /**
@@ -1468,6 +1479,148 @@ declare class SessionTxVerifier {
     verifyTransfer(params: VerifyTransferParams): Promise<VerifyTransferResult>;
 }
 
+/** SRC-6 `is_valid_signature` magic value: the short string 'VALID'. */
+declare const STARKNET_SIGNATURE_VALID = "0x56414c4944";
+/** Anything with a starknet.js-style `callContract` (e.g. `RpcProvider`). */
+interface StarknetCallProvider {
+    callContract(call: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata?: string[];
+    }): Promise<string[]>;
+}
+type StarknetSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED";
+    detail?: string;
+};
+/** `0x` + 64 hex, lowercase. Wallets differ on padding; compare on this. */
+declare function normalizeStarknetAddress(address: string): string;
+/**
+ * Asks the account itself (SRC-6 `is_valid_signature`) whether `signature`
+ * signs `messageHash`. The full signature array is passed through, so
+ * multi-felt signatures (Argent, Braavos, multisig) work.
+ *
+ * Only 'VALID' counts: accounts return 0 or panic on a bad signature, and a
+ * lax "anything non-zero" check would accept garbage. An account that is not
+ * deployed yet comes back as ACCOUNT_NOT_DEPLOYED so the caller can fall back
+ * to `verifyUndeployedStarknetSignature`.
+ */
+declare function isValidStarknetSignature(provider: StarknetCallProvider, accountAddress: string, messageHash: string, signature: Array<string | number | bigint>): Promise<StarknetSignatureCheck>;
+/** Account classes whose undeployed signatures we can check off-chain. */
+declare const COUNTERFACTUAL_ACCOUNT_CLASSES: {
+    /** OpenZeppelin AccountUpgradeable 3.0 (Bramble's default account). */
+    readonly OPENZEPPELIN_V3: "0x01d1777db36cdd06dd62cfde77b1b6ae06412af95d57a13dc40ac77b8a702381";
+    /** Argent X / Ready 0.4 (`WALLET_CLASS_HASHES.READY`). */
+    readonly ARGENT_V0_4: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f";
+};
+/** What a wallet returns from `wallet_deploymentData`. */
+interface StarknetDeploymentData {
+    address: string;
+    class_hash: string;
+    salt: string;
+    calldata: string[];
+}
+type UndeployedSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH" | "INVALID_SIGNATURE";
+};
+/**
+ * Checks a signature from an account that is not deployed yet (new Bramble
+ * and Ready accounts stay counterfactual until their first transaction), using
+ * the wallet's `wallet_deploymentData`:
+ *
+ * 1. The class must be one we know how to read: OpenZeppelin 3.0 or Argent 0.4
+ *    without a guardian.
+ * 2. The address must be the one those exact constructor arguments deploy to.
+ * 3. The signature must be the owner key's ECDSA signature of the hash.
+ */
+declare function verifyUndeployedStarknetSignature(deployment: StarknetDeploymentData, messageHash: string, signature: Array<string | number | bigint>): UndeployedSignatureCheck;
+
+/**
+ * Sign in with Starknet (SIWS): the SNIP-12 equivalent of Sign-In with
+ * Ethereum. The server issues a one-time nonce, the wallet signs this typed
+ * data, and the server checks the signature with the account itself.
+ *
+ * The typed data is kept to what every wallet accepts: SNIP-12 revision 1,
+ * mainnet chain id in the domain, single-line printable ASCII strings (Bramble
+ * refuses anything else), and no custom `u256`.
+ */
+declare const SIWS_DOMAIN_NAME = "Sign in with Starknet";
+declare const SIWS_DOMAIN_VERSION = "1";
+declare const SIWS_CHAIN_ID = "SN_MAIN";
+interface StarknetSignInParams {
+    /** Host asking for the sign-in, e.g. "vela-starknet.vercel.app". */
+    domain: string;
+    /** Full URL of the app, e.g. "https://vela-starknet.vercel.app". */
+    uri: string;
+    /** Account that signs. Any padding; stored as 0x + 64 hex. */
+    address: string;
+    /** One-time server nonce (letters and digits). */
+    nonce: string;
+    /** Shown to the user in the wallet. */
+    statement?: string;
+    /** Unix seconds. Defaults to now. */
+    issuedAt?: number;
+    /** Unix seconds. */
+    expirationTime: number;
+}
+interface StarknetSignInMessage {
+    domain: string;
+    address: string;
+    statement: string;
+    uri: string;
+    nonce: string;
+    issuedAt: number;
+    expirationTime: number;
+}
+/** Typed data for the wallet's `wallet_signTypedData`. */
+declare function createStarknetSignInTypedData(params: StarknetSignInParams): TypedData;
+interface VerifyStarknetSignInParams {
+    /** The typed data the wallet signed, as returned to the client. */
+    typedData: TypedData;
+    /** The wallet's `wallet_signTypedData` result (hex or decimal felts). */
+    signature: Array<string | number | bigint>;
+    /** Mainnet RPC (starknet.js `RpcProvider` or anything with `callContract`). */
+    provider: StarknetCallProvider;
+    /** What this server issued. Anything else is refused. */
+    expected: {
+        domain: string;
+        uri: string;
+        nonce: string;
+        now?: number;
+    };
+    /**
+     * The wallet's `wallet_deploymentData`, for accounts not deployed yet
+     * (new Bramble/Ready accounts). Only used when the RPC says the account
+     * does not exist.
+     */
+    deploymentData?: StarknetDeploymentData;
+}
+type StarknetSignInFailure = "MALFORMED" | "WRONG_CHAIN" | "WRONG_DOMAIN" | "WRONG_URI" | "WRONG_NONCE" | "EXPIRED" | "NOT_YET_VALID" | "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED" | "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH";
+type VerifyStarknetSignInResult = {
+    ok: true;
+    address: string;
+    message: StarknetSignInMessage;
+} | {
+    ok: false;
+    reason: StarknetSignInFailure;
+};
+/**
+ * Verifies a SIWS signature. The typed data is rebuilt from its message with
+ * `createStarknetSignInTypedData`, so a client can't swap in other types or a
+ * testnet domain; then the account is asked with `is_valid_signature`, or, if
+ * it isn't deployed yet and `deploymentData` is given, checked off-chain.
+ *
+ * The caller still owns the nonce: issue it once, and consume it before or
+ * right after calling this (never accept the same nonce twice).
+ */
+declare function verifyStarknetSignIn(params: VerifyStarknetSignInParams): Promise<VerifyStarknetSignInResult>;
+
 /**
  * SNIP-12 typed-data hash for `OutsideExecution` — TypeScript reference.
  *
@@ -3045,4 +3198,4 @@ declare class ShhhAccount {
  */
 declare function submitViaAccount(funded: Account): ShhhSubmit;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, VIEW_SELECTORS, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isThinkDecision, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, validateSpendingPolicyConfig, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, COUNTERFACTUAL_ACCOUNT_CLASSES, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, SIWS_CHAIN_ID, SIWS_DOMAIN_NAME, SIWS_DOMAIN_VERSION, STARKNET_MESSAGE_PREFIX, STARKNET_SIGNATURE_VALID, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, type StarknetCallProvider, type StarknetDeploymentData, type StarknetSignInFailure, type StarknetSignInMessage, type StarknetSignInParams, type StarknetSignatureCheck, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, type UndeployedSignatureCheck, VIEW_SELECTORS, type VerifyStarknetSignInParams, type VerifyStarknetSignInResult, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, createStarknetSignInTypedData, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isThinkDecision, isValidStarknetSignature, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, normalizeStarknetAddress, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, validateSpendingPolicyConfig, verifyStarknetSignIn, verifyUndeployedStarknetSignature, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
 import { C as ChipiClient } from './client-D6SDBu5p.js';
-import { Call, ProviderInterface, Account } from 'starknet';
+import { Call, TypedData, ProviderInterface, Account } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -649,9 +649,13 @@ declare class ChipiAi {
      * session key: a USDC `transfer` to the offer's `payTo`, then the same call
      * again with `X-PAYMENT`. The price must be at most `maxAmount`, `model`
      * must be payable and the input within `maxPromptBytes`, all checked before
-     * paying. The session must whitelist `transfer` and cap USDC. A payment
-     * that was made but not served is reported in `error.details.xPayment`;
-     * pass it back as `options.xPayment` to retry without paying again.
+     * paying. The wallet must be a wallet of the organization that owns the
+     * `sk_`: the first request names it in `X-PAYER`, and when the API answers
+     * that a payment from it would be refused, nothing is paid
+     * (`X402_PAYER_NOT_IN_ORG`). The session must whitelist `transfer` and cap
+     * USDC. A payment that was made but not served is reported in
+     * `error.details.xPayment`; pass it back as `options.xPayment` to retry
+     * without paying again.
      *
      * @example
      * ```typescript
@@ -751,11 +755,18 @@ declare class X402Facilitator {
      * Verify a payment signature is valid (doesn't execute the transfer).
      *
      * Checks:
-     * 1. Nonce has not been used (replay protection)
-     * 2. Payment has not expired (validUntil > now)
-     * 3. Asset is USDC mainnet
-     * 4. Amount is positive
-     * 5. Addresses are non-empty
+     * 1. x402 version is 1
+     * 2. Network is starknet-mainnet
+     * 3. Nonce has not been used (replay protection)
+     * 4. Payment has not expired (validUntil > now)
+     * 5. Asset is USDC mainnet
+     * 6. Amount is positive
+     * 7. Addresses are non-empty
+     * 8. Signature: with a `provider`, the payer account's `is_valid_signature`
+     *    must return 'VALID'. Without one, only its presence is checked (not a
+     *    cryptographic check). SHHH payloads must sign exactly one transfer
+     *    of `amount` of `asset` to `toAddress`; their signature is checked
+     *    on-chain at settle.
      */
     verify(payment: PaymentPayload): Promise<VerifyResponse>;
     /**
@@ -1468,6 +1479,148 @@ declare class SessionTxVerifier {
     verifyTransfer(params: VerifyTransferParams): Promise<VerifyTransferResult>;
 }
 
+/** SRC-6 `is_valid_signature` magic value: the short string 'VALID'. */
+declare const STARKNET_SIGNATURE_VALID = "0x56414c4944";
+/** Anything with a starknet.js-style `callContract` (e.g. `RpcProvider`). */
+interface StarknetCallProvider {
+    callContract(call: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata?: string[];
+    }): Promise<string[]>;
+}
+type StarknetSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED";
+    detail?: string;
+};
+/** `0x` + 64 hex, lowercase. Wallets differ on padding; compare on this. */
+declare function normalizeStarknetAddress(address: string): string;
+/**
+ * Asks the account itself (SRC-6 `is_valid_signature`) whether `signature`
+ * signs `messageHash`. The full signature array is passed through, so
+ * multi-felt signatures (Argent, Braavos, multisig) work.
+ *
+ * Only 'VALID' counts: accounts return 0 or panic on a bad signature, and a
+ * lax "anything non-zero" check would accept garbage. An account that is not
+ * deployed yet comes back as ACCOUNT_NOT_DEPLOYED so the caller can fall back
+ * to `verifyUndeployedStarknetSignature`.
+ */
+declare function isValidStarknetSignature(provider: StarknetCallProvider, accountAddress: string, messageHash: string, signature: Array<string | number | bigint>): Promise<StarknetSignatureCheck>;
+/** Account classes whose undeployed signatures we can check off-chain. */
+declare const COUNTERFACTUAL_ACCOUNT_CLASSES: {
+    /** OpenZeppelin AccountUpgradeable 3.0 (Bramble's default account). */
+    readonly OPENZEPPELIN_V3: "0x01d1777db36cdd06dd62cfde77b1b6ae06412af95d57a13dc40ac77b8a702381";
+    /** Argent X / Ready 0.4 (`WALLET_CLASS_HASHES.READY`). */
+    readonly ARGENT_V0_4: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f";
+};
+/** What a wallet returns from `wallet_deploymentData`. */
+interface StarknetDeploymentData {
+    address: string;
+    class_hash: string;
+    salt: string;
+    calldata: string[];
+}
+type UndeployedSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH" | "INVALID_SIGNATURE";
+};
+/**
+ * Checks a signature from an account that is not deployed yet (new Bramble
+ * and Ready accounts stay counterfactual until their first transaction), using
+ * the wallet's `wallet_deploymentData`:
+ *
+ * 1. The class must be one we know how to read: OpenZeppelin 3.0 or Argent 0.4
+ *    without a guardian.
+ * 2. The address must be the one those exact constructor arguments deploy to.
+ * 3. The signature must be the owner key's ECDSA signature of the hash.
+ */
+declare function verifyUndeployedStarknetSignature(deployment: StarknetDeploymentData, messageHash: string, signature: Array<string | number | bigint>): UndeployedSignatureCheck;
+
+/**
+ * Sign in with Starknet (SIWS): the SNIP-12 equivalent of Sign-In with
+ * Ethereum. The server issues a one-time nonce, the wallet signs this typed
+ * data, and the server checks the signature with the account itself.
+ *
+ * The typed data is kept to what every wallet accepts: SNIP-12 revision 1,
+ * mainnet chain id in the domain, single-line printable ASCII strings (Bramble
+ * refuses anything else), and no custom `u256`.
+ */
+declare const SIWS_DOMAIN_NAME = "Sign in with Starknet";
+declare const SIWS_DOMAIN_VERSION = "1";
+declare const SIWS_CHAIN_ID = "SN_MAIN";
+interface StarknetSignInParams {
+    /** Host asking for the sign-in, e.g. "vela-starknet.vercel.app". */
+    domain: string;
+    /** Full URL of the app, e.g. "https://vela-starknet.vercel.app". */
+    uri: string;
+    /** Account that signs. Any padding; stored as 0x + 64 hex. */
+    address: string;
+    /** One-time server nonce (letters and digits). */
+    nonce: string;
+    /** Shown to the user in the wallet. */
+    statement?: string;
+    /** Unix seconds. Defaults to now. */
+    issuedAt?: number;
+    /** Unix seconds. */
+    expirationTime: number;
+}
+interface StarknetSignInMessage {
+    domain: string;
+    address: string;
+    statement: string;
+    uri: string;
+    nonce: string;
+    issuedAt: number;
+    expirationTime: number;
+}
+/** Typed data for the wallet's `wallet_signTypedData`. */
+declare function createStarknetSignInTypedData(params: StarknetSignInParams): TypedData;
+interface VerifyStarknetSignInParams {
+    /** The typed data the wallet signed, as returned to the client. */
+    typedData: TypedData;
+    /** The wallet's `wallet_signTypedData` result (hex or decimal felts). */
+    signature: Array<string | number | bigint>;
+    /** Mainnet RPC (starknet.js `RpcProvider` or anything with `callContract`). */
+    provider: StarknetCallProvider;
+    /** What this server issued. Anything else is refused. */
+    expected: {
+        domain: string;
+        uri: string;
+        nonce: string;
+        now?: number;
+    };
+    /**
+     * The wallet's `wallet_deploymentData`, for accounts not deployed yet
+     * (new Bramble/Ready accounts). Only used when the RPC says the account
+     * does not exist.
+     */
+    deploymentData?: StarknetDeploymentData;
+}
+type StarknetSignInFailure = "MALFORMED" | "WRONG_CHAIN" | "WRONG_DOMAIN" | "WRONG_URI" | "WRONG_NONCE" | "EXPIRED" | "NOT_YET_VALID" | "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED" | "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH";
+type VerifyStarknetSignInResult = {
+    ok: true;
+    address: string;
+    message: StarknetSignInMessage;
+} | {
+    ok: false;
+    reason: StarknetSignInFailure;
+};
+/**
+ * Verifies a SIWS signature. The typed data is rebuilt from its message with
+ * `createStarknetSignInTypedData`, so a client can't swap in other types or a
+ * testnet domain; then the account is asked with `is_valid_signature`, or, if
+ * it isn't deployed yet and `deploymentData` is given, checked off-chain.
+ *
+ * The caller still owns the nonce: issue it once, and consume it before or
+ * right after calling this (never accept the same nonce twice).
+ */
+declare function verifyStarknetSignIn(params: VerifyStarknetSignInParams): Promise<VerifyStarknetSignInResult>;
+
 /**
  * SNIP-12 typed-data hash for `OutsideExecution` — TypeScript reference.
  *
@@ -3045,4 +3198,4 @@ declare class ShhhAccount {
  */
 declare function submitViaAccount(funded: Account): ShhhSubmit;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, VIEW_SELECTORS, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isThinkDecision, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, validateSpendingPolicyConfig, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, COUNTERFACTUAL_ACCOUNT_CLASSES, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, SIWS_CHAIN_ID, SIWS_DOMAIN_NAME, SIWS_DOMAIN_VERSION, STARKNET_MESSAGE_PREFIX, STARKNET_SIGNATURE_VALID, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, type StarknetCallProvider, type StarknetDeploymentData, type StarknetSignInFailure, type StarknetSignInMessage, type StarknetSignInParams, type StarknetSignatureCheck, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, type UndeployedSignatureCheck, VIEW_SELECTORS, type VerifyStarknetSignInParams, type VerifyStarknetSignInResult, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, createStarknetSignInTypedData, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isThinkDecision, isValidStarknetSignature, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, normalizeStarknetAddress, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, validateSpendingPolicyConfig, verifyStarknetSignIn, verifyUndeployedStarknetSignature, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };