@byokit/accounts 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## 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.
+- SECURITY: Credential writes use exclusive random temporary files with no-follow opens and file sync before atomic replacement when Node permissions allow it; default sign-in and discarded-credential revoke logs no longer include raw provider errors or member identifiers.
+
 ## 0.7.1 (2026-09-30)
 
 - FIX: a cut-off answer is now reported as cut off: `respond` throws `IncompleteError` with its reason and partial output, and notifies `onEvent`, instead of returning it as finished.

package/README.md

@@ -77,9 +77,11 @@ flows, pinned exactly:
 ```ts
 import { isolate } from '@byokit/accounts/isolate'; // first, before any Pi import
 isolate('/path/to/app/engine');                     // scrub inherited Pi settings and provider keys
-import { Accounts, fileStore } from '@byokit/accounts';
+const { Accounts, fileStore } = await import('@byokit/accounts');
+const { app, safeStorage } = await import('electron');
+await app.whenReady();
 
-const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`) });
+const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`, safeStorage) });
 const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: 'waiting', code, url }
 // show shown.code and shown.url; the sign-in finishes by itself
 (await accounts.status(1, 'chatgpt')).words;                     // "ChatGPT is connected."
@@ -116,7 +118,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 |---|---|
 | `Accounts` | Sign-in, status, sign-out, asking and limits for each member: `login`, `finished`, `status`, `plan`, `logout`, `respond`, `failed`, `ladder`, `keepFresh` |
 | `portable`, `computer`, `loopback` | The platform `Accounts` runs on: device code with `fetch` alone, or (Node entry only) Pi's flows and the loopback listener |
-| `memoryStore`, `fileStore`, `secureStore`, `browserStore`, `recordStore` | One store per person: in memory, a 0600 file (Node entry only), Keychain/Keystore, IndexedDB, or your own load and save |
+| `memoryStore`, `fileStore`, `secureStore`, `browserStore`, `recordStore` | One store per person: in memory, a sealed 0600 file (Node entry only), Keychain/Keystore, IndexedDB, or your own load and save |
 | `offered`, `provider`, `PROVIDERS` | The catalogue: each provider's billing, terms status, reason and source |
 | `billingWords`, `say`, `WORDS`, `signInError`, `failure`, `clock`, `callbackPage` | The plain sentences every app shows the same way (`words.json`), a time in words, and the page a browser sees after a sign-in |
 | `respond`, `ResponseError`, `IncompleteError`, `sseReader`, `limitResponse`, `isFunctionCall` | Ask ChatGPT's answers endpoint with a sign-in, with tools, pictures, thinking effort and an answer shape; the error with the words to show and the kind acted on |
@@ -135,7 +137,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | ChatGPT (subscription) | Its own page, straight back to this computer (port 1455); a code when asked or stuck | Device code | Device code |
 | OpenRouter (API billing) | Its own page, back to this computer (Pi's flow), when an app offers it (never by default) | 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) |
+| Where sign-ins are kept | `fileStore(path, safeStorage)`, sealing required | `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
@@ -182,16 +184,49 @@ the local sign-in even if the revoke fails. A failed revoke rejects after local
 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
+cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its discarded credential (or a generic failure 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,
+`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
@@ -299,3 +334,24 @@ including ID-token signature/issuer/audience/nonce verification and protected pe
 available to eligible open-source/local apps; paid/remote apps require approval. This adapter does not start an
 OAuth flow and does not convert the existing Codex `Accounts.login()` credential into a token-sharing session.
 It reads no environment or files, and remains portable to browsers and React Native.
+
+
+## Desktop credential storage security
+
+`fileStore(path, safeStorage)` requires a sealing adapter; there is no plaintext fallback.
+In Electron, pass `safeStorage` after `app.whenReady()`. The store refuses unavailable encryption
+and the Linux `basic_text` backend. Other adapters must protect their keys outside the credential
+file and provide authenticated encryption. For a Node service, use a host-owned keystore through
+`recordStore(load, save)`, or provide an equivalent sealing adapter; the kit never discovers a key
+or invokes an OS keyring itself. Use `memoryStore()` for temporary sign-ins.
+
+Use an app-owned directory: the immediate folder must be a real 0700 directory and credential
+files must be private regular files. Reuse one store instance for each path; a host lock is required
+if several processes write the same file. See [SECURITY.md](SECURITY.md) for the threat model and limits.
+
+**Migration from 0.7.x and earlier:** `fileStore(path)` is no longer accepted. Existing files already
+sealed with the same adapter remain readable. Plain JSON is never silently imported or overwritten.
+For a plaintext store, stop all writers, revoke the old credentials using the old app's sign-out flow,
+remove the old app-owned credential file, and sign in again with a sealing adapter. Old plaintext
+backups may retain tokens: delete them under the host's retention policy and revoke the affected
+credentials. Do not point this migration at another tool's sign-in directory.

package/SECURITY.md

@@ -0,0 +1,99 @@
+# Accounts security
+
+Review scope: accounts credential storage, sign-in failure logging, provider isolation and
+portable platform boundaries, reviewed 2026-09-30. This is a source review with offline
+regression tests, not an independent cryptographic audit or a live OS keychain certification.
+
+## Assets and trust boundaries
+
+OAuth access and refresh tokens, API keys, identity/plan claims, device sign-in codes and
+callback state are sensitive. The host selects each member's store, provider offer and
+platform adapter. The kit uses only those stores; it never imports another application's
+credentials. The computer engine is exactly pinned in package.json and isolated from
+ambient credential discovery. The Node entry has filesystem access; browser and React
+Native entries exclude runtime Node and engine imports.
+
+The provider and network are outside the storage boundary. OAuth sign-in sends codes and
+tokens only to the configured provider endpoints over TLS in production. Host-supplied
+endpoint overrides, adapters and fetch implementations are trusted code: production hosts
+must not substitute untrusted endpoints. Callback state binds the loopback return to the
+pending sign-in; a code or consent URL must be shown only to its intended member.
+
+## At rest
+
+`fileStore(path, adapter)` requires sealing. No encryption key is generated beside the
+credential file and no plaintext fallback exists. Electron hosts pass safeStorage after
+ready. When reported, unavailable encryption and the Linux basic_text backend are refused
+at construction and on each operation. An equivalent adapter is trusted to use authenticated
+encryption and keep its key outside this file, preferably in an OS keyring. An arbitrary
+adapter can lie about sealing; this seam cannot certify the host's implementation.
+
+New immediate directories are 0700; existing immediate directories must be real 0700
+directories. Reads use O_NOFOLLOW, then inspect the opened descriptor for a private regular
+file; nonblocking opens avoid waiting on a substituted FIFO. Writes seal before opening a
+random temporary path with O_EXCL (wx) and O_NOFOLLOW, mode 0600, sync the file (except under Node's permission model, which disables fsync), then rename
+it atomically. Cleanup removes only a temporary file this operation successfully created.
+A legacy predictable .tmp path is never opened. Decryption and parse failures propagate;
+corrupt or plaintext files are never replaced as an automatic recovery step.
+
+The host must own the entire parent path and prevent concurrent directory replacement.
+These POSIX checks do not resolve or pin every ancestor: malicious parent directories,
+mounts, a process running as the same OS user, root, and compromised host code are outside
+this boundary. Windows hosts must also configure private ACLs; POSIX mode bits and
+O_NOFOLLOW are not a substitute for Windows access controls. Atomic rename avoids partial
+records, but the directory is not synced: recovery after sudden power loss is not guaranteed.
+Use one store instance per path and a host lock for multiple processes. Encryption does
+not prevent deletion, rollback to an older sealed record, or leaking credentials in memory.
+
+Browser IndexedDB is origin-scoped plaintext accessible to scripts in that origin. The host
+must prevent XSS and untrusted scripts; a browser cannot promise OS-keychain protection.
+React Native secureStore delegates protection and device accessibility policy to the
+host's Keychain/Keystore adapter. memoryStore holds credentials only in process memory.
+Host-defined recordStore persistence inherits the host backend's security properties.
+
+## Logs, sign-out and isolation
+
+Default sign-in and discarded-credential revoke diagnostics contain fixed messages only,
+not raw provider errors, member identifiers, credentials, callback URLs or nested causes.
+The host's onSignOutError callback receives the underlying error for handling: do not log
+that error without sanitizing it. Other host-visible error/event payloads and model content
+can also be sensitive; the kit does not redact arbitrary host logging or dump memory.
+
+Sign-out attempts provider revocation and removes the local credential even on failure.
+A generation check discards late sign-ins/refreshes so they cannot restore a signed-out
+credential. Revocation failure means a copied token may remain usable at the provider.
+Deleting local files alone does not revoke tokens, and deletion cannot erase old backups.
+
+Tests use fake providers, temporary homes, filesystem canaries and Node permissions;
+`npm test` blocks outbound networking and checks the owner's existing setup byte for byte.
+The kit never invokes the owner's installed tools or borrows environment API keys.
+
+## Review record
+
+- [x] Required sealing; unavailable and basic_text Electron backends fail closed, including
+  availability changing after construction (`test/units.test.ts`).
+- [x] Sealed credentials round-trip without plaintext access/refresh tokens on disk;
+  existing sealed adapter format is preserved (`test/units.test.ts`).
+- [x] Target and immediate-directory symlinks and permissive modes are refused; a decoy
+  .tmp symlink is unchanged; encryption failure preserves the prior file and random temp
+  files are cleaned after successful replacement (`test/units.test.ts`).
+- [x] Sign-in and failed late-revoke logs use fixed messages, exercised with credential
+  canaries in injected failures (`test/accounts.test.ts`, `test/revoke.test.ts`).
+- [x] Revocation and late completion use offline fake-provider regression coverage
+  (`test/revoke.test.ts`); isolation and portable imports retain their existing tests
+  (`test/isolation.test.ts`, `test/portable.test.ts`).
+
+Run `npm run build`, `npm run check` and `npm test` to reproduce the review checks.
+Live Electron/OS keyring security and host adapter configuration remain the host's responsibility.
+
+## Reporting and migration
+
+Report a vulnerability privately through this repository's GitHub Security Advisories:
+https://github.com/umeranjum17/byokit/security/advisories/new . Do not include live tokens
+in an issue, logs, screenshots or a public reproduction. Include the package version,
+platform, affected seam and an offline reproduction using synthetic credentials.
+
+For legacy plaintext files, follow the README's migration: stop writers, revoke through
+the old app, remove only the app-owned credential file and sign in again using sealing.
+Previously sealed files need only the same adapter passed explicitly. There is no silent
+plaintext migration and no recovery by replacing a file that fails to decrypt.

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();
@@ -114,7 +126,7 @@ export class Accounts {
                             if (this.onSignOutError)
                                 this.onSignOutError(member, p.key, error);
                             else
-                                console.error(`sign-out ${p.key} for member ${member}:`, error);
+                                console.error('Sign-out of a discarded credential failed');
                             throw error;
                         }
                     }
@@ -391,8 +403,8 @@ export class Accounts {
             if (flow.state !== 'waiting')
                 return; // cancelled: already settled
             const error = String(e?.message ?? e);
-            console.error(`sign-in ${key} for member ${member}:`, error);
             const why = e?.why ?? (flow.timedOut ? 'tooLong' : failure(error));
+            console.error('Sign-in failed');
             Object.assign(flow, { state: 'failed', url: undefined, code: undefined, expiresAt: undefined, why,
                 error: why === 'busy' || why === 'tooLong' ? say(`signIn.${why}`, { name: p.name }) : signInError(p.name, error) });
         }
@@ -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,10 +1,13 @@
-import type { CredentialStore } from '@earendil-works/pi-ai';
-/** The parts of Electron's `safeStorage` this uses; pass `safeStorage` from 'electron' (main process, after `ready`). */
+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 = {
     encryptString(text: string): Uint8Array;
     decryptString(data: Buffer): string;
+    isEncryptionAvailable?(): boolean;
+    getSelectedStorageBackend?(): 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;
+/** 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): EndingStore;

package/dist/node-stores.js

@@ -1,27 +1,91 @@
-// 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';
+// Desktop stores: sealed with a host-supplied adapter, such as Electron's safeStorage.
+import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 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. */
+/** 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 function fileStore(path, safeStorage) {
+    const ready = () => {
+        if (!safeStorage || typeof safeStorage.encryptString !== 'function' || typeof safeStorage.decryptString !== 'function') {
+            throw new TypeError('fileStore requires a sealing adapter');
+        }
+        if (safeStorage.isEncryptionAvailable?.() === false || safeStorage.getSelectedStorageBackend?.() === 'basic_text') {
+            throw new Error('Secure credential storage is unavailable');
+        }
+    };
+    ready();
+    const folder = dirname(path);
+    const privateFolder = () => {
+        const st = lstatSync(folder);
+        if (!st.isDirectory() || (st.mode & 0o777) !== 0o700)
+            throw new Error('Credential storage requires a private 0700 folder');
+    };
     const load = async () => {
+        ready();
+        let fd;
         try {
-            const raw = readFileSync(path);
-            return JSON.parse(safeStorage ? safeStorage.decryptString(raw) : raw.toString('utf8'));
+            privateFolder();
+            fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
         }
         catch (e) {
             if (e?.code === 'ENOENT')
                 return {};
             throw e;
         }
+        try {
+            const st = fstatSync(fd);
+            if (!st.isFile() || (st.mode & 0o077))
+                throw new Error('Credential storage requires a private regular file');
+            return JSON.parse(safeStorage.decryptString(readFileSync(fd)));
+        }
+        finally {
+            closeSync(fd);
+        }
     };
     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);
+        ready();
+        const sealed = safeStorage.encryptString(JSON.stringify(data, null, 2));
+        mkdirSync(folder, { recursive: true, mode: 0o700 });
+        privateFolder();
+        const tmp = `${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`;
+        let created = false;
+        try {
+            // O_EXCL is the numeric equivalent of wx; O_NOFOLLOW also forbids a symlink.
+            const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            created = true;
+            try {
+                writeFileSync(fd, sealed);
+                // Node's permission model disables fsync even for permitted descriptors.
+                if (!process.permission)
+                    fsyncSync(fd);
+            }
+            finally {
+                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)
+                try {
+                    unlinkSync(tmp);
+                }
+                catch (e) {
+                    if (e?.code !== 'ENOENT')
+                        throw e;
+                }
+        }
     };
     return recordStore(load, save);
 }

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.7.1",
+  "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",
@@ -40,7 +40,8 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"