@peers-app/peers-sdk 0.22.0 → 0.23.1

package/dist/context/user-context-singleton.d.ts

@@ -1,12 +1,54 @@
 import type { Table } from "../data/orm";
 import type { DataContext } from "./data-context";
 import { UserContext } from "./user-context";
+/**
+ * Return the process user context, waiting until {@link setUserContext} if needed.
+ *
+ * Prefer an explicit `UserContext` when one is already in hand (multi-device
+ * tests and connection providers). Use {@link peekUserContext} to fail closed
+ * instead of waiting.
+ */
 export declare function getUserContext(): Promise<UserContext>;
+/**
+ * Return the process user context if {@link setUserContext} has already run.
+ *
+ * Does not wait. Callers that must not hang (role checks, contract tools)
+ * should treat `undefined` as fail-closed.
+ */
+export declare function peekUserContext(): UserContext | undefined;
+/**
+ * Install the process-wide user context. Throws if one is already set, except
+ * in a browser/PWA where HMR and navigations may replace it.
+ *
+ * @param userContext - Context that owns local personal and group data.
+ */
 export declare function setUserContext(userContext: UserContext): void;
+/**
+ * Return the current user's default data context after the singleton is ready.
+ */
 export declare function getDefaultDataContext(): Promise<DataContext>;
+/**
+ * Return the table container for `dataContext`, or the singleton default.
+ *
+ * @param dataContext - Context to read tables from. Falls back to the singleton.
+ */
 export declare function getTableContainer(dataContext?: DataContext | undefined): import("../data/orm").TableContainer;
+/**
+ * Install a client-proxy user context for renderer/RPC processes.
+ *
+ * No-ops when a real server-side context is already set in-process.
+ *
+ * @param userId - Local user id used as the personal data-context id.
+ */
 export declare function setDefaultClientUserContext(userId: string): void;
+/**
+ * Return every table currently loaded in the default table container, keyed by
+ * full table name.
+ */
 export declare function getAllTables(): {
     [tableName: string]: Table<any>;
 };
+/**
+ * Return the singleton user's id. Throws if {@link setUserContext} has not run.
+ */
 export declare const myUserId: () => string;

package/dist/context/user-context-singleton.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.myUserId = void 0;
 exports.getUserContext = getUserContext;
+exports.peekUserContext = peekUserContext;
 exports.setUserContext = setUserContext;
 exports.getDefaultDataContext = getDefaultDataContext;
 exports.getTableContainer = getTableContainer;
@@ -16,6 +17,13 @@ const user_context_1 = require("./user-context");
 var userContextInstance;
 var userContextResolved;
 var userContextPromise;
