@peers-app/peers-sdk 0.23.10 → 0.23.12

package/dist/contracts/contract-provider-router.js

@@ -2,7 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContractProviderRouter = createContractProviderRouter;
 const contract_transport_1 = require("./contract-transport");
-const routeKey = (contractId, version, providerPackageId, dataContextId) => JSON.stringify([contractId, version, providerPackageId ?? null, dataContextId ?? null]);
+const routeKey = (contractId, version, providerPackageId, dataContextId, targetDeviceId) => JSON.stringify([
+    contractId,
+    version,
+    providerPackageId ?? null,
+    dataContextId ?? null,
+    targetDeviceId ?? null,
+]);
+/**
+ * Reject remote-target operations the mesh path does not support yet. Only tool runs
+ * cross devices; subscriptions, tables, observables, and events stay local.
+ */
+function assertRemoteTargetCallSupported(call) {
+    if (call.member !== "tool" || call.operation !== "run") {
+        throw new Error(`Contract ${call.member} '${call.name}'.${call.operation} cannot target a remote device; only tool runs are remotely callable`);
+    }
+}
 /**
  * Own the sole {@link CONTRACT_REQUEST_CHANNEL} handler for a shared connection.
  *
@@ -91,7 +106,11 @@ function createContractProviderRouter(transport, opts) {
         if (isSubscribe && subscriptionId) {
             pendingSubscriptionIds.add(subscriptionId);
         }
+        const targetDeviceId = call.targetDeviceId || undefined;
         try {
+            if (targetDeviceId) {
+                assertRemoteTargetCallSupported(call);
+            }
             const inboundContext = opts.context ?? {};
             const authorization = await opts.authorizeCall(call, inboundContext);
             if (disposed) {
@@ -106,14 +125,17 @@ function createContractProviderRouter(transport, opts) {
                 contractId: call.contractId,
                 version: call.version,
                 dataContextId: authorization.dataContextId,
+                targetDeviceId,
                 context,
                 notify,
             };
-            const providerPackageId = opts.resolveProviderPackageId
+            // Provider selection happens on the executing device, so a remote route is
+            // cached by target device rather than by a locally selected provider package.
+            const providerPackageId = !targetDeviceId && opts.resolveProviderPackageId
                 ? await opts.resolveProviderPackageId(endpointRequest)
                 : undefined;
             endpointRequest.providerPackageId = providerPackageId;
-            const endpointKey = routeKey(call.contractId, call.version, providerPackageId, authorization.dataContextId);
+            const endpointKey = routeKey(call.contractId, call.version, providerPackageId, authorization.dataContextId, targetDeviceId);
             const endpoint = await getEndpoint(endpointKey, endpointRequest);
             const result = await endpoint.handleCall(routedCall, context);
             if (isSubscribe && subscriptionId) {

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

@@ -4,7 +4,7 @@ import type { IToolInstance } from "../data/tools";
 import type { Event, ISubscriptionResult } from "../events";
 import { type Observable } from "../observable";
 import { type IContractTransport } from "./contract-transport";
-import type { IContractDefinition } from "./types";
+import type { IContractDefinition, IRemoteContractConsumer } from "./types";
 /**
  * The RPC event name used to proxy a single {@link IContractCall} over a
  * {@link Connection} (`connection.emit(CONTRACT_CALL_RPC, call)` on the consumer
@@ -53,6 +53,15 @@ export interface IContractCall {
      * id to the local provider user's personal context.
      */
     dataContextId?: string;
