@peers-app/peers-sdk 0.23.9 → 0.23.11

package/dist/contracts/builder.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageBuilder = exports.ContractBuilder = void 0;
+exports.createDeferredContractHandle = createDeferredContractHandle;
 exports.createConsumedContractHandle = createConsumedContractHandle;
+exports.settleContractHandle = settleContractHandle;
+exports.rejectContractHandle = rejectContractHandle;
 exports.settleConsumedContractHandle = settleConsumedContractHandle;
 exports.rejectConsumedContractHandle = rejectConsumedContractHandle;
 exports.definePackage = definePackage;
@@ -106,14 +109,14 @@ class ContractBuilder {
     }
 }
 exports.ContractBuilder = ContractBuilder;
-const consumedContractDeferreds = new WeakMap();
+const contractHandleDeferreds = new WeakMap();
 /**
- * Create a deferred consumed-contract handle. Settlement is SDK-owned via
- * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
+ * Create a deferred contract handle. Settlement is SDK-owned via
+ * {@link settleContractHandle} / {@link rejectContractHandle}.
  *
  * @internal
  */
-function createConsumedContractHandle() {
+function createDeferredContractHandle() {
     let resolve;
     let reject;
     const consumer = new Promise((res, rej) => {
@@ -124,25 +127,53 @@ function createConsumedContractHandle() {
     // error before any package code awaits the handle.
     consumer.catch(() => { });
     const handle = { consumer };
-    consumedContractDeferreds.set(handle, { resolve, reject, settled: false });
+    contractHandleDeferreds.set(handle, { resolve, reject, settled: false });
     return handle;
 }
 /**
- * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
- * unmatched optional dependency. One-shot — throws if already settled.
+ * Create a deferred consumed-contract handle. Settlement is SDK-owned via
+ * {@link settleConsumedContractHandle} / {@link rejectConsumedContractHandle}.
  *
- * @internal Used by the package-loader when settling `consumes` handles.
+ * @internal
  */
-function settleConsumedContractHandle(handle, consumer) {
-    const deferred = consumedContractDeferreds.get(handle);
+function createConsumedContractHandle() {
+    return createDeferredContractHandle();
+}
+function takeDeferred(handle) {
+    const deferred = contractHandleDeferreds.get(handle);
     if (!deferred) {
-        throw new Error("Unknown consumed-contract handle");
+        throw new Error("Unknown contract handle");
     }
     if (deferred.settled) {
-        throw new Error("Consumed-contract handle has already been settled");
+        throw new Error("Contract handle has already been settled");
     }
     deferred.settled = true;
-    deferred.resolve(consumer);
+    return deferred;
+}
+/**
+ * Resolve a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+function settleContractHandle(handle, value) {
+    takeDeferred(handle).resolve(value);
+}
+/**
+ * Reject a deferred contract handle. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` / `remote` handles.
+ */
+function rejectContractHandle(handle, reason) {
+    takeDeferred(handle).reject(reason);
+}
+/**
+ * Resolve a consumed-contract handle with a live proxy, or `undefined` for an
+ * unmatched optional dependency. One-shot — throws if already settled.
+ *
+ * @internal Used by the package-loader when settling `consumes` handles.
+ */
+function settleConsumedContractHandle(handle, consumer) {
+    settleContractHandle(handle, consumer);
 }
 /**
  * Reject a consumed-contract handle (e.g. required dependency missing).
@@ -151,15 +182,7 @@ function settleConsumedContractHandle(handle, consumer) {
  * @internal Used by the package-loader when settling `consumes` handles.
  */
 function rejectConsumedContractHandle(handle, reason) {
-    const deferred = consumedContractDeferreds.get(handle);
-    if (!deferred) {
-        throw new Error("Unknown consumed-contract handle");
-    }
-    if (deferred.settled) {
-        throw new Error("Consumed-contract handle has already been settled");
-    }
-    deferred.settled = true;
-    deferred.reject(reason);
+    rejectContractHandle(handle, reason);
 }
 /**
  * Top-level builder passed to the `definePackage` callback.
@@ -175,6 +198,7 @@ class PackageBuilder {
     _version;
     _contracts = [];
     _consumes = [];
+    _remotes = [];
     /** Package-level assistants (not part of any contract). */
     assistants = [];
     /** Package-level app navigation items (not part of any contract). */
@@ -248,6 +272,39 @@ class PackageBuilder {
         });
         return handle;
     }
+    /**
+     * Declare that this package calls a contract's tools on **other devices**.
+     *
+     * A sibling of {@link consumes} for the mesh: the resolved
+     * {@link IRemoteContractConsumer} hands out a tools-only consumer per target device
+     * (`remote.device(deviceId).tools.x(...)`). No local provider is needed — a package
+     * commonly targets its *own* contract on a peer's device — and there is no `optional`
+     * flag because whether the remote device can serve the call is only known per call.
+     * The loader settles the handle once the contract definition is registered locally
+     * (from this package's `provides` or any installed package) and rejects it otherwise.
+     *
+     * Await `handle.consumer` from runtime code after package definition, not inside
+     * this callback.
+     *
+     * @typeParam T - Consumer proxy type (defaults to {@link IContractConsumer}).
+     * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
+     * @param version - Positive integer version number.
+     */
+    remote(contractId, version) {
+        if (!(0, utils_1.isid)(contractId)) {
+            throw new Error(`remote contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
+        }
+        if (version < 1 || !Number.isInteger(version)) {
+            throw new Error(`remote version must be a positive integer, got ${version}`);
+        }
+        const handle = createDeferredContractHandle();
+        this._remotes.push({
+            contractId,
+            version,
+            handle: handle,
+        });
+        return handle;
+    }
     /** @internal Finalize and return the package definition result. */
     _build() {
         if (!this._packageId) {
@@ -274,6 +331,7 @@ class PackageBuilder {
             version: this._version,
             contracts,
             consumes: [...this._consumes],
+            remotes: [...this._remotes],
             alsoImplements: alsoImplementsMap,
             assistants: [...this.assistants],
             appNavs: [...this.appNavs],

package/dist/contracts/contract-provider-router.d.ts

@@ -33,6 +33,12 @@ export interface IContractProviderEndpointRequest {
     providerPackageId?: string;
     /** Canonical data context returned by the authorization hook. */
     dataContextId?: string;
+    /**
+     * Device that should execute calls on this route when it differs from the local
+     * device. Copied from {@link IContractCall.targetDeviceId} by the router; the endpoint
+     * resolver decides whether forwarding is permitted for this router's principal.
+     */
+    targetDeviceId?: string;
     /** Authorized caller context for this route. */
     context: IContractCallContext;
     /** Sink for provider-to-consumer subscription notifications. */

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.