@peers-app/peers-sdk 0.25.18 → 0.25.19

package/dist/package-loader/host-authority-loading.test.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+test("host-backed package endpoints honor declared propagation and reread live metadata", async () => {
+    const packageId = (0, index_1.newid)();
+    const contractId = (0, index_1.newid)();
+    const userId = (0, index_1.newid)();
+    const groupId = (0, index_1.newid)();
+    const dataContext = {
+        dataContextId: groupId,
+        groupId,
+        tableContainer: {
+            getTable: (meta) => meta.name === "Groups"
+                ? { get: async () => ({ founderUserId: (0, index_1.newid)() }) }
+                : { findOne: async () => ({ userId, role: index_1.GroupMemberRole.Admin }) },
+        },
+    };
+    Object.assign(dataContext, {
+        userContext: {
+            userId,
+            deviceId: () => (0, index_1.newid)(),
+            loadingPromise: Promise.resolve(),
+            userDataContext: dataContext,
+            getDataContext: () => dataContext,
+        },
+    });
+    const loader = new index_1.PackageLoader(dataContext);
+    const make = (name, level, fn) => ({
+        tool: {
+            toolId: (0, index_1.newid)(),
+            name,
+            accessLevel: level,
+            code: "",
+            usageDescription: name,
+            inputSchema: { type: index_1.IOSchemaType.simple, fields: [] },
+            outputSchema: { type: index_1.IOSchemaType.simple, fields: [] },
+        },
+        toolFn: fn,
+    });
+    const route = make("route", 20, (_, ctx) => ctx.dispatchAction("act", {}));
+    route.tool.authorityPropagation = "preserve";
+    const effect = jest.fn(() => "admin target");
+    (0, index_1.registerContractResolver)(contractId, 1, () => ({
+        contractId,
+        version: 1,
+        tools: { route },
+        actionAliases: { act: "target" },
+        actionTools: { target: make("target", 60, effect) },
+    }), { providerPackageId: packageId });
+    loader.contractRegistry.register(packageId, {
+        contractId,
+        version: 1,
+        name: "Arbitrary",
+        description: "",
+        tools: [{ name: "route", usageDescription: "route", inputFields: [], outputFields: [] }],
+        tables: [],
+        observables: [],
+        events: [],
+    });
+    const endpoint = await loader.resolveContractEndpoint({
+        contractId,
+        version: 1,
+        providerPackageId: packageId,
+        context: { callerUserId: userId, dataContext },
+        notify: async () => undefined,
+    });
+    const call = {
+        contractId,
+        version: 1,
+        member: "tool",
+        name: "route",
+        operation: "run",
+        args: [{}],
+        dataContextId: groupId,
+    };
+    try {
+        await expect(endpoint.handleCall(call)).resolves.toBe("admin target");
+        // Metadata is read on every call: an ordinary Reader wrapper caps the Admin at Reader.
+        route.tool.authorityPropagation = "cap";
+        await expect(endpoint.handleCall(call)).rejects.toThrow("strict delegation");
+        expect(effect).toHaveBeenCalledTimes(1);
+    }
+    finally {
+        endpoint.dispose();
+        await loader.dispose();
+    }
+});

package/dist/package-loader/host-dispatch-policy.test.d.ts

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

package/dist/package-loader/host-dispatch-policy.test.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+it("host dispatch honors preferred providers, missing-provider policy, and owner pinning", async () => {
+    const dataContext = { dataContextId: (0, index_1.newid)() };
+    const loader = new index_1.PackageLoader(dataContext);
+    const caller = (0, index_1.newid)();
+    const preferred = (0, index_1.newid)();
+    const alternate = (0, index_1.newid)();
+    const contractId = (0, index_1.newid)();
+    const definition = {
+        contractId,
+        version: 1,
+        name: "Target",
+        description: "",
+        tables: [],
+        events: [],
+        observables: [],
+        tools: [{ name: "target", usageDescription: "", inputFields: [], outputFields: [] }],
+    };
+    loader.contractRegistry.register(alternate, definition);
+    loader.contractRegistry.register(preferred, definition);
+    loader.hostConsumes.set(caller, [
+        { contractId, version: 1, providerPackageIds: [preferred], fallbackToDefaultProvider: false },
+    ]);
+    const resolve = jest
+        .spyOn(loader, "resolveContractEndpoint")
+        .mockImplementation(async (request) => ({ handleCall: async () => request.providerPackageId, dispose: () => undefined }));
+    const context = {
+        dataContext,
+        callerUserId: (0, index_1.newid)(),
+        authority: {
+            userId: (0, index_1.newid)(),
+            userAccessLevel: 60,
+            assistantAccessLevel: 40,
+            strictActionScope: true,
+        },
+    };
+    const dispatch = (providerPackageId) => loader.dispatchToolFromProvider(caller, { contractId, version: 1, toolName: "target", providerPackageId }, {}, context);
+    try {
+        await expect(dispatch()).resolves.toBe(preferred);
+        await expect(dispatch(alternate)).rejects.toThrow("Provider substitution");
+        loader.contractRegistry.unregister(preferred);
+        await expect(dispatch()).rejects.toThrow("No declared contract provider");
+        loader.hostConsumes.get(caller)[0].fallbackToDefaultProvider = true;
+        await expect(dispatch()).resolves.toBe(alternate);
+        loader.contractRegistry.register(caller, definition);
+        loader.hostConsumes.delete(caller);
+        await expect(dispatch(alternate)).rejects.toThrow("Provider substitution");
+        await expect(dispatch()).resolves.toBe(caller);
+        expect(resolve).toHaveBeenCalledTimes(3);
+    }
+    finally {
+        await loader.dispose();
+    }
+});

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

