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

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

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

@@ -0,0 +1,128 @@
+import { type ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { WebSocket } from "@fastify/websocket";
+import type { Redis } from "ioredis";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { type MachineIdentity, MachinesService } from "./machines.js";
+/** WebSocket close codes the gateway uses (the program reads 4002 and 4003). */
+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). */
+    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. */
+    readonly replaced: 4002;
+    /** The machine's credential was revoked: the program exits. */
+    readonly revoked: 4003;
+    /** No valid `hello` first, or a frame that is not protocol v1 from a device. */
+    readonly protocol: 4400;
+    /** The lease could not be claimed in time: reconnect. */
+    readonly claimTimeout: 4409;
+};
+/** How long the program has to send `hello` after the upgrade. */
+export declare const HELLO_TIMEOUT_MS = 10000;
+/** How often a connection is pinged; two pings without a pong close it. */
+export declare const PING_INTERVAL_MS = 20000;
+/** How long a new connection retries the lease after asking the holder to let go. */
+export declare const CLAIM_TIMEOUT_MS = 5000;
+/** The pause between two tries at the lease while claiming. */
+export declare const CLAIM_RETRY_MS = 250;
+type State = "hello" | "claiming" | "holding" | "closed";
+/**
+ * One machine connection on this replica. Its state (the socket, the lease handle, the requests
+ * it forwarded) is the socket's own and lives exactly as long as the socket.
+ */
+declare class DeviceConnection {
+    private readonly gw;
+    private readonly socket;
+    readonly identity: MachineIdentity;
+    private readonly credential;
+    readonly token: `${string}-${string}-${string}-${string}-${string}`;
+    state: State;
+    private lease;
+    private readonly unsubscribes;
+    private helloTimer;
+    private pingTimer;
+    private missedPongs;
+    private lastTouch;
+    private lastAuth;
+    /** The drains (and the close after a revocation) run one after another. */
+    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;
+    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.
+     */
+    private store;
+    /**
+     * Claims the environment'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.
+     */
+    private claim;
+    /** Subscribes for this connection; a subscription that completes after the close is ended. */
+    private subscribe;
+    /** Queues one drain of the request list after the ones already queued. */
+    private drain;
+    private drainOnce;
+    /** 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). */
+    private reauthenticate;
+    private traffic;
+    /** Closes the socket with `code` and hands the lease back; idempotent. */
+    close(code: number, reason: string): Promise<void>;
+    /** Stops timers and subscriptions and releases the lease (a lost one is abandoned). */
+    shutdown(): Promise<void>;
+}
+/**
+ * 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
+ * (`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
+ * `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
+ * sockets are this process's own; everything other replicas need is in Redis.
+ */
+export declare class DeviceGateway {
+    readonly machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">;
+    readonly locks: Pick<LockService, "hold">;
+    readonly bus: ExtensionContext["bus"];
+    readonly redis: Redis;
+    private readonly config;
+    readonly log: Pick<KernelLogger, "info" | "warn">;
+    /** This replica's open connections (the sockets cannot live anywhere else). */
+    private readonly connections;
+    private stopping;
+    /** How often connections are pinged ({@link PING_INTERVAL_MS}; a test seam). */
+    pingIntervalMs: number;
+    constructor(machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">, locks: Pick<LockService, "hold">, bus: ExtensionContext["bus"], redis: Redis, config: KernelConfigService, log: Pick<KernelLogger, "info" | "warn">);
+    graceMs(): number;
+    leaseTtlMs(): number;
+    maxFrameBytes(): number;
+    /** Who a `Bearer` machine credential stands for, or null (checked before the upgrade). */
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    /** Serves one upgraded socket of an authenticated machine until it closes. */
+    accept(socket: WebSocket, identity: MachineIdentity, credential: string): void;
+    /** @internal a connection that ended. */
+    forget(conn: DeviceConnection): void;
+    /** Closes every connection (1001) and hands their leases back. */
+    stop(): Promise<void>;
+}
+export {};