@dexterai/connect 0.24.1 → 0.24.2

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import { S as SignInResult, C as CreateWalletResult, a as CreateWalletConfig, b as CeremonyPhase, D as DexterConnectConfig, c as ConnectVault, R as RecoverWalletConfig, d as RecoverOutcome, I as IdentityKind } from './signals-C05rIVey.js';
+export { A as ACTIVE_WALLET_STORAGE_KEY, e as ConnectError, f as IdentityInput, P as PasskeyLoginTokens, g as PasskeySignalSupport, h as RecoverVault, i as ResolvedIdentity, j as SESSION_TTL_30D, k as SpendPolicy, l as StoredWallet, m as authoredPolicy, n as createWallet, o as ejectActiveWallet, p as forgetWallet, q as getActiveHandle, r as getCredentialId, s as listWallets, t as passkeySignalSupport, u as prunePasskey, v as renamePasskey, w as resolveIdentity, x as setActiveHandle, y as subscribeWallet, z as switchWallet, B as syncAcceptedPasskeys, E as usdToAtomic } from './signals-C05rIVey.js';
+import { DexterApiBrowserPasskeySigner } from '@dexterai/vault/signers/browser';
+
+/**
+ * "Sign in with Dexter" — the discoverable-credential login ceremony.
+ *
+ *   1. POST /login-challenge  → a server-issued challenge (no allow-list:
+ *      the resident passkey itself identifies the user)
+ *   2. navigator.credentials.get over that challenge (no allowCredentials)
+ *   3. POST /passkey-login    → the server resolves the credential + vault,
+ *      verifies the assertion, and returns a Supabase session (+ the vault
+ *      payload once vault-review ships the dexter-api change — ASK 1)
+ *
+ * Relays to dexter-api's ANON router — a first-time third-party user has no
+ * Supabase session, so the Supabase-gated router would 401.
+ */
+declare function passkeyLogin(config?: DexterConnectConfig, onPhase?: (phase: CeremonyPhase) => void): Promise<SignInResult>;
+type ContinueResult = ({
+    kind: 'signin';
+} & SignInResult) | ({
+    kind: 'create';
+} & CreateWalletResult);
+declare function continueWithDexter(config?: CreateWalletConfig, onPhase?: (phase: CeremonyPhase) => void): Promise<ContinueResult>;
+
+/** What `issueChallenge` returns to the SDK signer. */
+interface AnonChallengeResult {
+    /** Server-issued WebAuthn challenge (=== the supplied operationHash). */
+    challenge: Uint8Array;
+    /** Credential id the server resolved from the userHandle (allowCredentials[0]). */
+    credentialId: Uint8Array;
+    rpId?: string;
+    transports?: AuthenticatorTransport[];
+}
+/** The policy the SDK's guest `DexterApiBrowserPasskeySigner` consumes. */
+interface AnonServerPolicy {
+    issueChallenge(args: {
+        userHandle: Uint8Array;
+        operationHash: Uint8Array;
+    }): Promise<AnonChallengeResult>;
+    verify(args: {
+        userHandle: Uint8Array;
+        credentialId: Uint8Array;
+        signature: Uint8Array;
+        clientDataJSON: Uint8Array;
+        authenticatorData: Uint8Array;
+    }): Promise<void>;
+}
+/**
+ * Build the anon ServerPolicy for a given dexter-api base.
+ *
+ * `issueChallenge` → POST /challenge { userHandle, operationHash } (both base64url).
+ *   The server uses operationHash AS the WebAuthn challenge (replay binding +
+ *   the on-chain webauthn.rs law: clientDataJSON.challenge === sha256(op)) and
+ *   resolves the credential into options.allowCredentials[0].
+ * `verify` → POST /verify { credential, userHandle }. NOTE: the SDK hands us the
+ *   COMPACT 64-byte signature; dexter-api's WebAuthn verifier wants DER, so we
+ *   re-encode compact → DER here (compactSignatureToDer).
+ */
+declare function createAnonServerPolicy(apiBase?: string): AnonServerPolicy;
+
+/** Test seam mirroring the SDK's injected-assertion shape (production omits it). */
+type AssertionLike = {
+    credentialId: Uint8Array;
+    assertOver(challenge: Uint8Array): Promise<{
+        signature: Uint8Array;
+        clientDataJSON: Uint8Array;
+        authenticatorData: Uint8Array;
+    }>;
+};
+/**
+ * Construct the guest signer from a connected `ConnectVault`.
+ *
+ * `vault.publicKey` is base64 (33-byte SEC1 compressed P-256); `vault.userHandle`
+ * is base64url (server-minted). Both are decoded to the Uint8Arrays the SDK wants.
+ *
+ * @param vault    the connected vault from useSignInWithDexter()
+ * @param apiBase  dexter-api base (defaults to https://api.dexter.cash via the policy)
+ * @param opts.__assertion  test-only injected assertion (skips real WebAuthn)
+ */
+declare function createPasskeySigner(vault: ConnectVault, apiBase?: string, opts?: {
+    __assertion?: AssertionLike;
+}): DexterApiBrowserPasskeySigner;
+
+declare function recoverWallet(config?: RecoverWalletConfig): Promise<RecoverOutcome>;
+
+/**
+ * Human-readable label for a ceremony phase — the live "connecting step" copy.
+ * ONE source of truth so sign-in (SignInWithDexter) and create (consumer setup
+ * flows) show identical wording. Consumers surfacing createWallet's `onPhase`
+ * should use this instead of hand-rolling their own strings (Rule #7).
+ */
+declare function ceremonyPhaseLabel(phase: CeremonyPhase): string;
+
+/** The automatic role-2 agent-spend rail. */
+interface AutomaticAgentSpend {
+    /** true = agent-spend is ON (not revoked). Derived from revokedAt === null. */
+    active: boolean;
+    /** ISO timestamp the rail was revoked, or null when active. */
+    revokedAt: string | null;
+    /**
+     * On-chain role-2 arm state, decoded from authority.signer by the backend:
+     *   true  = armed (the rail is live and can spend)
+     *   false = dormant (granted but not yet armed — arms on first pay)
+     *   null  = indeterminate (vault not activated, or a transient chain read failed)
+     * NEVER derived from liveSessionCount (that counts the wrong session model).
+     */
+    armed: boolean | null;
+    spentTodayAtomic?: string;
+    dailyCapAtomic?: string;
+    perCallCapAtomic?: string;
+    lifetimeSpentAtomic?: string;
+}
+/** One explicit user-opened Tab (a V6 per-counterparty session). */
+interface AgentSpendTab {
+    /** The session pubkey — the handle a Tab revoke targets. */
+    id: string;
+    /** The counterparty (agent/app) address this Tab authorizes. */
+    counterparty: string;
+    /** Display label: the Dexter-verified app name, else a shortened address. */
+    label: string;
+    /** Whether the Tab is currently live (not expired/spent-out/revoked). */
+    live: boolean;
+    /** Spent so far against this Tab's cap, atomic USDC (6dp) string. */
+    spentAtomic: string;
+    /** This Tab's spending cap, atomic USDC (6dp) string. */
+    capAtomic: string;
+    /** Unix seconds when the Tab expires. */
+    expiresAt: number;
+}
+/** The honest two-mode status: one balance, two separately-accounted rails. */
+interface AgentSpendStatus {
+    /** Vault USDC balance, atomic (6dp) string — the ONE pool both rails draw. */
+    balanceAtomic: string | null;
+    /** The automatic role-2 rail. */
+    automatic: AutomaticAgentSpend;
+    /** The explicit Tabs. */
+    tabs: AgentSpendTab[];
+}
+/** The fields of GET /status the two-mode read consumes. */
+interface RawAgentSpendStatus {
+    /** ISO timestamp when revoked, null when active. Top-level on /status. */
+    agentSpendRevokedAt?: string | null;
+    /** On-chain armed read (authority.signer). true/false/null. Top-level on /status. */
+    agentSpendArmed?: boolean | null;
+    /** On-chain block; usdcAtomic is the vault balance. */
+    onchain?: {
+        usdcAtomic?: string | null;
+        /** Present but DELIBERATELY UNUSED here — counts the wrong session model. */
+        liveSessionCount?: number;
+    } | null;
+    agentSpendDaily?: {
+        spentTodayAtomic?: string;
+        dailyCapAtomic?: string;
+        perCallCapAtomic?: string;
+        lifetimeSpentAtomic?: string;
+    } | null;
+}
+/** The fields of one GET /sessions row the Tabs rail consumes. */
+interface RawAgentSpendSession {
+    sessionPubkey: string;
+    counterparty: string;
+    appName?: string | null;
+    live: boolean;
+    spent: string;
+    maxAmount: string;
+    expiresAt: number;
+}
+/**
+ * Assemble the honest two-mode agent-spend status from the raw /status response
+ * and the raw /sessions rows. Pure: no fetch, no clock, no I/O.
+ */
+declare function assembleAgentSpendStatus(status: RawAgentSpendStatus, sessions?: RawAgentSpendSession[]): AgentSpendStatus;
+/**
+ * The minimal identity the off/on switch needs: WHO is active + the wallet
+ * handle the anon router keys on. Structurally satisfied by connect's
+ * ResolvedIdentity (pass it straight through), or hand-build `{ kind, userHandle }`.
+ */
+interface AgentSpendIdentity {
+    /** Passkey-vault-first identity axis. Agent-spend is Dexter-Wallet-only. */
+    kind: IdentityKind;
+    /** The passkey-vault user handle the anon router addresses, or null. */
+    userHandle: string | null;
+}
+/** Typed error whose `code` is the server's snake_case error string. */
+declare class AgentSpendError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/** Map an AgentSpendError.code to plain, user-facing copy. */
+declare function describeAgentSpendError(code: string): string;
+interface RevokeAgentSpendResult {
+    revoked: boolean;
+}
+/**
+ * Revoke the AUTOMATIC role-2 agent-spend rail — the off-switch. Takes effect on
+ * the very next agent payment (the spend path reads agent_spend_revoked_at fresh
+ * per spend). Dexter-Wallet (anon-vault) only; `credentialId` (base64url) targets
+ * the biometric prompt.
+ *
+ * @param id            WHO is active — must be the passkey-vault (Dexter Wallet).
+ * @param vaultPda      The vault PDA, base58 string. Becomes the signed message.
+ * @param apiOrigin     The dexter-api origin (e.g. https://api.dexter.cash). The
+ *                      caller owns env; connect reads none.
+ * @param credentialId  The wallet's passkey credential id (base64url), to make
+ *                      the assertion a direct biometric, not an account picker.
+ */
+declare function revokeAgentSpend(id: AgentSpendIdentity, vaultPda: string, apiOrigin: string, credentialId?: string | null): Promise<RevokeAgentSpendResult>;
+interface EnableAgentSpendResult {
+    enabled: boolean;
+}
+/**
+ * Re-enable the AUTOMATIC role-2 agent-spend rail — the ON switch. Turning spend
+ * back ON is the dangerous direction, so it is a two-step, replay-protected nonce
+ * flow: fetch a server-minted nonce+expiry (inert until redeemed), sign
+ * enableAgentSpendMessage over those EXACT values as the WebAuthn challenge,
+ * submit. Dexter-Wallet (anon-vault) only.
+ *
+ * @param id            WHO is active — must be the passkey-vault (Dexter Wallet).
+ * @param vaultPda      The vault PDA, base58 string.
+ * @param apiOrigin     The dexter-api origin (e.g. https://api.dexter.cash).
+ * @param credentialId  The wallet's passkey credential id (base64url).
+ */
+declare function enableAgentSpend(id: AgentSpendIdentity, vaultPda: string, apiOrigin: string, credentialId?: string | null): Promise<EnableAgentSpendResult>;
+
+export { AgentSpendError, type AgentSpendIdentity, type AgentSpendStatus, type AgentSpendTab, type AnonChallengeResult, type AnonServerPolicy, type AutomaticAgentSpend, CeremonyPhase, ConnectVault, type ContinueResult, CreateWalletConfig, CreateWalletResult, DexterConnectConfig, type EnableAgentSpendResult, IdentityKind, type RawAgentSpendSession, type RawAgentSpendStatus, RecoverOutcome, RecoverWalletConfig, type RevokeAgentSpendResult, SignInResult, assembleAgentSpendStatus, ceremonyPhaseLabel, continueWithDexter, createAnonServerPolicy, createPasskeySigner, describeAgentSpendError, enableAgentSpend, passkeyLogin, recoverWallet, revokeAgentSpend };