+/**
+ * Return the process user context, waiting until {@link setUserContext} if needed.
+ *
+ * Prefer an explicit `UserContext` when one is already in hand (multi-device
+ * tests and connection providers). Use {@link peekUserContext} to fail closed
+ * instead of waiting.
+ */
 async function getUserContext() {
     if (userContextInstance) {
         return userContextInstance.loadingPromise;
@@ -30,6 +38,21 @@ async function getUserContext() {
     }
     return userContextPromise;
 }
+/**
+ * Return the process user context if {@link setUserContext} has already run.
+ *
+ * Does not wait. Callers that must not hang (role checks, contract tools)
+ * should treat `undefined` as fail-closed.
+ */
+function peekUserContext() {
+    return userContextInstance;
+}
+/**
+ * Install the process-wide user context. Throws if one is already set, except
+ * in a browser/PWA where HMR and navigations may replace it.
+ *
+ * @param userContext - Context that owns local personal and group data.
+ */
 function setUserContext(userContext) {
     if (userContextInstance) {
         if (typeof window !== "undefined") {
@@ -51,10 +74,18 @@ function setUserContext(userContext) {
         window.userContext = userContext;
     }
 }
+/**
+ * Return the current user's default data context after the singleton is ready.
+ */
 async function getDefaultDataContext() {
     const userContext = await getUserContext();
     return userContext.defaultDataContext();
 }
+/**
+ * Return the table container for `dataContext`, or the singleton default.
+ *
+ * @param dataContext - Context to read tables from. Falls back to the singleton.
+ */
 function getTableContainer(dataContext) {
     dataContext ??= userContextInstance?.defaultDataContext();
     if (!dataContext) {
@@ -62,6 +93,13 @@ function getTableContainer(dataContext) {
     }
     return dataContext.tableContainer;
 }
+/**
+ * Install a client-proxy user context for renderer/RPC processes.
+ *
+ * No-ops when a real server-side context is already set in-process.
+ *
+ * @param userId - Local user id used as the personal data-context id.
+ */
 function setDefaultClientUserContext(userId) {
     // If a real (server-side) user context is already set in the same process
     // (e.g. PWA where peers-device runs in the browser), don't overwrite it
@@ -83,6 +121,10 @@ function setDefaultClientUserContext(userId) {
     })();
     setUserContext(userContext);
 }
+/**
+ * Return every table currently loaded in the default table container, keyed by
+ * full table name.
+ */
 function getAllTables() {
     const tables = getTableContainer().getAllTables();
     const tableMap = {};
@@ -117,6 +159,9 @@ if (!rpc_types_1.isClient) {
         return table[methodName](...args);
     };
 }
+/**
+ * Return the singleton user's id. Throws if {@link setUserContext} has not run.
+ */
 const myUserId = () => {
     if (!userContextInstance) {
         throw new Error(`myUserId called before userContext singleton was initialized`);

package/dist/contracts/__tests__/contract-proxy.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const groupPermissions = require("../../data/group-permissions");
 const decorators_1 = require("../../data/orm/decorators");
 const observable_1 = require("../../observable");
 const field_type_1 = require("../../types/field-type");
@@ -76,7 +77,7 @@ function makeResolution() {
         tables: { Widgets: table },
         tools: {
             "make-widget": {
-                tool: { toolId: (0, utils_1.newid)(), name: "make-widget" },
+                tool: { toolId: (0, utils_1.newid)(), name: "make-widget", accessLevel: 0 },
                 toolFn: makeWidget,
             },
         },
@@ -147,6 +148,55 @@ describe("contract proxy — consumer/provider round-trip", () => {
         expect(makeWidget).toHaveBeenCalledWith({ color: "blue" });
         expect(result.color).toBe("blue");
     });
+    it("allows a classified tool when the provider data context grants access", async () => {
+        const getUserAccessLevel = jest
+            .spyOn(groupPermissions, "getUserAccessLevel")
+            .mockResolvedValue(100);
+        const contract = makeContract();
+        const { resolution, makeWidget } = makeResolution();
+        const makeWidgetTool = resolution.tools?.["make-widget"];
+        if (!makeWidgetTool) {
+            throw new Error("expected make-widget tool");
+        }
+        makeWidgetTool.tool.accessLevel = 80;
+        const provider = (0, contract_proxy_1.createContractProvider)(resolution);
+        const dataContext = { userContext: { userId: "u1" } };
+        const consumer = consumerVia(contract, provider, {
+            callerUserId: "u1",
+            localUserId: "u1",
+            dataContext,
+        });
+        await expect(consumer.tools["make-widget"]({ color: "blue" })).resolves.toEqual(expect.objectContaining({ color: "blue" }));
+        expect(makeWidget).toHaveBeenCalledWith({ color: "blue" });
+        expect(getUserAccessLevel).toHaveBeenCalledWith(dataContext, "u1");
+    });
+    it("fails closed quickly when a classified tool has no user context", async () => {
+        const contract = makeContract();
+        const { resolution } = makeResolution();
+        const makeWidgetTool = resolution.tools?.["make-widget"];
+        if (!makeWidgetTool) {
+            throw new Error("expected make-widget tool");
+        }
+        makeWidgetTool.tool.accessLevel = 20;
+        const provider = (0, contract_proxy_1.createContractProvider)(resolution);
+        const consumer = consumerVia(contract, provider, {
+            callerUserId: (0, utils_1.newid)(),
+            localUserId: (0, utils_1.newid)(),
+        });
+        await expect(consumer.tools["make-widget"]({ color: "blue" })).rejects.toThrow("User context is not available");
+    });
+    it("denies unclassified tools when the caller identity is missing", async () => {
+        const contract = makeContract();
+        const { resolution } = makeResolution();
+        const makeWidgetTool = resolution.tools?.["make-widget"];
+        if (!makeWidgetTool) {
+            throw new Error("expected make-widget tool");
+        }
+        makeWidgetTool.tool.accessLevel = undefined;
+        const provider = (0, contract_proxy_1.createContractProvider)(resolution);
+        const consumer = consumerVia(contract, provider, {});
+        await expect(consumer.tools["make-widget"]({ color: "blue" })).rejects.toThrow("missing caller identity");
+    });
     it("forwards dataContextId on methods, tools, observables, and subscriptions", async () => {
         const dataContextId = (0, utils_1.newid)();
         const calls = [];

package/dist/contracts/__tests__/contract-resolvers.test.js

@@ -5,8 +5,16 @@ const user_trust_levels_1 = require("../../data/user-trust-levels");
 const users_1 = require("../../data/users");
 const socket_type_1 = require("../../device/socket.type");
 const keys_1 = require("../../keys");
+const system_ids_1 = require("../../system-ids");
 const utils_1 = require("../../utils");
 const index_1 = require("../index");
+jest.mock("../../data/group-permissions", () => {
+    const actual = jest.requireActual("../../data/group-permissions");
+    return {
+        ...actual,
+        getUserRole: jest.fn(async () => actual.GroupMemberRole.Founder),
+    };
+});
 jest.mock("../../data/user-trust-levels", () => ({
     UserTrustLevels: jest.fn(),
 }));
@@ -145,6 +153,26 @@ describe("Self-trusted contract caller authorization", () => {
         })).rejects.toThrow("Permission denied");
         router.dispose();
     });
+    it("rejects remote Tool Access Control as local-only", async () => {
+        const { remoteIdentity, user } = makeIdentity();
+        const records = new Map();
+        const { personalContext, userContext } = setupUserContext(remoteIdentity.userId, records);
+        records.set(personalContext, user);
+        mockTrustGet.mockResolvedValue({ trustLevel: socket_type_1.TrustLevel.Self });
+        const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+        const router = (0, index_1.createUserContextContractProviderRouter)(providerTransport, {
+            userContext,
+            remoteIdentity,
+        });
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, {
+            ...call,
+            contractId: system_ids_1.toolAccessControlContractId,
+            member: "tool",
+            name: "approve",
+            operation: "run",
+        })).rejects.toThrow("local-only");
+        router.dispose();
+    });
 });
 describe("local user-context contract routing", () => {
     function setupLocalRouter() {
@@ -180,6 +208,7 @@ describe("local user-context contract routing", () => {
                         outputSchema: { type: "simple", fields: [] },
                         code: "",
                         packageId: (0, utils_1.newid)(),
+                        accessLevel: 0,
                     },
                     toolFn: () => dataContext.dataContextId,
                 },
@@ -254,6 +283,7 @@ describe("local user-context contract routing", () => {
                         inputSchema: { type: "simple", fields: [] },
                         outputSchema: { type: "simple", fields: [] },
                         code: "",
+                        accessLevel: 0,
                     },
                     toolFn: async (variableName, context) => context.getVariable(variableName, "00localcontractsecrettool"),
                 },

package/dist/contracts/__tests__/playground.test.js

@@ -154,7 +154,10 @@ describe("playground", () => {
             contractId: CONTRACT_ID,
             version: 1,
             tools: {
-                logText: { tool: { toolId: "", name: "logText" }, toolFn: logTextFn },
+                logText: {
+                    tool: { toolId: "", name: "logText", accessLevel: 0 },
+                    toolFn: logTextFn,
+                },
             },
             observables: { logCount: logCountObs },
             observableWritability: { logCount: false },
@@ -208,6 +211,6 @@ describe("playground", () => {
         expect(logs).toEqual(["log1", "log2"]);
         expect(observedLogCount).toBe(2);
         // TODO test tables so we can see what this looks like and how it works for both providers and consumers
-        // TODO consider renaming ContractResolution to ContractProviderInstance or something like that.  ContractResolution is awkward.  
+        // TODO consider renaming ContractResolution to ContractProviderInstance or something like that.  ContractResolution is awkward.
     });
 });

package/dist/contracts/__tests__/system-contracts.test.js

@@ -17,6 +17,7 @@ describe("system contract catalog", () => {
             system_ids_1.deviceOperationsContractId,
             system_ids_1.networkDiagnosticsContractId,
             system_ids_1.networkControlContractId,
+            system_ids_1.toolAccessControlContractId,
         ]));
     });
     it("registers the Logs live resolver", async () => {
@@ -34,6 +35,8 @@ describe("system contract catalog", () => {
         expect(registry.getProviderPackageId(system_ids_1.networkDiagnosticsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
         expect(registry.resolve(system_ids_1.networkControlContractId, 1)?.name).toBe("System Network Control");
         expect(registry.getProviderPackageId(system_ids_1.networkControlContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(registry.resolve(system_ids_1.toolAccessControlContractId, 1)?.name).toBe("System Tool Access Control");
+        expect(registry.getProviderPackageId(system_ids_1.toolAccessControlContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
     });
     it("registerSystemContract makes new contracts installable without loader changes", () => {
         const fakeContractId = (0, utils_1.newid)();

package/dist/contracts/contract-proxy.d.ts

@@ -1,3 +1,4 @@
+import type { DataContext } from "../context/data-context";
 import type { Table } from "../data/orm/table";
 import type { IToolInstance } from "../data/tools";
 import type { Event, ISubscriptionResult } from "../events";
@@ -275,6 +276,11 @@ export interface IContractCallContext {
     callerUserId?: string;
     /** User id of the local device executing the call. */
     localUserId?: string;
+    /**
+     * Provider-side data context used to resolve the caller's group/personal role.
+     * In-process only — never serialized across a connection.
+     */
+    dataContext?: DataContext;
 }
 /**
  * A gate that decides whether a given call is allowed. Runs before dispatch on the

package/dist/contracts/contract-proxy.js

@@ -5,6 +5,8 @@ exports.createContractConsumer = createContractConsumer;
 exports.createContractProvider = createContractProvider;
 exports.createContractProviderEndpoint = createContractProviderEndpoint;
 exports.createContractProviderSession = createContractProviderSession;
+const access_level_1 = require("../data/access-level");
+const group_permissions_1 = require("../data/group-permissions");
 const decorators_1 = require("../data/orm/decorators");
 const observable_1 = require("../observable");
 const utils_1 = require("../utils");
@@ -340,6 +342,37 @@ const sameUserContractPermissionCheck = (_call, context) => {
     return Boolean(context.localUserId) && context.callerUserId === context.localUserId;
 };
 exports.sameUserContractPermissionCheck = sameUserContractPermissionCheck;
+/**
+ * Deny a contract tool when the caller’s group/personal access is below the tool.
+ *
+ * Tools at {@link AccessLevel.None} are unrestricted and do not need a caller
+ * identity. Higher levels fail closed if the transport omitted `callerUserId`
+ * and `localUserId`. Role lookup uses {@link IContractCallContext.dataContext}
+ * when the host attached one, so multi-device processes do not wait on the
+ * user-context singleton.
+ *
+ * Remote Self-trust is a separate, stricter gate applied by the connection router.
+ *
+ * @param tool - Live tool instance being dispatched.
+ * @param call - Inbound contract call (provides dataContextId).
+ * @param context - Caller identity from the transport.
+ */
+async function assertContractToolAccess(tool, call, context) {
+    const required = (0, access_level_1.resolveAccessLevel)(tool.tool.accessLevel);
+    if (required <= access_level_1.AccessLevel.None) {
+        return;
+    }
+    const userId = context.callerUserId ?? context.localUserId;
+    if (!userId) {
+        throw new Error(`Permission denied: missing caller identity for tool '${tool.tool.name}'`);
+    }
+    const userLevel = context.dataContext
+        ? await (0, group_permissions_1.getUserAccessLevel)(context.dataContext, userId)
+        : (0, access_level_1.accessLevelFromGroupRole)(await (0, group_permissions_1.getUserRole)(call.dataContextId || context.localUserId || userId, userId));
+    if (userLevel < required) {
+        throw new Error(`Permission denied: ${tool.tool.name} requires ${(0, access_level_1.getAccessLevelLabel)(required)} (${required})`);
+    }
+}
 /**
  * Build the **provider** side of a contract proxy: an async handler that permission-checks
  * an {@link IContractCall} and dispatches it to the live table method / tool fn / observable
@@ -394,6 +427,7 @@ function createContractProvider(resolution, opts = {}) {
                 if (!tool) {
                     throw new Error(`Contract ${call.contractId} does not provide tool '${call.name}'`);
                 }
+                await assertContractToolAccess(tool, call, context);
                 return resolution.toolContext
                     ? tool.toolFn(...call.args, resolution.toolContext)
                     : tool.toolFn(...call.args);

package/dist/contracts/contract-resolvers.js

@@ -10,6 +10,7 @@ const user_permissions_1 = require("../data/user-permissions");
 const user_trust_levels_1 = require("../data/user-trust-levels");
 const users_1 = require("../data/users");
 const socket_type_1 = require("../device/socket.type");
+const system_ids_1 = require("../system-ids");
 const contract_provider_router_1 = require("./contract-provider-router");
 const contract_proxy_1 = require("./contract-proxy");
 const types_1 = require("./types");
@@ -63,15 +64,20 @@ async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
     return trustLevel === socket_type_1.TrustLevel.Self;
 }
 async function authorizeUserContextCall(call, userContext, remoteIdentity) {
+    if (call.contractId === system_ids_1.toolAccessControlContractId) {
+        throw new Error("Permission denied: tool access control is local-only");
+    }
+    const dataContextId = call.dataContextId || userContext.userId;
     const context = {
         callerUserId: remoteIdentity.userId,
         localUserId: userContext.userId,
+        dataContext: userContext.getDataContext(dataContextId),
     };
     if (!(await isSelfTrustedContractCaller(userContext, remoteIdentity))) {
         throw new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}`);
     }
     return {
-        dataContextId: call.dataContextId || userContext.userId,
+        dataContextId,
         context,
     };
 }
@@ -114,6 +120,7 @@ function createLocalUserContextContractProviderRouter(transport, opts) {
             const context = {
                 callerUserId: userContext.userId,
                 localUserId: userContext.userId,
+                dataContext,
             };
             return {
                 dataContextId: dataContext.dataContextId,
@@ -160,6 +167,7 @@ function createUserContextContractProviderRouter(transport, opts) {
     const context = {
         callerUserId: remoteIdentity.userId,
         localUserId: userContext.userId,
+        dataContext: userContext.userDataContext,
     };
     return (0, contract_provider_router_1.createContractProviderRouter)(transport, {
         context,

package/dist/contracts/index.d.ts

@@ -13,6 +13,7 @@ export { ContractRegistry } from "./registry";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
+export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";
 export { type ISystemContractRegistration, installSystemContracts, listSystemContracts, registerSystemContract, } from "./system-contracts";
 export type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";

package/dist/contracts/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installSystemContracts = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.sameUserContractPermissionCheck = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = void 0;
+exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.sameUserContractPermissionCheck = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -80,6 +80,9 @@ Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true,
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./system/network-contracts"), exports);
+var tool_access_control_contract_1 = require("./system/tool-access-control-contract");
+Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
+Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });
 var system_contracts_1 = require("./system-contracts");
 Object.defineProperty(exports, "installSystemContracts", { enumerable: true, get: function () { return system_contracts_1.installSystemContracts; } });
 Object.defineProperty(exports, "listSystemContracts", { enumerable: true, get: function () { return system_contracts_1.listSystemContracts; } });

package/dist/contracts/system/index.d.ts

@@ -5,6 +5,8 @@
 import "./device-operations-contract";
 import "./logs-contract";
 import "./network-contracts";
+import "./tool-access-control-contract";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./device-operations-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./logs-contract";
 export * from "./network-contracts";
+export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./tool-access-control-contract";

package/dist/contracts/system/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = void 0;
 /**
  * Built-in system contracts. Importing this barrel runs each module's
  * {@link registerSystemContract} side effect so the catalog is populated.
@@ -22,6 +22,7 @@ exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsCon
 require("./device-operations-contract");
 require("./logs-contract");
 require("./network-contracts");
+require("./tool-access-control-contract");
 var device_operations_contract_1 = require("./device-operations-contract");
 Object.defineProperty(exports, "DEVICE_OPERATIONS_CONTRACT_VERSION", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_QUERY_LENGTH", { enumerable: true, get: function () { return device_operations_contract_1.DEVICE_OPERATIONS_MAX_QUERY_LENGTH; } });
@@ -36,3 +37,6 @@ Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true,
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });
 Object.defineProperty(exports, "resolveLogsContract", { enumerable: true, get: function () { return logs_contract_1.resolveLogsContract; } });
 __exportStar(require("./network-contracts"), exports);
+var tool_access_control_contract_1 = require("./tool-access-control-contract");
+Object.defineProperty(exports, "getToolAccessControlContractDefinition", { enumerable: true, get: function () { return tool_access_control_contract_1.getToolAccessControlContractDefinition; } });
+Object.defineProperty(exports, "TOOL_ACCESS_CONTROL_CONTRACT_VERSION", { enumerable: true, get: function () { return tool_access_control_contract_1.TOOL_ACCESS_CONTROL_CONTRACT_VERSION; } });

package/dist/contracts/system/tool-access-control-contract.d.ts

@@ -0,0 +1,35 @@
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Tool Access Control contract. */
+export declare const TOOL_ACCESS_CONTROL_CONTRACT_VERSION = 1;
+/**
+ * Local-only host contract for approving or rejecting step-up tool access.
+ *
+ * Assistants never receive these tools. Remote device connections must not
+ * resolve this contract.
+ */
+export declare function getToolAccessControlContractDefinition(): IContractDefinition;
+/** Consumer-side TypeScript shape for System Tool Access Control. */
+export interface IToolAccessControlConsumer extends IContractConsumerBase {
+    tools: {
+        approve(input: {
+            approvalId: string;
+            nonce: string;
+            scope?: "once" | "thread" | "context";
+        }): Promise<{
+            result: unknown;
+        }>;
+        reject(input: {
+            approvalId: string;
+            nonce: string;
+        }): Promise<{
+            result: unknown;
+        }>;
+        listPending(input?: {
+            threadMessageId?: string;
+            workflowRunId?: string;
+        }): Promise<{
+            approvals: unknown[];
+        }>;
+    };
+}

package/dist/contracts/system/tool-access-control-contract.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = void 0;
+exports.getToolAccessControlContractDefinition = getToolAccessControlContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Tool Access Control contract. */
+exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Local-only host contract for approving or rejecting step-up tool access.
+ *
+ * Assistants never receive these tools. Remote device connections must not
+ * resolve this contract.
+ */
+function getToolAccessControlContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.toolAccessControlContractId,
+        version: exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Tool Access Control",
+        description: "Approve or reject privileged tool calls requested by Assistants.",
+        tables: [],
+        tools: [
+            {
+                name: "approve",
+                usageDescription: "Approve a pending tool-access request and execute the frozen call.",
+                inputFields: [
+                    field("approvalId", field_type_1.FieldType.id, "Pending approval id."),
+                    field("nonce", field_type_1.FieldType.string, "Single-use nonce from the pending row."),
+                    field("scope", field_type_1.FieldType.string, "once, thread, or context.", { optional: true }),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Approval and execution result.")],
+            },
+            {
+                name: "reject",
+                usageDescription: "Reject a pending tool-access request.",
+                inputFields: [
+                    field("approvalId", field_type_1.FieldType.id, "Pending approval id."),
+                    field("nonce", field_type_1.FieldType.string, "Single-use nonce from the pending row."),
+                ],
+                outputFields: [field("result", field_type_1.FieldType.object, "Rejection result.")],
+            },
+            {
+                name: "listPending",
+                usageDescription: "List pending tool-access approvals for a thread or workflow.",
+                inputFields: [
+                    field("threadMessageId", field_type_1.FieldType.id, "Thread root or parent user message.", {
+                        optional: true,
+                    }),
+                    field("workflowRunId", field_type_1.FieldType.id, "Workflow run id.", { optional: true }),
+                ],
+                outputFields: [
+                    field("approvals", field_type_1.FieldType.object, "Pending approval rows.", { isArray: true }),
+                ],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.toolAccessControlContractId,
+    version: exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION,
+    getDefinition: getToolAccessControlContractDefinition,
+});