@capybara-hq/kernel 0.1.0-rc.11 → 0.1.0-rc.13

package/dist/{devices → local-devices}/device-auth.js

@@ -9,7 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { randomBytes } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
-import { EnvironmentsService } from "../environments/environments.service.js";
+import { DevicesService } from "../devices/devices.service.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { sha256Hex } from "../identity/hash.js";
@@ -19,8 +19,8 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { authorizeOrgAction } from "../orgs/org.guard.js";
-import { DEVICE_PROVIDER } from "../sandbox/providers.js";
-import { environmentNotFound } from "../sandbox/sandbox.service.js";
+import { LOCAL_PROVIDER } from "../sandbox/providers.js";
+import { deviceNotFound } from "../sandbox/sandbox.service.js";
 import { MachinesService } from "./machines.js";
 /** The 20 consonants a user code is made of (no vowels: no words; no look-alike letters). */
 export const USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
@@ -31,8 +31,8 @@ const DEVICE_CODE_RE = /^cap_dvc_[A-Za-z0-9_-]{43}$/;
 export const SLOW_DOWN_STEP_SECONDS = 5;
 /** Polls this much earlier than the interval are still on time (network jitter). */
 const POLL_JITTER_MS = 500;
-/** The web page that confirms a code: `<http.publicUrl>/device`. */
-export const DEVICE_PAGE_PATH = "/device";
+/** The web page that confirms a code: `<http.publicUrl>/devices/link`. */
+export const DEVICE_PAGE_PATH = "/devices/link";
 /** The machine's WebSocket route: `ws(s)://<http.publicUrl host>/device/connect`. */
 export const DEVICE_CONNECT_PATH = "/device/connect";
 /** The sign-in state of one device code: `capk:device-auth:<sha256(deviceCode)>` (a hash). */
