@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/devices/device-provider.js

@@ -0,0 +1,151 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { environmentNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { DeviceRelay, environmentOffline } from "./relay.js";
+import { DeviceTargets, sameRoots } from "./targets.js";
+/** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
+export const EXEC_DEADLINE_MARGIN_MS = 5000;
+/** How long the machine may take for one non-exec operation. */
+export const OP_DEADLINE_MS = 30_000;
+/**
+ * Room left in a frame for everything around a `readFile` result's base64 data (the `res`
+ * envelope): a read is clamped so the machine's answer fits `environments.device.maxFrameBytes`
+ * (ruling R26).
+ */
+export const FRAME_ENVELOPE_BYTES = 64 * 1024;
+/** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
+export const maxReadBytes = (maxFrameBytes) => Math.max(0, Math.floor((maxFrameBytes - FRAME_ENVELOPE_BYTES) / 4) * 3);
+const NAME_PREFIX = "cap-env-";
+/** The environment id of a `cap-env-<environmentId>` name; undefined for any other name. */
+export const environmentIdOfName = (name) => name.startsWith(NAME_PREFIX) && name.length > NAME_PREFIX.length
+    ? name.slice(NAME_PREFIX.length)
+    : undefined;
+const rootsOf = (h) => h.roots;
+const bytesOf = (b64) => new Uint8Array(Buffer.from(b64, "base64"));
+/**
+ * The kernel-internal provider `@device` (environments spec §13.5): every operation runs on the
+ * environment's connected machine through the {@link DeviceRelay}. The file system is the
+ * machine's environment directory (the program creates it on first use), so `createFileSystem`
+ * touches nothing; `suspend` and `destroy` do nothing (the machine is not the platform's to stop);
+ * deleting the environment leaves the files on the machine where they are. Nothing here throws `environment.offline` on the cleanup paths (ruling R9).
+ *
+ * The files on a machine are its owner's: `destroyFileSystem` (a files reset, the deletion sweep)
+ * does nothing; the deletion's `stop` comes from `MachinesService.revokeActive` (ruling R24).
+ */
+let DeviceSandboxProvider = class DeviceSandboxProvider {
+    relay;
+    targets;
+    sandbox;
+    config;
+    concurrentExec = true;
+    sessionIsolation = false;
+    constructor(relay, targets, sandbox, config) {
+        this.relay = relay;
+        this.targets = targets;
+        this.sandbox = sandbox;
+        this.config = config;
+    }
+    async createFileSystem(args) {
+        args.signal.throwIfAborted();
+        const id = environmentIdOfName(args.name);
+        if (id === undefined)
+            throw new Error(`not an environment name: ${args.name}`);
+        return { id };
+    }
+    /** The files are the machine owner's: nothing to do (ruling R24; never a `stop`). */
+    async destroyFileSystem(_fs, signal) {
+        signal.throwIfAborted();
+    }
+    async destroyFileSystemByName(_name, signal) {
+        signal.throwIfAborted();
+    }
+    async create(args) {
+        const id = args.fileSystem.id;
+        const r = await this.relay.call(id, "create", { limits: args.limits }, { deadlineMs: OP_DEADLINE_MS, signal: args.signal });
+        return { id, roots: r.roots, limits: args.limits };
+    }
+    /**
+     * Needs the machine online. `gone` (the kernel recreates the instance) when the active machine
+     * last reported other roots than the instance was created with (a new login into another
+     * directory or mode, ruling R23).
+     */
+    async resume(h, signal) {
+        signal.throwIfAborted();
+        if (!(await this.relay.holderLive(h.id)))
+            throw environmentOffline();
+        const had = rootsOf(h);
+        const now = await this.targets.machineRoots(h.id);
+        if (had === undefined || (now !== null && !sameRoots(had, now)))
+            return "gone";
+        return "resumed";
+    }
+    async suspend(_h, signal) {
+        signal.throwIfAborted();
+    }
+    async destroy(_h, signal) {
+        signal.throwIfAborted();
+    }
+    async destroyByName(_name, signal) {
+        signal.throwIfAborted();
+    }
+    async killAll(h, signal) {
+        await this.relay.call(h.id, "killAll", {}, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async killTagged(h, tags, signal) {
+        await this.relay.call(h.id, "killTagged", { tags }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async exec(h, args) {
+        const { signal, ...rest } = args;
+        signal.throwIfAborted();
+        const limits = await this.currentLimits(h.id);
+        signal.throwIfAborted();
+        try {
+            return await this.relay.call(h.id, "exec", { ...rest, limits }, { deadlineMs: args.timeoutMs + EXEC_DEADLINE_MARGIN_MS, signal });
+        }
+        catch (e) {
+            // the contract: an exec aborted after it was sent resolves with exitCode null (the relay
+            // queued a cancel, which kills the command on the machine); the output stays there
+            if (signal.aborted && e === signal.reason) {
+                return { exitCode: null, stdout: "", stderr: "", truncated: false, timedOut: false };
+            }
+            throw e;
+        }
+    }
+    async readFile(h, path, opts) {
+        // the answer must fit one frame: a larger file comes back truncated (Deliver: too large)
+        const maxBytes = Math.min(opts.maxBytes, maxReadBytes(this.config.get().environments.device.maxFrameBytes));
+        const r = await this.relay.call(h.id, "readFile", { path, maxBytes }, { deadlineMs: OP_DEADLINE_MS, signal: opts.signal });
+        return r === null ? null : { data: bytesOf(r.dataB64), truncated: r.truncated };
+    }
+    async writeFile(h, path, data, signal) {
+        const dataB64 = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("base64");
+        await this.relay.call(h.id, "writeFile", { path, dataB64 }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async stat(h, path, signal) {
+        return this.relay.call(h.id, "stat", { path }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    /** The org's effective limits now (ruling R27); a deleted environment is not found. */
+    async currentLimits(environmentId) {
+        const orgId = await this.targets.orgOf(environmentId);
+        if (orgId === null)
+            throw environmentNotFound();
+        return this.sandbox.orgLimits(orgId);
+    }
+};
+DeviceSandboxProvider = __decorate([
+    Injectable(),
+    __param(0, Inject(DeviceRelay)),
+    __param(1, Inject(DeviceTargets)),
+    __param(2, Inject(SandboxService)),
+    __param(3, Inject(KernelConfigService))
+], DeviceSandboxProvider);
+export { DeviceSandboxProvider };

package/dist/devices/device-routes.d.ts

@@ -0,0 +1,36 @@
+import { type WebSocket } from "@fastify/websocket";
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import type { MachineIdentity } from "./machines.js";
+/** The device connection route (environments spec §13.4). */
+export declare const DEVICE_CONNECT_ROUTE = "/device/connect";
+/** The header carrying the program's protocol version. */
+export declare const DEVICE_PROTOCOL_HEADER = "x-capybara-device-protocol";
+/** What the route needs from the gateway (`DeviceGateway`). */
+export interface DeviceRoutesGateway {
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    accept(socket: WebSocket, identity: MachineIdentity, credential: string): void;
+}
+export interface DeviceRoutesOptions {
+    gateway: DeviceRoutesGateway;
+    /** `environments.device.maxFrameBytes`: a larger incoming frame closes the socket (1009). */
+    maxFrameBytes: number;
+}
+/**
+ * A WebSocket upgrade: `Upgrade` lists `websocket` and `Connection` lists `upgrade` (both
+ * case-insensitive). Other upgrades (`h2c`, …) are ordinary requests here.
+ */
+export declare function isWebSocketUpgrade(req: FastifyRequest): boolean;
+/**
+ * Registers `GET /device/connect` (the gateway role only) in its own encapsulated scope with
+ * `@fastify/websocket`: a raw Fastify route outside Nest, so neither the API's `AuthGuard` nor its
+ * CSRF check applies; the route checks the machine credential itself, before the upgrade (401
+ * `device.credential_invalid`), then the protocol header (426 `environment.program_outdated`).
+ * Must be called before Nest `app.init()`, on the root instance.
+ *
+ * `@fastify/websocket` sends every upgrade request of the server through the Fastify router; the
+ * root hooks below keep that from reaching any other route: a WebSocket upgrade to another path
+ * is answered 404 and its socket closed once answered (Node would have dropped it without a
+ * listener). Other upgrades (`h2c`) reach their route as ordinary requests; their socket, which
+ * no HTTP connection owns any more, is closed once answered as well (the upgrade is declined).
+ */
+export declare function registerDeviceConnectRoute(fastify: FastifyInstance, opts: DeviceRoutesOptions): Promise<void>;

package/dist/devices/device-routes.js

@@ -0,0 +1,90 @@
+import { DEVICE_PROTOCOL_VERSION } from "@capybara-hq/plugin-sdk";
+import websocket, {} from "@fastify/websocket";
+import { errorBody } from "../errors.js";
+/** The device connection route (environments spec §13.4). */
+export const DEVICE_CONNECT_ROUTE = "/device/connect";
+/** The header carrying the program's protocol version. */
+export const DEVICE_PROTOCOL_HEADER = "x-capybara-device-protocol";
+/** The comma-separated tokens of a header, lowercased. */
+function tokens(v) {
+    return [v ?? []]
+        .flat()
+        .flatMap((x) => x.split(","))
+        .map((t) => t.trim().toLowerCase());
+}
+/**
+ * A WebSocket upgrade: `Upgrade` lists `websocket` and `Connection` lists `upgrade` (both
+ * case-insensitive). Other upgrades (`h2c`, …) are ordinary requests here.
+ */
+export function isWebSocketUpgrade(req) {
+    return viaUpgrade(req) && tokens(req.headers.upgrade).includes("websocket");
+}
+/**
+ * A request Node handed to the server's `upgrade` listeners (`Connection: upgrade` and an
+ * `Upgrade` header, any protocol): its socket belongs to no HTTP connection any more.
+ */
+function viaUpgrade(req) {
+    return req.headers.upgrade !== undefined && tokens(req.headers.connection).includes("upgrade");
+}
+/** The `Bearer` credential of the request, or "". */
+function bearer(req) {
+    const h = req.headers.authorization;
+    const m = typeof h === "string" ? /^Bearer\s+(\S+)\s*$/i.exec(h) : null;
+    return m?.[1] ?? "";
+}
+/**
+ * Registers `GET /device/connect` (the gateway role only) in its own encapsulated scope with
+ * `@fastify/websocket`: a raw Fastify route outside Nest, so neither the API's `AuthGuard` nor its
+ * CSRF check applies; the route checks the machine credential itself, before the upgrade (401
+ * `device.credential_invalid`), then the protocol header (426 `environment.program_outdated`).
+ * Must be called before Nest `app.init()`, on the root instance.
+ *
+ * `@fastify/websocket` sends every upgrade request of the server through the Fastify router; the
+ * root hooks below keep that from reaching any other route: a WebSocket upgrade to another path
+ * is answered 404 and its socket closed once answered (Node would have dropped it without a
+ * listener). Other upgrades (`h2c`) reach their route as ordinary requests; their socket, which
+ * no HTTP connection owns any more, is closed once answered as well (the upgrade is declined).
+ */
+export async function registerDeviceConnectRoute(fastify, opts) {
+    fastify.addHook("onRequest", async (req, reply) => {
+        if (!isWebSocketUpgrade(req) || req.routeOptions.url === DEVICE_CONNECT_ROUTE)
+            return;
+        return reply
+            .code(404)
+            .send(errorBody("not_found", "This path does not accept a protocol upgrade"));
+    });
+    fastify.addHook("onResponse", async (req) => {
+        if (viaUpgrade(req))
+            req.raw.socket?.destroy();
+    });
+    await fastify.register(async (scope) => {
+        await scope.register(websocket, { options: { maxPayload: opts.maxFrameBytes } });
+        const identities = new WeakMap();
+        scope.get(DEVICE_CONNECT_ROUTE, {
+            websocket: true,
+            preValidation: async (req, reply) => {
+                const cred = bearer(req);
+                const identity = cred === "" ? null : await opts.gateway.authenticate(cred);
+                if (identity === null) {
+                    return reply
+                        .code(401)
+                        .send(errorBody("device.credential_invalid", "The machine credential is unknown or revoked. Run capybara-device logout, then capybara-device login."));
+                }
+                if (req.headers[DEVICE_PROTOCOL_HEADER] !== String(DEVICE_PROTOCOL_VERSION)) {
+                    return reply
+                        .code(426)
+                        .send(errorBody("environment.program_outdated", `This kernel speaks device protocol ${DEVICE_PROTOCOL_VERSION}. ` +
+                        "Update capybara-device."));
+                }
+                identities.set(req, { identity, cred });
+            },
+        }, (socket, req) => {
+            const found = identities.get(req);
+            if (!found) {
+                socket.close(4400, "not authenticated");
+                return;
+            }
+            opts.gateway.accept(socket, found.identity, found.cred);
+        });
+    });
+}

package/dist/devices/devices.module.d.ts

@@ -0,0 +1,16 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { DeviceSandboxProvider } from "./device-provider.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@device` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a connected environment
+ * (the socket itself is held by the gateway role).
+ */
+export declare class DevicesModule implements OnModuleInit {
+    private readonly providers;
+    private readonly device;
+    constructor(providers: SandboxProviders, device: DeviceSandboxProvider);
+    onModuleInit(): void;
+}

package/dist/devices/devices.module.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Module } from "@nestjs/common";
+import { DEVICE_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { DeviceSandboxProvider } from "./device-provider.js";
+import { MachinesService } from "./machines.js";
+import { DeviceRelay } from "./relay.js";
+import { DeviceTargets } from "./targets.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@device` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a connected environment
+ * (the socket itself is held by the gateway role).
+ */
+let DevicesModule = class DevicesModule {
+    providers;
+    device;
+    constructor(providers, device) {
+        this.providers = providers;
+        this.device = device;
+    }
+    onModuleInit() {
+        this.providers.register({ plugin: DEVICE_PROVIDER, impl: this.device });
+    }
+};
+DevicesModule = __decorate([
+    Module({
+        imports: [SandboxModule],
+        providers: [DeviceTargets, DeviceRelay, DeviceSandboxProvider, MachinesService],
+        exports: [DeviceRelay, DeviceSandboxProvider, MachinesService],
+    }),
+    __param(0, Inject(SandboxProviders)),
+    __param(1, Inject(DeviceSandboxProvider))
+], DevicesModule);
+export { DevicesModule };

package/dist/devices/dto.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/** `POST /api/v1/device/authorize`: the machine as the program describes it. */
+export declare const DeviceAuthorizeBody: z.ZodObject<{
+    name: z.ZodString;
+    os: z.ZodEnum<{
+        darwin: "darwin";
+        linux: "linux";
+    }>;
+    arch: z.ZodString;
+    programVersion: z.ZodString;
+}, z.core.$strict>;
+/** `POST /api/v1/device/token`: the secret device code from `authorize`. */
+export declare const DeviceTokenBody: z.ZodObject<{
+    deviceCode: z.ZodString;
+}, z.core.$strict>;
+export declare const DeviceUserCodeParams: z.ZodObject<{
+    userCode: z.ZodString;
+}, z.core.$strip>;
+export declare const DeviceUserCodeBody: z.ZodObject<{
+    userCode: z.ZodString;
+}, z.core.$strict>;
+/**
+ * `POST /api/v1/device/confirm`: the org and exactly one of an existing device environment of the
+ * person's (`environmentId`) or the name of a new one (`name`).
+ */
+export declare const DeviceConfirmBody: z.ZodObject<{
+    userCode: z.ZodString;
+    orgId: z.ZodString;
+    environmentId: z.ZodOptional<z.ZodUUID>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const DeviceAuthorizeBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    name: z.ZodString;
+    os: z.ZodEnum<{
+        darwin: "darwin";
+        linux: "linux";
+    }>;
+    arch: z.ZodString;
+    programVersion: z.ZodString;
+}, z.core.$strict>>;
+export declare class DeviceAuthorizeBodyDto extends DeviceAuthorizeBodyDto_base {
+}
+declare const DeviceTokenBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    deviceCode: z.ZodString;
+}, z.core.$strict>>;
+export declare class DeviceTokenBodyDto extends DeviceTokenBodyDto_base {
+}
+declare const DeviceUserCodeParamsDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    userCode: z.ZodString;
+}, z.core.$strip>>;
+export declare class DeviceUserCodeParamsDto extends DeviceUserCodeParamsDto_base {
+}
+declare const DeviceUserCodeBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    userCode: z.ZodString;
+}, z.core.$strict>>;
+export declare class DeviceUserCodeBodyDto extends DeviceUserCodeBodyDto_base {
+}
+declare const DeviceConfirmBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    userCode: z.ZodString;
+    orgId: z.ZodString;
+    environmentId: z.ZodOptional<z.ZodUUID>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare class DeviceConfirmBodyDto extends DeviceConfirmBodyDto_base {
+}
+export {};

package/dist/devices/dto.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { EnvironmentName } from "../environments/dto.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+/** `POST /api/v1/device/authorize`: the machine as the program describes it. */
+export const DeviceAuthorizeBody = z
+    .object({
+    name: z.string().trim().min(1).max(64),
+    os: z.enum(["darwin", "linux"]),
+    arch: z.string().trim().min(1).max(32),
+    programVersion: z.string().trim().min(1).max(64),
+})
+    .strict();
+/** `POST /api/v1/device/token`: the secret device code from `authorize`. */
+export const DeviceTokenBody = z.object({ deviceCode: z.string().min(1).max(200) }).strict();
+/** A user code as typed (`XXXX-XXXX`; case, spaces and the dash are forgiven). */
+const UserCode = z.string().min(1).max(32);
+export const DeviceUserCodeParams = z.object({ userCode: UserCode });
+export const DeviceUserCodeBody = z.object({ userCode: UserCode }).strict();
+/**
+ * `POST /api/v1/device/confirm`: the org and exactly one of an existing device environment of the
+ * person's (`environmentId`) or the name of a new one (`name`).
+ */
+export const DeviceConfirmBody = z
+    .object({
+    userCode: UserCode,
+    orgId: z.string().min(1).max(100),
+    environmentId: z.uuid().optional(),
+    name: EnvironmentName.optional(),
+})
+    .strict()
+    .refine((b) => (b.environmentId === undefined) !== (b.name === undefined), {
+    message: "Give exactly one of environmentId and name",
+    path: ["environmentId"],
+});
+export class DeviceAuthorizeBodyDto extends createZodDto(DeviceAuthorizeBody, "DeviceAuthorizeBody") {
+}
+export class DeviceTokenBodyDto extends createZodDto(DeviceTokenBody, "DeviceTokenBody") {
+}
+export class DeviceUserCodeParamsDto extends createZodDto(DeviceUserCodeParams, "DeviceUserCodeParams") {
+}
+export class DeviceUserCodeBodyDto extends createZodDto(DeviceUserCodeBody, "DeviceUserCodeBody") {
+}
+export class DeviceConfirmBodyDto extends createZodDto(DeviceConfirmBody, "DeviceConfirmBody") {
+}

package/dist/devices/keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Redis keys and bus topics of the connected-machine relay (environments spec §6, §13). Every key
+ * is per environment (or per request); writers set a TTL on each.
+ */
+/** The lease of the replica holding the machine's connection: `capk:device-lease:<environmentId>`. */
+export declare const deviceLeaseKey: (environmentId: string) => string;
+/** The list of requests waiting for the machine: `capk:device-req:<environmentId>`. */
+export declare const deviceReqKey: (environmentId: string) => string;
+/** The result of one request: `capk:device-res:<requestId>`. */
+export declare const deviceResKey: (requestId: string) => string;
+/** The prefix of {@link deviceTakenKey} (the holder's Lua script builds the key from it). */
+export declare const DEVICE_TAKEN_PREFIX = "capk:device-taken:";
+/**
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the environment
+ * id. Only a result for a taken request of the socket's own environment is accepted.
+ */
+export declare const deviceTakenKey: (requestId: string) => string;
+/** A new request for the machine of the environment. */
+export declare const deviceReqTopic: (environmentId: string) => string;
+/** The result of one request is ready. */
+export declare const deviceResTopic: (requestId: string) => string;
+/** Another replica took the machine's connection over. */
+export declare const deviceTakeoverTopic: (environmentId: string) => string;
+/** The machine's credential was revoked: its connection is closed. */
+export declare const deviceRevokedTopic: (environmentId: string) => string;

package/dist/devices/keys.js

@@ -0,0 +1,25 @@
+/**
+ * Redis keys and bus topics of the connected-machine relay (environments spec §6, §13). Every key
+ * is per environment (or per request); writers set a TTL on each.
+ */
+/** The lease of the replica holding the machine's connection: `capk:device-lease:<environmentId>`. */
+export const deviceLeaseKey = (environmentId) => `capk:device-lease:${environmentId}`;
+/** The list of requests waiting for the machine: `capk:device-req:<environmentId>`. */
+export const deviceReqKey = (environmentId) => `capk:device-req:${environmentId}`;
+/** The result of one request: `capk:device-res:<requestId>`. */
+export const deviceResKey = (requestId) => `capk:device-res:${requestId}`;
+/** The prefix of {@link deviceTakenKey} (the holder's Lua script builds the key from it). */
+export const DEVICE_TAKEN_PREFIX = "capk:device-taken:";
+/**
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the environment
+ * id. Only a result for a taken request of the socket's own environment is accepted.
+ */
+export const deviceTakenKey = (requestId) => `${DEVICE_TAKEN_PREFIX}${requestId}`;
+/** A new request for the machine of the environment. */
+export const deviceReqTopic = (environmentId) => `device.req.${environmentId}`;
+/** The result of one request is ready. */
+export const deviceResTopic = (requestId) => `device.res.${requestId}`;
+/** Another replica took the machine's connection over. */
+export const deviceTakeoverTopic = (environmentId) => `device.takeover.${environmentId}`;
+/** The machine's credential was revoked: its connection is closed. */
+export const deviceRevokedTopic = (environmentId) => `device.revoked.${environmentId}`;

package/dist/devices/machines.d.ts

@@ -0,0 +1,118 @@
+import type { DeviceHello, DeviceStopArgs, ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { DeviceRelay } from "./relay.js";
+/** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
+export declare const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
+/** What a machine credential stands for. */
+export interface MachineIdentity {
+    machineId: string;
+    orgId: string;
+    environmentId: string;
+    accountId: string;
+}
+/** The machine connected to an environment (its unrevoked row). */
+export interface ActiveMachine {
+    id: string;
+    orgId: string;
+    accountId: string;
+    name: string;
+    os: string;
+    arch: string;
+    programVersion: string | null;
+    lastSeenAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Connected machines and their credentials (environments spec §13.2). One active machine per
+ * device environment: issuing a credential revokes the environment's previous machine. A
+ * credential is `cap_dev_` plus 32 random bytes; only its sha256 is stored. It is accepted only
+ * by the device connection route ({@link authenticate}), never by `/api`: it is no `Principal`.
+ *
+ * A revoked machine is told so after the commit: `stop { reason }` relayed while a replica holds
+ * its connection (fire-and-forget, ruling R14) and `device.revoked.<environmentId>` published with
+ * `{ machineId }`, so the holder closes that machine's connection.
+ */
+export declare class MachinesService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly relay;
+    private readonly bus;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<DeviceRelay, "holderLive" | "send">, bus: ExtensionContext["bus"], log: Pick<KernelLogger, "warn">);
+    /**
+     * A new machine for the environment and its credential (returned once). Revokes the
+     * environment's active machine first. Joins the caller's transaction (the device confirmation),
+     * which has already checked the environment is the person's own live device environment.
+     */
+    issue(input: {
+        orgId: string;
+        environmentId: string;
+        accountId: string;
+        name: string;
+        os: string;
+        arch: string;
+        programVersion: string;
+    }): Promise<{
+        machineId: string;
+        credential: string;
+    }>;
+    /**
+     * Ruling R23: the new machine may serve the environment from another directory or mode (other
+     * roots), and a login recreates a directory that was lost (ruling R24). So the instance row
+     * forgets its instance (status `none`, no handle) and its files count as there again; the next
+     * use creates a fresh instance on the machine (with its roots: a new `environment_paths` event
+     * follows). The fence moves on, so a lifecycle holder of the old instance fails its next write.
+     * The reset count (`fs_resets`) moves on when the files the next instance sees are not the old
+     * ones, so conversations that used the old files are told their files were reset, not that they
+     * were kept: lost files come back as an empty directory, and another machine (`moved`: name, OS
+     * or arch differ from the environment's previous machine) has other files. Another directory on
+     * the same machine is known only from the new machine's first hello ({@link recordHello}).
+     */
+    private resetInstance;
+    /**
+     * Who a machine credential stands for, or null: the machine is not revoked, its environment is
+     * live, the org is not deleted (ruling R12), and the person is an active account still a member
+     * of the org. Read live on every call (a connection re-checks it as it sees fit).
+     */
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    /**
+     * Stores what the program reported in its hello frame and marks the machine seen. On the
+     * machine's first hello, when it is the same machine as the environment's previous one (else
+     * {@link issue} already counted the reset) but serves another directory or mode (other roots,
+     * ruling R23), the environment's files are other files: `fs_resets` moves on (maintainer
+     * decision 2026-11-08), so conversations get the files-reset notice. A previous machine that
+     * never said hello has no known roots: nothing to compare.
+     */
+    recordHello(machineId: string, hello: DeviceHello): Promise<void>;
+    /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
+    touch(machineId: string): Promise<void>;
+    /**
+     * Disconnects the machine of one of the person's own live device environments (`DELETE
+     * /orgs/:orgId/environments/:id/machine`): revokes it and audits
+     * `environment.machine_revoked`. Anyone else's environment, a cloud one or a missing one →
+     * `environment.not_found`; no machine connected is a no-op.
+     */
+    revoke(orgId: string, accountId: string, environmentId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * Revokes the environment's active machine, if any, in the caller's transaction, and after the
+     * commit tells it to stop for `reason` (none: only its connection is closed) and closes its
+     * connection. Returns the revoked machine's id. Used by {@link issue} (replaced: no stop),
+     * {@link revoke} and the environment's deletion (`deleted`).
+     */
+    revokeActive(environmentId: string, reason: DeviceStopArgs["reason"] | null): Promise<string | null>;
+    /**
+     * Revokes one machine by id (a sign-in whose credential never reached the program), with the
+     * same post-commit disconnect as a replacement (no stop frame). True when it was active.
+     */
+    revokeMachine(machineId: string): Promise<boolean>;
+    /** The environment's active machine, or null. */
+    activeFor(environmentId: string): Promise<ActiveMachine | null>;
+    /**
+     * After a revocation commits: `stop` is queued only while a replica holds the connection (an
+     * offline machine must not find it on the list later), then the revocation is published.
+     * Failures are logged; the revocation itself stands.
+     */
+    private disconnect;
+}