@peers-app/peers-sdk 0.23.9 → 0.23.11

package/dist/contracts/contract-resolvers.js

@@ -2,10 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerContractResolver = registerContractResolver;
 exports.getContractResolver = getContractResolver;
+exports.verifyRemoteContractIdentity = verifyRemoteContractIdentity;
 exports.isSelfTrustedContractCaller = isSelfTrustedContractCaller;
+exports.authorizeRemoteContractCall = authorizeRemoteContractCall;
 exports.createLocalUserContextContractProviderRouter = createLocalUserContextContractProviderRouter;
 exports.createUserContextContractProviderRouter = createUserContextContractProviderRouter;
 exports.handleContractCall = handleContractCall;
+const access_level_1 = require("../data/access-level");
+const group_permissions_1 = require("../data/group-permissions");
 const user_permissions_1 = require("../data/user-permissions");
 const user_trust_levels_1 = require("../data/user-trust-levels");
 const users_1 = require("../data/users");
@@ -13,6 +17,7 @@ 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 remote_contract_transport_1 = require("./remote-contract-transport");
 const types_1 = require("./types");
 const resolvers = new Map();
 const resolverKey = (contractId, version, providerPackageId) => providerPackageId
@@ -60,15 +65,17 @@ function getContractResolver(contractId, version, providerPackageId) {
     return onlyScopedResolver;
 }
 /**
- * Check whether a connection-authenticated remote identity has full contract authority.
+ * Verify that a connection- or message-authenticated remote identity matches a valid
+ * self-signed Users record in the provider's personal or shared-group data.
  *
- * The identity must match a valid self-signed Users record in the provider's personal or
- * shared-group data, and the provider's personal context must assign the caller exactly
- * {@link TrustLevel.Self}. Unsigned discovery stubs and key mismatches fail closed.
+ * Unsigned discovery stubs, malformed signatures, and key mismatches fail closed. This is
+ * the identity half of remote authorization; trust and role decisions build on it.
+ *
+ * @param userContext Provider's user context whose data is searched.
+ * @param remoteIdentity Identity derived from the verified transport.
  */
-async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
+async function verifyRemoteContractIdentity(userContext, remoteIdentity) {
     const identityContexts = [userContext.userDataContext, ...userContext.groupDataContexts.values()];
-    let hasVerifiedIdentity = false;
     for (const dataContext of identityContexts) {
         const user = await (0, users_1.Users)(dataContext).get(remoteIdentity.userId);
         if (!user?.signature ||
@@ -79,38 +86,113 @@ async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
         }
         try {
             (0, user_permissions_1.verifyUserSignature)(user);
-            hasVerifiedIdentity = true;
-            break;
+            return true;
         }
         catch {
             // A different context may contain the valid signed record.
         }
     }
-    if (!hasVerifiedIdentity) {
-        return false;
-    }
+    return false;
+}
+/**
+ * Whether the provider's personal context assigns exactly {@link TrustLevel.Self} to a
+ * (previously identity-verified) remote user. The provider's own account is always Self.
+ */
+async function hasSelfTrust(userContext, remoteIdentity) {
     const trustLevel = remoteIdentity.userId === userContext.userId
         ? socket_type_1.TrustLevel.Self
         : ((await (0, user_trust_levels_1.UserTrustLevels)(userContext.userDataContext).get(remoteIdentity.userId))
             ?.trustLevel ?? socket_type_1.TrustLevel.Unknown);
     return trustLevel === socket_type_1.TrustLevel.Self;
 }
