@byokit/openclaw 0.5.0 → 0.6.1

package/dist/browser/resume.d.ts

@@ -0,0 +1,10 @@
+import type { NeedSignIn, ResumeState } from '../browser.ts';
+export type ResumeDispatch = (input: {
+    member: string;
+    sessionKey: string;
+    idempotencyKey: string;
+    message: string;
+}) => Promise<'accepted' | 'refused' | 'unknown'>;
+export declare function newResume(request: NeedSignIn, attempt?: number): ResumeState;
+export declare function recoverResume(request: NeedSignIn): void;
+export declare function dispatchResume(request: NeedSignIn, dispatch: ResumeDispatch): Promise<ResumeState['state']>;

package/dist/browser/resume.js

@@ -0,0 +1,23 @@
+import { randomUUID } from 'node:crypto';
+export function newResume(request, attempt = 1) {
+    return { key: `signin:${request.id}:resume:${attempt}:${randomUUID()}`, attempt, state: 'pending' };
+}
+export function recoverResume(request) {
+    const resume = request.settled?.resume;
+    // Neither process liveness nor an evictable gateway cache is submission proof.
+    if (resume && ['pending', 'accepted', 'submitted'].includes(resume.state))
+        resume.state = 'indeterminate';
+}
+export async function dispatchResume(request, dispatch) {
+    const resume = request.settled?.resume;
+    if (request.settled?.state !== 'verified' || resume?.state !== 'pending')
+        throw new Error('resume unavailable');
+    try {
+        const answer = await dispatch({ member: request.member, sessionKey: request.sessionKey, idempotencyKey: resume.key,
+            message: `The person signed in to ${request.site}. Continue the task.` });
+        return answer === 'accepted' ? 'accepted' : answer === 'refused' ? 'failed' : 'indeterminate';
+    }
+    catch {
+        return 'indeterminate';
+    }
+}

package/dist/browser/store.d.ts

@@ -0,0 +1,25 @@
+import type { NeedSignIn } from '../browser.ts';
+import type { Member } from '../types.ts';
+export type SignInData = {
+    v: 1;
+    requests: NeedSignIn[];
+    host: Record<string, {
+        checkUrl: string;
+        confirmed: string[];
+    }>;
+    verified: Record<Member, string[]>;
+};
+export interface SignInStore {
+    read(): SignInData;
+    write(data: SignInData): void;
+}
+export declare const emptySignIns: () => SignInData;
+export declare class BrowserStoreError extends Error {
+    constructor();
+}
+export declare function validOrigin(value: string): string;
+export declare function checkUrl(value: string): string;
+export declare function validateSignIns(value: unknown): SignInData;
+export declare function fileSignInStore(stateDir: string, io?: {
+    sync?: (fd: number) => void;
+}): SignInStore;

package/dist/browser/store.js