@@ -22,7 +22,8 @@ export interface IIsolatedContractToolRef {
  *
  * Shape matches {@link IContractTool}. `suggestedAccessLevel` is the default
  * effective level until install-time approval exists and calls `approveTool`.
- * Omit it to keep the fail-closed Self default.
+ * Omitted admission is None (0) for a preservation request, otherwise fail-closed Self (100).
+ * Operator approval changes propagation, never admission.
  */
 export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields" | "outputFields"> {
     /** Defaults to `[]` during validation when omitted. */
@@ -33,9 +34,13 @@ export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields"
      * Default effective access level for this tool.
      *
      * Used until an administrator explicitly approves the tool at install time.
-     * Omit to keep the fail-closed Self default.
+     * Omit for None (0) when requesting preservation; other tools default to Self (100).
      */
     suggestedAccessLevel?: number;
+    /** Declared outgoing authority mode; `preserve` omits this tool's own level from strict narrowing. */
+    authorityPropagation?: "cap" | "preserve";
+    /** Checked package-internal target, omitted from the public contract definition. */
+    private?: boolean;
     /**
      * Per-invoke deadline in milliseconds for this tool.
      *
@@ -136,6 +141,11 @@ export interface IIsolatedConsumedContract {
     providerPackageIds?: string[];
     fallbackToDefaultProvider?: boolean;
 }
+/** Package-owned catalog selector bound to a registered canonical action. */
+export interface IIsolatedActionAlias {
+    name: string;
+    target: IIsolatedContractToolRef;
+}
 /**
  * Pure-data package description. Validated on the host; never executed there.
  */
@@ -149,6 +159,8 @@ export interface IIsolatedPackageManifest {
     /** Host allowlist and credential refs for System HTTP. Omit to deny outbound HTTP. */
     network?: IIsolatedPackageNetwork;
     appNavs?: IAppNav[];
+    /** Private checked targets, independent of the frozen Voice Skill catalog. */
+    actionAliases?: IIsolatedActionAlias[];
 }
 /**
  * Installable isolated package: declarative manifest plus provider source
@@ -181,6 +193,8 @@ export interface IIsolatedInstalledPackage {
     tables: IIsolatedPackageTable[];
     definitions: IContractDefinition[];
     appNavs?: IAppNav[];
+    /** Private checked targets, independent of the frozen Voice Skill catalog. */
+    actionAliases?: IIsolatedActionAlias[];
 }
 /** Host-contract member guests use to request a consumed-contract tool call. */
 export declare const ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";

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

@@ -241,6 +241,8 @@ function validateProvidedContract(contract, index, packageTables) {
             "inputFields",
             "outputFields",
             "suggestedAccessLevel",
+            "authorityPropagation",
+            "private",
             "remoteAccessLevel",
             "timeoutMs",
         ], toolLabel);
@@ -256,6 +258,12 @@ function validateProvidedContract(contract, index, packageTables) {
         }
         tool.inputFields = validateFields(tool.inputFields, `${toolLabel}.inputFields`);
         tool.outputFields = validateFields(tool.outputFields, `${toolLabel}.outputFields`);
