@dogeos/dogeos-sdk 4.0.0 → 4.0.2-beta.0

package/README.md

@@ -163,7 +163,7 @@ export function SignMessageButton() {
 
 ### 5. Sign In with Wallet (SIW)
 
-Use the `signInWithWallet` method to sign in with wallet and obtain an authentication token:
+`signInWithWallet` constructs a message and returns its signature. It does not create a server session or return an authentication token. For EVM wallets it constructs an ERC-4361 (SIWE) message using the connected address and decimal chain ID. Supply your server-issued nonce and issuedAt, together with the expected domain and URI, so your server can reconstruct and verify the challenge. The helper preserves nonce and URI, normalizes issuedAt to ISO UTC, and signs the constructed bytes unchanged. A supplied address or chain ID must match the connected wallet. If your server already returns the complete message, use `signMessage({ message })` to sign those exact bytes instead.
 
 ```tsx
 // SignInButton.tsx
@@ -175,7 +175,9 @@ export function SignInButton() {
 
   const handleSignIn = async () => {
     try {
-      const proof = await signInWithWallet();
+      // Your server creates and retains these SIWE fields, including nonce and issuedAt.
+      const challenge = await fetchSignInChallenge(address);
+      const proof = await signInWithWallet(challenge);
       // Send the short-lived proof directly to your backend. Never log it or persist it in localStorage.
       await sendProofToBackend(proof);
     } catch (error) {
@@ -191,6 +193,8 @@ export function SignInButton() {
 }
 ```
 
+`fetchSignInChallenge` and `sendProofToBackend` above are application callbacks, not SDK endpoints. The server must verify the signature and expected challenge fields before creating a session. Version 4.0.1 corrects the EVM helper's previously nonstandard message format; custom verifiers that reconstructed the old text must adopt the SIWE format. No legacy-format fallback is performed.
+
 ## Configuration
 
 `WalletConnectProvider` accepts a `config` prop to customize the SDK's behavior.
@@ -488,6 +492,14 @@ const {
 } = useWalletConnect();
 ```
 
+On mobile, selecting a wallet without an injected provider may open the dApp in
+that wallet's browser. The SDK picker closes and clears its connecting state;
+the source tab is not connected by this handoff. If you call `connect()` directly,
+its promise rejects with `code: "WALLET_BROWSER_REDIRECT"` for this outcome.
+Handle that code as a browser handoff, not a completed connection. An existing
+connection in the source tab is preserved. Injected providers and WalletConnect
+sessions continue to resolve normally after connection approval.
+
 ### useAccount
 
 Hook for getting the currently connected account information and performing account-related operations.

package/dist/index.d.ts

@@ -17,8 +17,63 @@ import { WalletInfo } from '@tomo-inc/wallet-adaptor-base';
 import { WalletProvider } from '@tomo-inc/inject-providers';
 import { WalletProvider as WalletProvider_2 } from '@tomo-inc/wallet-adaptor-base';
 
+declare type AuthAssurance = "baseline" | "strong";
+
+declare type AuthClientState = {
+    kind: "anonymous";
+} | {
+    kind: "authenticating";
+    flowId: FlowId;
+} | {
+    kind: "authenticated";
+    session: AuthSessionProjection;
+} | {
+    kind: "error";
+    error: DogeOSAuthError;
+};
+
+declare type AuthErrorCode = "invalid_client" | "unsupported_protocol" | "invalid_delivery" | "provider_cancelled" | "provider_rejected" | "invalid_state" | "flow_interrupted" | "flow_expired" | "email_address_invalid" | "email_code_invalid" | "email_challenge_expired" | "email_challenge_exhausted" | "email_delivery_unavailable" | "attestation_enrollment_required" | "attestation_challenge_expired" | "attestation_rejected" | "handoff_replayed" | "proof_required" | "assurance_required" | "session_revoked" | "reauthentication_required" | "cleanup_required" | "wallet_mfa_dependency_unavailable" | "rate_limited" | "temporarily_unavailable";
+
+declare type AuthErrorResponse = {
+    code: AuthErrorCode;
+    message: string;
+    correlationId: string;
+};
+
+declare type AuthInteraction = {
+    kind: "relay_hosted";
+    mode: "popup" | "redirect";
+} | {
+    kind: "client_owned";
+} | {
+    kind: "embedded_wallet";
+    walletOrigin: string;
+    iframeChallenge: string;
+};
+
+declare type AuthMutationContext = {
+    readonly idempotencyKey: string;
+};
+
+declare type AuthProvider = "google" | "apple" | "x" | "email";
+
+declare type AuthSessionProjection = {
+    familyId: SessionFamilyId;
+    subjectId: string;
+    accountId: string;
+    tenantId: string;
+    clientId: ClientId;
+    sessionEpoch: number;
+    assurance: AuthAssurance;
+    expiresAt: string;
+};
+
 export declare type BasicLoginType = "email" | "externalWallets";
 
+declare type BrandedId<Name extends string> = string & {
+    readonly [idBrand]: Name;
+};
+
 export declare type Chain = {
     id: number;
     name: string;
@@ -67,6 +122,8 @@ export declare enum ChainTypeEnum {
     SUI = "sui"
 }
 
+declare type ClientId = BrandedId<"ClientId">;
+
 export declare interface ConnectData {
     address: string;
     chainId: string;
@@ -83,6 +140,54 @@ export declare interface ConnectVariables {
     chainId?: string;
 }
 
+declare type CreateEmailAuthFlowResponse = {
+    flowId: FlowId;
+    operationCredential: string;
+    expiresAt: string;
+    interaction: EmailFlowInteraction;
+};
+
+declare type CreateEmailFlowOptions = {
+    interaction?: AuthInteraction;
+    mutation?: AuthMutationContext;
+};
+
+declare class DogeOSAuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly correlationId: string | null;
+    constructor(args: {
+        code: AuthErrorCode;
+        message: string;
+        correlationId?: string | null;
+    });
+}
+
+export declare type DogeOSAuthFacade = {
+    state: AuthClientState;
+    readonly email: DogeOSEmailAuthClient;
+    login(options: LoginOptions): Promise<AuthSessionProjection>;
+    getSession(): Promise<AuthSessionProjection | null>;
+    refresh(): Promise<AuthSessionProjection>;
+    reauthenticate(requirement: ReauthenticationRequirement): Promise<AuthSessionProjection>;
+    logout(): Promise<void>;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+
+declare interface DogeOSEmailAuthClient {
+    create(options?: CreateEmailFlowOptions): Promise<EmailAuthFlowHandle>;
+    start(options: EmailStartOptions): Promise<EmailStartOutcome>;
+    resend(options: EmailStartOptions): Promise<EmailStartOutcome>;
+    verify(options: EmailVerifyOptions): Promise<EmailVerificationOutcome>;
+    status(options: EmailStatusOptions): Promise<EmailFlowStatus>;
+    cancel(options: EmailCancelOptions): Promise<EmailCancelReceipt>;
+    complete(options: EmailCompleteOptions): Promise<EmailAuthSessionProjection>;
+    /**
+     * Reconciles a safe session-scoped capsule with Relay. This performs only a
+     * status read; it never starts or resends email.
+     */
+    resume(): Promise<EmailFlowStatus | null>;
+}
+
 export declare type DogeOSEmbeddedWalletConfig = Omit<DogeOSEmbeddedWalletInitConfig, "stage"> & {
     stage?: EmbeddedWalletStage;
 };
@@ -91,6 +196,117 @@ export declare type DogeOSEmbeddedWalletInitConfig = Omit<EmbeddedWalletConfig,
     stage: EmbeddedWalletStage;
 };
 
+/**
+ * An email flow plus its original delivery verifier. Keep this object in
+ * volatile memory only. If its runtime is interrupted, discard it and surface
+ * `flow_interrupted`; do not persist or reconstruct its secrets.
+ */
+declare type EmailAuthFlowHandle = CreateEmailAuthFlowResponse & {
+    verifier: string;
+};
+
+/** Email possession establishes only baseline product authentication. */
+declare type EmailAuthSessionProjection = AuthSessionProjection & {
+    assurance: "baseline";
+};
+
+declare type EmailCancelOptions = EmailFlowAuthorization & {
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailCancelReceipt = {
+    flowId: FlowId;
+    status: "cancelled";
+    cancelledAt: string;
+};
+
+declare type EmailChallengeId = BrandedId<"EmailChallengeId">;
+
+declare type EmailChallengeStatus = {
+    challengeId: EmailChallengeId;
+    status: "dispatching" | "code_sent" | "verifying" | "verified" | "exhausted" | "expired" | "cancelled";
+    expiresAt?: string;
+    resendAfter?: string;
+    failuresRemaining?: number;
+    sendsRemaining?: number;
+};
+
+declare type EmailCompleteOptions = EmailFlowAuthorization & {
+    verifier: string;
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailFlowAuthorization = {
+    flowId: FlowId;
+    operationCredential: string;
+};
+
+declare type EmailFlowInteraction = {
+    kind: "relay_hosted";
+    state: "bootstrap_required";
+    bootstrap: {
+        action: string;
+        credential: string;
+    };
+} | {
+    kind: "client_owned";
+    state: "ready";
+} | {
+    kind: "embedded_wallet";
+    state: "ready";
+};
+
+declare type EmailFlowStatus = {
+    flowId: FlowId;
+    phase: "pending" | "processing" | "completed";
+    resumable: true;
+    challenge?: EmailChallengeStatus;
+} | {
+    flowId: FlowId;
+    phase: "failed" | "expired" | "cancelled";
+    resumable: false;
+    error: AuthErrorResponse;
+    challenge?: EmailChallengeStatus;
+};
+
+declare type EmailStartOptions = EmailFlowAuthorization & {
+    email: string;
+    mutation?: AuthMutationContext;
+};
+
+declare type EmailStartOutcome = {
+    challengeId: EmailChallengeId;
+    status: "dispatching";
+    destinationHint: string;
+    statusUrl: string;
+} | {
+    challengeId: EmailChallengeId;
+    status: "code_sent";
+    destinationHint: string;
+    expiresAt: string;
+    resendAfter: string;
+};
+
+declare type EmailStatusOptions = EmailFlowAuthorization;
+
+declare type EmailVerificationOutcome = {
+    flowId: FlowId;
+    status: "completed";
+} | {
+    flowId: FlowId;
+    status: "processing";
+};
+
+declare type EmailVerifyOptions = EmailFlowAuthorization & {
+    challengeId: EmailChallengeId;
+    /**
+     * Opaque, provider-delivered verifier segment. The SDK must not infer a
+     * numeric format, length, or leading-zero semantics from it.
+     */
+    code: string;
+    mutation?: AuthMutationContext;
+};
+
 declare interface EmbeddedWalletConnectedInfo {
     evmProvider?: ProviderConnectionInfo;
     solanaProvider?: ProviderConnectionInfo;
@@ -110,6 +326,8 @@ declare interface EmbeddedWalletState {
 
 export declare type EvmChain = Chain_2;
 
+declare type FlowId = BrandedId<"FlowId">;
+
 /**
  * Get all available chains
  * Fetches chains from backend API and returns all supported chains in config format
@@ -130,6 +348,15 @@ export declare function getConnectors(): Promise<WalletConfig[]>;
 
 export declare type GetConnectorsReturnType = Promise<WalletConfig[]>;
 
+declare const idBrand: unique symbol;
+
+declare type LoginOptions = {
+    provider: "email";
+    email: string;
+} | {
+    provider: Exclude<AuthProvider, "email">;
+};
+
 export declare enum ModalView {
     Loading = "LOADING",
     WalletList = "WALLET_LIST",
@@ -167,6 +394,17 @@ export declare interface ProviderInfo {
     walletId?: string;
 }
 
+declare type ReauthenticationRequestId = BrandedId<"ReauthenticationRequestId">;
+
+declare type ReauthenticationRequirement = {
+    requestId: ReauthenticationRequestId;
+    audience: string;
+    maxSessionAgeSeconds: number;
+    expiresAt: string;
+};
+
+declare type SessionFamilyId = BrandedId<"SessionFamilyId">;
+
 export { SignInParams }
 
 export declare interface SocialLoginProvider {
@@ -223,6 +461,8 @@ export declare const useConnectors: () => {
     currentProvider: WalletProvider_2 | null;
 };
 
+export declare function useDogeOSAuth(): DogeOSAuthFacade;
+
 /**
  * Internal hook to access embedded wallet state.
  * NOT part of the public API — use `useWalletConnect()` for readiness.