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

package/dist/lifecycle/kernel-lifecycle.d.ts

@@ -21,6 +21,7 @@ import { AccountsService } from "../identity/accounts.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { ReplicaPresence } from "../infra/presence/replica-presence.js";
 import type { KernelLogger } from "../log.js";
 import { GatewayRole } from "../roles/gateway-role.js";
 import { WorkerRole } from "../roles/worker-role.js";
@@ -83,6 +84,7 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
     private readonly titles;
     private readonly channelJobs;
     private readonly channelOutbound;
+    private readonly presence;
     private readonly worker?;
     private readonly gateway?;
     /** The startup config (hot fields are read through the config service). */
@@ -97,7 +99,9 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
     private unwatchConfig;
     /** What the first bootstrap pass did, carried into the second one. */
     private bootstrapCarry;
-    constructor(accounts: AccountsService, configService: KernelConfigService, log: KernelLogger, options: KernelAppOptions, pool: Kysely<any>, redis: Redis, kdb: KernelDb, shutdown: GracefulShutdown, host: ExtensionHost, registry: ExtensionRegistry, installs: ExtensionInstalls, blobs: ExtensionBlobs, extensionLifecycle: ExtensionLifecycle, replicaStatus: ReplicaStatusStore, bootstrap: BootstrapService, marketplaces: MarketplacesService, pluginImport: PluginImport, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, usageReport: UsageReporter, titles: TitleQueue, channelJobs: ChannelJobs, channelOutbound: ChannelOutbound, worker?: WorkerRole | undefined, gateway?: GatewayRole | undefined);
+    /** The packages the first bootstrap pass obtained, so the second downloads nothing again. */
+    private bootstrapPackages;
+    constructor(accounts: AccountsService, configService: KernelConfigService, log: KernelLogger, options: KernelAppOptions, pool: Kysely<any>, redis: Redis, kdb: KernelDb, shutdown: GracefulShutdown, host: ExtensionHost, registry: ExtensionRegistry, installs: ExtensionInstalls, blobs: ExtensionBlobs, extensionLifecycle: ExtensionLifecycle, replicaStatus: ReplicaStatusStore, bootstrap: BootstrapService, marketplaces: MarketplacesService, pluginImport: PluginImport, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, usageReport: UsageReporter, titles: TitleQueue, channelJobs: ChannelJobs, channelOutbound: ChannelOutbound, presence: ReplicaPresence, worker?: WorkerRole | undefined, gateway?: GatewayRole | undefined);
     /** The kernel HTTP application (set up by `buildKernelApp` before `init()`). */
     get http(): KernelHttpApp;
     attachHttp(http: KernelHttpApp): void;
@@ -120,10 +124,12 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
      * kernel never serves without a required plugin. A failed optional entry is logged and returns
      * true: the start runs the step once more after the extensions loaded (a declarative entry's
      * catalog files need the object store, which on a fresh deployment is itself a bootstrap plugin),
-     * and the next start tries again while it stays incomplete.
+     * and the next start tries again while it stays incomplete. The first pass skips the `builtin`
+     * entries (they may ship skills and templates, which need the object store) and returns true for
+     * them too; the final pass imports them, and one that fails is logged like an optional entry.
      */
     private runBootstrap;
-    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    /** 部署尚无活跃超级管理员时提示去初始化；查询失败只记日志，不影响启动。 */
     private warnIfSetupPending;
     beforeApplicationShutdown(): Promise<void>;
     /** Logs the end of the stop phases (Redis and the pool close right after, in the infra modules). */

package/dist/lifecycle/kernel-lifecycle.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { SANDBOX_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable, Optional, } from "@nestjs/common";
 import { sql } from "kysely";
 import { MarketplacesService } from "../catalog/marketplaces.service.js";
@@ -26,16 +26,19 @@ import { ExtensionRegistry } from "../extensions/registry.js";
 import { ReplicaStatusStore } from "../extensions/sources.js";
 import { syncPackage } from "../extensions/sync.js";
 import { AccountsService } from "../identity/accounts.js";
+import { insecurePublicUrlWarning } from "../identity/cookies.js";
 import { waitWithin } from "../infra/close-within.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { ReplicaPresence } from "../infra/presence/replica-presence.js";
 import { KERNEL_BUS, KERNEL_LOGGER, KERNEL_POOL, REDIS } from "../infra/tokens.js";
 import { KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA } from "../kernel.js";
 import { GatewayRole } from "../roles/gateway-role.js";
 import { WorkerRole } from "../roles/worker-role.js";
 import { UsageReporter } from "../runtime/usage-report.js";
 import { sandboxConfigWarnings } from "../sandbox/sandbox.service.js";
