@byokit/accounts 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.9.0 (2026-09-30)
+
+
+
+- SECURITY: Prevent replay of single-use refresh grants in the portable engine by saving a generation attempt before sending and committing the replacement before returning access. An uncertain or terminal attempt requires sign-in again; custom stores must provide a refresh transaction, and restart safety depends on durable storage and a single refresh owner or host lock.
+
 ## 0.8.0 (2026-09-30)
 
 - SECURITY: Desktop fileStore now requires a sealing adapter, rejects insecure Electron storage backends, and refuses symlink or permissive credential files. Plaintext stores must revoke old credentials and sign in again; previously sealed stores remain readable with the same adapter.

package/README.md

@@ -191,9 +191,42 @@ when no handler is set).
 
 `memoryStore()`, `fileStore(path, safeStorage)` (sealed, 0600), `secureStore(SecureStore, name,
 options?)` 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
+store instance; `browserStore` also uses Web Locks across tabs for the whole record when available. Never a shared
 fallback.
 
+### Refresh safety
+
+`portableEngine` (the default on phones and in browsers) holds the store lock, re-reads the current sign-in, and saves
+a non-secret `byokitRefresh` generation/attempt marker in the credential record **before** sending a refresh grant.
+It commits the replacement pair before returning access. A lost response, terminal refusal, unchanged refresh grant,
+or failure to save the replacement requires sign-in again; an attempted or quarantined generation is never retried,
+including by `recheck`. If the attempt marker cannot be saved, nothing is sent. A fresh sign-in replaces quarantine.
+This deliberately requires sign-in again after even a network failure once a refresh send has started: the server
+may already have spent the grant. Storage failures before the send, such as a locked phone keychain, remain retryable.
+
+- **iOS/Android `secureStore`**: crash-safe across process restart after the platform acknowledges the marker write,
+  with one store instance/refresh owner per storage name. Its chunk-generation pointer commits the marker and each
+  replacement atomically. Multiple app processes or independently created store instances need a host lock covering
+  the whole transaction.
+- **Browser/PWA `browserStore`**: IndexedDB commits the marker before sending. With Web Locks it serializes the whole
+  transaction across tabs. Without Web Locks, use one store instance and tab; multiple writers are only best-effort.
+  Browser storage eviction, rollback and power-loss durability are outside this guarantee.
+- **Node/Electron `fileStore` with `portableEngine`**: the sealed file is atomically replaced and synced when Node
+  permissions permit; on POSIX the directory is synced too. Process restart retains the attempt. Use one instance per
+  path and a host lock across processes. On Windows or with Node's permission model, power-loss durability is best-effort.
+- **`recordStore(load, save)`**: crash safety depends on the host's atomic, durable save completing before its promise
+  resolves and a host lock across independent writers. A best-effort save makes refresh best-effort too.
+- **`memoryStore`**: serialized only in memory; there is no restart recovery. A bare custom `CredentialStore` can serve
+  existing access but cannot refresh: wrap its durable load/save in `recordStore`, or implement the exported
+  `RefreshStore.refresh` transaction contract with these same guarantees.
+
+The default computer engine is still Pi's engine; its refresh path does **not** use this transaction. Other engines
+and runtime aggregators own their own refresh guarantees. The fix does not add a second refresher to them.
+
+The persisted-attempt, failed-save and concurrency regression ideas were informed by
+[clauth's refresh guard](https://github.com/uwuclxdy/clauth/blob/6410345c65b91cf07eabd4f9f79670ba602ace63/src/codex_auth.rs).
+The TypeScript transaction and synthetic tests were written independently; no upstream code or tests were copied.
+
 - **Browser**: browser storage is readable by scripts on your page: avoid untrusted scripts.
 - **Phone**: pass `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }` as `options` (to every get, set
   and delete) so tokens never migrate to a new device through an iCloud/iTunes backup; without it Expo's default

package/dist/accounts.d.ts

@@ -2,10 +2,10 @@ import type { CredentialStore, Models } from '@earendil-works/pi-ai';
 import { type Provider } from './catalogue.ts';
 import { type Kind } from './limits.ts';
 import { ResponseError, type Ask, type ResponseResult, type ResponseTool } from './responses.ts';
-import { type EndingStore } from './stores.ts';
+import { type EndingStore, type RefreshStore } 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`). */
-type BoundStore = CredentialStore & {
+type BoundStore = CredentialStore & Partial<Pick<RefreshStore, 'refresh'>> & {
     signOut: (id: string, p: Provider) => Promise<void>;
 };
 export type AuthHost = Pick<Models, 'login' | 'logout' | 'checkAuth' | 'getAuth'> & {
@@ -171,7 +171,8 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     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. */
+     *  nobody is looking. A refusal or uncertain refresh requires sign-in again; `onExpired` says so once. A storage
+     *  read failure before sending remains unknown and can be retried. */
     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>;

package/dist/accounts.js

@@ -2,7 +2,7 @@ import { offered, provider } from "./catalogue.js";
 import { claims, PORTABLE, portableEngine } from "./engine.js";
 import { classify, REST_MS } from "./limits.js";
 import { respond, ResponseError } from "./responses.js";
-import { memoryStore } from "./stores.js";
+import { memoryStore, refreshCredential } 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) };
@@ -65,6 +65,7 @@ export class Accounts {
                 read: (id) => base.read(id),
                 list: () => base.list(),
                 modify: (id, fn, options) => serial(() => base.modify(id, fn, options)),
+                refresh: (id, due, rotate) => serial(() => refreshCredential(base, id, due, rotate)),
                 delete: (id, options) => serial(() => base.delete(id, options)),
                 end: (id, fn) => serial(async () => {
                     if (typeof base.end === 'function')
@@ -99,6 +100,17 @@ export class Accounts {
         return {
             read: (id, options) => raw.read(id, options),
             list: (options) => raw.list(options),
+            refresh: (id, due, rotate) => {
+                const account = key(id);
+                const started = this.generations.get(account) ?? 0;
+                return this.serial(account, async () => {
+                    if (started !== (this.generations.get(account) ?? 0))
+                        return undefined;
+                    const next = await refreshCredential(raw, id, due, rotate);
+                    // Sign-out waits on this lock and revokes the committed replacement pair.
+                    return started === (this.generations.get(account) ?? 0) ? next : undefined;
+                });
+            },
             modify: (id, fn, options) => {
                 const account = key(id);
                 const stale = Symbol();
@@ -453,14 +465,15 @@ export class Accounts {
                 const c = await this.store(member).read(pi);
                 return c?.type === 'oauth' && c.expires > Date.now();
             }
-            // Only the provider refusing (400-403) counts as expiry. Anything else (a locked keychain read, storage failing)
-            // is unknown: try later, never sign the person out.
+            // A provider refusal or quarantined refresh requires sign-in again. A read failure before sending (for example
+            // a locked keychain) is unknown: try later.
             const status = e?.status;
             return typeof status !== 'number' || status < 400 || status > 403;
         });
     }
     /** 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. */
+     *  nobody is looking. A refusal or uncertain refresh requires sign-in again; `onExpired` says so once. A storage
+     *  read failure before sending remains unknown and can be retried. */
     async keepFresh(members) {
         for (const m of members)
             for (const p of this.providers) {

package/dist/engine.js

@@ -1,3 +1,4 @@
+import { RefreshRequiredError, refreshCredential } from "./stores.js";
 const CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
 const CODE_LIVES_S = 15 * 60;
 /** The Pi provider ids this engine signs in to. */
@@ -143,7 +144,21 @@ export function portableEngine(credentials, { base = 'https://auth.openai.com' }
                 await sleep(interval, signal);
             }
         },
-        checkAuth: async (id) => (PORTABLE.includes(id) && (await credentials.read(id))?.type === 'oauth' ? { source: 'OAuth', type: 'oauth' } : undefined),
+        checkAuth: async (id) => {
+            if (!PORTABLE.includes(id))
+                return undefined;
+            try {
+                // Wait for a live transaction rather than mistake its before-send marker for a failed sign-in.
+                // A false due predicate only reads under the lock; it never sends or saves.
+                const c = await refreshCredential(credentials, id, () => false, refresh);
+                return c?.type === 'oauth' ? { source: 'OAuth', type: 'oauth' } : undefined;
+            }
+            catch (e) {
+                if (e instanceof RefreshRequiredError)
+                    return undefined;
+                throw e;
+            }
+        },
         /** 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 } = {}) {
@@ -151,14 +166,10 @@ export function portableEngine(credentials, { base = 'https://auth.openai.com' }
                 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);
+            // Even a still-valid access token must not bypass quarantine, including a forced refresh after a refusal.
+            const c = await refreshCredential(credentials, id, soon, refresh);
             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),

package/dist/node-stores.d.ts

@@ -1,4 +1,4 @@
-import type { CredentialStore } from '@earendil-works/pi-ai';
+import { type EndingStore } from './stores.ts';
 /** Pass Electron's safeStorage from the main process after ready, or an equivalent trusted sealing adapter.
  * Adapters without capability methods are responsible for ensuring their key is protected. */
 export type SafeStorageLike = {
@@ -10,4 +10,4 @@ export type SafeStorageLike = {
 /** One person's sealed sign-ins in an app-owned 0600 file inside a private 0700 folder.
  * No plaintext fallback. Writes are serialized per store instance; use one instance per path and a host lock
  * if multiple processes share it. The host owns the adapter and its key, separately from this file. */
-export declare function fileStore(path: string, safeStorage: SafeStorageLike): CredentialStore;
+export declare function fileStore(path: string, safeStorage: SafeStorageLike): EndingStore;

package/dist/node-stores.js

@@ -65,6 +65,16 @@ export function fileStore(path, safeStorage) {
                 closeSync(fd);
             }
             renameSync(tmp, path);
+            // Windows does not support opening directories for fsync through this API.
+            if (!process.permission && process.platform !== 'win32') {
+                const dir = openSync(folder, constants.O_RDONLY);
+                try {
+                    fsyncSync(dir);
+                }
+                finally {
+                    closeSync(dir);
+                }
+            }
         }
         finally {
             if (created)

package/dist/portable.d.ts

@@ -3,6 +3,6 @@ export { PROVIDERS, offered, provider, type Billing, type Provider, type Terms }
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
 export { REST_MS, classify, type Kind } from './limits.ts';
 export { IncompleteError, ResponseError, isFunctionCall, limitResponse, respond, sseReader, type Ask, type ResponseFunctionCall, type ResponseInputItem, type ResponseOutputItem, type ResponseOutputMessage, type ResponseReasoning, type ResponseResult, type ResponseStreamEvent, type ResponseText, type ResponseTextFormat, type ResponseTool, type ResponseToolChoice } from './responses.ts';
-export { browserStore, memoryStore, recordStore, secureStore, type SecureStoreLike } from './stores.ts';
+export { browserStore, memoryStore, recordStore, secureStore, RefreshRequiredError, type RefreshStore, type SecureStoreLike } from './stores.ts';
 export { WORDS, billingWords, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';
 export { chatgptPlan, UnsupportedAccountError, type ChatGPTPlanAccount, type ChatGPTPlanSession } from './chatgpt-plan.ts';

package/dist/portable.js

@@ -5,6 +5,6 @@ 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 { IncompleteError, ResponseError, isFunctionCall, limitResponse, respond, sseReader } from "./responses.js";
-export { browserStore, memoryStore, recordStore, secureStore } from "./stores.js";
+export { browserStore, memoryStore, recordStore, secureStore, RefreshRequiredError } from "./stores.js";
 export { WORDS, billingWords, callbackPage, clock, failure, say, signInError } from "./words.js";
 export { chatgptPlan, UnsupportedAccountError } from "./chatgpt-plan.js";

package/dist/stores.d.ts

@@ -1,14 +1,28 @@
-import type { Credential, CredentialStore } from '@earendil-works/pi-ai';
+import type { Credential, CredentialStore, OAuthCredential } from '@earendil-works/pi-ai';
 export type Record = {
     [providerId: string]: Credential;
 };
-export type EndingStore = CredentialStore & {
+/** Extends the credential seam so two durable writes can bracket a refresh while holding the same lock. */
+export type RefreshStore = CredentialStore & {
+    refresh(id: string, due: (c: OAuthCredential) => boolean, rotate: (c: OAuthCredential) => Promise<OAuthCredential>): Promise<OAuthCredential | undefined>;
+};
+export type EndingStore = RefreshStore & {
     end(id: string, fn: (c: Credential | undefined) => Promise<void>): Promise<void>;
 };
+/** No provider response or credential is included in this error. `status` lets Accounts ask for sign-in again. */
+export declare class RefreshRequiredError extends Error {
+    readonly status = 401;
+    constructor();
+}
+/** Legacy credentials have no marker. Unknown or incomplete state fails closed. */
+export declare function needsReauth(c: Credential | undefined): boolean;
+/** Bare CredentialStore implementations cannot persist inside their modify callback. Require the transaction seam
+ *  rather than send a grant without its attempt marker; custom stores can use recordStore(load, save). */
+export declare function refreshCredential(store: CredentialStore, id: string, due: (c: OAuthCredential) => boolean, rotate: (c: OAuthCredential) => Promise<OAuthCredential>): Promise<OAuthCredential | undefined>;
 /** 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;
+export declare function memoryStore(): EndingStore;
 /** The parts of `expo-secure-store` this uses (Keychain on iOS, Keystore-encrypted on Android); pass the module itself.
  *  Every method takes the same optional `options` (e.g. `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`). */
 export type SecureStoreLike = {
@@ -21,7 +35,7 @@ export type SecureStoreLike = {
  *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. `options` (e.g.
  *  `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`) is passed to every get, set and delete;
  *  without it Expo's default (`WHEN_UNLOCKED`) applies. */
-export declare function secureStore(secure: SecureStoreLike, name: string, options?: object): CredentialStore;
+export declare function secureStore(secure: SecureStoreLike, name: string, options?: object): EndingStore;
 /** 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,3 +1,30 @@
+/** No provider response or credential is included in this error. `status` lets Accounts ask for sign-in again. */
+export class RefreshRequiredError extends Error {
+    status = 401;
+    constructor() { super('This sign-in needs to be connected again.'); this.name = 'RefreshRequiredError'; }
+}
+/** Legacy credentials have no marker. Unknown or incomplete state fails closed. */
+export function needsReauth(c) {
+    if (c?.type !== 'oauth' || c.byokitRefresh === undefined)
+        return false;
+    const marker = c.byokitRefresh;
+    return !marker || marker.state !== 'ready' || !Number.isSafeInteger(marker.generation) || marker.generation < 0;
+}
+/** Bare CredentialStore implementations cannot persist inside their modify callback. Require the transaction seam
+ *  rather than send a grant without its attempt marker; custom stores can use recordStore(load, save). */
+export async function refreshCredential(store, id, due, rotate) {
+    const refresh = store.refresh;
+    if (refresh)
+        return refresh.call(store, id, due, rotate);
+    const c = await store.read(id);
+    if (c?.type !== 'oauth')
+        return undefined;
+    if (needsReauth(c))
+        throw new RefreshRequiredError();
+    if (!due(c))
+        return c;
+    throw new Error('Refresh requires a transactional credential store; use recordStore(load, save).');
+}
 /** 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) {
@@ -16,6 +43,42 @@ export function recordStore(load, save) {
             await save({ ...(await load()), [id]: next });
             return next;
         }),
+        refresh: (id, due, rotate) => serial(async () => {
+            const current = (await load())[id];
+            if (current?.type !== 'oauth')
+                return undefined;
+            if (needsReauth(current))
+                throw new RefreshRequiredError();
+            if (!due(current))
+                return current;
+            const generation = current.byokitRefresh?.generation ?? 0;
+            const attempted = { ...current, byokitRefresh: { generation, state: 'attempted' } };
+            const write = async (c) => save({ ...(await load()), [id]: c });
+            // Never send if this write fails. The marker stays in the same sealed record as the old pair.
+            await write(attempted);
+            let next;
+            try {
+                next = await rotate(current);
+                if (next.refresh === current.refresh)
+                    throw new Error('Refresh did not replace the grant');
+                if (current.accountId && next.accountId !== current.accountId)
+                    throw new RefreshRequiredError();
+            }
+            catch (e) {
+                const state = [400, 401, 403].includes(e?.status) ? 'terminal' : 'uncertain';
+                // The before-send marker already prevents replay if the quarantine write also fails.
+                await write({ ...attempted, byokitRefresh: { generation, state } }).catch(() => { });
+                throw new RefreshRequiredError();
+            }
+            const committed = { ...current, ...next, byokitRefresh: { generation: generation + 1, state: 'ready' } };
+            try {
+                await write(committed);
+            }
+            catch {
+                throw new RefreshRequiredError();
+            }
+            return committed;
+        }),
         delete: (id) => serial(async () => { const data = await load(); if (id in data) {
             delete data[id];
             await save(data);
@@ -91,11 +154,13 @@ export function browserStore(name, db = 'byokit') {
         }
     };
     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();
+    // Every write replaces the whole record, so tabs must share a record lock, including the entire refresh.
+    const locked = async (fn) => typeof navigator !== 'undefined' && navigator.locks ? await navigator.locks.request(`byokit:${db}:${name}`, 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)),
+        modify: (id, fn, options) => locked(() => store.modify(id, fn, options)),
+        refresh: (id, due, rotate) => locked(() => store.refresh(id, due, rotate)),
+        delete: (id, options) => locked(() => store.delete(id, options)),
+        end: (id, fn) => locked(() => store.end(id, fn)),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",