@peers-app/peers-sdk 0.25.17 → 0.25.19

package/dist/package-loader/isolated-runtime.d.ts

@@ -1,9 +1,10 @@
+import type { DataContext } from "../context/data-context";
 import type { IContractProviderEndpointRequest } from "../contracts/contract-provider-router";
 import type { IContractCall, IContractProviderEndpoint } from "../contracts/contract-proxy";
 import type { ContractRegistry } from "../contracts/registry";
 import type { PersistentVarScope } from "../data/persistent-vars";
 import type { IField } from "../types/field-type";
-import type { IIsolatedInstallResult, IIsolatedPackageArtifact } from "./isolated-artifact";
+import type { IIsolatedContractToolRef, IIsolatedInstallResult, IIsolatedPackageArtifact } from "./isolated-artifact";
 /** Standard table methods exposed through isolated contract-table references. */
 export declare const ISOLATED_CONTRACT_TABLE_OPERATIONS: readonly ["get", "list", "count", "findOne", "save", "insert", "update", "delete"];
 /** Consumer-callable operation on an isolated contract table. */
@@ -14,6 +15,14 @@ export type IsolatedContractTableOperation = (typeof ISOLATED_CONTRACT_TABLE_OPE
  */
 export interface IIsolatedCallPrincipal {
     userAccessLevel: number;
+    /** Signed identity retained by the host across local hops. */
+    userId?: string;
+    /** Strict runtime tool-dispatch scope; never supplied by guest arguments. */
+    strictActionScope?: boolean;
+    /** Effective level of the currently executing ordinary tool. */
+    callingToolAccessLevel?: number;
+    /** Effective permission from the host, never requested package metadata. */
+    authorityPropagation?: "cap" | "preserve";
     /** Omit for a direct user invocation. */
     assistantAccessLevel?: number;
 }
@@ -73,6 +82,25 @@ export interface IIsolatedPackageRuntime {
     provides(contractId: string, version: number): boolean;
     /** True when this runtime has installed `packageId`. */
     isInstalled(packageId: string): boolean;
+    /**
+     * Run a tool the package provides, starting its worker if needed.
+     *
+     * Used by System Scheduler. The principal defaults to Self for compatibility,
+     * but schedulers should pass the current user's trusted access level.
+     *
+     * @param packageId - Installed package that declares the tool.
+     * @param ref - Contract tool to invoke.
+     * @param args - JSON value passed as the tool argument.
+     * @param principal - Trusted caller authority. Defaults to Self when omitted.
+     */
+    invokeOwnedTool?(packageId: string, ref: IIsolatedContractToolRef, args: unknown, principal?: IIsolatedCallPrincipal): Promise<unknown>;
+    /** Narrow a projected action turn by the trusted consumer's selected contract consume ceiling. */
+    actionDispatchPrincipal?(principal: IIsolatedCallPrincipal, consumerPackageId?: string, ref?: IIsolatedContractToolRef): IIsolatedCallPrincipal;
+    /** Project aliases whose wrapper and canonical targets allow the trusted caller. */
+    authorizedActionNames?(packageId: string, principal: IIsolatedCallPrincipal, consumerPackageId?: string, selectedContract?: {
+        contractId: string;
+        version: number;
+    }): string[] | Promise<string[]>;
     /** Terminate every worker and drop installed state. */
     dispose(): Promise<void>;
 }
@@ -199,12 +227,26 @@ export interface IIsolatedContractProviderGateway {
      */
     resolveEndpoint(request: IIsolatedContractProviderEndpointRequest): Promise<IContractProviderEndpoint | undefined>;
 }
+/**
+ * Resolve the signed-in local user for a runtime's owning data context.
+ *
+ * Invoked only by the host for guest-originated gateway calls. The user id and
+ * data context must come from authenticated host state, never guest payloads.
+ * Return `undefined` when no signed-in identity is available; protected tools
+ * then retain their existing missing-caller-identity denial.
+ */
+export type IsolatedLocalUserContextResolver = () => {
+    userId: string;
+    dataContext: DataContext;
+} | undefined;
 /** Options passed to a registered {@link IsolatedPackageRuntimeFactory}. */
 export interface IIsolatedPackageRuntimeFactoryOptions {
     /** Shared per-data-context contract registry from {@link PackageLoader}. */
     registry: ContractRegistry;
     /** Owning data-context id (personal user id or group id). */
     dataContextId: string;
+    /** Trusted local identity and role-lookup context for guest-to-host calls. */
+    getLocalUserContext?: IsolatedLocalUserContextResolver;
     /**
      * Host-owned table capability for this data context. Required when an
      * isolated package declares tables.

package/dist/package-loader/package-loader.d.ts

@@ -28,6 +28,7 @@ export declare class PackageLoader {
     static PeersSDK: any;
     /** Host-injected Zod module used as the `zod` require. */
     static Zod: any;
+    private hostConsumes;
     private packageInstances;
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     private contractInstalledPackages;
@@ -64,6 +65,7 @@ export declare class PackageLoader {
     isIsolatedInstalled(packageId: string): boolean;
     /** Return whether this host configured an isolated-package runtime. */
     supportsIsolatedPackages(): boolean;
+    private dispatchToolFromProvider;
     /**
      * Return the active provider selected by this data context's trusted registry.
      *

package/dist/package-loader/package-loader.js

@@ -45,6 +45,7 @@ class PackageLoader {
     static PeersSDK;
     /** Host-injected Zod module used as the `zod` require. */
     static Zod;
+    hostConsumes = new Map();
     packageInstances = {};
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     contractInstalledPackages = new Set();
@@ -74,6 +75,10 @@ class PackageLoader {
             this.isolatedRuntime = factory({
                 registry: this.contractRegistry,
                 dataContextId: dataContext.dataContextId,
+                getLocalUserContext: () => {
+                    const userId = this.dataContext.userContext?.userId;
+                    return userId ? { userId, dataContext: this.dataContext } : undefined;
+                },
                 tableGateway: dataContext.tableContainer
                     ? (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext)
                     : undefined,
@@ -110,6 +115,62 @@ class PackageLoader {
     supportsIsolatedPackages() {
         return this.isolatedRuntime !== undefined;
     }
+    async dispatchToolFromProvider(packageId, target, args, context) {
+        if (!context.authority?.userId ||
+            !context.dataContext ||
+            context.dataContext.dataContextId !== this.dataContext.dataContextId)
+            throw new Error("Missing trusted execution context");
+        if (target.targetDeviceId)
+            throw new Error("Strict delegated calls cannot target another device until authority transport is supported");
+        if (target.dataContextId && target.dataContextId !== this.dataContext.dataContextId)
+            throw new Error("Cross-context action dispatch is denied");
+        const own = this.contractRegistry
+            .getRegisteredProviderIds(target.contractId, target.version)
+            .includes(packageId);
+        const consume = this.hostConsumes
+            .get(packageId)
+            ?.find((c) => c.contractId === target.contractId && c.version === target.version);
+        if (!own && !consume)
+            throw new Error("Undeclared contract consumption");
+        if (own && target.providerPackageId && target.providerPackageId !== packageId && !consume)
+            throw new Error("Provider substitution is denied for package-owned targets");
+        const selected = own && (!target.providerPackageId || target.providerPackageId === packageId)
+            ? packageId
+            : consume
+                ? this.contractRegistry.selectProvider(consume)?.providerPackageId
+                : undefined;
+        if (!selected)
+            throw new Error("No declared contract provider is available");
+        if (target.providerPackageId && target.providerPackageId !== selected)
+            throw new Error("Provider substitution is denied");
+        const providerPackageId = selected;
+        const authority = this.isolatedRuntime?.actionDispatchPrincipal?.(context.authority, packageId, target) ??
+            context.authority;
+        const callContext = { ...context, authority, callerPackageId: packageId };
+        const endpoint = await this.resolveContractEndpoint({
+            contractId: target.contractId,
+            version: target.version,
+            dataContextId: this.dataContext.dataContextId,
+            providerPackageId,
+            context: callContext,
+            notify: async () => undefined,
+        });
+        try {
+            return await endpoint.handleCall({
+                contractId: target.contractId,
+                version: target.version,
+                name: target.toolName,
+                member: "tool",
+                operation: "run",
+                args: [args],
+                providerPackageId,
+                dataContextId: this.dataContext.dataContextId,
+            }, callContext);
+        }
+        finally {
+            endpoint.dispose();
+        }
+    }
     /**
      * Return the active provider selected by this data context's trusted registry.
      *
@@ -201,6 +262,7 @@ class PackageLoader {
             }
             : resolution;
         const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
+            dispatchTool: (target, args, context) => this.dispatchToolFromProvider(providerPackageId, target, args, context),
             context: request.context,
             notify: (notification) => request.notify({
                 ...notification,
@@ -314,6 +376,7 @@ class PackageLoader {
      * @param packageId - Package to unload.
      */
     async unloadPackage(packageId) {
+        this.hostConsumes.delete(packageId);
         if (this.isolatedRuntime?.isInstalled(packageId)) {
             await this.isolatedRuntime.uninstall(packageId);
         }
@@ -625,6 +688,7 @@ class PackageLoader {
                 await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
                     registry: this.contractRegistry,
                 });
+                this.hostConsumes.set(packageDefinition.packageId, packageDefinition.consumes);
                 this.contractInstalledPackages.add(packageDefinition.packageId);
                 await this.correctPackageVersion(pkg, selectedPackageVersion, packageDefinition.version);
                 // Build a proper IPeersPackage from the contract definition so callers

package/dist/package-loader/package-loader.test.js

@@ -12,6 +12,7 @@ jest.mock("../data/package-versions", () => ({
 }));
 const contract_resolvers_1 = require("../contracts/contract-resolvers");
 const registry_1 = require("../contracts/registry");
+const access_level_1 = require("../data/access-level");
 const system_ids_1 = require("../system-ids");
 const utils_1 = require("../utils");
 const isolated_artifact_1 = require("./isolated-artifact");
@@ -142,6 +143,46 @@ describe("PackageLoader.contractRegistry", () => {
         expect(resolver).toHaveBeenCalledWith({ dataContext });
         endpoint.dispose();
     });
+    it("does not supply local identity to ordinary callers that omit it", async () => {
+        const userId = (0, utils_1.newid)();
+        const dataContext = {
+            dataContextId: userId,
+            userContext: { userId, deviceId: () => "local-device" },
+        };
+        const loader = new package_loader_1.PackageLoader(dataContext);
+        const contractId = (0, utils_1.newid)();
+        const write = jest.fn();
+        (0, contract_resolvers_1.registerContractResolver)(contractId, 1, () => ({
+            contractId,
+            version: 1,
+            tools: {
+                invoke: {
+                    tool: { toolId: (0, utils_1.newid)(), name: "invoke", accessLevel: access_level_1.AccessLevel.Writer },
+                    toolFn: write,
+                },
+            },
+        }));
+        const endpoint = await loader.resolveContractEndpoint({
+            contractId,
+            version: 1,
+            context: {},
+            notify: async () => undefined,
+        });
+        try {
+            await expect(endpoint.handleCall({
+                contractId,
+                version: 1,
+                member: "tool",
+                name: "invoke",
+                operation: "run",
+                args: [],
+            })).rejects.toThrow("missing caller identity or trusted context for tool 'invoke'");
+            expect(write).not.toHaveBeenCalled();
+        }
+        finally {
+            endpoint.dispose();
+        }
+    });
 });
 const mockGetFileContents = jest.fn();
 jest.mock("../data/files", () => ({
@@ -364,8 +405,8 @@ describe("PackageLoader isolated artifacts", () => {
         await expect(loader.loadPackage(pkg)).rejects.toThrow(/JSON is invalid/);
         expect(globalThis.__shouldNotEvalOnHost).toBeUndefined();
     });
-    it("passes table and package-pvar gateways from a complete data context", () => {
-        const factory = jest.fn(() => ({
+    it("passes gateways and a trusted local identity resolver from its data context", () => {
+        const factory = jest.fn((_options) => ({
             install: jest.fn(async () => ({ packageId, provided: [], consumes: [] })),
             replace: jest.fn(async () => ({ packageId, provided: [], consumes: [] })),
             uninstall: jest.fn(async () => undefined),
@@ -381,11 +422,13 @@ describe("PackageLoader isolated artifacts", () => {
             tableContainer,
         };
         dataContext.userContext = {
+            userId: (0, utils_1.newid)(),
             userDataContext: dataContext,
         };
         new package_loader_1.PackageLoader(dataContext);
         expect(factory).toHaveBeenCalledWith(expect.objectContaining({
             dataContextId: "ctx-tables",
+            getLocalUserContext: expect.any(Function),
             providerGateway: expect.objectContaining({
                 resolveEndpoint: expect.any(Function),
             }),
@@ -399,6 +442,11 @@ describe("PackageLoader isolated artifacts", () => {
                 save: expect.any(Function),
             }),
         }));
+        const resolveLocalUser = factory.mock.calls[0][0].getLocalUserContext;
+        expect(resolveLocalUser?.()).toEqual({ userId: dataContext.userContext.userId, dataContext });
+        expect(resolveLocalUser?.()?.dataContext).toBe(dataContext);
+        dataContext.userContext = undefined;
+        expect(resolveLocalUser?.()).toBeUndefined();
     });
     it("unloads an isolated package on force reload and disable", async () => {
         const runtime = makeRuntime();

package/dist/package-loader/package-network-policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Host-side record of an isolated package's declared outbound HTTP policy.
+ *
+ * Populated when the isolated runtime installs a manifest and read by System HTTP.
+ * Secrets are not stored here; {@link IPackageNetworkCredential.secretVar} is a
+ * logical name the host resolves at request time.
+ */
+/** How System HTTP injects one secret the guest never receives. */
+export interface IPackageNetworkCredential {
+    /** Name the guest passes as `credentialRef`. */
+    ref: string;
+    /** Logical persistent-variable name. The host prefixes it with the package id. */
+    secretVar: string;
+    /** Where the secret persistent variable lives. Defaults to `user`. */
+    scope?: "user" | "device";
+    /** Request header the host sets from the secret. */
+    header: string;
+    /** Header value template. Must contain the literal `{secret}`. */
+    format: string;
+}
+/** Outbound HTTP permission recorded for one installed package in one data context. */
+export interface IPackageNetworkPolicy {
+    /** Exact hostnames the package may request. `https` only. */
+    allowedHosts: string[];
+    /** Secrets the host may attach. The guest names a `ref`, never the value. */
+    credentials: IPackageNetworkCredential[];
+}
+/**
+ * Record or clear the network policy for one package in one data context.
+ *
+ * Pass `undefined` when the package is uninstalled or declares no network block.
+ * The policy is process memory; install republishes it.
+ *
+ * @param dataContextId - Personal or group context that installed the package.
+ * @param packageId - Trusted package id from the manifest, not from a guest payload.
+ * @param policy - Declared allowlist and credential refs, or `undefined` to forget it.
+ */
+export declare function setPackageNetworkPolicy(dataContextId: string, packageId: string, policy: IPackageNetworkPolicy | undefined): void;
+/**
+ * Return the network policy installed for this package, if it declared one.
+ *
+ * @param dataContextId - Context whose runtime installed the package.
+ * @param packageId - Package that is calling System HTTP.
+ * @returns A copy of the policy, or `undefined` when HTTP is not declared.
+ */
+export declare function getPackageNetworkPolicy(dataContextId: string, packageId: string): IPackageNetworkPolicy | undefined;
+/**
+ * Drop every recorded network policy.
+ *
+ * @internal Test-only. Production install and uninstall update one package at a time.
+ */
+export declare function _clearPackageNetworkPoliciesForTests(): void;

package/dist/package-loader/package-network-policy.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Host-side record of an isolated package's declared outbound HTTP policy.
+ *
+ * Populated when the isolated runtime installs a manifest and read by System HTTP.
+ * Secrets are not stored here; {@link IPackageNetworkCredential.secretVar} is a
+ * logical name the host resolves at request time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPackageNetworkPolicy = setPackageNetworkPolicy;
+exports.getPackageNetworkPolicy = getPackageNetworkPolicy;
+exports._clearPackageNetworkPoliciesForTests = _clearPackageNetworkPoliciesForTests;
+const policies = new Map();
+function policyKey(dataContextId, packageId) {
+    return `${dataContextId}:${packageId}`;
+}
+/**
+ * Record or clear the network policy for one package in one data context.
+ *
+ * Pass `undefined` when the package is uninstalled or declares no network block.
+ * The policy is process memory; install republishes it.
+ *
+ * @param dataContextId - Personal or group context that installed the package.
+ * @param packageId - Trusted package id from the manifest, not from a guest payload.
+ * @param policy - Declared allowlist and credential refs, or `undefined` to forget it.
+ */
+function setPackageNetworkPolicy(dataContextId, packageId, policy) {
+    const key = policyKey(dataContextId, packageId);
+    if (!policy) {
+        policies.delete(key);
+        return;
+    }
+    policies.set(key, {
+        allowedHosts: [...policy.allowedHosts],
+        credentials: policy.credentials.map((credential) => ({ ...credential })),
+    });
+}
+/**
+ * Return the network policy installed for this package, if it declared one.
+ *
+ * @param dataContextId - Context whose runtime installed the package.
+ * @param packageId - Package that is calling System HTTP.
+ * @returns A copy of the policy, or `undefined` when HTTP is not declared.
+ */
+function getPackageNetworkPolicy(dataContextId, packageId) {
+    const policy = policies.get(policyKey(dataContextId, packageId));
+    if (!policy) {
+        return undefined;
+    }
+    return {
+        allowedHosts: [...policy.allowedHosts],
+        credentials: policy.credentials.map((credential) => ({ ...credential })),
+    };
+}
+/**
+ * Drop every recorded network policy.
+ *
+ * @internal Test-only. Production install and uninstall update one package at a time.
+ */
+function _clearPackageNetworkPoliciesForTests() {
+    policies.clear();
+}

package/dist/system-ids.d.ts

@@ -152,3 +152,34 @@ export declare const localFoldersToolIds: {
     readonly trash: "00mukk9dwejbuehqzszpyxefx";
     readonly purgeTrash: "00mukk9dwe6co8gvuy44kmuzd";
 };
+/**
+ * Contract id for the local-only System HTTP surface.
+ * Host-mediated fetch for isolated packages. Not available over device-to-device connections.
+ */
+export declare const httpContractId = "00muxgugn4tzd527r3cwnie2o";
+/** Stable IDs for tools in System HTTP v1. */
+export declare const httpToolIds: {
+    readonly request: "00muxgugn6e3dan5ej6dotzy5";
+    readonly cancel: "00muxgugn6scnni9563focivs";
+    readonly describePolicy: "00muxgugn6kouo2ocpun70q31";
+};
+/**
+ * Contract id for the local-only System Contract Catalog.
+ * Lists every registered provider of a contract version so a hub package can fan out.
+ */
+export declare const contractCatalogContractId = "00muxgugn6ncjuunb8r28puae";
+/** Stable IDs for tools in System Contract Catalog v1. */
+export declare const contractCatalogToolIds: {
+    readonly listContractProviders: "00muxgugn6ek5apk8d5jtfavp";
+};
+/**
+ * Contract id for the local-only System Scheduler.
+ * Device-local timers that wake an isolated package's own tool. Not synced and not remote.
+ */
+export declare const schedulerContractId = "00muxgugn6pj2o0lcu7kxkvrs";
+/** Stable IDs for tools in System Scheduler v1. */
+export declare const schedulerToolIds: {
+    readonly schedule: "00muxgugn6t0o5s7239zg6bf5";
+    readonly cancel: "00muxgugn6vqfxpppodqlgfhg";
+    readonly list: "00muxgugn661g0qmpuwafrmsi4";
+};

package/dist/system-ids.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.schedulerToolIds = exports.schedulerContractId = exports.contractCatalogToolIds = exports.contractCatalogContractId = exports.httpToolIds = exports.httpContractId = exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
 /** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
 /** Default assistant used when no user-selected assistant is available. */
@@ -159,3 +159,34 @@ exports.localFoldersToolIds = {
     trash: "00mukk9dwejbuehqzszpyxefx",
     purgeTrash: "00mukk9dwe6co8gvuy44kmuzd",
 };
+/**
+ * Contract id for the local-only System HTTP surface.
+ * Host-mediated fetch for isolated packages. Not available over device-to-device connections.
+ */
+exports.httpContractId = "00muxgugn4tzd527r3cwnie2o";
+/** Stable IDs for tools in System HTTP v1. */
+exports.httpToolIds = {
+    request: "00muxgugn6e3dan5ej6dotzy5",
+    cancel: "00muxgugn6scnni9563focivs",
+    describePolicy: "00muxgugn6kouo2ocpun70q31",
+};
+/**
+ * Contract id for the local-only System Contract Catalog.
+ * Lists every registered provider of a contract version so a hub package can fan out.
+ */
+exports.contractCatalogContractId = "00muxgugn6ncjuunb8r28puae";
+/** Stable IDs for tools in System Contract Catalog v1. */
+exports.contractCatalogToolIds = {
+    listContractProviders: "00muxgugn6ek5apk8d5jtfavp",
+};
+/**
+ * Contract id for the local-only System Scheduler.
+ * Device-local timers that wake an isolated package's own tool. Not synced and not remote.
+ */
+exports.schedulerContractId = "00muxgugn6pj2o0lcu7kxkvrs";
+/** Stable IDs for tools in System Scheduler v1. */
+exports.schedulerToolIds = {
+    schedule: "00muxgugn6t0o5s7239zg6bf5",
+    cancel: "00muxgugn6vqfxpppodqlgfhg",
+    list: "00muxgugn661g0qmpuwafrmsi4",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.25.17",
+  "version": "0.25.19",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"