@byokit/accounts 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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,12 +184,12 @@ 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
 fallback.
@@ -299,3 +301,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.js

@@ -114,7 +114,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 +391,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) });
         }

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`). */
+/** 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): CredentialStore;

package/dist/node-stores.js

@@ -1,27 +1,81 @@
-// 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);
+        }
+        finally {
+            if (created)
+                try {
+                    unlinkSync(tmp);
+                }
+                catch (e) {
+                    if (e?.code !== 'ENOENT')
+                        throw e;
+                }
+        }
     };
     return recordStore(load, save);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.7.1",
+  "version": "0.8.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"