-async function authorizeUserContextCall(call, userContext, remoteIdentity) {
+/**
+ * Check whether a connection-authenticated remote identity has full contract authority.
+ *
+ * The identity must match a valid self-signed Users record in the provider's personal or
+ * shared-group data, and the provider's personal context must assign the caller exactly
+ * {@link TrustLevel.Self}. Unsigned discovery stubs and key mismatches fail closed.
+ */
+async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
+    if (!(await verifyRemoteContractIdentity(userContext, remoteIdentity))) {
+        return false;
+    }
+    return hasSelfTrust(userContext, remoteIdentity);
+}
+const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}${reason ? ` (${reason})` : ""}`);
+/**
+ * Authorize one inbound contract call from **another device**.
+ *
+ * Layered policy, evaluated in order:
+ * 1. Calls that still carry a `targetDeviceId` are denied: a remote caller may not use
+ *    this device as a relay under its identity. The tool-access-control contract is
+ *    local-only.
+ * 2. The caller's keys must match a valid signed Users record known to the provider.
+ * 3. A Self-trusted caller (the provider's own account, or an account granted exact
+ *    `TrustLevel.Self`) keeps full access; an omitted data context selects the provider's
+ *    personal context.
+ * 4. Any other verified caller is treated as a **group member**: the call must name a
+ *    group the provider belongs to, must be a tool run, the contract definition registered
+ *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and
+ *    the caller's role in that group must meet it. Missing loader, definition, or level
+ *    fails closed.
+ *
+ * @param call Inbound call.
+ * @param userContext Provider's user context.
+ * @param remoteIdentity Identity derived from the verified transport (never from the call).
+ * @returns The canonical route and caller context for the router.
+ */
+async function authorizeRemoteContractCall(call, userContext, remoteIdentity) {
+    if (call.targetDeviceId) {
+        throw permissionDenied(call, "remote callers cannot relay through this device");
+    }
     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}`);