@@ -78,7 +78,7 @@ redis.call('HSET', KEYS[1], 'status', ARGV[2])
 if ARGV[3] then redis.call('HSET', KEYS[1], ARGV[3], ARGV[4]) end
 return 1
 `;
-const codeInvalid = () => new ApiError("device.code_invalid", "This code is unknown or has expired; check the code shown by capybara-device, or run capybara-device login again");
+const codeInvalid = () => new ApiError("device_sign_in.code_invalid", "This code is unknown or has expired; check the code shown by capybara-device, or run capybara-device login again");
 /** A user code as typed → `XXXX-XXXX`, or null when it cannot be one. */
 export function normalizeUserCode(input) {
     const s = input.toUpperCase().replace(/[\s-]/g, "");
@@ -107,7 +107,7 @@ function newUserCode() {
  * for a code pair (`authorize`), the signed-in person confirms the user code on the web page
  * `/device` (`pending`, `confirm` or `deny`), and the program polls `token` until it gets the
  * machine credential, once. State lives only in Redis, both keys with the code's TTL
- * (`environments.device.authCodeTtlSeconds`): `capk:device-auth:<sha256(deviceCode)>` (a hash:
+ * (`devices.local.authCodeTtlSeconds`): `capk:device-auth:<sha256(deviceCode)>` (a hash:
  * `info` JSON, `status`, `interval`, `lastPollAt`, the parked `grant`) and
  * `capk:device-user:<userCode>` → the device code's hash. The device code itself is never stored.
  */
@@ -116,22 +116,22 @@ let DeviceAuthService = class DeviceAuthService {
     txHost;
     redis;
     config;
-    environments;
+    devices;
     machines;
     log;
-    constructor(db, txHost, redis, config, environments, machines, log) {
+    constructor(db, txHost, redis, config, devices, machines, log) {
         this.db = db;
         this.txHost = txHost;
         this.redis = redis;
         this.config = config;
-        this.environments = environments;
+        this.devices = devices;
         this.machines = machines;
         this.log = log;
     }
     /** A new code pair for a machine. Needs `http.publicUrl` (the page and the connection URL). */
     async authorize(machine) {
         const web = this.publicUrl();
-        const { authCodeTtlSeconds: ttl, pollIntervalSeconds: interval } = this.config.get().environments.device;
+        const { authCodeTtlSeconds: ttl, pollIntervalSeconds: interval } = this.config.get().devices.local;
         const deviceCode = DEVICE_CODE_PREFIX + randomBytes(32).toString("base64url");
         const hash = sha256Hex(deviceCode);
         for (let attempt = 0;; attempt++) {
@@ -169,8 +169,8 @@ let DeviceAuthService = class DeviceAuthService {
     }
     /**
      * The program's poll: the grant once the person confirmed (the code is consumed), else
-     * `device.authorization_pending`, `device.slow_down` (details `[{ interval }]`, the grown
-     * interval), `device.denied` or `device.expired` (also for an unknown code).
+     * `device_sign_in.authorization_pending`, `device_sign_in.slow_down` (details `[{ interval }]`, the grown
+     * interval), `device_sign_in.denied` or `device_sign_in.expired` (also for an unknown code).
      */
     async token(deviceCode) {
         const connectUrl = this.connectUrl();
@@ -180,21 +180,21 @@ let DeviceAuthService = class DeviceAuthService {
         switch (r[0]) {
             case "approved": {
                 const grant = JSON.parse(r[1]);
-                const device = this.config.get().environments.device;
+                const local = this.config.get().devices.local;
                 return {
                     ...grant,
                     connectUrl,
-                    reconnectGraceSeconds: device.reconnectGraceSeconds,
-                    maxFrameBytes: device.maxFrameBytes,
+                    reconnectGraceSeconds: local.reconnectGraceSeconds,
+                    maxFrameBytes: local.maxFrameBytes,
                 };
             }
             case "slow_down":
-                throw new ApiError("device.slow_down", `Polling too fast; wait ${r[1]} seconds between polls`, [{ interval: Number(r[1]) }]);
+                throw new ApiError("device_sign_in.slow_down", `Polling too fast; wait ${r[1]} seconds between polls`, [{ interval: Number(r[1]) }]);
             case "denied":
-                throw new ApiError("device.denied", "The sign-in was denied in the browser");
+                throw new ApiError("device_sign_in.denied", "The sign-in was denied in the browser");
             case "pending":
             case "claimed":
-                throw new ApiError("device.authorization_pending", "Waiting for the code to be confirmed in the browser");
+                throw new ApiError("device_sign_in.authorization_pending", "Waiting for the code to be confirmed in the browser");
             default:
                 throw expired();
         }
@@ -206,10 +206,10 @@ let DeviceAuthService = class DeviceAuthService {
     }
     /**
      * The person confirms a user code: in an org where they may use agents (`agents.use`), into
-     * one of their own live device environments or a new one named `name` (` 2`, ` 3`, … appended
-     * while the name is taken). One transaction creates the environment if needed, issues the
-     * machine (revoking the environment's previous one) and audits
-     * `environment.machine_connected` (retried once when a concurrent confirmation took the new
+     * one of their own live local devices or a new one named `name` (` 2`, ` 3`, … appended
+     * while the name is taken). One transaction creates the device if needed, issues the
+     * machine (revoking the device's previous one) and audits
+     * `device.machine_connected` (retried once when a concurrent confirmation took the new
      * name); after the commit the credential is parked for the poll ({@link park}). The code is
      * claimed first, so two confirmations of one code cannot both issue a machine; a confirmation
      * that fails before the commit leaves it pending.
@@ -223,9 +223,7 @@ let DeviceAuthService = class DeviceAuthService {
         try {
             issued = await this.confirmIn(principal.account.id, input, info).catch((e) => {
                 // a concurrent confirmation took the same new name between our read and our insert
-                if (input.name !== undefined &&
-                    e instanceof ApiError &&
-                    e.code === "environment.name_taken") {
+                if (input.name !== undefined && e instanceof ApiError && e.code === "device.name_taken") {
                     return this.confirmIn(principal.account.id, input, info);
                 }
                 throw e;
@@ -236,12 +234,12 @@ let DeviceAuthService = class DeviceAuthService {
             throw e;
         }
         await this.park(hash, info, issued);
-        return { environmentId: issued.environmentId };
+        return { deviceId: issued.deviceId };
     }
     /**
      * Parks the committed machine's credential for the poll. When that fails (the code expired
      * meanwhile, or Redis failed) the machine is revoked again, so no credential nobody holds stays
-     * valid, and the person is told to start over: `device.expired` / `device.unavailable`.
+     * valid, and the person is told to start over: `device_sign_in.expired` / `device_sign_in.unavailable`.
      */
     async park(hash, info, issued) {
         let parked;
@@ -260,16 +258,16 @@ let DeviceAuthService = class DeviceAuthService {
             return;
         }
         this.log.warn("device credential could not be parked; the machine is revoked", {
-            environmentId: issued.environmentId,
+            deviceId: issued.deviceId,
             machineId: issued.machineId,
             err: failure,
         });
         await this.abandon(issued);
-        // the program's next poll then ends with device.expired instead of waiting out the TTL
+        // the program's next poll then ends with device_sign_in.expired instead of waiting out the TTL
         await this.redis.del(authKeyOf(hash), deviceUserKey(info.userCode)).catch(() => undefined);
         if (failure === undefined)
             throw expired();
-        throw new ApiError("device.unavailable", "The machine could not be connected; run capybara-device login again");
+        throw new ApiError("device_sign_in.unavailable", "The machine could not be connected; run capybara-device login again");
     }
     /** Revokes a machine whose credential never reached the program (see {@link park}). */
     async abandon(issued) {
@@ -279,12 +277,12 @@ let DeviceAuthService = class DeviceAuthService {
         await audit(this.db.db, {
             actorAccountId: issued.accountId,
             orgId: grant.orgId,
-            action: "environment.machine_revoked",
-            target: grant.environmentId,
+            action: "device.machine_revoked",
+            target: grant.deviceId,
             detail: { machineId, reason: "sign_in_incomplete" },
         });
     }
-    /** The person refuses a user code: the program's next poll gets `device.denied`. */
+    /** The person refuses a user code: the program's next poll gets `device_sign_in.denied`. */
     async deny(userCode) {
         const { info, hash } = await this.lookup(userCode, "pending");
         if (!(await this.transition(hash, "pending", "denied")))
@@ -293,53 +291,53 @@ let DeviceAuthService = class DeviceAuthService {
     }
     async confirmIn(accountId, input, info) {
         const { orgId } = input;
-        let environmentId;
+        let deviceId;
         if (input.name !== undefined) {
             const name = await this.freeName(orgId, accountId, input.name);
-            environmentId = (await this.environments.createDevice(orgId, accountId, name)).id;
+            deviceId = (await this.devices.createLocal(orgId, accountId, name)).id;
         }
         else {
             const env = await this.db
-                .selectFrom("environments")
+                .selectFrom("devices")
                 .select("id")
-                .where("id", "=", input.environmentId)
+                .where("id", "=", input.deviceId)
                 .where("org_id", "=", orgId)
                 .where("owner_kind", "=", "personal")
                 .where("owner_account_id", "=", accountId)
-                .where("source", "=", "device")
-                .where("provider", "=", DEVICE_PROVIDER)
+                .where("source", "=", "local")
+                .where("provider", "=", LOCAL_PROVIDER)
                 .where("deleted_at", "is", null)
                 .forNoKeyUpdate()
                 .executeTakeFirst();
             if (!env)
-                throw environmentNotFound();
-            environmentId = env.id;
+                throw deviceNotFound();
+            deviceId = env.id;
         }
         const { machine } = info;
         const { machineId, credential } = await this.machines.issue({
             orgId,
-            environmentId,
+            deviceId,
             accountId,
             ...machine,
         });
         await audit(this.db.db, {
             actorAccountId: accountId,
             orgId,
-            action: "environment.machine_connected",
-            target: environmentId,
+            action: "device.machine_connected",
+            target: deviceId,
             detail: { machineId, ...machine },
         });
         return {
-            environmentId,
+            deviceId,
             machineId,
             accountId,
-            grant: { credential, orgId, environmentId },
+            grant: { credential, orgId, deviceId },
         };
     }
     /** `name`, or `name 2`, `name 3`, … : the first that is none of the person's live names. */
     async freeName(orgId, accountId, name) {
         const taken = new Set((await this.db
-            .selectFrom("environments")
+            .selectFrom("devices")
             .select("name")
             .where("org_id", "=", orgId)
             .where("owner_account_id", "=", accountId)
@@ -353,7 +351,7 @@ let DeviceAuthService = class DeviceAuthService {
         }
         return candidate;
     }
-    /** The code behind a user code with status `status`, else `device.code_invalid`. */
+    /** The code behind a user code with status `status`, else `device_sign_in.code_invalid`. */
     async lookup(userCode, status) {
         const code = normalizeUserCode(userCode);
         if (code === null)
@@ -370,11 +368,11 @@ let DeviceAuthService = class DeviceAuthService {
         const args = grant === undefined ? [from, to] : [from, to, "grant", grant];
         return (await this.redis.eval(TRANSITION, 1, authKeyOf(hash), ...args)) === 1;
     }
-    /** `http.publicUrl` without trailing slashes; unset → `environment.unavailable`. */
+    /** `http.publicUrl` without trailing slashes; unset → `device.unavailable`. */
     publicUrl() {
         const url = this.config.get().http.publicUrl;
         if (!url) {
-            throw new ApiError("environment.unavailable", "Connecting machines needs http.publicUrl to be configured; ask the super admin");
+            throw new ApiError("device.unavailable", "Connecting machines needs http.publicUrl to be configured; ask the super admin");
         }
         return url.replace(/\/+$/, "");
     }
@@ -395,9 +393,9 @@ DeviceAuthService = __decorate([
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(REDIS)),
     __param(3, Inject(KernelConfigService)),
-    __param(4, Inject(EnvironmentsService)),
+    __param(4, Inject(DevicesService)),
     __param(5, Inject(MachinesService)),
     __param(6, Inject(KERNEL_LOGGER))
 ], DeviceAuthService);
 export { DeviceAuthService };
-const expired = () => new ApiError("device.expired", "This sign-in code has expired or was already used; run capybara-device login again");
+const expired = () => new ApiError("device_sign_in.expired", "This sign-in code has expired or was already used; run capybara-device login again");

package/dist/local-devices/device-auth.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Device sign-in (environments spec §13.3): {@link DeviceAuthService} behind
+ * `DeviceAuthController`. Kept apart from {@link LocalDevicesModule}, which `DevicesModule`
+ * imports (deleting a device revokes its machine), while sign-in needs both.
+ */
+export declare class DeviceAuthModule {
+}

package/dist/{devices → local-devices}/device-auth.module.js

@@ -5,19 +5,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
-import { EnvironmentsModule } from "../environments/environments.module.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { DeviceAuthService } from "./device-auth.js";
-import { DevicesModule } from "./devices.module.js";
+import { LocalDevicesModule } from "./local-devices.module.js";
 /**
  * Device sign-in (environments spec §13.3): {@link DeviceAuthService} behind
- * `DeviceAuthController`. Kept apart from {@link DevicesModule}, which `EnvironmentsModule`
- * imports (deleting an environment revokes its machine), while sign-in needs both.
+ * `DeviceAuthController`. Kept apart from {@link LocalDevicesModule}, which `DevicesModule`
+ * imports (deleting a device revokes its machine), while sign-in needs both.
  */
 let DeviceAuthModule = class DeviceAuthModule {
 };
 DeviceAuthModule = __decorate([
     Module({
-        imports: [DevicesModule, EnvironmentsModule],
+        imports: [LocalDevicesModule, DevicesModule],
         providers: [DeviceAuthService],
         exports: [DeviceAuthService],
     })

package/dist/{devices → local-devices}/device-routes.d.ts

@@ -5,14 +5,14 @@ import type { MachineIdentity } from "./machines.js";
 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`). */
