@capybara-hq/kernel 0.1.0-rc.7 → 0.1.0-rc.9

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

@@ -0,0 +1,89 @@
+import type { ExecResult, FileSystemHandle, SandboxHandle, SandboxLimits, SandboxProvider, SandboxRoots } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { DeviceRelay } from "./relay.js";
+import { DeviceTargets } from "./targets.js";
+/** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
+export declare const EXEC_DEADLINE_MARGIN_MS = 5000;
+/** How long the machine may take for one non-exec operation. */
+export declare const OP_DEADLINE_MS = 30000;
+/**
+ * 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 declare const FRAME_ENVELOPE_BYTES: number;
+/** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
+export declare const maxReadBytes: (maxFrameBytes: number) => number;
+/**
+ * The handle of an instance on a machine: the environment id (ruling R1: the relay is keyed by
+ * environment), the roots the machine reported at `create`, and the org's effective limits at
+ * creation (for the record: every `exec` carries the org's limits read at that moment, ruling
+ * R27, so the machine intersects its local policy with the current egress).
+ */
+export interface DeviceSandboxHandle extends SandboxHandle {
+    roots: SandboxRoots;
+    limits: SandboxLimits;
+}
+/** The environment id of a `cap-env-<environmentId>` name; undefined for any other name. */
+export declare const environmentIdOfName: (name: string) => string | undefined;
+/**
+ * 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).
+ */
+export declare class DeviceSandboxProvider implements SandboxProvider {
+    private readonly relay;
+    private readonly targets;
+    private readonly sandbox;
+    private readonly config;
+    readonly concurrentExec: true;
+    readonly sessionIsolation = false;
+    constructor(relay: DeviceRelay, targets: Pick<DeviceTargets, "orgOf" | "machineRoots">, sandbox: Pick<SandboxService, "orgLimits">, config: Pick<KernelConfigService, "get">);
+    createFileSystem(args: {
+        name: string;
+        limits: SandboxLimits;
+        signal: AbortSignal;
+    }): Promise<FileSystemHandle>;
+    /** The files are the machine owner's: nothing to do (ruling R24; never a `stop`). */
+    destroyFileSystem(_fs: FileSystemHandle, signal: AbortSignal): Promise<void>;
+    destroyFileSystemByName(_name: string, signal: AbortSignal): Promise<void>;
+    create(args: {
+        name: string;
+        image?: string;
+        limits: SandboxLimits;
+        fileSystem: FileSystemHandle;
+        signal: AbortSignal;
+    }): Promise<DeviceSandboxHandle>;
+    /**
+     * 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).
+     */
+    resume(h: SandboxHandle, signal: AbortSignal): Promise<"resumed" | "gone">;
+    suspend(_h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    destroy(_h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    destroyByName(_name: string, signal: AbortSignal): Promise<void>;
+    killAll(h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    killTagged(h: SandboxHandle, tags: string[], signal: AbortSignal): Promise<void>;
+    exec(h: SandboxHandle, args: Parameters<SandboxProvider["exec"]>[1]): Promise<ExecResult>;
+    readFile(h: SandboxHandle, path: string, opts: {
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        data: Uint8Array;
+        truncated: boolean;
+    } | null>;
+    writeFile(h: SandboxHandle, path: string, data: Uint8Array, signal: AbortSignal): Promise<void>;
+    stat(h: SandboxHandle, path: string, signal: AbortSignal): Promise<{
+        size: number;
+        isDir: boolean;
+    } | null>;
+    /** The org's effective limits now (ruling R27); a deleted environment is not found. */
+    private currentLimits;
+}

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}`;