@byokit/openclaw 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.3.3 (2026-09-30)
+
+- Dependency update: pins @byokit/secrets 0.5.0.
+
+- SECURITY: Opt-in dual-wrap credential upgrades are authenticated and atomically replaced under the store lock; protection is only as strong as the owner-only host-key file, which must stay out of sealed-store backups.
+- FIX: A locked or unresponsive keyring no longer throws from prepare or start. The kit reports a locked saved sign-in in plain words, preserves the sealed store and retries normally on a later start after unlock; dual-wrapped stores open through their host key without prompting.
+
+- FIX: ChatGPT subscription device pairing was blocked by the plugin allowlist unless the app added the provider plugin itself. The kit now merges every offered route's provider plugin with the bridge and caller-provided plugins, without adding plugins for unoffered routes.
+- Label the explicit Anthropic route as API key (billed per use), keeping API and plan routes off by default.
+
 ## 0.3.2 (2026-09-30)
 
 - Dependency update: pins @byokit/secrets 0.4.0.

package/README.md

@@ -172,8 +172,16 @@ The pinned engine has no supported hook for sealing OAuth profile writes. Its `a
 credential JSON in agent SQLite databases and a shared state database, and doctor imports leave migration
 archives. `authSeal` therefore protects the complete isolated `state` and `home` directories, including SQLite
 journals. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
-falls back to a persistent private file key when no non-interactive keyring is available, including
-locked or unresponsive Linux keyrings; existing `authSeal` calls pick up the chain unchanged.
+uses a persistent private file key for new stores when no non-interactive keyring is available.
+Opening follows the saved envelope's mode. A locked or unresponsive keyring-only store leaves
+`kit.state.phase === 'locked'`: `prepare()` and `start()` resolve, show `stateWords(kit.state)` for
+recovery, and keep the sealed snapshot unchanged without launching the engine. Call `start()` again
+after unlock to restore the same credentials, even if a fallback key directory now exists.
+
+For hosts whose keyring stays locked, opt into `osKeyringSeal({ service, dualWrap: true })`.
+While unlocked, reading an existing keyring-only snapshot atomically upgrades it to dual-wrap.
+Later starts and stops can use the host wrap without prompting. Default off: **protection is only
+as strong as the owner-only host-key file**, which must stay outside sealed-store backups.
 
 ```ts
 import { osKeyringSeal, hostKeySeal } from '@byokit/secrets';
@@ -187,7 +195,7 @@ await kit.prepare(); // seals an existing plaintext store and migration archives
 await kit.start();   // authenticates and restores the isolated files for the engine
 await kit.stop();    // waits for exit, verifies an atomic sealed snapshot, then removes plaintext
 
-// Inspect the adapter's mode for host UI: 'keyring' or 'host-key-file'.
+// Inspect the adapter's write mode: 'keyring', 'host-key-file' or opt-in 'dual-wrap'.
 // Hosts can also explicitly supply a 32-byte key kept outside stateDir and its backups:
 declare const hostKey: Uint8Array;
 const server = new OpenClawKit({
@@ -200,7 +208,8 @@ The automatic key lives in the platform state directory, separate from the engin
 on the same disk protects copied stores/backups only when the key directory is excluded; it does
 not protect against code running as the same OS user. See [secrets' rotation and threat model](../secrets/README.md#servers-and-headless-node).
 Stop the kit, acquire the host writer lock and call `seal.rotate()` with `auth-store.sealed` plus
-every retained sealed migration archive before retiring an automatic key.
+every retained sealed migration archive before retiring an automatic key. Rotate each envelope mode
+separately; dual-wrap rotation retains old wrapping keys for backups.
 
 Without `authSeal`, engine credentials remain plaintext. With it, successful `prepare()` and `stop()` leave
 only a sealed snapshot, `auth-store.sealed`, for those directories. The adapter authenticates the snapshot

package/SECURITY.md

@@ -23,6 +23,13 @@ running as the app's user, a compromised host/engine/plugin, or readable backups
 The isolated environment and tool gate are not an OS filesystem/network sandbox.
 The app must sandbox `ToolHost.call` and judge requests in `ToolHost.gate`.
 
+A locked or unresponsive keyring leaves the sealed snapshot unchanged. `prepare()` and `start()`
+resolve with `phase: 'locked'`, do not restore plaintext or launch the engine, and a later start
+retries after unlock. Opt-in dual wrapping opens through an owner-only host key without prompting;
+its protection is only as strong as that file, which must stay outside sealed-store backups.
+Unlocked keyring-only snapshots upgrade atomically under the store's exclusive lock after verifying
+the replacement decrypts to identical contents. Other sealing failures still reject.
+
 ## Secrets at rest and in memory
 
 | Asset | Location relative to `stateDir` | Protection and consequence of theft |

package/dist/auth-store.js

@@ -149,7 +149,17 @@ export class AuthStore {
         if (!existsSync(this.file))
             return undefined;
         regular(this.file);
-        return snapshot(this.o.seal.decryptString(readFileSync(this.file)));
+        const seal = this.o.seal;
+        const bytes = readFileSync(this.file);
+        const text = seal.decryptString(bytes);
+        const saved = snapshot(text);
+        const upgraded = seal.upgrade?.(bytes);
+        if (upgraded) {
+            if (seal.decryptString(Buffer.from(upgraded)) !== text)
+                throw new Error('credential upgrade verification failed');
+            put(this.file, upgraded);
+        }
+        return saved;
     }
     collect() {
         const s = { v: 1, dirs: [], files: [] };

package/dist/config.js

@@ -1,4 +1,5 @@
 import { dirname, join } from 'node:path';
+import { routes } from "./routes.js";
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const merge = (a, b) => {
     for (const [k, v] of Object.entries(b))
@@ -53,7 +54,8 @@ export function reconcileConfig(saved, o) {
     c.plugins ??= {};
     c.plugins.load ??= {};
     c.plugins.load.paths = [...new Set([...(c.plugins.load.paths ?? []).filter((p) => !p.includes('byokit-openclaw-bridge')), o.pluginDir])];
-    c.plugins.allow = [...new Set([...(c.plugins.allow ?? []), o.pluginId])];
+    c.plugins.allow = [...new Set([...(c.plugins.allow ?? []), o.pluginId,
+            ...routes().filter(route => route.offer && route.plugin).map(route => route.plugin)])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
     c.security ??= {};

package/dist/engine.d.ts

@@ -16,6 +16,7 @@ export declare class Engine {
     private starting?;
     private readonly authStore;
     private stopping;
+    private credentialsLocked;
     private repaired;
     private prepared?;
     private port;
@@ -40,7 +41,8 @@ export declare class Engine {
         port: number;
         token: string;
         identityPath: string;
-    }>;
+    } | undefined>;
+    private locked;
     private startOnce;
     private launch;
     withAuthStore<T>(task: () => Promise<T>): Promise<T>;

package/dist/engine.js

@@ -52,6 +52,7 @@ export class Engine {
     starting;
     authStore;
     stopping = false;
+    credentialsLocked = false;
     repaired = false;
     prepared;
     port = 0;
@@ -94,7 +95,15 @@ export class Engine {
             throw new Error('authSeal required for sealed credential store');
         for (const d of [this.root, ...(!this.o.authSeal ? [join(this.root, 'home'), join(this.root, 'state')] : []), join(this.root, 'tmp'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs'), this.dir])
             mkdirSync(d, { recursive: true, mode: 0o700 });
-        await this.authStore.prepare();
+        try {
+            await this.authStore.prepare();
+            this.credentialsLocked = false;
+        }
+        catch (error) {
+            if (this.locked(error))
+                return;
+            throw error;
+        }
         if (this.o.spawnEngine) {
             const versionPath = join(this.dir, 'node_modules', 'openclaw', 'package.json');
             if (!existsSync(this.entry) || !installMatches(this.dir)) {
@@ -183,9 +192,25 @@ export class Engine {
             this.starting = undefined; }).catch(() => { });
         return pending;
     }
+    locked(error) {
+        if (!(error instanceof Error) || error.name !== 'KeystoreError' || !('code' in error) || error.code !== 'keyring-locked')
+            return false;
+        this.credentialsLocked = true;
+        this.state('locked');
+        return true;
+    }
     async startOnce() {
         await this.prepare();
-        await this.authStore.start();
+        if (this.credentialsLocked)
+            return undefined;
+        try {
+            await this.authStore.start();
+        }
+        catch (error) {
+            if (this.locked(error))
+                return undefined;
+            throw error;
+        }
         try {
             return this.launch();
         }
@@ -275,7 +300,8 @@ export class Engine {
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;
         rmSync(join(this.root, 'gateway.pid'), { force: true });
-        await this.authStore.stop();
+        if (!this.credentialsLocked)
+            await this.authStore.stop();
         rmSync(this.bridgeSock, { force: true });
         this.state('stopped');
     }

package/dist/kit.js

@@ -468,7 +468,7 @@ export class OpenClawKit {
         let transport;
         try {
             const ctx = await this.engine.start();
-            if (this.stopping)
+            if (!ctx || this.stopping)
                 return;
             this.setState({ phase: 'starting' });
             transport = (this.o.transport ?? gatewayTransport)({ ...ctx, bridgeSock: this.engine.bridgeSock });

package/dist/routes.d.ts

@@ -1,7 +1,8 @@
 import type { Route } from './types.ts';
 /** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
  *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin the app must allow for that route to start (5.6). Only the pin's bundled provider contracts are
+ *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
+ *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
  *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
  *  are deliberately absent. */
 export declare function routes(): Route[];

package/dist/routes.js

@@ -3,7 +3,8 @@ import routesJson from './routes.json' with { type: 'json' };
 const table = routesJson;
 /** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
  *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin the app must allow for that route to start (5.6). Only the pin's bundled provider contracts are
+ *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
+ *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
  *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
  *  are deliberately absent. */
 export function routes() {

package/dist/routes.json

@@ -117,7 +117,7 @@
         "via": "browser",
         "prerequisite": "the Claude CLI, signed in inside the engine's own folder",
         "offer": false,
-        "reason": "byokit never adds Claude plan sign-in",
+        "reason": "Requires an explicit app opt-in; the pinned Gateway does not expose this plan route",
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
     },
     {
@@ -128,7 +128,7 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; never offered (D12): no Anthropic API fallback.",
+        "reason": "API key (billed per use); shown only when an app explicitly asks.",
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
     },
     {
@@ -348,7 +348,7 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "byokit never adds Claude plan sign-in",
+        "reason": "Requires an explicit app opt-in; the pinned Gateway does not expose this plan route",
         "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
     },
     {

package/dist/types.d.ts

@@ -108,7 +108,7 @@ export type Decision = {
     answer?: unknown;
 };
 export type KitState = {
-    phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update';
+    phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
     why?: 'install' | 'handshake' | 'exited' | 'port' | 'version';
     retryAt?: number;
 };

package/dist/words.js

@@ -14,6 +14,7 @@ const PHASE_WORDS = {
     ready: 'engine.ready',
     restarting: 'engine.restarting',
     failed: 'engine.failed',
+    locked: 'engine.locked',
     'needs-update': 'engine.needsUpdate',
 };
 export function stateWords(s) {

package/dist/words.json

@@ -2,6 +2,7 @@
     "engine.installing": "Getting things ready on this computer. The first time takes a few minutes.",
     "engine.starting": "Starting up…",
     "engine.repairing": "Fixing a small problem with the setup. This takes a moment.",
+    "engine.locked": "Your saved sign-in is locked. Unlock your password storage, then try again.",
     "engine.ready": "Ready.",
     "engine.restarting": "Something stopped. Starting it again by itself.",
     "engine.failed": "This computer couldn't start the helper. Restart the app to try again.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -56,7 +56,7 @@
     "@byokit/relay": "0.4.2",
     "@byokit/reach": "0.4.0",
     "@byokit/seal": "0.2.0",
-    "@byokit/secrets": "0.4.0",
+    "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.8.1",
     "@openclaw/gateway-protocol": "2026.8.1",
     "ws": "8.21.3"