+/** What the route needs from the gateway (`LocalDeviceGateway`). */
 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). */
+    /** `devices.local.maxFrameBytes`: a larger incoming frame closes the socket (1009). */
     maxFrameBytes: number;
 }
 /**
@@ -24,7 +24,7 @@ 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`).
+ * `device.credential_invalid`), then the protocol header (426 `device.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

package/dist/{devices → local-devices}/device-routes.js

@@ -36,7 +36,7 @@ function bearer(req) {
  * 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`).
+ * `device.credential_invalid`), then the protocol header (426 `device.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
@@ -73,7 +73,7 @@ export async function registerDeviceConnectRoute(fastify, opts) {
                 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}. ` +
+                        .send(errorBody("device.program_outdated", `This kernel speaks device protocol ${DEVICE_PROTOCOL_VERSION}. ` +
                         "Update capybara-device."));
                 }
                 identities.set(req, { identity, cred });

package/dist/local-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 local device of the
+ * person's (`deviceId`) or the name of a new one (`name`).
+ */
+export declare const DeviceConfirmBody: z.ZodObject<{
+    userCode: z.ZodString;
+    orgId: z.ZodString;
+    deviceId: 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;
+    deviceId: z.ZodOptional<z.ZodUUID>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare class DeviceConfirmBodyDto extends DeviceConfirmBodyDto_base {
+}
+export {};

package/dist/local-devices/dto.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { DeviceName } from "../devices/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 local device of the
+ * person's (`deviceId`) or the name of a new one (`name`).
+ */
+export const DeviceConfirmBody = z
+    .object({
+    userCode: UserCode,
+    orgId: z.string().min(1).max(100),
+    deviceId: z.uuid().optional(),
+    name: DeviceName.optional(),
+})
+    .strict()
+    .refine((b) => (b.deviceId === undefined) !== (b.name === undefined), {
+    message: "Give exactly one of deviceId and name",
+    path: ["deviceId"],
+});
+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 → local-devices}/keys.d.ts

