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

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

@@ -0,0 +1,116 @@
+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 { Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
+import { CurrentPrincipal, Public, requireUser, SessionOnly, } from "../identity/principal.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { Throttled } from "../infra/throttler/throttler.guard.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
+import { DeviceAuthService, } from "./device-auth.js";
+import { DeviceAuthorizeBodyDto, DeviceConfirmBodyDto, DeviceTokenBodyDto, DeviceUserCodeBodyDto, DeviceUserCodeParamsDto, } from "./dto.js";
+/** The throttler of every route that takes a user code (guessing another machine's code). */
+const CODE_THROTTLER = ["device-code-account"];
+/**
+ * Device sign-in (`/api/v1/device`, environments spec §13.3; the shape of RFC 8628).
+ *
+ * The program's routes are public (it has no credential yet); like every public unsafe route
+ * they need `X-Capybara-Csrf: 1`, which `capybara-device` sends:
+ * - `POST /authorize { name, os, arch, programVersion }` → `{ deviceCode, userCode,
+ *   verificationUri, verificationUriComplete, interval, expiresIn }` (`device-authorize-ip`);
+ * - `POST /token { deviceCode }` → `{ credential, orgId, environmentId, connectUrl,
+ *   reconnectGraceSeconds, maxFrameBytes }` once, else `device.authorization_pending` / `device.slow_down` /
+ *   `device.denied` / `device.expired` (`device-token-ip`).
+ *
+ * The person's routes need a web session (the confirmation page `/device`); each try of a user
+ * code counts on `device-code-account` (refunded on success):
+ * - `GET /pending/:userCode` → `{ machine, expiresAt }`;
+ * - `POST /confirm { userCode, orgId, environmentId | name }` → `{ environmentId }`
+ *   (`device.expired` / `device.unavailable` when the credential could not be handed over: the
+ *   machine is revoked again and the person runs login again);
+ * - `POST /deny { userCode }` → 204.
+ */
+let DeviceAuthController = class DeviceAuthController {
+    auth;
+    throttler;
+    constructor(auth, throttler) {
+        this.auth = auth;
+        this.throttler = throttler;
+    }
+    async authorize(body) {
+        return this.auth.authorize(body);
+    }
+    async token(body) {
+        return this.auth.token(body.deviceCode);
+    }
+    async pending(principal, params, req, reply) {
+        requireUser(principal);
+        return this.counted(req, reply, () => this.auth.pending(params.userCode));
+    }
+    async confirm(principal, body, req, reply) {
+        const p = requireUser(principal);
+        return this.counted(req, reply, () => this.auth.confirm(p, body));
+    }
+    async deny(principal, body, req, reply) {
+        requireUser(principal);
+        await this.counted(req, reply, () => this.auth.deny(body.userCode));
+    }
+    /** Runs `fn` as one counted try of a user code; a success gives the try back. */
+    async counted(req, reply, fn) {
+        await this.throttler.reserve(CODE_THROTTLER, req, reply);
+        const out = await fn();
+        await this.throttler.succeeded(CODE_THROTTLER, req);
+        return out;
+    }
+};
+__decorate([
+    Post("authorize"),
+    Public(),
+    HttpCode(200),
+    Throttled("device-authorize-ip"),
+    __param(0, ZBody(DeviceAuthorizeBodyDto))
+], DeviceAuthController.prototype, "authorize", null);
+__decorate([
+    Post("token"),
+    Public(),
+    HttpCode(200),
+    Throttled("device-token-ip"),
+    __param(0, ZBody(DeviceTokenBodyDto))
+], DeviceAuthController.prototype, "token", null);
+__decorate([
+    Get("pending/:userCode"),
+    SessionOnly(),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(DeviceUserCodeParamsDto)),
+    __param(2, Req()),
+    __param(3, Res({ passthrough: true }))
+], DeviceAuthController.prototype, "pending", null);
+__decorate([
+    Post("confirm"),
+    SessionOnly(),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZBody(DeviceConfirmBodyDto)),
+    __param(2, Req()),
+    __param(3, Res({ passthrough: true }))
+], DeviceAuthController.prototype, "confirm", null);
+__decorate([
+    Post("deny"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZBody(DeviceUserCodeBodyDto)),
+    __param(2, Req()),
+    __param(3, Res({ passthrough: true }))
+], DeviceAuthController.prototype, "deny", null);
+DeviceAuthController = __decorate([
+    Controller("api/v1/device"),
+    __param(0, Inject(DeviceAuthService)),
+    __param(1, Inject(CredentialThrottler))
+], DeviceAuthController);
+export { DeviceAuthController };

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

