@capybara-hq/kernel 0.1.0-rc.20 → 0.1.0-rc.22

package/dist/devices/devices.service.d.ts

@@ -1,14 +1,17 @@
-import type { LocalizedName, SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { type DeviceFeature, type DeviceLocalPolicySummary, type LocalizedName, type SandboxLimits, type SandboxTier } from "@capybara-hq/plugin-sdk";
 import { ExtensionDisplayNames } from "../extensions/display-name.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 { LockService } from "../infra/lock/lock.service.js";
+import { DevicePolicyService } from "../local-devices/device-policy.service.js";
 import { MachinesService } from "../local-devices/machines.js";
 import type { KernelLogger } from "../log.js";
+import type { DeviceSandboxLevel } from "../runtime/context/device-paths.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { SandboxProviders } from "../sandbox/providers.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
+import { type EffectiveSandboxPolicy } from "../sandbox/tiers.js";
 import { DeviceAccess } from "./access.js";
 /** A device as its owner sees it (`GET /orgs/:orgId/devices`). */
 export interface DeviceView {
@@ -42,6 +45,17 @@ export interface DeviceView {
     online: boolean | null;
     /** A local device's connected machine (its unrevoked one); null for cloud or none. */
     machine: DeviceMachineView | null;
+    /**
+     * A local device's network facts as its connected machine last reported them (network
+     * ask-to-allow spec §5.4): the program's features and its local policy summary (null when
+     * unknown). null for a cloud device or a local one without a connected machine.
+     */
+    network: {
+        features: string[];
+        policy: DeviceLocalPolicySummary | null;
+    } | null;
+    /** Its sandbox level (sandbox dev tiers spec §4, §11.1). */
+    sandbox: DeviceSandboxView;
     sessionIsolation: boolean;
     /** Its file system is gone at the provider; reset the files to use it again. */
     filesLost: boolean;
@@ -49,10 +63,92 @@ export interface DeviceView {
         status: "running" | "suspended";
         lastUsedAt: string;
     } | null;
-    /** The org's effective sandbox limits (phase 1 devices use them unchanged, spec §8.4). */
+    /**
+     * The sandbox limits of its effective tier (sandbox dev tiers spec §4.2): what a cloud
+     * instance is created with; for a local device the network of the org's default tier.
+     */
     limits: SandboxLimits;
     createdAt: string;
 }
+/**
+ * A device's sandbox level as its owner sees it (sandbox dev tiers spec §4, §11.1).
+ */
+export interface DeviceSandboxView {
+    /**
+     * The tier the owner chose: a cloud device's stored one, a local device's as its machine last
+     * reported it; null follows the org's default.
+     */
+    tier: SandboxTier | null;
+    /**
+     * The tier its commands run at: min(chosen ?? the org's default, ceiling); `strict` for a local
+     * device whose program lacks the `tiers` feature (it runs as before tiers).
+     */
+    effectiveTier: SandboxTier;
+    /** The highest tier the device may reach: min(the org's max, the platform's max). */
+    ceiling: SandboxTier;
+    /** Which ceiling lowered the chosen tier; null when none did. */
+    cappedBy: "org" | "platform" | null;
+    /** The org's default tier for devices that choose none (at most {@link ceiling}). */
+    defaultTier: SandboxTier;
+    /** The org and the platform let a local device run without a sandbox (its ceiling is `open`). */
+    allowUnsandboxed: boolean;
+    /** `none`: a local device runs its commands without a sandbox (its owner set it locally). */
+    isolation: "sandbox" | "none";
+    /**
+     * A cloud device's instance runs another tier or network than {@link effectiveTier}: its next
+     * use updates or recreates it, files kept (「下次使用时生效，文件保留」).
+     */
+    pendingNextUse: boolean;
+    /**
+     * A cloud device's new tier waits for a file reset: its provider applies limits only when the
+     * file system is made (`limitsApplyAt: "fileSystem"`) and cannot update them.
+     */
+    pendingFilesReset: boolean;
+    /** Its last {@link RECENT_POLICY_CHANGES} sandbox changes, newest first (§10.4). */
+    recent: DeviceSandboxChangeView[];
+}
+/** How many recent sandbox changes a device view lists. */
+export declare const RECENT_POLICY_CHANGES = 10;
+/**
+ * One sandbox change of a device, as its owner sees it on the device page (§10.4):
+ * - `policy` (`device.policy_changed`): a local policy change sent to the machine;
+ * - `tier` (`device.tier_changed`): a cloud device's tier set by its owner;
+ * - `isolation` (`device.isolation_reported`): the machine reported running without a sandbox,
+ *   or with one again.
+ */
+export interface DeviceSandboxChangeView {
+    at: string;
+    kind: "policy" | "tier" | "isolation";
+    /** Hosts added to / removed from the local allowlist (`policy` only; else empty). */
+    add: string[];
+    remove: string[];
+    /** The tier set (`to: null`: follow the org's default); null when the tier did not change. */
+    tier: {
+        to: SandboxTier | null;
+    } | null;
+    /** The isolation set or reported; null when it did not change. */
+    isolation: "sandbox" | "none" | null;
+    /** The deciding account's display name (null when the account is gone). */
+    by: string | null;
+    /** `device`: reported by the machine itself (`isolation`). */
+    via: "web" | "im" | "device";
+    /** The machine answered with the policy as written (false: the answer never came). */
+    confirmed: boolean;
+}
+/** A change of a local device's policy by its owner (`POST /devices/:id/policy`). */
+export interface DevicePolicyChange {
+    add?: string[] | undefined;
+    remove?: string[] | undefined;
+    /** null: follow the org's default. */
+    tier?: SandboxTier | null | undefined;
+    isolation?: "sandbox" | undefined;
+}
+/** What `PATCH /devices/:id` changes. */
+export interface DevicePatch {
+    name?: string;
+    /** A cloud device's tier; null follows the org's default. */
+    tier?: SandboxTier | null;
+}
 /** The machine connected to a local device, as its owner sees it. */
 export interface DeviceMachineView {
     id: string;
@@ -92,9 +188,10 @@ export declare class DevicesService {
     /** Reads the device relay's lease (`online`). */
     private readonly locks;
     private readonly machines;
-    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "cloud" | "forName">, sandbox: Pick<SandboxService, "orgLimits">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<DeviceAccess, "usable">, displayNames: Pick<ExtensionDisplayNames, "many">, log: Pick<KernelLogger, "warn">, 
+    private readonly policies;
+    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "cloud" | "forName">, sandbox: Pick<SandboxService, "deviceLimits" | "limitsState">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<DeviceAccess, "usable">, displayNames: Pick<ExtensionDisplayNames, "many">, log: Pick<KernelLogger, "warn">, 
     /** Reads the device relay's lease (`online`). */
-    locks: Pick<LockService, "holderOf">, machines: Pick<MachinesService, "revoke" | "revokeActive">);
+    locks: Pick<LockService, "holderOf">, machines: Pick<MachinesService, "revoke" | "revokeActive">, policies: Pick<DevicePolicyService, "apply" | "summary">);
     /**
      * The person's live devices in the org, the default first, then by creation. With a
      * current sandbox provider the default device is created first if missing (its first need,
@@ -149,6 +246,34 @@ export declare class DevicesService {
      */
     rename(orgId: string, accountId: string, id: string, name: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<DeviceView>;
     private renameIn;
+    /**
+     * `PATCH /devices/:id` (sandbox dev tiers spec §7.2): renames one of the person's live devices
+     * ({@link rename}) and sets a cloud device's sandbox tier, in one transaction. The tier: null
+     * follows the org's default; above the device's ceiling (the org's or the platform's max) →
+     * `device.tier_not_allowed`; a local device → `device.tier_on_device` (its tier is its
+     * machine's, changed with {@link changePolicy}). A changed tier is audited `device.tier_changed`
+     * (`from` / `to`); the device's next use applies it (the instance is updated, or recreated on
+     * the kept files). Callers make sure only a person in a session sets the tier.
+     */
+    update(orgId: string, accountId: string, id: string, patch: DevicePatch, actorTokenId?: string): Promise<DeviceView>;
+    private updateIn;
+    /** The org's sandbox policy for a device choosing `tier` (null: the org's default). */
+    private policyFor;
+    /**
+     * The sandbox level a sandbox call in the device runs at now, for the model (`device_paths`,
+     * spec §11.5): see {@link sandboxStateOf}, plus
+     * - `network: "none"` when the org's or the platform's sandbox network is off;
+     * - a cloud device whose new limits wait for a file reset: the tier and network its instance
+     *   still runs with (`limitsState(...).applied`; open with its network on when unrecorded);
+     * - a local device: its machine's localhost and unix socket facts; in a scheduled run without
+     *   a person (`runId`, {@link unattendedTierOf}) and without the task's `tier:open` grant its
+     *   tier is capped at `dev`, as the exec args cap it;
+     * - `unattended` in such a run: nobody can approve a domain.
+     * Null when the device is not a live device of the org.
+     */
+    sandboxLevel(orgId: string, deviceId: string, runId?: string): Promise<DeviceSandboxLevel | null>;
+    /** Renames the device locked by {@link lockOwn} (`before`); see {@link rename}. */
+    private renameLocked;
     /**
      * Deletes one of the person's live devices: soft delete, its IM default row cleared, and
      * after the commit a `sandbox-destroy-for` job (the worker waits for running commands, then
@@ -163,6 +288,23 @@ export declare class DevicesService {
      * again); see {@link MachinesService.revoke}.
      */
     revokeMachine(orgId: string, accountId: string, id: string, actorTokenId?: string): Promise<void>;
+    /**
+     * The owner changes one of their own devices' local policy (network ask-to-allow spec §7, §13
+     * Q6; sandbox dev tiers spec §7.3): sent to the machine with the `policy` op, which is the
+     * authority and answers with the policy as written. Anyone but the owner gets
+     * `device.not_found`. A `tier` above the device's ceiling → `device.tier_not_allowed`. A widening
+     * change (`add`; a `tier` that may raise the machine's, judged as the machine judges it) is
+     * refused up front with `device.policy_refused` when the machine last reported
+     * `remoteGrants: "off"` (otherwise the machine decides); narrowing is always sent, and
+     * `isolation` is only ever `sandbox`. The machine offline → `device.offline`; a cloud device or a
+     * program without the `policyOp` feature → `device.policy_unsupported`; the machine's refusal →
+     * `device.policy_refused` with its message. Callers are human sessions only (no personal access
+     * token, no service token, no Platform op).
+     */
+    changePolicy(orgId: string, account: {
+        id: string;
+        displayName: string;
+    }, id: string, change: DevicePolicyChange): Promise<DeviceLocalPolicySummary>;
     /**
      * Starts one of the person's devices over with empty files (after
      * `device.files_lost`): records the request (audit), then, after the commit, enqueues the
@@ -238,6 +380,12 @@ export declare class DevicesService {
     private stranded;
     /** The person's live devices (or the one `id`) as views. */
     private views;
+    /**
+     * The last {@link RECENT_POLICY_CHANGES} sandbox changes of each device in the org (audit rows
+     * `device.policy_changed`, `device.tier_changed`, `device.isolation_reported`), newest first,
+     * with the deciding account's display name.
+     */
+    private recentSandboxChanges;
     /**
      * Serializes the person's device writes in the org: the org row (`FOR SHARE`), then their
      * membership row (`FOR NO KEY UPDATE`, or `FOR SHARE` with `mode` share: enough to keep the
@@ -249,3 +397,27 @@ export declare class DevicesService {
     private lockOwn;
     private assertNameFree;
 }
+/** What {@link sandboxStateOf} reads of a device. */
+export interface DeviceSandboxFacts {
+    source: "cloud" | "local";
+    /** A cloud device's stored tier (ignored for a local device). */
+    tier: SandboxTier | null;
+    /** A local device's connected machine's features ([] when none is connected). */
+    features: readonly DeviceFeature[];
+    /** A local device's policy summary as last reported (null when unknown or none connected). */
+    policy: DeviceLocalPolicySummary | null;
+}
+/**
+ * A device's sandbox level (spec §4.2, §4.4): its chosen tier (a cloud device's stored one, a
+ * local device's reported one) under the org's policy (`policyOf`). A local device whose program
+ * lacks the `tiers` feature runs `strict` (it ignores the tier the kernel sends); it runs without
+ * a sandbox only when it reports `isolation: "none"` and its effective tier is `open` (the device
+ * keeps the sandbox at any lower tier).
+ */
+export declare function sandboxStateOf(policyOf: (tier: SandboxTier | null) => EffectiveSandboxPolicy, d: DeviceSandboxFacts): Omit<DeviceSandboxView, "pendingNextUse" | "pendingFilesReset" | "recent">;
+/**
+ * Whether setting a local device's tier to `next` (null: follow the org's default) may raise it,
+ * not knowing the org's default at the machine: a tier above the reported one, any tier but
+ * `strict` when it reports none, and following the default when it reports `strict` or `dev`.
+ */
+export declare function tierWidens(reported: SandboxTier | undefined, next: SandboxTier | null | undefined): boolean;