@@ -1,25 +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.
+ * is per device (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 lease of the replica holding the machine's connection: `capk:device-lease:<deviceId>`. */
+export declare const deviceLeaseKey: (deviceId: string) => string;
+/** The list of requests waiting for the machine: `capk:device-req:<deviceId>`. */
+export declare const deviceReqKey: (deviceId: 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.
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the device
+ * id. Only a result for a taken request of the socket's own device 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;
+/** A new request for the machine of the device. */
+export declare const deviceReqTopic: (deviceId: 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;
+export declare const deviceTakeoverTopic: (deviceId: string) => string;
 /** The machine's credential was revoked: its connection is closed. */
-export declare const deviceRevokedTopic: (environmentId: string) => string;
+export declare const deviceRevokedTopic: (deviceId: string) => string;

package/dist/{devices → local-devices}/keys.js

@@ -1,25 +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.
+ * is per device (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 lease of the replica holding the machine's connection: `capk:device-lease:<deviceId>`. */
+export const deviceLeaseKey = (deviceId) => `capk:device-lease:${deviceId}`;
+/** The list of requests waiting for the machine: `capk:device-req:<deviceId>`. */
+export const deviceReqKey = (deviceId) => `capk:device-req:${deviceId}`;
 /** 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.
+ * A request the holder forwarded to a machine: `capk:device-taken:<requestId>` → the device
+ * id. Only a result for a taken request of the socket's own device 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}`;
+/** A new request for the machine of the device. */
+export const deviceReqTopic = (deviceId) => `device.req.${deviceId}`;
 /** 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}`;
+export const deviceTakeoverTopic = (deviceId) => `device.takeover.${deviceId}`;
 /** The machine's credential was revoked: its connection is closed. */
-export const deviceRevokedTopic = (environmentId) => `device.revoked.${environmentId}`;
+export const deviceRevokedTopic = (deviceId) => `device.revoked.${deviceId}`;

package/dist/{devices/device-gateway.d.ts → local-devices/local-device-gateway.d.ts}

@@ -9,13 +9,13 @@ import { type MachineIdentity, MachinesService } from "./machines.js";
 export declare const DEVICE_CLOSE: {
     /** The kernel is shutting down: reconnect (another gateway replica takes over). */
     readonly shutdown: 1001;
-    /** A frame larger than `environments.device.maxFrameBytes` (sent by `ws` itself). */
+    /** A frame larger than `devices.local.maxFrameBytes` (sent by `ws` itself). */
     readonly tooBig: 1009;
     /** The kernel failed (e.g. the database): reconnect. */
     readonly internal: 1011;
     /** The lease was lost (renewal kept failing or the key was taken): reconnect. */
     readonly leaseLost: 4001;
-    /** A newer connection of the environment took over: the program exits. */
+    /** A newer connection of the device took over: the program exits. */
     readonly replaced: 4002;
     /** The machine's credential was revoked: the program exits. */
     readonly revoked: 4003;
@@ -55,17 +55,17 @@ declare class DeviceConnection {
     private chain;
     /** Resolves once the lease is handed back (or was never held). */
     private released;
-    constructor(gw: DeviceGateway, socket: WebSocket, identity: MachineIdentity, credential: string);
-    get environmentId(): string;
+    constructor(gw: LocalDeviceGateway, socket: WebSocket, identity: MachineIdentity, credential: string);
+    get deviceId(): string;
     start(): void;
     private onFrame;
     /**
      * Stores one result and announces it (the relay's wire, relay.ts), only for a request taken for
-     * this environment (ruling R20); anything else is dropped.
+     * this device (ruling R20); anything else is dropped.
      */
     private store;
     /**
-     * Claims the environment's lease; true when this connection holds it. The newest connection
+     * Claims the device's lease; true when this connection holds it. The newest connection
      * wins (ruling R21): when another connection holds the lease, a takeover is published (the
      * holder yields to any takeover) and the lease retried every {@link CLAIM_RETRY_MS} for
      * {@link CLAIM_TIMEOUT_MS}, then 4409 (the program reconnects). A claimer never yields.
@@ -79,7 +79,7 @@ declare class DeviceConnection {
     /** The next ping (a chain of timeouts; the lease renewal is LockService's, not this timer's). */
     private schedulePing;
     private ping;
-    /** The credential still stands (membership, org and environment are read live). */
+    /** The credential still stands (membership, org and device are read live). */
     private reauthenticate;
     private traffic;
     /** Closes the socket with `code` and hands the lease back; idempotent. */
@@ -90,17 +90,17 @@ declare class DeviceConnection {
 /**
  * The gateway role's half of the device relay (environments spec §13.4): holds the WebSocket
  * connections of connected machines (`GET /device/connect`, device-routes.ts). One connection per
- * environment across replicas, under the lease `capk:device-lease:<environmentId>` (the newest
- * connection wins: it publishes `device.takeover.<environmentId>` and the holder lets go). The
- * holder drains `capk:device-req:<environmentId>` on every `device.req.<environmentId>` nudge,
- * once after claiming and on every ping, marking each forwarded request taken for its environment
+ * device across replicas, under the lease `capk:device-lease:<deviceId>` (the newest
+ * connection wins: it publishes `device.takeover.<deviceId>` and the holder lets go). The
+ * holder drains `capk:device-req:<deviceId>` on every `device.req.<deviceId>` nudge,
+ * once after claiming and on every ping, marking each forwarded request taken for its device
  * (`capk:device-taken:<id>`, TTL the reconnect grace plus the request's deadline plus a margin).
- * A `res` is accepted only for a request taken for the socket's environment: it is stored under
+ * A `res` is accepted only for a request taken for the socket's device: it is stored under
  * `capk:device-res:<id>` for the rest of that TTL and published on `device.res.<id>`.
- * `device.revoked.<environmentId>` closes the connection of that machine only (ruling R16). The
+ * `device.revoked.<deviceId>` closes the connection of that machine only (ruling R16). The
  * sockets are this process's own; everything other replicas need is in Redis.
  */
-export declare class DeviceGateway {
+export declare class LocalDeviceGateway {
     readonly machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">;
     readonly locks: Pick<LockService, "hold">;
     readonly bus: ExtensionContext["bus"];