+    if (!(await verifyRemoteContractIdentity(userContext, remoteIdentity))) {
+        throw permissionDenied(call, "unverified caller identity");
+    }
+    if (await hasSelfTrust(userContext, remoteIdentity)) {
+        const dataContextId = call.dataContextId || userContext.userId;
+        return {
+            dataContextId,
+            context: {
+                callerUserId: remoteIdentity.userId,
+                localUserId: userContext.userId,
+                callerDeviceId: remoteIdentity.deviceId,
+                dataContext: userContext.getDataContext(dataContextId),
+            },
+        };
+    }
+    // Group-member path: explicit shared group, tool runs only, remoteAccessLevel required.
+    const dataContextId = call.dataContextId;
+    if (!dataContextId || !userContext.groupIds().includes(dataContextId)) {
+        throw permissionDenied(call, "a shared group data context is required");
+    }
+    if (call.member !== "tool" || call.operation !== "run") {
+        throw permissionDenied(call, "only tool runs are remotely callable");
+    }
+    const dataContext = userContext.getDataContext(dataContextId);
+    const definition = dataContext.packageLoader?.contractRegistry?.getDefinition(call.contractId, call.version);
+    const tool = definition?.tools.find((entry) => entry.name === call.name);
+    if (!tool) {
+        throw permissionDenied(call, "tool is not provided in this data context");
+    }
+    if (typeof tool.remoteAccessLevel !== "number") {
+        throw permissionDenied(call, "tool is not remotely callable");
+    }
+    const requiredLevel = (0, access_level_1.resolveAccessLevel)(tool.remoteAccessLevel);
+    const callerLevel = await (0, group_permissions_1.getUserAccessLevel)(dataContext, remoteIdentity.userId);
+    if (callerLevel <= access_level_1.AccessLevel.None || callerLevel < requiredLevel) {
+        throw permissionDenied(call, `requires ${(0, access_level_1.getAccessLevelLabel)(requiredLevel)} (${requiredLevel}), caller has ${(0, access_level_1.getAccessLevelLabel)(callerLevel)} (${callerLevel})`);
     }
     return {
         dataContextId,
-        context,
+        context: {
+            callerUserId: remoteIdentity.userId,
+            localUserId: userContext.userId,
+            callerDeviceId: remoteIdentity.deviceId,
+            dataContext,
+        },
     };
 }
 function getAuthorizedLocalDataContext(userContext, requestedId) {
@@ -127,6 +209,13 @@ function getActiveProviderPackageId(dataContext, contractId, version) {
     return dataContext.packageLoader?.getActiveContractProviderPackageId?.(contractId, version);
 }
 async function resolveDataContextEndpoint(dataContext, request, resolveVariable) {
+    const remoteEndpoint = (0, remote_contract_transport_1.resolveRemoteTargetEndpoint)(request, {
+        localDeviceId: dataContext.userContext?.deviceId(),
+        userContext: dataContext.userContext,
+    });
+    if (remoteEndpoint) {
+        return remoteEndpoint;
+    }
     if (dataContext.packageLoader?.resolveContractEndpoint) {
         return dataContext.packageLoader.resolveContractEndpoint(request, {
             resolveVariable: resolveVariable
@@ -207,29 +296,30 @@ function createLocalUserContextContractProviderRouter(transport, opts) {
     });
 }
 /**
- * Create the local-object provider router for one verified device connection.
+ * Create the local-object provider router for one verified remote device, whether it is
+ * reached over a direct {@link Connection} or through device messages.
  *
- * The router derives caller identity from the connection owner supplied by the host,
- * authorizes every call before invoking a registered resolver, normalizes omitted data
- * contexts to the local user's personal context, and caches stateful endpoints per
- * contract/version/data-context route. The caller must match a valid signed Users record
- * and have exact Self trust in the provider's personal context. Explicit data-context ids
- * retain their existing behavior after authorization.
+ * The router derives caller identity from the transport owner supplied by the host,
+ * authorizes every call with {@link authorizeRemoteContractCall} before invoking a
+ * registered resolver, normalizes omitted data contexts to the local user's personal
+ * context for Self callers, and caches stateful endpoints per contract/version/data-context
+ * route. Group members reach only tools marked with `remoteAccessLevel`.
  *
- * @param transport  Contract transport backed by one verified connection.
+ * @param transport  Contract transport backed by one verified remote device.
  * @param opts.userContext  Local user context that owns provider data.
- * @param opts.remoteIdentity  Identity derived from the verified remote connection.
+ * @param opts.remoteIdentity  Identity derived from the verified remote device.
  */
 function createUserContextContractProviderRouter(transport, opts) {
     const { userContext, remoteIdentity } = opts;
     const context = {
         callerUserId: remoteIdentity.userId,
         localUserId: userContext.userId,
+        callerDeviceId: remoteIdentity.deviceId,
         dataContext: userContext.userDataContext,
     };
     return (0, contract_provider_router_1.createContractProviderRouter)(transport, {
         context,
-        authorizeCall: (call) => authorizeUserContextCall(call, userContext, remoteIdentity),
+        authorizeCall: (call) => authorizeRemoteContractCall(call, userContext, remoteIdentity),
         resolveProviderPackageId: ({ contractId, version, dataContextId }) => {
             const dataContext = userContext.getDataContext(dataContextId || userContext.userId);
             return getActiveProviderPackageId(dataContext, contractId, version);
@@ -241,9 +331,9 @@ function createUserContextContractProviderRouter(transport, opts) {
     });
 }
 /**
- * Provider-side request/response glue: apply the signed-identity Self-trust host gate,
- * resolve the contract for the authorized data context, build a stateless provider, and
- * execute the call.
+ * Provider-side request/response glue: apply {@link authorizeRemoteContractCall}, resolve
+ * the contract for the authorized data context, build a stateless provider, and execute
+ * the call.
  *
  * Used by transports (e.g. the connection `CONTRACT_CALL_RPC` handler) to run an inbound
  * {@link IContractCall} against local state.
@@ -254,7 +344,7 @@ function createUserContextContractProviderRouter(transport, opts) {
  */
 async function handleContractCall(call, opts) {
     const { userContext, remoteIdentity } = opts;
-    const authorization = await authorizeUserContextCall(call, userContext, remoteIdentity);
+    const authorization = await authorizeRemoteContractCall(call, userContext, remoteIdentity);
     const routedCall = {
         ...call,
         dataContextId: authorization.dataContextId,

package/dist/contracts/extract.d.ts

@@ -29,6 +29,8 @@ export interface IExtractableToolInstance {
         outputSchema?: {
             fields: IField[];
         };
+        /** See {@link IContractTool.remoteAccessLevel}. */
+        remoteAccessLevel?: number;
     };
 }
 /** Override the schemaToFields implementation (useful for tests). */
@@ -41,6 +43,7 @@ export declare function setSchemaToFieldsFn(fn: (schema: z.AnyZodObject) => IFie
 export declare function extractTableShape(def: IExtractableTableDef): IContractTable;
 /**
  * Extract the contract-level tool shape from a tool instance.
- * Uses the tool record's `inputSchema.fields` and `outputSchema.fields`.
+ * Uses the tool record's `inputSchema.fields` and `outputSchema.fields`, and carries
+ * the optional `remoteAccessLevel` policy through unchanged.
  */
 export declare function extractToolShape(inst: IExtractableToolInstance): IContractTool;

package/dist/contracts/extract.js

@@ -38,7 +38,8 @@ function extractTableShape(def) {
 }
 /**
  * Extract the contract-level tool shape from a tool instance.
- * Uses the tool record's `inputSchema.fields` and `outputSchema.fields`.
+ * Uses the tool record's `inputSchema.fields` and `outputSchema.fields`, and carries
+ * the optional `remoteAccessLevel` policy through unchanged.
  */
 function extractToolShape(inst) {
     const { tool } = inst;
@@ -47,5 +48,6 @@ function extractToolShape(inst) {
         usageDescription: tool.usageDescription,
         inputFields: tool.inputSchema?.fields ?? [],
         outputFields: tool.outputSchema?.fields ?? [],
+        ...(tool.remoteAccessLevel !== undefined ? { remoteAccessLevel: tool.remoteAccessLevel } : {}),
     };
 }

package/dist/contracts/index.d.ts

@@ -1,8 +1,8 @@
 export { ContractBuilder, definePackage, PackageBuilder } from "./builder";
 export { type ContractCallAuthorizer, type ContractProviderEndpointResolver, type ContractProviderPackageResolver, createContractProviderRouter, type IAuthorizedContractRoute, type IContractProviderEndpointRequest, type IContractProviderRouter, type IContractProviderRouterOptions, } from "./contract-provider-router";
 export { ContractProviders, ContractProvidersTable, contractProvidersMetaData, contractProvidersSchema, type IContractProviderRecord, } from "./contract-providers.table";
-export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
-export { type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, } from "./contract-resolvers";
+export { CONTRACT_CALL_RPC, type ContractMemberType, type ContractNotificationSink, type ContractPermissionCheck, createContractConsumer, createContractProvider, createContractProviderEndpoint, createContractProviderSession, createRemoteContractConsumer, type IContractCall, type IContractCallContext, type IContractConsumer, type IContractConsumerBase, type IContractNotification, type IContractProviderEndpoint, type IContractProviderEndpointOptions, type IContractProviderSession, type IContractProviderSessionOptions, type IContractResolution, type IContractTableProxy, type IContractToolContext, type ITableProxy, sameUserContractPermissionCheck, } from "./contract-proxy";
+export { authorizeRemoteContractCall, type ContractRemoteIdentity, type ContractResolver, createLocalUserContextContractProviderRouter, createUserContextContractProviderRouter, getContractResolver, handleContractCall, type IContractResolverRegistrationOptions, type ILocalContractVariableRequest, isSelfTrustedContractCaller, type LocalContractVariableResolver, registerContractResolver, verifyRemoteContractIdentity, } from "./contract-resolvers";
 export { CONTRACT_NOTIFY_CHANNEL, CONTRACT_REQUEST_CHANNEL, connectionContractTransport, type IContractTransport, type IDuplexEmitter, inProcessTransportPair, } from "./contract-transport";
 export { Contracts, ContractsTable, contractsMetaData, contractsSchema, type IContractRecord, } from "./contracts.table";
 export { createLocalContractConsumer } from "./create-local-consumer";
@@ -10,11 +10,12 @@ export { extractTableShape, extractToolShape, type IExtractableTableDef, type IE
 export { getHostContractTransport, type HostContractTransportListener, registerHostContractTransport, subscribeHostContractTransport, waitForHostContractTransport, } from "./host-contract-transport";
 export { PersistentContractRegistry } from "./persistent-registry";
 export { ContractRegistry, type IContractProviderRegistration } from "./registry";
+export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type IRemoteContractHost, type IRemoteContractTarget, type RemoteContractTransportFactory, resolveRemoteTargetEndpoint, setRemoteContractTransportFactory, } from "./remote-contract-transport";
 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 type { IAlsoImplementsDeclaration, IConsumedContract, IConsumedContractHandle, IConsumedContractOptions, IContractDefinition, IContractEvent, IContractObservable, IContractTable, IContractTool, IPackageDefinitionResult, IRemoteContract, IRemoteContractConsumer, IRemoteContractHandle, IResolvedContract, IValidationError, IValidationResult, } from "./types";
 export { contractKey } from "./types";
 export { validateAlsoImplements, validateImmutability, validateProviderSatisfiesContract, } from "./validate";

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.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;
+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.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = 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.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.createRemoteContractConsumer = 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 = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = 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; } });
@@ -33,14 +33,17 @@ Object.defineProperty(exports, "createContractConsumer", { enumerable: true, get
 Object.defineProperty(exports, "createContractProvider", { enumerable: true, get: function () { return contract_proxy_1.createContractProvider; } });
 Object.defineProperty(exports, "createContractProviderEndpoint", { enumerable: true, get: function () { return contract_proxy_1.createContractProviderEndpoint; } });
 Object.defineProperty(exports, "createContractProviderSession", { enumerable: true, get: function () { return contract_proxy_1.createContractProviderSession; } });
+Object.defineProperty(exports, "createRemoteContractConsumer", { enumerable: true, get: function () { return contract_proxy_1.createRemoteContractConsumer; } });
 Object.defineProperty(exports, "sameUserContractPermissionCheck", { enumerable: true, get: function () { return contract_proxy_1.sameUserContractPermissionCheck; } });
 var contract_resolvers_1 = require("./contract-resolvers");
+Object.defineProperty(exports, "authorizeRemoteContractCall", { enumerable: true, get: function () { return contract_resolvers_1.authorizeRemoteContractCall; } });
 Object.defineProperty(exports, "createLocalUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createLocalUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "createUserContextContractProviderRouter", { enumerable: true, get: function () { return contract_resolvers_1.createUserContextContractProviderRouter; } });
 Object.defineProperty(exports, "getContractResolver", { enumerable: true, get: function () { return contract_resolvers_1.getContractResolver; } });
 Object.defineProperty(exports, "handleContractCall", { enumerable: true, get: function () { return contract_resolvers_1.handleContractCall; } });
 Object.defineProperty(exports, "isSelfTrustedContractCaller", { enumerable: true, get: function () { return contract_resolvers_1.isSelfTrustedContractCaller; } });
 Object.defineProperty(exports, "registerContractResolver", { enumerable: true, get: function () { return contract_resolvers_1.registerContractResolver; } });
+Object.defineProperty(exports, "verifyRemoteContractIdentity", { enumerable: true, get: function () { return contract_resolvers_1.verifyRemoteContractIdentity; } });
 var contract_transport_1 = require("./contract-transport");
 Object.defineProperty(exports, "CONTRACT_NOTIFY_CHANNEL", { enumerable: true, get: function () { return contract_transport_1.CONTRACT_NOTIFY_CHANNEL; } });
 Object.defineProperty(exports, "CONTRACT_REQUEST_CHANNEL", { enumerable: true, get: function () { return contract_transport_1.CONTRACT_REQUEST_CHANNEL; } });
@@ -66,6 +69,11 @@ var persistent_registry_1 = require("./persistent-registry");
 Object.defineProperty(exports, "PersistentContractRegistry", { enumerable: true, get: function () { return persistent_registry_1.PersistentContractRegistry; } });
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "ContractRegistry", { enumerable: true, get: function () { return registry_1.ContractRegistry; } });
+var remote_contract_transport_1 = require("./remote-contract-transport");
+Object.defineProperty(exports, "createRemoteContractEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.createRemoteContractEndpoint; } });
+Object.defineProperty(exports, "getRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.getRemoteContractTransportFactory; } });
+Object.defineProperty(exports, "resolveRemoteTargetEndpoint", { enumerable: true, get: function () { return remote_contract_transport_1.resolveRemoteTargetEndpoint; } });
+Object.defineProperty(exports, "setRemoteContractTransportFactory", { enumerable: true, get: function () { return remote_contract_transport_1.setRemoteContractTransportFactory; } });
 var device_operations_contract_1 = require("./system/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; } });

package/dist/contracts/remote-contract-transport.d.ts

@@ -0,0 +1,69 @@
+import type { UserContext } from "../context/user-context";
+import type { IContractProviderEndpointRequest } from "./contract-provider-router";
+import type { IContractProviderEndpoint } from "./contract-proxy";
+import { type IContractTransport } from "./contract-transport";
+/** Destination of a device-targeted contract call. */
+export interface IRemoteContractTarget {
+    /** Device that should execute the call. */
+    deviceId: string;
+    /**
+     * Data context the call is scoped to. Required so the transport can seal the message
+     * to the right group or personal keys and the remote device can authorize membership.
+     */
+    dataContextId: string;
+}
+/**
+ * Host-registered factory that produces an outbound {@link IContractTransport} to one
+ * remote device. `peers-device` registers a `sendDeviceMessage`-backed implementation;
+ * the SDK stays transport-agnostic and only knows how to ask for one.
+ */
+export type RemoteContractTransportFactory = (target: IRemoteContractTarget) => IContractTransport;
+/** Trusted host state used to decide whether and how to forward a route. */
+export interface IRemoteContractHost {
+    /** This device's id (`userContext.deviceId()`); a matching target resolves locally. */
+    localDeviceId?: string;
+    /** Owning user context, used to pick a per-context transport factory. */
+    userContext?: UserContext;
+}
+/**
+ * Register (or clear, with `undefined`) the factory used to reach other devices for
+ * contract tool calls. A connection manager registers one for its own `UserContext`;
+ * omitting `opts.userContext` sets the process-wide fallback. Call before any package
+ * invokes a `pkg.remote(...)` device consumer.
+ *
+ * @param factory Factory returning an outbound transport, or `undefined` to unregister.
+ * @param opts.userContext Scope the registration to one user context.
+ */
+export declare function setRemoteContractTransportFactory(factory: RemoteContractTransportFactory | undefined, opts?: {
+    userContext?: UserContext;
+}): void;
+/**
+ * Return the transport factory for a user context, falling back to the process default.
+ *
+ * @param userContext Optional owning user context.
+ */
+export declare function getRemoteContractTransportFactory(userContext?: UserContext): RemoteContractTransportFactory | undefined;
+/**
+ * Shared chokepoint for trusted local hosts: when an authorized route names a device
+ * other than this one, return a forwarding endpoint; otherwise return `undefined` so the
+ * caller resolves the provider locally. A target equal to the local device is treated as
+ * local so `remote.device(myOwnDeviceId)` behaves like a plain consumer.
+ *
+ * @param request Authorized route from a router serving a *local* principal.
+ * @param host This device's id and owning user context.
+ */
+export declare function resolveRemoteTargetEndpoint(request: IContractProviderEndpointRequest, host: IRemoteContractHost): IContractProviderEndpoint | undefined;
+/**
+ * Build a provider endpoint that forwards authorized calls to another device.
+ *
+ * The endpoint is created only by a trusted local host after it has authorized the
+ * *local* caller for the route. It strips {@link IContractCall.targetDeviceId} before
+ * emitting so the receiving device sees an ordinary call addressed to itself and the
+ * message is signed with this device's own identity. Only tool runs are forwarded; the
+ * router rejects other members before reaching this endpoint.
+ *
+ * @param request Authorized route whose `targetDeviceId` and `dataContextId` are set.
+ * @param factory Transport factory; defaults to the process-wide registration.
+ * @throws If no factory is available or the route lacks a target device or data context.
+ */
+export declare function createRemoteContractEndpoint(request: IContractProviderEndpointRequest, factory?: RemoteContractTransportFactory | undefined): IContractProviderEndpoint;

package/dist/contracts/remote-contract-transport.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setRemoteContractTransportFactory = setRemoteContractTransportFactory;
+exports.getRemoteContractTransportFactory = getRemoteContractTransportFactory;
+exports.resolveRemoteTargetEndpoint = resolveRemoteTargetEndpoint;
+exports.createRemoteContractEndpoint = createRemoteContractEndpoint;
+const contract_transport_1 = require("./contract-transport");
+const factoriesByUserContext = new WeakMap();
+let defaultFactory;
+/**
+ * Register (or clear, with `undefined`) the factory used to reach other devices for
+ * contract tool calls. A connection manager registers one for its own `UserContext`;
+ * omitting `opts.userContext` sets the process-wide fallback. Call before any package
+ * invokes a `pkg.remote(...)` device consumer.
+ *
+ * @param factory Factory returning an outbound transport, or `undefined` to unregister.
+ * @param opts.userContext Scope the registration to one user context.
+ */
+function setRemoteContractTransportFactory(factory, opts = {}) {
+    if (opts.userContext) {
+        if (factory) {
+            factoriesByUserContext.set(opts.userContext, factory);
+        }
+        else {
+            factoriesByUserContext.delete(opts.userContext);
+        }
+        return;
+    }
+    defaultFactory = factory;
+}
+/**
+ * Return the transport factory for a user context, falling back to the process default.
+ *
+ * @param userContext Optional owning user context.
+ */
+function getRemoteContractTransportFactory(userContext) {
+    return (userContext && factoriesByUserContext.get(userContext)) ?? defaultFactory;
+}
+/**
+ * Shared chokepoint for trusted local hosts: when an authorized route names a device
+ * other than this one, return a forwarding endpoint; otherwise return `undefined` so the
+ * caller resolves the provider locally. A target equal to the local device is treated as
+ * local so `remote.device(myOwnDeviceId)` behaves like a plain consumer.
+ *
+ * @param request Authorized route from a router serving a *local* principal.
+ * @param host This device's id and owning user context.
+ */
+function resolveRemoteTargetEndpoint(request, host) {
+    if (!request.targetDeviceId || request.targetDeviceId === host.localDeviceId) {
+        return undefined;
+    }
+    return createRemoteContractEndpoint(request, getRemoteContractTransportFactory(host.userContext));
+}
+/**
+ * Build a provider endpoint that forwards authorized calls to another device.
+ *
+ * The endpoint is created only by a trusted local host after it has authorized the
+ * *local* caller for the route. It strips {@link IContractCall.targetDeviceId} before
+ * emitting so the receiving device sees an ordinary call addressed to itself and the
+ * message is signed with this device's own identity. Only tool runs are forwarded; the
+ * router rejects other members before reaching this endpoint.
+ *
+ * @param request Authorized route whose `targetDeviceId` and `dataContextId` are set.
+ * @param factory Transport factory; defaults to the process-wide registration.
+ * @throws If no factory is available or the route lacks a target device or data context.
+ */
+function createRemoteContractEndpoint(request, factory = getRemoteContractTransportFactory()) {
+    const { targetDeviceId, dataContextId } = request;
+    if (!targetDeviceId) {
+        throw new Error("Remote contract endpoint requires a target device id");
+    }
+    if (!dataContextId) {
+        throw new Error("Remote contract endpoint requires an authorized data context id");
+    }
+    if (!factory) {
+        throw new Error(`Cannot reach device ${targetDeviceId}: no remote contract transport is registered on this host`);
+    }
+    const transport = factory({ deviceId: targetDeviceId, dataContextId });
+    let disposed = false;
+    return {
+        handleCall(call) {
+            if (disposed) {
+                return Promise.reject(new Error(`Remote contract endpoint for ${targetDeviceId} is disposed`));
+            }
+            if (call.member !== "tool" || call.operation !== "run") {
+                return Promise.reject(new Error(`Contract ${call.member} '${call.name}'.${call.operation} cannot be forwarded to a remote device`));
+            }
+            const { targetDeviceId: _stripped, ...outbound } = call;
+            return transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, { ...outbound, dataContextId });
+        },
+        dispose() {
+            disposed = true;
+        },
+    };
+}

package/dist/contracts/types.d.ts

@@ -39,6 +39,13 @@ export interface IContractTool {
     usageDescription: string;
     inputFields: IField[];
     outputFields: IField[];
+    /**
+     * Minimum group access level (0–100) a caller on **another device** needs to run
+     * this tool. Absent means the tool is local-only: consumers on the same device can
+     * call it, but remote devices are denied. Self-trusted callers (the provider's own
+     * account) are never gated by this value. Policy only — not part of shape validation.
+     */
+    remoteAccessLevel?: number;
 }
 /** Observable value exposed by a contract. */
 export interface IContractObservable {
@@ -111,6 +118,51 @@ export interface IConsumedContract {
     /** Deferred handle returned by `consumes()` for this dependency. */
     handle?: IConsumedContractHandle<IContractConsumerBase | undefined>;
 }
+/**
+ * Resolved value of a {@link PackageBuilder.remote} handle: a factory of tools-only
+ * consumers whose calls execute on other devices.
+ *
+ * Unlike a consumed contract, no local provider is required — the executing device
+ * selects its own provider and authorizes the call against the caller's group role and
+ * the tool's {@link IContractTool.remoteAccessLevel}. Only `tools` are reachable on the
+ * returned consumers today; `tables`, `observables`, and `events` throw on access.
+ *
+ * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+ */
+export interface IRemoteContractConsumer<T extends IContractConsumerBase = IContractConsumer> {
+    contractId: string;
+    version: number;
+    /**
+     * Consumer whose tool calls run on `deviceId`. Instances are cached per device; passing
+     * this device's own id behaves like a plain local consumer.
+     *
+     * @param deviceId Device that should run the calls.
+     */
+    device(deviceId: string): T;
+    /** Idempotently dispose every per-device consumer created by this factory. */
+    dispose(): void;
+}
+/**
+ * Deferred handle returned by {@link PackageBuilder.remote}.
+ *
+ * Like {@link IConsumedContractHandle}, the handle is not thenable — await
+ * {@link consumer} from runtime code after `definePackage` finishes. The
+ * package-loader settles it once the contract definition is known locally.
+ */
+export interface IRemoteContractHandle<T extends IContractConsumerBase = IContractConsumer> {
+    /** Resolves to the per-device consumer factory. */
+    readonly consumer: Promise<IRemoteContractConsumer<T>>;
+}
+/**
+ * A contract a package calls on other devices. Recorded during `definePackage`;
+ * the loader settles the handle without requiring a local provider.
+ */
+export interface IRemoteContract {
+    contractId: string;
+    version: number;
+    /** Deferred handle returned by `remote()` for this declaration. */
+    handle?: IRemoteContractHandle<IContractConsumerBase>;
+}
 /**
  * Declares that the owning contract's implementation also satisfies another
  * contract (single version or inclusive range).
@@ -132,6 +184,11 @@ export interface IPackageDefinitionResult {
     contracts: IContractDefinition[];
     /** Contracts this package depends on. */
     consumes: IConsumedContract[];
+    /**
+     * Contracts this package calls on other devices via `pkg.remote()`. Optional so
+     * bundles built with an older SDK still load.
+     */
+    remotes?: IRemoteContract[];
     /** `alsoImplements` declarations keyed by the owning contractId+version. */
     alsoImplements: Map<string, IAlsoImplementsDeclaration[]>;
     /** Package-level items not part of any contract. */

package/dist/data/persistent-vars.d.ts

@@ -123,12 +123,20 @@ export declare function groupVar<T = string>(name: string, opts?: Omit<IPersiste
 /**
  * A persistent variable that is stored only on this device, in the user's personal db.
  * It can have a different value for each group on the device but is not synced to other devices.
+ *
+ * The record always lives in the personal db. `opts.dataContext` (or, when omitted, the
+ * current default group) only selects which group's value is addressed by suffixing the
+ * stored name with that data context id, so server-side callers that pin a group and
+ * renderer callers that follow the default group share one row.
  */
 export declare function groupDeviceVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
 export declare function groupDeviceVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;
 /**
  * A persistent variable that is stored in the user's personal db and synced across all their devices in the group.
  * It can have a different value for each user in the group and a different value for each group the user is in.
+ *
+ * As with {@link groupDeviceVar}, the record always lives in the personal db; `opts.dataContext`
+ * only selects the group whose value is addressed.
  */
 export declare function groupUserVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
 export declare function groupUserVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;