@peers-app/peers-sdk 0.25.2 → 0.25.3

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

@@ -164,7 +164,11 @@ describe("Self-trusted contract caller authorization", () => {
         })).rejects.toThrow("Permission denied");
         router.dispose();
     });
-    it("rejects remote Tool Access Control as local-only", async () => {
+    it.each([
+        ["Tool Access Control", system_ids_1.toolAccessControlContractId],
+        ["Identity", system_ids_1.identityContractId],
+        ["Invites", system_ids_1.invitesContractId],
+    ])("rejects remote %s as local-only", async (_name, contractId) => {
         const { remoteIdentity, user } = makeIdentity();
         const records = new Map();
         const { personalContext, userContext } = setupUserContext(remoteIdentity.userId, records);
@@ -177,7 +181,7 @@ describe("Self-trusted contract caller authorization", () => {
         });
         await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, {
             ...call,
-            contractId: system_ids_1.toolAccessControlContractId,
+            contractId,
             member: "tool",
             name: "approve",
             operation: "run",
@@ -381,6 +385,35 @@ describe("local user-context contract routing", () => {
         await expect(result).resolves.toBe(setup.userId);
         router.dispose();
     });
+    it("resolves a signed-out contract without waiting for a user context", async () => {
+        const contractId = (0, utils_1.newid)();
+        (0, index_1.registerContractResolver)(contractId, 1, () => ({
+            contractId,
+            version: 1,
+            tools: {
+                inspect: {
+                    tool: {
+                        toolId: (0, utils_1.newid)(),
+                        name: "inspect",
+                        usageDescription: "Report that no user was required.",
+                        inputSchema: { type: "simple", fields: [] },
+                        outputSchema: { type: "simple", fields: [] },
+                        code: "",
+                        packageId: (0, utils_1.newid)(),
+                        accessLevel: 0,
+                    },
+                    toolFn: () => "signed-out",
+                },
+            },
+        }), { requiresUserContext: false });
+        const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+        const router = (0, index_1.createLocalUserContextContractProviderRouter)(providerTransport, {
+            getUserContext: () => new Promise(() => undefined),
+            peekUserContext: () => undefined,
+        });
+        await expect(consumerTransport.emit(index_1.CONTRACT_REQUEST_CHANNEL, makeToolCall(contractId))).resolves.toBe("signed-out");
+        router.dispose();
+    });
     it("routes known groups and rejects unknown contexts without creating them", async () => {
         const setup = setupLocalRouter();
         const router = (0, index_1.createLocalUserContextContractProviderRouter)(setup.providerTransport, {

package/dist/contracts/__tests__/host-contract-consumer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/contracts/__tests__/host-contract-consumer.test.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const field_type_1 = require("../../types/field-type");
+const contract_transport_1 = require("../contract-transport");
+const index_1 = require("../index");
+const definition = {
+    contractId: "hostconsumercontract00001",
+    version: 1,
+    devTag: "dev",
+    name: "Host consumer test",
+    description: "Exercises hostContractConsumer caching.",
+    tables: [],
+    tools: [
+        {
+            name: "ping",
+            usageDescription: "Echo the provider label.",
+            inputFields: [],
+            outputFields: [{ name: "label", type: field_type_1.FieldType.string, description: "Provider label." }],
+        },
+    ],
+    observables: [
+        {
+            name: "state",
+            description: "Snapshot withheld until the test releases it.",
+            valueType: field_type_1.FieldType.object,
+            writable: false,
+        },
+    ],
+    events: [],
+};
+function setupHost(label, opts = {}) {
+    const [consumerTransport, providerTransport] = (0, index_1.inProcessTransportPair)();
+    let releaseSnapshot;
+    const snapshot = opts.holdSnapshot
+        ? new Promise((resolve) => {
+            releaseSnapshot = resolve;
+        })
+        : Promise.resolve({ phase: "idle" });
+    const calls = [];
+    providerTransport.on(contract_transport_1.CONTRACT_REQUEST_CHANNEL, (call) => {
+        calls.push(call);
+        if (call.member === "observable" && call.operation === "get") {
+            return snapshot;
+        }
+        if (call.member === "tool" && call.name === "ping") {
+            return { label };
+        }
+        return undefined;
+    });
+    return {
+        transport: consumerTransport,
+        calls,
+        release: () => releaseSnapshot?.({ phase: "idle" }),
+        dispose: (0, index_1.registerHostContractTransport)(consumerTransport),
+    };
+}
+function waitForCall(host, match) {
+    return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const timer = setInterval(() => {
+            if (host.calls.some(match)) {
+                clearInterval(timer);
+                resolve();
+                return;
+            }
+            if (Date.now() - started > 1000) {
+                clearInterval(timer);
+                reject(new Error(`timed out waiting for a host call; saw ${JSON.stringify(host.calls)}`));
+            }
+        }, 5);
+    });
+}
+describe("hostContractConsumer", () => {
+    const handles = [];
+    const hosts = [];
+    afterEach(() => {
+        while (handles.length > 0) {
+            handles.pop()?.dispose();
+        }
+        while (hosts.length > 0) {
+            hosts.pop()?.dispose();
+        }
+    });
+    function open() {
+        const handle = (0, index_1.hostContractConsumer)(definition, {
+            dataContextId: async () => "user-context",
+        });
+        handles.push(handle);
+        return handle;
+    }
+    it("waits for a transport, then returns the same consumer", async () => {
+        const handle = open();
+        const pending = handle.get();
+        const host = setupHost("first");
+        hosts.push(host);
+        const consumer = await pending;
+        expect(await handle.get()).toBe(consumer);
+        await expect(consumer.tools.ping()).resolves.toEqual({ label: "first" });
+        expect(host.calls).toContainEqual(expect.objectContaining({
+            member: "tool",
+            name: "ping",
+            dataContextId: "user-context",
+        }));
+    });
+    it("shares one in-flight load across concurrent callers", async () => {
+        const host = setupHost("shared");
+        hosts.push(host);
+        const handle = open();
+        const [first, second] = await Promise.all([handle.get(), handle.get()]);
+        expect(second).toBe(first);
+        const snapshots = host.calls.filter((call) => call.member === "observable" && call.operation === "get");
+        expect(snapshots).toHaveLength(1);
+    });
+    it("disposes the cached consumer when the transport is replaced", async () => {
+        const first = setupHost("first");
+        hosts.push(first);
+        const handle = open();
+        const firstConsumer = await handle.get();
+        const second = setupHost("second");
+        hosts.push(second);
+        const secondConsumer = await handle.get();
+        expect(secondConsumer).not.toBe(firstConsumer);
+        await expect(firstConsumer.tools.ping()).rejects.toThrow("disposed");
+        await expect(secondConsumer.tools.ping()).resolves.toEqual({ label: "second" });
+    });
+    it("drops an in-flight consumer when the transport changes during load", async () => {
+        const first = setupHost("first", { holdSnapshot: true });
+        hosts.push(first);
+        const handle = open();
+        const pending = handle.get();
+        await waitForCall(first, (call) => call.member === "observable" && call.operation === "get");
+        const second = setupHost("second");
+        hosts.push(second);
+        first.release();
+        const consumer = await pending;
+        await expect(consumer.tools.ping()).resolves.toEqual({ label: "second" });
+        await waitForCall(first, (call) => call.operation === "unsubscribe");
+    });
+    it("rejects get after dispose and disposes the cached consumer", async () => {
+        const host = setupHost("first");
+        hosts.push(host);
+        const handle = open();
+        const consumer = await handle.get();
+        handle.dispose();
+        handle.dispose();
+        await expect(consumer.tools.ping()).rejects.toThrow("disposed");
+        await expect(handle.get()).rejects.toThrow("is disposed");
+    });
+    it("rejects when no transport arrives before timeoutMs", async () => {
+        jest.useFakeTimers();
+        try {
+            const handle = (0, index_1.hostContractConsumer)(definition, { timeoutMs: 25 });
+            handles.push(handle);
+            const pending = handle.get();
+            const expectation = expect(pending).rejects.toThrow("Timed out waiting for host contract transport after 25ms");
+            await jest.advanceTimersByTimeAsync(25);
+            await expectation;
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+});

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

@@ -4,6 +4,7 @@ const system_ids_1 = require("../../system-ids");
 const utils_1 = require("../../utils");
 const contract_resolvers_1 = require("../contract-resolvers");
 const registry_1 = require("../registry");
+const identity_contract_1 = require("../system/identity-contract");
 const system_contracts_1 = require("../system-contracts");
 // Populate the catalog with built-in system contracts.
 require("../system");
@@ -15,6 +16,7 @@ describe("system contract catalog", () => {
         expect(ids).toEqual(expect.arrayContaining([
             system_ids_1.logsContractId,
             system_ids_1.deviceOperationsContractId,
+            system_ids_1.identityContractId,
             system_ids_1.networkDiagnosticsContractId,
             system_ids_1.networkControlContractId,
             system_ids_1.toolAccessControlContractId,
@@ -31,6 +33,8 @@ describe("system contract catalog", () => {
         expect(registry.getProviderPackageId(system_ids_1.logsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
         expect(registry.resolve(system_ids_1.deviceOperationsContractId, 1)?.name).toBe("System Device Operations");
         expect(registry.getProviderPackageId(system_ids_1.deviceOperationsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
+        expect(registry.resolve(system_ids_1.identityContractId, 1)?.name).toBe("System Identity");
+        expect(registry.getProviderPackageId(system_ids_1.identityContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
         expect(registry.resolve(system_ids_1.networkDiagnosticsContractId, 1)?.name).toBe("System Network Diagnostics");
         expect(registry.getProviderPackageId(system_ids_1.networkDiagnosticsContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
         expect(registry.resolve(system_ids_1.networkControlContractId, 1)?.name).toBe("System Network Control");
@@ -38,6 +42,16 @@ describe("system contract catalog", () => {
         expect(registry.resolve(system_ids_1.toolAccessControlContractId, 1)?.name).toBe("System Tool Access Control");
         expect(registry.getProviderPackageId(system_ids_1.toolAccessControlContractId, 1)).toBe(system_ids_1.peersSystemPackageId);
     });
+    it("declares DevicePairingState as the identity ceremony result", async () => {
+        // Loaded lazily. A top-level import cycles through device tables before they finish initializing.
+        const { devicePairingStateSchema } = await Promise.resolve().then(() => require("../../device-pairing/types"));
+        const stateFields = Object.keys(devicePairingStateSchema.shape).sort();
+        const definition = (0, identity_contract_1.getIdentityContractDefinition)();
+        for (const name of ["startSource", "startDestination", "approve", "reject", "cancel"]) {
+            const tool = definition.tools.find((entry) => entry.name === name);
+            expect(tool?.outputFields.map((entry) => entry.name).sort()).toEqual(stateFields);
+        }
+    });
     it("registerSystemContract makes new contracts installable without loader changes", () => {
         const fakeContractId = (0, utils_1.newid)();
         const providerPackageId = (0, utils_1.newid)();

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

@@ -30,6 +30,12 @@ export interface IContractResolverRegistrationOptions {
      * resolver used as a compatibility fallback.
      */
     providerPackageId?: string;
+    /**
+     * When `false`, the local host router resolves this contract without waiting
+     * for a signed-in user. The resolver must not read `dataContext` in that case.
+     * Defaults to requiring a user.
+     */
+    requiresUserContext?: boolean;
 }
 /** Connection-authenticated identity fields used to authorize remote contract calls. */
 export type ContractRemoteIdentity = Pick<IDeviceInfo, "deviceId" | "userId" | "publicKey" | "publicBoxKey">;
@@ -72,8 +78,7 @@ export declare function isSelfTrustedContractCaller(userContext: UserContext, re
  *
  * 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.
+ *    this device as a relay under its identity. Host-only system contracts are 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
@@ -99,16 +104,23 @@ export declare function authorizeRemoteContractCall(call: IContractCall, userCon
  * currently known group context; arbitrary valid IDs are rejected before
  * `UserContext.getDataContext` can create a new context.
  *
+ * Contracts registered with `requiresUserContext: false` resolve before sign-in
+ * when `peekUserContext` reports that no user is loaded. Every other call still
+ * waits for `getUserContext`.
+ *
  * This helper trusts the host transport's session authentication. It does not
  * infer package-level authority from renderer-supplied data.
  *
  * @param transport Contract transport backed by an authenticated local session.
  * @param opts.getUserContext Lazy accessor for the host's loaded user context.
+ * @param opts.peekUserContext Non-blocking view of the same user context. Required
+ *   for contracts that resolve on the signed-out setup screen.
  * @param opts.allowedContractIds Optional contract allowlist for this session.
  * @param opts.resolveVariable Optional host-only pvar resolver exposed to local package tools.
  */
 export declare function createLocalUserContextContractProviderRouter(transport: IContractTransport, opts: {
     getUserContext: () => Promise<UserContext>;
+    peekUserContext?: () => UserContext | undefined;
     allowedContractIds?: ReadonlySet<string>;
     resolveVariable?: LocalContractVariableResolver;
 }): IContractProviderRouter;

package/dist/contracts/contract-resolvers.js

@@ -20,6 +20,8 @@ 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();
+/** Resolver keys that may run before a user context exists. */
+const resolversWithoutUser = new Set();
 const resolverKey = (contractId, version, providerPackageId) => providerPackageId
     ? `${(0, types_1.contractKey)(contractId, version)}#provider:${providerPackageId}`
     : (0, types_1.contractKey)(contractId, version);
@@ -29,7 +31,32 @@ const resolverKey = (contractId, version, providerPackageId) => providerPackageI
  * registry's "latest provider wins for dev contracts" behavior).
  */
 function registerContractResolver(contractId, version, resolver, opts = {}) {
-    resolvers.set(resolverKey(contractId, version, opts.providerPackageId), resolver);
+    const key = resolverKey(contractId, version, opts.providerPackageId);
+    resolvers.set(key, resolver);
+    if (opts.requiresUserContext === false) {
+        resolversWithoutUser.add(key);
+    }
+    else {
+        resolversWithoutUser.delete(key);
+    }
+}
+/**
+ * Whether the local host must wait for a signed-in user before resolving this contract.
+ *
+ * A contract is user-optional when any of its resolvers registered with
+ * `requiresUserContext: false`.
+ */
+function contractRequiresUserContext(contractId, version) {
+    if (resolversWithoutUser.has(resolverKey(contractId, version))) {
+        return false;
+    }
+    const providerPrefix = `${(0, types_1.contractKey)(contractId, version)}#provider:`;
+    for (const key of resolversWithoutUser) {
+        if (key.startsWith(providerPrefix)) {
+            return false;
+        }
+    }
+    return true;
 }
 /**
  * Look up a resolver for a contract version.
@@ -119,13 +146,17 @@ async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
     return hasSelfTrust(userContext, remoteIdentity);
 }
 const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}${reason ? ` (${reason})` : ""}`);
+const localOnlyContractIds = new Set([
+    system_ids_1.identityContractId,
+    system_ids_1.invitesContractId,
+    system_ids_1.toolAccessControlContractId,
+]);
 /**
  * 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.
+ *    this device as a relay under its identity. Host-only system contracts are 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
@@ -145,8 +176,8 @@ 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");
+    if (localOnlyContractIds.has(call.contractId)) {
+        throw permissionDenied(call, "host system contract is local-only");
     }
     if (!(await verifyRemoteContractIdentity(userContext, remoteIdentity))) {
         throw permissionDenied(call, "unverified caller identity");
@@ -247,6 +278,23 @@ async function resolveDataContextEndpoint(dataContext, request, resolveVariable)
         notify: request.notify,
     });
 }
+async function resolveSignedOutEndpoint(request) {
+    const resolver = getContractResolver(request.contractId, request.version, request.providerPackageId);
+    if (!resolver) {
+        throw new Error(`No contract provider registered for ${request.contractId} v${request.version}`);
+    }
+    // Signed-out contracts declare that they do not read dataContext.
+    const resolution = await resolver({ dataContext: undefined });
+    return (0, contract_proxy_1.createContractProviderEndpoint)(resolution, {
+        context: request.context,
+        notify: request.notify,
+    });
+}
+function resolvesWithoutUser(contractId, version, peekUserContext) {
+    return (!contractRequiresUserContext(contractId, version) &&
+        peekUserContext !== undefined &&
+        !peekUserContext());
+}
 /**
  * Create a provider router for one authenticated UI-to-local-host session.
  *
@@ -256,21 +304,30 @@ async function resolveDataContextEndpoint(dataContext, request, resolveVariable)
  * currently known group context; arbitrary valid IDs are rejected before
  * `UserContext.getDataContext` can create a new context.
  *
+ * Contracts registered with `requiresUserContext: false` resolve before sign-in
+ * when `peekUserContext` reports that no user is loaded. Every other call still
+ * waits for `getUserContext`.
+ *
  * This helper trusts the host transport's session authentication. It does not
  * infer package-level authority from renderer-supplied data.
  *
  * @param transport Contract transport backed by an authenticated local session.
  * @param opts.getUserContext Lazy accessor for the host's loaded user context.
+ * @param opts.peekUserContext Non-blocking view of the same user context. Required
+ *   for contracts that resolve on the signed-out setup screen.
  * @param opts.allowedContractIds Optional contract allowlist for this session.
  * @param opts.resolveVariable Optional host-only pvar resolver exposed to local package tools.
  */
 function createLocalUserContextContractProviderRouter(transport, opts) {
-    const { getUserContext, allowedContractIds, resolveVariable } = opts;
+    const { getUserContext, peekUserContext, allowedContractIds, resolveVariable } = opts;
     return (0, contract_provider_router_1.createContractProviderRouter)(transport, {
         authorizeCall: async (call) => {
             if (allowedContractIds && !allowedContractIds.has(call.contractId)) {
                 throw new Error(`Permission denied: contract ${call.contractId} is not available locally`);
             }
+            if (resolvesWithoutUser(call.contractId, call.version, peekUserContext)) {
+                return { context: {} };
+            }
             const userContext = await getUserContext();
             const dataContext = getAuthorizedLocalDataContext(userContext, call.dataContextId);
             const context = {
@@ -284,11 +341,17 @@ function createLocalUserContextContractProviderRouter(transport, opts) {
             };
         },
         resolveProviderPackageId: async ({ contractId, version, dataContextId }) => {
+            if (resolvesWithoutUser(contractId, version, peekUserContext)) {
+                return undefined;
+            }
             const userContext = await getUserContext();
             const dataContext = getAuthorizedLocalDataContext(userContext, dataContextId);
             return getActiveProviderPackageId(dataContext, contractId, version);
         },
         resolveEndpoint: async (request) => {
+            if (resolvesWithoutUser(request.contractId, request.version, peekUserContext)) {
+                return resolveSignedOutEndpoint(request);
+            }
             const userContext = await getUserContext();
             const dataContext = getAuthorizedLocalDataContext(userContext, request.dataContextId);
             return resolveDataContextEndpoint(dataContext, request, resolveVariable);

package/dist/contracts/host-contract-consumer.d.ts

@@ -0,0 +1,40 @@
+import { type IContractConsumer, type IContractConsumerBase } from "./contract-proxy";
+import type { IContractDefinition } from "./types";
+/** Options for {@link hostContractConsumer}. */
+export interface IHostContractConsumerOptions {
+    /**
+     * Data context bound into every call. Resolved when a consumer is built, not when
+     * the handle is created. Omit it for contracts that resolve before sign-in.
+     */
+    dataContextId?: () => Promise<string | undefined>;
+    /**
+     * How long `get` waits for a host transport on the first call. Later calls reuse
+     * the cached consumer and do not wait again.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Cached handle for one contract consumed over the UI-to-host transport.
+ *
+ * `get` returns the same consumer until the transport is replaced (socket reconnect).
+ * The stale consumer is disposed. A load that is in flight when the transport changes
+ * disposes its half-built consumer and resolves with one bound to the new transport.
+ */
+export interface IHostContractConsumer<T extends IContractConsumerBase> {
+    /** Return the live consumer, building or rebuilding it when the transport changed. */
+    get(): Promise<T>;
+    /** Dispose the cached consumer and ignore later transport changes. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Cache one local-host contract consumer per active UI-to-host transport.
+ *
+ * UI modules that talk to a system contract should share one handle instead of
+ * reimplementing transport wait, swap, and dispose. The CLI does not use this;
+ * it opens a socket per invocation and has no transport swaps.
+ *
+ * @param definition Contract shape to consume.
+ * @param options Data-context resolver and transport wait.
+ * @returns A handle whose `get` is safe to call concurrently.
+ */
+export declare function hostContractConsumer<T extends IContractConsumerBase = IContractConsumer>(definition: IContractDefinition, options?: IHostContractConsumerOptions): IHostContractConsumer<T>;

package/dist/contracts/host-contract-consumer.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hostContractConsumer = hostContractConsumer;
+const contract_proxy_1 = require("./contract-proxy");
+const host_contract_transport_1 = require("./host-contract-transport");
+/** Default wait for a UI-to-host transport before `get` rejects. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Cache one local-host contract consumer per active UI-to-host transport.
+ *
+ * UI modules that talk to a system contract should share one handle instead of
+ * reimplementing transport wait, swap, and dispose. The CLI does not use this;
+ * it opens a socket per invocation and has no transport swaps.
+ *
+ * @param definition Contract shape to consume.
+ * @param options Data-context resolver and transport wait.
+ * @returns A handle whose `get` is safe to call concurrently.
+ */
+function hostContractConsumer(definition, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let cached;
+    let pending;
+    let disposed = false;
+    const disposedMessage = () => `Host contract consumer ${definition.contractId} v${definition.version} is disposed`;
+    const dropCached = () => {
+        cached?.consumer.dispose();
+        cached = undefined;
+    };
+    const unsubscribe = (0, host_contract_transport_1.subscribeHostContractTransport)((transport) => {
+        if (cached && cached.transport !== transport) {
+            dropCached();
+        }
+        if (pending && pending.transport !== transport) {
+            pending = undefined;
+        }
+    }, { emitCurrent: false });
+    async function load(transport) {
+        const dataContextId = options.dataContextId ? await options.dataContextId() : undefined;
+        if (disposed) {
+            throw new Error(disposedMessage());
+        }
+        if ((0, host_contract_transport_1.getHostContractTransport)() !== transport) {
+            return get();
+        }
+        const consumer = (0, contract_proxy_1.createContractConsumer)(definition, transport, dataContextId ? { dataContextId } : {});
+        try {
+            await consumer.loadingPromise;
+            if (disposed || (0, host_contract_transport_1.getHostContractTransport)() !== transport) {
+                consumer.dispose();
+                if (disposed) {
+                    throw new Error(disposedMessage());
+                }
+                return get();
+            }
+            cached = { transport, consumer };
+            return consumer;
+        }
+        catch (error) {
+            consumer.dispose();
+            throw error;
+        }
+    }
+    async function get() {
+        if (disposed) {
+            throw new Error(disposedMessage());
+        }
+        const transport = (0, host_contract_transport_1.getHostContractTransport)() ?? (await (0, host_contract_transport_1.waitForHostContractTransport)({ timeoutMs }));
+        if (disposed) {
+            throw new Error(disposedMessage());
+        }
+        if ((0, host_contract_transport_1.getHostContractTransport)() !== transport) {
+            return get();
+        }
+        if (cached?.transport === transport) {
+            return cached.consumer;
+        }
+        if (pending?.transport === transport) {
+            return pending.promise;
+        }
+        const flight = { transport, promise: undefined };
+        const promise = load(transport);
+        flight.promise = promise;
+        pending = flight;
+        try {
+            return await promise;
+        }
+        finally {
+            if (pending === flight) {
+                pending = undefined;
+            }
+        }
+    }
+    return {
+        get,
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            unsubscribe();
+            pending = undefined;
+            dropCached();
+        },
+    };
+}

package/dist/contracts/index.d.ts

@@ -7,11 +7,13 @@ export { CONTRACT_NOTIFY_CHANNEL, CONTRACT_REQUEST_CHANNEL, connectionContractTr
 export { Contracts, ContractsTable, contractsMetaData, contractsSchema, type IContractRecord, } from "./contracts.table";
 export { createLocalContractConsumer } from "./create-local-consumer";
 export { extractTableShape, extractToolShape, type IExtractableTableDef, type IExtractableToolInstance, setSchemaToFieldsFn, } from "./extract";
+export { hostContractConsumer, type IHostContractConsumer, type IHostContractConsumerOptions, } from "./host-contract-consumer";
 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 { getIdentityContractDefinition, IDENTITY_CONTRACT_VERSION, type IIdentityConsumer, type IIdentitySessionInfo, } from "./system/identity-contract";
 export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./system/invites-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";

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.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.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = void 0;
+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.hostContractConsumer = 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.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = 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; } });
@@ -60,6 +60,8 @@ var extract_1 = require("./extract");
 Object.defineProperty(exports, "extractTableShape", { enumerable: true, get: function () { return extract_1.extractTableShape; } });
 Object.defineProperty(exports, "extractToolShape", { enumerable: true, get: function () { return extract_1.extractToolShape; } });
 Object.defineProperty(exports, "setSchemaToFieldsFn", { enumerable: true, get: function () { return extract_1.setSchemaToFieldsFn; } });
+var host_contract_consumer_1 = require("./host-contract-consumer");
+Object.defineProperty(exports, "hostContractConsumer", { enumerable: true, get: function () { return host_contract_consumer_1.hostContractConsumer; } });
 var host_contract_transport_1 = require("./host-contract-transport");
 Object.defineProperty(exports, "getHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.getHostContractTransport; } });
 Object.defineProperty(exports, "registerHostContractTransport", { enumerable: true, get: function () { return host_contract_transport_1.registerHostContractTransport; } });
@@ -83,6 +85,9 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+var identity_contract_1 = require("./system/identity-contract");
+Object.defineProperty(exports, "getIdentityContractDefinition", { enumerable: true, get: function () { return identity_contract_1.getIdentityContractDefinition; } });
+Object.defineProperty(exports, "IDENTITY_CONTRACT_VERSION", { enumerable: true, get: function () { return identity_contract_1.IDENTITY_CONTRACT_VERSION; } });
 var invites_contract_1 = require("./system/invites-contract");
 Object.defineProperty(exports, "getInvitesContractDefinition", { enumerable: true, get: function () { return invites_contract_1.getInvitesContractDefinition; } });
 Object.defineProperty(exports, "INVITES_CONTRACT_VERSION", { enumerable: true, get: function () { return invites_contract_1.INVITES_CONTRACT_VERSION; } });