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

package/dist/devices/machines.d.ts

@@ -0,0 +1,106 @@
+import type { DeviceHello, DeviceStopArgs, ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { DeviceRelay } from "./relay.js";
+/** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
+export declare const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
+/** What a machine credential stands for. */
+export interface MachineIdentity {
+    machineId: string;
+    orgId: string;
+    environmentId: string;
+    accountId: string;
+}
+/** The machine connected to an environment (its unrevoked row). */
+export interface ActiveMachine {
+    id: string;
+    orgId: string;
+    accountId: string;
+    name: string;
+    os: string;
+    arch: string;
+    programVersion: string | null;
+    lastSeenAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Connected machines and their credentials (environments spec §13.2). One active machine per
+ * device environment: issuing a credential revokes the environment's previous machine. A
+ * credential is `cap_dev_` plus 32 random bytes; only its sha256 is stored. It is accepted only
+ * by the device connection route ({@link authenticate}), never by `/api`: it is no `Principal`.
+ *
+ * A revoked machine is told so after the commit: `stop { reason }` relayed while a replica holds
+ * its connection (fire-and-forget, ruling R14) and `device.revoked.<environmentId>` published with
+ * `{ machineId }`, so the holder closes that machine's connection.
+ */
+export declare class MachinesService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly relay;
+    private readonly bus;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<DeviceRelay, "holderLive" | "send">, bus: ExtensionContext["bus"], log: Pick<KernelLogger, "warn">);
+    /**
+     * A new machine for the environment and its credential (returned once). Revokes the
+     * environment's active machine first. Joins the caller's transaction (the device confirmation),
+     * which has already checked the environment is the person's own live device environment.
+     */
+    issue(input: {
+        orgId: string;
+        environmentId: string;
+        accountId: string;
+        name: string;
+        os: string;
+        arch: string;
+        programVersion: string;
+    }): Promise<{
+        machineId: string;
+        credential: string;
+    }>;
+    /**
+     * Ruling R23: the new machine may serve the environment from another directory or mode (other
+     * roots), and a login recreates a directory that was lost (ruling R24). So the instance row
+     * forgets its instance (status `none`, no handle) and its files count as there again; the next
+     * use creates a fresh instance on the machine (with its roots: a new `environment_paths` event
+     * follows). The fence moves on, so a lifecycle holder of the old instance fails its next write.
+     */
+    private resetInstance;
+    /**
+     * Who a machine credential stands for, or null: the machine is not revoked, its environment is
+     * live, the org is not deleted (ruling R12), and the person is an active account still a member
+     * of the org. Read live on every call (a connection re-checks it as it sees fit).
+     */
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    /** Stores what the program reported in its hello frame and marks the machine seen. */
+    recordHello(machineId: string, hello: DeviceHello): Promise<void>;
+    /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
+    touch(machineId: string): Promise<void>;
+    /**
+     * Disconnects the machine of one of the person's own live device environments (`DELETE
+     * /orgs/:orgId/environments/:id/machine`): revokes it and audits
+     * `environment.machine_revoked`. Anyone else's environment, a cloud one or a missing one →
+     * `environment.not_found`; no machine connected is a no-op.
+     */
+    revoke(orgId: string, accountId: string, environmentId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * Revokes the environment's active machine, if any, in the caller's transaction, and after the
+     * commit tells it to stop for `reason` (none: only its connection is closed) and closes its
+     * connection. Returns the revoked machine's id. Used by {@link issue} (replaced: no stop),
+     * {@link revoke} and the environment's deletion (`deleted`).
+     */
+    revokeActive(environmentId: string, reason: DeviceStopArgs["reason"] | null): Promise<string | null>;
+    /**
+     * Revokes one machine by id (a sign-in whose credential never reached the program), with the
+     * same post-commit disconnect as a replacement (no stop frame). True when it was active.
+     */
+    revokeMachine(machineId: string): Promise<boolean>;
+    /** The environment's active machine, or null. */
+    activeFor(environmentId: string): Promise<ActiveMachine | null>;
+    /**
+     * After a revocation commits: `stop` is queued only while a replica holds the connection (an
+     * offline machine must not find it on the list later), then the revocation is published.
+     * Failures are logged; the revocation itself stands.
+     */
+    private disconnect;
+}

package/dist/devices/machines.js

@@ -0,0 +1,301 @@
+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 { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+import { sha256Hex } from "../identity/hash.js";
+import { afterCommit } from "../infra/database/after-commit.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_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
+import { DEVICE_PROVIDER } from "../sandbox/providers.js";
+import { environmentNotFound } from "../sandbox/sandbox.service.js";
+import { deviceRevokedTopic } from "./keys.js";
+import { DeviceRelay } from "./relay.js";
+/** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
+export const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
+const CREDENTIAL_RE = /^cap_dev_[A-Za-z0-9_-]{43}$/;
+/** How long the `stop` frame told to a revoked machine may take (it only closes the connection). */
+const STOP_DEADLINE_MS = 30_000;
+/**
+ * Connected machines and their credentials (environments spec §13.2). One active machine per
+ * device environment: issuing a credential revokes the environment's previous machine. A
+ * credential is `cap_dev_` plus 32 random bytes; only its sha256 is stored. It is accepted only
+ * by the device connection route ({@link authenticate}), never by `/api`: it is no `Principal`.
+ *
+ * A revoked machine is told so after the commit: `stop { reason }` relayed while a replica holds
+ * its connection (fire-and-forget, ruling R14) and `device.revoked.<environmentId>` published with
+ * `{ machineId }`, so the holder closes that machine's connection.
+ */
+let MachinesService = class MachinesService {
+    db;
+    txHost;
+    relay;
+    bus;
+    log;
+    constructor(db, txHost, relay, bus, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.relay = relay;
+        this.bus = bus;
+        this.log = log;
+    }
+    /**
+     * A new machine for the environment and its credential (returned once). Revokes the
+     * environment's active machine first. Joins the caller's transaction (the device confirmation),
+     * which has already checked the environment is the person's own live device environment.
+     */
+    async issue(input) {
+        // no stop frame: it would wait on the list and could reach the replacement machine instead
+        await this.revokeActive(input.environmentId, null);
+        await this.resetInstance(input.environmentId);
+        const credential = MACHINE_CREDENTIAL_PREFIX + randomBytes(32).toString("base64url");
+        const row = await this.db
+            .insertInto("environment_machines")
+            .values({
+            org_id: input.orgId,
+            environment_id: input.environmentId,
+            account_id: input.accountId,
+            credential_hash: sha256Hex(credential),
+            name: input.name,
+            os: input.os,
+            arch: input.arch,
+            program_version: input.programVersion,
+        })
+            .returning("id")
+            .executeTakeFirstOrThrow();
+        return { machineId: row.id, credential };
+    }
+    /**
+     * Ruling R23: the new machine may serve the environment from another directory or mode (other
+     * roots), and a login recreates a directory that was lost (ruling R24). So the instance row
+     * forgets its instance (status `none`, no handle) and its files count as there again; the next
+     * use creates a fresh instance on the machine (with its roots: a new `environment_paths` event
+     * follows). The fence moves on, so a lifecycle holder of the old instance fails its next write.
+     */
+    async resetInstance(environmentId) {
+        await this.db
+            .updateTable("environment_instances")
+            .set((eb) => ({
+            status: "none",
+            handle: null,
+            fs_status: sql `CASE WHEN fs_handle IS NULL THEN 'none' ELSE 'ready' END`,
+            running_since: null,
+            suspended_at: null,
+            destroyed_at: sql `now()`,
+            generation: eb("generation", "+", 1),
+        }))
+            .where("environment_id", "=", environmentId)
+            .execute();
+    }
+    /**
+     * Who a machine credential stands for, or null: the machine is not revoked, its environment is
+     * live, the org is not deleted (ruling R12), and the person is an active account still a member
+     * of the org. Read live on every call (a connection re-checks it as it sees fit).
+     */
+    async authenticate(credential) {
+        if (!CREDENTIAL_RE.test(credential))
+            return null;
+        const row = await this.db
+            .selectFrom("environment_machines as m")
+            .innerJoin("environments as e", "e.id", "m.environment_id")
+            .innerJoin("orgs as o", "o.id", "m.org_id")
+            .innerJoin("memberships as ms", (j) => j.onRef("ms.org_id", "=", "m.org_id").onRef("ms.account_id", "=", "m.account_id"))
+            .innerJoin("accounts as a", "a.id", "m.account_id")
+            .select(["m.id", "m.org_id", "m.environment_id", "m.account_id"])
+            .where("m.credential_hash", "=", sha256Hex(credential))
+            .where("m.revoked_at", "is", null)
+            .whereRef("e.org_id", "=", "m.org_id")
+            .where("e.deleted_at", "is", null)
+            .where("e.source", "=", "device")
+            .where("o.deleted_at", "is", null)
+            .where("a.status", "=", "active")
+            .executeTakeFirst();
+        return row
+            ? {
+                machineId: row.id,
+                orgId: row.org_id,
+                environmentId: row.environment_id,
+                accountId: row.account_id,
+            }
+            : null;
+    }
+    /** Stores what the program reported in its hello frame and marks the machine seen. */
+    async recordHello(machineId, hello) {
+        await this.db
+            .updateTable("environment_machines")
+            .set({
+            program_version: hello.programVersion,
+            os: hello.os,
+            arch: hello.arch,
+            mode: hello.mode,
+            roots: JSON.stringify(hello.roots),
+            session_isolation: hello.sessionIsolation,
+            last_seen_at: sql `now()`,
+        })
+            .where("id", "=", machineId)
+            .where("revoked_at", "is", null)
+            .execute();
+    }
+    /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
+    async touch(machineId) {
+        await this.db
+            .updateTable("environment_machines")
+            .set({ last_seen_at: sql `now()` })
+            .where("id", "=", machineId)
+            .where("revoked_at", "is", null)
+            .where((eb) => eb.or([
+            eb("last_seen_at", "is", null),
+            eb("last_seen_at", "<", sql `now() - interval '60 seconds'`),
+        ]))
+            .execute();
+    }
+    /**
+     * Disconnects the machine of one of the person's own live device environments (`DELETE
+     * /orgs/:orgId/environments/:id/machine`): revokes it and audits
+     * `environment.machine_revoked`. Anyone else's environment, a cloud one or a missing one →
+     * `environment.not_found`; no machine connected is a no-op.
+     */
+    async revoke(orgId, accountId, environmentId, actorTokenId) {
+        const env = await this.db
+            .selectFrom("environments")
+            .select("id")
+            .where("id", "=", 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();
+        const machineId = await this.revokeActive(environmentId, "revoked");
+        if (machineId === null)
+            return;
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.machine_revoked",
+            target: environmentId,
+            detail: { machineId },
+        });
+    }
+    /**
+     * Revokes the environment's active machine, if any, in the caller's transaction, and after the
+     * commit tells it to stop for `reason` (none: only its connection is closed) and closes its
+     * connection. Returns the revoked machine's id. Used by {@link issue} (replaced: no stop),
+     * {@link revoke} and the environment's deletion (`deleted`).
+     */
+    async revokeActive(environmentId, reason) {
+        const row = await this.db
+            .updateTable("environment_machines")
+            .set({ revoked_at: sql `now()` })
+            .where("environment_id", "=", environmentId)
+            .where("revoked_at", "is", null)
+            .returning("id")
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        const machineId = row.id;
+        afterCommit(() => this.disconnect(environmentId, machineId, reason));
+        return machineId;
+    }
+    /**
+     * Revokes one machine by id (a sign-in whose credential never reached the program), with the
+     * same post-commit disconnect as a replacement (no stop frame). True when it was active.
+     */
+    async revokeMachine(machineId) {
+        const row = await this.db
+            .updateTable("environment_machines")
+            .set({ revoked_at: sql `now()` })
+            .where("id", "=", machineId)
+            .where("revoked_at", "is", null)
+            .returning("environment_id")
+            .executeTakeFirst();
+        if (!row)
+            return false;
+        const environmentId = row.environment_id;
+        afterCommit(() => this.disconnect(environmentId, machineId, null));
+        return true;
+    }
+    /** The environment's active machine, or null. */
+    async activeFor(environmentId) {
+        const r = await this.db
+            .selectFrom("environment_machines")
+            .select([
+            "id",
+            "org_id",
+            "account_id",
+            "name",
+            "os",
+            "arch",
+            "program_version",
+            "last_seen_at",
+            "created_at",
+        ])
+            .where("environment_id", "=", environmentId)
+            .where("revoked_at", "is", null)
+            .executeTakeFirst();
+        return r
+            ? {
+                id: r.id,
+                orgId: r.org_id,
+                accountId: r.account_id,
+                name: r.name,
+                os: r.os,
+                arch: r.arch,
+                programVersion: r.program_version,
+                lastSeenAt: r.last_seen_at,
+                createdAt: r.created_at,
+            }
+            : null;
+    }
+    /**
+     * After a revocation commits: `stop` is queued only while a replica holds the connection (an
+     * offline machine must not find it on the list later), then the revocation is published.
+     * Failures are logged; the revocation itself stands.
+     */
+    async disconnect(environmentId, machineId, reason) {
+        try {
+            if (reason !== null && (await this.relay.holderLive(environmentId))) {
+                await this.relay.send(environmentId, "stop", { reason }, STOP_DEADLINE_MS);
+            }
+        }
+        catch (err) {
+            this.log.warn("could not tell a revoked machine to stop", { environmentId, machineId, err });
+        }
+        try {
+            await this.bus.publish(deviceRevokedTopic(environmentId), { machineId });
+        }
+        catch (err) {
+            this.log.warn("could not publish a machine revocation", { environmentId, machineId, err });
+        }
+    }
+};
+__decorate([
+    Transactional()
+], MachinesService.prototype, "issue", null);
+__decorate([
+    Transactional()
+], MachinesService.prototype, "revoke", null);
+MachinesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(DeviceRelay)),
+    __param(3, Inject(KERNEL_BUS)),
+    __param(4, Inject(KERNEL_LOGGER))
+], MachinesService);
+export { MachinesService };

