@peers-app/peers-sdk 0.25.16 → 0.25.18

package/dist/contracts/system/scheduler-contract.d.ts

@@ -0,0 +1,54 @@
+import type { IContractConsumerBase } from "../contract-proxy";
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Scheduler contract. */
+export declare const SCHEDULER_CONTRACT_VERSION = 1;
+/** Package id of the System Scheduler provider. */
+export declare const schedulerProviderPackageId = "000peers0system0000000001";
+/** Furthest a schedule may sit in the future. */
+export declare const SCHEDULER_MAX_DELAY_MS: number;
+/** Input for scheduling a wake-up of the caller's own tool. */
+export interface IScheduleInput {
+    /** Unix epoch milliseconds when the tool should run. */
+    at: number;
+    contractId: string;
+    version: number;
+    toolName: string;
+    payload?: unknown;
+}
+/** One device-local schedule owned by a package. */
+export interface IScheduleInfo {
+    scheduleId: string;
+    packageId: string;
+    dataContextId: string;
+    contractId: string;
+    version: number;
+    toolName: string;
+    at: number;
+}
+/**
+ * Consumer shape for System Scheduler.
+ *
+ * Schedules are stored on this device only. Another device does not run them.
+ */
+export interface ISchedulerConsumer extends IContractConsumerBase {
+    tools: {
+        schedule(input: IScheduleInput): Promise<{
+            scheduleId: string;
+        }>;
+        cancel(input: {
+            scheduleId: string;
+        }): Promise<{
+            cancelled: boolean;
+        }>;
+        list(): Promise<{
+            schedules: IScheduleInfo[];
+        }>;
+    };
+}
+/**
+ * Return the local-only System Scheduler contract shape.
+ *
+ * A package may schedule a tool that it provides. When `at` arrives, the host
+ * starts that package's worker if needed and runs the tool as Self.
+ */
+export declare function getSchedulerContractDefinition(): IContractDefinition;

package/dist/contracts/system/scheduler-contract.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEDULER_MAX_DELAY_MS = exports.schedulerProviderPackageId = exports.SCHEDULER_CONTRACT_VERSION = void 0;
+exports.getSchedulerContractDefinition = getSchedulerContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Scheduler contract. */
+exports.SCHEDULER_CONTRACT_VERSION = 1;
+/** Package id of the System Scheduler provider. */
+exports.schedulerProviderPackageId = system_ids_1.peersSystemPackageId;
+/** Furthest a schedule may sit in the future. */
+exports.SCHEDULER_MAX_DELAY_MS = 366 * 24 * 60 * 60 * 1000;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+let definition;
+/**
+ * Return the local-only System Scheduler contract shape.
+ *
+ * A package may schedule a tool that it provides. When `at` arrives, the host
+ * starts that package's worker if needed and runs the tool as Self.
+ */
+function getSchedulerContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.schedulerContractId,
+        version: exports.SCHEDULER_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Scheduler",
+        description: "Device-local schedules that wake a package's own tool. Schedules do not sync to other devices.",
+        tables: [],
+        tools: [
+            {
+                name: "schedule",
+                usageDescription: "Run one of this package's tools at a future time on this device. Returns a scheduleId.",
+                inputFields: [
+                    field("at", field_type_1.FieldType.number, "Unix epoch milliseconds when the tool should run."),
+                    field("contractId", field_type_1.FieldType.id, "Contract this package provides."),
+                    field("version", field_type_1.FieldType.number, "Contract version."),
+                    field("toolName", field_type_1.FieldType.string, "Tool on that contract to run."),
+                    field("payload", field_type_1.FieldType.any, "JSON value passed to the tool.", { optional: true }),
+                ],
+                outputFields: [field("scheduleId", field_type_1.FieldType.id, "Id to pass to cancel.")],
+            },
+            {
+                name: "cancel",
+                usageDescription: "Cancel a schedule this package created.",
+                inputFields: [field("scheduleId", field_type_1.FieldType.id, "Schedule to cancel.")],
+                outputFields: [
+                    field("cancelled", field_type_1.FieldType.boolean, "True when the schedule existed and was removed."),
+                ],
+            },
+            {
+                name: "list",
+                usageDescription: "List schedules owned by the calling package on this device.",
+                inputFields: [],
+                outputFields: [
+                    field("schedules", field_type_1.FieldType.object, "Schedules with scheduleId, contractId, version, toolName, and at.", { isArray: true }),
+                ],
+            },
+        ],
+        observables: [],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: exports.schedulerProviderPackageId,
+    contractId: system_ids_1.schedulerContractId,
+    version: exports.SCHEDULER_CONTRACT_VERSION,
+    getDefinition: getSchedulerContractDefinition,
+});

