@peers-app/peers-sdk 0.25.19 → 0.25.21

package/dist/package-installer/package-creator.d.ts

@@ -27,30 +27,39 @@ export declare function ensureTemplateCache(deps: IPackageInstallerDeps, templat
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
  *
- * Idempotent: never rotates an established key. Reuses `existingPublishPublicKey`
- * when present, derives the public key from an existing secret pvar when possible,
- * and only generates a new keypair when both are missing.
+ * Never rotates an established identity. Checks the Packages key, the public key
+ * cached in the personal signing pvar's description, and any key recoverable from
+ * its secret for agreement before writing. Hosts may decrypt legacy secrets via
+ * `resolveSigningPublicKey`; plaintext secrets never need to leave the host.
+ * Lazily caches recovered public keys without changing the stored secret value.
+ * Generates keys only when both the secret and every public-key source are missing.
  *
- * @throws When a readable secret key does not match an established `publishPublicKey`.
+ * @throws When recovered public keys disagree, or a secret has no recoverable public key.
  */
 export declare function ensurePackageSigningKey(opts: {
     personalContext?: DataContext;
     packageId: string;
     packageName: string;
     existingPublishPublicKey?: string;
+    /** Host-only recovery of a public key from an encrypted personal signing secret. */
+    resolveSigningPublicKey?: ICreatePackageOpts["resolveSigningPublicKey"];
 }): Promise<string>;
 /**
  * Import an existing on-disk Peers package directory into the current data context.
  *
  * Validates the manifest packageId, creates/updates the Packages record, persists
  * `packageLocalPath_*`, provisions a signing key when missing, then installs the
- * local dev bundles.
+ * local dev bundles. When the target Packages row is absent, reuses the first
+ * nonblank public key for the same packageId from the user's personal context
+ * or groups. Other contexts' package metadata is not copied.
  */
 export declare function importExistingPackage(dataContext: DataContext, deps: IPackageInstallerDeps, opts: {
     location: string;
     personalContext?: DataContext;
     /** Display name fallback when the manifest name is a slug. */
     displayName?: string;
+    /** Host-only recovery of a public key from an encrypted personal signing secret. */
+    resolveSigningPublicKey?: ICreatePackageOpts["resolveSigningPublicKey"];
 }): Promise<ICreatePackageResult>;
 /**
  * Create a new Peers package from the package template.

package/dist/package-installer/package-creator.js

@@ -106,63 +106,96 @@ async function ensureTemplateCache(deps, templateRepo) {
     await deps.shell.exec(`git clone ${templateRepo} ${cachePath}`);
     return { cachePath };
 }
+const SIGNING_KEY_MARKER_PREFIX = "peers-package-signing-key:";
+function validSigningPublicKey(value) {
+    return typeof value === "string" && (0, keys_1.derivePublicBoxKey)(value) ? value : undefined;
+}
+function cachedSigningPublicKey(description, packageId) {
+    const markers = (description || "")
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith(SIGNING_KEY_MARKER_PREFIX));
+    if (markers.length !== 1)
+        return undefined;
+    const match = /^peers-package-signing-key:v1:([^:]+):([^:]+)$/.exec(markers[0]);
+    return match?.[1] === packageId ? validSigningPublicKey(match[2]) : undefined;
+}
+function signingKeyDescription(description, packageId, publicKey) {
+    const text = description
+        .split(/\r?\n/)
+        .filter((line) => !line.startsWith(SIGNING_KEY_MARKER_PREFIX))
+        .join("\n");
+    return `${text}${text ? "\n" : ""}${SIGNING_KEY_MARKER_PREFIX}v1:${packageId}:${publicKey}`;
+}
 /**
  * Resolve (or create) the Ed25519 publish public key for a package.
  *
- * Idempotent: never rotates an established key. Reuses `existingPublishPublicKey`
- * when present, derives the public key from an existing secret pvar when possible,
- * and only generates a new keypair when both are missing.
+ * Never rotates an established identity. Checks the Packages key, the public key
+ * cached in the personal signing pvar's description, and any key recoverable from
+ * its secret for agreement before writing. Hosts may decrypt legacy secrets via
+ * `resolveSigningPublicKey`; plaintext secrets never need to leave the host.
+ * Lazily caches recovered public keys without changing the stored secret value.
+ * Generates keys only when both the secret and every public-key source are missing.
  *
- * @throws When a readable secret key does not match an established `publishPublicKey`.
+ * @throws When recovered public keys disagree, or a secret has no recoverable public key.
  */
 async function ensurePackageSigningKey(opts) {
     const { personalContext, packageId, packageName, existingPublishPublicKey } = opts;
     const establishedKey = existingPublishPublicKey?.trim() || "";
-    if (personalContext) {
-        const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
-        const existingKey = await (0, persistent_vars_1.PersistentVars)(personalContext).findOne({ name: keyName });
-        const rawSecret = existingKey?.value?.value;
-        if (typeof rawSecret === "string" && rawSecret.length > 0) {
+    if (!personalContext)
+        return establishedKey;
+    const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
+    const table = (0, persistent_vars_1.PersistentVars)(personalContext);
+    const existingKey = await table.findOne({ name: keyName });
+    const rawSecret = existingKey?.value?.value;
+    const cachedKey = cachedSigningPublicKey(existingKey?.description, packageId);
+    let derivedKey;
+    if (typeof rawSecret === "string" && rawSecret.length > 0) {
+        try {
+            derivedKey = validSigningPublicKey((0, keys_1.hydrateKeys)(rawSecret).publicKey);
+        }
+        catch {
+            // Encrypted-at-rest secrets cannot be hydrated directly by the SDK.
+        }
+        if (!derivedKey && opts.resolveSigningPublicKey) {
             try {
-                const derivedPublicKey = (0, keys_1.hydrateKeys)(rawSecret).publicKey;
-                if (establishedKey && derivedPublicKey !== establishedKey) {
-                    throw new Error(`Package signing key mismatch for "${packageName}" (${packageId}): ` +
-                        "stored secret does not match Packages.publishPublicKey. " +
-                        "Refusing to rotate the established key.");
-                }
-                return establishedKey || derivedPublicKey;
+                derivedKey = validSigningPublicKey(await opts.resolveSigningPublicKey(rawSecret));
             }
-            catch (err) {
-                if (err instanceof Error && err.message.includes("signing key mismatch")) {
-                    throw err;
-                }
-                // Secret is likely encrypted at rest — cannot derive here without the user key.
-                if (establishedKey) {
-                    return establishedKey;
-                }
-                throw new Error(`Package "${packageName}" (${packageId}) has a signing secret pvar but no ` +
-                    "publishPublicKey, and the secret could not be hydrated. " +
-                    "Restore publishPublicKey or replace the unreadable key before importing.");
+            catch {
+                // Decryption is best-effort. Never expose ciphertext, plaintext, or host errors.
             }
         }
     }
-    if (establishedKey) {
-        return establishedKey;
+    const publicKey = establishedKey || cachedKey || derivedKey;
+    if ([establishedKey, cachedKey, derivedKey].some((key) => key && key !== publicKey)) {
+        throw new Error(`Package signing key mismatch for "${packageName}" (${packageId}): ` +
+            "Packages.publishPublicKey, cached public key, and stored secret must agree. " +
+            "Refusing to rotate the established key.");
     }
-    if (!personalContext) {
-        return "";
+    if (publicKey) {
+        if (existingKey && validSigningPublicKey(publicKey)) {
+            const description = signingKeyDescription(existingKey.description || "", packageId, publicKey);
+            if (description !== existingKey.description) {
+                // Keep the ciphertext identical so PersistentVarsTable.save does not encrypt it again.
+                await table.save({ ...existingKey, description });
+            }
+        }
+        return publicKey;
+    }
+    if (rawSecret !== undefined && rawSecret !== null && rawSecret !== "") {
+        throw new Error(`Package "${packageName}" (${packageId}) has a signing secret pvar but no ` +
+            "recoverable publishPublicKey, and the secret could not be hydrated. " +
+            "Restore publishPublicKey or unlock the signing secret before importing.");
     }
     const keys = (0, keys_1.newKeys)();
-    const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
-    await (0, persistent_vars_1.PersistentVars)(personalContext).save({
+    await table.save({
         persistentVarId: (0, utils_1.deterministicPvarId)(keyName),
         name: keyName,
         scope: "user",
         value: { value: keys.secretKey },
         isSecret: true,
-        description: `Signing key for package "${packageName}"`,
+        description: signingKeyDescription(`Signing key for package "${packageName}"`, packageId, keys.publicKey),
         modifiedAt: Date.now(),
-    });
+    }, { restoreIfDeleted: true });
     return keys.publicKey;
 }
 async function registerPackageRecord(dataContext, opts) {
@@ -195,7 +228,9 @@ async function persistPackageLocalPath(dataContext, deps, packageId, location) {
  *
  * Validates the manifest packageId, creates/updates the Packages record, persists
  * `packageLocalPath_*`, provisions a signing key when missing, then installs the
- * local dev bundles.
+ * local dev bundles. When the target Packages row is absent, reuses the first
+ * nonblank public key for the same packageId from the user's personal context
+ * or groups. Other contexts' package metadata is not copied.
  */
 async function importExistingPackage(dataContext, deps, opts) {
     const info = await (0, package_installer_1.getPackageInfo)(deps, opts.location);
@@ -204,12 +239,30 @@ async function importExistingPackage(dataContext, deps, opts) {
     }
     const packageId = info.packageId;
     const existing = await (0, packages_1.Packages)(dataContext).get(packageId);
+    let existingPublishPublicKey = existing?.publishPublicKey;
+    const userContext = dataContext.userContext;
+    if (!existing && userContext) {
+        for (const sourceContext of [
+            userContext.userDataContext,
+            ...userContext.groupDataContexts.values(),
+        ]) {
+            if (sourceContext.dataContextId === dataContext.dataContextId)
+                continue;
+            const sourcePackage = await (0, packages_1.Packages)(sourceContext).get(packageId);
+            const sourcePublicKey = sourcePackage?.publishPublicKey?.trim();
+            if (sourcePublicKey) {
+                existingPublishPublicKey = sourcePublicKey;
+                break;
+            }
+        }
+    }
     const packageName = opts.displayName || info.name || packageId;
     const publishPublicKey = await ensurePackageSigningKey({
         personalContext: opts.personalContext,
         packageId,
         packageName,
-        existingPublishPublicKey: existing?.publishPublicKey,
+        existingPublishPublicKey,
+        resolveSigningPublicKey: opts.resolveSigningPublicKey,
     });
     await registerPackageRecord(dataContext, {
         packageId,
@@ -248,6 +301,7 @@ async function createPackage(dataContext, deps, opts) {
             location,
             personalContext: opts.personalContext,
             displayName: opts.name,
+            resolveSigningPublicKey: opts.resolveSigningPublicKey,
         });
     }
     await (0, package_dev_tools_1.assertPackageDevTools)(deps);
@@ -313,6 +367,7 @@ async function createPackage(dataContext, deps, opts) {
         personalContext: opts.personalContext,
         packageId,
         packageName: opts.name,
+        resolveSigningPublicKey: opts.resolveSigningPublicKey,
     });
     await registerPackageRecord(dataContext, {
         packageId,

package/dist/package-installer/package-creator.test.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const system_ids_1 = require("../system-ids");
+const utils_1 = require("../utils");
 const package_creator_1 = require("./package-creator");
 const package_dev_tools_1 = require("./package-dev-tools");
 // --- Mocks for SDK internals ---
 const mockSignAndSavePkg = jest.fn();
 const mockGetPkg = jest.fn();
 jest.mock("../data/packages", () => ({
-    Packages: () => ({
-        signAndSave: mockSignAndSavePkg,
-        get: mockGetPkg,
+    Packages: (dataContext) => ({
+        signAndSave: (...args) => mockSignAndSavePkg(dataContext, ...args),
+        get: (packageId) => mockGetPkg(dataContext, packageId),
     }),
 }));
 const mockGroupDeviceVar = jest.fn();
@@ -36,6 +38,10 @@ jest.mock("./package-installer", () => ({
     installPackageFromBundles: (...args) => mockInstallPackageFromBundles(...args),
     getPackageInfo: (...args) => mockGetPackageInfo(...args),
 }));
+const { newKeys: realNewKeys } = jest.requireActual("../keys");
+const generatedKeys = realNewKeys();
+const sourceKeys = realNewKeys();
+const targetKeys = realNewKeys();
 // --- Test utilities ---
 function makeMockDeps(files, shellExec) {
     return {
@@ -67,6 +73,7 @@ function makeMockDeps(files, shellExec) {
 }
 function mockDataContext() {
     return {
+        dataContextId: (0, utils_1.newid)(),
         packageLoader: {
             loadPackage: jest.fn().mockResolvedValue(undefined),
         },
@@ -75,13 +82,10 @@ function mockDataContext() {
 // --- Tests ---
 beforeEach(() => {
     jest.clearAllMocks();
-    mockGetPkg.mockResolvedValue(undefined);
-    mockPersistentVarsFindOne.mockResolvedValue(undefined);
-    mockNewKeys.mockReturnValue({
-        publicKey: "test-public-key-abc",
-        secretKey: "test-secret-key-xyz",
-        publicBoxKey: "test-box-key",
-    });
+    mockGetPkg.mockReset().mockResolvedValue(undefined);
+    mockPersistentVarsFindOne.mockReset().mockResolvedValue(undefined);
+    mockNewKeys.mockReturnValue(generatedKeys);
+    mockPersistentVarsSave.mockReset();
 });
 describe("unwrapAddOrUpdatePackageResult", () => {
     it("accepts a legacy packageId string", () => {
@@ -204,7 +208,7 @@ describe("createPackage", () => {
             cwd: "/packages/my-widget",
         });
         // Verify package record was created
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             name: "My Widget",
             disabled: false,
         }), { restoreIfDeleted: true, saveAsSnapshot: true });
@@ -273,18 +277,18 @@ describe("createPackage", () => {
             personalContext: personalCtx,
         });
         expect(deps.shell.exec).not.toHaveBeenCalled();
-        expect(mockGetPkg).toHaveBeenCalledWith("00mnkoyo7mizav6tseubjzr3a");
+        expect(mockGetPkg).toHaveBeenCalledWith(dc, "00mnkoyo7mizav6tseubjzr3a");
         expect(mockNewKeys).toHaveBeenCalled();
         expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
             name: "packageSigningKey_00mnkoyo7mizav6tseubjzr3a",
             isSecret: true,
-            value: { value: "test-secret-key-xyz" },
-        }));
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+            value: { value: generatedKeys.secretKey },
+        }), { restoreIfDeleted: true });
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             packageId: "00mnkoyo7mizav6tseubjzr3a",
             name: "Existing Pkg",
             description: "Imported package",
-            publishPublicKey: "test-public-key-abc",
+            publishPublicKey: generatedKeys.publicKey,
         }), { restoreIfDeleted: true, saveAsSnapshot: true });
         expect(mockGroupDeviceVar).toHaveBeenCalledWith("packageLocalPath_00mnkoyo7mizav6tseubjzr3a", expect.any(Object));
         expect(pvarSetter).toHaveBeenCalledWith("/custom/path");
@@ -324,11 +328,145 @@ describe("createPackage", () => {
         });
         expect(mockNewKeys).not.toHaveBeenCalled();
         expect(mockPersistentVarsSave).not.toHaveBeenCalled();
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             publishPublicKey: "already-established-public-key",
             createdBy: "00m87fbwu96jzf8qnwllly0fd",
         }), expect.any(Object));
     });
+    describe("importing by name across contexts", () => {
+        const packageId = "00mnkoyo7mizav6tseubjzr3a";
+        let contexts;
+        let deps;
+        beforeEach(() => {
+            contexts = {
+                personal: mockDataContext(),
+                blankGroup: mockDataContext(),
+                group: mockDataContext(),
+                otherGroup: mockDataContext(),
+            };
+            const userContext = {
+                userId: contexts.personal.dataContextId,
+                userDataContext: contexts.personal,
+                groupDataContexts: new Map(Object.values(contexts)
+                    .slice(1)
+                    .map((dc) => [dc.dataContextId, dc])),
+            };
+            for (const dc of Object.values(contexts))
+                dc.userContext = userContext;
+            deps = makeMockDeps({ "/packages/existing-pkg/package.json": "{}" });
+            mockGetPackageInfo.mockResolvedValue({ packageId, description: "Imported package" });
+            mockGroupDeviceVar.mockReturnValue(jest.fn());
+            mockInstallPackageFromBundles.mockResolvedValue({ packageVersion: { packageId } });
+            mockPersistentVarsFindOne.mockResolvedValue({ value: { value: "unreadable-secret" } });
+        });
+        it.each([
+            ["group", "personal", ["personal", "blankGroup", "group"]],
+            ["group", "otherGroup", ["otherGroup", "personal", "blankGroup", "group"]],
+            ["personal", "group", ["group", "personal"]],
+        ])("reuses the key from %s when importing into %s", async (source, target, lookups) => {
+            mockGetPkg.mockImplementation(async (dc, id) => {
+                if (id !== packageId || dc === contexts[target])
+                    return undefined;
+                if (dc === contexts[source]) {
+                    return {
+                        publishPublicKey: sourceKeys.publicKey,
+                        name: "Source name",
+                        description: "Source description",
+                        createdBy: (0, utils_1.newid)(),
+                        disabled: true,
+                        activePackageVersionId: (0, utils_1.newid)(),
+                        versionFollowRange: "^1.0.0",
+                        followVersionTags: ["stable"],
+                        updateUrl: "source-url",
+                        remoteRepo: "source-repo",
+                        signature: "source-signature",
+                    };
+                }
+                if (dc === contexts.personal || dc === contexts.blankGroup) {
+                    return { publishPublicKey: " \t " };
+                }
+                return undefined;
+            });
+            const result = await (0, package_creator_1.createPackage)(contexts[target], deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            });
+            expect(mockGetPkg.mock.calls).toEqual(lookups.map((name) => [contexts[name], packageId]));
+            expect(mockSignAndSavePkg).toHaveBeenCalledWith(contexts[target], expect.objectContaining({
+                packageId,
+                name: "Existing Pkg",
+                description: "Imported package",
+                publishPublicKey: sourceKeys.publicKey,
+                createdBy: system_ids_1.peersRootUserId,
+                disabled: false,
+                activePackageVersionId: undefined,
+                versionFollowRange: undefined,
+                followVersionTags: undefined,
+                updateUrl: undefined,
+                remoteRepo: undefined,
+                signature: "",
+            }), { restoreIfDeleted: true, saveAsSnapshot: true });
+            expect(mockInstallPackageFromBundles).toHaveBeenCalledWith(contexts[target], deps, packageId, {
+                localPath: "/packages/existing-pkg",
+            });
+            expect(result.packageVersion).toEqual({ packageId });
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+                value: { value: "unreadable-secret" },
+                description: expect.stringContaining(`v1:${packageId}:${sourceKeys.publicKey}`),
+            }));
+        });
+        it("keeps the target key without looking up a differing source key", async () => {
+            mockGetPkg.mockImplementation(async (dc) => ({
+                publishPublicKey: dc === contexts.otherGroup ? targetKeys.publicKey : sourceKeys.publicKey,
+            }));
+            await (0, package_creator_1.createPackage)(contexts.otherGroup, deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            });
+            expect(mockGetPkg.mock.calls).toEqual([[contexts.otherGroup, packageId]]);
+            expect(mockSignAndSavePkg).toHaveBeenCalledWith(contexts.otherGroup, expect.objectContaining({ publishPublicKey: targetKeys.publicKey }), expect.any(Object));
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+                value: { value: "unreadable-secret" },
+                description: expect.stringContaining(`v1:${packageId}:${targetKeys.publicKey}`),
+            }));
+        });
+        it.each([
+            "missing",
+            "mismatch",
+            "lookup-error",
+            "empty-target",
+        ])("fails without installing or changing keys for %s", async (failure) => {
+            mockGetPkg.mockImplementation(async (dc) => {
+                if (dc === contexts.otherGroup) {
+                    return failure === "empty-target" ? { publishPublicKey: "" } : undefined;
+                }
+                if (failure === "lookup-error")
+                    throw new Error("source lookup failed");
+                return failure === "missing" ? undefined : { publishPublicKey: sourceKeys.publicKey };
+            });
+            if (failure === "mismatch") {
+                const { newKeys: realNewKeys } = jest.requireActual("../keys");
+                mockPersistentVarsFindOne.mockResolvedValue({ value: { value: realNewKeys().secretKey } });
+            }
+            await expect((0, package_creator_1.createPackage)(contexts.otherGroup, deps, {
+                name: "Existing Pkg",
+                personalContext: contexts.personal,
+            })).rejects.toThrow(failure === "mismatch"
+                ? "signing key mismatch"
+                : failure === "lookup-error"
+                    ? "source lookup failed"
+                    : "secret could not be hydrated");
+            if (failure === "empty-target") {
+                expect(mockGetPkg.mock.calls).toEqual([[contexts.otherGroup, packageId]]);
+            }
+            expect(mockSignAndSavePkg).not.toHaveBeenCalled();
+            expect(mockInstallPackageFromBundles).not.toHaveBeenCalled();
+            expect(mockNewKeys).not.toHaveBeenCalled();
+            expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        });
+    });
     it("throws when directory exists but has no valid package", async () => {
         const deps = makeMockDeps({});
         const dc = mockDataContext();
@@ -410,13 +548,13 @@ describe("createPackage", () => {
         expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
             name: expect.stringMatching(/^packageSigningKey_[a-z0-9]{25}$/),
             scope: "user",
-            value: { value: "test-secret-key-xyz" },
+            value: { value: generatedKeys.secretKey },
             isSecret: true,
             description: expect.stringContaining("Signed Pkg"),
-        }));
+        }), { restoreIfDeleted: true });
         // Verify publishPublicKey was set on the package record
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
-            publishPublicKey: "test-public-key-abc",
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
+            publishPublicKey: generatedKeys.publicKey,
         }), expect.any(Object));
     });
     it("skips key generation when personalContext is not provided", async () => {
@@ -441,7 +579,7 @@ describe("createPackage", () => {
         // Should NOT save any pvar
         expect(mockPersistentVarsSave).not.toHaveBeenCalled();
         // publishPublicKey should be empty string
-        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(dc, expect.objectContaining({
             publishPublicKey: "",
         }), expect.any(Object));
     });
@@ -454,9 +592,14 @@ describe("ensurePackageSigningKey", () => {
             packageId: "00mnkoyo7mizav6tseubjzr3a",
             packageName: "Test Pkg",
         });
-        expect(publicKey).toBe("test-public-key-abc");
+        expect(publicKey).toBe(generatedKeys.publicKey);
         expect(mockNewKeys).toHaveBeenCalledTimes(1);
         expect(mockPersistentVarsSave).toHaveBeenCalledTimes(1);
+        expect(mockPersistentVarsSave).toHaveBeenCalledWith(expect.objectContaining({
+            persistentVarId: (0, utils_1.deterministicPvarId)("packageSigningKey_00mnkoyo7mizav6tseubjzr3a"),
+            value: { value: generatedKeys.secretKey },
+            description: `Signing key for package "Test Pkg"\npeers-package-signing-key:v1:00mnkoyo7mizav6tseubjzr3a:${generatedKeys.publicKey}`,
+        }), { restoreIfDeleted: true });
     });
     it("reuses an established publishPublicKey without generating a new key", async () => {
         const personalCtx = mockDataContext();
@@ -489,6 +632,148 @@ describe("ensurePackageSigningKey", () => {
         expect(mockNewKeys).not.toHaveBeenCalled();
     });
 });
