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

package/dist/catalog/requests.service.d.ts

@@ -5,13 +5,31 @@ 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 { OrgLock } from "../orgs/org-lock.js";
+import { OrgSettingsService } from "../orgs/settings.service.js";
 import { CatalogService, type MarketplaceImportResult } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
 import type { RequestActorOpts } from "./request-rules.js";
-export type CatalogRequestKind = "access" | "import" | "enable" | "connector_setup";
+export type CatalogRequestKind = "access" | "import" | "enable" | "connector_setup" | "network_allowlist";
 export type CatalogRequestStatus = "pending" | "approved" | "rejected" | "cancelled";
+/**
+ * What a `network_allowlist` request asks for (network ask-to-allow spec §5.3): the hosts (sorted,
+ * lowercased, exact) and the conversation and agent of the blocked command, when the member gave
+ * them. Stored in `catalog_requests.detail`; the member's note is the request's `note`.
+ */
+export interface NetworkRequestDetail {
+    hosts: string[];
+    conversationId: string | null;
+    agentId: string | null;
+}
+/** A member's network request input (`POST /orgs/:orgId/catalog-requests/network`). */
+export interface NetworkRequestInput {
+    hosts: string[];
+    note?: string | undefined;
+    conversationId?: string | undefined;
+    agentId?: string | undefined;
+}
 /** A pending connector a `connector_setup` request waits for (ruling P4-T6-5). */
 export interface SetupRequestConnector {
     /** The agent's `pendingConnectors[].key` (the bind route's `:key`). */
@@ -81,6 +99,8 @@ export interface CatalogRequestView {
      * other kinds.
      */
     connectors: SetupRequestConnector[] | null;
+    /** The hosts, conversation and agent of a `network_allowlist` request; null for other kinds. */
+    network: NetworkRequestDetail | null;
     status: CatalogRequestStatus;
     note: string;
     /** The optional reason of a rejection. */
@@ -99,6 +119,8 @@ export interface CatalogDecision {
     approve: boolean;
     reason?: string | undefined;
 }
+/** The most pending `network_allowlist` requests one member may have in an org. */
+export declare const NETWORK_REQUESTS_PENDING_MAX = 10;
 /** 申请列表一次最多返回的条数。 */
 export declare const CATALOG_REQUESTS_LIST_MAX = 200;
 /**
@@ -115,7 +137,9 @@ export declare const CATALOG_REQUESTS_LIST_MAX = 200;
  * - `connector_setup` (ruling P4-7): one per agent (`agent_id`, `pending_keys`), asking the org
  *   admins to set up an agent's pending connectors; written by the agents module
  *   (`PendingConnectorRequests`), closed by binding (`approved`) or the agent's deletion
- *   (`cancelled`); here it is listed and rejected.
+ *   (`cancelled`); here it is listed and rejected;
+ * - `network_allowlist` (network ask-to-allow spec §5.3): a member asks the org admins to add hosts
+ *   to the org's sandbox egress allowlist; approving merges them into the org's `sandboxEgress`.
  * A rejection stores an optional reason. Decided requests show in the requester's inbox until
  * dismissed. No in-process state.
  */
@@ -129,12 +153,16 @@ export declare class CatalogRequestsService {
     private readonly catalog;
     private readonly config;
     private readonly pluginImport;
+    /** Approving a network request writes the org's `sandboxEgress` through the settings path. */
+    private readonly orgSettings;
     readonly txHost: TransactionHost;
     /** Serializes the approvals of one `import` request (`@WithLock`). */
     readonly lockService: LockService;
     constructor(kdb: KernelDb, 
     /** The org row and super admin locks: both join the caller's transaction. */
-    orgLock: OrgLock, adminLock: SuperAdminLock, orgCatalog: OrgCatalogService, scope: CatalogScopeService, catalog: CatalogService, config: KernelConfigService, pluginImport: PluginImport, txHost: TransactionHost, 
+    orgLock: OrgLock, adminLock: SuperAdminLock, orgCatalog: OrgCatalogService, scope: CatalogScopeService, catalog: CatalogService, config: KernelConfigService, pluginImport: PluginImport, 
+    /** Approving a network request writes the org's `sandboxEgress` through the settings path. */
+    orgSettings: OrgSettingsService, txHost: TransactionHost, 
     /** Serializes the approvals of one `import` request (`@WithLock`). */
     lockService: LockService);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -155,6 +183,19 @@ export declare class CatalogRequestsService {
     /** The role check alone, before any item error (a member cannot probe items by error codes). */
     private authorize;
     private writeItemRequest;
+    /**
+     * A member asks the org admins to allow hosts in the org's sandbox egress (`POST /orgs/:orgId/
+     * catalog-requests/network`, `catalog.request`; spec §5.3). The hosts arrive validated (exact,
+     * lowercased) and are deduped and sorted here. The deployment egress `none` ->
+     * `catalog.request_invalid` (only a super admin can turn sandbox network on); the org's own
+     * egress `none` -> `catalog.request_invalid`; {@link NETWORK_REQUESTS_PENDING_MAX} pending
+     * requests of the member already -> `catalog.request_invalid`; every host already
+     * allowed by the org's effective egress -> `catalog.request_invalid`; a conversation or agent not
+     * in the org -> `catalog.request_invalid`. A pending request of the same requester for the same
+     * host set is returned as is (no second request). Audits `catalog.requested`.
+     */
+    requestNetwork(orgId: string, actor: string, input: NetworkRequestInput, opts?: RequestActorOpts): Promise<CatalogRequestView>;
+    private writeNetworkRequest;
     /**
      * An org admin asks for a marketplace entry to be imported (`POST /orgs/:orgId/
      * marketplace-requests`, `catalog.decide`). The deployment setting `orgMarketplaceBrowse` off ->
@@ -173,17 +214,21 @@ export declare class CatalogRequestsService {
     }, opts?: RequestActorOpts): Promise<CatalogRequestView>;
     private writeImportRequest;
     /**
-     * An org admin decides a member's `enable` or `connector_setup` request (`catalog.decide`). Not
-     * this org's request of those kinds -> `catalog.request_not_found`; decided ->
-     * `catalog.request_decided`. Approving an `enable` request switches the item on in the org as the
-     * deciding admin ({@link OrgCatalogService.setSwitch}: its errors, e.g. inputs the install
+     * An org admin decides a member's `enable`, `network_allowlist` or `connector_setup` request
+     * (`catalog.decide`). Not this org's request of those kinds -> `catalog.request_not_found`;
+     * decided -> `catalog.request_decided`. Approving a `network_allowlist` request merges its hosts
+     * into the org's `sandboxEgress` (`approveNetwork`). Approving an `enable` request switches the
+     * item on in the org as the deciding admin ({@link OrgCatalogService.setSwitch}: its errors, e.g. inputs the install
      * needs, leave the request pending); the install itself resolves the request. A
      * `connector_setup` request is approved only by binding its connectors (ruling P4-T6-6):
      * approving it -> `catalog.request_invalid`. Rejecting stores the reason. Audits
      * `catalog.request_decided`.
      */
     decideOrg(orgId: string, actor: string, requestId: string, decision: CatalogDecision, opts?: RequestActorOpts): Promise<CatalogRequestView>;
-    /** The item of a pending `enable` request of the org (the decider re-checked). */
+    /**
+     * The item of a pending `enable` request of the org, null for a `network_allowlist` one (the
+     * decider re-checked).
+     */
     private pendingOrgRequest;
     /**
      * A super admin decides an `access` or `import` request (re-checked inside the super
@@ -218,6 +263,17 @@ export declare class CatalogRequestsService {
      * approval of an `enable` request may find it approved already by the install it triggered.
      */
     private writeDecision;
+    /**
+     * Approves a `network_allowlist` request inside its decision's transaction: the hosts the org's
+     * effective egress does not allow yet are added to the org's `sandboxEgress.allowHosts` through
+     * {@link OrgSettingsService.update} (audited `org.settings_updated` with `requestId`). An org
+     * following the deployment default starts from the deployment's list (it keeps its own list from
+     * then on). The deployment egress `none`, or the org's `none` -> `catalog.request_invalid`; more
+     * than {@link ORG_SANDBOX_ALLOW_HOSTS_MAX} hosts -> `catalog.request_invalid`; decided with an API
+     * token -> `org.sandbox_egress_not_allowed` (only a person widens the network). Hosts all allowed
+     * already: nothing is written.
+     */
+    private approveNetwork;
     /**
      * The requester dismisses a decided request from the inbox (`POST /orgs/:orgId/
      * catalog-requests/:id/dismiss`). Not the requester's decided request in this org ->
@@ -232,8 +288,8 @@ export declare class CatalogRequestsService {
     countPendingDeployment(): Promise<number>;
     /**
      * The inbox: when the account is an org admin of the org (the role read live), the members'
-     * pending `enable` requests and the pending `connector_setup` requests, newest first; otherwise
-     * none.
+     * pending `enable` and `network_allowlist` requests and the pending `connector_setup` requests,
+     * newest first; otherwise none.
      */
     listForOrgAdmin(orgId: string, accountId: string): Promise<CatalogRequestView[]>;
     /** The inbox: the account's decided requests in the org it has not dismissed, newest first. */

package/dist/catalog/requests.service.js

@@ -20,14 +20,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 { WithLock } from "../infra/lock/with-lock.decorator.js";
+import { orgAllows } from "../local-devices/network-grants.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { roleAtLeast } from "../orgs/roles.js";
+import { ORG_SANDBOX_ALLOW_HOSTS_MAX, OrgSettingsService, readOrgSettings, } from "../orgs/settings.service.js";
+import { baseSandboxEgress } from "../sandbox/tiers.js";
 import { CatalogService } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { assertEntryNotDeprecated, loadMarketplaceEntry } from "./marketplaces.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { PluginImport } from "./plugin-import.js";
 import { itemsSeenBy } from "./scope-state.js";
+/** The most pending `network_allowlist` requests one member may have in an org. */
+export const NETWORK_REQUESTS_PENDING_MAX = 10;
 /** 申请列表一次最多返回的条数。 */
 export const CATALOG_REQUESTS_LIST_MAX = 200;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -36,12 +41,13 @@ const itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item
 const itemDisabled = () => new ApiError("catalog.item_disabled", "This catalog item is disabled by the super admin and cannot be requested");
 const alreadyDecided = () => new ApiError("catalog.request_decided", "This request has already been decided");
 const pendingExists = () => new ApiError("catalog.request_pending", "This organization already has a pending request of this kind for it");
+const deploymentEgressNone = () => new ApiError("catalog.request_invalid", "The platform turned sandbox network off; only a super admin can turn it on");
 /** A unique violation (the partial index of pending requests). */
 const isUniqueViolation = (e) => typeof e === "object" && e !== null && e.code === "23505";
 /** The deployment-level kinds (decided by the super admin). */
 const DEPLOYMENT_KINDS = ["access", "import"];
 /** The org-level kinds (decided by the org admins). */
-const ORG_KINDS = ["enable", "connector_setup"];
+const ORG_KINDS = ["enable", "connector_setup", "network_allowlist"];
 /**
  * Catalog requests under plugin scope (spec §5.1). Three kinds, one pending request per (org,
  * kind, item or entry) (partial unique indexes; org-side writes run inside the org row lock):
@@ -56,7 +62,9 @@ const ORG_KINDS = ["enable", "connector_setup"];
  * - `connector_setup` (ruling P4-7): one per agent (`agent_id`, `pending_keys`), asking the org
  *   admins to set up an agent's pending connectors; written by the agents module
  *   (`PendingConnectorRequests`), closed by binding (`approved`) or the agent's deletion
- *   (`cancelled`); here it is listed and rejected.
+ *   (`cancelled`); here it is listed and rejected;
+ * - `network_allowlist` (network ask-to-allow spec §5.3): a member asks the org admins to add hosts
+ *   to the org's sandbox egress allowlist; approving merges them into the org's `sandboxEgress`.
  * A rejection stores an optional reason. Decided requests show in the requester's inbox until
  * dismissed. No in-process state.
  */
@@ -69,11 +77,14 @@ let CatalogRequestsService = class CatalogRequestsService {
     catalog;
     config;
     pluginImport;
+    orgSettings;
     txHost;
     lockService;
     constructor(kdb, 
     /** The org row and super admin locks: both join the caller's transaction. */
-    orgLock, adminLock, orgCatalog, scope, catalog, config, pluginImport, txHost, 
+    orgLock, adminLock, orgCatalog, scope, catalog, config, pluginImport, 
+    /** Approving a network request writes the org's `sandboxEgress` through the settings path. */
+    orgSettings, txHost, 
     /** Serializes the approvals of one `import` request (`@WithLock`). */
     lockService) {
         this.kdb = kdb;
@@ -84,6 +95,7 @@ let CatalogRequestsService = class CatalogRequestsService {
         this.catalog = catalog;
         this.config = config;
         this.pluginImport = pluginImport;
+        this.orgSettings = orgSettings;
         this.txHost = txHost;
         this.lockService = lockService;
     }
@@ -170,6 +182,113 @@ let CatalogRequestsService = class CatalogRequestsService {
         });
         return id;
     }
+    /**
+     * A member asks the org admins to allow hosts in the org's sandbox egress (`POST /orgs/:orgId/
+     * catalog-requests/network`, `catalog.request`; spec §5.3). The hosts arrive validated (exact,
+     * lowercased) and are deduped and sorted here. The deployment egress `none` ->
+     * `catalog.request_invalid` (only a super admin can turn sandbox network on); the org's own
+     * egress `none` -> `catalog.request_invalid`; {@link NETWORK_REQUESTS_PENDING_MAX} pending
+     * requests of the member already -> `catalog.request_invalid`; every host already
+     * allowed by the org's effective egress -> `catalog.request_invalid`; a conversation or agent not
+     * in the org -> `catalog.request_invalid`. A pending request of the same requester for the same
+     * host set is returned as is (no second request). Audits `catalog.requested`.
+     */
+    async requestNetwork(orgId, actor, input, opts = {}) {
+        const id = await this.writeNetworkRequest(orgId, actor, input, opts);
+        return this.view(id);
+    }
+    async writeNetworkRequest(orgId, actor, input, opts) {
+        const t = this.db;
+        await this.orgLock.lockAndAuthorize(orgId, actor, "catalog.request");
+        const hosts = [...new Set(input.hosts.map((h) => h.toLowerCase()))].sort();
+        const deployment = this.orgSettings.deployment().sandboxEgress;
+        if (deployment.mode === "none")
+            throw deploymentEgressNone();
+        const settings = await readOrgSettings(t, orgId);
+        if (settings.sandboxEgress?.mode === "none") {
+            throw new ApiError("catalog.request_invalid", "The organization has sandbox network turned off; ask an admin to turn it on first.");
+        }
+        // the org's base list: the hosts a strict device reaches (the tiers only widen it)
+        const effective = baseSandboxEgress({ egress: deployment.mode, allowHosts: deployment.allowHosts }, settings.sandboxEgress);
+        if (hosts.every((h) => orgAllows(h, effective))) {
+            throw new ApiError("catalog.request_invalid", "This organization's sandbox network already allows these hosts; nothing to request");
+        }
+        if (input.conversationId !== undefined) {
+            const c = await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", input.conversationId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (!c) {
+                throw new ApiError("catalog.request_invalid", "The conversation is not in this organization");
+            }
+        }
+        if (input.agentId !== undefined) {
+            const a = await t
+                .selectFrom("agents")
+                .select("id")
+                .where("id", "=", input.agentId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (!a) {
+                throw new ApiError("catalog.request_invalid", "The agent is not in this organization");
+            }
+        }
+        // The same requester asking for the same hosts again gets the pending request back (the org
+        // row lock above serializes concurrent asks)
+        const existing = await t
+            .selectFrom("catalog_requests")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("kind", "=", "network_allowlist")
+            .where("requested_by", "=", actor)
+            .where("status", "=", "pending")
+            .where(sql `detail -> 'hosts' = ${JSON.stringify(hosts)}::jsonb`)
+            .executeTakeFirst();
+        if (existing)
+            return existing.id;
+        const pending = await t
+            .selectFrom("catalog_requests")
+            .select(sql `count(*)`.as("n"))
+            .where("org_id", "=", orgId)
+            .where("kind", "=", "network_allowlist")
+            .where("requested_by", "=", actor)
+            .where("status", "=", "pending")
+            .executeTakeFirstOrThrow();
+        if (Number(pending.n) >= NETWORK_REQUESTS_PENDING_MAX) {
+            throw new ApiError("catalog.request_invalid", "You have too many pending domain requests; wait for an admin to handle them.");
+        }
+        const detail = {
+            hosts,
+            conversationId: input.conversationId ?? null,
+            agentId: input.agentId ?? null,
+        };
+        const id = randomUUID();
+        await t
+            .insertInto("catalog_requests")
+            .values({
+            id,
+            org_id: orgId,
+            item_id: null,
+            kind: "network_allowlist",
+            // still written for the old NOT NULL / CHECK, never read
+            stage: "org",
+            detail: JSON.stringify(detail),
+            requested_by: actor,
+            note: input.note ?? "",
+        })
+            .execute();
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            orgId,
+            action: "catalog.requested",
+            target: id,
+            detail: { kind: "network_allowlist", hosts, ...opts.auditDetail },
+        });
+        return id;
+    }
     /**
      * An org admin asks for a marketplace entry to be imported (`POST /orgs/:orgId/
      * marketplace-requests`, `catalog.decide`). The deployment setting `orgMarketplaceBrowse` off ->
@@ -254,10 +373,11 @@ let CatalogRequestsService = class CatalogRequestsService {
         return id;
     }
     /**
-     * An org admin decides a member's `enable` or `connector_setup` request (`catalog.decide`). Not
-     * this org's request of those kinds -> `catalog.request_not_found`; decided ->
-     * `catalog.request_decided`. Approving an `enable` request switches the item on in the org as the
-     * deciding admin ({@link OrgCatalogService.setSwitch}: its errors, e.g. inputs the install
+     * An org admin decides a member's `enable`, `network_allowlist` or `connector_setup` request
+     * (`catalog.decide`). Not this org's request of those kinds -> `catalog.request_not_found`;
+     * decided -> `catalog.request_decided`. Approving a `network_allowlist` request merges its hosts
+     * into the org's `sandboxEgress` (`approveNetwork`). Approving an `enable` request switches the
+     * item on in the org as the deciding admin ({@link OrgCatalogService.setSwitch}: its errors, e.g. inputs the install
      * needs, leave the request pending); the install itself resolves the request. A
      * `connector_setup` request is approved only by binding its connectors (ruling P4-T6-6):
      * approving it -> `catalog.request_invalid`. Rejecting stores the reason. Audits
@@ -268,12 +388,18 @@ let CatalogRequestsService = class CatalogRequestsService {
             throw requestNotFound();
         if (decision.approve) {
             const itemId = await this.pendingOrgRequest(orgId, actor, requestId);
-            await this.orgCatalog.setSwitch(orgId, actor, itemId, { enabled: true }, opts.actorTokenId);
+            // a network request is approved inside the decision (writeDecision), under the row lock
+            if (itemId !== null) {
+                await this.orgCatalog.setSwitch(orgId, actor, itemId, { enabled: true }, opts.actorTokenId);
+            }
         }
         await this.writeDecision(requestId, actor, decision, opts, { orgId });
         return this.view(requestId);
     }
-    /** The item of a pending `enable` request of the org (the decider re-checked). */
+    /**
+     * The item of a pending `enable` request of the org, null for a `network_allowlist` one (the
+     * decider re-checked).
+     */
     async pendingOrgRequest(orgId, actor, requestId) {
         await this.orgLock.lockAndAuthorize(orgId, actor, "catalog.decide");
         const row = await this.db
@@ -290,6 +416,8 @@ let CatalogRequestsService = class CatalogRequestsService {
         if (row.kind === "connector_setup") {
             throw new ApiError("catalog.request_invalid", "A connector setup request is resolved by binding the agent's connectors; reject it to refuse");
         }
+        if (row.kind === "network_allowlist")
+            return null;
         if (row.item_id === null)
             throw requestNotFound();
         return row.item_id;
@@ -416,7 +544,7 @@ let CatalogRequestsService = class CatalogRequestsService {
             await this.adminLock.lockAndAuthorize(actor);
         let q = t
             .selectFrom("catalog_requests")
-            .select(["id", "org_id", "item_id", "kind", "status", "decided_by"])
+            .select(["id", "org_id", "item_id", "kind", "status", "decided_by", "detail"])
             .where("id", "=", requestId);
         q =
             "orgId" in side
@@ -448,6 +576,9 @@ let CatalogRequestsService = class CatalogRequestsService {
                 throw requestNotFound();
             await this.scope.addOrg(actor, row.item_id, row.org_id, { ...opts, requestId });
         }
+        if (decision.approve && row.kind === "network_allowlist") {
+            await this.approveNetwork(row.org_id, actor, requestId, row.detail, opts);
+        }
         // An `import` request whose entry is in the catalog already: the org joins that item's list
         const grantItem = "grantItem" in side ? side.grantItem : undefined;
         if (decision.approve && row.kind === "import" && grantItem !== undefined) {
@@ -478,6 +609,39 @@ let CatalogRequestsService = class CatalogRequestsService {
             },
         });
     }
+    /**
+     * Approves a `network_allowlist` request inside its decision's transaction: the hosts the org's
+     * effective egress does not allow yet are added to the org's `sandboxEgress.allowHosts` through
+     * {@link OrgSettingsService.update} (audited `org.settings_updated` with `requestId`). An org
+     * following the deployment default starts from the deployment's list (it keeps its own list from
+     * then on). The deployment egress `none`, or the org's `none` -> `catalog.request_invalid`; more
+     * than {@link ORG_SANDBOX_ALLOW_HOSTS_MAX} hosts -> `catalog.request_invalid`; decided with an API
+     * token -> `org.sandbox_egress_not_allowed` (only a person widens the network). Hosts all allowed
+     * already: nothing is written.
+     */
+    async approveNetwork(orgId, actor, requestId, detail, opts) {
+        const hosts = detail?.hosts ?? [];
+        const deployment = this.orgSettings.deployment().sandboxEgress;
+        if (deployment.mode === "none")
+            throw deploymentEgressNone();
+        const current = (await readOrgSettings(this.db, orgId)).sandboxEgress;
+        if (current?.mode === "none") {
+            throw new ApiError("catalog.request_invalid", "The organization has sandbox network turned off; turn it on in the organization settings first");
+        }
+        // the org's base list: the hosts a strict device reaches (the tiers only widen it)
+        const effective = baseSandboxEgress({ egress: deployment.mode, allowHosts: deployment.allowHosts }, current);
+        const missing = hosts.filter((h) => !orgAllows(h, effective));
+        if (missing.length === 0)
+            return;
+        const base = current?.allowHosts ?? deployment.allowHosts;
+        const allowHosts = [...new Set([...base, ...missing])];
+        if (allowHosts.length > ORG_SANDBOX_ALLOW_HOSTS_MAX) {
+            throw new ApiError("catalog.request_invalid", `The organization's sandbox allowlist would exceed ${ORG_SANDBOX_ALLOW_HOSTS_MAX} hosts; remove some in the organization settings first`);
+        }
+        // approving widens the org's base list: only a person in a session does that, never an API
+        // token (sandbox dev tiers spec §7.2; the Platform tool has no decide operation at all)
+        await this.orgSettings.update(orgId, { sandboxEgress: { mode: "allowlist", allowHosts } }, actor, opts.actorTokenId, { requestId }, { onlyNarrows: opts.actorTokenId !== undefined });
+    }
     /**
      * The requester dismisses a decided request from the inbox (`POST /orgs/:orgId/
      * catalog-requests/:id/dismiss`). Not the requester's decided request in this org ->
@@ -524,8 +688,8 @@ let CatalogRequestsService = class CatalogRequestsService {
     }
     /**
      * The inbox: when the account is an org admin of the org (the role read live), the members'
-     * pending `enable` requests and the pending `connector_setup` requests, newest first; otherwise
-     * none.
+     * pending `enable` and `network_allowlist` requests and the pending `connector_setup` requests,
+     * newest first; otherwise none.
      */
     async listForOrgAdmin(orgId, accountId) {
         const m = await this.db
@@ -550,7 +714,7 @@ let CatalogRequestsService = class CatalogRequestsService {
         const seen = await itemsSeenBy(this.db, orgId, ids);
         return this.toViews(rows.filter((r) => r.kind === "connector_setup"
             ? r.agent_id !== null && r.agent_deleted_at === null
-            : r.item_id !== null && seen.has(r.item_id)));
+            : r.kind === "network_allowlist" || (r.item_id !== null && seen.has(r.item_id))));
     }
     /** The inbox: the account's decided requests in the org it has not dismissed, newest first. */
     async listDecidedForRequester(orgId, accountId) {
@@ -644,6 +808,7 @@ let CatalogRequestsService = class CatalogRequestsService {
             "r.decided_by",
             "r.decided_at",
             "r.staging_id",
+            "r.detail",
             "r.created_at",
         ]));
     }