+import { warnLegacyToolKeys } from "../tools/legacy-data.js";
 import { KERNEL_APP_OPTIONS } from "./tokens.js";
 /**
  * The stop phase budgets. Each phase waits `min(its budget, what is left of the total)`, where the
@@ -60,6 +63,8 @@ export const STOP_BUDGET_MS = {
 };
 /** 停机时留给渠道长连接交还租约的最少时间（与 runs 阶段并行开始，runs 用尽预算时仍保底）。 */
 const CHANNELS_STOP_MIN_MS = 2_000;
+/** The time the device connections get to close and hand their leases back. */
+const DEVICES_STOP_MS = 2_000;
 /** runs 阶段里留给强制关闭 worker 的余量（预算的其余部分用于等运行到达步骤边界）。 */
 const RUNS_FORCE_CLOSE_MS = 500;
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
@@ -100,6 +105,7 @@ let KernelLifecycle = class KernelLifecycle {
     titles;
     channelJobs;
     channelOutbound;
+    presence;
     worker;
     gateway;
     /** The startup config (hot fields are read through the config service). */
@@ -114,11 +120,15 @@ let KernelLifecycle = class KernelLifecycle {
     unwatchConfig;
     /** What the first bootstrap pass did, carried into the second one. */
     bootstrapCarry;
+    /** The packages the first bootstrap pass obtained, so the second downloads nothing again. */
+    bootstrapPackages;
     constructor(accounts, configService, log, options, 
     // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
     pool, redis, kdb, shutdown, host, registry, installs, blobs, extensionLifecycle, replicaStatus, bootstrap, marketplaces, pluginImport, bus, 
     // the producers closed on every role (their consumers are the worker role's)
     usageReport, titles, channelJobs, channelOutbound, 
+    // this process's presence beat, on every role (admin overview spec §5.1)
+    presence, 
     // The role modules' parts: a role module is imported only when `roles` names it, so each is
     // present exactly when its role is (checked at the start)
     worker, gateway) {
@@ -144,6 +154,7 @@ let KernelLifecycle = class KernelLifecycle {
         this.titles = titles;
         this.channelJobs = channelJobs;
         this.channelOutbound = channelOutbound;
+        this.presence = presence;
         this.worker = worker;
         this.gateway = gateway;
         this.config = configService.get();
@@ -193,6 +204,10 @@ let KernelLifecycle = class KernelLifecycle {
         // In flight for the stop: aborted when the shutdown begins, which then waits for its session to end
         await this.shutdown.trackInFlight(migrate(config.db.url, { schema: KERNEL_SCHEMA, dir: KERNEL_MIGRATIONS_DIR }, { connectTimeoutMs: config.db.connectTimeoutMs, signal: this.shutdown.signal }));
         this.checkpoint();
+        // Rows still holding a release-candidate tool key that migration 0063 could not map: one
+        // read-only count, a WARN when there are any (tool naming spec §8.2); never blocks the start
+        await warnLegacyToolKeys(this.kdb.db, this.log).catch((e) => this.log.warn("tools.legacy_key_count_failed", { error: errMsg(e) }));
+        this.checkpoint();
         // official 清单来源按配置同步（幂等；每个副本启动时都做）
         await this.marketplaces.syncOfficialFromConfig();
         // The bootstrap plugins (spec §7), once per manifest across replicas (the Redis lock
@@ -232,7 +247,7 @@ let KernelLifecycle = class KernelLifecycle {
             .list("sandbox")
             .find((x) => x.capability === SANDBOX_EXTENSION_POINT);
         if (sandboxEntry !== undefined) {
-            for (const w of sandboxConfigWarnings(cfg(), sandboxEntry.plugin, sandboxEntry.impl)) {
+            for (const w of sandboxConfigWarnings(cfg(), sandboxEntry.plugin)) {
                 this.log[w.level](w.message);
             }
         }
@@ -259,6 +274,12 @@ let KernelLifecycle = class KernelLifecycle {
             // 热更新：重新校验；只应用 hot 字段，其余变化 warn 并列出需重启的键；校验失败保持原配置
             this.unwatchConfig = opts.source.watch((raw) => this.configService.apply(raw), (err) => this.log.error("config watch error", { error: err.message }));
         }
+        // Last: the process says it is alive (in its roles) only once its start went through
+        this.presence.start({
+            replicaId: this.replicaStatus.replicaId,
+            channelsHeld: () => gateway?.channelsHeld() ?? 0,
+            devicesConnected: () => gateway?.devicesConnected() ?? 0,
+        });
     }
     /**
      * Listens on `port` (0.0.0.0; every role listens: worker-only serves only `/healthz` and
@@ -272,6 +293,9 @@ let KernelLifecycle = class KernelLifecycle {
         this.listening = await this.shutdown.trackInFlight(this.http.listen(port));
         this.checkpoint();
         this.log.info("kernel started", { roles: this.config.roles, port: this.listening });
+        const insecure = insecurePublicUrlWarning(this.config);
+        if (insecure !== null)
+            this.log.warn(insecure);
         await this.warnIfSetupPending();
         return this.listening;
     }
@@ -281,7 +305,9 @@ let KernelLifecycle = class KernelLifecycle {
      * kernel never serves without a required plugin. A failed optional entry is logged and returns
      * true: the start runs the step once more after the extensions loaded (a declarative entry's
      * catalog files need the object store, which on a fresh deployment is itself a bootstrap plugin),
-     * and the next start tries again while it stays incomplete.
+     * and the next start tries again while it stays incomplete. The first pass skips the `builtin`
+     * entries (they may ship skills and templates, which need the object store) and returns true for
+     * them too; the final pass imports them, and one that fails is logged like an optional entry.
      */
     async runBootstrap(dir, final = false) {
         const manifest = this.options.bootstrapManifest ?? (await readBootstrapManifest());
@@ -296,27 +322,35 @@ let KernelLifecycle = class KernelLifecycle {
                 ...(dir !== undefined && { dir }),
                 signal: this.shutdown.signal,
                 ...(this.bootstrapCarry !== undefined && { carry: this.bootstrapCarry }),
+                ...(this.bootstrapPackages !== undefined && { packages: this.bootstrapPackages }),
+                deferBuiltin: !final,
             });
             return false;
         }
         catch (e) {
             if (e instanceof BootstrapFailedError && !e.requiredFailed) {
                 this.bootstrapCarry = e.results;
-                if (final) {
-                    this.log.error("bootstrap: optional plugins could not be installed; retried on the next start", { failures: e.failures });
+                this.bootstrapPackages = e.packages;
+                if (e.failures.length === 0) {
+                    this.log.info("bootstrap: builtin plugins are installed once the extensions have loaded", {
+                        deferred: e.deferred,
+                    });
+                }
+                else if (final) {
+                    this.log.error("bootstrap: optional or builtin plugins could not be installed; retried on the next start", { failures: e.failures });
                 }
                 else {
-                    this.log.warn("bootstrap: optional plugins could not be installed yet; retried once the extensions have loaded", { failures: e.failures });
+                    this.log.warn("bootstrap: optional or builtin plugins could not be installed yet; retried once the extensions have loaded", { failures: e.failures });
                 }
                 return true;
             }
             throw e;
         }
     }
-    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    /** 部署尚无活跃超级管理员时提示去初始化；查询失败只记日志，不影响启动。 */
     async warnIfSetupPending() {
         try {
-            if ((await this.accounts.countEnterpriseAdmins()) === 0) {
+            if ((await this.accounts.countSuperAdmins()) === 0) {
                 this.log.warn("deployment is not set up; open the setup wizard or run `capybara admin create`");
             }
         }
@@ -368,6 +402,8 @@ let KernelLifecycle = class KernelLifecycle {
         // Extension requests in progress (SSE and other long requests end on req.signal) are aborted
         // first, otherwise they would use up the http phase
         this.httpApp?.abortPluginRequests();
+        // Leave the replica presence first: the admin console stops counting this process at once
+        await within("presence", this.presence.stop(), 1_000);
         // Scheduled jobs (worker role): no new tick, the runs in progress get the stop signal; awaited
         // in the runs phase (before the extension host closes: a job may call an extension)
         const { worker, gateway } = this;
@@ -378,6 +414,9 @@ let KernelLifecycle = class KernelLifecycle {
         this.unwatchConfig = undefined;
         gateway?.unwatch();
         await within("webhooks-unsubscribe", (gateway?.unsubscribe() ?? Promise.resolve()).catch(() => { }), 1_000);
+        // Device connections: closed (1001) and their leases handed back before the HTTP server
+        // closes, so the machines reconnect to another gateway replica at once
+        await within("devices", gateway?.stopDevices() ?? Promise.resolve(), DEVICES_STOP_MS);
         // 不再接 reconcile（进行中的那次由宿主关闭收尾）
         await within("plugin-lifecycle", this.extensionLifecycle.stop(), 1_000);
         // http 阶段：等 listen 与关闭 HTTP 共用一个截止时间；listen 卡满预算时关闭只剩 0ms，直接强制断开
@@ -443,9 +482,10 @@ KernelLifecycle = __decorate([
     __param(19, Inject(TitleQueue)),
     __param(20, Inject(ChannelJobs)),
     __param(21, Inject(ChannelOutbound)),
-    __param(22, Optional()),
-    __param(22, Inject(WorkerRole)),
+    __param(22, Inject(ReplicaPresence)),
     __param(23, Optional()),
-    __param(23, Inject(GatewayRole))
+    __param(23, Inject(WorkerRole)),
+    __param(24, Optional()),
+    __param(24, Inject(GatewayRole))
 ], KernelLifecycle);
 export { KernelLifecycle };

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

@@ -0,0 +1,42 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { type DeviceAuthorization, DeviceAuthService, type DeviceGrant, type DeviceMachineInfo } from "./device-auth.js";
+import { type DeviceAuthorizeBody, type DeviceConfirmBody, type DeviceTokenBody, type DeviceUserCodeBody, type DeviceUserCodeParams } from "./dto.js";
+/**
+ * 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, deviceId, connectUrl,
+ *   reconnectGraceSeconds, maxFrameBytes }` once, else `device_sign_in.authorization_pending` / `device_sign_in.slow_down` /
+ *   `device_sign_in.denied` / `device_sign_in.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, deviceId | name }` → `{ deviceId }`
+ *   (`device_sign_in.expired` / `device_sign_in.unavailable` when the credential could not be handed over: the
+ *   machine is revoked again and the person runs login again);
+ * - `POST /deny { userCode }` → 204.
+ */
+export declare class DeviceAuthController {
+    private readonly auth;
+    private readonly throttler;
+    constructor(auth: DeviceAuthService, throttler: CredentialThrottler);
+    authorize(body: z.infer<typeof DeviceAuthorizeBody>): Promise<DeviceAuthorization>;
+    token(body: z.infer<typeof DeviceTokenBody>): Promise<DeviceGrant>;
+    pending(principal: Principal, params: z.infer<typeof DeviceUserCodeParams>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        machine: DeviceMachineInfo;
+        expiresAt: string;
+    }>;
+    confirm(principal: Principal, body: z.infer<typeof DeviceConfirmBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        deviceId: string;
+    }>;
+    deny(principal: Principal, body: z.infer<typeof DeviceUserCodeBody>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /** Runs `fn` as one counted try of a user code; a success gives the try back. */
+    private counted;
+}

package/dist/local-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, deviceId, connectUrl,
+ *   reconnectGraceSeconds, maxFrameBytes }` once, else `device_sign_in.authorization_pending` / `device_sign_in.slow_down` /
+ *   `device_sign_in.denied` / `device_sign_in.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, deviceId | name }` → `{ deviceId }`
+ *   (`device_sign_in.expired` / `device_sign_in.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/local-devices/device-auth.d.ts

@@ -0,0 +1,119 @@
+import type { Redis } from "ioredis";
+import { DevicesService } from "../devices/devices.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>/devices/link`. */
+export declare const DEVICE_PAGE_PATH = "/devices/link";
+/** 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;
+    deviceId: 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;
+    /** `devices.local.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
+ * (`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.
+ */
+export declare class DeviceAuthService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly redis;
+    private readonly config;
+    private readonly devices;
+    private readonly machines;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, config: Pick<KernelConfigService, "get">, devices: Pick<DevicesService, "createLocal">, 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_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).
+     */
+    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 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.
+     */
+    confirm(principal: UserPrincipal, input: {
+        userCode: string;
+        orgId: string;
+        deviceId?: string | undefined;
+        name?: string | undefined;
+    }): Promise<{
+        deviceId: 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_sign_in.expired` / `device_sign_in.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_sign_in.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_sign_in.code_invalid`. */
+    private lookup;
+    private transition;
+    /** `http.publicUrl` without trailing slashes; unset → `device.unavailable`. */
+    private publicUrl;
+    /** The machine's WebSocket URL: the public URL with `ws` / `wss` and `/device/connect`. */
+    private connectUrl;
+}
+export {};