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

package/dist/devices/devices.service.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
+import { minTier, tierAtMost, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
@@ -20,12 +21,19 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { DevicePolicyService } from "../local-devices/device-policy.service.js";
 import { deviceLeaseKey } from "../local-devices/keys.js";
 import { MachinesService } from "../local-devices/machines.js";
+import { deviceFeaturesOf, localPolicyOf } from "../local-devices/policy-summary.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { isInternalProvider, LOCAL_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
 import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { effectiveSandboxPolicy } from "../sandbox/tiers.js";
+import { unattendedTierOf } from "../schedules/unattended.js";
 import { DeviceAccess, demotedProvider, deviceProvider, deviceUnavailable, inUseForDefault, } from "./access.js";
+/** How many recent sandbox changes a device view lists. */
+export const RECENT_POLICY_CHANGES = 10;
 const isUniqueViolation = (e, constraint) => typeof e === "object" &&
     e !== null &&
     e.code === "23505" &&
@@ -50,9 +58,10 @@ let DevicesService = class DevicesService {
     log;
     locks;
     machines;
+    policies;
     constructor(db, txHost, config, providers, sandbox, sandboxJobs, access, displayNames, log, 
     /** Reads the device relay's lease (`online`). */
-    locks, machines) {
+    locks, machines, policies) {
         this.db = db;
         this.txHost = txHost;
         this.config = config;
@@ -64,6 +73,7 @@ let DevicesService = class DevicesService {
         this.log = log;
         this.locks = locks;
         this.machines = machines;
+        this.policies = policies;
     }
     /**
      * The person's live devices in the org, the default first, then by creation. With a
@@ -236,6 +246,115 @@ let DevicesService = class DevicesService {
     }
     async renameIn(orgId, accountId, id, name, actorTokenId, auditDetail) {
         const before = await this.lockOwn(orgId, accountId, id);
+        await this.renameLocked(orgId, accountId, id, before, name, actorTokenId, auditDetail);
+    }
+    /**
+     * `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.
+     */
+    async update(orgId, accountId, id, patch, actorTokenId) {
+        await this.updateIn(orgId, accountId, id, patch, actorTokenId);
+        return this.get(orgId, accountId, id);
+    }
+    async updateIn(orgId, accountId, id, patch, actorTokenId) {
+        const before = await this.lockOwn(orgId, accountId, id);
+        if (patch.tier !== undefined) {
+            if (before.source !== "cloud") {
+                throw new ApiError("device.tier_on_device", "This device's sandbox level is kept on its connected machine: change it from the device page (sent to the machine) or run capybara-device policy set tier <strict|dev|open|default> there.");
+            }
+            const policy = await this.policyFor(orgId, patch.tier);
+            if (patch.tier !== null && !tierAtMost(patch.tier, policy.ceiling)) {
+                throw tierNotAllowed(patch.tier, policy);
+            }
+            if (patch.tier !== before.tier) {
+                await this.db
+                    .updateTable("devices")
+                    .set({ tier: patch.tier, updated_at: sql `now()` })
+                    .where("id", "=", id)
+                    .execute();
+                await audit(this.db.db, {
+                    actorAccountId: accountId,
+                    ...(actorTokenId !== undefined && { actorTokenId }),
+                    orgId,
+                    action: "device.tier_changed",
+                    target: id,
+                    detail: { from: before.tier, to: patch.tier },
+                });
+            }
+        }
+        if (patch.name !== undefined) {
+            await this.renameLocked(orgId, accountId, id, before, patch.name, actorTokenId, undefined);
+        }
+    }
+    /** The org's sandbox policy for a device choosing `tier` (null: the org's default). */
+    async policyFor(orgId, tier) {
+        return effectiveSandboxPolicy(this.config.get().sandbox, await readOrgSettings(this.db.db, orgId), tier);
+    }
+    /**
+     * 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.
+     */
+    async sandboxLevel(orgId, deviceId, runId) {
+        const row = await this.db
+            .selectFrom("devices as e")
+            .leftJoin("device_machines as m", (j) => j.onRef("m.device_id", "=", "e.id").on("m.revoked_at", "is", null))
+            .select(["e.source", "e.tier", "m.features", "m.local_policy"])
+            .where("e.id", "=", deviceId)
+            .where("e.org_id", "=", orgId)
+            .where("e.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (row === undefined)
+            return null;
+        const [settings, unattended] = await Promise.all([
+            readOrgSettings(this.db.db, orgId),
+            runId === undefined ? null : unattendedTierOf(this.db.db, runId, deviceId),
+        ]);
+        const policyOf = (tier) => effectiveSandboxPolicy(this.config.get().sandbox, settings, tier);
+        const summary = localPolicyOf(row.local_policy);
+        const s = sandboxStateOf(policyOf, {
+            source: row.source,
+            tier: row.tier,
+            features: deviceFeaturesOf(row.features),
+            policy: summary,
+        });
+        let tier = s.effectiveTier;
+        let networkOff = policyOf(s.tier).base.egress === "none";
+        if (row.source === "cloud") {
+            const state = await this.sandbox.limitsState({ orgId, deviceId }, { policy: policyOf(row.tier) });
+            if (state.pendingFilesReset) {
+                // an unknown record (an instance made before records) may be wider: it counts as open
+                // with its network on, as the unattended gate counts it (`mayRunOpen`)
+                tier = state.applied?.tier ?? "open";
+                networkOff = state.applied?.egress === "none";
+            }
+        }
+        else if (unattended !== null && !unattended.openGranted) {
+            tier = minTier(tier, "dev");
+        }
+        return {
+            tier,
+            isolation: tier === "open" ? s.isolation : "sandbox",
+            ...(networkOff && { network: "none" }),
+            ...(row.source === "local" &&
+                summary !== null && { localhost: summary.localhost, unixSockets: summary.unixSockets }),
+            ...(unattended !== null && { unattended: true }),
+        };
+    }
+    /** Renames the device locked by {@link lockOwn} (`before`); see {@link rename}. */
+    async renameLocked(orgId, accountId, id, before, name, actorTokenId, auditDetail) {
         if (before.name === name)
             return;
         // the same name in another case is this device's own: the index allows it
@@ -310,6 +429,55 @@ let DevicesService = class DevicesService {
     async revokeMachine(orgId, accountId, id, actorTokenId) {
         await this.machines.revoke(orgId, accountId, id, actorTokenId);
     }
+    /**
+     * 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).
+     */
+    async changePolicy(orgId, account, id, change) {
+        await this.access.usable(orgId, account.id, id);
+        if (change.tier !== undefined && change.tier !== null) {
+            const policy = await this.policyFor(orgId, change.tier);
+            if (!tierAtMost(change.tier, policy.ceiling))
+                throw tierNotAllowed(change.tier, policy);
+        }
+        const summary = await this.policies.summary(id);
+        const known = summary?.policy ?? null;
+        const widens = (change.add?.length ?? 0) > 0 || (known !== null && tierWidens(known.tier, change.tier));
+        // only a known "off" is refused here; an unknown summary, a machine that cannot take the op
+        // or none at all are left to apply (the machine decides, or unsupported / offline)
+        const canApply = summary?.features.includes("policyOp") === true;
+        if (widens && canApply && known?.remoteGrants === "off") {
+            throw new ApiError("device.policy_refused", remoteGrantsOffMessage(change));
+        }
+        const out = await this.policies.apply({
+            orgId,
+            deviceId: id,
+            change: {
+                ...(change.add !== undefined && { add: change.add }),
+                ...(change.remove !== undefined && { remove: change.remove }),
+                ...(change.tier !== undefined && { tier: change.tier }),
+                ...(change.isolation !== undefined && { isolation: change.isolation }),
+            },
+            source: { accountId: account.id, accountName: account.displayName, via: "web" },
+        });
+        if (out.applied)
+            return out.policy;
+        if (out.reason === "offline")
+            throw new ApiError("device.offline", out.message);
+        if (out.reason === "unsupported") {
+            throw new ApiError("device.policy_unsupported", out.message);
+        }
+        throw new ApiError("device.policy_refused", out.message);
+    }
     /**
      * 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
@@ -590,6 +758,7 @@ let DevicesService = class DevicesService {
             "e.source",
             "e.provider",
             "e.demoted_from_provider",
+            "e.tier",
             "e.created_at",
             "m.id as machine_id",
             "m.name as machine_name",
@@ -598,6 +767,8 @@ let DevicesService = class DevicesService {
             "m.program_version as machine_program_version",
             "m.last_seen_at as machine_last_seen_at",
             "m.session_isolation as machine_session_isolation",
+            "m.features as machine_features",
+            "m.local_policy as machine_local_policy",
             "i.provider as instance_provider",
             "i.fs_status",
             "i.handle",
@@ -636,10 +807,23 @@ let DevicesService = class DevicesService {
         const demotedProviders = [
             ...new Set(rows.flatMap((r) => (demoted.get(r.id) ? [demoted.get(r.id)] : []))),
         ];
-        const [limits, names] = await Promise.all([
-            this.sandbox.orgLimits(orgId),
+        const [names, recent, settings] = await Promise.all([
             this.displayNames.many(demotedProviders),
+            this.recentSandboxChanges(orgId, rows.map((r) => r.id)),
+            readOrgSettings(this.db.db, orgId),
         ]);
+        const policyOf = (tier) => effectiveSandboxPolicy(this.config.get().sandbox, settings, tier);
+        // each device's limits (a cloud device's own tier) and its instance's pending change
+        const perDevice = new Map(await Promise.all(rows.map(async (r) => {
+            const policy = policyOf(r.source === "cloud" ? r.tier : null);
+            const [limits, state] = await Promise.all([
+                this.sandbox.deviceLimits({ orgId, deviceId: r.id }, { policy }),
+                r.source === "cloud"
+                    ? this.sandbox.limitsState({ orgId, deviceId: r.id }, { policy })
+                    : { pendingNextUse: false, pendingFilesReset: false },
+            ]);
+            return [r.id, { limits, state }];
+        })));
         const current = this.providers.cloud()?.plugin;
         // a local device is online while a replica holds its machine's connection lease
         const online = new Map(await Promise.all(rows
@@ -677,6 +861,23 @@ let DevicesService = class DevicesService {
                         lastSeenAt: r.machine_last_seen_at?.toISOString() ?? null,
                     }
                     : null,
+                network: r.source === "local" && r.machine_id !== null
+                    ? {
+                        features: deviceFeaturesOf(r.machine_features),
+                        policy: localPolicyOf(r.machine_local_policy),
+                    }
+                    : null,
+                sandbox: {
+                    ...sandboxStateOf(policyOf, {
+                        source: r.source,
+                        tier: r.tier,
+                        features: r.machine_id === null ? [] : deviceFeaturesOf(r.machine_features),
+                        policy: r.machine_id === null ? null : localPolicyOf(r.machine_local_policy),
+                    }),
+                    pendingNextUse: perDevice.get(r.id)?.state.pendingNextUse ?? false,
+                    pendingFilesReset: perDevice.get(r.id)?.state.pendingFilesReset ?? false,
+                    recent: recent.get(r.id) ?? [],
+                },
                 // a local device's machine decides it; cloud devices have none in phase 2
                 sessionIsolation: r.machine_session_isolation ?? false,
                 filesLost: r.fs_status === "lost",
@@ -686,11 +887,49 @@ let DevicesService = class DevicesService {
                         lastUsedAt: r.last_used_at.toISOString(),
                     }
                     : null,
-                limits: { ...limits, allowHosts: [...limits.allowHosts] },
+                limits: limitsView(perDevice.get(r.id)?.limits),
                 createdAt: r.created_at.toISOString(),
             };
         });
     }
+    /**
+     * 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.
+     */
+    async recentSandboxChanges(orgId, deviceIds) {
+        const out = new Map();
+        if (deviceIds.length === 0)
+            return out;
+        const ranked = this.db
+            .selectFrom("audit_events as a")
+            .select([
+            "a.target",
+            "a.action",
+            "a.at",
+            "a.detail",
+            "a.actor_account_id",
+            sql `row_number() OVER (PARTITION BY a.target ORDER BY a.at DESC, a.id DESC)`.as("n"),
+        ])
+            .where("a.org_id", "=", orgId)
+            .where("a.action", "in", [...SANDBOX_CHANGE_ACTIONS])
+            .where("a.target", "in", deviceIds);
+        const rows = await this.db
+            .selectFrom(ranked.as("r"))
+            .leftJoin("accounts as ac", "ac.id", "r.actor_account_id")
+            .select(["r.target", "r.action", "r.at", "r.detail", "ac.display_name"])
+            .where("r.n", "<=", RECENT_POLICY_CHANGES)
+            .orderBy("r.at", "desc")
+            .execute();
+        for (const r of rows) {
+            if (r.target === null)
+                continue;
+            const list = out.get(r.target) ?? [];
+            list.push(sandboxChangeOf(r.action, r.at, (r.detail ?? {}), r.display_name ?? null));
+            out.set(r.target, list);
+        }
+        return out;
+    }
     /**
      * 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
@@ -722,7 +961,7 @@ let DevicesService = class DevicesService {
         await this.lockMember(orgId, accountId);
         const row = await this.db
             .selectFrom("devices")
-            .select(["name", "is_default"])
+            .select(["name", "is_default", "source", "tier"])
             .where("id", "=", id)
             .where("org_id", "=", orgId)
             .where("owner_kind", "=", "personal")
@@ -756,6 +995,9 @@ __decorate([
 __decorate([
     Transactional()
 ], DevicesService.prototype, "renameIn", null);
+__decorate([
+    Transactional()
+], DevicesService.prototype, "updateIn", null);
 __decorate([
     Transactional()
 ], DevicesService.prototype, "remove", null);
@@ -777,7 +1019,8 @@ DevicesService = __decorate([
     __param(7, Inject(ExtensionDisplayNames)),
     __param(8, Inject(KERNEL_LOGGER)),
     __param(9, Inject(LockService)),
-    __param(10, Inject(MachinesService))
+    __param(10, Inject(MachinesService)),
+    __param(11, Inject(DevicePolicyService))
 ], DevicesService);
 export { DevicesService };
 /**
@@ -789,3 +1032,95 @@ function refuseDeviceReset(env) {
         throw new ApiError("device.files_on_device", "This device's files are in a directory on its connected machine and cannot be reset from here. To start over, run capybara-device logout, then capybara-device login into this device, on that machine.");
     }
 }
+/** A copy of `l` for a view (its lists not shared). */
+const limitsView = (l) => ({
+    ...l,
+    allowHosts: [...l.allowHosts],
+    devHosts: [...l.devHosts],
+});
+/** The audit actions a device's recent sandbox changes list. */
+const SANDBOX_CHANGE_ACTIONS = [
+    "device.policy_changed",
+    "device.tier_changed",
+    "device.isolation_reported",
+];
+const tierOrNull = (v) => v === "strict" || v === "dev" || v === "open" ? v : null;
+/** One audit row of {@link SANDBOX_CHANGE_ACTIONS} as a {@link DeviceSandboxChangeView}. */
+function sandboxChangeOf(action, at, d, by) {
+    const hosts = (v) => Array.isArray(v) ? v.filter((h) => typeof h === "string") : [];
+    const isolation = d.isolation === "sandbox" || d.isolation === "none" ? d.isolation : null;
+    const base = { at: at.toISOString(), add: [], remove: [], tier: null, isolation: null, by };
+    if (action === "device.tier_changed") {
+        return { ...base, kind: "tier", tier: { to: tierOrNull(d.to) }, via: "web", confirmed: true };
+    }
+    if (action === "device.isolation_reported") {
+        return { ...base, kind: "isolation", isolation, via: "device", confirmed: true };
+    }
+    return {
+        ...base,
+        kind: "policy",
+        add: hosts(d.add),
+        remove: hosts(d.remove),
+        // the key is there only when the change set the tier (null: follow the org's default)
+        tier: "tier" in d ? { to: tierOrNull(d.tier) } : null,
+        isolation,
+        via: d.via === "im" ? "im" : "web",
+        confirmed: d.confirmed === true,
+    };
+}
+/**
+ * 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 function sandboxStateOf(policyOf, d) {
+    const chosen = d.source === "cloud" ? d.tier : (d.policy?.tier ?? null);
+    const p = policyOf(chosen);
+    const tiersKnown = d.source === "cloud" || d.features.includes("tiers");
+    const effectiveTier = tiersKnown ? p.tier : "strict";
+    return {
+        tier: chosen,
+        effectiveTier,
+        ceiling: p.ceiling,
+        cappedBy: tiersKnown ? p.cappedBy : null,
+        defaultTier: p.defaultTier,
+        allowUnsandboxed: p.allowUnsandboxed,
+        isolation: d.source === "local" && d.policy?.isolation === "none" && effectiveTier === "open"
+            ? "none"
+            : "sandbox",
+    };
+}
+/**
+ * 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 function tierWidens(reported, next) {
+    if (next === undefined || next === "strict")
+        return false;
+    if (next === null)
+        return reported !== undefined && reported !== "open";
+    return reported === undefined || !tierAtMost(next, reported);
+}
+/** A tier above the device's ceiling: which ceiling, and the highest tier allowed. */
+function tierNotAllowed(tier, policy) {
+    const platform = policy.cappedBy === "platform";
+    return new ApiError("device.tier_not_allowed", `${platform ? "The platform" : "Your organization"} allows sandbox levels up to ${policy.ceiling}; this device cannot be set to ${tier}.`);
+}
+/**
+ * The refusal of a widening change on a device whose machine reported `remoteGrants: "off"`: the
+ * command to run on the machine instead.
+ */
+function remoteGrantsOffMessage(change) {
+    const local = [
+        ...(change.add !== undefined && change.add.length > 0
+            ? [`capybara-device policy add allowedDomains ${change.add.join(",")}`]
+            : []),
+        ...(change.tier !== undefined
+            ? [`capybara-device policy set tier ${change.tier ?? "default"}`]
+            : []),
+    ];
+    return `This device does not accept widening changes from the deployment; change it on the machine: ${local.join("; ")}`;
+}

package/dist/devices/dto.d.ts

@@ -7,19 +7,72 @@ export declare const DeviceNameBody: z.ZodObject<{
 export declare const DeviceParams: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
+/** A sandbox tier (sandbox dev tiers spec §5). */
+export declare const DeviceTier: z.ZodEnum<{
+    dev: "dev";
+    open: "open";
+    strict: "strict";
+}>;
+/**
+ * `PATCH /devices/:id`: a new name, and for a cloud device its sandbox tier (null = follow the
+ * org's default; sandbox dev tiers spec §7.2). The tier is a person's choice in a web session:
+ * an API token gets `auth.session_required` and the Platform tool leaves the field out.
+ */
+export declare const DevicePatchBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    tier: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
+}, z.core.$strict>;
+/**
+ * `POST /devices/:id/policy` (network ask-to-allow spec §7, sandbox dev tiers spec §7.3): the
+ * device owner's change of the machine's local policy. `add` and a higher `tier` widen it (the
+ * machine accepts them only while its local `remoteGrants` is `owner`); `remove` and a lower
+ * `tier` narrow it. `tier: null` follows the org's default. `isolation` only turns the sandbox
+ * back on: running without one is decided on the machine.
+ */
+export declare const DevicePolicyBody: z.ZodObject<{
+    add: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    remove: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tier: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
+    isolation: z.ZodOptional<z.ZodLiteral<"sandbox">>;
+}, z.core.$strict>;
 declare const DeviceCreateBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strict>>;
 export declare class DeviceCreateBodyDto extends DeviceCreateBodyDto_base {
 }
-declare const DeviceRenameBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    name: z.ZodString;
+declare const DevicePatchBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    tier: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
 }, z.core.$strict>>;
-export declare class DeviceRenameBodyDto extends DeviceRenameBodyDto_base {
+export declare class DevicePatchBodyDto extends DevicePatchBodyDto_base {
 }
 declare const DeviceParamsDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>>;
 export declare class DeviceParamsDto extends DeviceParamsDto_base {
 }
+declare const DevicePolicyBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    add: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    remove: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tier: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
+    isolation: z.ZodOptional<z.ZodLiteral<"sandbox">>;
+}, z.core.$strict>>;
+export declare class DevicePolicyBodyDto extends DevicePolicyBodyDto_base {
+}
 export {};

package/dist/devices/dto.js

@@ -1,12 +1,62 @@
+import { validateAllowHost } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { publicSuffixWildcard } from "./public-suffix.js";
 /** A device's name: trimmed, 1-64 characters (unique per person, case-insensitive). */
 export const DeviceName = z.string().trim().min(1).max(64);
 export const DeviceNameBody = z.object({ name: DeviceName }).strict();
 export const DeviceParams = z.object({ id: z.string().min(1).max(100) });
+/** A sandbox tier (sandbox dev tiers spec §5). */
+export const DeviceTier = z.enum(["strict", "dev", "open"]);
+/**
+ * `PATCH /devices/:id`: a new name, and for a cloud device its sandbox tier (null = follow the
+ * org's default; sandbox dev tiers spec §7.2). The tier is a person's choice in a web session:
+ * an API token gets `auth.session_required` and the Platform tool leaves the field out.
+ */
+export const DevicePatchBody = z
+    .object({ name: DeviceName.optional(), tier: DeviceTier.nullable().optional() })
+    .strict()
+    .refine((b) => b.name !== undefined || b.tier !== undefined, {
+    message: "Give at least one of name or tier",
+});
+/** One host of a device's network allowlist (`validateAllowHost`: lowercase, `*.` allowed). */
+const PolicyHost = z
+    .string()
+    .max(253)
+    .superRefine((h, ctx) => {
+    for (const message of validateAllowHost(h))
+        ctx.addIssue({ code: "custom", message });
+});
+/** A host to add: also no `*.` wildcard over a whole public suffix (`*.com`, `*.co.uk`). */
+const AddHost = PolicyHost.superRefine((h, ctx) => {
+    const tooBroad = publicSuffixWildcard(h);
+    if (tooBroad !== null)
+        ctx.addIssue({ code: "custom", message: tooBroad });
+});
+/**
+ * `POST /devices/:id/policy` (network ask-to-allow spec §7, sandbox dev tiers spec §7.3): the
+ * device owner's change of the machine's local policy. `add` and a higher `tier` widen it (the
+ * machine accepts them only while its local `remoteGrants` is `owner`); `remove` and a lower
+ * `tier` narrow it. `tier: null` follows the org's default. `isolation` only turns the sandbox
+ * back on: running without one is decided on the machine.
+ */
+export const DevicePolicyBody = z
+    .object({
+    add: z.array(AddHost).min(1).max(20).optional(),
+    remove: z.array(PolicyHost).min(1).max(100).optional(),
+    tier: DeviceTier.nullable().optional(),
+    isolation: z.literal("sandbox").optional(),
+})
+    .strict()
+    .refine((b) => b.add !== undefined ||
+    b.remove !== undefined ||
+    b.tier !== undefined ||
+    b.isolation !== undefined, { message: "Give at least one of add, remove, tier or isolation" });
 export class DeviceCreateBodyDto extends createZodDto(DeviceNameBody, "DeviceCreateBody") {
 }
-export class DeviceRenameBodyDto extends createZodDto(DeviceNameBody, "DeviceRenameBody") {
+export class DevicePatchBodyDto extends createZodDto(DevicePatchBody, "DevicePatchBody") {
 }
 export class DeviceParamsDto extends createZodDto(DeviceParams, "DeviceParams") {
 }
+export class DevicePolicyBodyDto extends createZodDto(DevicePolicyBody, "DevicePolicyBody") {
+}

package/dist/devices/public-suffix.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Why a `*.` wildcard is too broad to add from the device page: its remainder is a whole public
+ * suffix (one label such as `com`, or a known multi-label one such as `co.uk`, `github.io`);
+ * null for an exact host or a narrower wildcard.
+ */
+export declare function publicSuffixWildcard(pattern: string): string | null;