+    /**
+     * Device that should execute this call when it is not the local device. Set by a
+     * {@link createRemoteContractConsumer} device consumer and honored only by the caller's own
+     * trusted host, which forwards the call over the device mesh and strips this field
+     * before it leaves the device. A provider router serving *remote* callers rejects any
+     * call that still carries it, so one device can never relay another device's call
+     * under its own identity.
+     */
+    targetDeviceId?: string;
     /**
      * For any subscription call (a generic `event`, a table `dataChanged`, or an observable
      * value stream): the consumer-chosen id that ties a `"subscribe"` (and its later
@@ -236,6 +245,8 @@ export interface IContractToolContext {
  * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
  * cached observable reads remain available afterward.
  *
+ * To run tools on another device use {@link createRemoteContractConsumer} instead.
+ *
  * @param contract   The contract definition (shape) being consumed.
  * @param transport  Bidirectional channel to the provider; requests go out on
  *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
@@ -244,6 +255,29 @@ export interface IContractToolContext {
 export declare function createContractConsumer(contract: IContractDefinition, transport: IContractTransport, opts?: {
     dataContextId?: string;
 }): IContractConsumer;
+/**
+ * Build the **remote** consumer side of a contract: a factory of tools-only consumers whose
+ * calls execute on other devices (the runtime behind {@link PackageBuilder.remote}).
+ *
+ * `device(deviceId)` returns a consumer of the contract that stamps
+ * {@link IContractCall.targetDeviceId} on every tool call. The trusted local host router
+ * behind `transport` recognizes the target, forwards the call over the device mesh, and the
+ * remote device authorizes it against the caller's group role and the tool's
+ * {@link IContractTool.remoteAccessLevel}. Consumers are cached per device; passing this
+ * device's own id resolves locally. No notify listener or observable mirror is created
+ * because subscriptions do not cross devices yet, so `tables`, `observables`, and `events`
+ * throw on access and `loadingPromise` resolves immediately. Disposing the factory disposes
+ * every device consumer; a device consumer may also be disposed on its own.
+ *
+ * @param contract   The contract definition (shape) whose tools are called remotely.
+ * @param transport  Channel to the caller's own trusted host router (never to the remote
+ *   device directly).
+ * @param opts.dataContextId  Data context every call is scoped to. Cross-account calls must
+ *   name the shared group whose membership the remote device checks.
+ */
+export declare function createRemoteContractConsumer(contract: IContractDefinition, transport: IContractTransport, opts?: {
+    dataContextId?: string;
+}): IRemoteContractConsumer<IContractConsumer>;
 /**
  * The live implementation a **provider** dispatches contract calls to. This is the
  * runtime-callable counterpart to {@link IResolvedContract} (which additionally tracks
@@ -279,6 +313,12 @@ export interface IContractCallContext {
     callerUserId?: string;
     /** User id of the local device executing the call. */
     localUserId?: string;