@@ -0,0 +1,151 @@
+// Host-only durable state. One kit owns stateDir; host serializes every mutation across members.
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const emptySignIns = () => ({ v: 1, requests: [], host: {}, verified: {} });
+export class BrowserStoreError extends Error {
+    constructor() { super('browser state unavailable'); }
+}
+const strings = (v) => Array.isArray(v) && v.every(x => typeof x === 'string');
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const integer = (v) => Number.isSafeInteger(v) && Number(v) >= 0;
+export function validOrigin(value) {
+    try {
+        const u = new URL(value);
+        if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || value !== u.origin)
+            throw 0;
+        return u.origin;
+    }
+    catch {
+        throw new BrowserStoreError();
+    }
+}
+export function checkUrl(value) {
+    try {
+        const u = new URL(value);
+        if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password)
+            throw 0;
+        // No credential-bearing fragments or URL parameters in durable host state.
+        if (u.hash || [...u.searchParams.keys()].some(k => /password|passwd|secret|token|code|authorization/i.test(k)))
+            throw 0;
+        return u.href;
+    }
+    catch {
+        throw new BrowserStoreError();
+    }
+}
+export function validateSignIns(value) {
+    try {
+        if (!object(value) || value.v !== 1 || !Array.isArray(value.requests) || !object(value.host) || !object(value.verified)
+            || Object.keys(value).some(k => !['v', 'requests', 'host', 'verified'].includes(k)))
+            throw 0;
+        const ids = new Set();
+        const active = new Set();
+        for (const r of value.requests) {
+            if (!object(r) || typeof r.id !== 'string' || !/^[A-Za-z0-9_-]{22}$/.test(r.id) || ids.has(r.id)
+                || typeof r.member !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(r.member) || !integer(r.gen) || r.gen < 1
+                || typeof r.sessionKey !== 'string' || !r.sessionKey || typeof r.origin !== 'string' || typeof r.site !== 'string'
+                || typeof r.secure !== 'boolean' || typeof r.firstTime !== 'boolean' || !integer(r.at) || !integer(r.expires)
+                || !strings(r.reasons) || !strings(r.hints) || !Array.isArray(r.choices)
+                || !['waiting', 'held', 'checking', 'parked', 'settled'].includes(String(r.state))
+                || Object.keys(r).some(k => !['id', 'gen', 'prev', 'member', 'sessionKey', 'origin', 'site', 'secure', 'firstTime', 'reasons', 'agentNote', 'hints', 'choices', 'state', 'settled', 'at', 'expires'].includes(k))
+                || r.reasons.some(x => !['redirected-to-login', 'password-field', 'http-401', 'agent-asked', 'session-expired'].includes(x))
+                || r.hints.some(x => !['password', 'google', 'microsoft', 'apple', 'sso', 'passkey', 'code', 'other'].includes(x))
+                || r.choices.some(x => !object(x) || Object.keys(x).length !== 1 || !['takeover', 'not-now', 'cancel'].includes(String(x.kind))))
+                throw 0;
+            validOrigin(r.origin);
+            if (r.state === 'settled') {
+                if (!object(r.settled) || !['verified', 'entered-unverified', 'cancelled', 'expired', 'failed'].includes(String(r.settled.state))
+                    || !integer(r.settled.at) || Object.keys(r.settled).some(k => !['state', 'reason', 'at', 'resume'].includes(k)))
+                    throw 0;
+                const resume = r.settled.resume;
+                if (resume !== undefined && (!object(resume) || r.settled.state !== 'verified' || !integer(resume.attempt) || resume.attempt < 1
+                    || typeof resume.key !== 'string' || !resume.key.startsWith(`signin:${r.id}:resume:${resume.attempt}:`)
+                    || !['pending', 'accepted', 'submitted', 'indeterminate', 'failed'].includes(String(resume.state))
+                    || Object.keys(resume).some(k => !['key', 'attempt', 'state'].includes(k))))
+                    throw 0;
+            }
+            else {
+                if (r.settled !== undefined || active.has(r.member))
+                    throw 0;
+                active.add(r.member);
+            }
+            ids.add(r.id);
+            const h = value.host[r.id];
+            if (!object(h) || typeof h.checkUrl !== 'string' || !strings(h.confirmed) || Object.keys(h).some(k => !['checkUrl', 'confirmed'].includes(k)))
+                throw 0;
+            checkUrl(h.checkUrl);
+            h.confirmed.forEach(validOrigin);
+        }
+        if (Object.keys(value.host).some(id => !ids.has(id)))
+            throw 0;
+        for (const [member, sites] of Object.entries(value.verified)) {
+            if (!/^[a-z][a-z0-9-]{0,31}$/.test(member) || !strings(sites))
+                throw 0;
+        }
+        return structuredClone(value);
+    }
+    catch {
+        throw new BrowserStoreError();
+    }
+}
+export function fileSignInStore(stateDir, io = {}) {
+    const dir = join(stateDir, 'browser');
+    const file = join(dir, 'signins.json');
+    let failed = false;
+    const sync = io.sync ?? fsyncSync;
+    const guard = () => { if (failed)
+        throw new BrowserStoreError(); };
+    return {
+        read() {
+            guard();
+            try {
+                if (!existsSync(file))
+                    return emptySignIns();
+                if (!lstatSync(dir).isDirectory() || lstatSync(dir).isSymbolicLink() || !lstatSync(file).isFile() || lstatSync(file).isSymbolicLink())
+                    throw 0;
+                chmodSync(file, 0o600);
+                return validateSignIns(JSON.parse(readFileSync(file, 'utf8')));
+            }
+            catch {
+                failed = true;
+                throw new BrowserStoreError();
+            }
+        },
+        write(data) {
+            guard();
+            const tmp = join(dir, `.signins-${randomUUID()}`);
+            try {
+                const safe = validateSignIns(data);
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                if (!lstatSync(dir).isDirectory() || lstatSync(dir).isSymbolicLink())
+                    throw 0;
+                chmodSync(dir, 0o700);
+                writeFileSync(tmp, JSON.stringify(safe), { flag: 'wx', mode: 0o600 });
+                const fd = openSync(tmp, 'r');
+                try {
+                    sync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(tmp, file);
+                // A failed directory fsync is ambiguous: poison this store, never dispatch or unfence.
+                const directory = openSync(dir, 'r');
+                try {
+                    sync(directory);
+                }
+                finally {
+                    closeSync(directory);
+                }
+            }
+            catch {
+                failed = true;
+                throw new BrowserStoreError();
+            }
+            finally {
+                rmSync(tmp, { force: true });
+            }
+        },
+    };
+}

package/dist/browser/verify.d.ts

@@ -0,0 +1,17 @@
+import type { SiteVerifier, SettledReason } from '../browser.ts';
+export type Probe = {
+    url: string;
+    status: number;
+    exists(selector: string): Promise<boolean>;
+};
+export type Prober = {
+    probe(url: string, verify: (p: Probe) => Promise<boolean>, timeoutMs: number): Promise<'ok' | 'fail' | 'timeout'>;
+};
+export type Verification = {
+    state: 'verified';
+} | {
+    state: 'entered-unverified';
+    reason: SettledReason;
+};
+export declare function validateVerifiers(verifiers: SiteVerifier[]): void;
+export declare function verifySignIn(broker: Prober, origin: string, verifiers: SiteVerifier[], timeoutMs: number): Promise<Verification>;

package/dist/browser/verify.js

@@ -0,0 +1,38 @@
+import { checkUrl, validOrigin } from "./store.js";
+export function validateVerifiers(verifiers) {
+    for (const v of verifiers) {
+        validOrigin(v.origin);
+        if (new URL(checkUrl(v.url)).origin !== v.origin || (v.status !== undefined && (!Number.isInteger(v.status) || v.status < 100 || v.status > 599))) {
+            throw new Error('invalid browser verifier');
+        }
+    }
+}
+export async function verifySignIn(broker, origin, verifiers, timeoutMs) {
+    const v = verifiers.find(v => v.origin === origin);
+    // A bare endpoint status is not positive proof; host code or a signed-in-only selector is required.
+    if (!v || (!v.selector && !v.check))
+        return { state: 'entered-unverified', reason: 'no-verifier' };
+    let timer;
+    try {
+        const result = await Promise.race([
+            broker.probe(v.url, async (p) => {
+                if (new URL(p.url).origin !== origin || (v.status !== undefined && p.status !== v.status))
+                    return false;
+                if (v.selector && !await p.exists(v.selector))
+                    return false;
+                if (v.check && !await v.check(p))
+                    return false;
+                // The verifier may have navigated: check the final host-side URL again.
+                return new URL(p.url).origin === origin;
+            }, timeoutMs),
+            new Promise(resolve => { timer = setTimeout(() => resolve('timeout'), timeoutMs); }),
+        ]);
+        return result === 'ok' ? { state: 'verified' } : { state: 'entered-unverified', reason: result === 'timeout' ? 'check-timeout' : 'still-signed-out' };
+    }
+    catch {
+        return { state: 'entered-unverified', reason: 'still-signed-out' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/browser.d.ts

@@ -0,0 +1,212 @@
+import type { Member } from './types.ts';
+/** What a live view shows. A browser source never claims to be a whole computer. */
+export type LiveSource = {
+    kind: 'browser';
+    member: Member;
+} | {
+    kind: 'desktop';
+    member: Member;
+    source: 'host' | 'node' | 'environment';
+};
+/** One member's kit-owned browser: one Chromium process + one profile per member, inside one kit (one person). */
+export type BrowserState = {
+    member: Member;
+    phase: 'off' | 'starting' | 'ready' | 'recovering' | 'fenced' | 'blocked';
+    why?: 'no-browser' | 'recovery-exhausted' | 'engine-detached' | 'unsafe-tools' | 'gate-off' | 'handoff-unprotected';
+    recovery?: {
+        attempt: number;
+        of: number;
+        nextAt?: number;
+    };
+};
+/** Display hints read from the page by the host (button text, input types). Never from the model. */
+export type SignInMethodHint = 'password' | 'google' | 'microsoft' | 'apple' | 'sso' | 'passkey' | 'code' | 'other';
+export type SignInReason = 'redirected-to-login' | 'password-field' | 'http-401' | 'agent-asked' | 'session-expired';
+export type SignInChoice = {
+    kind: 'takeover';
+} | {
+    kind: 'not-now';
+} | {
+    kind: 'cancel';
+};
+export type SettledState = 'verified' | 'entered-unverified' | 'cancelled' | 'expired' | 'failed';
+export type SettledReason = 'still-signed-out' | 'origin-mismatch' | 'browser-gone' | 'superseded' | 'check-timeout' | 'run-replaced' | 'no-verifier';
+/** Resume bookkeeping for a verified request. Persisted BEFORE dispatch; never claims exactly-once. */
+export type ResumeState = {
+    key: string;
+    attempt: number;
+    state: 'pending' | 'accepted' | 'submitted' | 'indeterminate' | 'failed';
+};
+export type NeedSignIn = {
+    id: string;
+    gen: number;
+    prev?: string;
+    member: Member;
+    sessionKey: string;
+    origin: string;
+    site: string;
+    secure: boolean;
+    firstTime: boolean;
+    reasons: SignInReason[];
+    agentNote?: string;
+    hints: SignInMethodHint[];
+    choices: SignInChoice[];
+    state: 'waiting' | 'held' | 'checking' | 'parked' | 'settled';
+    settled?: {
+        state: SettledState;
+        reason?: SettledReason;
+        at: number;
+        resume?: ResumeState;
+    };
+    at: number;
+    expires: number;
+};
+/** The single controlling viewer's lease. Bound to the grant that took it. */
+export type TakeoverLease = {
+    requestId: string;
+    gen: number;
+    epoch: number;
+    nonce: string;
+    expires: number;
+    claimMs: number;
+    graceMs: number;
+};
+export type LiveViewState = {
+    source: LiveSource;
+    phase: 'connecting' | 'live' | 'reconnecting' | 'private' | 'ended' | 'failed';
+    mode: 'observe' | 'control';
+    origin?: string;
+    secure?: boolean;
+    offOrigin?: boolean;
+    leaseExpires?: number;
+    why?: 'revoked' | 'expired' | 'stale-epoch' | 'superseded' | 'browser-gone' | 'unsupported';
+};
+/** JPEG frame on the link stream. Never written to disk, logs, transcripts, relay jobs or telemetry. */
+export type LiveFrame = {
+    seq: number;
+    w: number;
+    h: number;
+    at: number;
+    jpeg: Uint8Array;
+};
+/** Lease holder only, private tab only. Never logged; never in errors or events. */
+export type LiveInput = {
+    kind: 'pointer';
+    type: 'move' | 'down' | 'up' | 'wheel';
+    x: number;
+    y: number;
+    button?: 'left' | 'right' | 'middle';
+    dx?: number;
+    dy?: number;
+} | {
+    kind: 'key';
+    type: 'down' | 'up';
+    key: string;
+    code?: string;
+    modifiers?: number;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'nav';
+    action: 'back' | 'forward' | 'reload';
+};
+export type ThumbnailResult = {
+    state: 'ok';
+    frame: LiveFrame;
+} | {
+    state: 'private' | 'off' | 'unsupported';
+};
+export type SignInRefusedWhy = 'stale' | 'not-found' | 'held-by-other' | 'lease-expired' | 'not-control' | 'not-lease-holder' | 'confirm-site' | 'already-open' | 'insecure-remote' | 'unsupported';
+export type BrowserOptions = {
+    executablePath: string;
+    members: Member[] | 'all';
+    requestTtlMs?: number;
+    leaseTtlMs?: number;
+    claimMs?: number;
+    graceMs?: number;
+    checkMs?: number;
+    recovery?: {
+        attempts: number;
+        backoffMs: number[];
+    };
+    knownIdps?: string[];
+    verifiers?: SiteVerifier[];
+};
+/** Host-only positive proof that the browser session is signed in. Run by the host in a host-only tab after Done;
+ * the result is a boolean plus a reason code. No page text, cookie, header or value leaves it; never evented,
+ * logged or shown to a model. A login-free page or a clean 200 alone never counts. */
+export type SiteVerifier = {
+    origin: string;
+    url: string;
+    status?: number;
+    selector?: string;
+    check?: (probe: {
+        url: string;
+        status: number;
+        exists(selector: string): Promise<boolean>;
+    }) => Promise<boolean>;
+};
+export interface BrowserHost {
+    state(member: Member): BrowserState;
+    signIns(member?: Member): NeedSignIn[];
+    takeover(id: string, gen: number, by: {
+        grant: string;
+        confirmSite?: string;
+    }): Promise<TakeoverLease>;
+    confirmOrigin(lease: Pick<TakeoverLease, 'requestId' | 'epoch' | 'nonce'>, origin: string): void;
+    done(lease: Pick<TakeoverLease, 'requestId' | 'epoch' | 'nonce'>): Promise<NeedSignIn>;
+    notNow(id: string, gen: number, by: {
+        grant: string;
+    }): Promise<NeedSignIn>;
+    reopen(id: string, gen: number, by: {
+        grant: string;
+    }): Promise<NeedSignIn>;
+    retry(id: string, gen: number, by: {
+        grant: string;
+    }): Promise<NeedSignIn>;
+    cancel(id: string, gen: number, by: {
+        grant: string;
+    }): Promise<NeedSignIn>;
+    thumbnail(source: LiveSource, by: {
+        grant: string;
+    }): Promise<ThumbnailResult>;
+    live(source: LiveSource, o: {
+        grant: string;
+        lease?: TakeoverLease;
+        maxWidth?: number;
+    }, on: {
+        state(s: LiveViewState): void;
+        frame(f: LiveFrame): void;
+    }): {
+        input(i: LiveInput): void;
+        close(): void;
+    };
+    forget(member: Member, site: string | 'all', by: {
+        grant: string;
+    }): Promise<void>;
+}
+export type BrowserDevice = {
+    state(member: Member): Promise<BrowserState>;
+    signIns(): Promise<NeedSignIn[]>;
+    takeover(id: string, gen: number, o?: {
+        confirmSite?: string;
+    }): Promise<TakeoverLease>;
+    confirmOrigin(lease: TakeoverLease, origin: string): Promise<void>;
+    done(lease: TakeoverLease): Promise<NeedSignIn>;
+    notNow(id: string, gen: number): Promise<NeedSignIn>;
+    reopen(id: string, gen: number): Promise<NeedSignIn>;
+    retry(id: string, gen: number): Promise<NeedSignIn>;
+    cancel(id: string, gen: number): Promise<NeedSignIn>;
+    forget(member: Member, site: string | 'all'): Promise<void>;
+    thumbnail(source: LiveSource): Promise<ThumbnailResult>;
+    live(source: LiveSource, o?: {
+        lease?: TakeoverLease;
+        maxWidth?: number;
+    }): {
+        states: AsyncIterable<LiveViewState>;
+        frames: AsyncIterable<LiveFrame>;
+        input(i: LiveInput): void;
+        close(): void;
+    };
+};

package/dist/browser.js

@@ -0,0 +1,4 @@
+// Browser sign-in handoff and live view: the portable typed interface (docs/runtime-kits.md 5.17, D20).
+// Types only, no runtime: the broker, host, kit wiring, link ops and device client are built by O18-O25 against these
+// shapes. Handoff stays refused (BrowserState why 'handoff-unprotected') until parked sessions are protected (5.17).
+export {};

package/dist/config.d.ts

@@ -1,5 +1,7 @@
 import type { KitOptions } from './kit.ts';
 import type { Member } from './types.ts';
+import type { NeedSignIn } from './browser.ts';
+type Obj = Record<string, any>;
 export declare function reconcileConfig(saved: object | undefined, o: {
     root: string;
     stateDir: string;
@@ -9,5 +11,31 @@ export declare function reconcileConfig(saved: object | undefined, o: {
     policyPath: string;
     app?: object;
     installPolicy?: KitOptions['installPolicy'];
+    browser?: {
+        profiles: Record<string, {
+            cdpUrl: string;
+            attachOnly: true;
+        }>;
+        tools: string[];
+    };
 }): object;
+/** Caller-owned task namespaces, including the engine key-agent rewrite; never an entire member. */
+export declare function appRecoveryPrefixes(ownership?: KitOptions['appOwnedSessions']): string[];
+/** A closed explicit global allow is required, not a group deny or an OS sandbox claim. Every nested
+ * agent, delegate and provider policy must stay inside it. The runtime also checks tools.effective. */
+export declare function browserToolPolicySafe(config: unknown, tools: readonly string[]): boolean;
+export declare function browserProfileAcknowledged(profile: unknown, owned: unknown, endpoint: string, snapshot: {
+    configRevisionHash?: unknown;
+    appliedConfigHash?: unknown;
+}, stableFile: boolean): boolean;
+export declare function browserSessionMayRun(requests: readonly NeedSignIn[], key: string, registeredRun?: boolean): boolean;
 export declare function memoryLimited(config: object, member: Member): boolean;
+/** One dotted path, validated at the boundary: a caller-supplied walk must never reach a prototype. */
+export declare function configKeyPath(key: string): string[];
+/** The value at one dotted path, or undefined when it is absent. A copy, so a caller cannot hold kit state. */
+export declare function readConfigKey(config: unknown, segments: readonly string[]): unknown;
+/** Writes one dotted path, creating only the missing objects on the way, and returns the value it replaced.
+ * undefined removes the key, and with it the empty objects this call created, so a removal restores the file it
+ * read. Every other key keeps its place, so one narrow set stays one narrow set. */
+export declare function writeConfigKey(config: Obj, segments: readonly string[], value: unknown): unknown;
+export {};