@byokit/openclaw 0.5.1 → 0.6.2

package/dist/browser/host.js

@@ -0,0 +1,945 @@
+// Internal host runtime (5.17). Production handoff is deliberately unprotected until W7/O17 qualification.
+import { randomBytes } from 'node:crypto';
+import { BrowserStoreError, checkUrl, validOrigin } from "./store.js";
+import { validateVerifiers, verifySignIn } from "./verify.js";
+import { dispatchResume, newResume, recoverResume } from "./resume.js";
+export class SignInRefused extends Error {
+    why;
+    constructor(why) { super(`sign-in refused: ${why}`); this.why = why; }
+}
+export class HandoffUnprotected extends Error {
+    why = 'handoff-unprotected';
+    constructor() { super('browser sign-in handoff unavailable'); }
+}
+const open = (r) => ['waiting', 'held', 'checking'].includes(r.state);
+const mint = () => randomBytes(16).toString('base64url');
+export function secureOrigin(origin) {
+    const u = new URL(validOrigin(origin));
+    return u.protocol === 'https:' || u.hostname === 'localhost' || u.hostname === '[::1]' || /^127\.(\d{1,3}\.){2}\d{1,3}$/.test(u.hostname);
+}
+export async function createBrowserHost(services) {
+    return startHost(services, false);
+}
+// TEST ONLY. Requires loopback-only synthetic brokers; never imported by kit wiring. No production enable flag.
+export async function fixtureBrowserHost(services) {
+    for (const broker of services.brokers.values()) {
+        const target = broker.agentTab();
+        if (!target)
+            throw new Error('fixture browser required');
+        const origin = await broker.originOf(target);
+        if (!secureOrigin(origin) || new URL(origin).protocol !== 'http:')
+            throw new Error('loopback fixture required');
+    }
+    return startHost(services, true);
+}
+async function startHost(services, fixture) {
+    const host = new Host(services, fixture);
+    await host.restore();
+    return host;
+}
+class Host {
+    s;
+    fixture;
+    data;
+    committed;
+    brokers;
+    attaching = new Map();
+    bindingVersions = new Map();
+    recovery = new Map();
+    exhausted = new Set();
+    queue = Promise.resolve();
+    leases = new Map();
+    epochs = new Map();
+    streams = new Set();
+    unavailable = new Set();
+    closing = new Set();
+    revoked = new Set();
+    thumbs = new Map();
+    ttl;
+    stopped = false;
+    failed = false;
+    constructor(services, fixture) {
+        this.s = services;
+        this.fixture = fixture;
+        validateVerifiers(services.options.verifiers ?? []);
+        for (const origin of services.options.knownIdps ?? [])
+            validOrigin(origin);
+        for (const n of ['requestTtlMs', 'leaseTtlMs', 'claimMs', 'graceMs', 'checkMs']) {
+            const value = services.options[n];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647))
+                throw new Error('invalid browser timeout');
+        }
+        const recovery = services.options.recovery;
+        if (recovery && (!Number.isInteger(recovery.attempts) || recovery.attempts < 0 || recovery.attempts > 3
+            || recovery.backoffMs.some(n => !Number.isSafeInteger(n) || n < 0 || n > 60_000)))
+            throw new Error('invalid browser recovery');
+        this.brokers = new Map(services.brokers);
+        for (const member of this.brokers.keys())
+            this.bindingVersions.set(member, 1);
+        this.data = services.store.read();
+        this.committed = structuredClone(this.data);
+    }
+    now() { return this.s.now?.() ?? Date.now(); }
+    broker(member) {
+        const broker = this.brokers.get(member);
+        if (!broker || this.unavailable.has(member))
+            throw new SignInRefused('unsupported');
+        return broker;
+    }
+    currentBroker(member, broker) {
+        if (this.stopped || this.failed || this.unavailable.has(member) || this.brokers.get(member) !== broker)
+            throw new SignInRefused('stale');
+    }
+    brokerBinding(member) {
+        const broker = this.brokers.get(member);
+        if (!broker || this.stopped || this.failed || this.unavailable.has(member) || this.attaching.has(member))
+            return undefined;
+        try {
+            return Object.freeze({ broker, generation: this.bindingVersions.get(member) ?? 0, endpoint: Object.freeze({ ...broker.endpoint() }) });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    attachBroker(member, next, previous) {
+        if (!/^[a-z][a-z0-9-]{0,31}$/.test(member) || (this.s.options.members !== 'all' && !this.s.options.members.includes(member))
+            || this.stopped || this.failed)
+            return Promise.reject(new SignInRefused('unsupported'));
+        if (this.attaching.has(member))
+            return Promise.reject(new SignInRefused('held-by-other'));
+        const old = this.brokers.get(member);
+        if (old !== previous)
+            return Promise.reject(new SignInRefused('stale'));
+        if (old === next)
+            return Promise.resolve();
+        this.attaching.set(member, next);
+        this.unavailable.add(member);
+        this.thumbs.delete(member);
+        this.bindingVersions.set(member, (this.bindingVersions.get(member) ?? 0) + 1);
+        this.recovery.delete(member);
+        this.epochs.set(member, (this.epochs.get(member) ?? 0) + 1);
+        const requests = this.data.requests.filter(r => r.member === member);
+        // No await before old capabilities are invalidated. New endpoint is not yet published to the engine.
+        try {
+            for (const r of requests) {
+                this.closing.add(r.id);
+                this.drop(r);
+            }
+            old?.bindLease(null);
+        }
+        catch {
+            this.failed = true;
+        }
+        for (const s of this.streams)
+            if (s.member === member)
+                s.close('browser-gone');
+        // ponytail: one host-wide queue keeps the single durable file atomic; split per member if latency matters.
+        return this.serial(async () => {
+            try {
+                if (this.brokers.get(member) !== old)
+                    throw new SignInRefused('stale');
+                await next.fence(true);
+                if (old) {
+                    await old.fence(true);
+                    await old.closePrivate();
+                    await old.close();
+                }
+                if (this.stopped || this.failed)
+                    throw new SignInRefused('unsupported');
+                for (const r of this.data.requests.filter(r => r.member === member)) {
+                    recoverResume(r);
+                    if (r.state === 'held' || r.state === 'checking') {
+                        r.state = 'settled';
+                        r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+                    }
+                    else if (r.state === 'waiting' || r.state === 'parked')
+                        r.gen++;
+                }
+                this.commit();
+                // Leave the replacement fenced. W3 publishes this binding, awaits config/policy ack, then releases.
+                if (this.stopped || this.failed || this.brokers.get(member) !== old)
+                    throw new SignInRefused('stale');
+                this.brokers.set(member, next);
+                this.unavailable.delete(member);
+                this.exhausted.delete(member);
+                this.attaching.delete(member); // state-ping listeners must see the accepted canonical binding
+                for (const r of requests) {
+                    this.closing.delete(r.id);
+                    this.ping(r);
+                }
+                try {
+                    this.s.ping?.(member, 'state');
+                }
+                catch { /* advisory */ }
+            }
+            catch {
+                this.exhausted.add(member);
+                for (const r of requests)
+                    if (r.state !== 'settled') {
+                        r.state = 'settled';
+                        r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+                    }
+                if (!this.failed)
+                    this.commit();
+                throw new SignInRefused('unsupported');
+            }
+        }).catch(async (e) => { try {
+            await next.close();
+        }
+        catch { /* never expose endpoint details */ } throw e; })
+            .finally(() => { if (this.attaching.get(member) === next)
+            this.attaching.delete(member); });
+    }
+    serial(fn) {
+        const result = this.queue.then(async () => {
+            if (this.failed || this.stopped)
+                throw new SignInRefused('unsupported');
+            try {
+                return await fn();
+            }
+            catch (e) {
+                if (e instanceof SignInRefused || e instanceof BrowserStoreError || e instanceof HandoffUnprotected)
+                    throw e;
+                throw new Error('browser action unavailable');
+            }
+        });
+        this.queue = result.catch(() => { });
+        return result;
+    }
+    commit() {
+        try {
+            this.s.store.write(this.data);
+            this.committed = structuredClone(this.data);
+        }
+        catch {
+            this.data = structuredClone(this.committed);
+            this.failed = true;
+            this.streams.forEach(s => s.close('browser-gone'));
+            throw new Error('browser state unavailable');
+        }
+        this.arm();
+    }
+    ping(r) { try {
+        this.s.ping?.(r.member, 'signin');
+    }
+    catch { /* invalidation is advisory */ } }
+    arm() {
+        clearTimeout(this.ttl);
+        const expires = this.data.requests.filter(r => r.state === 'waiting' || r.state === 'held').map(r => r.expires);
+        if (!expires.length)
+            return;
+        this.ttl = setTimeout(() => { void this.sweep().catch(() => { }); }, Math.max(1, Math.min(...expires) - this.now()));
+        this.ttl.unref?.();
+    }
+    async restore() {
+        for (const r of this.data.requests) {
+            recoverResume(r);
+            if (r.state === 'held' || r.state === 'checking') {
+                r.state = 'settled';
+                r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+            }
+            else if (r.state === 'waiting' || r.state === 'parked')
+                r.gen++;
+            if (open(r))
+                await this.broker(r.member).fence(true);
+        }
+        // No dispatch on restore, regardless of gateway process/cache state or submission marker.
+        this.commit();
+    }
+    state(member) {
+        if (this.attaching.has(member))
+            return this.brokers.has(member)
+                ? { member, phase: 'blocked', why: 'engine-detached' } : { member, phase: 'starting' };
+        if (!this.brokers.has(member))
+            return { member, phase: 'off', why: 'no-browser' };
+        const recovery = this.recovery.get(member);
+        if (recovery)
+            return { member, phase: 'recovering', recovery: { ...recovery } };
+        if (this.exhausted.has(member))
+            return { member, phase: 'blocked', why: 'recovery-exhausted' };
+        if (this.failed || this.stopped || this.unavailable.has(member))
+            return { member, phase: 'blocked', why: 'engine-detached' };
+        if (this.data.requests.some(r => r.member === member && open(r)))
+            return { member, phase: 'fenced' };
+        return this.fixture ? { member, phase: 'ready' } : { member, phase: 'blocked', why: 'handoff-unprotected' };
+    }
+    signIns(member) { return structuredClone(this.data.requests.filter(r => !member || r.member === member)); }
+    request(id, gen) {
+        const r = this.data.requests.find(r => r.id === id);
+        if (!r)
+            throw new SignInRefused('not-found');
+        if (gen !== undefined && gen !== r.gen)
+            throw new SignInRefused('stale');
+        return r;
+    }
+    access(grant, member, control) {
+        let allowed = false;
+        try {
+            allowed = !this.revoked.has(grant) && this.s.authorize(grant, member, control);
+        }
+        catch { /* fail closed */ }
+        if (!allowed)
+            throw new SignInRefused(control ? 'not-control' : 'not-found');
+    }
+    held(r, grant) {
+        this.access(grant, r.member, true);
+        if (r.state === 'held') {
+            const l = this.leases.get(r.id);
+            if (l?.grant !== grant)
+                throw new SignInRefused('not-lease-holder');
+            this.lease(l.value);
+        }
+        if (['waiting', 'held'].includes(r.state) && this.now() >= r.expires)
+            throw new SignInRefused('lease-expired');
+    }
+    lease(ref) {
+        if (this.failed || this.stopped)
+            throw new SignInRefused('stale');
+        const r = this.request(ref.requestId);
+        if (this.unavailable.has(r.member))
+            throw new SignInRefused('stale');
+        const l = this.leases.get(r.id);
+        if (!l || l.value.epoch !== ref.epoch || l.value.nonce !== ref.nonce || l.value.gen !== r.gen
+            || this.epochs.get(r.member) !== ref.epoch || !['held', 'checking'].includes(r.state))
+            throw new SignInRefused('stale');
+        this.access(l.grant, r.member, true);
+        if (r.state !== 'checking' && this.now() >= Math.min(l.value.expires, l.deadline, r.expires))
+            throw new SignInRefused('lease-expired');
+        return { r, l };
+    }
+    drop(r) {
+        const l = this.leases.get(r.id);
+        clearTimeout(l?.timer);
+        this.brokers.get(r.member)?.bindLease(null);
+        this.leases.delete(r.id);
+        this.epochs.set(r.member, (this.epochs.get(r.member) ?? 0) + 1);
+        for (const s of this.streams)
+            if (s.member === r.member)
+                s.close('superseded');
+    }
+    leaseTimer(r, l) {
+        clearTimeout(l.timer);
+        l.timer = setTimeout(() => { void this.sweep().catch(() => { }); }, Math.max(1, Math.min(l.deadline, l.value.expires) - this.now()));
+        l.timer.unref?.();
+    }
+    async raise(input) {
+        if (!this.fixture)
+            throw new HandoffUnprotected();
+        return this.serial(() => this.raiseLocked(input));
+    }
+    async raiseLocked(input, prev) {
+        const broker = this.broker(input.member);
+        if (this.data.requests.some(r => r.member === input.member && r.state !== 'settled'))
+            throw new SignInRefused('already-open');
+        if (!input.sessionKey)
+            throw new SignInRefused('unsupported');
+        const target = input.targetId ?? broker.agentTab();
+        if (!target)
+            throw new SignInRefused('unsupported');
+        const origin = validOrigin(await broker.originOf(target));
+        this.currentBroker(input.member, broker);
+        const url = checkUrl(input.checkUrl);
+        const site = this.s.siteOf(origin);
+        if (!site || /[\s/<>]/.test(site))
+            throw new SignInRefused('unsupported');
+        const r = { id: mint(), gen: 1, ...(prev ? { prev } : {}), member: input.member, sessionKey: input.sessionKey,
+            origin, site, secure: secureOrigin(origin), firstTime: !(Object.hasOwn(this.data.verified, input.member) && this.data.verified[input.member].includes(site)),
+            reasons: [...new Set(input.reasons)], hints: [...new Set(input.hints ?? [])],
+            choices: [...(secureOrigin(origin) ? [{ kind: 'takeover' }] : []), { kind: 'not-now' }, { kind: 'cancel' }],
+            state: 'waiting', at: this.now(), expires: this.now() + (this.s.options.requestTtlMs ?? 1_800_000) };
+        this.thumbs.delete(r.member);
+        this.data.requests.push(r);
+        this.data.host[r.id] = { checkUrl: url, confirmed: [] };
+        this.commit();
+        this.streams.forEach(s => { if (s.member === r.member)
+            s.close('superseded'); });
+        await broker.fence(true);
+        await this.s.park(r.member, r.sessionKey);
+        this.ping(r);
+        return structuredClone(r);
+    }
+    takeover(id, gen, by) {
+        if (!this.fixture)
+            return Promise.reject(new HandoffUnprotected());
+        if (this.closing.has(id))
+            return Promise.reject(new SignInRefused('held-by-other'));
+        return this.serial(async () => {
+            const r = this.request(id, gen);
+            this.access(by.grant, r.member, true);
+            if (r.state === 'held' || this.closing.has(r.id))
+                throw new SignInRefused('held-by-other');
+            if (r.state !== 'waiting')
+                throw new SignInRefused('stale');
+            if (this.now() >= r.expires)
+                throw new SignInRefused('lease-expired');
+            if (!r.secure)
+                throw new SignInRefused('insecure-remote');
+            if (r.firstTime && by.confirmSite !== r.site)
+                throw new SignInRefused('confirm-site');
+            const broker = this.broker(r.member);
+            await broker.fence(true);
+            const epoch = (this.epochs.get(r.member) ?? 0) + 1;
+            this.epochs.set(r.member, epoch);
+            const value = { requestId: r.id, gen: r.gen, epoch, nonce: mint(), expires: this.now() + (this.s.options.leaseTtlMs ?? 600_000),
+                claimMs: this.s.options.claimMs ?? 60_000, graceMs: this.s.options.graceMs ?? 30_000 };
+            broker.bindLease({ epoch, nonce: value.nonce, origin: r.origin, knownIdps: this.knownIdps() });
+            let target;
+            try {
+                target = await broker.openPrivate(this.data.host[r.id].checkUrl);
+                // Revocation during openPrivate cannot grant a new controller.
+                this.access(by.grant, r.member, true);
+                this.currentBroker(r.member, broker);
+            }
+            catch {
+                broker.bindLease(null);
+                try {
+                    await broker.closePrivate();
+                }
+                catch {
+                    this.unavailable.add(r.member);
+                }
+                throw new SignInRefused('stale');
+            }
+            const l = { value, grant: by.grant, target, attached: false, deadline: this.now() + value.claimMs };
+            this.leases.set(r.id, l);
+            r.state = 'held';
+            this.data.host[r.id].confirmed = [];
+            this.commit();
+            this.leaseTimer(r, l);
+            this.ping(r);
+            return structuredClone(value);
+        });
+    }
+    confirmOrigin(ref, origin) {
+        const { r } = this.lease(ref);
+        if (r.state !== 'held')
+            throw new SignInRefused('stale');
+        const exact = validOrigin(origin);
+        if (!secureOrigin(exact))
+            throw new SignInRefused('insecure-remote');
+        let confirmed = false;
+        try {
+            confirmed = this.broker(r.member).confirmOrigin({ epoch: ref.epoch, nonce: ref.nonce }, exact);
+        }
+        catch { /* fail closed */ }
+        if (!confirmed)
+            throw new SignInRefused('stale');
+        if (!this.data.host[r.id].confirmed.includes(exact))
+            this.data.host[r.id].confirmed.push(exact);
+        this.commit();
+    }
+    done(ref) {
+        return this.serial(async () => {
+            const { r, l } = this.lease(ref);
+            if (r.state !== 'held')
+                throw new SignInRefused('stale');
+            const broker = this.broker(r.member);
+            r.state = 'checking';
+            clearTimeout(l.timer);
+            for (const s of this.streams)
+                if (s.member === r.member)
+                    s.close('superseded');
+            this.commit();
+            this.ping(r);
+            const privateState = broker.privateState();
+            const origin = privateState ? validOrigin(privateState.origin) : undefined;
+            broker.bindLease(null);
+            const allowed = !!origin && (origin === r.origin || this.knownIdps().includes(origin) || this.data.host[r.id].confirmed.includes(origin));
+            const result = allowed && origin && secureOrigin(origin)
+                ? await verifySignIn(broker, r.origin, this.s.options.verifiers ?? [], this.s.options.checkMs ?? 30_000)
+                : { state: 'failed', reason: 'origin-mismatch' };
+            // Revocation/reconnect epochs can change while verification is in flight.
+            this.lease(ref);
+            await this.settle(r, result.state, 'reason' in result ? result.reason : undefined);
+            if (r.settled?.state === 'verified') {
+                if (this.stopped || this.failed || this.unavailable.has(r.member))
+                    throw new SignInRefused('unsupported');
+                r.settled.resume = newResume(r);
+                this.commit(); // action key/session/attempt durable BEFORE calling the gateway
+                r.settled.resume.state = await dispatchResume(r, this.s.resume);
+                this.commit();
+                this.ping(r);
+            }
+            return structuredClone(r);
+        });
+    }
+    async settle(r, state, reason) {
+        if (r.state === 'settled')
+            throw new SignInRefused('stale');
+        const broker = this.broker(r.member);
+        this.drop(r);
+        await this.closePrivate(r); // never lift before held targets (including probes/popups) are destroyed
+        r.state = 'settled';
+        r.settled = { state, ...(reason ? { reason } : {}), at: this.now() };
+        if (state === 'verified') {
+            const sites = Object.hasOwn(this.data.verified, r.member) ? this.data.verified[r.member] : (this.data.verified[r.member] = []);
+            if (!sites.includes(r.site))
+                sites.push(r.site);
+        }
+        this.commit();
+        await broker.fence(false);
+        await broker.navigateAgent(state === 'verified' ? this.data.host[r.id].checkUrl : 'reload');
+        this.ping(r);
+    }
+    cancel(id, gen, by) {
+        return this.serial(async () => {
+            const r = this.request(id, gen);
+            this.held(r, by.grant);
+            if (!['waiting', 'held', 'parked'].includes(r.state))
+                throw new SignInRefused('stale');
+            await this.settle(r, 'cancelled');
+            return structuredClone(r);
+        });
+    }
+    notNow(id, gen, by) {
+        return this.serial(async () => {
+            const r = this.request(id, gen);
+            this.held(r, by.grant);
+            if (!['waiting', 'held'].includes(r.state))
+                throw new SignInRefused('stale');
+            this.drop(r);
+            const broker = this.broker(r.member);
+            await this.closePrivate(r);
+            r.state = 'parked';
+            this.data.host[r.id].confirmed = [];
+            this.commit();
+            await broker.fence(false);
+            await broker.navigateAgent('reload');
+            this.ping(r);
+            return structuredClone(r);
+        });
+    }
+    reopen(id, gen, by) {
+        if (!this.fixture)
+            return Promise.reject(new HandoffUnprotected());
+        return this.serial(async () => {
+            const r = this.request(id, gen);
+            this.access(by.grant, r.member, true);
+            if (r.state !== 'parked')
+                throw new SignInRefused('stale');
+            r.state = 'waiting';
+            r.gen++;
+            r.expires = this.now() + (this.s.options.requestTtlMs ?? 1_800_000);
+            this.commit();
+            await this.broker(r.member).fence(true);
+            await this.s.park(r.member, r.sessionKey);
+            this.ping(r);
+            return structuredClone(r);
+        });
+    }
+    retry(id, gen, by) {
+        if (!this.fixture)
+            return Promise.reject(new HandoffUnprotected());
+        return this.serial(async () => {
+            const r = this.request(id, gen);
+            this.access(by.grant, r.member, true);
+            if (r.state !== 'settled' || r.settled?.state === 'verified')
+                throw new SignInRefused('stale');
+            return this.raiseLocked({ member: r.member, sessionKey: r.sessionKey, checkUrl: this.data.host[r.id].checkUrl,
+                reasons: r.reasons, hints: r.hints }, r.id);
+        });
+    }
+    async sweep() {
+        await this.serial(async () => {
+            for (const r of this.data.requests) {
+                if (['waiting', 'held'].includes(r.state) && this.now() >= r.expires) {
+                    await this.settle(r, 'expired');
+                    continue;
+                }
+                const l = this.leases.get(r.id);
+                if (l && r.state === 'held' && this.now() >= Math.min(l.deadline, l.value.expires))
+                    await this.lapse(r);
+            }
+        });
+    }
+    async closePrivate(r) {
+        this.closing.add(r.id);
+        const broker = this.broker(r.member);
+        try {
+            await broker.closePrivate();
+        }
+        catch {
+            r.state = 'settled';
+            r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+            this.unavailable.add(r.member);
+            this.commit();
+            this.ping(r);
+            void this.recover(r.member);
+            throw new SignInRefused('unsupported');
+        }
+        this.currentBroker(r.member, broker);
+        this.closing.delete(r.id);
+    }
+    async lapse(r) {
+        this.drop(r);
+        await this.closePrivate(r);
+        r.state = 'waiting';
+        r.gen++;
+        this.data.host[r.id].confirmed = [];
+        this.commit();
+        this.ping(r); // fence stays on
+    }
+    revokeGrant(grant) {
+        this.revoked.add(grant);
+        const requests = [...this.leases.entries()].filter(([, l]) => l.grant === grant).map(([id]) => this.request(id));
+        // Before any await: revoke every capability, detach input and close streams. No grace on revoke.
+        for (const r of requests) {
+            this.closing.add(r.id);
+            this.drop(r);
+        }
+        for (const s of this.streams)
+            if (s.grant === grant)
+                s.close('revoked');
+        return this.serial(async () => {
+            for (const r of requests) {
+                if (r.state === 'settled')
+                    continue;
+                try {
+                    await this.broker(r.member).closePrivate();
+                    r.state = 'waiting';
+                    r.gen++;
+                    this.data.host[r.id].confirmed = [];
+                    this.commit();
+                    this.closing.delete(r.id);
+                    this.ping(r);
+                }
+                catch {
+                    // A possibly-open private target cannot be reused. Fence remains held; no new lease.
+                    r.state = 'settled';
+                    r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+                    this.unavailable.add(r.member);
+                    this.commit();
+                    this.ping(r);
+                }
+            }
+        }).then(async () => { for (const member of new Set(requests.map(r => r.member)))
+            if (this.unavailable.has(member))
+                await this.recover(member); });
+    }
+    browserGone(member, expected = this.brokers.get(member)) {
+        // An old endpoint's delayed onExit must not tear down its replacement.
+        if (!expected || this.brokers.get(member) !== expected || this.attaching.has(member))
+            return Promise.resolve();
+        this.unavailable.add(member);
+        this.thumbs.delete(member);
+        this.bindingVersions.set(member, (this.bindingVersions.get(member) ?? 0) + 1);
+        this.streams.forEach(s => { if (s.member === member)
+            s.close('browser-gone'); });
+        this.epochs.set(member, (this.epochs.get(member) ?? 0) + 1);
+        return this.serial(async () => {
+            if (this.brokers.get(member) !== expected || this.attaching.has(member))
+                return;
+            for (const r of this.data.requests.filter(r => r.member === member)) {
+                this.drop(r);
+                recoverResume(r);
+                if (r.state === 'held' || r.state === 'checking') {
+                    r.state = 'settled';
+                    r.settled = { state: 'failed', reason: 'browser-gone', at: this.now() };
+                }
+                else if (r.state === 'waiting' || r.state === 'parked')
+                    r.gen++;
+            }
+            this.unavailable.add(member);
+            this.commit();
+            this.s.ping?.(member, 'state');
+        }).then(() => this.recover(member));
+    }
+    async recover(member) {
+        if (this.stopped || this.failed || this.recovery.has(member) || this.attaching.has(member))
+            return;
+        const old = this.brokers.get(member);
+        const epoch = this.epochs.get(member) ?? 0;
+        const current = () => !this.stopped && !this.failed && !this.attaching.has(member)
+            && this.brokers.get(member) === old && (this.epochs.get(member) ?? 0) === epoch;
+        const attempts = this.s.restart ? this.s.options.recovery?.attempts ?? 3 : 0;
+        // Close the old kit-owned endpoint before replacing its map entry; otherwise its server is orphaned.
+        try {
+            await old?.close();
+        }
+        catch {
+            if (current()) {
+                this.exhausted.add(member);
+                this.s.ping?.(member, 'state');
+            }
+            return;
+        }
+        if (!current())
+            return;
+        for (let attempt = 1; attempt <= attempts && current(); attempt++) {
+            const delay = this.s.options.recovery?.backoffMs[attempt - 1] ?? [1_000, 5_000, 15_000][attempt - 1];
+            this.recovery.set(member, { attempt, of: attempts, nextAt: this.now() + delay });
+            this.s.ping?.(member, 'state');
+            if (delay)
+                await new Promise(resolve => setTimeout(resolve, delay));
+            if (!current())
+                return;
+            try {
+                let expired = false;
+                let timer;
+                const launch = this.s.restart(member, attempt).then(async (broker) => {
+                    if (expired || !current()) {
+                        try {
+                            await broker?.close();
+                        }
+                        catch { /* owned stale candidate only */ }
+                        return undefined;
+                    }
+                    return broker;
+                });
+                let broker;
+                try {
+                    broker = await Promise.race([launch, new Promise(resolve => { timer = setTimeout(() => resolve(undefined), 30_000); })]);
+                }
+                finally {
+                    expired = true;
+                    clearTimeout(timer);
+                }
+                if (!broker)
+                    continue;
+                if (!current()) {
+                    await broker.close();
+                    return;
+                }
+                // Every recovered endpoint stays fenced until its canonical binding/config/policy ack. Never redispatch.
+                await broker.fence(true);
+                if (!current()) {
+                    await broker.close();
+                    return;
+                }
+                this.brokers.set(member, broker);
+                this.unavailable.delete(member);
+                this.recovery.delete(member);
+                this.bindingVersions.set(member, (this.bindingVersions.get(member) ?? 0) + 1);
+                this.s.ping?.(member, 'state');
+                return;
+            }
+            catch { /* bounded retries; details may contain endpoint credentials, never surface them */ }
+        }
+        if (current()) {
+            this.recovery.delete(member);
+            this.exhausted.add(member);
+            this.s.ping?.(member, 'state');
+        }
+    }
+    beforeRun(member, sessionKey) {
+        return this.serial(async () => {
+            const r = this.data.requests.find(r => r.member === member && r.sessionKey === sessionKey && r.state !== 'settled');
+            if (!r)
+                return true;
+            if (r.state !== 'parked')
+                return false;
+            await this.settle(r, 'cancelled', 'run-replaced');
+            return true;
+        });
+    }
+    thumbnail(source, by) {
+        this.access(by.grant, source.member, false);
+        if (source.kind !== 'browser')
+            return Promise.resolve({ state: 'unsupported' });
+        if (this.data.requests.some(r => r.member === source.member && open(r)))
+            return Promise.resolve({ state: 'private' });
+        if (!this.brokers.has(source.member) || this.unavailable.has(source.member) || this.stopped || this.failed)
+            return Promise.resolve({ state: 'off' });
+        const cached = this.thumbs.get(source.member);
+        if (cached && this.now() - cached.at < 5_000)
+            return Promise.resolve({ state: 'ok', frame: structuredClone(cached.frame) });
+        return this.captureThumbnail(source.member);
+    }
+    async captureThumbnail(member) {
+        const broker = this.broker(member);
+        let viewer;
+        let timer;
+        try {
+            viewer = broker.attachViewer({ maxWidth: 320 });
+            const result = await Promise.race([viewer.frames[Symbol.asyncIterator]().next(), new Promise(resolve => { timer = setTimeout(() => resolve(undefined), 2_000); })]);
+            // Privacy and endpoint identity are rechecked after awaiting a frame.
+            this.currentBroker(member, broker);
+            if (this.data.requests.some(r => r.member === member && open(r)))
+                return { state: 'private' };
+            if (!result || result.done || result.value.w > 320)
+                return { state: 'unsupported' };
+            const frame = structuredClone(result.value);
+            this.thumbs.set(member, { at: this.now(), frame });
+            return { state: 'ok', frame: structuredClone(frame) };
+        }
+        catch {
+            return { state: 'off' };
+        }
+        finally {
+            clearTimeout(timer);
+            viewer?.close();
+        }
+    }
+    live(source, o, on) {
+        this.access(o.grant, source.member, !!o.lease);
+        const mode = o.lease ? 'control' : 'observe';
+        let closed = false;
+        let viewer;
+        let l;
+        let r;
+        let attachDeadline;
+        let heartbeat;
+        const emit = (s) => on.state({ source, mode, ...s });
+        const stream = { member: source.member, grant: o.grant, control: !!o.lease, close: why => {
+                if (closed)
+                    return;
+                closed = true;
+                clearInterval(heartbeat);
+                viewer?.close();
+                this.streams.delete(stream);
+                if (!this.stopped && !this.failed && l && r && this.leases.get(r.id) === l && r.state === 'held') {
+                    l.attached = false;
+                    l.deadline = this.now() + l.value.graceMs;
+                    this.leaseTimer(r, l);
+                }
+                emit({ phase: 'ended', ...(why ? { why } : {}) });
+            } };
+        const inert = { input: (_i) => { throw new SignInRefused('not-control'); }, close: () => stream.close() };
+        if (source.kind !== 'browser') {
+            emit({ phase: 'failed', why: 'unsupported' });
+            return inert;
+        }
+        if (this.stopped || this.failed || this.unavailable.has(source.member)) {
+            emit({ phase: 'failed', why: 'browser-gone' });
+            return inert;
+        }
+        if (o.lease) {
+            const bound = this.lease(o.lease);
+            r = bound.r;
+            l = bound.l;
+            if (r.member !== source.member || l.grant !== o.grant)
+                throw new SignInRefused('not-lease-holder');
+            if (r.state !== 'held' || l.attached)
+                throw new SignInRefused('held-by-other');
+            attachDeadline = l.deadline;
+            l.attached = true;
+            l.deadline = l.value.expires;
+            this.leaseTimer(r, l);
+        }
+        else if (this.data.requests.some(r => r.member === source.member && open(r))) {
+            emit({ phase: 'private' });
+            return inert;
+        }
+        const broker = this.broker(source.member);
+        try {
+            viewer = broker.attachViewer({ ...(l ? { lease: { epoch: l.value.epoch, nonce: l.value.nonce } } : {}),
+                ...(o.maxWidth !== undefined ? { maxWidth: o.maxWidth } : {}) });
+        }
+        catch {
+            if (l && r) {
+                l.attached = false;
+                l.deadline = attachDeadline;
+                this.leaseTimer(r, l);
+            }
+            emit({ phase: 'failed', why: 'browser-gone' });
+            return inert;
+        }
+        this.streams.add(stream);
+        emit({ phase: 'connecting' });
+        if (l && r)
+            heartbeat = setInterval(() => {
+                try {
+                    this.lease(l.value);
+                    if (r.state !== 'held') {
+                        stream.close('superseded');
+                        return;
+                    }
+                    l.value.expires = this.now() + (this.s.options.leaseTtlMs ?? 600_000);
+                    l.deadline = l.value.expires;
+                    this.leaseTimer(r, l);
+                }
+                catch {
+                    stream.close('expired');
+                }
+            }, Math.max(1, Math.min(30_000, (this.s.options.leaseTtlMs ?? 600_000) / 3)));
+        heartbeat?.unref?.();
+        // Origins and the atomic input pause come from the broker, not frame contents or device input.
+        if (l && r)
+            void (async () => {
+                try {
+                    for await (const state of viewer.states) {
+                        if (closed)
+                            break;
+                        this.lease(l.value);
+                        emit({ phase: 'live', ...state, leaseExpires: l.value.expires });
+                    }
+                }
+                catch {
+                    stream.close('browser-gone');
+                }
+            })();
+        void (async () => {
+            try {
+                for await (const frame of viewer.frames) {
+                    if (closed)
+                        break;
+                    if (l && r) {
+                        this.lease(l.value);
+                        const state = broker.privateState();
+                        if (!state)
+                            throw new SignInRefused('stale');
+                        l.value.expires = this.now() + (this.s.options.leaseTtlMs ?? 600_000);
+                        l.deadline = l.value.expires;
+                        this.leaseTimer(r, l);
+                        emit({ phase: 'live', ...state, leaseExpires: l.value.expires });
+                    }
+                    else {
+                        if (this.data.requests.some(r => r.member === source.member && open(r))) {
+                            stream.close('superseded');
+                            break;
+                        }
+                        emit({ phase: 'live' });
+                    }
+                    if (!closed)
+                        on.frame(frame);
+                }
+                stream.close();
+            }
+            catch {
+                stream.close('browser-gone');
+            }
+        })();
+        return { input: (i) => {
+                if (closed)
+                    throw new SignInRefused('stale');
+                if (!l || !r)
+                    throw new SignInRefused('not-control');
+                this.lease(l.value);
+                if (r.state !== 'held')
+                    throw new SignInRefused('stale');
+                viewer.input(i); // Broker enforces exact bound origin, target, epoch and nonce at injection.
+            }, close: () => stream.close() };
+    }
+    forget(member, site, by) {
+        return this.serial(async () => {
+            this.access(by.grant, member, true);
+            if (this.data.requests.some(r => r.member === member && r.state !== 'settled'))
+                throw new SignInRefused('already-open');
+            if (site === 'all')
+                throw new SignInRefused('unsupported');
+            const requests = this.data.requests.filter(r => r.member === member && r.site === site);
+            const origins = [...new Set(requests.flatMap(r => [r.origin, ...this.data.host[r.id].confirmed]))];
+            if (!origins.length)
+                throw new SignInRefused('unsupported');
+            await this.broker(member).clearSite(origins);
+            this.data.verified[member] = (Object.hasOwn(this.data.verified, member) ? this.data.verified[member] : []).filter(s => s !== site);
+            this.commit();
+            this.s.ping?.(member, 'state');
+        });
+    }
+    knownIdps() {
+        return this.s.options.knownIdps ?? ['https://accounts.google.com', 'https://login.microsoftonline.com', 'https://login.live.com', 'https://appleid.apple.com', 'https://github.com'];
+    }
+    async close() {
+        // Invalidate synchronously before waiting on outstanding operations.
+        this.stopped = true;
+        clearTimeout(this.ttl);
+        for (const l of this.leases.values())
+            clearTimeout(l.timer);
+        this.streams.forEach(s => s.close('browser-gone'));
+        this.epochs.forEach((n, member) => this.epochs.set(member, n + 1));
+        await this.queue;
+        for (const broker of this.brokers.values())
+            await broker.close();
+    }
+}