@@ -654,6 +819,9 @@ __decorate([
 __decorate([
     Transactional()
 ], CatalogRequestsService.prototype, "writeItemRequest", null);
+__decorate([
+    Transactional()
+], CatalogRequestsService.prototype, "writeNetworkRequest", null);
 __decorate([
     Transactional()
 ], CatalogRequestsService.prototype, "writeImportRequest", null);
@@ -682,8 +850,9 @@ CatalogRequestsService = __decorate([
     __param(5, Inject(CatalogService)),
     __param(6, Inject(KernelConfigService)),
     __param(7, Inject(PluginImport)),
-    __param(8, Inject(TransactionHost)),
-    __param(9, Inject(LockService))
+    __param(8, Inject(OrgSettingsService)),
+    __param(9, Inject(TransactionHost)),
+    __param(10, Inject(LockService))
 ], CatalogRequestsService);
 export { CatalogRequestsService };
 /** The view fields of a `connector_setup` request (ruling P4-T6-5); null for other kinds. */
@@ -721,6 +890,17 @@ function setupFields(r, templateNames) {
         connectors,
     };
 }
+/** The detail of a `network_allowlist` request; null for other kinds. */
+function networkFields(r) {
+    if (r.kind !== "network_allowlist")
+        return null;
+    const d = (r.detail ?? {});
+    return {
+        hosts: Array.isArray(d.hosts) ? d.hosts.filter((h) => typeof h === "string") : [],
+        conversationId: typeof d.conversationId === "string" ? d.conversationId : null,
+        agentId: typeof d.agentId === "string" ? d.agentId : null,
+    };
+}
 function toView(r, templateNames) {
     return {
         id: r.id,
@@ -734,6 +914,7 @@ function toView(r, templateNames) {
             ? { marketplaceId: r.marketplace_id, name: r.entry_name, version: r.entry_version }
             : null,
         ...setupFields(r, templateNames),
+        network: networkFields(r),
         status: r.status,
         note: r.note,
         reason: r.reason,

package/dist/channels/actions.d.ts

@@ -35,5 +35,7 @@ export declare class ChannelCardActions {
     private readonly deps;
     constructor(deps: ChannelCardActionsDeps);
     handle(connectionId: string, e: CardActionEvent): Promise<void>;
+    /** Whether the approval `id` of the org is a network ask. */
+    private isNetworkAsk;
 }
 export {};

package/dist/channels/actions.js

@@ -12,6 +12,8 @@ const REPLY_FOR = {
     "question.already_answered": "alreadyHandled",
     validation_failed: "invalidAction",
     "approval.scope_not_allowed": "invalidAction",
+    // a network ask clicked by someone other than the device's owner
+    "approval.not_yours": "cannotHandle",
 };
 /**
  * IM 卡片上的按钮操作（Review Focus 2）：点击者按入站同样的规则映射到账号（未绑定 → 私聊回绑定卡片、群里只提示去私聊），
@@ -97,14 +99,17 @@ export class ChannelCardActions {
                 await reply("cannotHandle");
                 return;
             }
+            // a network ask is the device owner's, decided by them in person (network ask-to-allow
+            // spec §5.2): the shared guest account never decides one, whoever clicks
+            if (a.cardKind === "approval" && (await this.isNetworkAsk(row.orgId, a.cardId))) {
+                await reply("cannotHandle");
+                return;
+            }
         }
         try {
             if (a.cardKind === "approval" && (a.action === "approve" || a.action === "deny")) {
                 const scope = anonymous ? "once" : a.scope;
-                await this.deps.approvals.decide(row.orgId, a.cardId, who.accountId, {
-                    decision: a.action,
-                    ...(scope !== undefined && { scope }),
-                });
+                await this.deps.approvals.decide(row.orgId, a.cardId, who.accountId, { decision: a.action, ...(scope !== undefined && { scope }) }, undefined, "im");
             }
             else if (a.cardKind === "question" && a.action === "answer") {
                 await this.deps.questions.answer(a.cardId, who.accountId, a.answer ?? {}, row.orgId);
@@ -125,4 +130,14 @@ export class ChannelCardActions {
         // row is the child's, which has no delivery of its own
         await this.deps.outbound.enqueue(card.conversation_id);
     }
+    /** Whether the approval `id` of the org is a network ask. */
+    async isNetworkAsk(orgId, id) {
+        const r = await this.deps.db
+            .selectFrom("approvals")
+            .select("kind")
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        return r?.kind === "network";
+    }
 }

package/dist/channels/cards.d.ts

@@ -1,6 +1,6 @@
 import { type ChannelCard, type FormAnswer, type InputForm, type OutboundMessage } from "@capybara-hq/plugin-sdk";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
-import type { ApprovalsService, ApprovalView } from "../tools/approvals.service.js";
+import type { ApprovalsService, ApprovalView, NetworkAskView } from "../tools/approvals.service.js";
 import { type ToolInfo } from "../tools/info.js";
 import type { ToolRegistry } from "../tools/registry.js";
 import { type ChannelLocale } from "./phrases.js";
@@ -49,9 +49,23 @@ export interface CardDeps {
     /** The tools' display metadata (title, key arguments) for a call without a summary. */
     registry: Pick<ToolRegistry, "builtinSpecs" | "extensionToolSpecs">;
 }
+/** What a network ask's card shows instead of a tool call (network ask-to-allow spec §6.4, §6.5). */
+export interface NetworkCardText {
+    title: string;
+    inputPreview: string;
+    scopeLabels: Partial<Record<"once" | "always", string>>;
+}
+/**
+ * A network ask's card text: the title names the host (or the number of hosts); the preview lists
+ * the hosts, then the command clipped to {@link CARD_SUMMARY_MAX} and, for several hosts, that the
+ * decision applies to all of them (an IM card has no per-host choice). Model-controlled values
+ * are redacted by `redact` (the connection's secret values); the description stays on the web.
+ */
+export declare function networkCardText(detail: Pick<NetworkAskView, "hosts" | "command">, locale: ChannelLocale, redact?: (s: string) => string): NetworkCardText;
 /**
  * The approval card in the approval's current state; undefined when the approval does not exist.
- * A role escalation offers only "once". `webUrl` = `http.publicUrl` + the conversation path.
+ * A role escalation offers only "once". A network ask names its hosts and command and labels its
+ * scopes ({@link networkCardText}). `webUrl` = `http.publicUrl` + the conversation path.
  */
 export declare function approvalCard(d: CardDeps, approvalId: string, base: string, locale: ChannelLocale, redact?: (s: string) => string): Promise<Extract<ChannelCard, {
     kind: "approval";