package/dist/data/tool-access-approvals.d.ts

@@ -52,8 +52,8 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
     dataContextId: string;
     createdAt: Date;
     expiresAt: Date;
-    toolAccessApprovalId: string;
     toolName: string;
+    toolAccessApprovalId: string;
     argsHash: string;
     argsPreview: string;
     frozenArgs: {} & {
@@ -73,8 +73,8 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
     toolId: string;
     dataContextId: string;
     expiresAt: Date;
-    toolAccessApprovalId: string;
     toolName: string;
+    toolAccessApprovalId: string;
     argsHash: string;
     frozenArgs: {} & {
         [k: string]: any;
@@ -108,8 +108,8 @@ export declare function ToolAccessApprovals(dataContext?: DataContext): import("
     dataContextId: string;
     createdAt: Date;
     expiresAt: Date;
-    toolAccessApprovalId: string;
     toolName: string;
+    toolAccessApprovalId: string;
     argsHash: string;
     argsPreview: string;
     frozenArgs: {} & {

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

@@ -4,3 +4,4 @@ export * from "./isolated-persistent-var-gateway";
 export * from "./isolated-runtime";
 export * from "./isolated-table-gateway";
 export * from "./package-loader";
+export * from "./package-network-policy";

package/dist/package-loader/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./isolated-persistent-var-gateway"), exports);
 __exportStar(require("./isolated-runtime"), exports);
 __exportStar(require("./isolated-table-gateway"), exports);
 __exportStar(require("./package-loader"), exports);
+__exportStar(require("./package-network-policy"), exports);

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

@@ -36,6 +36,41 @@ export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields"
      * Omit to keep the fail-closed Self default.
      */
     suggestedAccessLevel?: number;
+    /**
+     * Per-invoke deadline in milliseconds for this tool.
+     *
+     * When omitted, the runtime's `invokeTimeoutMs` applies. Capped at
+     * {@link ISOLATED_TOOL_TIMEOUT_MAX_MS}. Host calls made during the invoke,
+     * including System HTTP, count against this deadline.
+     */
+    timeoutMs?: number;
+}
+/** Longest per-tool invoke deadline an isolated manifest may declare. */
+export declare const ISOLATED_TOOL_TIMEOUT_MAX_MS = 120000;
+/**
+ * Secret the host may attach to an outbound request.
+ *
+ * The guest passes `ref`. The host reads `secretVar` and sets `header`.
+ */
+export interface IIsolatedPackageNetworkCredential {
+    ref: string;
+    /** Logical persistent-variable name. The host prefixes it with the package id. */
+    secretVar: string;
+    /** Defaults to `user` when omitted. */
+    scope?: "user" | "device";
+    header: string;
+    /** Must contain the literal `{secret}`. */
+    format: string;
+}
+/**
+ * Outbound HTTPS this package is allowed to perform through System HTTP.
+ *
+ * Honored at install the same way `suggestedAccessLevel` is: there is no
+ * separate approval step yet. The Packages screen displays the declaration.
+ */
+export interface IIsolatedPackageNetwork {
+    allowedHosts: string[];
+    credentials?: IIsolatedPackageNetworkCredential[];
 }
 /**
  * Private table schema declared by an isolated package.
@@ -111,6 +146,8 @@ export interface IIsolatedPackageManifest {
     consumes: IIsolatedConsumedContract[];
     /** Package-owned table schemas. Contract references decide public exposure. */
     tables?: IIsolatedPackageTable[];
+    /** Host allowlist and credential refs for System HTTP. Omit to deny outbound HTTP. */
+    network?: IIsolatedPackageNetwork;
     appNavs?: IAppNav[];
 }
 /**

package/dist/package-loader/isolated-artifact.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_PACKAGE_MAGIC = void 0;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
 exports.parseIsolatedPackageArtifact = parseIsolatedPackageArtifact;
@@ -25,6 +25,8 @@ const utils_1 = require("../utils");
  * opt-in format without evaluating source.
  */
 exports.ISOLATED_PACKAGE_MAGIC = "PEERS_ISOLATED_PACKAGE_V1";
+/** Longest per-tool invoke deadline an isolated manifest may declare. */
+exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = 120_000;
 /** Host-contract member guests use to request a consumed-contract tool call. */
 exports.ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
 /** Host-contract member guests use to read or write a package-owned table. */
@@ -240,6 +242,7 @@ function validateProvidedContract(contract, index, packageTables) {
             "outputFields",
             "suggestedAccessLevel",
             "remoteAccessLevel",
+            "timeoutMs",
         ], toolLabel);
         if (typeof tool.name !== "string" || tool.name.trim() === "") {
             throw new Error(`${toolLabel}.name is required`);
@@ -267,6 +270,13 @@ function validateProvidedContract(contract, index, packageTables) {
                 throw new Error(`${toolLabel}.remoteAccessLevel must be an integer 0–100`);
             }
         }
+        if (tool.timeoutMs !== undefined) {
+            if (!Number.isInteger(tool.timeoutMs) ||
+                tool.timeoutMs < 1 ||
+                tool.timeoutMs > exports.ISOLATED_TOOL_TIMEOUT_MAX_MS) {
+                throw new Error(`${toolLabel}.timeoutMs must be an integer from 1 to ${exports.ISOLATED_TOOL_TIMEOUT_MAX_MS}`);
+            }
+        }
     }
     if (contract.tables === undefined) {
         contract.tables = [];
@@ -430,6 +440,72 @@ function validateConsumedContract(dep, index) {
         }
     }
 }