@@ -0,0 +1,119 @@
+import type { Redis } from "ioredis";
+import { EnvironmentsService } from "../environments/environments.service.js";
+import type { UserPrincipal } from "../identity/principal.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 type { KernelLogger } from "../log.js";
+import { MachinesService } from "./machines.js";
+/** The 20 consonants a user code is made of (no vowels: no words; no look-alike letters). */
+export declare const USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+/** What `slow_down` adds to the poll interval (RFC 8628 §3.5). */
+export declare const SLOW_DOWN_STEP_SECONDS = 5;
+/** The web page that confirms a code: `<http.publicUrl>/device`. */
+export declare const DEVICE_PAGE_PATH = "/device";
+/** The machine's WebSocket route: `ws(s)://<http.publicUrl host>/device/connect`. */
+export declare const DEVICE_CONNECT_PATH = "/device/connect";
+/** The sign-in state of one device code: `capk:device-auth:<sha256(deviceCode)>` (a hash). */
+export declare const deviceAuthKey: (deviceCode: string) => string;
+/** The user code's pointer to its device code's hash: `capk:device-user:<XXXX-XXXX>`. */
+export declare const deviceUserKey: (userCode: string) => string;
+/** The machine as `authorize` described it. */
+export interface DeviceMachineInfo {
+    name: string;
+    os: "darwin" | "linux";
+    arch: string;
+    programVersion: string;
+}
+interface Grant {
+    credential: string;
+    orgId: string;
+    environmentId: string;
+}
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    interval: number;
+    expiresIn: number;
+}
+export interface DeviceGrant extends Grant {
+    connectUrl: string;
+    reconnectGraceSeconds: number;
+    /** `environments.device.maxFrameBytes`: the program never sends a larger frame (ruling R26). */
+    maxFrameBytes: number;
+}
+/** A user code as typed → `XXXX-XXXX`, or null when it cannot be one. */
+export declare function normalizeUserCode(input: string): string | null;
+/**
+ * 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
+ * (`environments.device.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.
+ */
+export declare class DeviceAuthService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly redis;
+    private readonly config;
+    private readonly environments;
+    private readonly machines;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, config: Pick<KernelConfigService, "get">, environments: Pick<EnvironmentsService, "createDevice">, machines: Pick<MachinesService, "issue" | "revokeMachine">, log: Pick<KernelLogger, "warn">);
+    /** A new code pair for a machine. Needs `http.publicUrl` (the page and the connection URL). */
+    authorize(machine: DeviceMachineInfo): Promise<DeviceAuthorization>;
+    /**
+     * 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).
+     */
+    token(deviceCode: string): Promise<DeviceGrant>;
+    /** The machine waiting behind a user code, for the confirmation page. */
+    pending(userCode: string): Promise<{
+        machine: DeviceMachineInfo;
+        expiresAt: string;
+    }>;
+    /**
+     * 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
+     * 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.
+     */
+    confirm(principal: UserPrincipal, input: {
+        userCode: string;
+        orgId: string;
+        environmentId?: string | undefined;
+        name?: string | undefined;
+    }): Promise<{
+        environmentId: string;
+    }>;
+    /**
+     * 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`.
+     */
+    private park;
+    /** Revokes a machine whose credential never reached the program (see {@link park}). */
+    private abandon;
+    /** The person refuses a user code: the program's next poll gets `device.denied`. */
+    deny(userCode: string): Promise<void>;
+    private confirmIn;
+    /** `name`, or `name 2`, `name 3`, … : the first that is none of the person's live names. */
+    private freeName;
+    /** The code behind a user code with status `status`, else `device.code_invalid`. */
+    private lookup;
+    private transition;
+    /** `http.publicUrl` without trailing slashes; unset → `environment.unavailable`. */
+    private publicUrl;
+    /** The machine's WebSocket URL: the public URL with `ws` / `wss` and `/device/connect`. */
+    private connectUrl;
+}
+export {};

