@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/local-devices/device-auth.js

@@ -0,0 +1,401 @@
+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 { randomBytes } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { DevicesService } from "../devices/devices.service.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { sha256Hex } from "../identity/hash.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+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 { 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";
+const USER_CODE_LENGTH = 8;
+const DEVICE_CODE_PREFIX = "cap_dvc_";
+const DEVICE_CODE_RE = /^cap_dvc_[A-Za-z0-9_-]{43}$/;
+/** What `slow_down` adds to the poll interval (RFC 8628 §3.5). */
+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>/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). */
+export const deviceAuthKey = (deviceCode) => authKeyOf(sha256Hex(deviceCode));
+const authKeyOf = (deviceCodeHash) => `capk:device-auth:${deviceCodeHash}`;
+/** The user code's pointer to its device code's hash: `capk:device-user:<XXXX-XXXX>`. */
+export const deviceUserKey = (userCode) => `capk:device-user:${userCode}`;
+/**
+ * The poll (`ARGV[1]` now in ms, `ARGV[2]` jitter ms, `ARGV[3]` slow-down step s). Missing →
+ * `expired`. Earlier than the interval → `slow_down` with the grown interval. Approved → the
+ * parked grant, and the code is deleted (get-and-delete: the credential is handed out once).
+ * Otherwise the status (`pending`, `claimed`, `denied`). Every poll records its time.
+ */
+const POLL = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return {'expired'} end
+local now = tonumber(ARGV[1])
+local interval = tonumber(redis.call('HGET', KEYS[1], 'interval'))
+local last = redis.call('HGET', KEYS[1], 'lastPollAt')
+redis.call('HSET', KEYS[1], 'lastPollAt', ARGV[1])
+if last and now - tonumber(last) < interval * 1000 - tonumber(ARGV[2]) then
+  interval = interval + tonumber(ARGV[3])
+  redis.call('HSET', KEYS[1], 'interval', interval)
+  return {'slow_down', tostring(interval)}
+end
+local status = redis.call('HGET', KEYS[1], 'status')
+if status == 'approved' then
+  local grant = redis.call('HGET', KEYS[1], 'grant')
+  redis.call('DEL', KEYS[1])
+  return {'approved', grant}
+end
+return {status}
+`;
+/** Writes the user code's pointer (`ARGV[1]`, TTL `ARGV[2]` s) unless the code is in use. */
+const CREATE_POINTER = `
+if redis.call('EXISTS', KEYS[1]) == 1 then return 0 end
+redis.call('SET', KEYS[1], ARGV[1], 'EX', ARGV[2])
+return 1
+`;
+/** Moves the status from `ARGV[1]` to `ARGV[2]` (setting field `ARGV[3]` to `ARGV[4]` if given). */
+const TRANSITION = `
+if redis.call('HGET', KEYS[1], 'status') ~= ARGV[1] then return 0 end
+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_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, "");
+    if (s.length !== USER_CODE_LENGTH)
+        return null;
+    for (const c of s)
+        if (!USER_CODE_ALPHABET.includes(c))
+            return null;
+    return `${s.slice(0, 4)}-${s.slice(4)}`;
+}
+/** A uniformly random user code (rejection sampling keeps every letter equally likely). */
+function newUserCode() {
+    const n = USER_CODE_ALPHABET.length;
+    const limit = 256 - (256 % n);
+    let out = "";
+    while (out.length < USER_CODE_LENGTH) {
+        for (const b of randomBytes(USER_CODE_LENGTH * 2)) {
+            if (b < limit && out.length < USER_CODE_LENGTH)
+                out += USER_CODE_ALPHABET[b % n];
+        }
+    }
+    return `${out.slice(0, 4)}-${out.slice(4)}`;
+}
+/**
+ * Device authorization (environments spec §6.2, §13.3; the shape of RFC 8628). The program asks
+ * 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
+ * (`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.
+ */
+let DeviceAuthService = class DeviceAuthService {
+    db;
+    txHost;
+    redis;
+    config;
+    devices;
+    machines;
+    log;
+    constructor(db, txHost, redis, config, devices, machines, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.redis = redis;
+        this.config = config;
+        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().devices.local;
+        const deviceCode = DEVICE_CODE_PREFIX + randomBytes(32).toString("base64url");
+        const hash = sha256Hex(deviceCode);
+        for (let attempt = 0;; attempt++) {
+            const userCode = newUserCode();
+            // the pointer first: a user code is never shared by two device codes
+            const free = await this.redis.eval(CREATE_POINTER, 1, deviceUserKey(userCode), hash, ttl);
+            if (free !== 1) {
+                if (attempt >= 4)
+                    throw new Error("could not find a free device user code");
+                continue;
+            }
+            const info = {
+                machine,
+                userCode,
+                expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+            };
+            await this.redis
+                .multi()
+                .hset(authKeyOf(hash), {
+                info: JSON.stringify(info),
+                status: "pending",
+                interval: String(interval),
+            })
+                .expire(authKeyOf(hash), ttl)
+                .exec();
+            return {
+                deviceCode,
+                userCode,
+                verificationUri: `${web}${DEVICE_PAGE_PATH}`,
+                verificationUriComplete: `${web}${DEVICE_PAGE_PATH}?code=${userCode}`,
+                interval,
+                expiresIn: ttl,
+            };
+        }
+    }
+    /**
+     * The program's poll: the grant once the person confirmed (the code is consumed), else
+     * `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();
+        if (!DEVICE_CODE_RE.test(deviceCode))
+            throw expired();
+        const r = (await this.redis.eval(POLL, 1, deviceAuthKey(deviceCode), String(Date.now()), String(POLL_JITTER_MS), String(SLOW_DOWN_STEP_SECONDS)));
+        switch (r[0]) {
+            case "approved": {
+                const grant = JSON.parse(r[1]);
+                const local = this.config.get().devices.local;
+                return {
+                    ...grant,
+                    connectUrl,
+                    reconnectGraceSeconds: local.reconnectGraceSeconds,
+                    maxFrameBytes: local.maxFrameBytes,
+                };
+            }
+            case "slow_down":
+                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_sign_in.denied", "The sign-in was denied in the browser");
+            case "pending":
+            case "claimed":
+                throw new ApiError("device_sign_in.authorization_pending", "Waiting for the code to be confirmed in the browser");
+            default:
+                throw expired();
+        }
+    }
+    /** The machine waiting behind a user code, for the confirmation page. */
+    async pending(userCode) {
+        const { info } = await this.lookup(userCode, "pending");
+        return { machine: info.machine, expiresAt: info.expiresAt };
+    }
+    /**
+     * The person confirms a user code: in an org where they may use agents (`agents.use`), into
+     * 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.
+     */
+    async confirm(principal, input) {
+        await authorizeOrgAction(this.db.db, principal, input.orgId, "agents.use");
+        const { info, hash } = await this.lookup(input.userCode, "pending");
+        if (!(await this.transition(hash, "pending", "claimed")))
+            throw codeInvalid();
+        let issued;
+        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 === "device.name_taken") {
+                    return this.confirmIn(principal.account.id, input, info);
+                }
+                throw e;
+            });
+        }
+        catch (e) {
+            await this.transition(hash, "claimed", "pending").catch(() => undefined);
+            throw e;
+        }
+        await this.park(hash, info, issued);
+        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_sign_in.expired` / `device_sign_in.unavailable`.
+     */
+    async park(hash, info, issued) {
+        let parked;
+        let failure;
+        try {
+            parked = await this.transition(hash, "claimed", "approved", JSON.stringify(issued.grant));
+        }
+        catch (e) {
+            parked = false;
+            failure = e;
+        }
+        if (parked) {
+            await this.redis.del(deviceUserKey(info.userCode)).catch((err) => {
+                this.log.warn("could not delete a used device user code", { err });
+            });
+            return;
+        }
+        this.log.warn("device credential could not be parked; the machine is revoked", {
+            deviceId: issued.deviceId,
+            machineId: issued.machineId,
+            err: failure,
+        });
+        await this.abandon(issued);
+        // 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_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) {
+        const { grant, machineId } = issued;
+        if (!(await this.machines.revokeMachine(machineId)))
+            return;
+        await audit(this.db.db, {
+            actorAccountId: issued.accountId,
+            orgId: grant.orgId,
+            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_sign_in.denied`. */
+    async deny(userCode) {
+        const { info, hash } = await this.lookup(userCode, "pending");
+        if (!(await this.transition(hash, "pending", "denied")))
+            throw codeInvalid();
+        await this.redis.del(deviceUserKey(info.userCode));
+    }
+    async confirmIn(accountId, input, info) {
+        const { orgId } = input;
+        let deviceId;
+        if (input.name !== undefined) {
+            const name = await this.freeName(orgId, accountId, input.name);
+            deviceId = (await this.devices.createLocal(orgId, accountId, name)).id;
+        }
+        else {
+            const env = await this.db
+                .selectFrom("devices")
+                .select("id")
+                .where("id", "=", input.deviceId)
+                .where("org_id", "=", orgId)
+                .where("owner_kind", "=", "personal")
+                .where("owner_account_id", "=", accountId)
+                .where("source", "=", "local")
+                .where("provider", "=", LOCAL_PROVIDER)
+                .where("deleted_at", "is", null)
+                .forNoKeyUpdate()
+                .executeTakeFirst();
+            if (!env)
+                throw deviceNotFound();
+            deviceId = env.id;
+        }
+        const { machine } = info;
+        const { machineId, credential } = await this.machines.issue({
+            orgId,
+            deviceId,
+            accountId,
+            ...machine,
+        });
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            orgId,
+            action: "device.machine_connected",
+            target: deviceId,
+            detail: { machineId, ...machine },
+        });
+        return {
+            deviceId,
+            machineId,
+            accountId,
+            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("devices")
+            .select("name")
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .where("name", "is not", null)
+            .execute()).map((r) => r.name.toLowerCase()));
+        let candidate = name;
+        for (let n = 2; taken.has(candidate.toLowerCase()); n++) {
+            const suffix = ` ${n}`;
+            candidate = `${name.slice(0, 64 - suffix.length)}${suffix}`;
+        }
+        return candidate;
+    }
+    /** 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)
+            throw codeInvalid();
+        const hash = await this.redis.get(deviceUserKey(code));
+        if (hash === null)
+            throw codeInvalid();
+        const [info, current] = await this.redis.hmget(authKeyOf(hash), "info", "status");
+        if (info === null || info === undefined || current !== status)
+            throw codeInvalid();
+        return { info: JSON.parse(info), hash };
+    }
+    async transition(hash, from, to, grant) {
+        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 → `device.unavailable`. */
+    publicUrl() {
+        const url = this.config.get().http.publicUrl;
+        if (!url) {
+            throw new ApiError("device.unavailable", "Connecting machines needs http.publicUrl to be configured; ask the super admin");
+        }
+        return url.replace(/\/+$/, "");
+    }
+    /** The machine's WebSocket URL: the public URL with `ws` / `wss` and `/device/connect`. */
+    connectUrl() {
+        return `${this.publicUrl().replace(/^http/i, "ws")}${DEVICE_CONNECT_PATH}`;
+    }
+};
+__decorate([
+    Transactional()
+], DeviceAuthService.prototype, "abandon", null);
+__decorate([
+    Transactional()
+], DeviceAuthService.prototype, "confirmIn", null);
+DeviceAuthService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(DevicesService)),
+    __param(5, Inject(MachinesService)),
+    __param(6, Inject(KERNEL_LOGGER))
+], DeviceAuthService);
+export { DeviceAuthService };
+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/local-devices/device-auth.module.js

@@ -0,0 +1,25 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { DevicesModule } from "../devices/devices.module.js";
+import { DeviceAuthService } from "./device-auth.js";
+import { LocalDevicesModule } from "./local-devices.module.js";
+/**
+ * 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.
+ */
+let DeviceAuthModule = class DeviceAuthModule {
+};
+DeviceAuthModule = __decorate([
+    Module({
+        imports: [LocalDevicesModule, DevicesModule],
+        providers: [DeviceAuthService],
+        exports: [DeviceAuthService],
+    })
+], DeviceAuthModule);
+export { DeviceAuthModule };

package/dist/local-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 (`LocalDeviceGateway`). */
+export interface DeviceRoutesGateway {
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    accept(socket: WebSocket, identity: MachineIdentity, credential: string): void;
+}
+export interface DeviceRoutesOptions {
+    gateway: DeviceRoutesGateway;
+    /** `devices.local.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 `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
+ * 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/local-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 `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
+ * 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("device.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/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") {
+}