package/dist/react.d.ts

@@ -0,0 +1,263 @@
+import { DexterApiBrowserPasskeySigner } from '@dexterai/vault/signers/browser';
+import { b as CeremonyPhase, S as SignInResult, d as RecoverOutcome, P as PasskeyLoginTokens, c as ConnectVault, e as ConnectError, l as StoredWallet, g as PasskeySignalSupport, i as ResolvedIdentity, C as CreateWalletResult } from './signals-C05rIVey.js';
+export { h as RecoverVault } from './signals-C05rIVey.js';
+import { ReactElement, ButtonHTMLAttributes, ReactNode } from 'react';
+
+type ConnectStatus = 'idle' | 'pending' | 'done' | 'error';
+interface UseSignInWithDexterConfig {
+    /** dexter-api base. Default https://api.dexter.cash. */
+    apiBase?: string;
+    /** RPC for the connected-chip balance read. Default: Dexter's Helius proxy. */
+    rpcUrl?: string;
+    /** Ceremony transport (both verbs). 'auto' (default) = inline on dexter.cash,
+     *  popup anywhere else. Exposed so tests/staging can force a leg —
+     *  CreateWalletPanel already had this knob; the sign-in surface was the odd
+     *  one out. */
+    transport?: 'auto' | 'popup' | 'inline';
+    /** Hosted ceremony page for the popup transport. Default dexter.cash/connect. */
+    connectHost?: string;
+    /** Chrome-149+ immediate UI mode for the wallet-only verb: instant fast-fail
+     *  when this device holds no passkey. Ignored by signIn(). */
+    preferImmediate?: boolean;
+}
+interface UseSignInWithDexter {
+    status: ConnectStatus;
+    /** Live ceremony phase while status==='pending' (challenge → passkey →
+     *  verifying); null otherwise. Drives the button's "connecting steps". */
+    phase: CeremonyPhase | null;
+    isVaultConnected: boolean;
+    /** Run the ceremony. Resolves with the result; throws ConnectError on failure
+     *  (error is also captured in `error` + `status==='error'` for declarative UI). */
+    signIn: () => Promise<SignInResult>;
+    /** Wallet-only sign-in (P0c): re-points this browser at an existing wallet,
+     *  mints NO session. Returns a discriminated outcome — cancel is a normal
+     *  result, never a throw. Identity surfaces (useIdentity/useDexterWallet)
+     *  light up via the wallet store; `session`/`vault` here stay null. Fire on
+     *  tap only — never on mount (iOS gesture rule). */
+    recover: () => Promise<RecoverOutcome>;
+    /** Last recover outcome; null until recover() settles. */
+    recovered: RecoverOutcome | null;
+    disconnect: () => void;
+    session: PasskeyLoginTokens | null;
+    vault: ConnectVault | null;
+    /** Dexter Wallet address (swigAddress, base58). */
+    vaultAddress: string | null;
+    vaultPda: string | null;
+    credentialId: string | null;
+    /** Guest passkey signer for authorizing spends / opening x402 tabs. null until
+     *  a vault is connected. Drive it via `passkeySigner.signOperation(op)`. */
+    passkeySigner: DexterApiBrowserPasskeySigner | null;
+    /** USD available. number once read; null = unknown → chip shows wallet only. */
+    usdcBalance: number | null;
+    refreshBalance: () => Promise<void>;
+    error: ConnectError | null;
+}
+/**
+ * "Sign in with Dexter" — React surface over the login ceremony.
+ *
+ * Returns the Supabase session (always) plus the vault identity + USD balance
+ * (vault-review's login payload is live). dexter.cash login needs only
+ * `session`; the vault fields + balance drive the connected chip. The
+ * passkeySigner (for opening x402 tabs — dexter-agents) lands next, on the
+ * anon ServerPolicy bridge over the now-live publicKey/credentialId.
+ */
+declare function useSignInWithDexter(config?: UseSignInWithDexterConfig): UseSignInWithDexter;
+
+interface SignInWithDexterProps extends UseSignInWithDexterConfig {
+    /** 'signin' (default) = full sign-in minting the account session.
+     *  'recover' = wallet-only: re-points this browser at an existing wallet and
+     *  mints NOTHING else (the wallet IS the sign-in). After a successful
+     *  recover the element renders null — identity display belongs to
+     *  DexterWalletChip/useIdentity, which light up via the wallet store. */
+    mode?: 'signin' | 'recover';
+    /** Fired with the result the moment sign-in completes. */
+    onSuccess?: (result: SignInResult) => void;
+    /** Recover mode: fired with EVERY settled outcome (ok, no_credential,
+     *  cancelled, error) — the single channel; onError is not used in this mode.
+     *  Branch on `reason`: no_credential → offer create; cancelled → stay silent. */
+    onRecovered?: (outcome: RecoverOutcome) => void;
+    /** Fired with the typed error if the ceremony fails. */
+    onError?: (error: ConnectError) => void;
+    /** Button label when signed out. Default "Sign in with Dexter". */
+    label?: string;
+    /** 'primary' = filled ember (default), 'secondary' = outline. */
+    variant?: 'primary' | 'secondary';
+    /** Full-width button. */
+    block?: boolean;
+    /** 'md' (default) or 'sm' — the mini header variant of the button. */
+    size?: 'md' | 'sm';
+    /** Extra className composed after the brand classes. Prefer overriding the
+     *  `--dx-*` CSS variables for theming. */
+    className?: string;
+    /** Render the built-in connected chip (wallet + balance). Default true. */
+    showConnectedChip?: boolean;
+}
+/**
+ * Turnkey "Sign in with Dexter" element. Signed out → the branded DexterButton
+ * (hover / focus / active / loading states, themeable via --dx-* CSS vars);
+ * signed in → a compact chip with the Dexter Wallet address + USD available.
+ * Wraps useSignInWithDexter; for the wallet CREATE flow use <DexterButton>
+ * wired to your create action. Brand voice: no emojis, "unlock" banned.
+ */
+declare function SignInWithDexter(props: SignInWithDexterProps): ReactElement | null;
+
+/** The Dexter passkey mark — the brand glyph carried on the branded button. */
+declare function DexterMark(): ReactElement;
+interface DexterButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onClick' | 'disabled' | 'className' | 'type'> {
+    /** Button content (e.g. "Sign in with Dexter", "Create your Dexter Wallet"). */
+    children?: ReactNode;
+    /** Loading state: shows the animated spinner + `loadingLabel`, disables click. */
+    loading?: boolean;
+    /** Label shown next to the spinner while loading. Default "Connecting…". */
+    loadingLabel?: string;
+    /** 'primary' = filled ember (default), 'secondary' = outline,
+     *  'danger' = outline in the danger color for destructive actions. */
+    variant?: 'primary' | 'secondary' | 'danger';
+    /** Full-width (fills its container). */
+    block?: boolean;
+    /** 'md' (default) = the standard CTA. 'sm' = the mini header/chip-row
+     *  variant: tighter padding, smaller type and mark. Same states, same
+     *  theming — never hand-shrink the md button with a className. */
+    size?: 'md' | 'sm';
+    /** Render the Dexter mark before the children. Default true. */
+    withMark?: boolean;
+    onClick?: () => void;
+    disabled?: boolean;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+    type?: 'button' | 'submit';
+}
+/** The branded Dexter button. Wire it to any action via `onClick`. */
+declare function DexterButton(props: DexterButtonProps): ReactElement;
+
+interface UseDexterWallet {
+    /** Active wallet handle, or null if this browser has no active wallet. */
+    activeHandle: string | null;
+    /** The active wallet's roster entry (handle + label + credentialId), or
+     *  null. `activeWallet.label` is the wallet's human name — identity is
+     *  first-class, so display surfaces read it here instead of re-fetching. */
+    activeWallet: StoredWallet | null;
+    /** Known wallets on this browser, most-recently-used first. */
+    wallets: StoredWallet[];
+    /** What the WebAuthn Signal API supports in THIS browser (rename / prune). */
+    support: PasskeySignalSupport;
+    /**
+     * Eject the active wallet — "switch / start fresh". Clears the local binding
+     * and, where supported, prunes the old passkey from the OS manager so it
+     * disappears from the user's list. `{ forget: true }` also drops it from the
+     * roster.
+     */
+    eject: (opts?: {
+        forget?: boolean;
+    }) => void;
+    /** Switch the active wallet to a known handle. No-op if unknown. */
+    switchTo: (handle: string) => boolean;
+    /** Record/activate a handle (after enroll or recover). Prefer over writing
+     *  localStorage by hand so the roster + subscribers stay correct. */
+    setActive: (handle: string, label?: string, credentialId?: string) => void;
+    /**
+     * Rename the ACTIVE passkey in the OS keychain (post-creation). Returns true
+     * if the browser supported it and the signal fired; false otherwise (the
+     * keychain entry is then just left as-is).
+     */
+    rename: (name: string, displayName?: string) => Promise<boolean>;
+}
+declare function useDexterWallet(): UseDexterWallet;
+
+interface DexterWalletChipProps {
+    /** Connected (a wallet/account is present) → avatar + label; else signed-out label only. */
+    connected: boolean;
+    /** What to show: account name, wallet label, or the signed-out prompt (e.g. "Log in"). */
+    label: string;
+    /** Avatar image (e.g. a linked X avatar); falls back to the initial. */
+    avatarUrl?: string | null;
+    /** Single-character avatar fallback (defaults to the first letter of `label`). */
+    avatarInitial?: string;
+    onClick?: () => void;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+    /** Reflected to aria-expanded (when the chip toggles a menu). */
+    ariaExpanded?: boolean;
+}
+/** The branded wallet/account chip. Wire it to open your menu via `onClick`. */
+declare function DexterWalletChip(props: DexterWalletChipProps): ReactElement;
+
+interface DexterWalletMenuProps {
+    /** The wallet's display name (nickname, else "Dexter Wallet"). */
+    walletLabel: string;
+    /** Avatar initial (defaults to the first letter of walletLabel). */
+    avatarInitial?: string;
+    /** "Manage wallet" → the consumer's wallet page. Row hidden if omitted. */
+    onManageWallet?: () => void;
+    /** Eject row → the consumer ejects/resets (guard + perform on its side). Row hidden if omitted. */
+    onStartFresh?: () => void;
+    /** Label for the eject/reset row. Default "Eject wallet". */
+    startFreshLabel?: string;
+    /** Sign-in/save UI revealed when "Save your wallet" is tapped (e.g. <SignInWithDexter/>). Row hidden if omitted. */
+    saveSlot?: ReactNode;
+    /** Short hint shown above the save UI. */
+    saveHint?: string;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+}
+/** The branded wallet dropdown. */
+declare function DexterWalletMenu(props: DexterWalletMenuProps): ReactElement;
+
+interface UseIdentityConfig {
+    /** The account session token (e.g. a Supabase access_token), or null when the
+     *  user has no account session. The SDK is auth-agnostic — pass your own. */
+    accountToken: string | null;
+}
+declare function useIdentity({ accountToken }: UseIdentityConfig): ResolvedIdentity;
+
+interface AllowanceChipsProps {
+    /** The authored USD amount as a raw string, or null when nothing is chosen.
+     *  NONE selected initially → pass null. Preset chips echo '5' / '20' / '50';
+     *  Custom echoes whatever the user types. */
+    value: string | null;
+    /** Fired with the raw USD string (or null when Custom is opened empty). */
+    onChange: (usd: string | null) => void;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+}
+/** The consent-at-birth allowance chips. */
+declare function AllowanceChips(props: AllowanceChipsProps): ReactElement;
+
+interface CreateWalletPanelProps {
+    /** Fired with the minted wallet the moment creation succeeds. */
+    onCreated?: (result: CreateWalletResult) => void;
+    /** Fired with the typed error if the ceremony fails. */
+    onError?: (error: ConnectError) => void;
+    /** dexter-api base. Default https://api.dexter.cash (createWallet's default). */
+    apiBase?: string;
+    /** Where the WebAuthn ceremony runs. Default 'auto' (createWallet's default). */
+    transport?: 'auto' | 'popup' | 'inline';
+    /** Render the optional "Name your wallet" field. Default true. */
+    showName?: boolean;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+}
+/** The turnkey consent-at-birth create panel. */
+declare function CreateWalletPanel(props: CreateWalletPanelProps): ReactElement;
+
+type InstallApp = 'cursor' | 'vscode' | 'hermes' | 'claude-code';
+interface AppInstallButtonsProps {
+    /** MCP endpoint to install. Default: OpenDexter. */
+    mcpUrl?: string;
+    /** Server name written into the app's config. Default: opendexter. */
+    serverName?: string;
+    /** Which app buttons to render, in order. Default: all four. */
+    apps?: InstallApp[];
+    /** Stack full-width instead of a wrapping row. */
+    block?: boolean;
+    className?: string;
+    /** Observability hook: fired on every action a user takes. */
+    onAction?: (app: InstallApp, action: 'deeplink' | 'copied') => void;
+}
+declare function cursorInstallUrl(name: string, mcpUrl: string): string;
+declare function vscodeInstallUrl(name: string, mcpUrl: string): string;
+declare function hermesInstallCommand(name: string, mcpUrl: string): string;
+declare function claudeCodeInstallCommand(name: string, mcpUrl: string): string;
+declare function AppInstallButtons(props: AppInstallButtonsProps): ReactElement;
+
+export { AllowanceChips, type AllowanceChipsProps, AppInstallButtons, type AppInstallButtonsProps, type ConnectStatus, CreateWalletPanel, type CreateWalletPanelProps, DexterButton, type DexterButtonProps, DexterMark, DexterWalletChip, type DexterWalletChipProps, DexterWalletMenu, type DexterWalletMenuProps, type InstallApp, RecoverOutcome, SignInWithDexter, type SignInWithDexterProps, type UseDexterWallet, type UseIdentityConfig, type UseSignInWithDexter, type UseSignInWithDexterConfig, claudeCodeInstallCommand, cursorInstallUrl, hermesInstallCommand, useDexterWallet, useIdentity, useSignInWithDexter, vscodeInstallUrl };

