@x1id/resolve 0.19.2 → 0.22.0

package/dist/siws.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Sign In With Solana (SIWS, the Wallet Standard `solana:signIn` feature)
+ * against the hosted X1ID Connect API (`POST /v1/auth/challenge` +
+ * `POST /v1/auth/verify-signin`).
+ *
+ * # Why SIWS
+ *
+ * `solana:signIn` lets the WALLET build and display a structured sign-in
+ * message (domain, address, statement, nonce, ...) instead of an opaque blob.
+ * It is also the most reliable wallet-control proof on X1 in practice:
+ * Backpack's injected script hijacks OTHER wallets' `signMessage` but not
+ * `signIn`. This is the same path developers.x1id.io uses
+ * (portal/src/lib/wallet/standardWallet.ts) — the input fields here mirror it.
+ *
+ * # Flow
+ *
+ *   1. `requestSignInChallenge` — `POST /v1/auth/challenge {wallet, mode:"signin"}`
+ *      returns a single-use `nonce` bound to your API key and the wallet.
+ *   2. `buildSignInInput` — the `solana:signIn` input naming YOUR domain, the
+ *      wallet address and that nonce.
+ *   3. the wallet signs the SIWS message it renders from that input.
+ *   4. `verifySolanaSignIn` — `POST /v1/auth/verify-signin` with the exact
+ *      signed bytes (base64) and the 64-byte signature (base58). dev-api checks
+ *      line 1 (`<domain> wants you to sign in with your Solana account:`, domain
+ *      on its allowlist), line 2 (the challenged wallet), a `Nonce: <nonce>`
+ *      line, and the ed25519 signature (raw bytes or the SIMD-0048 v0
+ *      off-chain envelope). It returns a Bearer {@link ConnectSession}.
+ *
+ * `signInWithSolana` does all four. Framework-agnostic: it takes any Wallet
+ * Standard wallet object, with no wallet-adapter or web3.js dependency.
+ *
+ * # Fallbacks: `signInWithWallet`
+ *
+ * Not every wallet implements `solana:signIn`, and some implement it badly.
+ * `signInWithWallet` tries, in the same order as developers.x1id.io
+ * (portal/src/lib/wallet/standardWallet.ts `proveForPortalSession`):
+ *
+ *   1. SIWS (`solana:signIn` → `/v1/auth/verify-signin`);
+ *   2. a signed, NEVER-SENT memo transaction (`solana:signTransaction` →
+ *      `/v1/auth/verify-tx`) whose only instruction is an SPL-Memo carrying the
+ *      server's audience-bound `x1id-verify:<audience>:<nonce>` verbatim. With
+ *      `signinFeePayer` set it uses dev-api's no-fee layout (display-only fee
+ *      payer at signer index 0, the user at index 1); otherwise the user is the
+ *      fee payer. Works for Ledger, which refuses message signing;
+ *   3. `solana:signMessage` over the server's v2 challenge string
+ *      (`x1id-connect:v2:wallet-control:<audience>:<address>:<nonce>`) →
+ *      `/v1/auth/verify`.
+ *
+ * A user rejection or a wallet timeout stops the chain (the user said no; a
+ * second prompt would be hostile). Any other failure moves to the next path.
+ * Challenge strings and memos are always signed exactly as the server issued
+ * them, never rebuilt here (R3-L2P-1 audience binding).
+ *
+ * The session proves WALLET CONTROL (source `"wallet"`); the wallet's primary
+ * `@handle`, if any, is reported as metadata and re-resolved on every
+ * `GET /v1/auth/session`.
+ *
+ * Not to be confused with {@link import("./signin.js").signInWithX1ID}: that is
+ * the server-less, relying-party-verified `@handle` proof. This module talks to
+ * the hosted API and gets a session back.
+ */
+import { type ConnectSession } from "./connect.js";
+/**
+ * - `wallet-unsupported` — the wallet does not implement `solana:signIn` (or,
+ *   for `signInWithWallet`, none of signIn / signTransaction / signMessage).
+ * - `user-rejected` — the user declined in the wallet.
+ * - `domain-not-allowed` — dev-api rejected the domain named in the message
+ *   (it is not on the deployment's SIWS allowlist).
+ * - `nonce-expired` — the challenge expired, was already used, or is unknown;
+ *   request a fresh one and retry.
+ * - `invalid-params` — bad input (missing apiKey/domain, injection in a field).
+ * - `wallet-timeout` — the wallet never answered.
+ * - `wallet-error` — the wallet failed or returned an unusable result.
+ * - `network` — the request did not complete (no fetch, timeout, non-JSON).
+ * - `api-error` — any other dev-api error; see `serverCode` / `status`.
+ */
+export type SiwsErrorCode = "wallet-unsupported" | "user-rejected" | "domain-not-allowed" | "nonce-expired" | "invalid-params" | "wallet-timeout" | "wallet-error" | "network" | "api-error";
+export declare class SiwsError extends Error {
+    readonly code: SiwsErrorCode;
+    /** dev-api's own error code (e.g. `CHALLENGE_EXPIRED`), when it sent one. */
+    readonly serverCode?: string | undefined;
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number | undefined;
+    constructor(code: SiwsErrorCode, message: string, 
+    /** dev-api's own error code (e.g. `CHALLENGE_EXPIRED`), when it sent one. */
+    serverCode?: string | undefined, 
+    /** HTTP status, when the error came from a response. */
+    status?: number | undefined);
+}
+/** Map a dev-api error response onto a {@link SiwsErrorCode}. */
+export declare function siwsErrorCodeFor(serverCode: string | undefined, message: string | undefined): SiwsErrorCode;
+/** `solana:signIn` input (Phantom's SIWS spec / @solana/wallet-standard-features). */
+export interface SolanaSignInInput {
+    readonly domain?: string;
+    readonly address?: string;
+    readonly statement?: string;
+    readonly uri?: string;
+    readonly version?: string;
+    readonly chainId?: string;
+    readonly nonce?: string;
+    readonly issuedAt?: string;
+    readonly expirationTime?: string;
+    readonly notBefore?: string;
+    readonly requestId?: string;
+    readonly resources?: readonly string[];
+}
+export interface WalletStandardAccount {
+    readonly address: string;
+    readonly publicKey?: Uint8Array;
+}
+export interface SolanaSignInOutput {
+    readonly account: WalletStandardAccount;
+    readonly signedMessage: Uint8Array;
+    readonly signature: Uint8Array;
+    readonly signatureType?: string;
+}
+/** The slice of a Wallet Standard wallet this module uses. */
+export interface SignInCapableWallet {
+    readonly name?: string;
+    readonly accounts?: readonly WalletStandardAccount[];
+    readonly features: Record<string, unknown>;
+}
+/** True if `wallet` implements `solana:signIn`. */
+export declare function walletSupportsSignIn(wallet: SignInCapableWallet | null | undefined): boolean;
+/** The SIWS message line-1 suffix dev-api's verifier matches on. */
+export declare const SIWS_HEADER_SUFFIX: " wants you to sign in with your Solana account:";
+/** Default statement shown in the wallet. */
+export declare const DEFAULT_SIWS_STATEMENT: "Sign in with your wallet. This does not send a transaction.";
+export interface BuildSignInInputParams {
+    /** The host the user is signing in to (e.g. `app.example.com`). Must be on
+     *  your deployment's SIWS allowlist. Defaults to `globalThis.location.host`. */
+    readonly domain?: string;
+    /** The wallet address (base58) the challenge was issued for. */
+    readonly address: string;
+    /** The challenge nonce from {@link requestSignInChallenge}. */
+    readonly nonce: string;
+    /** Human-readable statement the wallet displays. Defaults to
+     *  {@link DEFAULT_SIWS_STATEMENT}; pass `""` to omit it. */
+    readonly statement?: string;
+    /** Defaults to `globalThis.location.origin`, else `https://<domain>`. */
+    readonly uri?: string;
+    /** ISO-8601; defaults to now. */
+    readonly issuedAt?: string;
+}
+/**
+ * Build the Wallet Standard `solana:signIn` input for an X1ID challenge —
+ * exactly the fields developers.x1id.io sends: domain, address, statement, uri,
+ * version `"1"`, nonce, issuedAt.
+ */
+export declare function buildSignInInput(params: BuildSignInInputParams): SolanaSignInInput;
+/**
+ * Render a `solana:signIn` input as SIWS message text, per the SIWS spec
+ * (identical to `createSignInMessageText` in @solana/wallet-standard-util).
+ * Wallets render this themselves; it is exported for tests, previews, and
+ * server-side expectations.
+ */
+export declare function buildSignInMessageText(input: SolanaSignInInput & {
+    domain: string;
+    address: string;
+}): string;
+export interface SiwsApiConfig {
+    /** Your X1ID integrator API key (sent as `x-api-key`). */
+    readonly apiKey: string;
+    /** API origin. Defaults to `https://api.x1id.io`; a trailing `/v1` is tolerated. */
+    readonly apiBase?: string;
+    /** Inject a `fetch` (tests, non-global-fetch runtimes). */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms (default 15_000). */
+    readonly timeoutMs?: number;
+}
+/** `POST /v1/auth/challenge` response for a `mode: "signin"` wallet challenge. */
+export interface SignInChallengeResponse {
+    readonly nonce: string;
+    readonly handle: string | null;
+    /** The exact string to sign for the signMessage path
+     *  (`x1id-connect:v2:wallet-control:<audience>:<address>:<nonce>`). */
+    readonly challenge: string;
+    /** The audience the signed bytes name (R3-L2P-1): your API key id, or the
+     *  portal's domain for the portal key. Absent from a pre-#608 API. */
+    readonly audience?: string;
+    /** Tx mode only: the exact memo (`x1id-verify:<audience>:<nonce>`). */
+    readonly memo?: string;
+    readonly signature_encoding: string;
+    readonly expires_at: number;
+    readonly proves: string;
+    readonly disclaimer: string;
+}
+/** Body of `POST /v1/auth/verify-signin`. */
+export interface VerifySignInBody {
+    readonly nonce: string;
+    /** base64 of the EXACT bytes the wallet signed. */
+    readonly signedMessage: string;
+    /** base58 of the 64-byte ed25519 signature. */
+    readonly signature: string;
+}
+/** `POST /v1/auth/challenge {wallet, mode: "signin"}` — a single-use nonce. */
+export declare function requestSignInChallenge(params: SiwsApiConfig & {
+    readonly wallet: string;
+}): Promise<SignInChallengeResponse>;
+/**
+ * `POST /v1/auth/challenge {wallet, mode?}` for any wallet-proof mode:
+ * `"signin"` (SIWS), `"tx"` (memo transaction; the response carries `memo`),
+ * or omitted (signMessage over `challenge`).
+ */
+export declare function requestConnectChallenge(params: SiwsApiConfig & {
+    readonly wallet: string;
+    readonly mode?: "signin" | "tx";
+}): Promise<SignInChallengeResponse>;
+/**
+ * `POST /v1/auth/verify-signin` — the raw verify call. Accepts the wallet's
+ * byte outputs and encodes them as dev-api expects (signedMessage base64,
+ * signature base58), or pre-encoded strings passed through as-is.
+ */
+export declare function verifySolanaSignIn(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signedMessage: Uint8Array | string;
+    readonly signature: Uint8Array | string;
+}): Promise<ConnectSession>;
+/** `POST /v1/auth/verify-tx` with the fully signed memo transaction (base64). */
+export declare function verifySignInTransaction(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signedTransaction: Uint8Array | string;
+}): Promise<ConnectSession>;
+/** `POST /v1/auth/verify` with a signMessage signature over the challenge
+ *  string (signature base58, `signer` = the wallet address). */
+export declare function verifySignInMessage(params: SiwsApiConfig & {
+    readonly nonce: string;
+    readonly signature: Uint8Array | string;
+    readonly signer: string;
+}): Promise<ConnectSession>;
+/** X1ID's display-only sign-in fee payer on X1 MAINNET (System-owned, tiny
+ *  balance so wallet simulations pass; it never signs and the tx is never
+ *  sent). Pass it as `signinFeePayer` only against a deployment whose
+ *  `CONNECT_SIGNIN_FEE_PAYER` is this address (api.x1id.io on mainnet). */
+export declare const X1ID_MAINNET_SIGNIN_FEE_PAYER: "9kFEzXbNBJLTsvZwrTAcpxr6iLRqHPyu9yp8K4m2YwC3";
+export interface BuildSignInMemoTransactionParams {
+    /** The signing wallet (base58). */
+    readonly user: string;
+    /** The memo, verbatim from the challenge (`x1id-verify:<audience>:<nonce>`). */
+    readonly memo: string;
+    /** A recent blockhash; defaults to the all-ones placeholder (never sent). */
+    readonly blockhash?: string;
+    /** Display-only fee payer for dev-api's no-fee layout (user = signer index 1).
+     *  Null/omitted = the user pays and signs alone (always accepted). */
+    readonly feePayer?: string | null;
+}
+/**
+ * The unsigned, serialized LEGACY memo-only transaction the wallet signs for
+ * `/v1/auth/verify-tx`: exactly one SPL-Memo instruction carrying `memo`, with
+ * the user as the memo's signer. Byte-identical to the portal's
+ * `buildMemoTx` (portal/src/lib/wallet/memoTx.ts). It is never broadcast.
+ */
+export declare function buildSignInMemoTransaction(params: BuildSignInMemoTransactionParams): Uint8Array;
+export interface SignInWithSolanaParams extends SiwsApiConfig {
+    /** A Wallet Standard wallet implementing `solana:signIn`. */
+    readonly wallet: SignInCapableWallet;
+    /** The account to sign in with. Defaults to the wallet's first account
+     *  (connecting via `standard:connect` first if it has none). */
+    readonly account?: WalletStandardAccount;
+    /** Defaults to `globalThis.location.host`. */
+    readonly domain?: string;
+    readonly statement?: string;
+    readonly uri?: string;
+    /** How long to wait for the wallet, ms (default 60_000). */
+    readonly signTimeoutMs?: number;
+}
+/**
+ * Sign in with a Wallet Standard wallet via `solana:signIn` ONLY and return the
+ * X1ID Connect session. Throws {@link SiwsError} (`wallet-unsupported` when the
+ * wallet lacks `solana:signIn`). For automatic fallbacks use
+ * {@link signInWithWallet}.
+ *
+ * ```ts
+ * const session = await signInWithSolana({ wallet, apiKey: "x1id_..." });
+ * // session.token → `Authorization: Bearer …`; session.address; session.handle
+ * ```
+ */
+export declare function signInWithSolana(params: SignInWithSolanaParams): Promise<ConnectSession>;
+export type SignInMethod = "siws" | "memo-tx" | "sign-message";
+export interface SignInWithWalletParams extends SignInWithSolanaParams {
+    /** Paths to try, in order. Default: all three, SIWS → memo tx → signMessage
+     *  (the developers.x1id.io order). */
+    readonly methods?: readonly SignInMethod[];
+    /** Memo path: display-only fee payer for dev-api's no-fee layout. Must equal
+     *  the deployment's CONNECT_SIGNIN_FEE_PAYER (on api.x1id.io mainnet:
+     *  {@link X1ID_MAINNET_SIGNIN_FEE_PAYER}). Default null: the user is the fee
+     *  payer (accepted by every deployment; the tx is never sent either way). */
+    readonly signinFeePayer?: string | null;
+    /** Memo path: an RPC to fetch a recent blockhash from (wallets simulate the
+     *  transaction before signing, and some refuse a stale one). */
+    readonly rpcUrl?: string;
+    /** Memo path: a blockhash to use as-is (overrides `rpcUrl`). Default: the
+     *  all-ones placeholder. */
+    readonly blockhash?: string;
+    /** Called before each path is tried (for UI copy / telemetry). */
+    readonly onAttempt?: (method: SignInMethod) => void;
+}
+/** A session plus the path that produced it. */
+export type WalletSignInResult = ConnectSession & {
+    readonly method: SignInMethod;
+};
+/**
+ * Sign in with any Wallet Standard wallet, falling back across the three
+ * wallet-control proofs the hosted API accepts: SIWS → never-sent memo
+ * transaction → signMessage (see the module docs). A user rejection or a
+ * wallet timeout stops immediately; otherwise the LAST path's error is thrown
+ * if every path fails. `wallet-unsupported` when the wallet implements none of
+ * `solana:signIn`, `solana:signTransaction`, `solana:signMessage`.
+ */
+export declare function signInWithWallet(params: SignInWithWalletParams): Promise<WalletSignInResult>;