+const NETWORK_HOST_PATTERN = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+const NETWORK_REF_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const NETWORK_HEADER_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
+const NETWORK_SECRET_VAR_PATTERN = /^[A-Za-z][A-Za-z0-9_:-]{0,80}$/;
+function validatePackageNetwork(manifest) {
+    if (manifest.network === undefined) {
+        return;
+    }
+    const network = manifest.network;
+    if (!network || typeof network !== "object" || Array.isArray(network)) {
+        throw new Error("manifest.network must be an object");
+    }
+    assertOnlyKeys(network, ["allowedHosts", "credentials"], "manifest.network");
+    if (!Array.isArray(network.allowedHosts) || network.allowedHosts.length === 0) {
+        throw new Error("manifest.network.allowedHosts must be a non-empty array");
+    }
+    const hosts = new Set();
+    for (const [index, host] of network.allowedHosts.entries()) {
+        if (typeof host !== "string" || !NETWORK_HOST_PATTERN.test(host)) {
+            throw new Error(`manifest.network.allowedHosts[${index}] must be a lowercase hostname with no scheme, port, or path`);
+        }
+        if (host.split(".").every((label) => /^\d+$/.test(label))) {
+            throw new Error(`manifest.network.allowedHosts[${index}] must be a hostname, not an IP address`);
+        }
+        if (hosts.has(host)) {
+            throw new Error(`manifest.network declares duplicate host "${host}"`);
+        }
+        hosts.add(host);
+    }
+    if (network.credentials === undefined) {
+        network.credentials = [];
+    }
+    if (!Array.isArray(network.credentials)) {
+        throw new Error("manifest.network.credentials must be an array");
+    }
+    const refs = new Set();
+    for (const [index, credential] of network.credentials.entries()) {
+        const label = `manifest.network.credentials[${index}]`;
+        if (!credential || typeof credential !== "object" || Array.isArray(credential)) {
+            throw new Error(`${label} must be an object`);
+        }
+        assertOnlyKeys(credential, ["ref", "secretVar", "scope", "header", "format"], label);
+        if (typeof credential.ref !== "string" || !NETWORK_REF_PATTERN.test(credential.ref)) {
+            throw new Error(`${label}.ref must be a short identifier`);
+        }
+        if (refs.has(credential.ref)) {
+            throw new Error(`manifest.network declares duplicate credential ref "${credential.ref}"`);
+        }
+        refs.add(credential.ref);
+        if (typeof credential.secretVar !== "string" ||
+            !NETWORK_SECRET_VAR_PATTERN.test(credential.secretVar)) {
+            throw new Error(`${label}.secretVar must be a logical persistent-variable name`);
+        }
+        if (credential.scope !== undefined &&
+            credential.scope !== "user" &&
+            credential.scope !== "device") {
+            throw new Error(`${label}.scope must be "user" or "device"`);
+        }
+        if (typeof credential.header !== "string" || !NETWORK_HEADER_PATTERN.test(credential.header)) {
+            throw new Error(`${label}.header must be an HTTP header name`);
+        }
+        if (typeof credential.format !== "string" || !credential.format.includes("{secret}")) {
+            throw new Error(`${label}.format must contain {secret}`);
+        }
+    }
+}
 function validateAppNavs(appNavs) {
     if (appNavs === undefined) {
         return undefined;
@@ -494,7 +570,7 @@ function validateIsolatedPackageArtifact(artifact) {
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
         throw new Error("Package artifact.manifest is required");
     }
-    assertOnlyKeys(manifest, ["packageId", "version", "provides", "consumes", "tables", "appNavs"], "manifest");
+    assertOnlyKeys(manifest, ["packageId", "version", "provides", "consumes", "tables", "network", "appNavs"], "manifest");
     if (typeof providerSource !== "string" || providerSource.trim() === "") {
         throw new Error("Package artifact.providerSource must be a non-empty string");
     }
@@ -523,6 +599,7 @@ function validateIsolatedPackageArtifact(artifact) {
         validateConsumedContract(dep, index);
     }
     manifest.appNavs = validateAppNavs(manifest.appNavs);
+    validatePackageNetwork(manifest);
     return manifest;
 }
 /**

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

@@ -315,4 +315,29 @@ describe("isolated package artifact", () => {
         };
         expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/JSON-compatible/);
     });
+    test("accepts a network allowlist and rejects a host with a scheme", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.network = {
+            allowedHosts: ["api.openai.com"],
+            credentials: [
+                {
+                    ref: "openai",
+                    secretVar: "openaiApiKey",
+                    header: "Authorization",
+                    format: "Bearer {secret}",
+                },
+            ],
+        };
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.network?.allowedHosts).toEqual(["api.openai.com"]);
+        artifact.manifest.network = { allowedHosts: ["https://api.openai.com"] };
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/lowercase hostname/);
+        artifact.manifest.network = { allowedHosts: ["127.0.0.1"] };
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/hostname, not an IP address/);
+    });
+    test("rejects a tool timeout above the cap", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].tools[0].timeoutMs = 120_001;
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/timeoutMs/);
+    });
 });

package/dist/package-loader/isolated-persistent-var-gateway.js

@@ -7,6 +7,19 @@ const isolated_value_1 = require("./isolated-value");
 function memoryKey(ref) {
     return `${ref.packageId}:${ref.scope}:${ref.name}`;
 }
+async function assertPackagePersistentVarIsNotSecret(dataContext, ref) {
+    const userContext = dataContext.userContext;
+    if (!userContext) {
+        throw new Error("Package persistent variables require a signed-in user");
+    }
+    const storageContext = ref.scope === "group" ? dataContext : userContext.userDataContext;
+    const storageName = (0, persistent_var_identity_1.packageScopedPersistentVarStorageName)(ref.packageId, ref.name, ref.scope, dataContext.dataContextId);
+    const { PersistentVars } = await Promise.resolve().then(() => require("../data/persistent-vars"));
+    const record = await PersistentVars(storageContext).findOne({ name: storageName });
+    if (record?.isSecret) {
+        throw new Error("Secret persistent variables are not readable by packages");
+    }
+}
 async function resolvePersistentVar(dataContext, ref) {
     const { deviceVar, groupDeviceVar, groupUserVar, groupVar, userVar } = await Promise.resolve().then(() => require("../data/persistent-vars"));
     const name = (0, persistent_var_identity_1.packageScopedPersistentVarName)(ref.packageId, ref.name);
@@ -77,8 +90,10 @@ function createMemoryIsolatedPackagePersistentVarGateway() {
 function createIsolatedPackagePersistentVarGateway(dataContext) {
     return {
         async get(ref) {
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             const persistentVar = await resolvePersistentVar(dataContext, ref);
             await persistentVar.loadingPromise;
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             const value = persistentVar();
             return value === undefined ? undefined : (0, isolated_value_1.copyIsolatedValue)(value);
         },
@@ -86,17 +101,21 @@ function createIsolatedPackagePersistentVarGateway(dataContext) {
             if (value === undefined) {
                 throw new Error("Persistent variable value must be copyable");
             }
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             const persistentVar = await resolvePersistentVar(dataContext, ref);
             const copy = (0, isolated_value_1.copyIsolatedValue)(value);
             await persistentVar.loadingPromise;
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             persistentVar(copy);
             await persistentVar.loadingPromise;
             const saved = persistentVar();
             return saved === undefined ? undefined : (0, isolated_value_1.copyIsolatedValue)(saved);
         },
         async subscribe(ref, handler) {
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             const persistentVar = await resolvePersistentVar(dataContext, ref);
             await persistentVar.loadingPromise;
+            await assertPackagePersistentVarIsNotSecret(dataContext, ref);
             const subscription = persistentVar.subscribe((value) => {
                 handler((0, isolated_value_1.copyIsolatedValue)(value));
             });

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. */
@@ -73,6 +74,18 @@ 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>;
     /** Terminate every worker and drop installed state. */
     dispose(): Promise<void>;
 }
@@ -199,12 +212,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.js

@@ -74,6 +74,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,

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 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;