@parall/daemon 1.46.0 → 1.48.0

package/dist/local-control.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Local (same-machine) control plane for the BYOC daemon — the ONLY human
+ * control surface for local browser profiles per
+ * docs/engineering-design/daemon-control-authorization-design.md §7.1.
+ *
+ * Transport: a per-user Unix domain socket under the daemon config dir
+ * (`<daemonConfigDir>/run/control.sock`), directory mode 0700 + socket mode
+ * 0600, so only the same OS user (the person who installed the daemon) can
+ * connect. The Parall Desktop shell — Electron main, never the renderer — is
+ * the intended client. The trust boundary is deliberately the OS user account:
+ * anything running as that user already owns `config.json` (the mck_), so the
+ * socket adds no new exposure; the platform-identity check (requester ==
+ * machines.created_by) is enforced by the supervisor's handler on top.
+ *
+ * Protocol: newline-delimited JSON, one request per line, one response per
+ * line, over a short-lived connection:
+ *   → {"id":"1","command":"profile.open","profile_id":"brp_x","requester_user_id":"usr_y"}
+ *   ← {"id":"1","ok":true,"result":{...}}
+ *   ← {"id":"1","ok":false,"error":{"code":"OWNER_MISMATCH","message":"..."}}
+ * Unknown fields are ignored (forward compat); unknown commands are rejected.
+ * Windows support (named pipe) is deliberately deferred — the Desktop daemon
+ * module is darwin-only today (design §7.1).
+ */
+export type LocalProfileAction = 'open' | 'stop' | 'reset';
+/** Typed failure a handler may throw; anything else maps to INTERNAL. */
+export declare class LocalControlError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface LocalControlHandlers {
+    /** Liveness + capability probe; the result rides back verbatim. */
+    ping(): Promise<Record<string, unknown>>;
+    /** Drive one local browser profile. Resolves when the action completed. */
+    profileControl(action: LocalProfileAction, profileId: string, requesterUserId: string): Promise<void>;
+}
+/** Socket path SSOT — the Desktop shell derives the same path from the shared
+ *  config dir (PRLL_DAEMON_CONFIG_DIR namespacing keeps staging/prod apart). */
+export declare function localControlSocketPath(env?: NodeJS.ProcessEnv): string;
+export interface LocalControlServerOptions {
+    socketPath: string;
+    handlers: LocalControlHandlers;
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+}
+export declare class LocalControlServer {
+    private readonly opts;
+    private server;
+    private readonly sockets;
+    constructor(opts: LocalControlServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleConnection;
+    private handleLine;
+    private reply;
+}
+//# sourceMappingURL=local-control.d.ts.map

package/dist/local-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-control.d.ts","sourceRoot":"","sources":["../src/local-control.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,yEAAyE;AACzE,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,2EAA2E;IAC3E,cAAc,CACZ,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAWD;gFACgF;AAChF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEnF;AA6BD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACrF;AAED,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAEpB,IAAI,EAAE,yBAAyB;IAEtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkEtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B,OAAO,CAAC,gBAAgB;YA0BV,UAAU;IAuDxB,OAAO,CAAC,KAAK;CAiBd"}

package/dist/local-control.js

@@ -0,0 +1,230 @@
+import { chmodSync, existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { daemonConfigDir } from './daemon-paths.js';
+/** Typed failure a handler may throw; anything else maps to INTERNAL. */
+export class LocalControlError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalControlError';
+    }
+}
+const MAX_LINE_BYTES = 16 * 1024;
+/** Socket path SSOT — the Desktop shell derives the same path from the shared
+ *  config dir (PRLL_DAEMON_CONFIG_DIR namespacing keeps staging/prod apart). */
+export function localControlSocketPath(env = process.env) {
+    return path.join(daemonConfigDir(env), 'run', 'control.sock');
+}
+/**
+ * Is something actually listening on this socket path? Used to tell a crashed
+ * daemon's leftover socket (safe to unlink) from a live one (must never be
+ * stolen — see start()). Fail-closed: only a definitive connection refusal
+ * (nothing is bound) counts as stale; any other error is treated as live so an
+ * ambiguous probe never licenses a unlink.
+ */
+function isSocketLive(sockPath) {
+    return new Promise((resolve) => {
+        const probe = net.connect(sockPath);
+        const done = (live) => {
+            probe.removeAllListeners();
+            probe.destroy();
+            clearTimeout(timer);
+            resolve(live);
+        };
+        // A bound-but-wedged peer may accept without ever replying; treat the
+        // silence as live (do not steal the path from a process that exists).
+        const timer = setTimeout(() => done(true), 1000);
+        probe.once('connect', () => done(true));
+        probe.once('error', (err) => {
+            // ECONNREFUSED (nobody listening) / ENOENT (already gone) ⇒ stale.
+            done(!(err.code === 'ECONNREFUSED' || err.code === 'ENOENT'));
+        });
+    });
+}
+export class LocalControlServer {
+    opts;
+    server = null;
+    sockets = new Set();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async start() {
+        if (this.server)
+            throw new Error('local control server already started');
+        const sockPath = this.opts.socketPath;
+        const dir = path.dirname(sockPath);
+        // 0700 dir is the primary boundary; the socket chmod below is the backstop.
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        // Fail closed if the directory cannot be restricted: the 0700 dir is the
+        // primary boundary (a group/world-writable dir lets another user rename or
+        // replace the socket regardless of the socket file's own 0600), so a
+        // control plane we cannot isolate must not serve at all — same posture as
+        // the socket chmod below.
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch (err) {
+            throw new Error(`could not restrict control socket directory: ${String(err)}`);
+        }
+        // Reclaim a socket left behind by a crash — but ONLY after proving nothing
+        // is listening. Unlinking is not safe by default: on Unix it removes the
+        // PATHNAME, not the live socket, so a blind unlink would silently steal the
+        // path from a running daemon (its existing connections survive, new clients
+        // reach us instead) and listen() would then succeed rather than reporting
+        // EADDRINUSE. Probe first: connect-refused ⇒ nobody is listening ⇒ stale.
+        if (existsSync(sockPath)) {
+            let st;
+            try {
+                st = statSync(sockPath);
+            }
+            catch (err) {
+                throw new Error(`could not inspect existing control socket: ${String(err)}`);
+            }
+            // A non-socket file is unknown state — never delete it; let listen() fail.
+            if (st.isSocket()) {
+                if (await isSocketLive(sockPath)) {
+                    throw new Error(`another process is already serving the local control socket at ${sockPath}`);
+                }
+                rmSync(sockPath, { force: true });
+            }
+        }
+        const server = net.createServer((socket) => this.handleConnection(socket));
+        this.server = server;
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                this.server = null;
+                reject(err);
+            };
+            server.once('error', onError);
+            server.listen(sockPath, () => {
+                server.removeListener('error', onError);
+                try {
+                    chmodSync(sockPath, 0o600);
+                }
+                catch (err) {
+                    // Fail closed: a control socket we cannot restrict must not serve.
+                    server.close();
+                    this.server = null;
+                    reject(new Error(`could not restrict control socket permissions: ${String(err)}`));
+                    return;
+                }
+                resolve();
+            });
+        });
+        server.on('error', (err) => this.opts.log.warn(`local control server error: ${String(err)}`));
+        this.opts.log.info(`local control socket listening at ${sockPath}`);
+    }
+    async stop() {
+        const server = this.server;
+        if (!server)
+            return;
+        this.server = null;
+        for (const s of this.sockets)
+            s.destroy();
+        this.sockets.clear();
+        await new Promise((resolve) => server.close(() => resolve()));
+        try {
+            rmSync(this.opts.socketPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    handleConnection(socket) {
+        this.sockets.add(socket);
+        socket.on('close', () => this.sockets.delete(socket));
+        socket.on('error', () => socket.destroy());
+        socket.setEncoding('utf8');
+        let buffer = '';
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES) {
+                // end() (half-close after flush), NOT destroy(): the reply must reach
+                // the client, and destroy() can discard the still-buffered write.
+                this.reply(socket, undefined, { code: 'INVALID_REQUEST', message: 'request too large' });
+                socket.end();
+                return;
+            }
+            let newline = buffer.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line)
+                    void this.handleLine(socket, line);
+                newline = buffer.indexOf('\n');
+            }
+        });
+    }
+    async handleLine(socket, line) {
+        let req;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new Error('not an object');
+            }
+            req = parsed;
+        }
+        catch {
+            // end() not destroy() — flush the error reply before closing (see above).
+            this.reply(socket, undefined, { code: 'INVALID_REQUEST', message: 'invalid JSON request' });
+            socket.end();
+            return;
+        }
+        const id = typeof req.id === 'string' ? req.id : undefined;
+        try {
+            switch (req.command) {
+                case 'ping': {
+                    const result = await this.opts.handlers.ping();
+                    this.reply(socket, id, undefined, result);
+                    return;
+                }
+                case 'profile.open':
+                case 'profile.stop':
+                case 'profile.reset': {
+                    const action = req.command.slice('profile.'.length);
+                    const profileId = typeof req.profile_id === 'string' ? req.profile_id.trim() : '';
+                    const requester = typeof req.requester_user_id === 'string' ? req.requester_user_id.trim() : '';
+                    if (!profileId || !requester) {
+                        throw new LocalControlError('INVALID_REQUEST', 'profile_id and requester_user_id are required');
+                    }
+                    await this.opts.handlers.profileControl(action, profileId, requester);
+                    this.reply(socket, id, undefined, { status: 'ok' });
+                    return;
+                }
+                default:
+                    throw new LocalControlError('UNKNOWN_COMMAND', `unknown command ${String(req.command)}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof LocalControlError) {
+                this.reply(socket, id, { code: err.code, message: err.message });
+            }
+            else {
+                this.opts.log.warn(`local control command failed: ${String(err)}`);
+                this.reply(socket, id, {
+                    code: 'INTERNAL',
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    reply(socket, id, error, result) {
+        if (socket.destroyed)
+            return;
+        const payload = { ok: !error };
+        if (id !== undefined)
+            payload.id = id;
+        if (error)
+            payload.error = error;
+        if (result !== undefined)
+            payload.result = result;
+        try {
+            socket.write(`${JSON.stringify(payload)}\n`);
+        }
+        catch {
+            socket.destroy();
+        }
+    }
+}

package/dist/local-profile-control.d.ts

@@ -0,0 +1,77 @@
+import type { MachineBrowserProfile } from '@parall/sdk';
+import type { BrowserProfilePool } from './clip-runtime/browser-profile-pool.js';
+import { LocalControlServer, type LocalProfileAction } from './local-control.js';
+/**
+ * Same-machine browser-profile control (design daemon-control-authorization
+ * §7.1) — the daemon's local control PLANE: the socket server's lifecycle plus
+ * the authorization + drive logic behind profile.open/stop/reset. The socket
+ * transport itself lives in local-control.ts; the supervisor owns the pool, the
+ * queues, and the machine identity and lends them here.
+ */
+/**
+ * What the handler needs from the supervisor. Identity and pool are getters,
+ * not values: both change over the daemon's life (bootstrap / refresh /
+ * provider state), and the handler must read whatever is true AT CALL TIME —
+ * a snapshot captured at wiring time could authorize against a stale owner.
+ */
+export interface LocalProfileControlDeps {
+    /** machines.created_by; null until bootstrap proves one — then fail closed. */
+    owner(): string | null;
+    /** null when the browser-profile runtime is disabled on this daemon. */
+    pool(): BrowserProfilePool | null;
+    /** mck_-scoped GET /machines/me/browser-profiles — the assignment SSOT. */
+    listProfiles(): Promise<MachineBrowserProfile[]>;
+    /** Queue a revive (tracked for reconnect-reconcile fencing). */
+    enqueueRevive(profileId: string, op: () => Promise<void>): Promise<void>;
+    /** Queue a non-revive op (stop / reset). */
+    enqueueOp(profileId: string, op: () => Promise<void>): Promise<void>;
+    wipeBeforeRevive(pool: BrowserProfilePool, profileId: string, resetGen: number, generation: number | undefined): Promise<void>;
+}
+/** Extra facts the ping probe reports back to the Desktop shell. */
+export interface LocalProfileControlPlaneDeps extends LocalProfileControlDeps {
+    machineId(): string | null;
+    orgId(): string | null;
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+}
+/**
+ * Start the same-machine control plane: a per-user Unix socket the owner's
+ * Desktop drives local browser profiles through.
+ *
+ * Local machines only — a K8s daemon has no same-machine human, and win32 has
+ * no Unix socket support here (design §7.1 defers the named pipe). Returns null
+ * when the plane does not apply OR fails to bind: failure is non-fatal, since
+ * the daemon's agent/clip duties are independent and the Desktop's ping probe
+ * simply reports the capability absent. The caller owns stop().
+ */
+export declare function startLocalProfileControl(deps: LocalProfileControlPlaneDeps): Promise<LocalControlServer | null>;
+/**
+ * TRUST MODEL — be precise about what each layer actually proves:
+ *  - The 0600 socket + 0700 dir prove "same OS user on this machine". That
+ *    is the REAL isolation boundary, and it is a hard one: that user already
+ *    owns config.json (the mck_), so they could drive this machine anyway.
+ *  - `requesterUserId` is supplied by the Desktop shell from the identity the
+ *    web layer reported at auth:report-state. The shell holds no tokens (by
+ *    design), so this is the app's assertion — NOT an independently verified
+ *    identity. It is enforced here so the honest cases are right (a different
+ *    Parall account signed into this computer's Desktop is refused, and a
+ *    bridge call cannot name an arbitrary user), but it is defense in depth
+ *    on top of the OS-user boundary, not a substitute for it.
+ *  - The profile must be listed by the server FOR THIS MACHINE (the
+ *    mck_-scoped /machines/me/browser-profiles is the SSOT — it also delivers
+ *    the current lifecycle/reset generations, so status reports land under the
+ *    server's fence exactly like the WS event path). This one IS
+ *    server-authoritative.
+ * All three fail closed.
+ *
+ * The action then flows through the SAME fence + queue discipline as the WS
+ * lifecycle path (pre-fence on stop/reset, reset-before-open fail-closed,
+ * sinceSeq stale-revive capture) — but unlike the WS handler it PROPAGATES
+ * failures, so the Desktop caller gets a real error instead of a log line.
+ * Status converges server-side through the pool's normal reportStatus.
+ */
+export declare function handleLocalProfileControl(deps: LocalProfileControlDeps, action: LocalProfileAction, profileId: string, requesterUserId: string): Promise<void>;
+//# sourceMappingURL=local-profile-control.d.ts.map

package/dist/local-profile-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-profile-control.d.ts","sourceRoot":"","sources":["../src/local-profile-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAEL,kBAAkB,EAClB,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,KAAK,IAAI,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,IAAI,IAAI,kBAAkB,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IACjD,gEAAgE;IAChE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,4CAA4C;IAC5C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,gBAAgB,CACd,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,IAAI,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACrF;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAsBpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,uBAAuB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CA2Df"}

package/dist/local-profile-control.js

@@ -0,0 +1,108 @@
+import { LocalControlError, LocalControlServer, localControlSocketPath, } from './local-control.js';
+/**
+ * Start the same-machine control plane: a per-user Unix socket the owner's
+ * Desktop drives local browser profiles through.
+ *
+ * Local machines only — a K8s daemon has no same-machine human, and win32 has
+ * no Unix socket support here (design §7.1 defers the named pipe). Returns null
+ * when the plane does not apply OR fails to bind: failure is non-fatal, since
+ * the daemon's agent/clip duties are independent and the Desktop's ping probe
+ * simply reports the capability absent. The caller owns stop().
+ */
+export async function startLocalProfileControl(deps) {
+    if (process.env.KUBERNETES_SERVICE_HOST || process.platform === 'win32')
+        return null;
+    const server = new LocalControlServer({
+        socketPath: localControlSocketPath(),
+        log: deps.log,
+        handlers: {
+            ping: async () => ({
+                machine_id: deps.machineId(),
+                org_id: deps.orgId(),
+                profile_control: deps.pool() !== null,
+            }),
+            profileControl: (action, profileId, requesterUserId) => handleLocalProfileControl(deps, action, profileId, requesterUserId),
+        },
+    });
+    try {
+        await server.start();
+        return server;
+    }
+    catch (err) {
+        deps.log.warn(`local control socket unavailable: ${String(err)}`);
+        return null;
+    }
+}
+/**
+ * TRUST MODEL — be precise about what each layer actually proves:
+ *  - The 0600 socket + 0700 dir prove "same OS user on this machine". That
+ *    is the REAL isolation boundary, and it is a hard one: that user already
+ *    owns config.json (the mck_), so they could drive this machine anyway.
+ *  - `requesterUserId` is supplied by the Desktop shell from the identity the
+ *    web layer reported at auth:report-state. The shell holds no tokens (by
+ *    design), so this is the app's assertion — NOT an independently verified
+ *    identity. It is enforced here so the honest cases are right (a different
+ *    Parall account signed into this computer's Desktop is refused, and a
+ *    bridge call cannot name an arbitrary user), but it is defense in depth
+ *    on top of the OS-user boundary, not a substitute for it.
+ *  - The profile must be listed by the server FOR THIS MACHINE (the
+ *    mck_-scoped /machines/me/browser-profiles is the SSOT — it also delivers
+ *    the current lifecycle/reset generations, so status reports land under the
+ *    server's fence exactly like the WS event path). This one IS
+ *    server-authoritative.
+ * All three fail closed.
+ *
+ * The action then flows through the SAME fence + queue discipline as the WS
+ * lifecycle path (pre-fence on stop/reset, reset-before-open fail-closed,
+ * sinceSeq stale-revive capture) — but unlike the WS handler it PROPAGATES
+ * failures, so the Desktop caller gets a real error instead of a log line.
+ * Status converges server-side through the pool's normal reportStatus.
+ */
+export async function handleLocalProfileControl(deps, action, profileId, requesterUserId) {
+    const owner = deps.owner();
+    if (!owner || !requesterUserId || requesterUserId !== owner) {
+        throw new LocalControlError('OWNER_MISMATCH', 'Only the machine owner can control local browser profiles');
+    }
+    const pool = deps.pool();
+    if (!pool) {
+        throw new LocalControlError('RUNTIME_DISABLED', 'Browser profile runtime is disabled on this daemon');
+    }
+    let profiles;
+    try {
+        profiles = await deps.listProfiles();
+    }
+    catch (err) {
+        throw new LocalControlError('SERVER_UNAVAILABLE', `could not verify the profile with the server: ${String(err)}`);
+    }
+    const profile = profiles.find((p) => p.id === profileId && p.machine_id);
+    if (!profile) {
+        throw new LocalControlError('PROFILE_NOT_ON_MACHINE', 'Browser profile is not assigned to this machine');
+    }
+    const generation = profile.lifecycle_generation;
+    if (action === 'open') {
+        // Mirror the WS open path: a reset recorded on the server but not yet
+        // applied locally must wipe BEFORE the open (fail-closed), and the fence
+        // generation is captured after any pre-fence so a concurrent stop wins.
+        const resetGen = profile.reset_generation ?? 0;
+        const wipeGen = resetGen > pool.appliedResetGeneration(profileId) ? resetGen : null;
+        if (wipeGen !== null)
+            pool.fence(profileId);
+        const sinceSeq = pool.stopSeqOf(profileId);
+        await deps.enqueueRevive(profileId, async () => {
+            if (wipeGen !== null)
+                await deps.wipeBeforeRevive(pool, profileId, wipeGen, generation);
+            await pool.openProfile(profileId, undefined, sinceSeq, generation);
+        });
+        return;
+    }
+    // stop / reset: pre-fence synchronously (reject hub invokes racing the
+    // queued teardown), same contract as the WS event receipt.
+    pool.fence(profileId);
+    if (action === 'stop') {
+        await deps.enqueueOp(profileId, () => pool.stopProfile(profileId, generation));
+        return;
+    }
+    // Local reset wipes immediately; record the server's current
+    // reset_generation as applied so a reconnect reconcile won't re-wipe.
+    await deps.enqueueOp(profileId, () => pool.resetProfile(profileId, generation, profile.reset_generation));
+}

package/dist/supervisor.d.ts

@@ -1,6 +1,7 @@
 import { type GatewayLogger } from '@parall/agent-core';
 import { type ParallClient } from '@parall/sdk';
 import { type ClaudeDaemonConfig } from './config.js';
+import { type LocalProfileControlPlaneDeps } from './local-profile-control.js';
 import type { DaemonUpdater } from './updater.js';
 import type { PendingUpdateHealthGate } from './update-health-gate.js';
 /**
@@ -39,6 +40,7 @@ export declare class DaemonSupervisor {
     private running;
     private machineId;
     private machineOrgId;
+    private machineCreatedBy;
     private machineLlmSource;
     private machineProviderEnabled;
     private machineClipProviderUrl;
@@ -47,6 +49,7 @@ export declare class DaemonSupervisor {
     private updater;
     private healthGate;
     private browserProfilePool;
+    private localControl;
     private clipManager;
     private clipProvider;
     private clipReconcileTimer;
@@ -99,6 +102,16 @@ export declare class DaemonSupervisor {
     private handleFilesystemBrowse;
     private handleBrowserProfileLifecycle;
     private enqueueBrowserProfileLifecycle;
+    /**
+     * What the supervisor lends the local control plane: identity, pool, queues.
+     * Getters, not values — owner and pool both change over the daemon's life
+     * (bootstrap / refresh / provider state), so the handler must read what is
+     * true AT CALL TIME; a snapshot could authorize against a stale owner.
+     *
+     * One definition, used by both `run()` and the authorization tests, so the
+     * matrix under test is wired exactly like production.
+     */
+    localProfileControlDeps(): LocalProfileControlPlaneDeps;
     private enqueueBrowserProfileOp;
     private enqueueBrowserProfileRevive;
     /**

package/dist/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/supervisor.js

@@ -11,6 +11,7 @@ import { BrowserProfilePool, ClipProcessManager, ClipProvider, HubClient, } from
 import { agentClaudeHomeFor, agentHomeDirFor, agentStateDirFor, agentWorkspaceDirFor, } from './config.js';
 import { reconcileBrowserProfiles as runBrowserProfileReconcile } from './browser-profile-reconcile.js';
 import { listDirectory } from './filesystem.js';
+import { startLocalProfileControl, } from './local-profile-control.js';
 import { ensureIsolatedHome, ensureSharedCredentialLink, } from './home-isolation.js';
 import { assertAgentKey, getRuntimeAdapter } from './runtimes.js';
 import { applyRuntimeBinaryEnv } from './runtime-bin-resolver.js';
@@ -99,6 +100,11 @@ export class DaemonSupervisor {
     running = false;
     machineId = null;
     machineOrgId = null;
+    // machines.created_by — the machine owner. The local control socket's profile
+    // commands are authorized against it (requester must BE the owner); kept
+    // fresh via bootstrap + refreshMachineConfig. Null until bootstrap → the
+    // local control plane fails closed.
+    machineCreatedBy = null;
     machineLlmSource = 'parall';
     // Whether this machine contributes its local clips as a hub provider. The
     // org admin toggles it via PATCH /machines/{id}/provider-enabled; default true.
@@ -117,6 +123,7 @@ export class DaemonSupervisor {
     // browserProfilePool replaces the old single browserProfileManager.
     healthGate = null;
     browserProfilePool = null;
+    localControl = null;
     clipManager = null;
     clipProvider = null;
     clipReconcileTimer = null;
@@ -215,6 +222,9 @@ export class DaemonSupervisor {
             await this.applyClipProviderState();
             this.startClipReconcileTimer();
         }
+        // Same-machine control plane (design daemon-control-authorization §7.1) —
+        // socket lifecycle + authorization live in local-profile-control.ts.
+        this.localControl = await startLocalProfileControl(this.localProfileControlDeps());
         // Report daemon version + self-update capability + detected runtime CLIs
         // via heartbeat (best-effort, off the critical path — detection spawns
         // `--version` probes). Capability tracks whether a service manager
@@ -360,6 +370,10 @@ export class DaemonSupervisor {
             }
             exits.push(this.terminateChild(state));
         }
+        if (this.localControl) {
+            exits.push(this.localControl.stop());
+            this.localControl = null;
+        }
         if (this.clipProvider) {
             exits.push(this.clipProvider.disconnect());
             this.clipProvider = null;
@@ -388,6 +402,7 @@ export class DaemonSupervisor {
                 const machine = await this.client.getMachineSelf();
                 this.machineId = machine.id;
                 this.machineOrgId = machine.org_id;
+                this.machineCreatedBy = machine.created_by ?? null;
                 this.machineLlmSource = machine.llm_source ?? 'parall';
                 this.machineProviderEnabled = machine.provider_enabled ?? true;
                 this.machineClipProviderUrl = machine.clip_provider_url ?? null;
@@ -807,6 +822,28 @@ export class DaemonSupervisor {
             ? this.enqueueBrowserProfileRevive(data.profile_id, op)
             : this.enqueueBrowserProfileOp(data.profile_id, op);
     }
+    /**
+     * What the supervisor lends the local control plane: identity, pool, queues.
+     * Getters, not values — owner and pool both change over the daemon's life
+     * (bootstrap / refresh / provider state), so the handler must read what is
+     * true AT CALL TIME; a snapshot could authorize against a stale owner.
+     *
+     * One definition, used by both `run()` and the authorization tests, so the
+     * matrix under test is wired exactly like production.
+     */
+    localProfileControlDeps() {
+        return {
+            log: this.log,
+            machineId: () => this.machineId,
+            orgId: () => this.machineOrgId,
+            owner: () => this.machineCreatedBy,
+            pool: () => this.browserProfilePool,
+            listProfiles: () => this.client.listMachineBrowserProfiles(),
+            enqueueRevive: (id, op) => this.enqueueBrowserProfileRevive(id, op),
+            enqueueOp: (id, op) => this.enqueueBrowserProfileOp(id, op),
+            wipeBeforeRevive: (pool, id, resetGen, gen) => this.wipeBeforeRevive(pool, id, resetGen, gen),
+        };
+    }
     enqueueBrowserProfileOp(profileId, op) {
         const previous = this.browserProfileOpQueues.get(profileId) ?? Promise.resolve();
         const next = previous
@@ -1168,6 +1205,11 @@ export class DaemonSupervisor {
     async refreshMachineConfig() {
         try {
             const machine = await this.client.getMachineSelf();
+            // Fail closed, exactly like bootstrap: an absent created_by means the
+            // server no longer proves an owner, so keeping the previous one would let
+            // a revoked user keep driving profiles over the local socket. No owner =>
+            // no local control, until a refresh proves one again.
+            this.machineCreatedBy = machine.created_by ?? null;
             const newSource = machine.llm_source ?? 'parall';
             if (newSource !== this.machineLlmSource) {
                 this.log.info(`machine config refreshed: llm_source ${this.machineLlmSource} → ${newSource}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/daemon",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Parall local agent runtime — daemon supervisor + bridge runtimes, bundled as standalone JS files",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,11 @@
     "@aws-sdk/client-s3": "3.984.0",
     "@pinixai/bb-browser-pro": "0.15.0",
     "ws": "^8.18.0",
-    "@parall/agent-core": "1.46.0",
-    "@parall/sdk": "1.46.0",
-    "@parall/claude-agent": "1.46.0",
-    "@parall/codex-agent": "1.46.0",
-    "@parall/openclaw-agent": "1.46.0"
+    "@parall/sdk": "1.48.0",
+    "@parall/codex-agent": "1.48.0",
+    "@parall/openclaw-agent": "1.48.0",
+    "@parall/claude-agent": "1.48.0",
+    "@parall/agent-core": "1.48.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",