+        if (tool.authorityPropagation !== undefined &&
+            tool.authorityPropagation !== "cap" &&
+            tool.authorityPropagation !== "preserve")
+            throw new Error(`${toolLabel}.authorityPropagation must be cap or preserve`);
+        if (tool.private !== undefined && typeof tool.private !== "boolean")
+            throw new Error(`${toolLabel}.private must be a boolean`);
         if (tool.suggestedAccessLevel !== undefined) {
             if (!Number.isInteger(tool.suggestedAccessLevel) ||
                 tool.suggestedAccessLevel < access_level_1.MIN_ACCESS_LEVEL ||
@@ -570,7 +578,16 @@ 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", "network", "appNavs"], "manifest");
+    assertOnlyKeys(manifest, [
+        "packageId",
+        "version",
+        "provides",
+        "consumes",
+        "tables",
+        "network",
+        "appNavs",
+        "actionAliases",
+    ], "manifest");
     if (typeof providerSource !== "string" || providerSource.trim() === "") {
         throw new Error("Package artifact.providerSource must be a non-empty string");
     }
@@ -598,6 +615,22 @@ function validateIsolatedPackageArtifact(artifact) {
     for (const [index, dep] of manifest.consumes.entries()) {
         validateConsumedContract(dep, index);
     }
+    if (manifest.actionAliases !== undefined) {
+        if (!Array.isArray(manifest.actionAliases))
+            throw new Error("actionAliases must be an array");
+        const names = new Set();
+        for (const alias of manifest.actionAliases) {
+            if (!alias || typeof alias.name !== "string" || !alias.name || names.has(alias.name)) {
+                throw new Error("Invalid or duplicate action alias");
+            }
+            names.add(alias.name);
+            const target = alias.target;
+            if (!target ||
+                !packageProvidesTool(manifest.provides, target.contractId, target.version, target.toolName)) {
+                throw new Error(`Action alias ${alias.name} has no registered target`);
+            }
+        }
+    }
     manifest.appNavs = validateAppNavs(manifest.appNavs);
     validatePackageNetwork(manifest);
     return manifest;
@@ -650,12 +683,16 @@ function serializeIsolatedPackageArtifact(artifact) {
  * @param packageTables - Package-owned schemas available for contract exposure.
  */
 function isolatedContractToDefinition(contract, packageTables) {
-    const tools = contract.tools.map((tool) => ({
+    const tools = contract.tools
+        .filter((tool) => !tool.private)
+        .map((tool) => ({
         name: tool.name,
         usageDescription: tool.usageDescription,
         inputFields: tool.inputFields ?? [],
         outputFields: tool.outputFields ?? [],
-        ...(tool.remoteAccessLevel !== undefined ? { remoteAccessLevel: tool.remoteAccessLevel } : {}),
+        ...(tool.remoteAccessLevel !== undefined
+            ? { remoteAccessLevel: tool.remoteAccessLevel }
+            : {}),
     }));
     const tables = (contract.tables ?? []).map((tableRef) => {
         const table = findPackageTable(packageTables, tableRef.name);

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

@@ -40,6 +40,16 @@ function makeArtifact(overrides = {}) {
     };
 }
 describe("isolated package artifact", () => {
+    test("round-trips a generic authority request and rejects unknown modes", () => {
+        const { artifact } = makeArtifact();
+        const tool = artifact.manifest.provides[0].tools[0];
+        tool.authorityPropagation = "preserve";
+        expect(() => (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)).not.toThrow();
+        expect((0, isolated_artifact_1.parseIsolatedPackageArtifact)((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)).manifest.provides[0]
+            .tools[0]).toMatchObject({ authorityPropagation: "preserve" });
+        tool.authorityPropagation = "elevate";
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/authorityPropagation/);
+    });
     test("serializes and parses a valid envelope", () => {
         const { artifact, contractId } = makeArtifact();
         const bundle = (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact);
@@ -62,6 +72,34 @@ describe("isolated package artifact", () => {
         const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
         expect(manifest.tables).toEqual([]);
     });
+    test("validates private action aliases without extending the public contract", () => {
+        const { artifact, contractId } = makeArtifact();
+        artifact.manifest.provides[0].tools.push({
+            name: "private-write",
+            usageDescription: "Internal write",
+            private: true,
+            suggestedAccessLevel: access_level_1.AccessLevel.Writer,
+        });
+        artifact.manifest.actionAliases = [
+            {
+                name: "write",
+                target: { contractId, version: 1, toolName: "private-write" },
+            },
+        ];
+        const validated = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect((0, isolated_artifact_1.isolatedContractToDefinition)(validated.provides[0], []).tools.map((tool) => tool.name)).toEqual(["greet"]);
+        expect((0, isolated_artifact_1.parseIsolatedPackageArtifact)((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)).manifest
+            .actionAliases).toEqual(artifact.manifest.actionAliases);
+        artifact.manifest.actionAliases.push(artifact.manifest.actionAliases[0]);
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow("duplicate action alias");
+        artifact.manifest.actionAliases = [
+            {
+                name: "write",
+                target: { contractId, version: 1, toolName: "missing" },
+            },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow("no registered target");
+    });
     test("accepts a package-private table without adding it to the contract definition", () => {
         const { artifact } = makeArtifact();
         artifact.manifest.tables = [

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

@@ -15,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;
 }
@@ -86,6 +94,13 @@ export interface IIsolatedPackageRuntime {
      * @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>;
 }

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();
@@ -114,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.
      *
@@ -205,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,
@@ -318,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);
         }
@@ -629,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

@@ -176,7 +176,7 @@ describe("PackageLoader.contractRegistry", () => {
                 name: "invoke",
                 operation: "run",
                 args: [],
-            })).rejects.toThrow("missing caller identity for tool 'invoke'");
+            })).rejects.toThrow("missing caller identity or trusted context for tool 'invoke'");
             expect(write).not.toHaveBeenCalled();
         }
         finally {

package/package.json

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