@byokit/accounts 0.1.0 → 0.2.1

package/README.md

@@ -1,8 +1,13 @@
 # @byokit/accounts
 
-Sign in with the AI plan you already pay for (ChatGPT, OpenRouter; Grok and GitHub Copilot on request), inside your
-own app, into your app's own store. Built on Pi's [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
-sign-in flows, pinned exactly.
+Sign in with the AI plan you already pay for (ChatGPT on every platform; OpenRouter on computers; Grok and GitHub
+Copilot hidden by default), inside your own app, into your app's own store: on a computer (Node, Electron), in a browser
+(a PWA, Electron's renderer) and on a
+phone (React Native and Expo, iOS and Android). One import; your bundler picks the platform's side
+(`package.json`'s `react-native` and `browser` conditions).
+
+On a computer it uses Pi's [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) sign-in
+flows, pinned exactly:
 
 ```ts
 import { isolate } from '@byokit/accounts/isolate'; // first, before any Pi import
@@ -15,18 +20,59 @@ const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: '
 (await accounts.status(1, 'chatgpt')).words;                     // "ChatGPT is connected."
 ```
 
+On a phone or in a browser the same `Accounts` signs in to ChatGPT by device code with `fetch` alone (Pi's flows need
+Node), into the phone's secure storage or the browser's IndexedDB:
+
+```ts
+import * as SecureStore from 'expo-secure-store';
+import { Accounts, secureStore } from '@byokit/accounts';
+
+const accounts = new Accounts({ store: (member) => secureStore(SecureStore, `byokit.${member}`) });
+const shown = await accounts.login(1, 'chatgpt'); // { state: 'waiting', via: 'code', code, url }: open url, show code
+```
+
+Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Android emulator sign-in) and
+[`examples/pwa`](../../examples/pwa) (browser sign-in).
+
+## Which sign-in works where
+
+| | Computer (Node, Electron main) | Browser (PWA, Electron renderer) | Phone (React Native: iOS, Android) |
+|---|---|---|---|
+| ChatGPT | Its own page, straight back to this computer (port 1455); a code when asked or stuck | Device code | Device code |
+| OpenRouter | Its own page, back to this computer (Pi's flow) | Not yet | Not yet |
+| Grok, Copilot (hidden) | Pi's flows | No | No |
+| Where sign-ins are kept | `fileStore(path)`, sealed with Electron's `safeStorage` when given | `browserStore(name)` (IndexedDB) | `secureStore(SecureStore, name)` (Keychain, Keystore) |
+
+Device code works everywhere: OpenAI's sign-in endpoints answer any web page. The page-straight-back sign-in needs a
+listener on the computer the browser runs on, so it is desktop only: ChatGPT sends the browser back to
+`localhost:1455`, fixed for the client this signs in as. A web page can't call ChatGPT's model endpoint itself (it
+doesn't answer other web pages), so a PWA's model calls go through the app's own server or relay.
+
 - **Catalogue** (`catalogue.json`): each provider with its terms status (`allowed`, `grey`, `partner`), a one-line reason
-  and a source. The kit labels; your app decides what to offer (`new Accounts({ offer: ['chatgpt', 'grok'] })`).
-  Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
-- **Sign-in**: the provider's own page by default. For ChatGPT, whose page returns to this computer's port 1455, the kit
-  listens there itself, so the tab shows your app's words (`new Accounts({ app: 'My App' })`) and only once they are
+  and a source. The kit labels; your app decides what to offer (`new Accounts({ offer: ['chatgpt'] })`). Without an
+  explicit `offer`, only sign-ins supported on this platform are shown; an explicit list is not platform-filtered, so
+  choose from the table above. Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
+- **Sign-in**: on computers, the provider's own page by default. For ChatGPT, whose page returns to this computer's
+  port 1455, the kit listens there itself, so the tab shows your app's words (`new Accounts({ app: 'My App' })`) and only once they are
   true. A code takes over when asked ("Having trouble?"), when the page never comes back, or when the port is taken by
   another sign-in. A 15-minute cap, nothing kept unless the engine can use it, and every failure is one plain sentence
   (`words.json`) with a `why` for apps that word it themselves. `plan(member)` tells a work ChatGPT from a personal one.
-- **One person, one store**: `memoryStore()` or `fileStore(path)` (0600, the same shape as Pi's `auth.json`). Never a
-  shared fallback. Using another engine with the same seam (Pi's coding-agent `ModelRuntime`)? Override `open(member)`.
+- **Sign-out**: `logout(member, key)` attempts to revoke a ChatGPT token at OpenAI (`POST auth.openai.com/oauth/revoke`),
+  then deletes the local sign-in even if the revoke fails. A failed revoke rejects after local deletion; report it because
+  the remote sign-in may remain active. Within one store instance, a refresh already in progress finishes first, so
+  sign-out uses its rotated token. If a cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its
+  discarded credential (or it is logged when no handler is set).
+- **One person, one store**: `memoryStore()`, `fileStore(path)` (0600, the same shape as Pi's `auth.json`),
+  `secureStore(SecureStore, name)` or `browserStore(name)`; any other storage with `recordStore(load, save)`. Writes are
+  serialized within a store instance; `browserStore` also uses Web Locks across tabs for the same provider when available.
+  Never a shared fallback. Browser storage is readable by scripts on your page: avoid untrusted scripts. Using another
+  engine with the same seam (Pi's coding-agent `ModelRuntime`)? Override `open(member)` with an engine whose
+  `credentialStore` is made with `boundStore(member, engineStore)` and whose `readCredential(id)` reads that store.
 - **Limits**: `failed(member, key, error)` rests an account until the provider said (or a default), marks a plan that
   doesn't include this use, and signs out only a sign-in that no longer refreshes. `ladder()` picks the next usable
   account; `keepFresh()` refreshes ahead of expiry. Limits come from errors only; no undocumented usage endpoint is read.
 - **Isolation**: ambient discovery is off (no environment variable or credential file is ever consulted), and
   `@byokit/accounts/testing` has the decoy-HOME harness and fs tracer to prove it in your own tests.
+- **A stand-in OpenAI**: `mockOpenAI()` from `@byokit/accounts/testing` (or `node .../testing/mock-openai.ts [port]`)
+  answers device code, its page where a person types the code, token exchange, refresh and revoke, so tests and demos
+  sign in end to end with no account. Point the kit at it with `new Accounts({ authBase })`.

package/dist/accounts.d.ts

@@ -1,9 +1,16 @@
 import type { CredentialStore, Models } from '@earendil-works/pi-ai';
 import { type Provider } from './catalogue.ts';
 import { type Kind } from './limits.ts';
+import { type EndingStore } from './stores.ts';
 import { type Why } from './words.ts';
 /** What signing in needs from an engine: Pi's `Models`, or anything shaped like it (the coding agent's `ModelRuntime`). */
-export type AuthHost = Pick<Models, 'login' | 'logout' | 'checkAuth' | 'getAuth'>;
+type BoundStore = CredentialStore & {
+    signOut: (id: string, p: Provider) => Promise<void>;
+};
+export type AuthHost = Pick<Models, 'login' | 'logout' | 'checkAuth' | 'getAuth'> & {
+    readCredential: CredentialStore['read'];
+    credentialStore: BoundStore;
+};
 export type Member = string | number;
 /** What the person sees while signing in: the provider's own page to open (`via: 'browser'`), or a code to type there
  *  (`via: 'code'`), never the engine's own prompts. `why` names how a failed one failed, for apps that word it themselves. */
@@ -23,6 +30,21 @@ export type Status = {
     until?: number;
     words: string;
 };
+/** Listens on this computer for the provider's page coming back: each request's path in, the page to answer with out. */
+export type Loopback = (port: number, handle: (path: string) => Promise<{
+    status: number;
+    html: string;
+}>) => Promise<{
+    close(): void;
+}>;
+/** What differs by platform: the engine that signs in, which providers it can, and (on a computer) a loopback listener. */
+export type Platform = {
+    engine: (credentials: CredentialStore, authBase?: string) => AuthHost;
+    signsIn: (pi: string) => boolean;
+    loopback?: Loopback;
+};
+/** Phones and browsers: ChatGPT by device code, no listener. */
+export declare const portable: Platform;
 export type AccountsOptions<M extends Member = Member> = {
     /** The accounts this app offers, in order. Default: every provider not hidden (ChatGPT, OpenRouter). */
     offer?: readonly string[];
@@ -36,6 +58,10 @@ export type AccountsOptions<M extends Member = Member> = {
     redirectMs?: number;
     /** Listen here for the provider's redirect instead of its fixed port (tests, so they never meet a real sign-in). */
     callbackPort?: number;
+    /** Where OpenAI's sign-in lives, for a stand-in in tests and demos (`mockOpenAI()` from `@byokit/accounts/testing`).
+     *  Phones and browsers sign in and sign out there; on a computer Pi's engine always calls OpenAI, and only sign-out's
+     *  revoke goes here. */
+    authBase?: string;
 };
 /** The ChatGPT plan behind a sign-in, from its own token: a work plan (Business, Enterprise, Edu) follows the employer's rules. */
 export declare function planOf(access: string): {
@@ -48,6 +74,10 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     private opts;
     private runtimes;
     private stores;
+    private generations;
+    private signals;
+    private chains;
+    private signingOut;
     private flows;
     private ready;
     private lapsed;
@@ -60,9 +90,15 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     onSignedIn?: (member: M, key: string) => void;
     /** Said once when a sign-in can no longer be refreshed. */
     onExpired?: (member: M, key: string) => void;
-    constructor(opts?: AccountsOptions<M>);
+    onSignOutError?: (member: M, key: string, error: Error) => void;
+    private platform;
+    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    constructor(opts?: AccountsOptions<M>, platform?: Platform);
     /** A member's own store. */
-    protected store(member: M): CredentialStore;
+    protected store(member: M): EndingStore;
+    private serial;
+    protected boundStore(member: M, raw: CredentialStore): BoundStore;
+    protected engine(member: M, raw: CredentialStore): Promise<R>;
     /** A member's engine, holding only their own sign-ins (`store(member)`). Override to use another engine with the same seam. */
     protected open(member: M): Promise<R>;
     runtime(member: M): Promise<R>;
@@ -115,12 +151,16 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     paste(member: M, key: string, text: string): void;
     /** Stop a sign-in and forget it; nothing it started is kept. */
     cancel(member: M, key: string): void;
+    private refreshed;
     /** Refresh every signed-in account an hour ahead of expiry (call it now and then), so a sign-in never lapses while
      *  nobody is looking. Only the provider refusing signs it out, and `onExpired` says so once; a network hiccup doesn't. */
     keepFresh(members: readonly M[]): Promise<void>;
     /** After the account turned a request away: true if its sign-in still refreshes; if not, it is signed out for good. */
     recheck(member: M, key: string): Promise<boolean>;
+    /** Signs out here, and at the provider too where it can end a sign-in (ChatGPT), best effort: the sign-in is deleted
+     *  here whatever the provider answers. */
     logout(member: M, key: string): Promise<void>;
     view(member: M, key: string): SignIn | null;
     stop(): void;
 }
+export {};

package/dist/accounts.js

@@ -1,29 +1,38 @@
-// Sign in with the AI plan you already pay for, one person at a time, into that person's own store. Sharing one
-// person's plan breaks the vendors' terms, so every sign-in, rest and refresh is keyed by member and account.
-// Pi's own sign-in flows do the work; the app only shows the provider's page to open or the code to type.
-import { createServer } from 'node:http';
-import { builtinModels } from '@earendil-works/pi-ai/providers/all';
 import { offered, provider } from "./catalogue.js";
-import { emptyAuthContext } from "./isolate.js";
+import { claims, PORTABLE, portableEngine } from "./engine.js";
 import { classify, REST_MS } from "./limits.js";
 import { memoryStore } from "./stores.js";
 import { callbackPage, clock, failure, say, signInError } from "./words.js";
+/** Phones and browsers: ChatGPT by device code, no listener. */
+export const portable = { engine: (c, base) => portableEngine(c, { base }), signsIn: (pi) => PORTABLE.includes(pi) };
 /** The ChatGPT plan behind a sign-in, from its own token: a work plan (Business, Enterprise, Edu) follows the employer's rules. */
 export function planOf(access) {
-    let claims = {};
+    let c = {};
     try {
-        claims = JSON.parse(Buffer.from(access.split('.')[1] ?? '', 'base64url').toString());
+        c = claims(access);
     }
     catch { }
-    const plan = String(claims['https://api.openai.com/auth']?.chatgpt_plan_type ?? '').toLowerCase();
-    return { plan, email: String(claims['https://api.openai.com/profile']?.email ?? claims.email ?? ''), work: /^(team|business|enterprise|edu|education|k12)/.test(plan) };
+    const plan = String(c['https://api.openai.com/auth']?.chatgpt_plan_type ?? '').toLowerCase();
+    return { plan, email: String(c['https://api.openai.com/profile']?.email ?? c.email ?? ''), work: /^(team|business|enterprise|edu|education|k12)/.test(plan) };
 }
 const offline = (e) => failure(String(e?.message)) === 'offline';
+/** Ends a sign-in on the provider's side, as Codex's own logout does (openai/codex#17825): the refresh token, else the
+ *  access token, never retried (fixtures/conformance/revoke.json). */
+async function revoke(url, clientId, c) {
+    const body = c.refresh ? { token: c.refresh, token_type_hint: 'refresh_token', client_id: clientId } : { token: c.access, token_type_hint: 'access_token' };
+    const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(10_000) });
+    if (!response.ok)
+        throw new Error(`ChatGPT sign-out failed (${response.status})`);
+}
 export class Accounts {
     providers;
     opts;
     runtimes = new Map();
     stores = new Map();
+    generations = new Map();
+    signals = new WeakMap();
+    chains = new Map();
+    signingOut = new Map();
     flows = new Map();
     ready = new Map();
     lapsed = new Set();
@@ -36,18 +45,126 @@ export class Accounts {
     onSignedIn;
     /** Said once when a sign-in can no longer be refreshed. */
     onExpired;
-    constructor(opts = {}) { this.opts = opts; this.providers = offered(opts.offer); }
+    onSignOutError;
+    platform;
+    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    constructor(opts = {}, platform = portable) {
+        this.opts = opts;
+        this.platform = platform;
+        this.providers = opts.offer ? offered(opts.offer) : offered().filter((p) => platform.signsIn(p.pi));
+    }
     /** A member's own store. */
     store(member) {
         let s = this.stores.get(String(member));
-        if (!s)
-            this.stores.set(String(member), s = (this.opts.store ?? memoryStore)(member));
+        if (!s) {
+            const base = (this.opts.store ?? memoryStore)(member);
+            let chain = Promise.resolve();
+            const serial = (fn) => { const result = chain.then(fn); chain = result.catch(() => { }); return result; };
+            s = {
+                read: (id) => base.read(id),
+                list: () => base.list(),
+                modify: (id, fn, options) => serial(() => base.modify(id, fn, options)),
+                delete: (id, options) => serial(() => base.delete(id, options)),
+                end: (id, fn) => serial(async () => {
+                    if (typeof base.end === 'function')
+                        return base.end(id, fn);
+                    try {
+                        await fn(await base.read(id));
+                    }
+                    finally {
+                        await base.delete(id);
+                    }
+                }),
+            };
+            this.stores.set(String(member), s);
+        }
         return s;
     }
-    /** A member's engine, holding only their own sign-ins (`store(member)`). Override to use another engine with the same seam. */
-    open(member) {
-        return Promise.resolve(builtinModels({ credentials: this.store(member), authContext: emptyAuthContext }));
+    async serial(id, fn) {
+        const previous = this.chains.get(id) ?? Promise.resolve();
+        const work = previous.then(fn, fn);
+        const tail = work.then(() => { }, () => { });
+        this.chains.set(id, tail);
+        try {
+            return await work;
+        }
+        finally {
+            if (this.chains.get(id) === tail)
+                this.chains.delete(id);
+        }
     }
+    boundStore(member, raw) {
+        const key = (id) => `${member}:${this.providers.find((p) => p.pi === id)?.key ?? id}`;
+        return {
+            read: (id, options) => raw.read(id, options),
+            list: (options) => raw.list(options),
+            modify: (id, fn, options) => {
+                const account = key(id);
+                const stale = Symbol();
+                const started = options?.signal ? this.signals.get(options.signal) ?? this.generations.get(account) ?? 0 : this.generations.get(account) ?? 0;
+                const discard = async (next) => {
+                    const p = this.providers.find((p) => p.pi === id);
+                    if (next?.type === 'oauth' && p?.revoke) {
+                        try {
+                            await revoke(this.opts.authBase ? `${this.opts.authBase}/oauth/revoke` : p.revoke, p.clientId, next);
+                        }
+                        catch (e) {
+                            const error = e instanceof Error ? e : new Error(String(e));
+                            if (this.onSignOutError)
+                                this.onSignOutError(member, p.key, error);
+                            else
+                                console.error(`sign-out ${p.key} for member ${member}:`, error);
+                            throw error;
+                        }
+                    }
+                };
+                return this.serial(account, async () => {
+                    if (started !== (this.generations.get(account) ?? 0)) {
+                        await discard(await fn(undefined));
+                        return undefined;
+                    }
+                    try {
+                        return await raw.modify(id, async (current) => {
+                            const next = await fn(current);
+                            if (started !== (this.generations.get(account) ?? 0)) {
+                                await discard(next);
+                                throw stale;
+                            }
+                            return next;
+                        }, options);
+                    }
+                    catch (e) {
+                        if (e === stale)
+                            return undefined;
+                        throw e;
+                    }
+                });
+            },
+            delete: (id, options) => this.serial(key(id), () => raw.delete(id, options)),
+            signOut: (id, p) => this.serial(key(id), async () => {
+                let error;
+                try {
+                    const c = await raw.read(id);
+                    if (c?.type === 'oauth')
+                        await revoke(this.opts.authBase ? `${this.opts.authBase}/oauth/revoke` : p.revoke, p.clientId, c);
+                }
+                catch (e) {
+                    error = e;
+                }
+                await raw.delete(id);
+                if (error)
+                    throw error;
+            }),
+        };
+    }
+    engine(member, raw) {
+        const credentials = this.boundStore(member, raw);
+        return Promise.resolve(Object.assign(this.platform.engine(credentials, this.opts.authBase), {
+            credentialStore: credentials, readCredential: (id) => credentials.read(id),
+        }));
+    }
+    /** A member's engine, holding only their own sign-ins (`store(member)`). Override to use another engine with the same seam. */
+    open(member) { return this.engine(member, this.store(member)); }
     runtime(member) {
         let r = this.runtimes.get(String(member));
         if (!r)
@@ -70,7 +187,7 @@ export class Accounts {
     }
     /** Which ChatGPT the member signed in with: its plan, email, and whether it is a work account. Null when not signed in. */
     async plan(member) {
-        const c = await this.store(member).read(this.offer('chatgpt').pi).catch(() => undefined);
+        const c = await (await this.runtime(member)).readCredential(this.offer('chatgpt').pi).catch(() => undefined);
         return c?.type === 'oauth' ? planOf(c.access) : null;
     }
     /** Whether the member's plan lacks this use; `on` records what the provider said, or that the person changed plans. */
@@ -144,6 +261,9 @@ export class Accounts {
     async login(member, key, body = {}) {
         this.offer(key);
         const id = `${member}:${key}`;
+        const pending = this.signingOut.get(id);
+        if (pending)
+            await pending.catch(() => { });
         const now = this.flows.get(id);
         if (now?.state === 'waiting' && body.via === 'code' && now.via === 'browser') {
             // "Having trouble?": the same sign-in carries on with a code instead.
@@ -152,7 +272,8 @@ export class Accounts {
             await Promise.race([visible, now.done]);
         }
         else if (now?.state !== 'waiting') {
-            const flow = { state: 'waiting', abort: new AbortController() };
+            const flow = { state: 'waiting', abort: new AbortController(), generation: this.generations.get(id) ?? 0 };
+            this.signals.set(flow.abort.signal, flow.generation);
             this.flows.set(id, flow);
             const visible = new Promise((r) => (flow.shown = r));
             flow.done = this.signIn(member, key, body, flow);
@@ -207,7 +328,7 @@ export class Accounts {
         const stuck = setTimeout(() => this.toCode(flow), this.opts.redirectMs ?? 3 * 60_000);
         // Listen where the provider sends the browser back (the engine then finds the port taken and waits to be handed the address).
         const port = p.callbackPort && (this.opts.callbackPort ?? p.callbackPort);
-        const catcher = port && body.via !== 'code' ? await this.catchRedirect(flow, p.name, port).catch(() => null) : undefined;
+        const catcher = port && body.via !== 'code' && this.platform.loopback ? await this.catchRedirect(this.platform.loopback, flow, p.name, port).catch(() => null) : undefined;
         try {
             if (catcher === null)
                 throw Object.assign(new Error('port busy'), { why: 'busy' });
@@ -220,14 +341,16 @@ export class Accounts {
                     throw e;
                 Object.assign(flow, { url: undefined, code: undefined, via: 'code' });
                 catcher?.close();
-                catcher?.closeIdleConnections();
                 await attempt('code');
             }
-            // Never half signed in: only a sign-in the engine can use counts.
+            if (flow.generation !== (this.generations.get(id) ?? 0) || flow.state !== 'waiting')
+                return;
             if (!(await rt.checkAuth(p.pi).catch(() => undefined))) {
                 await rt.logout(p.pi).catch(() => { });
                 throw new Error('no usable credential');
             }
+            if (flow.generation !== (this.generations.get(id) ?? 0) || flow.state !== 'waiting')
+                return;
             flow.state = 'done';
             this.ready.set(id, true);
             for (const s of [this.lapsed, this.without])
@@ -248,34 +371,31 @@ export class Accounts {
             clearTimeout(timer);
             clearTimeout(stuck);
             catcher?.close();
-            catcher?.closeIdleConnections();
             this.onChange?.(member, key);
         }
     }
     /** Listen where the provider sends the browser back; rejects if something else on this computer already listens there. */
-    catchRedirect(flow, name, port) {
+    catchRedirect(loopback, flow, name, port) {
         const app = this.opts.app ?? 'the app';
-        const server = createServer(async (req, res) => {
-            const q = new URL(req.url ?? '/', 'http://localhost').searchParams;
-            // No keep-alive: a browser must never land on a listener from an earlier try.
-            const page = (status, words, close = false) => { res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', connection: 'close' }); res.end(callbackPage(this.opts.app ?? name, words, close)); };
+        const page = (status, words, close = false) => ({ status, html: callbackPage(this.opts.app ?? name, words, close) });
+        return loopback(port, async (path) => {
+            const q = new URL(path, 'http://localhost').searchParams;
             if (!flow.oauthState || q.get('state') !== flow.oauthState || flow.state !== 'waiting')
                 return page(400, say('callback.outOfDate', { app, name }));
             if (q.get('error'))
                 flow.refuse?.(new Error(q.get('error')));
             // The engine only reads the query; the address it expects is the provider's registered one, on its fixed port.
             else
-                flow.paste?.(`http://localhost:${port}${req.url}`);
+                flow.paste?.(`http://localhost:${port}${path}`);
             // The tab waits for the real outcome (a few seconds at most), so it never says "signed in" before it is.
-            await Promise.race([flow.done, new Promise((r) => setTimeout(r, 30_000).unref())]);
+            await Promise.race([flow.done, new Promise((r) => setTimeout(r, 30_000).unref?.())]);
             const end = flow.state;
             if (end === 'done')
                 return page(200, say('callback.done', { app }), true);
             if (flow.why === 'declined')
                 return page(200, say('callback.declined', { app }), true);
-            page(200, end === 'failed' ? say('callback.failed', { app, error: flow.error ?? '' }) : say('callback.nearly', { app }));
+            return page(200, end === 'failed' ? say('callback.failed', { app, error: flow.error ?? '' }) : say('callback.nearly', { app }));
         });
-        return new Promise((resolve, reject) => { server.once('error', reject).listen(port, '127.0.0.1', () => resolve(server)); });
     }
     /** The redirect address (or a code) pasted back, for when the browser couldn't return to this computer by itself. */
     paste(member, key, text) {
@@ -295,6 +415,17 @@ export class Accounts {
         this.flows.delete(`${member}:${key}`);
         this.onChange?.(member, key);
     }
+    async refreshed(member, key, minOAuthValidityMs) {
+        const pi = this.offer(key).pi;
+        return (await this.runtime(member)).getAuth(pi, { minOAuthValidityMs }).then(Boolean, async (e) => {
+            if (offline(e))
+                return true;
+            if (e?.message !== `OAuth refresh returned a token that expires too soon for ${pi}`)
+                return false;
+            const c = await this.store(member).read(pi);
+            return c?.type === 'oauth' && c.expires > Date.now();
+        });
+    }
     /** Refresh every signed-in account an hour ahead of expiry (call it now and then), so a sign-in never lapses while
      *  nobody is looking. Only the provider refusing signs it out, and `onExpired` says so once; a network hiccup doesn't. */
     async keepFresh(members) {
@@ -302,7 +433,7 @@ export class Accounts {
             for (const p of this.providers) {
                 if (this.ready.get(`${m}:${p.key}`) !== true)
                     continue;
-                const ok = await (await this.runtime(m)).getAuth(p.pi, { minOAuthValidityMs: 60 * 60_000 }).then(Boolean, offline);
+                const ok = await this.refreshed(m, p.key, 60 * 60_000);
                 if (!ok) {
                     this.forget(m, p.key);
                     this.onExpired?.(m, p.key);
@@ -311,17 +442,45 @@ export class Accounts {
     }
     /** After the account turned a request away: true if its sign-in still refreshes; if not, it is signed out for good. */
     async recheck(member, key) {
-        const ok = await (await this.runtime(member)).getAuth(this.offer(key).pi, { minOAuthValidityMs: 365 * 86_400_000 }).then(Boolean, offline);
+        const ok = await this.refreshed(member, key, 365 * 86_400_000);
         if (!ok) {
             await this.logout(member, key).catch(() => { });
             this.forget(member, key);
         }
         return ok;
     }
+    /** Signs out here, and at the provider too where it can end a sign-in (ChatGPT), best effort: the sign-in is deleted
+     *  here whatever the provider answers. */
     async logout(member, key) {
-        await (await this.runtime(member)).logout(this.offer(key).pi);
-        this.ready.set(`${member}:${key}`, false);
-        this.onChange?.(member, key);
+        const p = this.offer(key);
+        const id = `${member}:${key}`;
+        this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
+        this.cancel(member, key);
+        const work = (async () => {
+            const rt = await this.runtime(member);
+            let error;
+            try {
+                if (p.revoke)
+                    await rt.credentialStore.signOut(p.pi, p);
+                else
+                    await rt.logout(p.pi);
+            }
+            catch (e) {
+                error = e;
+            }
+            this.ready.set(id, false);
+            this.onChange?.(member, key);
+            if (error)
+                throw error;
+        })();
+        this.signingOut.set(id, work);
+        try {
+            await work;
+        }
+        finally {
+            if (this.signingOut.get(id) === work)
+                this.signingOut.delete(id);
+        }
     }
     view(member, key) {
         const f = this.flows.get(`${member}:${key}`);

package/dist/catalogue.d.ts

@@ -1,5 +1,6 @@
 export type Terms = 'allowed' | 'grey' | 'partner' | 'forbidden';
-/** `callbackPort`: where the provider sends the browser back after its own sign-in page, fixed for the client Pi signs in as. */
+/** `callbackPort`: where the provider sends the browser back after its own sign-in page, fixed for the client Pi signs in as.
+ *  `revoke`: where signing out ends the sign-in on the provider's side too, for the client `clientId`. */
 export type Provider = {
     key: string;
     pi: string;
@@ -10,6 +11,8 @@ export type Provider = {
         fast?: string;
     };
     callbackPort?: number;
+    clientId?: string;
+    revoke?: string;
     terms: Terms;
     hidden: boolean;
     why: string;

package/dist/catalogue.json

@@ -8,6 +8,8 @@
             "fast": "gpt-6-luna"
         },
         "callbackPort": 1455,
+        "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
+        "revoke": "https://auth.openai.com/oauth/revoke",
         "terms": "grey",
         "hidden": false,
         "why": "Signs in through Codex's own sign-in. OpenAI documents it for Codex, not for other apps, and has endorsed one other app using it.",

package/dist/engine.d.ts

@@ -0,0 +1,30 @@
+import type { CredentialStore, OAuthCredential } from '@earendil-works/pi-ai';
+import type { AuthHost } from './accounts.ts';
+/** The Pi provider ids this engine signs in to. */
+export declare const PORTABLE: string[];
+/** A JWT's claims, on any platform (no Buffer). */
+export declare function claims(token: string): any;
+export declare function deviceStart(status: number, body: string): {
+    deviceAuthId: string;
+    userCode: string;
+    intervalSeconds: number;
+};
+export type Poll = {
+    status: 'complete';
+    authorizationCode: string;
+    codeVerifier: string;
+} | {
+    status: 'pending' | 'slow_down';
+} | {
+    status: 'failed';
+    message: string;
+};
+export declare function devicePoll(status: number, body: string): Poll;
+/** A token response as the stored credential, the same shape Pi keeps. */
+export declare function credentialOf(j: any, now?: number): OAuthCredential;
+export type EngineOptions = {
+    /** Where OpenAI's sign-in lives; a stand-in for tests and demos (`mockOpenAI()` from `@byokit/accounts/testing`). */
+    base?: string;
+};
+/** A member's engine on phones and in browsers: ChatGPT's device-code sign-in, refresh and sign-out, into `credentials`. */
+export declare function portableEngine(credentials: CredentialStore, { base }?: EngineOptions): AuthHost;

package/dist/engine.js

@@ -0,0 +1,167 @@
+const CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+const CODE_LIVES_S = 15 * 60;
+/** The Pi provider ids this engine signs in to. */
+export const PORTABLE = ['openai-codex'];
+/** A JWT's claims, on any platform (no Buffer). */
+export function claims(token) {
+    const b64 = (token.split('.')[1] ?? '').replace(/-/g, '+').replace(/_/g, '/');
+    return JSON.parse(decodeURIComponent(atob(b64).replace(/[\s\S]/g, (c) => '%' + c.charCodeAt(0).toString(16).padStart(2, '0'))));
+}
+const json = (body) => { try {
+    return JSON.parse(body);
+}
+catch {
+    return undefined;
+} };
+export function deviceStart(status, body) {
+    if (status === 404)
+        throw new Error('OpenAI Codex device code login is not enabled for this server. Use browser login or verify the server URL.');
+    if (status < 200 || status > 299)
+        throw new Error(`OpenAI Codex device code request failed with status ${status}`);
+    const j = json(body);
+    const intervalSeconds = typeof j?.interval === 'string' ? Number(j.interval.trim()) : j?.interval;
+    if (!j?.device_auth_id || !j.user_code || typeof intervalSeconds !== 'number' || !Number.isFinite(intervalSeconds) || intervalSeconds < 0)
+        throw new Error('Invalid OpenAI Codex device code response');
+    return { deviceAuthId: String(j.device_auth_id), userCode: String(j.user_code), intervalSeconds };
+}
+export function devicePoll(status, body) {
+    if (status >= 200 && status <= 299) {
+        const j = json(body);
+        return j?.authorization_code && j.code_verifier
+            ? { status: 'complete', authorizationCode: j.authorization_code, codeVerifier: j.code_verifier }
+            : { status: 'failed', message: 'Invalid OpenAI Codex device auth token response' };
+    }
+    if (status === 403 || status === 404)
+        return { status: 'pending' };
+    const error = json(body)?.error;
+    const code = typeof error === 'object' ? error?.code : error;
+    if (code === 'deviceauth_authorization_pending')
+        return { status: 'pending' };
+    if (code === 'slow_down')
+        return { status: 'slow_down' };
+    const detail = code === 'deviceauth_expired' || code === 'access_denied' ? `: ${code}` : '';
+    return { status: 'failed', message: `OpenAI Codex device auth failed with status ${status}${detail}` };
+}
+/** A token response as the stored credential, the same shape Pi keeps. */
+export function credentialOf(j, now = Date.now()) {
+    if (typeof j?.access_token !== 'string' || typeof j.refresh_token !== 'string' || typeof j.expires_in !== 'number')
+        throw new Error('OpenAI Codex token response missing fields');
+    let accountId;
+    try {
+        accountId = claims(j.access_token)['https://api.openai.com/auth']?.chatgpt_account_id;
+    }
+    catch { }
+    if (typeof accountId !== 'string' || !accountId)
+        throw new Error('Failed to extract accountId from token');
+    return { type: 'oauth', access: j.access_token, refresh: j.refresh_token, expires: now + j.expires_in * 1000, accountId };
+}
+/** Wait, unless the sign-in is cancelled first. */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new Error('Login cancelled'));
+    const t = setTimeout(() => { signal?.removeEventListener('abort', stop); resolve(); }, ms);
+    const stop = () => { clearTimeout(t); reject(new Error('Login cancelled')); };
+    signal?.addEventListener('abort', stop, { once: true });
+});
+/** A member's engine on phones and in browsers: ChatGPT's device-code sign-in, refresh and sign-out, into `credentials`. */
+export function portableEngine(credentials, { base = 'https://auth.openai.com' } = {}) {
+    const post = async (path, body, form = false, signal) => {
+        try {
+            const res = await fetch(base + path, {
+                method: 'POST', signal,
+                headers: { 'content-type': form ? 'application/x-www-form-urlencoded' : 'application/json' },
+                body: form ? new URLSearchParams(body).toString() : JSON.stringify(body),
+            });
+            return { status: res.status, body: await res.text() };
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw new Error('Login cancelled');
+            throw e;
+        }
+    };
+    const tokens = async (what, r) => {
+        if (r.status < 200 || r.status > 299)
+            throw new Error(`OpenAI Codex token ${what} failed (${r.status})`);
+        return credentialOf(json(r.body));
+    };
+    const refresh = async (c) => {
+        const stop = new AbortController();
+        const t = setTimeout(() => stop.abort(), 15_000);
+        try {
+            return await tokens('refresh', await post('/oauth/token', { grant_type: 'refresh_token', refresh_token: c.refresh, client_id: CLIENT_ID }, true, stop.signal));
+        }
+        catch (e) {
+            throw new Error(`OAuth refresh failed for openai-codex: ${e?.message ?? e}`);
+        }
+        finally {
+            clearTimeout(t);
+        }
+    };
+    const known = (id) => { if (!PORTABLE.includes(id))
+        throw new Error(`${id} can't be signed in to on this device`); };
+    const engine = {
+        async login(id, _type, { signal, notify }) {
+            known(id);
+            const asked = await post('/api/accounts/deviceauth/usercode', { client_id: CLIENT_ID }, false, signal);
+            const start = deviceStart(asked.status, asked.body);
+            notify({ type: 'device_code', userCode: start.userCode, verificationUri: `${base}/codex/device`, intervalSeconds: start.intervalSeconds, expiresInSeconds: CODE_LIVES_S });
+            let interval = Math.max(1000, start.intervalSeconds * 1000);
+            for (const deadline = Date.now() + CODE_LIVES_S * 1000;;) {
+                if (Date.now() >= deadline)
+                    throw new Error('Device flow timed out');
+                // A poll that can't get through waits for the next: a phone cuts a backgrounded app's network while the person
+                // is typing the code in the browser (Android 15 and later), which isn't the sign-in failing.
+                const r = await post('/api/accounts/deviceauth/token', { device_auth_id: start.deviceAuthId, user_code: start.userCode }, false, signal)
+                    .catch((e) => { if (signal?.aborted)
+                    throw e; return { status: 0, body: '' }; });
+                const p = r.status ? devicePoll(r.status, r.body) : { status: 'pending' };
+                if (p.status === 'failed')
+                    throw new Error(p.message);
+                if (p.status === 'complete') {
+                    const c = await tokens('exchange', await post('/oauth/token', {
+                        grant_type: 'authorization_code', client_id: CLIENT_ID, code: p.authorizationCode, code_verifier: p.codeVerifier, redirect_uri: `${base}/deviceauth/callback`,
+                    }, true, signal));
+                    if (signal?.aborted)
+                        throw new Error('Login cancelled');
+                    let wrote = false;
+                    await credentials.modify(id, async () => {
+                        if (signal?.aborted)
+                            return undefined;
+                        wrote = true;
+                        return c;
+                    }, { signal });
+                    if (signal?.aborted) {
+                        if (wrote)
+                            await credentials.delete(id);
+                        throw new Error('Login cancelled');
+                    }
+                    return c;
+                }
+                if (p.status === 'slow_down')
+                    interval += 5000;
+                await sleep(interval, signal);
+            }
+        },
+        checkAuth: async (id) => (PORTABLE.includes(id) && (await credentials.read(id))?.type === 'oauth' ? { source: 'OAuth', type: 'oauth' } : undefined),
+        /** Pi's rule: refresh under the store's lock when under 5 minutes (or `minOAuthValidityMs`) remain, re-checked there,
+         *  so a sign-out or another refresh in between wins; undefined once signed out. */
+        async getAuth(id, { minOAuthValidityMs } = {}) {
+            if (!PORTABLE.includes(id))
+                return undefined;
+            const min = Math.max(5 * 60_000, minOAuthValidityMs ?? 0);
+            const soon = (c) => Date.now() + min >= c.expires;
+            let c = await credentials.read(id);
+            if (c?.type !== 'oauth')
+                return undefined;
+            if (soon(c)) {
+                c = await credentials.modify(id, async (now) => (now?.type === 'oauth' && soon(now) ? refresh(now) : undefined));
+                if (c?.type !== 'oauth')
+                    return undefined;
+            }
+            return { auth: { apiKey: c.access }, source: 'OAuth' };
+        },
+        logout: (id) => credentials.delete(id),
+    };
+    return engine;
+}

package/dist/index.d.ts

@@ -1,6 +1,11 @@
-export { Accounts, planOf, type AccountsOptions, type AuthHost, type Member, type SignIn, type Status } from './accounts.ts';
-export { PROVIDERS, offered, provider, type Provider, type Terms } from './catalogue.ts';
+import { Accounts as Portable, type AccountsOptions, type AuthHost, type Loopback, type Member, type Platform } from './accounts.ts';
+/** Listen on 127.0.0.1 only; no keep-alive, so a browser never lands on a listener from an earlier try. */
+export declare const loopback: Loopback;
+/** A computer: every provider Pi signs in to, and the loopback listener. */
+export declare const computer: Platform;
+export declare class Accounts<R extends AuthHost = AuthHost, M extends Member = Member> extends Portable<R, M> {
+    constructor(opts?: AccountsOptions<M>, platform?: Platform);
+}
+export * from './portable.ts';
 export { INHERITED, emptyAuthContext, isolate } from './isolate.ts';
-export { REST_MS, classify, type Kind } from './limits.ts';
-export { fileStore, memoryStore } from './stores.ts';
-export { WORDS, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';
+export { fileStore, type SafeStorageLike } from './node-stores.ts';

package/dist/index.js

@@ -1,6 +1,28 @@
-export { Accounts, planOf } from "./accounts.js";
-export { PROVIDERS, offered, provider } from "./catalogue.js";
+// @byokit/accounts on a computer (Node, Electron's main process): Pi's own sign-in flows, and a listener for ChatGPT's
+// page coming back to this computer, so its tab shows the app's words. Phones and browsers get portable.ts instead
+// (package.json's "react-native" and "browser" conditions).
+import { createServer } from 'node:http';
+import { builtinModels } from '@earendil-works/pi-ai/providers/all';
+import { Accounts as Portable } from "./accounts.js";
+import { emptyAuthContext } from "./isolate.js";
+/** Listen on 127.0.0.1 only; no keep-alive, so a browser never lands on a listener from an earlier try. */
+export const loopback = (port, handle) => new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+        const { status, html } = await handle(req.url ?? '/');
+        res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', connection: 'close' });
+        res.end(html);
+    });
+    server.once('error', reject).listen(port, '127.0.0.1', () => resolve({ close: () => { server.close(); server.closeIdleConnections(); } }));
+});
+/** A computer: every provider Pi signs in to, and the loopback listener. */
+export const computer = {
+    engine: (credentials) => builtinModels({ credentials, authContext: emptyAuthContext }),
+    signsIn: () => true,
+    loopback,
+};
+export class Accounts extends Portable {
+    constructor(opts = {}, platform = computer) { super(opts, platform); }
+}
+export * from "./portable.js";
 export { INHERITED, emptyAuthContext, isolate } from "./isolate.js";
-export { REST_MS, classify } from "./limits.js";
-export { fileStore, memoryStore } from "./stores.js";
-export { WORDS, callbackPage, clock, failure, say, signInError } from "./words.js";
+export { fileStore } from "./node-stores.js";

package/dist/node-stores.d.ts

@@ -0,0 +1,10 @@
+import type { CredentialStore } from '@earendil-works/pi-ai';
+/** The parts of Electron's `safeStorage` this uses; pass `safeStorage` from 'electron' (main process, after `ready`). */
+export type SafeStorageLike = {
+    encryptString(text: string): Uint8Array;
+    decryptString(data: Buffer): string;
+};
+/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
+ *  With Electron's `safeStorage` the file is sealed with the OS keychain's key instead of plain JSON.
+ *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
+export declare function fileStore(path: string, safeStorage?: SafeStorageLike): CredentialStore;

package/dist/node-stores.js

@@ -0,0 +1,27 @@
+// Desktop stores: a file the app chooses, optionally sealed with Electron's safeStorage (the OS keychain's key).
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { recordStore } from "./stores.js";
+/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
+ *  With Electron's `safeStorage` the file is sealed with the OS keychain's key instead of plain JSON.
+ *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
+export function fileStore(path, safeStorage) {
+    const load = async () => {
+        try {
+            const raw = readFileSync(path);
+            return JSON.parse(safeStorage ? safeStorage.decryptString(raw) : raw.toString('utf8'));
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return {};
+            throw e;
+        }
+    };
+    const save = async (data) => {
+        const text = JSON.stringify(data, null, 2);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(`${path}.tmp`, safeStorage ? safeStorage.encryptString(text) : text, { mode: 0o600 });
+        renameSync(`${path}.tmp`, path);
+    };
+    return recordStore(load, save);
+}

package/dist/portable.d.ts

@@ -0,0 +1,6 @@
+export { Accounts, planOf, portable, type AccountsOptions, type AuthHost, type Loopback, type Member, type Platform, type SignIn, type Status } from './accounts.ts';
+export { PROVIDERS, offered, provider, type Provider, type Terms } from './catalogue.ts';
+export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
+export { REST_MS, classify, type Kind } from './limits.ts';
+export { browserStore, memoryStore, recordStore, secureStore, type SecureStoreLike } from './stores.ts';
+export { WORDS, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';

package/dist/portable.js

@@ -0,0 +1,8 @@
+// @byokit/accounts on phones (React Native, Expo) and in browsers (a PWA, Electron's renderer): the same Accounts, with
+// ChatGPT by device code (portableEngine) and the phone's or browser's own storage. No Node module is imported.
+export { Accounts, planOf, portable } from "./accounts.js";
+export { PROVIDERS, offered, provider } from "./catalogue.js";
+export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine } from "./engine.js";
+export { REST_MS, classify } from "./limits.js";
+export { browserStore, memoryStore, recordStore, secureStore } from "./stores.js";
+export { WORDS, callbackPage, clock, failure, say, signInError } from "./words.js";

package/dist/stores.d.ts

@@ -1,5 +1,24 @@
-import { type CredentialStore } from '@earendil-works/pi-ai';
-export declare const memoryStore: () => CredentialStore;
-/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
- *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
-export declare function fileStore(path: string): CredentialStore;
+import type { Credential, CredentialStore } from '@earendil-works/pi-ai';
+export type Record = {
+    [providerId: string]: Credential;
+};
+export type EndingStore = CredentialStore & {
+    end(id: string, fn: (c: Credential | undefined) => Promise<void>): Promise<void>;
+};
+/** A store over one whole record the platform loads and saves. Writes are serialized within this process; a write
+ *  re-reads first, so a sign-in that took minutes never overwrites a provider that changed meanwhile. */
+export declare function recordStore(load: () => Promise<Record>, save: (data: Record) => Promise<void>): EndingStore;
+export declare function memoryStore(): CredentialStore;
+/** The parts of `expo-secure-store` this uses (Keychain on iOS, Keystore-encrypted on Android); pass the module itself. */
+export type SecureStoreLike = {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+};
+/** One person's sign-ins in the phone's secure storage: `secureStore(SecureStore, 'byokit.1')`. Keys may hold letters,
+ *  digits, `.`, `-` and `_`. The record is split into pieces under the 2048 bytes expo-secure-store warns about, written
+ *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. */
+export declare function secureStore(secure: SecureStoreLike, name: string): CredentialStore;
+/** One person's sign-ins in the browser's IndexedDB (a PWA, or Electron's renderer), under `name`. A browser has no
+ *  keychain: anything running on this page could read them, so keep the page free of scripts you don't control. */
+export declare function browserStore(name: string, db?: string): EndingStore;

package/dist/stores.js

@@ -1,42 +1,99 @@
-// Credential stores behind Pi's own CredentialStore seam: one per person, never a shared fallback.
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { InMemoryCredentialStore } from '@earendil-works/pi-ai';
-export const memoryStore = () => new InMemoryCredentialStore();
-/** One person's sign-ins in a JSON file the app chooses (0600, in a 0700 folder), in the same shape as Pi's auth.json.
- *  ponytail: writes are serialized within this process only; add a file lock if two processes ever share one file. */
-export function fileStore(path) {
+/** A store over one whole record the platform loads and saves. Writes are serialized within this process; a write
+ *  re-reads first, so a sign-in that took minutes never overwrites a provider that changed meanwhile. */
+export function recordStore(load, save) {
     let chain = Promise.resolve();
     const serial = (fn) => { const r = chain.then(fn); chain = r.catch(() => { }); return r; };
-    const load = () => {
-        try {
-            return JSON.parse(readFileSync(path, 'utf8'));
-        }
-        catch (e) {
-            if (e?.code === 'ENOENT')
-                return {};
-            throw e;
-        }
-    };
-    const save = (data) => {
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        writeFileSync(`${path}.tmp`, JSON.stringify(data, null, 2), { mode: 0o600 });
-        renameSync(`${path}.tmp`, path);
-    };
     return {
-        read: async (id) => load()[id],
-        list: async () => Object.entries(load()).map(([providerId, c]) => ({ providerId, type: c.type })),
-        modify: (id, fn) => serial(async () => {
-            const current = load()[id];
+        read: async (id) => (await load())[id],
+        list: async () => Object.entries(await load()).map(([providerId, c]) => ({ providerId, type: c.type })),
+        modify: (id, fn, options) => serial(async () => {
+            const current = (await load())[id];
             const next = await fn(current);
             if (next === undefined)
                 return current;
-            save({ ...load(), [id]: next }); // re-read: a sign-in can take minutes, and other providers may have changed meanwhile
+            if (options?.signal?.aborted)
+                throw new Error('Login cancelled');
+            await save({ ...(await load()), [id]: next });
             return next;
         }),
-        delete: (id) => serial(async () => { const data = load(); if (id in data) {
+        delete: (id) => serial(async () => { const data = await load(); if (id in data) {
             delete data[id];
-            save(data);
+            await save(data);
         } }),
+        end: (id, fn) => serial(async () => {
+            try {
+                await fn((await load())[id]);
+            }
+            finally {
+                const data = await load();
+                if (id in data) {
+                    delete data[id];
+                    await save(data);
+                }
+            }
+        }),
+    };
+}
+export function memoryStore() {
+    let data = {};
+    return recordStore(async () => ({ ...data }), async (d) => { data = d; });
+}
+/** One person's sign-ins in the phone's secure storage: `secureStore(SecureStore, 'byokit.1')`. Keys may hold letters,
+ *  digits, `.`, `-` and `_`. The record is split into pieces under the 2048 bytes expo-secure-store warns about, written
+ *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. */
+export function secureStore(secure, name) {
+    const head = async () => { const [gen = '0', n = '0'] = (await secure.getItemAsync(name))?.split(':') ?? []; return { gen: Number(gen), n: Number(n) }; };
+    const load = async () => {
+        const { gen, n } = await head();
+        let text = '';
+        for (let i = 0; i < n; i++)
+            text += (await secure.getItemAsync(`${name}.${gen}.${i}`)) ?? '';
+        return text ? JSON.parse(text) : {};
+    };
+    const save = async (data) => {
+        const old = await head();
+        const gen = old.gen + 1;
+        const parts = (Object.keys(data).length ? JSON.stringify(data) : '').match(/[\s\S]{1,1800}/g) ?? [];
+        for (const [i, part] of parts.entries())
+            await secure.setItemAsync(`${name}.${gen}.${i}`, part);
+        await secure.setItemAsync(name, `${gen}:${parts.length}`);
+        for (let i = 0; i < old.n; i++)
+            await secure.deleteItemAsync(`${name}.${old.gen}.${i}`);
+        // Leftovers of a write that crashed at this generation before.
+        for (let i = parts.length; (await secure.getItemAsync(`${name}.${gen}.${i}`)) !== null; i++)
+            await secure.deleteItemAsync(`${name}.${gen}.${i}`);
+    };
+    return recordStore(load, save);
+}
+/** One person's sign-ins in the browser's IndexedDB (a PWA, or Electron's renderer), under `name`. A browser has no
+ *  keychain: anything running on this page could read them, so keep the page free of scripts you don't control. */
+export function browserStore(name, db = 'byokit') {
+    const open = () => new Promise((resolve, reject) => {
+        const r = indexedDB.open(db, 1);
+        r.onupgradeneeded = () => r.result.createObjectStore('signins');
+        r.onsuccess = () => resolve(r.result);
+        r.onerror = () => reject(r.error);
+    });
+    const run = async (mode, fn) => {
+        const d = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const t = d.transaction('signins', mode);
+                const r = fn(t.objectStore('signins'));
+                t.oncomplete = () => resolve(r.result);
+                t.onerror = t.onabort = () => reject(t.error);
+            });
+        }
+        finally {
+            d.close();
+        }
+    };
+    const store = recordStore(async () => (await run('readonly', (s) => s.get(name))) ?? {}, (data) => run('readwrite', (s) => s.put(data, name)));
+    const locked = async (id, fn) => typeof navigator !== 'undefined' && navigator.locks ? await navigator.locks.request(`byokit:${db}:${name}:${id}`, fn) : fn();
+    return {
+        ...store,
+        modify: (id, fn, options) => locked(id, () => store.modify(id, fn, options)),
+        delete: (id, options) => locked(id, () => store.delete(id, options)),
+        end: (id, fn) => locked(id, () => store.end(id, fn)),
     };
 }

package/dist/testing/index.d.ts

@@ -17,3 +17,4 @@ export declare function decoy(root?: string): {
     /** Marks left by the decoy's extension or CLIs: something ran code from someone else's setup. */
     ran: () => string[];
 };
+export { mockJwt, mockOpenAI, type MockOpenAIOptions } from './mock-openai.ts';

package/dist/testing/index.js

@@ -48,3 +48,4 @@ export function decoy(root = mkdtempSync(join(tmpdir(), 'byokit-decoy-'))) {
         ran: () => readdirSync(marks),
     };
 }
+export { mockJwt, mockOpenAI } from "./mock-openai.js";

package/dist/testing/mock-openai.d.ts

@@ -0,0 +1,31 @@
+export type MockOpenAIOptions = {
+    port?: number;
+    host?: string;
+    plan?: string;
+    email?: string;
+    expiresIn?: number;
+    log?: (line: string) => void;
+};
+/** An access token as OpenAI shapes it: the account, the plan and the email in its claims. */
+export declare const mockJwt: (plan?: string, email?: string, n?: number) => string;
+export declare function mockOpenAI({ port, host, plan, email, expiresIn, log }?: MockOpenAIOptions): Promise<{
+    base: string;
+    state: {
+        /** Refresh tokens OpenAI still honours; a refresh spends the old one (rotation), sign-out revokes one. */
+        live: Set<string>;
+        requests: {
+            path: string;
+            body: string;
+        }[];
+        /** Refuse every refresh, as when the person signed out elsewhere. */
+        refuse: boolean;
+        /** Seconds each issued token lives. */
+        expiresIn: number;
+        /** Drop this many device-code polls on the floor, as a phone does to a backgrounded app. */
+        dropPolls: number;
+    };
+    approve: (userCode: string, deny?: boolean) => boolean;
+    /** The code most recently handed out. */
+    lastCode: () => string | undefined;
+    close: () => Promise<void>;
+}>;

package/dist/testing/mock-openai.js

@@ -0,0 +1,112 @@
+// OpenAI's sign-in, stood in for: device code, its page where a person types the code, token exchange and refresh
+// (rotating), revoke, and the same CORS answer the real endpoints give, so a web page, a phone app or a test signs in
+// end to end with no account and no real network. Run it alone for a demo or an emulator:
+//   node packages/accounts/src/testing/mock-openai.ts [port]      (21455 by default, never ChatGPT's own 1455)
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+/** An access token as OpenAI shapes it: the account, the plan and the email in its claims. */
+export const mockJwt = (plan = 'plus', email = 'sara@example.com', n = 0) => ['eyJhbGciOiJub25lIn0', Buffer.from(JSON.stringify({
+        'https://api.openai.com/auth': { chatgpt_account_id: 'acct-1', chatgpt_plan_type: plan }, 'https://api.openai.com/profile': { email }, n,
+        // As long as a real one, whose claims fill about 1.5 kB.
+        scp: ['openid', 'profile', 'email', 'offline_access'], pad: 'x'.repeat(1200),
+    })).toString('base64url'), 'sig'].join('.');
+export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus', email = 'sara@example.com', expiresIn = 864_000, log } = {}) {
+    const codes = new Map();
+    let issued = 0, asked = 0;
+    const state = {
+        /** Refresh tokens OpenAI still honours; a refresh spends the old one (rotation), sign-out revokes one. */
+        live: new Set(),
+        requests: [],
+        /** Refuse every refresh, as when the person signed out elsewhere. */
+        refuse: false,
+        /** Seconds each issued token lives. */
+        expiresIn,
+        /** Drop this many device-code polls on the floor, as a phone does to a backgrounded app. */
+        dropPolls: 0,
+    };
+    const issue = () => {
+        const refresh = `rt_${++issued}`;
+        state.live.add(refresh);
+        return { access_token: mockJwt(plan, email, issued), refresh_token: refresh, expires_in: state.expiresIn, id_token: 'x' };
+    };
+    const approve = (userCode, deny = false) => {
+        const c = codes.get(userCode.trim().toUpperCase());
+        if (c)
+            Object.assign(c, deny ? { denied: true } : { approved: true });
+        return !!c;
+    };
+    const page = (words, form = true) => `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Stand-in OpenAI</title>
+<body style="font:18px system-ui;max-width:28em;margin:3em auto;padding:0 1em"><h1>Stand-in OpenAI</h1><p id="words">${words}</p>${form ? `<form method="post">
+<input name="user_code" id="code" autocomplete="off" placeholder="XXXX-XXXXX" style="font:inherit;padding:.4em"> <button id="continue" style="font:inherit;padding:.4em 1em">Continue</button></form>` : ''}</body>`;
+    const server = createServer(async (req, res) => {
+        let body = '';
+        for await (const chunk of req)
+            body += chunk;
+        const url = new URL(req.url ?? '/', 'http://x');
+        const form = new URLSearchParams(body);
+        state.requests.push({ path: url.pathname, body });
+        log?.(`${req.method} ${url.pathname} ${form.get('grant_type') ?? ''}`.trim());
+        const send = (status, data, type = 'application/json') => {
+            res.writeHead(status, { 'content-type': type, 'access-control-allow-origin': '*', 'access-control-allow-headers': 'content-type', 'access-control-allow-methods': 'POST, GET, OPTIONS' });
+            res.end(typeof data === 'string' ? data : JSON.stringify(data));
+        };
+        const json = () => { try {
+            return JSON.parse(body);
+        }
+        catch {
+            return {};
+        } };
+        if (req.method === 'OPTIONS')
+            return send(200, '');
+        switch (url.pathname) {
+            case '/api/accounts/deviceauth/usercode': {
+                const userCode = `MOCK-${String(10000 + ++asked).slice(-5)}`;
+                codes.set(userCode, { device: `da_${asked}` });
+                return send(200, { device_auth_id: codes.get(userCode).device, user_code: userCode, interval: '1' });
+            }
+            case '/api/accounts/deviceauth/token': {
+                if (state.dropPolls > 0 && state.dropPolls--)
+                    return req.socket.destroy();
+                const { device_auth_id, user_code } = json();
+                const c = codes.get(user_code);
+                if (!c || c.device !== device_auth_id)
+                    return send(400, { error: { code: 'deviceauth_invalid' } });
+                if (c.denied)
+                    return send(400, { error: { code: 'access_denied', message: 'The user declined' } });
+                return c.approved ? send(200, { authorization_code: `ac_${user_code}`, code_verifier: 'cv' }) : send(403, { error: { code: 'deviceauth_authorization_pending' } });
+            }
+            case '/oauth/token':
+                if (form.get('grant_type') === 'authorization_code') {
+                    const c = codes.get(form.get('code')?.replace(/^ac_/, '') ?? '');
+                    if (!c?.approved)
+                        return send(401, { error: { code: 'token_expired' } });
+                    codes.delete(form.get('code').slice(3));
+                    return send(200, issue());
+                }
+                if (state.refuse || !state.live.delete(form.get('refresh_token') ?? ''))
+                    return send(401, { error: { code: 'refresh_token_reused', message: 'invalid_grant' } });
+                return send(200, issue());
+            case '/oauth/revoke':
+                state.live.delete(json().token);
+                return send(200, {});
+            case '/codex/device':
+                if (req.method !== 'POST')
+                    return send(200, page('Type the code the app shows you.'), 'text/html; charset=utf-8');
+                return send(200, approve(form.get('user_code') ?? '') ? page('Signed in. Go back to the app.', false) : page("That code doesn't match. Try again."), 'text/html; charset=utf-8');
+            default:
+                return send(404, { error: 'not found' });
+        }
+    });
+    await new Promise((r) => server.listen(port, host, r));
+    const base = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${server.address().port}`;
+    return {
+        base, state, approve,
+        /** The code most recently handed out. */
+        lastCode: () => [...codes.keys()].at(-1),
+        close: () => new Promise((r) => { server.close(() => r()); server.closeAllConnections(); }),
+    };
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const m = await mockOpenAI({ port: Number(process.argv[2] ?? 21455), host: '0.0.0.0', log: (line) => console.log(new Date().toISOString().slice(11, 19), line) });
+    console.log(`stand-in OpenAI on ${m.base}; approve codes at ${m.base}/codex/device`);
+}

package/dist/words.json

@@ -1,4 +1,9 @@
 {
+    "signIn.opening": "Opening {name}…",
+    "signIn.waitingUrl": "Sign in on the {name} page that just opened.",
+    "signIn.waitingCode": "On the {name} page, type this code: {code}",
+    "signIn.pasteHint": "Having trouble? Copy the address from the browser and paste it here.",
+    "signIn.cancelled": "Sign-in stopped. Nothing was kept.",
     "signIn.expired": "The code expired before it was used. Tap Sign in with {name} for a new one.",
     "signIn.declined": "The sign-in was declined on the {name} page. Tap Sign in with {name} to try again.",
     "signIn.offline": "Couldn't reach {name}. Check the internet connection, then tap Sign in again.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,6 +14,14 @@
   },
   "exports": {
     ".": {
+      "react-native": {
+        "types": "./dist/portable.d.ts",
+        "default": "./dist/portable.js"
+      },
+      "browser": {
+        "types": "./dist/portable.d.ts",
+        "default": "./dist/portable.js"
+      },
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },