@byokit/openclaw 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-09-30)
+
+
+
+- SECURITY: Provider access and refresh tokens persisted in plaintext engine stores; hosts can now pass `authSeal` from `@byokit/secrets` to seal the isolated stores while stopped and protect migration archives. Upgrade and call `prepare()` with an OS-keyring or host-owned-key adapter; protect live state and backups separately.
+- SECURITY: Verified retained-login sources are removed instead of archived in plaintext; existing confirmed copies and engine migration archives are removed or sealed on the next prepare.
+
+## 0.2.5 (2026-09-30)
+
+- Dependency update: pins @byokit/relay 0.4.2.
+- Dependency update: pins @byokit/link 0.6.0.
+
+## 0.2.4 (2026-09-30)
+
+- Dependency update: pins @byokit/relay 0.4.1.
+- Dependency update: pins @byokit/link 0.5.1.
+- FIX: (from @byokit/link 0.5.1) Reject an authenticated empty transport frame instead of decoding it as an empty control message.
+
+
+## 0.2.3 (2026-09-30)
+
+
+
+- FIX: `prepare()` repairs stale engine manifests and missing or wrong-version dependencies before reusing an installed engine.
+
+
 ## 0.2.2 (2026-09-30)
 
 - Depends on @byokit/relay 0.4.0.

package/README.md

@@ -166,6 +166,62 @@ The kit writes only under the `stateDir` the app passes. It spawns the engine wi
 (never `process.env`), reads no environment variables except `PATH` to find `npm`, and never bills an API behind the
 person's back (memory search is never a paid provider).
 
+## Credential sealing and threat model
+
+The pinned engine has no supported hook for sealing OAuth profile writes. Its `auth-profiles` loader stores
+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 same injected `SealingAdapter` as `@byokit/secrets`; the kit creates no sealing key.
+
+```ts
+import { osKeyringSeal, hostKeySeal } from '@byokit/secrets';
+import { OpenClawKit } from '@byokit/openclaw';
+
+const kit = new OpenClawKit({
+  stateDir: './openclaw-state',
+  authSeal: osKeyringSeal({ service: 'my-app-runtime' }),
+});
+await kit.prepare(); // seals an existing plaintext store and migration archives without starting the engine
+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
+
+// A headless server supplies its own 32-byte key, held outside stateDir and its backups:
+declare const hostKey: Uint8Array;
+const server = new OpenClawKit({
+  stateDir: './server-state',
+  authSeal: hostKeySeal({ key: hostKey, service: 'my-app-runtime' }),
+});
+```
+
+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
+before any restoration; a wrong key, tampering, or a missing adapter rejects. Files restored for the engine
+have mode 0600 and directories 0700. Symlinks and special files inside the sealed directories are refused.
+One kit owns the store at a time; a live owner or orphan gateway blocks preparation instead of racing its writes.
+Sealing copies the whole store through memory, so startup and stop cost grows with session history.
+
+The migration doctor temporarily opens the same store and reseals it even when import fails. Once the gateway
+verifies every provider, `confirmRetainedLogin()` removes the explicitly passed legacy source and writes only
+an empty completion marker. It no longer creates a plaintext `.moved-to-engine` copy. On prepare, old engine
+`*.json.migrated-*` and `*.json.sqlite-import.*.bak` archives and retained copies under `stateDir` are sealed
+with the adapter (a `credential archive sealed` log event). Without an adapter, engine archives and confirmed
+retained copies are removed (`verified credential archive removed`). An unconfirmed retained copy remains a
+migration source until verified or sealed; pass its original path to migration to recover a sealed copy.
+Archives stay sealed and are never restored as engine input. External source paths are handled only when the
+host explicitly passes them to migration/confirmation. An app supplying a record still removes its own copy.
+
+Residual risk: credentials are plaintext on disk and in process memory while the gateway or migration doctor
+runs. Abrupt host termination or power loss cannot run stop cleanup: next prepare seals leftover live files,
+but refuses while the old gateway is alive. Interrupted restore/removal is recovered from the authenticated
+snapshot. A sealing failure rejects stop and retains recoverable live files; the host must resolve it and retry.
+Await `stop()` during orderly shutdown. File removal does not erase old filesystem blocks, snapshots, swap or
+backups; use an encrypted volume and exclude live state from backups. A same-user process, administrator,
+compromised engine/plugin, memory dump, or stolen host key can read credentials. There is no rollback protection
+against replacement with an older authentic snapshot. Gateway/device keys, inline config secrets, logs, engine
+install/cache files and app workspaces are outside this adapter's sealing scope; protect them separately.
+`doctorContext()` is an advanced escape hatch: launching an external doctor bypasses this lifecycle; use the
+kit's migration method for sealed stores.
+
 ## Status
 
 Pinned to OpenClaw `2026.8.1` (protocol 4); `ENGINE_VERSION` and `PROTOCOL_VERSION` carry the pin. Signatures are

package/dist/auth-store.d.ts

@@ -0,0 +1,32 @@
+import type { SealingAdapter } from '@byokit/secrets';
+export declare class AuthStore {
+    private active;
+    private owned;
+    private queue;
+    private readonly file;
+    private readonly lock;
+    private readonly cleanup;
+    private readonly restoring;
+    constructor(privateOptions: {
+        root: string;
+        stateDir: string;
+        engineDir: string;
+        seal?: SealingAdapter;
+        log?: (line: string) => void;
+    });
+    private readonly o;
+    private serial;
+    private acquire;
+    private release;
+    private read;
+    private collect;
+    private persist;
+    private restore;
+    archives(): Promise<void>;
+    prepare(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    offline<T>(task: () => Promise<T>): Promise<T>;
+}
+/** A retired archive is never restored as a live engine source. */
+export declare function retireArchive(path: string, seal?: SealingAdapter, log?: (line: string) => void): Promise<void>;

package/dist/auth-store.js

@@ -0,0 +1,320 @@
+// The pin persists OAuth JSON in both shared and agent SQLite. There is no public persistence hook.
+// Seal the complete isolated stores, including journals, only after their writer has exited.
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+const encoder = new TextEncoder();
+const archive = (name) => /^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)
+    || name.endsWith('.moved-to-engine');
+const live = (pid) => {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+};
+function regular(path) {
+    if (!lstatSync(path).isFile())
+        throw new Error('credential store requires regular files');
+}
+function syncDir(path) {
+    if (process.platform === 'win32')
+        return;
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function removeMarker(path) {
+    rmSync(path, { force: true });
+    syncDir(dirname(path));
+}
+function put(path, bytes) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.sealing-${process.pid}`;
+    try {
+        writeFileSync(tmp, bytes, { mode: 0o600, flag: 'wx' });
+        const fd = openSync(tmp, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+        // POSIX directory fsync makes the rename durable before any plaintext is removed.
+        syncDir(dirname(path));
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+function safePath(path) {
+    return typeof path === 'string' && /^(state|home)(\/[^/]+)*$/.test(path)
+        && !path.split('/').some((part) => part === '.' || part === '..' || part.includes('\\') || part.includes('\0'));
+}
+function snapshot(text) {
+    const s = JSON.parse(text);
+    if (s?.v !== 1 || !Array.isArray(s.dirs) || !Array.isArray(s.files))
+        throw new Error('invalid sealed credential store');
+    const paths = new Set();
+    for (const path of s.dirs) {
+        if (!safePath(path) || paths.has(path))
+            throw new Error('invalid sealed credential path');
+        paths.add(path);
+    }
+    for (const entry of s.files) {
+        if (!Array.isArray(entry) || entry.length !== 2 || !safePath(entry[0]) || typeof entry[1] !== 'string'
+            || paths.has(entry[0]) || Buffer.from(entry[1], 'base64').toString('base64') !== entry[1])
+            throw new Error('invalid sealed credential file');
+        paths.add(entry[0]);
+        if (!s.dirs.includes(dirname(entry[0])))
+            throw new Error('invalid sealed credential parent');
+    }
+    for (const path of s.dirs)
+        if (path.includes('/') && !s.dirs.includes(dirname(path)))
+            throw new Error('invalid sealed credential parent');
+    return s;
+}
+export class AuthStore {
+    active = false;
+    owned = false;
+    queue = Promise.resolve();
+    file;
+    lock;
+    cleanup;
+    restoring;
+    constructor(privateOptions) {
+        this.o = privateOptions;
+        this.file = join(this.o.root, 'auth-store.sealed');
+        this.lock = join(this.o.root, 'auth-store.lock');
+        this.cleanup = join(this.o.root, 'auth-store.cleanup');
+        this.restoring = join(this.o.root, 'auth-store.restoring');
+    }
+    o;
+    serial(task) {
+        const pending = this.queue.then(task);
+        this.queue = pending.catch(() => { });
+        return pending;
+    }
+    acquire() {
+        if (this.owned)
+            return;
+        if (existsSync(this.file) && !this.o.seal)
+            throw new Error('authSeal required for sealed credential store');
+        if (!this.o.seal)
+            return;
+        // Never race a live gateway or another kit, including an orphan after its host crashed.
+        const gateway = join(this.o.root, 'gateway.pid');
+        if (existsSync(gateway) && live(Number(readFileSync(gateway, 'utf8'))))
+            throw new Error('credential store is in use');
+        if (existsSync(this.lock)) {
+            if (!lstatSync(this.lock).isDirectory() || lstatSync(this.lock).isSymbolicLink())
+                throw new Error('invalid credential lock');
+            const owner = join(this.lock, 'pid');
+            if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8'))))
+                throw new Error('credential store is in use');
+            // Only one stale-owner recovery can proceed. Recheck after claiming it so a stale reader
+            // cannot remove the lock a newer owner has just acquired.
+            const recovery = join(this.lock, 'recovery');
+            try {
+                mkdirSync(recovery, { mode: 0o700 });
+            }
+            catch {
+                throw new Error('credential store is in use');
+            }
+            if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8')))) {
+                rmSync(recovery, { recursive: true });
+                throw new Error('credential store is in use');
+            }
+            rmSync(this.lock, { recursive: true });
+        }
+        mkdirSync(this.lock, { mode: 0o700 });
+        writeFileSync(join(this.lock, 'pid'), String(process.pid), { mode: 0o600, flag: 'wx' });
+        this.owned = true;
+    }
+    release() {
+        if (!this.owned)
+            return;
+        rmSync(this.lock, { recursive: true });
+        this.owned = false;
+    }
+    async read() {
+        if (!existsSync(this.file))
+            return undefined;
+        regular(this.file);
+        return snapshot(this.o.seal.decryptString(readFileSync(this.file)));
+    }
+    collect() {
+        const s = { v: 1, dirs: [], files: [] };
+        const walk = (path) => {
+            const name = relative(this.o.root, path).split('\\').join('/');
+            const stat = lstatSync(path);
+            if (stat.isDirectory()) {
+                chmodSync(path, 0o700);
+                s.dirs.push(name);
+                for (const child of readdirSync(path).sort())
+                    walk(join(path, child));
+                return;
+            }
+            regular(path);
+            chmodSync(path, 0o600);
+            s.files.push([name, readFileSync(path).toString('base64')]);
+        };
+        for (const dir of ['state', 'home'])
+            if (existsSync(join(this.o.root, dir)))
+                walk(join(this.o.root, dir));
+        return s;
+    }
+    async persist() {
+        if (!this.o.seal)
+            return;
+        // Always authenticate an earlier snapshot before considering a leftover live store after a crash.
+        const previous = await this.read();
+        if (previous && (existsSync(this.cleanup) || existsSync(this.restoring))) {
+            for (const dir of ['state', 'home'])
+                rmSync(join(this.o.root, dir), { recursive: true, force: true });
+            removeMarker(this.cleanup);
+            removeMarker(this.restoring);
+            this.o.log?.('interrupted credential transition recovered');
+        }
+        const hasLive = ['state', 'home'].some((dir) => existsSync(join(this.o.root, dir)));
+        if (!hasLive && previous)
+            return;
+        const text = JSON.stringify(this.collect());
+        const sealed = this.o.seal.encryptString(text);
+        if (this.o.seal.decryptString(Buffer.from(sealed)) !== text)
+            throw new Error('credential seal verification failed');
+        put(this.file, sealed);
+        if (this.o.seal.decryptString(readFileSync(this.file)) !== text)
+            throw new Error('credential seal verification failed');
+        put(this.cleanup, encoder.encode('1'));
+        for (const dir of ['state', 'home'])
+            rmSync(join(this.o.root, dir), { recursive: true, force: true });
+        removeMarker(this.cleanup);
+    }
+    async restore() {
+        if (!this.o.seal)
+            return;
+        const saved = await this.read();
+        // A crashed host may leave a newer live state; prepare seals that before restore.
+        put(this.restoring, encoder.encode('1'));
+        if (saved) {
+            for (const dir of saved.dirs.sort((a, b) => a.split('/').length - b.split('/').length))
+                mkdirSync(join(this.o.root, dir), { recursive: true, mode: 0o700 });
+            for (const [path, data] of saved.files)
+                put(join(this.o.root, path), Buffer.from(data, 'base64'));
+        }
+        for (const dir of ['state', 'home'])
+            mkdirSync(join(this.o.root, dir), { recursive: true, mode: 0o700 });
+        removeMarker(this.restoring);
+    }
+    async archives() {
+        const ignored = new Set([resolve(this.o.engineDir), ...['npm-cache', 'install-home', 'tmp', 'plugin', 'workspaces'].map((d) => resolve(this.o.root, d))]);
+        const walk = async (dir) => {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const path = join(dir, entry.name);
+                if (ignored.has(resolve(path)) || entry.isSymbolicLink())
+                    continue;
+                if (entry.isDirectory()) {
+                    await walk(path);
+                    continue;
+                }
+                if (!entry.isFile() || !archive(entry.name))
+                    continue;
+                if (!this.o.seal && entry.name.endsWith('.moved-to-engine') && !existsSync(path + '.canonicalized'))
+                    continue;
+                await retireArchive(path, this.o.seal, this.o.log);
+            }
+        };
+        if (existsSync(this.o.stateDir))
+            await walk(this.o.stateDir);
+    }
+    prepare() {
+        return this.serial(async () => {
+            if (this.active)
+                return;
+            this.acquire();
+            try {
+                await this.read();
+                await this.archives();
+                await this.persist();
+            }
+            finally {
+                this.release();
+            }
+        });
+    }
+    start() {
+        return this.serial(async () => {
+            if (this.active)
+                return;
+            this.acquire();
+            try {
+                await this.restore();
+                this.active = true;
+            }
+            catch (error) {
+                this.release();
+                throw error;
+            }
+        });
+    }
+    stop() {
+        return this.serial(async () => {
+            this.acquire();
+            await this.archives();
+            await this.persist();
+            this.active = false;
+            this.release();
+        });
+    }
+    offline(task) {
+        return this.serial(async () => {
+            if (this.active)
+                throw new Error('credential migration requires a stopped engine');
+            this.acquire();
+            try {
+                await this.restore();
+                try {
+                    return await task();
+                }
+                finally {
+                    await this.archives();
+                    await this.persist();
+                }
+            }
+            finally {
+                this.release();
+            }
+        });
+    }
+}
+/** A retired archive is never restored as a live engine source. */
+export async function retireArchive(path, seal, log) {
+    regular(path);
+    if (seal) {
+        const bytes = readFileSync(path);
+        try {
+            const text = bytes.toString('base64');
+            const sealed = seal.encryptString(text);
+            if (seal.decryptString(Buffer.from(sealed)) !== text)
+                throw new Error('archive seal verification failed');
+            put(path + '.sealed', sealed);
+            if (seal.decryptString(readFileSync(path + '.sealed')) !== text)
+                throw new Error('archive seal verification failed');
+        }
+        finally {
+            bytes.fill(0);
+        }
+    }
+    rmSync(path);
+    syncDir(dirname(path));
+    log?.(seal ? 'credential archive sealed' : 'verified credential archive removed');
+}

package/dist/engine.d.ts

@@ -1,6 +1,6 @@
 import type { KitOptions } from './kit.ts';
 import type { KitState, ToolSpec } from './types.ts';
-export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'installPolicy' | 'log' | 'bridge'> & {
+export type EngineOptions = Pick<KitOptions, 'stateDir' | 'engineDir' | 'npmPath' | 'enginePath' | 'config' | 'installPolicy' | 'log' | 'bridge' | 'authSeal'> & {
     pluginId: string;
     tools: ToolSpec[];
     gateBuiltins?: boolean;
@@ -13,6 +13,8 @@ export declare class Engine {
     readonly bridgeSock: string;
     private readonly dir;
     private child?;
+    private starting?;
+    private readonly authStore;
     private stopping;
     private repaired;
     private prepared?;
@@ -39,5 +41,8 @@ export declare class Engine {
         token: string;
         identityPath: string;
     }>;
+    private startOnce;
+    private launch;
+    withAuthStore<T>(task: () => Promise<T>): Promise<T>;
     stop(): Promise<void>;
 }

package/dist/engine.js

@@ -5,6 +5,7 @@ import { createServer } from 'node:net';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
+import { AuthStore } from "./auth-store.js";
 import { ENGINE_VERSION } from "./constants.js";
 import { reconcileConfig } from "./config.js";
 import { writePlugin, resolveBridge } from "./bridge.js";
@@ -15,11 +16,41 @@ const putChanged = (path, data) => {
     if (!existsSync(path) || readFileSync(path, 'utf8') !== data)
         writeFileSync(path, data, { mode: 0o600 });
 };
+const supports = (list, value) => !list ||
+    (!list.includes(`!${value}`) && (list.includes('any') || list.every(item => item.startsWith('!')) || list.includes(value)));
+function installMatches(dir) {
+    const manifests = ['package.json', 'package-lock.json'].map(file => ({
+        path: join(dir, file), shipped: readFileSync(join(kitDir, 'engine', file)),
+    }));
+    const lock = JSON.parse(manifests[1].shipped.toString('utf8'));
+    // npm omits optional binaries for other platforms (including the other Linux libc).
+    const report = process.platform === 'linux' ? process.report.getReport() : undefined;
+    const libc = report?.header.glibcVersionRuntime ? 'glibc' : process.platform === 'linux' ? 'musl' : '';
+    try {
+        if (manifests.some(({ path, shipped }) => !readFileSync(path).equals(shipped)))
+            return false;
+        for (const [path, pkg] of Object.entries(lock.packages)) {
+            if (!path)
+                continue; // The root manifest is checked byte for byte above.
+            if (pkg.optional && (!supports(pkg.os, process.platform) || !supports(pkg.cpu, process.arch) || !supports(pkg.libc, libc)))
+                continue;
+            if (JSON.parse(readFileSync(join(dir, path, 'package.json'), 'utf8')).version !== pkg.version)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        // Missing or unreadable manifests and malformed installed package metadata need repair too.
+        return false;
+    }
+}
 export class Engine {
     root;
     bridgeSock;
     dir;
     child;
+    starting;
+    authStore;
     stopping = false;
     repaired = false;
     prepared;
@@ -34,6 +65,7 @@ export class Engine {
         this.dir = o.engineDir ?? join(this.root, 'engine');
         this.bridgeSock = join(this.root, bridge.socketName);
         this.paramPrefix = bridge.paramPrefix;
+        this.authStore = new AuthStore({ root: this.root, stateDir: o.stateDir, engineDir: this.dir, seal: o.authSeal, log: o.log });
     }
     state(phase, why, retryAt) { this.o.onState({ phase, ...(why ? { why } : {}), ...(retryAt ? { retryAt } : {}) }); }
     get entry() { return join(this.dir, 'node_modules', 'openclaw', 'openclaw.mjs'); }
@@ -58,12 +90,14 @@ export class Engine {
         return pending;
     }
     async prepareOnce() {
-        for (const d of [this.root, 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])
+        if (!this.o.authSeal && existsSync(join(this.root, 'auth-store.sealed')))
+            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();
         if (this.o.spawnEngine) {
             const versionPath = join(this.dir, 'node_modules', 'openclaw', 'package.json');
-            const version = existsSync(versionPath) ? JSON.parse(readFileSync(versionPath, 'utf8')).version : undefined;
-            if (!existsSync(this.entry) || version !== ENGINE_VERSION) {
+            if (!existsSync(this.entry) || !installMatches(this.dir)) {
                 this.state('installing');
                 rmSync(join(this.dir, 'node_modules'), { recursive: true, force: true });
                 for (const f of ['package.json', 'package-lock.json'])
@@ -139,8 +173,28 @@ export class Engine {
         }
         catch { /* pid is gone or not ours */ }
     }
-    async start() {
+    start() {
+        if (this.starting)
+            return this.starting;
+        this.stopping = false;
+        const pending = this.startOnce();
+        this.starting = pending;
+        void pending.finally(() => { if (this.starting === pending)
+            this.starting = undefined; }).catch(() => { });
+        return pending;
+    }
+    async startOnce() {
         await this.prepare();
+        await this.authStore.start();
+        try {
+            return this.launch();
+        }
+        catch (error) {
+            await this.authStore.stop();
+            throw error;
+        }
+    }
+    launch() {
         const identityPath = join(this.root, 'device.json');
         if (!existsSync(identityPath)) {
             const { privateKey, publicKey } = generateKeyPairSync('ed25519');
@@ -150,7 +204,6 @@ export class Engine {
             return { port: this.port, token: this.token, identityPath };
         if (this.child && this.child.exitCode === null)
             return { port: this.port, token: this.token, identityPath };
-        this.stopping = false;
         this.stalePid();
         this.state('starting');
         const { entry, env } = this.doctorContext();
@@ -162,6 +215,12 @@ export class Engine {
             closeSync(fd);
         }
         const child = this.child;
+        child.on('error', () => {
+            if (this.child !== child || this.stopping)
+                return;
+            this.child = undefined;
+            void this.authStore.stop().then(() => { this.state('failed', 'exited'); this.o.onExit(null); }, () => this.state('failed', 'exited'));
+        });
         if (!child.pid) {
             this.state('failed', 'exited');
             throw new Error('engine spawn failed');
@@ -171,41 +230,52 @@ export class Engine {
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
-            this.o.onExit(code);
-            if (code === 78 && !this.repaired) {
-                this.repaired = true;
-                this.state('repairing');
-                const result = this.doctor(60_000);
-                if (result.status === 0) {
-                    void this.start().catch(() => this.state('failed', 'exited'));
+            rmSync(join(this.root, 'gateway.pid'), { force: true });
+            void (async () => {
+                await this.authStore.stop();
+                if (this.stopping)
                     return;
+                if (code === 78 && !this.repaired) {
+                    this.repaired = true;
+                    this.state('repairing');
+                    const result = await this.withAuthStore(async () => this.doctor(60_000));
+                    if (result.status === 0 && !this.stopping) {
+                        await this.start();
+                        return;
+                    }
                 }
-            }
-            this.state('failed', 'exited');
+                this.state('failed', 'exited');
+                this.o.onExit(code);
+            })().catch(() => this.state('failed', 'exited'));
         });
         return { port: this.port, token: this.token, identityPath };
     }
+    withAuthStore(task) { return this.authStore.offline(task); }
     async stop() {
         this.stopping = true;
+        await this.starting?.catch(() => { });
         const child = this.child;
-        this.child = undefined;
         if (child?.pid && child.exitCode === null) {
             try {
                 process.kill(-child.pid, 'SIGTERM');
             }
             catch { /* already gone */ }
-            for (let i = 0; i < 15 && child.exitCode === null; i++)
+            for (let i = 0; i < 15 && child.exitCode === null && child.signalCode === null; i++)
                 await delay(200);
-            if (child.exitCode === null) {
+            if (child.exitCode === null && child.signalCode === null) {
                 try {
                     process.kill(-child.pid, 'SIGKILL');
                 }
                 catch { /* already gone */ }
             }
-            for (let i = 0; i < 15 && child.exitCode === null; i++)
+            for (let i = 0; i < 15 && child.exitCode === null && child.signalCode === null; i++)
                 await delay(200);
         }
+        if (child && child.exitCode === null && child.signalCode === null)
+            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();
         rmSync(this.bridgeSock, { force: true });
         this.state('stopped');
     }

package/dist/kit.d.ts

@@ -1,6 +1,8 @@
+import type { SealingAdapter } from '@byokit/secrets';
 import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
+    authSeal?: SealingAdapter;
     engineDir?: string;
     npmPath?: string;
     enginePath?: string[];

package/dist/kit.js

@@ -1,5 +1,3 @@
-// The OpenClawKit facade: state, complete pass-through (D6), members, sign-in, runs, approvals, config (5.3).
-// Built in O4 (and O5/O6/O8 for the delegated parts); until then every body refuses to run.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -501,9 +499,13 @@ export class OpenClawKit {
             await this.approvalsCtl.resync();
         }
         catch (error) {
+            const needsUpdate = this.current.phase === 'needs-update';
             if (transport && this.transport === transport)
                 await this.disconnect();
-            if (this.current.phase !== 'needs-update' && !this.stopping)
+            await this.engine.stop();
+            if (needsUpdate)
+                this.setState({ phase: 'needs-update', why: 'version' });
+            if (!needsUpdate && !this.stopping)
                 this.setState({ phase: 'failed', why: 'handshake' });
             throw error;
         }
@@ -518,7 +520,8 @@ export class OpenClawKit {
         await transport?.stop();
     }
     closed(_why) {
-        if (this.stopping || this.current.phase !== 'ready')
+        const engineFailed = _why === 'engine exited' && this.current.phase === 'failed' && this.current.why === 'exited';
+        if (this.stopping || (this.current.phase !== 'ready' && !engineFailed))
             return;
         void this.disconnect();
         if (this.o.spawnEngine === false) {
@@ -593,10 +596,11 @@ export class OpenClawKit {
         return engineSignOut(this.signInCtx(), member, provider);
     }
     migrateRetainedLogin(member, source) {
-        return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000) }, member, source);
+        return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000),
+            seal: this.o.authSeal, log: this.o.log, withStore: (task) => this.engine.withAuthStore(task) }, member, source);
     }
     confirmRetainedLogin(member, source) {
-        return confirmLogin(this.signInCtx(), member, source);
+        return confirmLogin({ ...this.signInCtx(), seal: this.o.authSeal, log: this.o.log }, member, source);
     }
     // runs (5.8): the facade owns no run state; every call delegates to the O8 module
     // with this kit's live transport, member table and bridge (firstmate clearance, O9).

package/dist/migrate.d.ts

@@ -1,3 +1,4 @@
+import type { SealingAdapter } from '@byokit/secrets';
 import type { RetainedLogin } from './kit.ts';
 import type { SignInCtx } from './signin.ts';
 import type { Member } from './types.ts';
@@ -13,10 +14,16 @@ export declare function migrateRetainedLogin(ctx: {
     root: string;
     prepare(): Promise<void>;
     doctor: DoctorRunner;
+    seal?: SealingAdapter;
+    log?: (line: string) => void;
+    withStore?<T>(task: () => Promise<T>): Promise<T>;
 }, member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
 /**
- * After `ready`: the migration counts only when the Gateway itself reports every provider signed in. Only then does
- * a path source move aside (a rename, so the original bytes survive whole) — anything else leaves the sign-in where
+ * After `ready`: the migration counts only when the Gateway itself reports every provider signed in. Only then is
+ * a path source removed without creating a plaintext archive — anything else leaves the sign-in where
  * it was and the next boot retries it without asking the person to sign in again.
  */
-export declare function confirmRetainedLogin(ctx: SignInCtx, member: Member, source: RetainedLogin): Promise<boolean>;
+export declare function confirmRetainedLogin(ctx: SignInCtx & {
+    seal?: SealingAdapter;
+    log?: (line: string) => void;
+}, member: Member, source: RetainedLogin): Promise<boolean>;

package/dist/migrate.js

@@ -2,6 +2,7 @@
 // only when the Gateway itself reports every provider signed in.
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { retireArchive } from "./auth-store.js";
 import { MEMBER_ID } from "./members.js";
 import { providers } from "./signin.js";
 const MOVED = '.moved-to-engine';
@@ -15,17 +16,30 @@ function sourceFile(source) {
     if (existsSync(source.path))
         return source.path;
     const moved = source.path + MOVED;
-    return existsSync(moved) && !existsSync(moved + MARKER) ? moved : undefined;
+    if (existsSync(moved + MARKER))
+        return undefined;
+    if (existsSync(moved))
+        return moved;
+    return existsSync(moved + '.sealed') ? moved + '.sealed' : undefined;
 }
 /** The old sign-in's plain `{ '<provider>': credential }` map, or undefined when it is absent or unreadable. */
-function credentials(source, path) {
+async function credentials(source, path, seal) {
+    let opened;
+    if (path?.endsWith('.sealed')) {
+        if (!seal)
+            throw new Error('authSeal required for sealed retained login');
+        opened = Buffer.from(seal.decryptString(readFileSync(path)), 'base64');
+    }
     try {
-        const raw = 'record' in source ? source.record : JSON.parse(readFileSync(path, 'utf8'));
+        const raw = 'record' in source ? source.record : JSON.parse(opened ? new TextDecoder('utf-8', { fatal: true }).decode(opened) : readFileSync(path, 'utf8'));
         return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : undefined;
     }
     catch {
         return undefined;
     }
+    finally {
+        opened?.fill(0);
+    }
 }
 /** The engine's own provider ids for what the old sign-in holds; `openai-codex` is `openai` (D15). */
 function wantedProviders(legacy) {
@@ -50,40 +64,45 @@ export async function migrateRetainedLogin(ctx, member, source) {
     const path = sourceFile(source);
     if ('path' in source && !path)
         return 'nothing';
-    const legacy = credentials(source, path);
+    const legacy = await credentials(source, path, ctx.seal);
     if (!legacy || !Object.keys(legacy).length)
         return 'nothing'; // never migrate an empty source
     // A retired copy without the one provider the engine's canonicalization exists for is not worth importing.
-    if (path?.endsWith(MOVED) && !('openai-codex' in legacy))
+    if ((path?.endsWith(MOVED) || path?.endsWith(MOVED + '.sealed')) && !('openai-codex' in legacy))
         return 'nothing';
+    if (path?.endsWith(MOVED) && ctx.seal)
+        await retireArchive(path, ctx.seal, ctx.log);
     await ctx.prepare();
-    const agentDir = join(ctx.root, 'state', 'agents', member, 'agent');
-    const staged = join(agentDir, 'auth-profiles.json');
-    // Only a staging this call wrote may ever be removed: the file is the member's live sign-in once the engine has
-    // imported it, and a failed run must not take that with it.
-    const wrote = !existsSync(staged);
-    if (wrote) {
-        // Doctor canonicalizes legacy provider ids before importing; staging `auth.json` instead keeps the old id,
-        // which looks signed in but cannot authenticate `openai/*` turns.
-        mkdirSync(agentDir, { recursive: true, mode: 0o700 });
-        const body = JSON.stringify({ version: 1, profiles: Object.fromEntries(Object.entries(legacy).map(([provider, credential]) => [`${provider}:default`, credential])) });
-        // Written beside its home and renamed into place, so a reader never sees half a profile store.
-        const staging = `${staged}.staging-${process.pid}`;
-        writeFileSync(staging, body, { mode: 0o600 });
-        renameSync(staging, staged);
-    }
-    // The doctor's exit is a weak yes (it exits 0 even when it imports nothing), so a failed run only clears the
-    // staging; retiring the original stays confirm's job.
-    if (ctx.doctor().status !== 0) {
-        if (wrote)
-            rmSync(staged, { force: true });
-        return 'failed';
-    }
-    return 'staged';
+    const stage = async () => {
+        const agentDir = join(ctx.root, 'state', 'agents', member, 'agent');
+        const staged = join(agentDir, 'auth-profiles.json');
+        // Only a staging this call wrote may ever be removed: the file is the member's live sign-in once the engine has
+        // imported it, and a failed run must not take that with it.
+        const wrote = !existsSync(staged);
+        if (wrote) {
+            // Doctor canonicalizes legacy provider ids before importing; staging `auth.json` instead keeps the old id,
+            // which looks signed in but cannot authenticate `openai/*` turns.
+            mkdirSync(agentDir, { recursive: true, mode: 0o700 });
+            const body = JSON.stringify({ version: 1, profiles: Object.fromEntries(Object.entries(legacy).map(([provider, credential]) => [`${provider}:default`, credential])) });
+            // Written beside its home and renamed into place, so a reader never sees half a profile store.
+            const staging = `${staged}.staging-${process.pid}`;
+            writeFileSync(staging, body, { mode: 0o600 });
+            renameSync(staging, staged);
+        }
+        // The doctor's exit is a weak yes (it exits 0 even when it imports nothing), so a failed run only clears the
+        // staging; retiring the original stays confirm's job.
+        if (ctx.doctor().status !== 0) {
+            if (wrote)
+                rmSync(staged, { force: true });
+            return 'failed';
+        }
+        return 'staged';
+    };
+    return ctx.withStore ? ctx.withStore(stage) : stage();
 }
 /**
- * After `ready`: the migration counts only when the Gateway itself reports every provider signed in. Only then does
- * a path source move aside (a rename, so the original bytes survive whole) — anything else leaves the sign-in where
+ * After `ready`: the migration counts only when the Gateway itself reports every provider signed in. Only then is
+ * a path source removed without creating a plaintext archive — anything else leaves the sign-in where
  * it was and the next boot retries it without asking the person to sign in again.
  */
 export async function confirmRetainedLogin(ctx, member, source) {
@@ -93,7 +112,7 @@ export async function confirmRetainedLogin(ctx, member, source) {
     const path = sourceFile(source);
     if (original && !path)
         return false;
-    const legacy = credentials(source, path);
+    const legacy = await credentials(source, path, ctx.seal);
     if (!legacy)
         return false;
     const wanted = wantedProviders(legacy);
@@ -103,10 +122,12 @@ export async function confirmRetainedLogin(ctx, member, source) {
         for (let tries = 0; tries < TRIES; tries++) {
             const have = await providers(ctx, member, true);
             if (wanted.every((provider) => have.includes(provider))) {
-                if (path && path === original)
-                    renameSync(path, path + MOVED);
-                if (original)
+                if (original) {
+                    for (const file of [original, original + MOVED, original + MOVED + '.sealed'])
+                        rmSync(file, { force: true });
                     writeFileSync(original + MOVED + MARKER, '', { mode: 0o600 });
+                    ctx.log?.('verified retained credential source removed');
+                }
                 return true; // a record source moves nothing: the app deletes its own copy
             }
             if (tries < TRIES - 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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",
@@ -51,10 +51,11 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.5.0",
-    "@byokit/relay": "0.4.0",
+    "@byokit/link": "0.6.0",
+    "@byokit/relay": "0.4.2",
     "@byokit/reach": "0.4.0",
     "@byokit/seal": "0.2.0",
+    "@byokit/secrets": "0.3.0",
     "@openclaw/gateway-client": "2026.8.1",
     "@openclaw/gateway-protocol": "2026.8.1",
     "ws": "8.21.3"