+describe("signing key recovery after uninstall", () => {
+    const packageId = "00mnkoyo7mizav6tseubjzr3a";
+    const marker = `peers-package-signing-key:v1:${packageId}:${generatedKeys.publicKey}`;
+    let record;
+    let deps;
+    let personalContext;
+    let target;
+    beforeEach(() => {
+        personalContext = mockDataContext();
+        target = mockDataContext();
+        record = {
+            persistentVarId: (0, utils_1.deterministicPvarId)(`packageSigningKey_${packageId}`),
+            name: `packageSigningKey_${packageId}`,
+            scope: "user",
+            isSecret: true,
+            value: { value: "encrypted-secret~nonce" },
+            description: 'Signing key for package "Test Pkg"',
+            modifiedAt: 123,
+        };
+        mockPersistentVarsFindOne.mockImplementation(async () => record);
+        mockPersistentVarsSave.mockImplementation(async (saved) => {
+            record = saved;
+        });
+        deps = makeMockDeps({ "/packages/test-pkg/package.json": "{}" });
+        mockGetPackageInfo.mockResolvedValue({ packageId, name: "test-pkg" });
+        mockGroupDeviceVar.mockReturnValue(jest.fn());
+        mockInstallPackageFromBundles.mockResolvedValue({ packageVersion: { packageId } });
+    });
+    async function importPackage(resolveSigningPublicKey) {
+        return (0, package_creator_1.createPackage)(target, deps, {
+            name: "Test Pkg",
+            personalContext,
+            resolveSigningPublicKey,
+        });
+    }
+    function expectNoWrites() {
+        expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        expect(mockNewKeys).not.toHaveBeenCalled();
+        expect(mockSignAndSavePkg).not.toHaveBeenCalled();
+        expect(mockGroupDeviceVar).not.toHaveBeenCalled();
+        expect(mockInstallPackageFromBundles).not.toHaveBeenCalled();
+    }
+    it("recovers a cached public key with no Packages row or decryption callback", async () => {
+        record.description += `\n${marker}`;
+        await importPackage();
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(target, expect.objectContaining({ publishPublicKey: generatedKeys.publicKey }), expect.any(Object));
+        expect(mockPersistentVarsSave).not.toHaveBeenCalled();
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it("recovers a legacy encrypted secret through the host and backfills only description once", async () => {
+        const original = { ...record };
+        const resolve = jest.fn(async () => generatedKeys.publicKey);
+        await importPackage(resolve);
+        expect(resolve).toHaveBeenCalledWith(original.value.value);
+        expect(mockPersistentVarsSave).toHaveBeenCalledWith({
+            ...original,
+            description: `${original.description}\n${marker}`,
+        });
+        await importPackage(resolve);
+        expect(mockPersistentVarsSave).toHaveBeenCalledTimes(1);
+        expect(record.value).toBe(original.value);
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it("retains raw-secret hydration and backfills its public key without invoking the host", async () => {
+        record.value = { value: generatedKeys.secretKey };
+        const resolve = jest.fn();
+        await importPackage(resolve);
+        expect(resolve).not.toHaveBeenCalled();
+        expect(record.description).toContain(marker);
+        expect(record.value.value).toBe(generatedKeys.secretKey);
+    });
+    it.each([
+        "absent",
+        "throws",
+        "undefined",
+        "invalid",
+    ])("fails safely when host recovery is %s", async (mode) => {
+        const resolve = mode === "absent"
+            ? undefined
+            : jest.fn(async () => {
+                if (mode === "throws")
+                    throw new Error(`sensitive ${record.value.value} ${generatedKeys.secretKey}`);
+                return mode === "invalid" ? "not-a-public-key" : undefined;
+            });
+        await expect(importPackage(resolve)).rejects.toThrow(`Package "Test Pkg" (${packageId}) has a signing secret pvar but no recoverable publishPublicKey, ` +
+            "and the secret could not be hydrated. Restore publishPublicKey or unlock the signing secret before importing.");
+        expectNoWrites();
+    });
+    it.each([
+        "established",
+        "cached",
+    ])("uses the %s key when host decryption fails", async (source) => {
+        if (source === "cached")
+            record.description += `\n${marker}`;
+        else
+            mockGetPkg.mockResolvedValue({ publishPublicKey: generatedKeys.publicKey });
+        await importPackage(async () => {
+            throw new Error("decryption unavailable");
+        });
+        expect(record.description).toContain(marker);
+        expect(record.value.value).toBe("encrypted-secret~nonce");
+        expect(mockNewKeys).not.toHaveBeenCalled();
+    });
+    it.each([
+        "",
+        `peers-package-signing-key:v2:${packageId}:${generatedKeys.publicKey}`,
+        `peers-package-signing-key:v1:${(0, utils_1.newid)()}:${generatedKeys.publicKey}`,
+        `peers-package-signing-key:v1:${packageId}:invalid-key`,
+        `${marker}:extra`,
+        `prefix ${marker}`,
+        `${marker}\n${marker}`,
+    ])("does not trust malformed or unrelated metadata: %s", async (description) => {
+        record.description = description;
+        await expect(importPackage()).rejects.toThrow("secret could not be hydrated");
+        expectNoWrites();
+    });
+    it("repairs malformed metadata after recovering a valid key", async () => {
+        record.description += `\npeers-package-signing-key:v1:${packageId}:invalid`;
+        await importPackage(async () => generatedKeys.publicKey);
+        expect(record.description).toBe(`Signing key for package "Test Pkg"\n${marker}`);
+        expect(record.value.value).toBe("encrypted-secret~nonce");
+    });
+    it.each([
+        "established/cache",
+        "raw/cache",
+        "host/cache",
+        "host/established",
+    ])("rejects a %s mismatch before writes", async (source) => {
+        if (source.endsWith("cache"))
+            record.description += `\n${marker}`;
+        if (source.startsWith("established") || source.endsWith("established")) {
+            mockGetPkg.mockResolvedValue({ publishPublicKey: sourceKeys.publicKey });
+        }
+        if (source === "raw/cache")
+            record.value = { value: sourceKeys.secretKey };
+        const resolve = source.startsWith("host")
+            ? async () => (source.endsWith("cache") ? sourceKeys.publicKey : generatedKeys.publicKey)
+            : undefined;
+        await expect(importPackage(resolve)).rejects.toThrow("signing key mismatch");
+        expectNoWrites();
+    });
+});
 describe("ensureTemplateCache", () => {
     it("clones template when cache directory does not exist", async () => {
         const deps = makeMockDeps({});

package/dist/package-installer/types.d.ts

@@ -83,6 +83,14 @@ export interface ICreatePackageOpts {
      * personal storage isn't available). The migration script backfills these.
      */
     personalContext?: import("../context/data-context").DataContext;
+    /**
+     * Optional host-only recovery for an encrypted personal signing secret. Return
+     * only its Ed25519 public key, or `undefined` when recovery is unavailable.
+     * Called after raw hydration fails, including when a public key is already known
+     * so mismatches can be rejected. Errors are suppressed without logging secret
+     * material; existing or cached public keys remain usable when decryption fails.
+     */
+    resolveSigningPublicKey?: (encryptedSecret: string) => Promise<string | undefined>;
 }
 /** Why a `git pull` of the cached package template did not succeed. */
 export type TemplateCacheRefreshFailure = "offline" | "could-not-refresh";

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

@@ -72,6 +72,8 @@ export interface IIsolatedPackageNetworkCredential {
  *
  * Honored at install the same way `suggestedAccessLevel` is: there is no
  * separate approval step yet. The Packages screen displays the declaration.
+ * This constrains the System HTTP bridge in both execution modes. Privileged
+ * providers can also use Node's network APIs directly, outside this policy.
  */
 export interface IIsolatedPackageNetwork {
     allowedHosts: string[];
@@ -152,11 +154,21 @@ export interface IIsolatedActionAlias {
 export interface IIsolatedPackageManifest {
     packageId: string;
     version: string;
+    /**
+     * Provider execution backend. Omission selects the SES sandbox. Privileged
+     * providers run as trusted code in a separate Node process with the host's
+     * OS account, environment, working directory, and unrestricted OS access;
+     * this does not elevate to root/admin and does not apply to UI code.
+     */
+    executionMode?: "sandbox" | "privileged";
     provides: IIsolatedProvidedContract[];
     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. */
+    /**
+     * System HTTP allowlist and credentials. Omit to deny requests through that bridge.
+     * Privileged providers retain direct OS/network access.
+     */
     network?: IIsolatedPackageNetwork;
     appNavs?: IAppNav[];
     /** Private checked targets, independent of the frozen Voice Skill catalog. */
@@ -164,7 +176,7 @@ export interface IIsolatedPackageManifest {
 }
 /**
  * Installable isolated package: declarative manifest plus provider source
- * that may run only inside a supervised worker.
+ * that runs only inside a supervised sandbox worker or privileged Node process.
  */
 export interface IIsolatedPackageArtifact {
     manifest: IIsolatedPackageManifest;

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

@@ -587,10 +587,16 @@ function validateIsolatedPackageArtifact(artifact) {
         "network",
         "appNavs",
         "actionAliases",
+        "executionMode",
     ], "manifest");
     if (typeof providerSource !== "string" || providerSource.trim() === "") {
         throw new Error("Package artifact.providerSource must be a non-empty string");
     }
+    if (manifest.executionMode !== undefined &&
+        manifest.executionMode !== "sandbox" &&
+        manifest.executionMode !== "privileged") {
+        throw new Error('manifest.executionMode must be "sandbox" or "privileged"');
+    }
     assertPeerId(manifest.packageId, "packageId");
     if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
         throw new Error("package version is required");

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

@@ -40,6 +40,40 @@ function makeArtifact(overrides = {}) {
     };
 }
 describe("isolated package artifact", () => {
+    test.each([
+        undefined,
+        "sandbox",
+        "privileged",
+    ])("round-trips executionMode=%s without changing the legacy envelope", (executionMode) => {
+        const { artifact } = makeArtifact();
+        if (executionMode !== undefined)
+            artifact.manifest.executionMode = executionMode;
+        const bundle = (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact);
+        const parsed = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundle);
+        expect(parsed.manifest.executionMode).toBe(executionMode);
+        expect((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(parsed)).toBe(bundle);
+        if (executionMode === undefined)
+            expect(bundle).not.toContain("executionMode");
+    });
+    test.each([
+        null,
+        true,
+        false,
+        1,
+        "",
+        "node",
+        "Privileged",
+        {},
+        [],
+    ])("rejects malformed executionMode=%p at validation and parse time", (executionMode) => {
+        const { artifact } = makeArtifact();
+        Object.assign(artifact.manifest, { executionMode });
+        const bundle = `${isolated_artifact_1.ISOLATED_PACKAGE_MAGIC}\n${JSON.stringify(artifact)}\n`;
+        expect((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(bundle)).toBe(true);
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/executionMode/);
+        expect(() => (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundle)).toThrow(/executionMode/);
+        expect(() => (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)).toThrow(/executionMode/);
+    });
     test("round-trips a generic authority request and rejects unknown modes", () => {
         const { artifact } = makeArtifact();
         const tool = artifact.manifest.provides[0].tools[0];

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

@@ -252,7 +252,12 @@ describe("PackageLoader isolated artifacts", () => {
         (0, isolated_runtime_1.setIsolatedPackageRuntimeFactory)(() => runtime);
         return runtime;
     }
-    it("installs a valid isolated artifact without evaluating provider source", async () => {
+    it.each([
+        undefined,
+        "sandbox",
+        "privileged",
+    ])("installs executionMode=%s without host evaluation", async (executionMode) => {
+        artifact.manifest.executionMode = executionMode;
         const runtime = makeRuntime();
         mockGet.mockResolvedValue(selectedVersion());
         mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
@@ -405,6 +410,21 @@ describe("PackageLoader isolated artifacts", () => {
         await expect(loader.loadPackage(pkg)).rejects.toThrow(/JSON is invalid/);
         expect(globalThis.__shouldNotEvalOnHost).toBeUndefined();
     });
+    it.each([
+        null,
+        true,
+        "unknown",
+    ])("fails closed on malformed executionMode=%p", async (executionMode) => {
+        const runtime = makeRuntime();
+        mockGet.mockResolvedValue(selectedVersion());
+        const malformed = structuredClone(artifact);
+        Object.assign(malformed.manifest, { executionMode });
+        mockGetFileContents.mockResolvedValue(Buffer.from(`PEERS_ISOLATED_PACKAGE_V1\n${JSON.stringify(malformed)}`));
+        const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-bad-mode" });
+        await expect(loader.loadPackage(pkg)).rejects.toThrow(/executionMode/);
+        expect(runtime.install).not.toHaveBeenCalled();
+        expect(globalThis.__shouldNotEvalOnHost).toBeUndefined();
+    });
     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: [] })),

package/package.json

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