package/dist/devices/relay.d.ts

@@ -0,0 +1,100 @@
+import { type DeviceOp, type DeviceOpResults, type ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { DeviceTargets } from "./targets.js";
+/** The environment's connected machine is not connected (no replica holds its lease). */
+export declare const environmentOffline: () => ApiError;
+/**
+ * The environment's machine was disconnected (revoked, signed out): 403 `environment.forbidden`
+ * with `details: [{ reason: "machine_revoked" }]`, so the tools tell the model what to ask for.
+ */
+export declare const machineRevoked: () => ApiError;
+/** The text a machine's `error` result reaches the model with (ruling R28). */
+export declare const ON_MACHINE_PREFIX = "On the connected machine: ";
+/** The longest one lease check of a waiting caller may take before it counts as "unknown". */
+export declare const LEASE_CHECK_TIMEOUT_MS = 2000;
+/** How often a waiting caller checks that a replica still holds the machine's connection. */
+export declare const HOLDER_POLL_MS = 5000;
+/**
+ * How much longer than the caller's wait a queued request lives: giving up must still find an
+ * untaken request on the list (an expired one would look taken and get a needless cancel).
+ */
+export declare const LIST_TTL_MARGIN_MS = 30000;
+export interface DeviceCallOptions {
+    /** How long the machine may take for the operation (sent to it as `deadlineMs`). */
+    deadlineMs: number;
+    /** The caller's signal: aborting gives the request up and rejects. */
+    signal: AbortSignal;
+}
+/**
+ * The caller side of the device relay (environments spec §13.4). A request goes onto the
+ * environment's Redis list (`capk:device-req:<environmentId>`) and is announced on
+ * `device.req.<environmentId>`; whichever gateway replica holds the machine's lease drains the
+ * list and forwards the frames to the machine.
+ *
+ * **The holder's half of the wire** (Task 6 follows it): items on the list are `KernelReq` or
+ * `KernelCancel` frames as JSON text, to be parsed with `parseDeviceFrame(item, "kernel")`; the
+ * nudge's payload is `{ id }`. For each `res` frame the machine sends, the holder writes the frame
+ * (the JSON text as validated by `parseDeviceFrame(…, "device")`) under
+ * `capk:device-res:<requestId>` with a TTL and publishes the same frame object on
+ * `device.res.<requestId>`.
+ *
+ * The caller subscribes to its result topic before pushing and reads the result key once after,
+ * and once more before giving up (the run-abort pattern; a publish lost while the subscriber
+ * reconnects is still found). It waits within its own call for at most `deadlineMs` plus
+ * `environments.device.reconnectGraceSeconds`; when the lease disappears meanwhile (checked every
+ * {@link HOLDER_POLL_MS}) the wait ends at most one grace later. A result produced while the
+ * machine was disconnected arrives after it reconnects. Giving up (grace, abort, a bad result)
+ * removes the request from the list, or queues a `cancel` when the machine already took it
+ * (ruling R15). Nothing is kept in process memory beyond the call.
+ */
+export declare class DeviceRelay {
+    private readonly redis;
+    private readonly bus;
+    private readonly locks;
+    private readonly config;
+    private readonly log;
+    private readonly targets;
+    constructor(redis: Redis, bus: ExtensionContext["bus"], locks: Pick<LockService, "holderOf">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "warn">, targets: Pick<DeviceTargets, "state">);
+    /** Whether a gateway replica holds the machine's connection now. */
+    holderLive(environmentId: string): Promise<boolean>;
+    /**
+     * Queues `op` for the machine without waiting for an answer (ruling R14: `stop`). The caller
+     * checks {@link holderLive} first; the frame waits on the list for the grace like any request.
+     */
+    send(environmentId: string, op: DeviceOp, args: unknown, deadlineMs: number): Promise<void>;
+    /**
+     * Runs `op` on the environment's machine and returns its validated result. Throws
+     * `environment.offline` when no replica holds the machine at send time or when the wait ran
+     * out, but `environment.forbidden` ({@link machineRevoked}) when the machine was revoked and
+     * `environment.not_found` when the environment was deleted (checked whenever the connection is
+     * missing, ruling R27); the machine's failures map to `SandboxGoneError` (`gone`),
+     * `FileSystemGoneError` (`fs_gone`) or a `ToolError` (`policy`, and `error` prefixed
+     * {@link ON_MACHINE_PREFIX}); an invalid answer throws a `DeviceProtocolError`. On abort the
+     * abort reason is thrown.
+     */
+    call<Op extends DeviceOp>(environmentId: string, op: Op, args: unknown, opts: DeviceCallOptions): Promise<DeviceOpResults[Op]>;
+    /** {@link holderLive}, or undefined when it takes longer than {@link LEASE_CHECK_TIMEOUT_MS}. */
+    private leaseCheck;
+    /**
+     * The environment's state ({@link DeviceTargets}), or undefined when it cannot be read within
+     * {@link LEASE_CHECK_TIMEOUT_MS} (a failure only logs: the caller keeps its other rules).
+     */
+    private targetState;
+    /** The error of a state that never comes back; undefined for `active` or unknown. */
+    private goneError;
+    private graceMs;
+    private push;
+    /** Announces new frames to the holder; a lost nudge is picked up on the holder's next drain. */
+    private nudge;
+    /** Removes the request from the list, or queues a cancel when the machine took it (R15). */
+    private giveUp;
+    /** Runs a side step whose failure must not replace the call's outcome: logged, swallowed. */
+    private quietly;
+    /** A stored / published `res` frame for request `id`, or the protocol error it carries. */
+    private parseRes;
+    private resultOf;
+}