@rakomi/react-native 0.0.0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,698 @@
+import { ReactNode } from 'react';
+import { AuthEvent, Locale, Translations, AuthMachineState, SignInOptions, SignInResult, TokenResult, AuthError, UserResource, HasParams, SwitchOrgResult, SessionResource, AuthConfig, BrandingConfig, OrgMembershipClaim, TranslationFn, OAuthTokenResponse, HttpClient, OpaqueUserHandle, PasskeyCeremonyAdapter, PasskeySummary, PasskeyError, AssertPasskeyResult, StepUpWithPasskeyResult, RegisterPasskeyResult, ListPasskeysResult, PasskeySummaryResult, DeletePasskeyResult, RequestResult, VerifyResult } from '@rakomi/sdk-core';
+export { AssertPasskeyResult, AuthError, AuthEvent, AuthMachineState, CryptoProvider, DeletePasskeyResult, HasParams, HttpClient, KeyValueStore, ListPasskeysResult, Locale, MfaStepUpRequiredError, MfaStepUpUnavailableError, OpaqueUserHandle, PasskeyCeremonyAdapter, PasskeyError, PasskeyErrorCode, PasskeySummary, PasskeySummaryResult, PasskeyTokens, PkceChallenge, RegisterPasskeyResult, RegisterResult, SessionResource, SignInOptions, SignInResult, StepUpWithPasskeyResult, SwitchOrgResult, TokenResult, Translations, UserResource, base64url, createTranslator, decodeJwtPayload, decodeSession, decodeUser, generatePkce, getErrorMessage, hasPermission, hasRole, isSafeUrl, networkError, parseOAuthCallbackError, parseTokenEndpointError, scorePassword, selectPluralForm } from '@rakomi/sdk-core';
+import { D as DpopProver, N as NativeAuthAdapter, T as TokenCache } from './passkey-adapter-D_Z3Z7lV.js';
+export { A as AppLifecycle, a as AppStateValue, b as AttestationVerifier, B as BackgroundTask, c as BiometricGate, d as BiometricResult, e as BrowserAuthSessionOptions, f as BrowserAuthSessionResult, C as ConnectivityProvider, g as CreateDefaultExpoAdapterOptions, h as CreateNativeDpopProverOptions, i as CreateNativePasskeyAdapterOptions, j as DeepLinkProvider, k as DpopProofInput, l as NativeDpopModuleSpec, m as NativePasskeyCeremonyAdapter, n as NativePasskeyModuleSpec, P as ParClient, S as SystemBrowser, o as createDefaultExpoAdapter, p as createNativeDpopProver, q as createNativePasskeyAdapter } from './passkey-adapter-D_Z3Z7lV.js';
+
+/** Reason a DPoP-requested session was downgraded to Bearer by the server. */
+interface DpopDowngradeInfo {
+    /** The server returned `token_type: "Bearer"` for a session that presented a DPoP proof. */
+    reason: 'server_returned_bearer';
+}
+interface CreateDpopSessionOptions {
+    /**
+     * The native-keystore-backed prover for this session (one keypair per session).
+     * Wire the consumer's native adapter (`NativeAuthAdapter.dpopProver`) here. The
+     * SAME instance MUST serve issuance and refresh — never construct a new prover
+     * per refresh.
+     */
+    prover: DpopProver;
+    /**
+     * Base URL of the Rakomi API (e.g. `https://api.rakomi.com`). Used to build the
+     * canonical `htu` of the proof; MUST match the host the refresh call targets or
+     * the server rejects the proof (`htu` mismatch, RFC 9449 §4.3).
+     */
+    baseUrl: string;
+    /**
+     * Invoked at most once if the server downgrades a DPoP-requested session to
+     * `Bearer`. The session does NOT become bound. No secret material (proof / key
+     * / jwk / jti) is ever passed to this hook.
+     */
+    onDowngrade?: (info: DpopDowngradeInfo) => void;
+}
+/**
+ * Opaque, session-scoped DPoP binding handle. Create ONE per logged-in session,
+ * pass it to the auth ceremony AND every refresh for that session. Never share an
+ * instance across distinct sessions or across a refresh-token boundary.
+ *
+ * @public — additive-only.
+ */
+declare class DpopSession {
+    private readonly prover;
+    private readonly baseUrl;
+    private readonly onDowngrade?;
+    private _bound;
+    private _downgraded;
+    private _downgradeNotified;
+    private _boundJkt;
+    constructor(options: CreateDpopSessionOptions);
+    /**
+     * `true` once the server has confirmed (`token_type === "DPoP"`) that this
+     * session's key is sender-bound. The SDK attaches a refresh proof IFF this is
+     * `true`. Starts `false`; set by observing issuance/refresh responses.
+     */
+    get isBound(): boolean;
+    /**
+     * `true` if a session that presented a DPoP proof was returned as `Bearer` by
+     * the server (a security downgrade — flag off / server-side downgrade).
+     */
+    get isDowngraded(): boolean;
+    /** The committed RFC 7638 thumbprint (`jkt`) of the session keypair, once bound. */
+    get boundJkt(): string | undefined;
+    resolveProof(htm: string, target: string, opts?: {
+        nonce?: string;
+    }): Promise<string>;
+    jktHint(): Promise<string>;
+    observeTokenType(tokenType: string | undefined, attachedProof: boolean): Promise<void>;
+}
+/**
+ * Factory for a {@link DpopSession}. Equivalent to `new DpopSession(options)`.
+ *
+ * @public — additive-only.
+ */
+declare function createDpopSession(options: CreateDpopSessionOptions): DpopSession;
+
+/**
+ * `<RakomiProvider>` — RN context provider.
+ *
+ * Owns:
+ * - The frozen `NativeAuthAdapter`.
+ * - The auth-machine snapshot (`@rakomi/sdk-core` `MachineSnapshot`).
+ * - The HTTP client.
+ * - The `TokenRuntime` — drives the FSM, manages refresh + storage.
+ * - Deep-link callback subscription (single-use, idempotent).
+ * - AppState listener (debounced 300ms) for
+ * foreground refresh, with single in-flight Promise dedup.
+ * - Network connectivity listener for online/offline transitions.
+ *
+ * Hooks read from this context — they're thin wrappers.
+ */
+
+interface RakomiProviderProps {
+    /** Tenant publishable key — used to derive base URL + tenant ID. */
+    publishableKey: string;
+    /** API base URL. Required if `publishableKey` is dev/local. */
+    baseUrl?: string;
+    /** Custom URL scheme for OAuth callback (RFC 8252). Reverse-DNS recommended. */
+    redirectUri: string;
+    /** Override the default Expo adapter. Bare-RN consumers MUST supply this. */
+    nativeAdapter?: NativeAuthAdapter;
+    /** Sugar override: replace only storage in the default adapter. */
+    tokenCache?: TokenCache;
+    /** Enable biometric gate before reading refresh tokens. */
+    biometric?: boolean;
+    /** When `biometric: true`, disable device passcode fallback. Default false. */
+    biometricStrict?: boolean;
+    /** Localized prompt for biometric reads. */
+    biometricPrompt?: string;
+    /** iOS ephemeral session toggle. Default true. */
+    browserPreferEphemeralSession?: boolean;
+    /** JWKS TTL ceiling (≤7 days). Default 24h. */
+    offlineMaxAgeSeconds?: number;
+    /** opt-out of automatic deep-link handling. */
+    deepLinkAutoHandle?: boolean;
+    /** Typed event bus. Consumer wires telemetry. */
+    onEvent?: (event: AuthEvent) => void;
+    /** i18n locale. Default 'en'. */
+    locale?: Locale;
+    /** Translation overrides — merged onto locale dictionary. */
+    translations?: Partial<Translations>;
+    /** Override the OAuth token endpoint. Default: `<baseUrl>/oauth/token`. */
+    tokenEndpoint?: string;
+    /** Tenant identifier for storage-key derivation. Defaults to `publishableKey`. */
+    tenantId?: string;
+    children: ReactNode;
+}
+declare function RakomiProvider(props: RakomiProviderProps): ReactNode;
+
+/**
+ * `useAuth()` — RN port of `@rakomi/react`'s `useAuth`. Parity-tested at type level.
+ * Returns the same discriminated-union AuthState shape so consumer code is portable.
+ */
+
+/**
+ * Discriminated-union AuthState — identical to `@rakomi/react`'s `AuthState`.
+ *
+ * `state: AuthMachineState` is the addition.
+ */
+type AuthState = {
+    isLoaded: false;
+    isSignedIn: undefined;
+    userId: undefined;
+    user: undefined;
+    sessionId: undefined;
+    error: null;
+    state: AuthMachineState;
+    signIn: (options?: SignInOptions) => Promise<SignInResult>;
+    signOut: () => Promise<void>;
+    getToken: () => Promise<TokenResult>;
+} | {
+    isLoaded: true;
+    isSignedIn: false;
+    userId: null;
+    user: null;
+    sessionId: null;
+    error: AuthError | null;
+    state: AuthMachineState;
+    signIn: (options?: SignInOptions) => Promise<SignInResult>;
+    signOut: () => Promise<void>;
+    getToken: () => Promise<TokenResult>;
+} | {
+    isLoaded: true;
+    isSignedIn: true;
+    userId: string;
+    user: UserResource;
+    sessionId: string;
+    error: AuthError | null;
+    state: AuthMachineState;
+    isExpiringSoon: boolean;
+    has: (params: HasParams) => boolean;
+    signIn: (options?: SignInOptions) => Promise<SignInResult>;
+    signOut: () => Promise<void>;
+    getToken: () => Promise<TokenResult>;
+    switchOrganization: (orgId: string | null) => Promise<SwitchOrgResult>;
+};
+declare function useAuth(): AuthState;
+
+interface UseSessionReturn {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    session: SessionResource | null;
+}
+declare function useSession(): UseSessionReturn;
+
+interface UseUserReturn {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: UserResource | null;
+}
+declare function useUser(): UseUserReturn;
+
+/**
+ * Hook surface — parity superset of `@rakomi/react`.
+ *
+ * 0.1.0 ships these as thin reads off `RakomiContextValue` + minimal stubs that
+ * preserve the `@rakomi/react` return-shape so the parity test (`test/parity.test.ts`)
+ * passes. Full data wiring (Org list, Linked accounts, Flag eval, Branding, BaaS
+ * plans/subscriptions) lands in a future release; the public types are LOCKED.
+ */
+
+interface UseFlagOptions {
+    /** Optional default value if the flag is unknown. */
+    defaultValue?: boolean | string | number;
+    /** Optional user context override (rarely needed — provider supplies it). */
+    user?: {
+        id?: string;
+        email?: string;
+    };
+}
+interface UseFlagReturn<T = unknown> {
+    isLoaded: boolean;
+    value: T | undefined;
+    isEnabled: boolean;
+}
+declare function useFlag<T = unknown>(flag: string, options?: UseFlagOptions): UseFlagReturn<T>;
+/** The active organization context, from the `org` scope's JWT claims. */
+interface OrgContext {
+    orgId: string;
+    orgRole: string;
+    orgMemberships: OrgMembershipClaim[];
+}
+interface UseOrganizationReturn {
+    isLoaded: boolean;
+    organization: OrgContext | null;
+}
+declare function useOrganization(): UseOrganizationReturn;
+interface UseOrganizationListReturn {
+    isLoaded: boolean;
+    organizations: OrgMembershipClaim[];
+}
+declare function useOrganizationList(): UseOrganizationListReturn;
+type LinkProvider = 'google' | 'github' | 'microsoft' | 'apple' | 'discord' | 'facebook' | 'slack' | 'twitter' | 'gitlab' | 'linkedin';
+type LinkedVia = 'oauth' | 'password' | 'magic_link' | 'email_otp' | 'passkey' | 'anonymous';
+interface LinkedMethod {
+    provider: LinkProvider | 'password' | 'magic_link' | 'email_otp' | 'passkey';
+    via: LinkedVia;
+    linkedAt: string;
+}
+type LinkedMethods = LinkedMethod[];
+interface UseLinkedAccountsResult {
+    isLoaded: boolean;
+    methods: LinkedMethods;
+    link: (provider: LinkProvider) => Promise<{
+        status: 'redirect' | 'error';
+    }>;
+    unlink: (provider: LinkProvider | 'password' | 'magic_link' | 'email_otp' | 'passkey') => Promise<{
+        status: 'complete' | 'error';
+    }>;
+}
+declare function useLinkedAccounts(): UseLinkedAccountsResult;
+declare function useTranslation(): {
+    t: TranslationFn;
+    locale: string;
+};
+interface UseAuthConfigReturn {
+    isLoaded: boolean;
+    config: AuthConfig | null;
+}
+declare function useAuthConfig(): UseAuthConfigReturn;
+interface UseBrandingReturn {
+    isLoaded: boolean;
+    branding: BrandingConfig | null;
+}
+declare function useBranding(): UseBrandingReturn;
+interface UseAnonymousSigninResult {
+    isLoaded: boolean;
+    signInAnonymously: (options?: {
+        publicMetadata?: Record<string, unknown>;
+    }) => Promise<{
+        status: 'complete' | 'error';
+    }>;
+}
+declare function useAnonymousSignin(): UseAnonymousSigninResult;
+interface BaasPlanPublicItem {
+    id: string;
+    name: string;
+    price_cents: number;
+    currency: string;
+    interval: string;
+    trial_days: number | null;
+    features: string[] | null;
+}
+interface UseBaasPlansReturn {
+    isLoaded: boolean;
+    plans: BaasPlanPublicItem[];
+    error: string | null;
+}
+/**
+ * Fetch the public BaaS plan list for `tenantSlug` from `/v1/billing/baas/{slug}/public-plans`.
+ * Response is cached per `(baseUrl, tenantSlug)` for the provider lifetime.
+ */
+declare function useBaasPlans({ tenantSlug }: {
+    tenantSlug: string;
+}): UseBaasPlansReturn;
+interface BaasSubscription {
+    id: string;
+    user_id: string;
+    plan_id: string;
+    plan_name: string;
+    status: string;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    trial_end: string | null;
+    cancelled_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface UseBaasSubscriptionReturn {
+    isLoaded: boolean;
+    subscription: BaasSubscription | null;
+    error: string | null;
+}
+/**
+ * Fetch the signed-in user's BaaS subscription for `tenantSlug`. Authenticated:
+ * sends `Authorization: Bearer <accessToken>` from `getToken()`.
+ *
+ * 404 (no subscription) → `subscription: null` + `isLoaded: true` (NOT an error).
+ */
+declare function useBaasSubscription({ tenantSlug }: {
+    tenantSlug: string;
+}): UseBaasSubscriptionReturn;
+
+/**
+ * Conditional render components — RN ports of `@rakomi/react`'s
+ * `<SignedIn>`, `<SignedOut>`, `<Protect>`, `<Feature>`. Identical contracts
+ * (parity test asserts).
+ *
+ * They render a `Fragment` (no DOM/RN primitive nesting) — pure logic gates.
+ */
+
+interface SignedInProps {
+    children: ReactNode;
+}
+declare function SignedIn({ children }: SignedInProps): ReactNode;
+interface SignedOutProps {
+    children: ReactNode;
+}
+declare function SignedOut({ children }: SignedOutProps): ReactNode;
+interface ProtectProps extends HasParams {
+    children: ReactNode;
+    /** Rendered when the predicate fails. Default: nothing. */
+    fallback?: ReactNode;
+}
+declare function Protect({ children, fallback, permission, role }: ProtectProps): ReactNode;
+/**
+ * `<Feature flag="…">` — render only when a feature flag is enabled. v0.1.0 stub:
+ * checks `user.rawClaims.feature_flags?.[flag] === true`. Full wiring
+ * (`useFlag` with provider + targeting rules) lands later — surface stays stable.
+ */
+interface FeatureProps {
+    flag: string;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+declare function Feature({ flag, children, fallback }: FeatureProps): ReactNode;
+
+/**
+ * `<SignIn />` — RN port.
+ *
+ * Renders a sign-in flow using ONLY RN primitives (`<View>`, `<Text>`,
+ * `<TextInput>`, `<Pressable>`) — no HTML. Supports:
+ * - Password (direct) sign-in.
+ * - Social provider list (Google, GitHub, …) via `startSocialSignIn`.
+ * - MFA TOTP code entry view (`keyboardType="number-pad"`,
+ * `textContentType="oneTimeCode"`, `autoComplete="sms-otp"`).
+ *
+ * Accessibility:
+ * - Every interactive element has `accessibilityLabel` + `accessibilityRole`.
+ * - i18n keys come from `useRakomiContext.translate`.
+ * - `branding`/`theme` props supported.
+ */
+
+interface SignInProps {
+    /** Authorization endpoint, default `${baseUrl}/oauth/authorize`. */
+    authorizationEndpoint?: string;
+    /** Token endpoint, default `${baseUrl}/v1/auth/oauth/callback`. */
+    tokenEndpoint?: string;
+    /** MFA TOTP verify endpoint, default `${baseUrl}/v1/auth/mfa/totp/verify`. */
+    totpVerifyEndpoint?: string;
+    /** Social providers to render. Default: ['google']. */
+    providers?: string[];
+    /** OAuth scope. Default `openid profile email`. */
+    scope?: string;
+    /** Customize the rendered title. */
+    title?: string;
+    /** RN style prop. */
+    style?: any;
+}
+declare function SignIn(props: SignInProps): ReactNode;
+
+/**
+ * `<SignUp />` — RN port. Mirrors `<SignIn />`'s
+ * UX patterns; password strength scored via `@rakomi/sdk-core/scorePassword`.
+ *
+ * For 0.1.0 the registration POST is wired against the canonical
+ * `/v1/auth/register` endpoint via the injected `HttpClient`. Email-verification
+ * follow-up step (which the API returns) leaves the user on the
+ * "verification_required" view — the consumer typically renders their own
+ * confirmation copy after that.
+ */
+
+interface SignUpProps {
+    /** Registration endpoint, default `/v1/auth/register`. */
+    registerEndpoint?: string;
+    /** Optional return URL after email confirmation — validated via `isSafeUrl`. */
+    returnTo?: string;
+    style?: any;
+}
+declare function SignUp(props: SignUpProps): ReactNode;
+
+/**
+ * `<UserButton />` — RN port. Renders a tap-target showing the current user's
+ * email/initials + a sign-out action when expanded.
+ *
+ * RN primitives only.
+ */
+
+interface UserButtonProps {
+    /** Show the email next to the avatar. Default true. */
+    showName?: boolean;
+    style?: any;
+}
+declare function UserButton(props: UserButtonProps): ReactNode;
+
+/**
+ * `<UserProfile />` — RN port (PREVIEW).
+ *
+ * Marked `'preview'` until 0.2.0; on first mount in `__DEV__` builds we log a
+ * warning so consumers don't accidentally ship it to production.
+ */
+
+interface UserProfileProps {
+    style?: any;
+}
+declare function UserProfile(props: UserProfileProps): ReactNode;
+
+/** RFC 9449 / three-class client-side refresh failure taxonomy (+ network). */
+type DpopRefreshErrorClass = 'dpop_prover_unavailable' | 'invalid_dpop_proof' | 'invalid_refresh_token' | 'network';
+interface DpopRefreshError {
+    /** Stable machine token for the failure class. */
+    class: DpopRefreshErrorClass;
+    /** Full `auth/<class>` code string — parity with `@rakomi/node`'s surfacing. */
+    code: `auth/${DpopRefreshErrorClass}`;
+    message: string;
+}
+type DpopRefreshResult = {
+    ok: true;
+    tokens: OAuthTokenResponse;
+    attachedProof: boolean;
+} | {
+    ok: false;
+    error: DpopRefreshError;
+};
+
+/**
+ * Default `HttpClient` for React Native — wraps WHATWG `fetch` with the
+ * SSRF guard required by the project security rules (`redirect: 'error'`).
+ *
+ * used by all OAuth/PKCE/refresh flows. Consumers can inject a
+ * custom `HttpClient` via `nativeAdapter` for telemetry / mTLS / retry layers.
+ */
+
+interface CreateRnHttpClientOptions {
+    /** Base URL prepended to relative paths (e.g. `https://api.rakomi.com`). */
+    baseUrl?: string;
+    /** Default request timeout in ms. Default: 30_000. */
+    defaultTimeoutMs?: number;
+}
+declare function createRnHttpClient(options?: CreateRnHttpClientOptions): HttpClient;
+
+/** Default publisher replay window (seconds) and the hard max clamp. */
+declare const DEFAULT_WEBHOOK_TOLERANCE = 300;
+declare const MAX_WEBHOOK_TOLERANCE = 600;
+/** Portable webhook-verify error class — the value IS the cross-SDK conformance `error_class`. */
+type WebhookVerifyErrorClass = 'invalid_signature' | 'invalid_secret' | 'missing_header' | 'timestamp_too_old' | 'timestamp_too_new' | 'invalid_body';
+/** Open-set publisher event type (the known catalog widened with the base string for forward-compat). */
+type PublisherEventType = 'app.installed' | 'app.uninstalled' | 'app.install.scope_bump' | 'app.install.receipts_revoked' | 'publisher.created' | 'publisher.domain_verified' | 'publisher.dpa_accepted' | 'app.created' | 'app.version_published' | 'app.state_changed' | 'publisher.review_requested' | 'publisher.review_denied' | 'publisher.review_stale' | 'publisher.verified' | 'publisher.deverified' | 'publisher.subscription_activated' | 'publisher.subscription_lapsed';
+type PublisherWebhookEventType = PublisherEventType | (string & {});
+/** The flat publisher-webhook delivery body. Unknown fields tolerated (forward-compat). No end-user PII. */
+interface PublisherWebhookEvent {
+    publisher_id: string;
+    correlation_id: string;
+    installation_id?: string;
+    app_id?: string;
+    app_version_id?: string;
+    actor_axis?: string;
+    install_state_from?: string;
+    install_state_to?: string;
+    revoked_count?: number;
+    already_revoked_count?: number;
+    [key: string]: unknown;
+}
+interface PublisherWebhookVerifyData {
+    /** Stable Standard Webhooks message id — the at-least-once dedup key. */
+    webhookId: string;
+    /** Per-delivery id (diagnostics/logging). */
+    deliveryId: string;
+    /** Event type from the X-Rakomi-Event header (open set). */
+    eventType: PublisherWebhookEventType;
+    timestamp: number;
+    payload: PublisherWebhookEvent;
+}
+type WebhookVerifyResult = {
+    ok: true;
+    data: PublisherWebhookVerifyData;
+} | {
+    ok: false;
+    error: WebhookVerifyErrorClass;
+};
+type Headers = Record<string, string | string[] | undefined>;
+/**
+ * Raw generic verify (advanced use). ASYNC (WebCrypto). Never throws except when WebCrypto is entirely
+ * absent (a misconfigured runtime) — that surfaces a clear error rather than a silent mis-verify.
+ */
+declare function verifyWebhook(body: string | Uint8Array, headers: Headers, secret: string, tolerance?: number): Promise<WebhookVerifyResult>;
+/**
+ * Recommended publisher entry point. Pre-binds the 300 s window (clamped ≤600) and REJECTS a non-`rksec_`
+ * secret outright. ASYNC (WebCrypto) — `await` it. Mirrors `@rakomi/node`'s `verifyPublisherWebhook`.
+ */
+declare function verifyPublisherWebhook(body: string | Uint8Array, headers: Headers, secret: string, tolerance?: number): Promise<WebhookVerifyResult>;
+
+/**
+ * RFC 8252 OAuth flow orchestrator for React Native / Expo.
+ *
+ * system browser ONLY (`expo-web-browser.openAuthSessionAsync`).
+ * PKCE S256 mandatory. State 32 bytes, single-use, 60s TTL, constant-time compare.
+ * Confused-deputy guard: redirect URI scheme/host re-checked client-side after callback ingest.
+ *
+ * No `WebView` (codebase guard the project lint guards enforces).
+ */
+
+interface StartSocialSignInInput {
+    adapter: NativeAuthAdapter;
+    http: HttpClient;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    redirectUri: string;
+    provider: string;
+    scope?: string;
+    acrValues?: string;
+    preferEphemeralSession?: boolean;
+    /**
+   * Optional DPoP binding handle (opt-in at issuance). When supplied, a fresh RFC 9449 proof is
+   * attached to the code→token exchange so the server binds `dpop_jkt` to THIS
+   * session's native keypair; the SAME `DpopSession` must then be wired into the
+   * runtime so every refresh re-presents the bound key. Pass the session
+   * `<RakomiProvider>` auto-constructs from `NativeAuthAdapter.dpopProver`.
+   *
+   * Absent ⇒ a plain Bearer issuance (unchanged behaviour).
+   */
+    dpopSession?: DpopSession;
+}
+type SocialSignInOutcome = {
+    ok: true;
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_in: number;
+        token_type: string;
+    };
+} | {
+    ok: false;
+    error: AuthError;
+};
+/**
+ * Start a social-provider sign-in. Opens the system browser, waits for the
+ * deep-link callback, validates state + scheme, exchanges the code for tokens.
+ *
+ * Idempotent: only one OAuth ceremony can be in flight per call. Caller must
+ * serialize concurrent invocations themselves.
+ */
+declare function startSocialSignIn(input: StartSocialSignInInput): Promise<SocialSignInOutcome>;
+
+interface UsePasskeysOptions {
+    /**
+     * Override the ceremony adapter. Intended for tests (`createFakePasskeyAdapter()` from
+     * `@rakomi/sdk-core/passkeys/testing`) and for a host that builds its adapter outside the provider.
+     * When omitted, the adapter comes from `nativeAdapter.passkeys`.
+     */
+    adapter?: PasskeyCeremonyAdapter;
+}
+interface SignInWithPasskeyInput {
+    /**
+     * Identified sign-in. **An opaque, server-issued handle — NOT an email, NOT a username.** The type is
+     * branded (`OpaqueUserHandle`), so a raw string will not compile: passing a user-typed identifier here
+     * turns a usernameless flow into an account-enumeration oracle, and — because platform passkeys sync
+     * across a user's devices — can reveal which of their devices hold a credential. Omit it for the
+     * usernameless flow, which is what almost every app wants.
+     */
+    userHandle?: OpaqueUserHandle;
+}
+interface RegisterPasskeyHookInput {
+    /** Minted by `stepUpWithPasskey()` or by the password step-up endpoint. */
+    stepUpToken: string;
+    nickname?: string;
+}
+interface ListPasskeysHookInput {
+    stepUpToken: string;
+}
+interface RenamePasskeyHookInput {
+    stepUpToken: string;
+    passkeyId: string;
+    nickname: string;
+}
+interface DeletePasskeyHookInput {
+    stepUpToken: string;
+    passkeyId: string;
+}
+interface UsePasskeysResult {
+    /** `null` until the capability probe resolves. `false` means this device cannot run a ceremony. */
+    isSupported: boolean | null;
+    /** `null` until probed, and `null` also means UNKNOWN (a module that cannot answer). A UI hint for
+     * wording ("Sign in with Face ID"), never a gate. */
+    hasPlatformAuthenticator: boolean | null;
+    /** `undefined` until `listPasskeys` is called — the hook fetches nothing on mount. */
+    passkeys: PasskeySummary[] | undefined;
+    error: PasskeyError | null;
+    isSigningIn: boolean;
+    isRegistering: boolean;
+    isSteppingUp: boolean;
+    isLoading: boolean;
+    isMutating: boolean;
+    signInWithPasskey: (input?: SignInWithPasskeyInput) => Promise<AssertPasskeyResult>;
+    stepUpWithPasskey: () => Promise<StepUpWithPasskeyResult>;
+    registerPasskey: (input: RegisterPasskeyHookInput) => Promise<RegisterPasskeyResult>;
+    listPasskeys: (input: ListPasskeysHookInput) => Promise<ListPasskeysResult>;
+    renamePasskey: (input: RenamePasskeyHookInput) => Promise<PasskeySummaryResult>;
+    deletePasskey: (input: DeletePasskeyHookInput) => Promise<DeletePasskeyResult>;
+}
+declare function usePasskeys(options?: UsePasskeysOptions): UsePasskeysResult;
+
+/**
+ * `useSubmitOAuthTokens` — bridge between `startSocialSignIn` (free function) and the
+ * `<RakomiProvider>` runtime.
+ *
+ * this hook issues a fresh submit-nonce on every call (5-min TTL, single-use).
+ * The nonce is invisible to the consumer — the public surface stays a single-arg function,
+ * but the runtime is protected against arbitrary `OAuthTokenResponse` injection from
+ * third-party components.
+ *
+ * Consumer pattern:
+ * ```tsx
+ * const submit = useSubmitOAuthTokens;
+ * const outcome = await startSocialSignIn({... });
+ * if (outcome.ok) await submit(outcome.tokens);
+ * ```
+ *
+ * Calling `submit` persists the refresh token to secure storage and dispatches
+ * `SIGN_IN_SUCCESS` so `useAuth.isSignedIn` flips to `true` and `getToken` becomes available.
+ */
+
+declare function useSubmitOAuthTokens(): (tokens: OAuthTokenResponse) => Promise<void>;
+
+/**
+ * Direct-auth hooks — (magic-link, email-OTP, register).
+ *
+ * Wraps `@rakomi/sdk-core` direct-auth helpers with `useRakomiContext` wiring so
+ * consumers don't have to thread `http` / `baseUrl` / `clientId` themselves.
+ *
+ * On verify success:
+ * - `tokens` variant → calls `submitOAuthTokens` (dispatches SIGN_IN_SUCCESS).
+ * - `oauthCode` variant → caller is responsible for the code → token exchange (PKCE binding).
+ * - `mfa` variant → caller drives MFA UI; SDK does not auto-dispatch MFA_REQUIRED here
+ * (component layer owns that decision).
+ */
+
+interface UseMagicLinkResult {
+    request: (email: string) => Promise<RequestResult>;
+    verify: (token: string) => Promise<VerifyResult>;
+}
+declare function useMagicLink(): UseMagicLinkResult;
+interface UseEmailOtpResult {
+    request: (email: string, mode?: 'login' | 'login_or_create') => Promise<RequestResult>;
+    verify: (email: string, code: string) => Promise<VerifyResult>;
+}
+declare function useEmailOtp(): UseEmailOtpResult;
+interface UseRegisterResult {
+    register: (email: string, password: string) => Promise<RequestResult>;
+}
+declare function useRegister(): UseRegisterResult;
+interface UseMfaResult {
+    /**
+     * Verify a TOTP code against the MFA challenge token surfaced by `verifyMagicLink`
+     * or `verifyEmailOtp` when their result is the `mfa` variant.
+     *
+     * On success, server-issued tokens are submitted to the runtime and `SIGN_IN_SUCCESS`
+     * is dispatched. On failure, returns the error so the caller can surface it in UI.
+     */
+    verifyTotp: (challengeToken: string, code: string, endpoint?: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: AuthError;
+    }>;
+}
+declare function useMfa(): UseMfaResult;
+
+export { type AuthState, type CreateDpopSessionOptions, type CreateRnHttpClientOptions, DEFAULT_WEBHOOK_TOLERANCE, type DeletePasskeyHookInput, type DpopDowngradeInfo, DpopProver, type DpopRefreshError, type DpopRefreshErrorClass, type DpopRefreshResult, DpopSession, Feature, type FeatureProps, type LinkProvider, type LinkedMethod, type LinkedMethods, type LinkedVia, type ListPasskeysHookInput, MAX_WEBHOOK_TOLERANCE, NativeAuthAdapter, Protect, type ProtectProps, type PublisherEventType, type PublisherWebhookEvent, type PublisherWebhookEventType, type PublisherWebhookVerifyData, RakomiProvider, type RakomiProviderProps, type RegisterPasskeyHookInput, type RenamePasskeyHookInput, SignIn, type SignInProps, type SignInWithPasskeyInput, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, type SocialSignInOutcome, type StartSocialSignInInput, TokenCache, type UseAnonymousSigninResult, type UseAuthConfigReturn, type UseBaasPlansReturn, type UseBaasSubscriptionReturn, type UseBrandingReturn, type UseEmailOtpResult, type UseFlagOptions, type UseFlagReturn, type UseLinkedAccountsResult, type UseMagicLinkResult, type UseMfaResult, type UseOrganizationListReturn, type UseOrganizationReturn, type UsePasskeysOptions, type UsePasskeysResult, type UseRegisterResult, type UseSessionReturn, type UseUserReturn, UserButton, type UserButtonProps, UserProfile, type UserProfileProps, type WebhookVerifyErrorClass, type WebhookVerifyResult, createDpopSession, createRnHttpClient, startSocialSignIn, useAnonymousSignin, useAuth, useAuthConfig, useBaasPlans, useBaasSubscription, useBranding, useEmailOtp, useFlag, useLinkedAccounts, useMagicLink, useMfa, useOrganization, useOrganizationList, usePasskeys, useRegister, useSession, useSubmitOAuthTokens, useTranslation, useUser, verifyPublisherWebhook, verifyWebhook };