@authowl/react-native 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,654 @@
+import { PublicConfig, NativeAuthClient, NativePasskeyCapableClient, PasskeyCeremonyClientFactory, NativeSocialSignInOptions, AuthActionResult, SocialAuthData, AuthUser, AuthSession, HasParams, SessionState, Organization, PasskeyRegistrationResponse, PasskeyAuthenticationResponse } from '@authowl/core/native';
+export { AuthSession, AuthUser, HasParams, NativeAuthClient, NativeSocialSignInOptions, OrganizationMembership, SessionState, NativeSocialSignInOptions as SocialIdTokenSignInOptions, sessionCookieName } from '@authowl/core/native';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Locale, ServerErrorInput, MessageKey, MessageParams } from '@authowl/core/i18n';
+export { Locale, MessageKey, MessageParams } from '@authowl/core/i18n';
+
+/**
+ * Where a native app keeps its session.
+ *
+ * The session cookie is a bearer credential: anything holding it IS the signed-in
+ * user until it expires. On a phone that means the OS keychain / keystore, not
+ * AsyncStorage, which is plain unencrypted files any process with the sandbox
+ * can read. `@authowl/expo` supplies an `expo-secure-store` adapter; bare React
+ * Native apps typically use `react-native-keychain`.
+ */
+interface SecureStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * An in-memory store, for tests and for previews where persistence is unwanted.
+ *
+ * Explicitly NOT a default: silently falling back to memory would make sign-in
+ * appear to work and then drop the session on the next app launch, which is a
+ * confusing bug to chase. Callers must choose their storage.
+ */
+declare class MemoryStorage implements SecureStorage {
+    private readonly entries;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/** Building the AuthOwl client for a native app. */
+
+interface AuthOwlNativeConfig {
+    /** The project's `pk_live_…` / `pk_test_…` key. Secret keys are refused. */
+    publishableKey: string;
+    /** The AuthOwl API origin, e.g. `https://api.authowl.dev`. */
+    apiUrl: string;
+    /** Where the session cookie is persisted. Use the OS keychain in production. */
+    storage: SecureStorage;
+    /** Defaults to the global fetch. Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    /** Called after any action that mutates the session. */
+    onSessionMutation?: () => void;
+    /**
+     * Platform passkey ceremony, from `createNativePasskeys()`.
+     *
+     * Omit it and the passkey methods are absent from the client's TYPE, so an
+     * app cannot call a prompt the runtime could never show.
+     */
+    passkeys?: PasskeyCeremonyClientFactory;
+}
+interface AuthOwlNativeConfigWithPasskeys extends AuthOwlNativeConfig {
+    passkeys: PasskeyCeremonyClientFactory;
+}
+interface AuthOwlNativeBase {
+    projectId: string;
+    getPublicConfig: () => Promise<PublicConfig>;
+}
+interface AuthOwlNative extends AuthOwlNativeBase {
+    client: NativeAuthClient | NativePasskeyCapableClient;
+}
+interface AuthOwlPasskeyNative extends AuthOwlNativeBase {
+    client: NativePasskeyCapableClient;
+}
+interface AuthOwlHeadlessNative extends AuthOwlNativeBase {
+    client: NativeAuthClient;
+}
+/**
+ * Build a native AuthOwl client with session persistence wired up.
+ *
+ * The publishable key is decoded up front so a `sk_` key fails HERE, loudly, at
+ * startup - rather than being shipped inside an app binary where it cannot be
+ * rotated out of users' hands.
+ */
+declare function createAuthOwlNative(config: AuthOwlNativeConfigWithPasskeys): AuthOwlPasskeyNative;
+declare function createAuthOwlNative(config: AuthOwlNativeConfig & {
+    passkeys?: undefined;
+}): AuthOwlHeadlessNative;
+declare function createAuthOwlNative(config: AuthOwlNativeConfig): AuthOwlNative;
+
+/**
+ * A one-cookie jar backed by secure storage.
+ *
+ * Why this exists: the AuthOwl server authenticates with a session COOKIE, and
+ * the browser SDK simply lets the browser's cookie jar do the work. React Native
+ * has no dependable equivalent - its `fetch` cookie behaviour differs between
+ * iOS and Android, is invisible to JS, and does not reliably survive an app
+ * restart or update. So the native SDK keeps the one cookie it cares about
+ * itself: replay it on every request, and re-capture it whenever the server
+ * rotates it.
+ *
+ * This talks to the server exactly as the browser does, so no server-side
+ * "native mode" is required.
+ */
+
+interface CookieJarOptions {
+    /** Where the session cookie is persisted. */
+    storage: SecureStorage;
+    /** The project id, used to derive the exact cookie name the server sets. */
+    projectId: string;
+    /**
+     * Whether the server issues `__Secure-` cookies. Derive it from the API URL's
+     * scheme (`https:` => true) - it must match the SERVER, not the client.
+     */
+    secure: boolean;
+    /** Defaults to the global fetch. Injectable for tests. */
+    fetchImpl?: typeof fetch;
+}
+/** The storage key under which the raw cookie value is kept. */
+declare function sessionStorageKey(projectId: string): string;
+/**
+ * Parse the cookie value the server set for `name`, if this response sets it.
+ *
+ * Deliberately hand-rolled and narrow: it looks for ONE cookie by exact name and
+ * ignores every attribute (`Path`, `HttpOnly`, `SameSite`, …). A general cookie
+ * jar would have to model domains and paths, which is a large amount of surface
+ * for a client that only ever talks to one origin.
+ *
+ * Returns `null` when the response does not set the cookie, and the empty string
+ * when the server clears it (sign-out), which the caller treats as a deletion.
+ */
+declare function readSetCookie(header: readonly string[] | string | null, name: string): string | null;
+/**
+ * Wrap `fetch` so the session cookie is replayed from, and captured into,
+ * secure storage.
+ */
+declare function createCookieJarFetch(options: CookieJarOptions): typeof fetch;
+
+/** Native social sign-in through a provider-issued ID token. */
+
+/**
+ * Exchange an ID token obtained from a provider's native SDK for an AuthOwl
+ * session. The cookie jar captures the session cookie from this same response,
+ * so no browser-cookie bridge or deep-link credential is required.
+ */
+declare function signInWithSocialIdToken(client: NativeAuthClient, options: NativeSocialSignInOptions): Promise<AuthActionResult<SocialAuthData>>;
+
+/** React context and hooks for a native AuthOwl app. */
+
+type PublicConfigState = 'loading' | 'ready' | 'error';
+interface AuthOwlProviderProps extends AuthOwlNativeConfig {
+    children?: ReactNode;
+    /**
+     * Locale for the built-in components. Defaults to English.
+     *
+     * Not auto-detected from the device: a phone set to Arabic does not imply the
+     * app is localized to Arabic, and silently switching the auth screens away
+     * from the rest of the app is worse than defaulting. Pass the locale the app
+     * has already resolved.
+     */
+    locale?: Locale;
+}
+/** Provides the AuthOwl client to a native React tree. */
+declare function AuthOwlProvider(props: AuthOwlProviderProps): ReactNode;
+/** The locale the provider resolved, for the built-in components. */
+declare function useAuthOwlLocale(): Locale;
+/** Native-safe sign-in, account, organization, and passkey-management actions. */
+declare function useAuthOwlClient(): NativeAuthClient | NativePasskeyCapableClient;
+/** Project capabilities and legal policy used by the built-in components. */
+declare function usePublicConfig(): {
+    data: PublicConfig | null;
+    state: PublicConfigState;
+    isLoading: boolean;
+};
+/** The live session state, re-rendering whenever the session changes. */
+declare function useSession(): SessionState;
+interface UseAuthResult {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: AuthUser | null;
+    session: AuthSession | null;
+    signOut: () => Promise<void>;
+    /**
+     * Advisory permission check over the CURRENT session claim.
+     *
+     * Advisory only: this is for hiding UI the user cannot use. The real boundary
+     * is server-side, over a verified token - never gate anything that matters on
+     * a client-side answer.
+     */
+    has: (params: HasParams) => boolean;
+    hasPermission: (params: {
+        permission: string;
+    }) => boolean;
+}
+/** The primary hook: who is signed in, and what may they do. */
+declare function useAuth(): UseAuthResult;
+/** The signed-in user, or null. */
+declare function useUser(): AuthUser | null;
+/** Exchange an ID token from a provider's native SDK for an AuthOwl session. */
+declare function useSocialSignIn(): (options: NativeSocialSignInOptions) => Promise<AuthActionResult<SocialAuthData>>;
+
+/**
+ * Visual tokens for the built-in components.
+ *
+ * Deliberately small and overridable rather than a full theming engine: an app
+ * that wants its own look should compose the headless hooks, not fight a
+ * cascade. These exist so the drop-in screens look deliberate out of the box.
+ */
+interface AuthOwlTheme {
+    accent: string;
+    accentText: string;
+    /** Readable inline-link color; defaults to `accent` for custom themes. */
+    link?: string;
+    text: string;
+    mutedText: string;
+    background: string;
+    surface: string;
+    border: string;
+    danger: string;
+    radius: number;
+    spacing: number;
+}
+declare const defaultTheme: AuthOwlTheme;
+declare const darkTheme: AuthOwlTheme;
+/** Build the stylesheet for a theme. Memoize per theme at the call site. */
+declare function createStyles(theme: AuthOwlTheme): {
+    container: {
+        gap: number;
+        backgroundColor: string;
+    };
+    title: {
+        fontSize: number;
+        fontWeight: string;
+        color: string;
+    };
+    label: {
+        fontSize: number;
+        fontWeight: string;
+        color: string;
+    };
+    field: {
+        gap: number;
+    };
+    input: {
+        borderWidth: number;
+        borderColor: string;
+        borderRadius: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        fontSize: number;
+        color: string;
+        backgroundColor: string;
+    };
+    inputInvalid: {
+        borderColor: string;
+    };
+    button: {
+        borderRadius: number;
+        paddingVertical: number;
+        alignItems: string;
+        backgroundColor: string;
+    };
+    buttonDisabled: {
+        opacity: number;
+    };
+    buttonText: {
+        color: string;
+        fontSize: number;
+        fontWeight: string;
+    };
+    link: {
+        color: string;
+        fontSize: number;
+    };
+    consentRow: {
+        flexDirection: string;
+        alignItems: string;
+        gap: number;
+    };
+    consentToggle: {
+        minWidth: number;
+        height: number;
+        alignItems: string;
+        justifyContent: string;
+    };
+    consentBox: {
+        width: number;
+        height: number;
+        alignItems: string;
+        justifyContent: string;
+        borderWidth: number;
+        borderColor: string;
+        borderRadius: number;
+        backgroundColor: string;
+    };
+    consentBoxChecked: {
+        borderColor: string;
+        backgroundColor: string;
+    };
+    consentBoxDisabled: {
+        opacity: number;
+    };
+    consentCheck: {
+        color: string;
+        fontSize: number;
+        fontWeight: string;
+        lineHeight: number;
+    };
+    consentText: {
+        flex: number;
+        color: string;
+        fontSize: number;
+        lineHeight: number;
+    };
+    consentLink: {
+        color: string;
+        textDecorationLine: string;
+    };
+    error: {
+        color: string;
+        fontSize: number;
+    };
+};
+
+interface SignInProps {
+    /** Called once a session exists. */
+    onSignedIn?: () => void;
+    /** Called when valid credentials require an MFA challenge before a session exists. */
+    onSecondFactorRequired?: () => void;
+    /** Rendered as a link under the form, when provided. */
+    onForgotPassword?: () => void;
+    theme?: AuthOwlTheme;
+}
+/**
+ * Email and password sign-in.
+ *
+ * Social sign-in is intentionally NOT rendered here. It needs a provider ID
+ * token from a native SDK the app has to configure itself, so a button that
+ * cannot work without that wiring would be a broken affordance. Use
+ * `useSocialSignIn()` alongside this screen.
+ */
+declare function SignIn({ onSignedIn, onSecondFactorRequired, onForgotPassword, theme, }: SignInProps): react.JSX.Element | null;
+
+interface SignUpProps {
+    /**
+     * Called when sign-up succeeds.
+     *
+     * `sessionCreated` is false when the project requires email verification
+     * first. The caller decides what happens next, because "check your email" and
+     * "you are signed in" are different screens.
+     */
+    onSignedUp?: (result: {
+        sessionCreated: boolean;
+    }) => void;
+    /** Collect first and last name instead of a single display name. */
+    structuredName?: boolean;
+    theme?: AuthOwlTheme;
+}
+/** Create an account with an email address and password. */
+declare function SignUp({ onSignedUp, structuredName, theme }: SignUpProps): react.JSX.Element | null;
+
+interface EmailOtpFormProps {
+    onSignedIn?: () => void;
+    theme?: AuthOwlTheme;
+}
+/**
+ * Two stages in one screen: request a code, then verify it.
+ *
+ * Kept together because the second stage is meaningless without the address
+ * entered in the first, and splitting them across screens loses that context on
+ * a back navigation.
+ */
+declare function EmailOtpForm({ onSignedIn, theme }: EmailOtpFormProps): react.JSX.Element;
+
+interface OrganizationSwitcherProps {
+    /** Called after the active organization changes, including to personal. */
+    onSwitched?: (organization: Organization | null) => void;
+    /**
+     * Offer a "personal account" row that clears the active organization.
+     * Off by default: many apps require an organization context to function.
+     */
+    allowPersonal?: boolean;
+    theme?: AuthOwlTheme;
+}
+/**
+ * Lists the caller's organizations and switches between them.
+ *
+ * Reads the ACTIVE organization from the session rather than tracking it
+ * locally. Switching re-mints the session claim server-side, so local state
+ * would be a second source of truth that drifts the moment anything else
+ * changes the active org.
+ */
+declare function OrganizationSwitcher({ onSwitched, allowPersonal, theme, }: OrganizationSwitcherProps): react.JSX.Element | null;
+
+interface PasskeyEnrollmentProps {
+    /** Suggested credential name, shown in the platform's list. */
+    name?: string;
+    onEnrolled?: () => void;
+    /** Rendered as a skip link when provided. */
+    onSkip?: () => void;
+    theme?: AuthOwlTheme;
+}
+/**
+ * Offer to create a passkey.
+ *
+ * Renders nothing without a passkey adapter, so it is safe to drop into a
+ * post-sign-up flow that also runs on projects with passkeys disabled.
+ */
+declare function PasskeyEnrollment({ name, onEnrolled, onSkip, theme, }: PasskeyEnrollmentProps): react.JSX.Element | null;
+interface PasskeySignInButtonProps {
+    onSignedIn?: () => void;
+    theme?: AuthOwlTheme;
+}
+/** Sign in with an already-enrolled passkey. */
+declare function PasskeySignInButton({ onSignedIn, theme, }: PasskeySignInButtonProps): react.JSX.Element | null;
+
+/**
+ * Platform passkeys on a phone.
+ *
+ * React Native has no `navigator.credentials`, but both platforms do have
+ * passkey APIs - `ASAuthorization` on iOS, Credential Manager on Android - and
+ * the community libraries (`react-native-passkey`, `expo-passkeys`) speak the
+ * same WebAuthn JSON the server already emits. So the app supplies the ceremony
+ * and the SDK keeps the protocol: option decoding, response projection, and the
+ * in-flight de-duplication all come from `@authowl/core`.
+ *
+ * The adapter is the app's because the native libraries differ, need native
+ * builds, and require associated-domain configuration the SDK cannot do on the
+ * app's behalf.
+ */
+
+/** The platform passkey calls an app must provide. */
+interface NativePasskeyAdapter {
+    /**
+     * Run the platform's registration ceremony.
+     *
+     * `optionsJSON` is the server's WebAuthn creation options; return the
+     * credential the platform produced. Throw to signal cancellation or failure.
+     */
+    register(optionsJSON: unknown): Promise<PasskeyRegistrationResponse>;
+    /** Run the platform's authentication ceremony. */
+    authenticate(optionsJSON: unknown): Promise<PasskeyAuthenticationResponse>;
+    /**
+     * Optional: map a platform failure to a stable code.
+     *
+     * Without it a cancelled prompt is reported as a generic ceremony error. iOS
+     * and Android both surface cancellation distinctly, and users cancel far more
+     * often than anything actually breaks, so implementing this is worth it.
+     */
+    errorCode?(error: unknown): string | undefined;
+}
+/**
+ * Adapt a platform passkey library into the factory `@authowl/core` expects.
+ *
+ * Pass the result as `passkeys` to `<AuthOwlProvider>`; without it the passkey
+ * ceremony is absent from the client's type entirely, so an app cannot call a
+ * prompt that would fail.
+ */
+declare function createNativePasskeys(adapter: NativePasskeyAdapter): PasskeyCeremonyClientFactory;
+
+/** An ID token obtained from a provider's native SDK. */
+interface ProviderIdToken {
+    token: string;
+    accessToken?: string;
+    nonce?: string;
+}
+interface SocialProvider {
+    /** The provider id AuthOwl knows, e.g. `google` or `apple`. */
+    id: string;
+    /** Display name, interpolated into the localized button label. */
+    label: string;
+    /**
+     * Run the provider's native sign-in and return its ID token.
+     *
+     * Return `null` when the user cancels. The app owns this because the native
+     * SDKs differ per provider and per platform, and bundling one would force
+     * every consumer to carry it - `google_sign_in`, `expo-apple-authentication`,
+     * and friends stay the app's dependency, not the SDK's.
+     */
+    getIdToken: () => Promise<ProviderIdToken | null>;
+}
+interface SocialButtonsProps {
+    providers: readonly SocialProvider[];
+    onSignedIn?: () => void;
+    theme?: AuthOwlTheme;
+}
+/**
+ * One button per provider.
+ *
+ * Redirect OAuth is not an option here: it completes inside a system browser
+ * whose cookie jar this client cannot read, so the session would land somewhere
+ * the app can never see it. ID-token exchange is the only native flow that
+ * actually establishes a session.
+ */
+declare function SocialButtons({ providers, onSignedIn, theme, }: SocialButtonsProps): react.JSX.Element | null;
+
+declare function useStyles(theme?: AuthOwlTheme): {
+    container: {
+        gap: number;
+        backgroundColor: string;
+    };
+    title: {
+        fontSize: number;
+        fontWeight: string;
+        color: string;
+    };
+    label: {
+        fontSize: number;
+        fontWeight: string;
+        color: string;
+    };
+    field: {
+        gap: number;
+    };
+    input: {
+        borderWidth: number;
+        borderColor: string;
+        borderRadius: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        fontSize: number;
+        color: string;
+        backgroundColor: string;
+    };
+    inputInvalid: {
+        borderColor: string;
+    };
+    button: {
+        borderRadius: number;
+        paddingVertical: number;
+        alignItems: string;
+        backgroundColor: string;
+    };
+    buttonDisabled: {
+        opacity: number;
+    };
+    buttonText: {
+        color: string;
+        fontSize: number;
+        fontWeight: string;
+    };
+    link: {
+        color: string;
+        fontSize: number;
+    };
+    consentRow: {
+        flexDirection: string;
+        alignItems: string;
+        gap: number;
+    };
+    consentToggle: {
+        minWidth: number;
+        height: number;
+        alignItems: string;
+        justifyContent: string;
+    };
+    consentBox: {
+        width: number;
+        height: number;
+        alignItems: string;
+        justifyContent: string;
+        borderWidth: number;
+        borderColor: string;
+        borderRadius: number;
+        backgroundColor: string;
+    };
+    consentBoxChecked: {
+        borderColor: string;
+        backgroundColor: string;
+    };
+    consentBoxDisabled: {
+        opacity: number;
+    };
+    consentCheck: {
+        color: string;
+        fontSize: number;
+        fontWeight: string;
+        lineHeight: number;
+    };
+    consentText: {
+        flex: number;
+        color: string;
+        fontSize: number;
+        lineHeight: number;
+    };
+    consentLink: {
+        color: string;
+        textDecorationLine: string;
+    };
+    error: {
+        color: string;
+        fontSize: number;
+    };
+};
+interface FieldProps {
+    label: string;
+    value: string;
+    onChangeText: (value: string) => void;
+    theme?: AuthOwlTheme;
+    placeholder?: string;
+    secure?: boolean;
+    invalid?: boolean;
+    editable?: boolean;
+    testID?: string;
+    autoComplete?: string;
+    keyboardType?: string;
+    maxLength?: number;
+    onSubmitEditing?: () => void;
+}
+/** A labelled text input. */
+declare function Field({ label, value, onChangeText, theme, placeholder, secure, invalid, editable, testID, autoComplete, keyboardType, maxLength, onSubmitEditing, }: FieldProps): react.JSX.Element;
+interface SubmitButtonProps {
+    label: string;
+    busyLabel: string;
+    onPress: () => void;
+    busy?: boolean;
+    disabled?: boolean;
+    theme?: AuthOwlTheme;
+    testID?: string;
+}
+/** The primary action, with its own busy state. */
+declare function SubmitButton({ label, busyLabel, onPress, busy, disabled, theme, testID, }: SubmitButtonProps): react.JSX.Element;
+/**
+ * An error message.
+ *
+ * Announced politely so a screen reader reports a failed sign-in without
+ * interrupting whatever the user is doing.
+ */
+declare function FormError({ message, theme, testID, }: {
+    message: string | null;
+    theme?: AuthOwlTheme;
+    testID?: string;
+}): react.JSX.Element | null;
+
+/**
+ * Localization for the React Native components.
+ *
+ * Reads the SAME catalogs the web components use (`@authowl/core/i18n`). That
+ * is a hard rule, not a convenience: a second catalog is how an Arabic string
+ * silently stops matching between the web app and the phone app.
+ */
+
+/** Translate a catalog key in the active locale. */
+declare function useT(): (key: MessageKey, params?: MessageParams) => string;
+/** The active locale and its writing direction. */
+declare function useLocale(): {
+    locale: Locale;
+    direction: 'ltr' | 'rtl';
+};
+/**
+ * Turn a server failure into a localized sentence.
+ *
+ * Falls back to the generic message rather than surfacing a raw server string:
+ * an untranslated backend error in the middle of an Arabic sign-in screen is
+ * both a leak and a UX failure.
+ */
+declare function useServerError(): (error: ServerErrorInput | null | undefined, fallback: MessageKey) => string;
+
+export { type AuthOwlHeadlessNative, type AuthOwlNative, type AuthOwlNativeConfig, type AuthOwlNativeConfigWithPasskeys, type AuthOwlPasskeyNative, AuthOwlProvider, type AuthOwlProviderProps, type AuthOwlTheme, type CookieJarOptions, EmailOtpForm, type EmailOtpFormProps, Field, type FieldProps, FormError, MemoryStorage, type NativePasskeyAdapter, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeyEnrollment, type PasskeyEnrollmentProps, PasskeySignInButton, type PasskeySignInButtonProps, type ProviderIdToken, type PublicConfigState, type SecureStorage, SignIn, type SignInProps, SignUp, type SignUpProps, SocialButtons, type SocialButtonsProps, type SocialProvider, SubmitButton, type SubmitButtonProps, type UseAuthResult, createAuthOwlNative, createCookieJarFetch, createNativePasskeys, createStyles, darkTheme, defaultTheme, readSetCookie, sessionStorageKey, signInWithSocialIdToken, useAuth, useAuthOwlClient, useAuthOwlLocale, useLocale, usePublicConfig, useServerError, useSession, useSocialSignIn, useStyles, useT, useUser };