+    /**
+     * Device the call arrived from when it was made by another device. Absent for
+     * same-device callers. Informational for providers; authorization is decided by the
+     * host router before dispatch.
+     */
+    callerDeviceId?: string;
     /**
      * Provider-side data context used to resolve the caller's group/personal role.
      * In-process only — never serialized across a connection.

package/dist/contracts/contract-proxy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sameUserContractPermissionCheck = exports.CONTRACT_CALL_RPC = void 0;
 exports.createContractConsumer = createContractConsumer;
+exports.createRemoteContractConsumer = createRemoteContractConsumer;
 exports.createContractProvider = createContractProvider;
 exports.createContractProviderEndpoint = createContractProviderEndpoint;
 exports.createContractProviderSession = createContractProviderSession;
@@ -66,6 +67,8 @@ exports.CONTRACT_CALL_RPC = contract_transport_1.CONTRACT_REQUEST_CHANNEL;
  * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
  * cached observable reads remain available afterward.
  *
+ * To run tools on another device use {@link createRemoteContractConsumer} instead.
+ *
  * @param contract   The contract definition (shape) being consumed.
  * @param transport  Bidirectional channel to the provider; requests go out on
  *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
@@ -334,6 +337,106 @@ function createContractConsumer(contract, transport, opts = {}) {
     consumer.loadingPromise = Promise.all(observableLoads).then(() => undefined);
     return consumer;
 }
+/**
+ * Build a bag whose every string property access throws, used for the contract members a
+ * remote consumer cannot reach yet. Symbol access (inspection, `then` probing) stays inert.
+ */
+function unreachableRemoteMembers(member) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== "string" || prop === "then" || prop === "toJSON") {
+                return undefined;
+            }
+            throw new Error(`Contract ${member} '${prop}' is not remotely accessible yet; only tools can be called on a remote device`);
+        },
+    });
+}
+/**
+ * Build the **remote** consumer side of a contract: a factory of tools-only consumers whose
+ * calls execute on other devices (the runtime behind {@link PackageBuilder.remote}).
+ *
+ * `device(deviceId)` returns a consumer of the contract that stamps
+ * {@link IContractCall.targetDeviceId} on every tool call. The trusted local host router
+ * behind `transport` recognizes the target, forwards the call over the device mesh, and the
+ * remote device authorizes it against the caller's group role and the tool's
+ * {@link IContractTool.remoteAccessLevel}. Consumers are cached per device; passing this
+ * device's own id resolves locally. No notify listener or observable mirror is created
+ * because subscriptions do not cross devices yet, so `tables`, `observables`, and `events`
+ * throw on access and `loadingPromise` resolves immediately. Disposing the factory disposes
+ * every device consumer; a device consumer may also be disposed on its own.
+ *
+ * @param contract   The contract definition (shape) whose tools are called remotely.
+ * @param transport  Channel to the caller's own trusted host router (never to the remote
+ *   device directly).
+ * @param opts.dataContextId  Data context every call is scoped to. Cross-account calls must
+ *   name the shared group whose membership the remote device checks.
+ */
+function createRemoteContractConsumer(contract, transport, opts = {}) {
+    const { contractId, version } = contract;
+    const { dataContextId } = opts;
+    const consumers = new Map();
+    let disposed = false;
+    const createDeviceConsumer = (targetDeviceId) => {
+        let deviceDisposed = false;
+        const tools = {};
+        for (const tool of contract.tools) {
+            const name = tool.name;
+            tools[name] = (...args) => deviceDisposed
+                ? Promise.reject(new Error(`Remote contract consumer ${contractId} v${version} for device ${targetDeviceId} is disposed`))
+                : transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, {
+                    contractId,
+                    version,
+                    member: "tool",
+                    name,
+                    operation: "run",
+                    args,
+                    dataContextId,
+                    targetDeviceId,
+                });
+        }
+        return {
+            contractId,
+            version,
+            tables: unreachableRemoteMembers("table"),
+            tools,
+            observables: unreachableRemoteMembers("observable"),
+            events: unreachableRemoteMembers("event"),
+            loadingPromise: Promise.resolve(),
+            dispose: () => {
+                deviceDisposed = true;
+                consumers.delete(targetDeviceId);
+            },
+        };
+    };
+    return {
+        contractId,
+        version,
+        device(deviceId) {
+            if (disposed) {
+                throw new Error(`Remote contract consumer ${contractId} v${version} is disposed`);
+            }
+            if (typeof deviceId !== "string" || deviceId.trim() === "") {
+                throw new Error("device(deviceId) requires a non-empty device id");
+            }
+            let consumer = consumers.get(deviceId);
+            if (!consumer) {
+                consumer = createDeviceConsumer(deviceId);
+                consumers.set(deviceId, consumer);
+            }
+            return consumer;
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            for (const consumer of [...consumers.values()]) {
+                consumer.dispose();
+            }
+            consumers.clear();
+        },
+    };
+}
 /**
  * Legacy gate that allows calls only when caller and provider user ids match.
  *

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

@@ -1,7 +1,7 @@
 import type { DataContext } from "../context/data-context";
 import type { UserContext } from "../context/user-context";
 import type { IDeviceInfo } from "../data/devices";
-import { type IContractProviderRouter } from "./contract-provider-router";
+import { type IAuthorizedContractRoute, type IContractProviderRouter } from "./contract-provider-router";
 import { type IContractCall, type IContractResolution } from "./contract-proxy";
 import type { IContractTransport } from "./contract-transport";
 /**
@@ -48,6 +48,17 @@ export declare function registerContractResolver(contractId: string, version: nu
  * yet adopted provider selection; multiple scoped providers remain ambiguous.
  */
 export declare function getContractResolver(contractId: string, version: number, providerPackageId?: string): ContractResolver | undefined;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function verifyRemoteContractIdentity(userContext: UserContext, remoteIdentity: ContractRemoteIdentity): Promise<boolean>;
 /**
  * Check whether a connection-authenticated remote identity has full contract authority.
  *
@@ -56,6 +67,29 @@ export declare function getContractResolver(contractId: string, version: number,
  * {@link TrustLevel.Self}. Unsigned discovery stubs and key mismatches fail closed.
  */
 export declare function isSelfTrustedContractCaller(userContext: UserContext, remoteIdentity: ContractRemoteIdentity): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function authorizeRemoteContractCall(call: IContractCall, userContext: UserContext, remoteIdentity: ContractRemoteIdentity): Promise<IAuthorizedContractRoute>;
 /**
  * Create a provider router for one authenticated UI-to-local-host session.
  *
@@ -79,27 +113,27 @@ export declare function createLocalUserContextContractProviderRouter(transport:
     resolveVariable?: LocalContractVariableResolver;
 }): IContractProviderRouter;
 /**
- * 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.
  */
 export declare function createUserContextContractProviderRouter(transport: IContractTransport, opts: {
     userContext: UserContext;
     remoteIdentity: ContractRemoteIdentity;
 }): IContractProviderRouter;
 /**
- * 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.

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 } : {}),
     };
 }