package/dist/react.js

@@ -677,7 +677,7 @@ var DEFAULT_MCP_URL = "https://open.dexter.cash/mcp";
 var DEFAULT_NAME = "opendexter";
 var ALL_APPS = ["cursor", "vscode", "hermes", "claude-code"];
 function cursorInstallUrl(name, mcpUrl) {
-  const config = typeof btoa === "function" ? btoa(JSON.stringify({ url: mcpUrl })) : Buffer.from(JSON.stringify({ url: mcpUrl })).toString("base64");
+  const config = btoa(JSON.stringify({ url: mcpUrl }));
   return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(name)}&config=${encodeURIComponent(config)}`;
 }
 function vscodeInstallUrl(name, mcpUrl) {

package/dist/server.d.ts

@@ -0,0 +1,72 @@
+import { JWTPayload, JWK, JSONWebKeySet } from 'jose';
+
+/**
+ * @dexterai/connect/server — offline Dexter session verification.
+ *
+ * The server half of Sign in with Dexter (CONTRACT-dexter-session-token.md):
+ * a local ES256 signature check against the published JWKS — no call to
+ * Supabase or dexter-api on the hot path, so it runs on Node and edge
+ * runtimes alike. Pre-hook tokens (no `dexter` claim) verify as signed-in
+ * with `vaultAddress: null`; once the access-token hook is enabled the
+ * claim appears with no code change here.
+ *
+ * Phase 1 issuer is Supabase (CONTRACT §3); everything is parameterized on
+ * (iss, jwksUrl) so the Phase-2 sovereign cutover is a config flip.
+ */
+
+declare const DEFAULT_ISS = "https://qdgumpoqnthrjfmqziwm.supabase.co/auth/v1";
+declare const DEFAULT_AUDIENCE = "authenticated";
+/** The namespaced claim sealed into the token by the access-token hook. */
+interface DexterClaim {
+    ver: number;
+    /** Swig state address (base58) — the canonical Dexter Wallet identity. */
+    vault: string;
+    /** 16-byte passkey handle, base64url; absent on rows without one. */
+    userHandle?: string;
+    agentGrant?: unknown;
+}
+type VerifyFailureReason = 'no_token' | 'invalid' | 'expired' | 'issuer_mismatch' | 'audience_mismatch';
+type DexterSession = {
+    isSignedIn: true;
+    sub: string;
+    vaultAddress: string | null;
+    userHandle: string | null;
+    agentGrant: unknown;
+    sessionId: string | null;
+    aal: string | null;
+    claims: JWTPayload & {
+        dexter?: DexterClaim;
+    };
+} | {
+    isSignedIn: false;
+    reason: VerifyFailureReason;
+};
+interface VerifyOptions {
+    /** Expected issuer. Phase 1 default: the Dexter Supabase project. */
+    iss?: string;
+    /** JWKS location; defaults to `${iss}/.well-known/jwks.json`. */
+    jwksUrl?: string;
+    /**
+     * Public key(s) for fully networkless verification (a JWK or a JWKS).
+     * When omitted, the JWKS is fetched once and cached in-instance.
+     */
+    jwtKey?: JWK | JSONWebKeySet;
+    /** Expected audience. Default: Supabase's `authenticated`. */
+    audience?: string;
+}
+/** A fetch-API Request or anything with a node-style headers bag. */
+type RequestLike = Request | {
+    headers: Record<string, string | string[] | undefined>;
+};
+interface DexterClient {
+    verifyDexterSession(token: string): Promise<DexterSession>;
+    authenticateRequest(req: RequestLike): Promise<DexterSession>;
+}
+declare function createDexterClient(options?: VerifyOptions): DexterClient;
+/**
+ * One-off verification. For servers verifying many requests against a
+ * remote JWKS, create a client once instead so the key set caches.
+ */
+declare function verifyDexterSession(token: string, options?: VerifyOptions): Promise<DexterSession>;
+
+export { DEFAULT_AUDIENCE, DEFAULT_ISS, type DexterClaim, type DexterClient, type DexterSession, type RequestLike, type VerifyFailureReason, type VerifyOptions, createDexterClient, verifyDexterSession };

package/dist/signals-C05rIVey.d.ts

@@ -0,0 +1,289 @@
+/** Supabase session tokens returned by dexter-api's passkey-login (camelCase). */
+interface PasskeyLoginTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    expiresIn: number;
+    tokenType: string;
+}
+/**
+ * Vault identity, returned ALONGSIDE the session by passkey-login once
+ * vault-review ships the dexter-api change (ASK 1). Optional until then —
+ * the connector degrades to session-only. Consumers that open x402 tabs
+ * (dexter-agents) need `vaultPda` + `publicKey` to build a passkey signer.
+ */
+interface ConnectVault {
+    vaultPda: string;
+    /** Swig state address, base58 — the user-facing Dexter Wallet address. */
+    swigAddress: string;
+    /** v2 swig wallet PDA (deposit address); null until the swig is deployed. */
+    receiveAddress: string | null;
+    /** Swig wallet's USDC ATA, base58 (for the connected-chip balance read);
+     *  null until the swig is deployed. Server-resolved (off-curve-safe). */
+    usdcAta: string | null;
+    /** base64 33-byte SEC1 compressed P-256 authority pubkey (for the signer). */
+    publicKey: string;
+    userHandle: string;
+    credentialId: string;
+    /** The wallet's cross-device display name (user-authored via rename), or
+     *  null when never named. Identity is first-class: every sign-in carries
+     *  the human name so no consumer ever falls back to a synthetic email.
+     *  Optional for wire-compat with servers/popup pages predating 0.23. */
+    walletLabel?: string | null;
+}
+/** Result of a completed "Sign in with Dexter" ceremony. */
+interface SignInResult {
+    session: PasskeyLoginTokens;
+    /** Present once vault-review ships the vault-in-login change. */
+    vault?: ConnectVault;
+}
+/**
+ * Coarse ceremony phase, emitted as a sign-in/create ceremony progresses so the
+ * UI can show live "connecting steps" instead of one flat spinner:
+ *   challenge → passkey (the OS prompt) → verifying → finalizing (create only).
+ */
+type CeremonyPhase = 'challenge' | 'passkey' | 'verifying' | 'finalizing';
+/**
+ * Vault identity on the wallet-only recover leg, as reported by
+ * /api/passkey-vault-anon/status. Narrower than ConnectVault on purpose —
+ * the status endpoint carries no publicKey/usdcAta, so a recover cannot
+ * construct a passkey signer; it re-points this browser at the wallet and
+ * lets useIdentity/useDexterWallet light the UI.
+ */
+interface RecoverVault {
+    vaultPda: string;
+    /** Swig state address, base58 — the user-facing Dexter Wallet address. */
+    swigAddress: string;
+    /** Deposit address; null until the swig is deployed. */
+    receiveAddress: string | null;
+    isActivated: boolean;
+    walletLabel: string | null;
+}
+/**
+ * Result of a wallet-only recover ceremony. A discriminated RESULT, not a
+ * throw: user-cancel is a normal outcome in WebAuthn, and consumers branch on
+ * `reason` (no_credential → offer create; cancelled → stay silent; error →
+ * retry copy). `no_credential` covers both the immediate-mode instant
+ * rejection (no passkey on this device) and a verify 404 (a passkey the
+ * server has no row for).
+ */
+type RecoverOutcome = {
+    ok: true;
+    userHandle: string;
+    credentialId: string;
+    vault: RecoverVault;
+} | {
+    ok: false;
+    reason: 'no_credential' | 'cancelled' | 'error';
+    error?: ConnectError;
+};
+interface RecoverWalletConfig extends DexterConnectConfig {
+    /** Chrome-149+ immediate UI mode: instant fast-fail when this device has no
+     *  discoverable passkey (no empty account-picker sheet). Falls back to the
+     *  normal modal wherever unsupported. */
+    preferImmediate?: boolean;
+    onPhase?: (phase: CeremonyPhase) => void;
+}
+interface DexterConnectConfig {
+    /** dexter-api base. Default https://api.dexter.cash. */
+    apiBase?: string;
+    /**
+     * Where the WebAuthn ceremony runs:
+     *  - 'auto' (default): inline on the canonical Dexter origin (dexter.cash),
+     *    popup on ANY other origin — so a third-party site works without the
+     *    WebAuthn rpId-origin problem (in-page only works on dexter.cash).
+     *  - 'popup': always via the hosted popup (works on any website).
+     *  - 'inline': always in-page — only valid on a Dexter origin; this is what
+     *    the hosted ceremony page itself uses.
+     */
+    transport?: 'auto' | 'popup' | 'inline';
+    /** Hosted ceremony page (popup transport). Default https://dexter.cash/connect. */
+    connectHost?: string;
+}
+/** Typed error whose `code` is the server's snake_case error string. */
+declare class ConnectError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+
+/** Consent-at-birth allowance (Branch rulings 2026-07-02/03).
+ *  The user authors the number; zero is not consent; TTL is fixed 30d and
+ *  never user-editable; no caller may invent a default. */
+declare const SESSION_TTL_30D = "2592000";
+interface SpendPolicy {
+    /** Role-2 allowance, atomic USDC (6dp), decimal string. User-authored. */
+    spendLimitAtomic: string;
+    /** Fixed 30d. Present for wire compatibility; always SESSION_TTL_30D. */
+    sessionTtlSeconds: string;
+}
+/** Parse user-entered USD ("5", "$20", "1,000", "20.5") to atomic USDC.
+ *  Null on anything invalid — callers must not invent a fallback. */
+declare function usdToAtomic(input: string): bigint | null;
+/** Null when invalid or zero (zero is not consent). */
+declare function authoredPolicy(usdInput: string): SpendPolicy | null;
+
+interface CreateWalletConfig extends DexterConnectConfig {
+    /** Label for the passkey in the OS keychain AND the wallet roster. Set at
+     *  creation — the only moment naming is guaranteed to stick. Default "Dexter Wallet". */
+    name?: string;
+    /** RP id for the new credential. Default "dexter.cash". */
+    rpId?: string;
+    /** Consent-at-birth allowance the user authored at creation (chips $5/$20/$50
+     *  or Custom; zero is not consent; build it with authoredPolicy()). When
+     *  present it rides the /initialize body so the number becomes the server-side
+     *  write-once consent record. The TTL is ruled fixed 30d — whatever the object
+     *  carries, the wire always sends SESSION_TTL_30D. Absent → no policy authored
+     *  (the vault initializes without one; nothing invents a default). */
+    spendPolicy?: SpendPolicy;
+    /** Called as the ceremony progresses, for live "connecting steps" UI:
+     *  challenge → passkey → verifying → finalizing. */
+    onPhase?: (phase: CeremonyPhase) => void;
+}
+interface CreateWalletResult {
+    /** Server-minted 16-byte user handle, base64url — the vault identity. */
+    handle: string;
+    /** base64url credential id of the new passkey. */
+    credentialId: string;
+    /** The freshly initialized vault (swig not yet deployed; deploys lazily). */
+    vault: ConnectVault;
+    /** Wallet name recorded at birth (server-confirmed via /initialize). Rides
+     *  the result so a popup-typed name reaches the OPENER's wallet store —
+     *  before 0.23.2 it lived only on the popup origin. null = unnamed. */
+    label: string | null;
+}
+/**
+ * Mint a brand-new Dexter wallet (passkey + vault) and make it the active wallet.
+ *
+ * One passkey approval. Throws ConnectError on any failed leg (the `code` is the
+ * server's error string, or webauthn_failed / no_credential for the ceremony).
+ */
+declare function createWallet(config?: CreateWalletConfig): Promise<CreateWalletResult>;
+
+type IdentityKind = 'passkey-vault' | 'account' | 'none';
+interface IdentityInput {
+    /** An account session token (e.g. Supabase access_token) when present, else null. */
+    accountToken: string | null;
+    /** The passkey-vault user handle (the connect wallet store), else null. */
+    userHandle: string | null;
+    /** The active wallet's display name from the connect wallet store (persisted
+     *  at sign-in/recover/rename), else null. Browser-only input like the handle. */
+    walletLabel?: string | null;
+}
+interface ResolvedIdentity {
+    /** The primary identity axis, passkey-vault-first. */
+    kind: IdentityKind;
+    /** Passkey-vault identity (FIRST-CLASS): the wallet handle, or null. */
+    userHandle: string | null;
+    /** The wallet's human display name, or null when the wallet was never named
+     *  (or no wallet is active). Display surfaces prefer this over any synthetic
+     *  account identifier — a user should never be shown a generated email. */
+    walletLabel: string | null;
+    /** Account identity (secondary/legacy axis): bearer for account-scoped fetches, or null. */
+    accountToken: string | null;
+    /** A passkey vault is present on this device. */
+    hasPasskeyVault: boolean;
+    /** An account session is present. */
+    hasAccount: boolean;
+    /** Any identity at all — drives "show the wallet" vs "Sign in with Dexter". */
+    hasWallet: boolean;
+}
+declare function resolveIdentity(input: IdentityInput): ResolvedIdentity;
+
+/** A wallet this browser knows about. `handle` is the identity; the rest is UX. */
+interface StoredWallet {
+    /** base64url 16-byte user handle — the vault identity. */
+    handle: string;
+    /** Human label for switch UIs (e.g. an email, or "Dexter Wallet"). */
+    label?: string;
+    /** base64url credential id — enables the WebAuthn Signal API to prune this
+     *  passkey from the OS manager on eject (see ./signals). */
+    credentialId?: string;
+    /** Epoch ms of last activation — for ordering the switcher. */
+    lastUsedAt?: number;
+}
+type Listener = () => void;
+/** The active wallet handle, or null if this browser has no active wallet. */
+declare function getActiveHandle(): string | null;
+/**
+ * Set the active wallet handle (e.g. after enroll or recover), upserting it into
+ * the roster with a fresh `lastUsedAt`. Idempotent. Fires subscribers.
+ */
+declare function setActiveHandle(handle: string, label?: string, credentialId?: string): void;
+/** Look up a known wallet's stored credentialId (for Signal-API prune on eject). */
+declare function getCredentialId(handle: string): string | undefined;
+/**
+ * EJECT — clear the active wallet so the browser is no longer bound to it. This
+ * is "switch / start fresh / sign out of this wallet". The wallet stays in the
+ * roster (so the user can switch back) unless `forget` is true. After eject,
+ * `getActiveHandle()` is null and the next enroll/recover starts clean. Fires
+ * subscribers. This is the function whose absence WAS the welded-wallet bug.
+ */
+declare function ejectActiveWallet(opts?: {
+    forget?: boolean;
+}): void;
+/** Every wallet this browser knows about, most-recently-used first. */
+declare function listWallets(): StoredWallet[];
+/**
+ * Switch the active wallet to a handle ALREADY in the roster. Returns false (and
+ * does nothing) if the handle is unknown — switching is only ever to a wallet
+ * this browser has seen, never to an arbitrary string.
+ */
+declare function switchWallet(handle: string): boolean;
+/** Remove a wallet from the roster entirely; clears active if it was active. */
+declare function forgetWallet(handle: string): void;
+/**
+ * Subscribe to active-wallet/roster changes. Returns an unsubscribe fn. Also
+ * wires the cross-tab `storage` event once, so ejecting in one tab updates the
+ * others. The React hook (`useDexterWallet`) is a thin wrapper over this.
+ */
+declare function subscribe(listener: Listener): () => void;
+/** Exposed for consumers that must reference the canonical key (migrations,
+ *  tests). Prefer the accessors above — do NOT read localStorage by hand. */
+declare const ACTIVE_WALLET_STORAGE_KEY = "dexter:passkey:userHandle";
+
+interface PasskeySignalSupport {
+    /** signalCurrentUserDetails — rename a passkey post-creation. */
+    rename: boolean;
+    /** signalUnknownCredential — remove one stale passkey from the manager. */
+    prune: boolean;
+    /** signalAllAcceptedCredentials — reconcile the full valid set. */
+    syncAccepted: boolean;
+}
+/**
+ * What the CURRENT browser supports, by direct feature-detection. Instant, no
+ * network, no UA sniffing — tells you exactly what will light up on THIS device
+ * (e.g. call once on Branch's iPhone to learn its Safari's status).
+ */
+declare function passkeySignalSupport(): PasskeySignalSupport;
+/**
+ * Rename a passkey in the OS keychain AFTER creation. `userId` is the base64url
+ * user handle; `rpId` defaults to the current host. Returns true if the signal
+ * fired, false if unsupported/failed (caller treats false as "left as-is").
+ */
+declare function renamePasskey(args: {
+    userId: string;
+    name: string;
+    displayName?: string;
+    rpId?: string;
+}): Promise<boolean>;
+/**
+ * Tell the OS manager a credential is gone so it removes that passkey from the
+ * user's list — the welded-old-wallet auto-cleanup. `credentialId` is base64url.
+ * Returns true if fired, false if unsupported/failed.
+ */
+declare function prunePasskey(args: {
+    credentialId: string;
+    rpId?: string;
+}): Promise<boolean>;
+/**
+ * Declare the FULL set of still-valid credential IDs for a user; the manager
+ * prunes anything not listed. Use after sign-in or eject to reconcile in one
+ * shot (pass `[]` to clear all of a user's passkeys). Returns true if fired.
+ */
+declare function syncAcceptedPasskeys(args: {
+    userId: string;
+    acceptedCredentialIds: string[];
+    rpId?: string;
+}): Promise<boolean>;
+
+export { ACTIVE_WALLET_STORAGE_KEY as A, syncAcceptedPasskeys as B, type CreateWalletResult as C, type DexterConnectConfig as D, usdToAtomic as E, type IdentityKind as I, type PasskeyLoginTokens as P, type RecoverWalletConfig as R, type SignInResult as S, type CreateWalletConfig as a, type CeremonyPhase as b, type ConnectVault as c, type RecoverOutcome as d, ConnectError as e, type IdentityInput as f, type PasskeySignalSupport as g, type RecoverVault as h, type ResolvedIdentity as i, SESSION_TTL_30D as j, type SpendPolicy as k, type StoredWallet as l, authoredPolicy as m, createWallet as n, ejectActiveWallet as o, forgetWallet as p, getActiveHandle as q, getCredentialId as r, listWallets as s, passkeySignalSupport as t, prunePasskey as u, renamePasskey as v, resolveIdentity as w, setActiveHandle as x, subscribe as y, switchWallet as z };

package/dist/worldid.d.ts

@@ -0,0 +1,61 @@
+import { ReactElement } from 'react';
+import { IDKitResult } from '@worldcoin/idkit';
+
+type VerifyPersonhoodPhase = 'loading' | 'ready' | 'rp_error' | 'verified';
+interface VerifyPersonhoodConfig {
+    /** World ID app id (`app_…`), from the developer portal. */
+    appId: `app_${string}`;
+    /** The registered action (e.g. `dexter-credit-root-v2`) — pins the nullifier namespace. */
+    action: string;
+    /** `production` | `staging`. Default `production`. */
+    environment?: 'production' | 'staging';
+    /**
+     * URL that returns the SERVER-SIGNED RP context as `{ rp_context: RpContext }`.
+     * The RP signing key is server-side only (never the browser), so the consumer
+     * exposes an endpoint that signs the request and returns just the signed
+     * context. Mirrors the capture rig's `/api/rp-context`.
+     */
+    rpContextUrl: string;
+    /** Optional `fetch` init for the RP-context request (auth headers, etc.). */
+    rpContextInit?: RequestInit;
+}
+interface UseVerifyPersonhood {
+    phase: VerifyPersonhoodPhase;
+    error: string | null;
+    result: IDKitResult | null;
+    /** Open the World App verification sheet. No-op until phase is 'ready'/'verified'. */
+    open: () => void;
+    /** The IDKitRequestWidget element to render (null until the RP context loads). */
+    widget: ReactElement | null;
+}
+/**
+ * Headless hook: manages the RP-context fetch + IDKit lifecycle and hands back
+ * the raw proof. Render `widget` and call `open()` from your own UI, or use the
+ * turnkey <VerifyPersonhood> below.
+ */
+declare function useVerifyPersonhood(config: VerifyPersonhoodConfig, onProof?: (result: IDKitResult) => void, onError?: (error: Error) => void): UseVerifyPersonhood;
+interface VerifyPersonhoodProps extends VerifyPersonhoodConfig {
+    /** Fired with the raw World ID v4 proof the moment verification completes. */
+    onProof?: (result: IDKitResult) => void;
+    /** Fired with the typed error if RP signing or verification fails. */
+    onError?: (error: Error) => void;
+    /** Button label when armed. Default "Verify your personhood". */
+    label?: string;
+    /** Label after a proof is captured. Default "Verify again". */
+    verifiedLabel?: string;
+    /** 'primary' = filled ember (default), 'secondary' = outline. */
+    variant?: 'primary' | 'secondary';
+    /** Full-width button. */
+    block?: boolean;
+    /** Extra className composed after the brand classes. */
+    className?: string;
+}
+/**
+ * Turnkey "Verify your personhood" element — the personhood sibling of
+ * <SignInWithDexter>. Renders the branded DexterButton (loading while the RP
+ * context signs server-side) that opens World App; on success hands the raw
+ * IDKitResult to `onProof`. Brand voice: no emojis. Themeable via --dx-* vars.
+ */
+declare function VerifyPersonhood(props: VerifyPersonhoodProps): ReactElement;
+
+export { type UseVerifyPersonhood, VerifyPersonhood, type VerifyPersonhoodConfig, type VerifyPersonhoodPhase, type VerifyPersonhoodProps, useVerifyPersonhood };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/connect",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "description": "Sign in with Dexter — passkey connector. Composes @dexterai/vault.",
   "type": "module",
   "exports": {