package/dist/devices/device-auth.js

@@ -0,0 +1,403 @@
+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 { EnvironmentsService } from "../environments/environments.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 { DEVICE_PROVIDER } from "../sandbox/providers.js";
+import { environmentNotFound } 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>/device`. */
+export const DEVICE_PAGE_PATH = "/device";
+/** 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.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
+ * (`environments.device.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;
+    environments;
+    machines;
+    log;
+    constructor(db, txHost, redis, config, environments, machines, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.redis = redis;
+        this.config = config;
+        this.environments = environments;
+        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 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.authorization_pending`, `device.slow_down` (details `[{ interval }]`, the grown
+     * interval), `device.denied` or `device.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 device = this.config.get().environments.device;
+                return {
+                    ...grant,
+                    connectUrl,
+                    reconnectGraceSeconds: device.reconnectGraceSeconds,
+                    maxFrameBytes: device.maxFrameBytes,
+                };
+            }
+            case "slow_down":
+                throw new ApiError("device.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");
+            case "pending":
+            case "claimed":
+                throw new ApiError("device.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 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
+     * 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 === "environment.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 { environmentId: issued.environmentId };
+    }
+    /**
+     * 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`.
+     */
+    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", {
+            environmentId: issued.environmentId,
+            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
+        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");
+    }
+    /** 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: "environment.machine_revoked",
+            target: grant.environmentId,
+            detail: { machineId, reason: "sign_in_incomplete" },
+        });
+    }
+    /** The person refuses a user code: the program's next poll gets `device.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 environmentId;
+        if (input.name !== undefined) {
+            const name = await this.freeName(orgId, accountId, input.name);
+            environmentId = (await this.environments.createDevice(orgId, accountId, name)).id;
+        }
+        else {
+            const env = await this.db
+                .selectFrom("environments")
+                .select("id")
+                .where("id", "=", input.environmentId)
+                .where("org_id", "=", orgId)
+                .where("owner_kind", "=", "personal")
+                .where("owner_account_id", "=", accountId)
+                .where("source", "=", "device")
+                .where("provider", "=", DEVICE_PROVIDER)
+                .where("deleted_at", "is", null)
+                .forNoKeyUpdate()
+                .executeTakeFirst();
+            if (!env)
+                throw environmentNotFound();
+            environmentId = env.id;
+        }
+        const { machine } = info;
+        const { machineId, credential } = await this.machines.issue({
+            orgId,
+            environmentId,
+            accountId,
+            ...machine,
+        });
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            orgId,
+            action: "environment.machine_connected",
+            target: environmentId,
+            detail: { machineId, ...machine },
+        });
+        return {
+            environmentId,
+            machineId,
+            accountId,
+            grant: { credential, orgId, environmentId },
+        };
+    }
+    /** `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")
+            .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.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 → `environment.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");
+        }
+        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(EnvironmentsService)),
+    __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");

package/dist/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 DevicesModule}, which `EnvironmentsModule`
+ * imports (deleting an environment revokes its machine), while sign-in needs both.
+ */
+export declare class DeviceAuthModule {
+}

package/dist/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 { EnvironmentsModule } from "../environments/environments.module.js";
+import { DeviceAuthService } from "./device-auth.js";
+import { DevicesModule } from "./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.
+ */
+let DeviceAuthModule = class DeviceAuthModule {
+};
+DeviceAuthModule = __decorate([
+    Module({
+        imports: [DevicesModule, EnvironmentsModule],
+        providers: [DeviceAuthService],
+        exports: [DeviceAuthService],
+    })
+], DeviceAuthModule);
+export { DeviceAuthModule };