@atlasauth/capacitor 0.1.0

package/dist/plugins.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The Capacitor plugin surfaces this package touches — declared STRUCTURALLY so
+ * the package carries no hard dependency on any `@capacitor/*` module.
+ *
+ * `@capacitor/core`, `@capacitor/browser`, `@capacitor/app` and
+ * `@capacitor/preferences` are OPTIONAL peers the consuming app installs. So
+ * instead of `import { Browser } from '@capacitor/browser'`, we declare the
+ * minimal slice of each plugin we call and load the real module LAZILY at
+ * runtime (see {@link loadCapacitorPlugins}). At build time there is no
+ * dependency on any Capacitor package; at runtime the app's installed plugins
+ * are structurally compatible, and a web target with a plugin absent degrades
+ * gracefully rather than throwing at import.
+ *
+ * Every loader is guarded: a missing plugin resolves to `null`, never a throw,
+ * so the package runs in a bare browser (no Capacitor runtime), in Node tests,
+ * and on a device alike.
+ */
+/** The slice of `@capacitor/browser`'s `Browser` we use. */
+export interface BrowserPlugin {
+    /** Open `url` in the system browser (SFSafariViewController / Custom Tabs). */
+    open(options: {
+        url: string;
+    }): Promise<void>;
+    /** Dismiss the in-app browser, when the platform supports it. */
+    close?(): Promise<void>;
+}
+/** A Capacitor listener handle. `addListener` may return it directly or a promise of it. */
+export interface PluginListenerHandle {
+    remove(): Promise<void> | void;
+}
+/** The `appUrlOpen` event payload from `@capacitor/app`. */
+export interface AppUrlOpenEvent {
+    /** The full deep-link URL that reopened the app, e.g. `com.acme.app://cb?code=…`. */
+    url: string;
+}
+/** The slice of `@capacitor/app`'s `App` we use. */
+export interface AppPlugin {
+    addListener(eventName: 'appUrlOpen', listener: (event: AppUrlOpenEvent) => void): PluginListenerHandle | Promise<PluginListenerHandle>;
+}
+/** The slice of `@capacitor/preferences`'s `Preferences` we use. */
+export interface PreferencesPlugin {
+    get(options: {
+        key: string;
+    }): Promise<{
+        value: string | null;
+    }>;
+    set(options: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    remove(options: {
+        key: string;
+    }): Promise<void>;
+}
+/** The slice of `@capacitor/core`'s `Capacitor` we use. */
+export interface CapacitorGlobal {
+    /** True on iOS/Android, false on the web target. */
+    isNativePlatform(): boolean;
+}
+/** The Capacitor plugins a flow needs; any may be absent (web, tests). */
+export interface CapacitorPlugins {
+    Browser: BrowserPlugin | null;
+    App: AppPlugin | null;
+    Preferences: PreferencesPlugin | null;
+    Capacitor: CapacitorGlobal | null;
+}
+/**
+ * Lazily load the four Capacitor plugins, each guarded. A plugin that is not
+ * installed (or whose import fails) comes back `null`; nothing throws. Capacitor
+ * plugins export a named binding (`{ Browser }`, `{ App }`, …), so we read that
+ * off the module.
+ */
+export declare function loadCapacitorPlugins(): Promise<CapacitorPlugins>;
+/**
+ * Decide whether this is a native target. Prefers Capacitor's own
+ * `isNativePlatform()`; falls back to "no `window` ⇒ not a browser ⇒ native-ish"
+ * only when Capacitor is absent. On a plain web page (window present, no
+ * Capacitor) it returns false, so the standard redirect flow is used.
+ */
+export declare function isNativePlatform(plugins: Pick<CapacitorPlugins, 'Capacitor'>): boolean;

package/dist/plugins.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * The Capacitor plugin surfaces this package touches — declared STRUCTURALLY so
+ * the package carries no hard dependency on any `@capacitor/*` module.
+ *
+ * `@capacitor/core`, `@capacitor/browser`, `@capacitor/app` and
+ * `@capacitor/preferences` are OPTIONAL peers the consuming app installs. So
+ * instead of `import { Browser } from '@capacitor/browser'`, we declare the
+ * minimal slice of each plugin we call and load the real module LAZILY at
+ * runtime (see {@link loadCapacitorPlugins}). At build time there is no
+ * dependency on any Capacitor package; at runtime the app's installed plugins
+ * are structurally compatible, and a web target with a plugin absent degrades
+ * gracefully rather than throwing at import.
+ *
+ * Every loader is guarded: a missing plugin resolves to `null`, never a throw,
+ * so the package runs in a bare browser (no Capacitor runtime), in Node tests,
+ * and on a device alike.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCapacitorPlugins = loadCapacitorPlugins;
+exports.isNativePlatform = isNativePlatform;
+/**
+ * Dynamically import a module by specifier WITHOUT a static dependency on it.
+ *
+ * The specifier is a runtime value, so TypeScript does not resolve the module at
+ * build time (the package typechecks with no `@capacitor/*` installed) and a
+ * bundler can tree-shake/ignore it. A missing or broken module resolves to
+ * `null` rather than throwing — the caller decides how to degrade.
+ */
+async function loadModule(specifier) {
+    try {
+        return (await Promise.resolve(`${specifier}`).then(s => __importStar(require(s))));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Lazily load the four Capacitor plugins, each guarded. A plugin that is not
+ * installed (or whose import fails) comes back `null`; nothing throws. Capacitor
+ * plugins export a named binding (`{ Browser }`, `{ App }`, …), so we read that
+ * off the module.
+ */
+async function loadCapacitorPlugins() {
+    const [browserMod, appMod, prefsMod, coreMod] = await Promise.all([
+        loadModule('@capacitor/browser'),
+        loadModule('@capacitor/app'),
+        loadModule('@capacitor/preferences'),
+        loadModule('@capacitor/core'),
+    ]);
+    return {
+        Browser: browserMod?.Browser ?? null,
+        App: appMod?.App ?? null,
+        Preferences: prefsMod?.Preferences ?? null,
+        Capacitor: coreMod?.Capacitor ?? null,
+    };
+}
+/**
+ * Decide whether this is a native target. Prefers Capacitor's own
+ * `isNativePlatform()`; falls back to "no `window` ⇒ not a browser ⇒ native-ish"
+ * only when Capacitor is absent. On a plain web page (window present, no
+ * Capacitor) it returns false, so the standard redirect flow is used.
+ */
+function isNativePlatform(plugins) {
+    if (plugins.Capacitor)
+        return plugins.Capacitor.isNativePlatform();
+    return typeof window === 'undefined';
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEH,oDAaC;AAQD,4CAGC;AA9CD;;;;;;;GAOG;AACH,KAAK,UAAU,UAAU,CAAI,SAAiB;IAC5C,IAAI,CAAC;QACH,OAAO,CAAC,yBAA0D,SAAS,uCAAC,CAAM,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,oBAAoB;IACxC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChE,UAAU,CAA8B,oBAAoB,CAAC;QAC7D,UAAU,CAAsB,gBAAgB,CAAC;QACjD,UAAU,CAAsC,wBAAwB,CAAC;QACzE,UAAU,CAAkC,iBAAiB,CAAC;KAC/D,CAAC,CAAC;IACH,OAAO;QACL,OAAO,EAAE,UAAU,EAAE,OAAO,IAAI,IAAI;QACpC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI;QACxB,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,IAAI;QAC1C,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI;KACtC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,OAA4C;IAC3E,IAAI,OAAO,CAAC,SAAS;QAAE,OAAO,OAAO,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC;IACnE,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC;AACvC,CAAC"}

package/dist/sign-in.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The native-session sign-in flow for Capacitor.
+ *
+ * The shape, end to end:
+ *
+ *   1. Mint a PKCE pair + `state`, build the first-party authorize URL.
+ *   2. Open it in the SYSTEM browser (`@capacitor/browser`) — never an in-app
+ *      WebView, so the user authenticates in a trusted, cookie-bearing context.
+ *   3. The authorize response redirects to the app's custom-scheme `redirectUri`,
+ *      which reopens the app; `@capacitor/app` fires `appUrlOpen` with that URL.
+ *   4. Pull the `code` off the callback URL (after checking `state`), redeem it
+ *      for a first-party OAuth access token (PKCE `authorization_code` grant).
+ *   5. Trade that access token for a cookie-free Atlas SESSION via
+ *      {@link exchangeForSession} from `@atlasauth/js`.
+ *
+ * On the WEB target there is no deep link, so the flow falls back to the STANDARD
+ * redirect: it stashes the PKCE verifier + state and navigates the page to the
+ * authorize URL. The app finishes on the next load with
+ * {@link completeRedirectSignIn}, reading the stashed verifier.
+ *
+ * Every network step returns `null` — never throws — on failure, so a failed
+ * sign-in is "re-run the flow", mirroring `@atlasauth/js`'s native-session.
+ */
+import { type NativeSession } from '@atlasauth/js';
+import { type PkcePair } from './pkce';
+import { type AppPlugin, type BrowserPlugin, type CapacitorGlobal } from './plugins';
+import type { TokenStore } from './token-store';
+/** The default OAuth scopes requested for a first-party native sign-in. */
+export declare const DEFAULT_SCOPE = "openid profile email offline_access";
+/** The storage key the transient PKCE material is stashed under on the web path. */
+export declare const PKCE_STASH_KEY = "atlas.capacitor.pkce";
+export interface BuildAuthorizeUrlOptions {
+    /** The instance's FAPI origin, e.g. `https://fapi.acme.atlasauth.net`. */
+    frontendApi: string;
+    /** The first-party native OAuth client id. */
+    clientId: string;
+    /** The app's custom-scheme callback, e.g. `com.acme.app://auth`. */
+    redirectUri: string;
+    /** base64url(SHA-256(verifier)). */
+    codeChallenge: string;
+    /** CSRF `state` echoed back on the callback. */
+    state: string;
+    /** Space-delimited scopes. @default {@link DEFAULT_SCOPE} */
+    scope?: string;
+}
+/**
+ * Build the first-party PKCE authorize URL hit at `{frontendApi}/oauth2/authorize`.
+ * `response_type=code`, S256 challenge, space-delimited scopes.
+ */
+export declare function buildAuthorizeUrl(options: BuildAuthorizeUrlOptions): string;
+/** The outcome of reading a deep-link / redirect callback URL. */
+export type AuthCallback = {
+    code: string;
+    error?: undefined;
+} | {
+    code?: undefined;
+    error: string;
+};
+/**
+ * Read an authorization callback URL. Returns the `code` when `state` matches the
+ * value we sent, an `{ error }` when the server reported one (also state-checked),
+ * or `null` when the URL is not our callback (a foreign deep link, or a state
+ * mismatch) — the `appUrlOpen` listener fires for EVERY deep link, so a non-match
+ * must be ignored, not treated as a failure.
+ */
+export declare function parseAuthCallback(rawUrl: string, expectedState: string): AuthCallback | null;
+export interface RedeemAuthorizationCodeOptions {
+    frontendApi: string;
+    clientId: string;
+    redirectUri: string;
+    /** The `code` from the callback URL. */
+    code: string;
+    /** The PKCE verifier that matches the challenge sent on the authorize URL. */
+    codeVerifier: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Redeem an authorization code for a first-party OAuth access token via the PKCE
+ * `authorization_code` grant at `{frontendApi}/oauth2/token`. Returns the access
+ * token, or `null` — never throws — on a network failure, a non-2xx, or a body
+ * with no `access_token`.
+ */
+export declare function redeemAuthorizationCode(options: RedeemAuthorizationCodeOptions): Promise<string | null>;
+/**
+ * The flow tail shared by the native and web paths: redeem the code for an OAuth
+ * access token, then {@link exchangeForSession} it for an Atlas {@link
+ * NativeSession}. `null` at either step is `null` out — re-run the flow.
+ */
+export declare function exchangeAuthCode(options: RedeemAuthorizationCodeOptions): Promise<NativeSession | null>;
+export interface SignInWithBrowserOptions {
+    frontendApi: string;
+    clientId: string;
+    /** The app's custom-scheme callback, e.g. `com.acme.app://auth`. */
+    redirectUri: string;
+    scope?: string;
+    /** `@capacitor/browser`'s `Browser`. Required on native. */
+    browser: BrowserPlugin | null;
+    /** `@capacitor/app`'s `App`. Required on native. */
+    app: AppPlugin | null;
+    /** `@capacitor/core`'s `Capacitor`, to decide native vs web. */
+    capacitor: CapacitorGlobal | null;
+    /** Where the transient PKCE material is stashed for the WEB redirect path. */
+    pkceStore: TokenStore;
+    fetchImpl?: typeof fetch;
+    /** Navigate the page (web path). @default `window.location.assign` */
+    navigate?: (url: string) => void;
+    /** Injectable PKCE pair (tests). @default {@link createPkcePair} */
+    makePkce?: () => Promise<PkcePair>;
+    /** Injectable state (tests). @default {@link createState} */
+    makeState?: () => string;
+}
+/**
+ * The outcome of {@link signInWithBrowser}. On native it carries the completed
+ * session; on the web redirect path it carries `pending: true` (the page is
+ * navigating away — the app finishes with {@link completeRedirectSignIn} on the
+ * next load), never a session.
+ */
+export type SignInOutcome = {
+    session: NativeSession;
+    pending?: false;
+} | {
+    session: null;
+    pending: true;
+} | {
+    session: null;
+    pending?: false;
+};
+/**
+ * Run the sign-in flow. On NATIVE: open the system browser, wait for the
+ * `appUrlOpen` deep link, complete the exchange, resolve the session. On WEB:
+ * stash the PKCE verifier + state and navigate to the authorize URL (standard
+ * redirect) — resolves `{ session: null, pending: true }`, and the app completes
+ * via {@link completeRedirectSignIn}.
+ */
+export declare function signInWithBrowser(options: SignInWithBrowserOptions): Promise<SignInOutcome>;
+export interface CompleteRedirectSignInOptions {
+    frontendApi: string;
+    clientId: string;
+    redirectUri: string;
+    /** The redirect URL the web app landed on (carries `code` + `state`). */
+    url: string;
+    /** The same store {@link signInWithBrowser} stashed the PKCE material in. */
+    pkceStore: TokenStore;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Finish the WEB redirect flow. Reads the stashed PKCE verifier + state, checks
+ * the callback URL against them, redeems + exchanges, and clears the stash.
+ * Returns `null` when there is nothing to complete (no stash, not our callback,
+ * or a failed exchange). Call it once on app load when the URL looks like a
+ * callback.
+ */
+export declare function completeRedirectSignIn(options: CompleteRedirectSignInOptions): Promise<NativeSession | null>;

package/dist/sign-in.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * The native-session sign-in flow for Capacitor.
+ *
+ * The shape, end to end:
+ *
+ *   1. Mint a PKCE pair + `state`, build the first-party authorize URL.
+ *   2. Open it in the SYSTEM browser (`@capacitor/browser`) — never an in-app
+ *      WebView, so the user authenticates in a trusted, cookie-bearing context.
+ *   3. The authorize response redirects to the app's custom-scheme `redirectUri`,
+ *      which reopens the app; `@capacitor/app` fires `appUrlOpen` with that URL.
+ *   4. Pull the `code` off the callback URL (after checking `state`), redeem it
+ *      for a first-party OAuth access token (PKCE `authorization_code` grant).
+ *   5. Trade that access token for a cookie-free Atlas SESSION via
+ *      {@link exchangeForSession} from `@atlasauth/js`.
+ *
+ * On the WEB target there is no deep link, so the flow falls back to the STANDARD
+ * redirect: it stashes the PKCE verifier + state and navigates the page to the
+ * authorize URL. The app finishes on the next load with
+ * {@link completeRedirectSignIn}, reading the stashed verifier.
+ *
+ * Every network step returns `null` — never throws — on failure, so a failed
+ * sign-in is "re-run the flow", mirroring `@atlasauth/js`'s native-session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PKCE_STASH_KEY = exports.DEFAULT_SCOPE = void 0;
+exports.buildAuthorizeUrl = buildAuthorizeUrl;
+exports.parseAuthCallback = parseAuthCallback;
+exports.redeemAuthorizationCode = redeemAuthorizationCode;
+exports.exchangeAuthCode = exchangeAuthCode;
+exports.signInWithBrowser = signInWithBrowser;
+exports.completeRedirectSignIn = completeRedirectSignIn;
+const js_1 = require("@atlasauth/js");
+const pkce_1 = require("./pkce");
+const plugins_1 = require("./plugins");
+/** The default OAuth scopes requested for a first-party native sign-in. */
+exports.DEFAULT_SCOPE = 'openid profile email offline_access';
+/** The storage key the transient PKCE material is stashed under on the web path. */
+exports.PKCE_STASH_KEY = 'atlas.capacitor.pkce';
+/**
+ * Build the first-party PKCE authorize URL hit at `{frontendApi}/oauth2/authorize`.
+ * `response_type=code`, S256 challenge, space-delimited scopes.
+ */
+function buildAuthorizeUrl(options) {
+    const url = new URL('/oauth2/authorize', options.frontendApi);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', options.clientId);
+    url.searchParams.set('redirect_uri', options.redirectUri);
+    url.searchParams.set('scope', options.scope ?? exports.DEFAULT_SCOPE);
+    url.searchParams.set('state', options.state);
+    url.searchParams.set('code_challenge', options.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    return url.toString();
+}
+/**
+ * Read an authorization callback URL. Returns the `code` when `state` matches the
+ * value we sent, an `{ error }` when the server reported one (also state-checked),
+ * or `null` when the URL is not our callback (a foreign deep link, or a state
+ * mismatch) — the `appUrlOpen` listener fires for EVERY deep link, so a non-match
+ * must be ignored, not treated as a failure.
+ */
+function parseAuthCallback(rawUrl, expectedState) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return null;
+    }
+    // A custom-scheme URL may carry its params in the query OR the fragment.
+    const params = url.searchParams;
+    const state = params.get('state');
+    if (state !== expectedState)
+        return null;
+    const error = params.get('error');
+    if (error)
+        return { error };
+    const code = params.get('code');
+    return code ? { code } : null;
+}
+/**
+ * Redeem an authorization code for a first-party OAuth access token via the PKCE
+ * `authorization_code` grant at `{frontendApi}/oauth2/token`. Returns the access
+ * token, or `null` — never throws — on a network failure, a non-2xx, or a body
+ * with no `access_token`.
+ */
+async function redeemAuthorizationCode(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const form = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: options.clientId,
+        redirect_uri: options.redirectUri,
+        code: options.code,
+        code_verifier: options.codeVerifier,
+    });
+    let response;
+    try {
+        response = await doFetch(`${options.frontendApi}/oauth2/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!response.ok)
+        return null;
+    let body = null;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        return null;
+    }
+    return body && typeof body.access_token === 'string' ? body.access_token : null;
+}
+/**
+ * The flow tail shared by the native and web paths: redeem the code for an OAuth
+ * access token, then {@link exchangeForSession} it for an Atlas {@link
+ * NativeSession}. `null` at either step is `null` out — re-run the flow.
+ */
+async function exchangeAuthCode(options) {
+    const accessToken = await redeemAuthorizationCode(options);
+    if (!accessToken)
+        return null;
+    return (0, js_1.exchangeForSession)({
+        baseUrl: options.frontendApi,
+        clientId: options.clientId,
+        accessToken,
+        fetchImpl: options.fetchImpl,
+    });
+}
+/** Resolve a listener handle whether `addListener` returned it or a promise of it. */
+async function resolveHandle(handle) {
+    return await Promise.resolve(handle);
+}
+/**
+ * Run the sign-in flow. On NATIVE: open the system browser, wait for the
+ * `appUrlOpen` deep link, complete the exchange, resolve the session. On WEB:
+ * stash the PKCE verifier + state and navigate to the authorize URL (standard
+ * redirect) — resolves `{ session: null, pending: true }`, and the app completes
+ * via {@link completeRedirectSignIn}.
+ */
+async function signInWithBrowser(options) {
+    const makePkce = options.makePkce ?? pkce_1.createPkcePair;
+    const makeState = options.makeState ?? pkce_1.createState;
+    const pkce = await makePkce();
+    const state = makeState();
+    const authorizeUrl = buildAuthorizeUrl({
+        frontendApi: options.frontendApi,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        codeChallenge: pkce.challenge,
+        state,
+        scope: options.scope,
+    });
+    const native = (0, plugins_1.isNativePlatform)({ Capacitor: options.capacitor });
+    if (!native) {
+        // Web: stash the verifier + state so the next page load can finish, then
+        // navigate. The page is about to unload, so there is no session to return.
+        await options.pkceStore.setToken(JSON.stringify({ verifier: pkce.verifier, state }));
+        const navigate = options.navigate ??
+            ((url) => {
+                if (typeof window !== 'undefined')
+                    window.location.assign(url);
+            });
+        navigate(authorizeUrl);
+        return { session: null, pending: true };
+    }
+    if (!options.browser || !options.app) {
+        // Native target but a required plugin is missing — nothing to open.
+        return { session: null };
+    }
+    const browser = options.browser;
+    const app = options.app;
+    // Register the deep-link listener BEFORE opening the browser, so a very fast
+    // callback cannot race ahead of the handler.
+    const code = await new Promise((resolve) => {
+        let settled = false;
+        let handle = null;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            void handle?.remove();
+            void browser.close?.();
+            resolve(value);
+        };
+        void resolveHandle(app.addListener('appUrlOpen', (event) => {
+            const parsed = parseAuthCallback(event.url, state);
+            if (!parsed)
+                return; // not our callback — ignore foreign deep links.
+            finish(parsed.code ?? null);
+        })).then((h) => {
+            handle = h;
+            // If the flow already finished during handle setup, drop the listener now.
+            if (settled)
+                void h.remove();
+        });
+        browser.open({ url: authorizeUrl }).catch(() => finish(null));
+    });
+    if (!code)
+        return { session: null };
+    const session = await exchangeAuthCode({
+        frontendApi: options.frontendApi,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        code,
+        codeVerifier: pkce.verifier,
+        fetchImpl: options.fetchImpl,
+    });
+    return session ? { session } : { session: null };
+}
+/**
+ * Finish the WEB redirect flow. Reads the stashed PKCE verifier + state, checks
+ * the callback URL against them, redeems + exchanges, and clears the stash.
+ * Returns `null` when there is nothing to complete (no stash, not our callback,
+ * or a failed exchange). Call it once on app load when the URL looks like a
+ * callback.
+ */
+async function completeRedirectSignIn(options) {
+    const raw = await options.pkceStore.getToken();
+    if (!raw)
+        return null;
+    let stash = null;
+    try {
+        stash = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!stash || typeof stash.verifier !== 'string' || typeof stash.state !== 'string') {
+        return null;
+    }
+    const parsed = parseAuthCallback(options.url, stash.state);
+    if (!parsed || !parsed.code)
+        return null;
+    const session = await exchangeAuthCode({
+        frontendApi: options.frontendApi,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        code: parsed.code,
+        codeVerifier: stash.verifier,
+        fetchImpl: options.fetchImpl,
+    });
+    // Single-use: clear the stash whether or not the exchange succeeded.
+    await options.pkceStore.clearToken();
+    return session;
+}
+//# sourceMappingURL=sign-in.js.map

package/dist/sign-in.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-in.js","sourceRoot":"","sources":["../src/sign-in.ts"],"names":[],"mappings":"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"}

package/dist/token-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The Capacitor session token store.
+ *
+ * The web SDK keeps its short-lived JWT in memory and lets the browser carry the
+ * refresh token in an HttpOnly cookie. A Capacitor app — a WebView with no cookie
+ * jar against the FAPI origin — has to put the session somewhere the app chooses,
+ * and WHERE it lives is a security decision this SDK must not make for the app.
+ *
+ * So the SDK depends only on the small {@link TokenStore} interface below (the
+ * same three-method shape the `@atlasauth/js` native-session manager persists
+ * through) and ships two adapters: an in-memory default and a
+ * `@capacitor/preferences` one. `@capacitor/preferences` is an OPTIONAL peer, so
+ * its surface is declared structurally ({@link PreferencesPlugin}) and the app
+ * passes the real plugin in — the package compiles, typechecks and tests without
+ * it installed.
+ *
+ * ⚠️ `@capacitor/preferences` is NOT encrypted at rest (UserDefaults /
+ * SharedPreferences). For production, back the store with a secure-storage
+ * community plugin — e.g. `@capacitor-community/secure-storage` or
+ * `capacitor-secure-storage-plugin` — behind this same {@link TokenStore}
+ * interface. See {@link createPreferencesTokenStore} for the drop-in shape.
+ */
+import type { PreferencesPlugin } from './plugins';
+/**
+ * A single-slot token store: read, write, clear one string value. This is the
+ * exact contract the `@atlasauth/js` {@link NativeSessionManager} persists the
+ * serialized session through (its `persist` hook writes, boot reads, sign-out
+ * clears). Every method may be sync or async, so an in-memory store and an async
+ * `@capacitor/preferences` store both fit.
+ */
+export interface TokenStore {
+    /** The stored value, or null when absent. */
+    getToken(): string | null | Promise<string | null>;
+    /** Persist `value`. Called on every successful sign-in / refresh. */
+    setToken(value: string): void | Promise<void>;
+    /** Drop the stored value (sign-out, or a rejected session). */
+    clearToken(): void | Promise<void>;
+}
+/** The default key the serialized native session is stored under. */
+export declare const DEFAULT_SESSION_KEY = "atlas.native_session";
+/**
+ * Build a {@link TokenStore} backed by `@capacitor/preferences`, keyed by `key`.
+ * The app imports the plugin and passes it in — the SDK never imports
+ * `@capacitor/preferences` itself, so it stays an optional peer:
+ *
+ * ```ts
+ * import { Preferences } from '@capacitor/preferences';
+ * import { createPreferencesTokenStore } from '@atlasauth/capacitor';
+ *
+ * const store = createPreferencesTokenStore(Preferences);
+ * ```
+ *
+ * Preferences is plaintext at rest; swap a secure-storage plugin behind this same
+ * interface for production (see the module header).
+ */
+export declare function createPreferencesTokenStore(preferences: PreferencesPlugin, key?: string): TokenStore;
+/**
+ * A process-memory {@link TokenStore}. The zero-config default so the SDK runs
+ * out of the box in tests and prototypes — but it does NOT survive an app
+ * restart, so ship {@link createPreferencesTokenStore} (or a secure-storage
+ * adapter) in production.
+ */
+export declare function createInMemoryTokenStore(): TokenStore;