@peers-app/peers-sdk 0.18.8 → 0.19.6

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

@@ -0,0 +1,55 @@
+/**
+ * Pure artifact builder for publishing Peers packages.
+ *
+ * Accepts bundle contents and a signing callback, produces a signed tarball
+ * and an {@link ILatestPointer}-compatible JSON object. Does not perform any
+ * I/O — callers (the system tool, tests) provide bundle strings and receive
+ * artifacts in memory.
+ */
+import type { IAppNav } from "../types/app-nav";
+import { type IAuthorSignedPayload } from "./package-author-signing";
+import type { ILatestPointer } from "./package-remote-checker";
+import { type ITarballPayload } from "./package-tarball";
+/** Bundle contents to publish. Only `packageBundle` is required. */
+export interface IPublishBundleInput {
+    packageBundle: string;
+    routesBundle?: string;
+    uiBundle?: string;
+}
+/** Options for {@link buildPublishArtifacts}. */
+export interface IBuildPublishArtifactsOpts {
+    packageId: string;
+    version: string;
+    versionTag?: string;
+    bundles: IPublishBundleInput;
+    /**
+     * Callback that signs the author payload and returns a base64url signature.
+     * The private key never leaves the caller's scope.
+     */
+    sign: (payload: IAuthorSignedPayload) => Promise<string> | string;
+    /** Publisher's Ed25519 public key (base64url). */
+    publicKey: string;
+    /** Pre-generated packageVersionId. If omitted, a new one is created via {@link newid}. */
+    packageVersionId?: string;
+    /** App navigation items to include in the tarball metadata. */
+    appNavs?: IAppNav[];
+    /** Peer ID of the publisher. Recorded as `createdBy` on the PV. */
+    createdBy?: string;
+}
+/** Artifacts produced by {@link buildPublishArtifacts}. */
+export interface IPublishArtifacts {
+    tarball: Uint8Array;
+    tarballHash: string;
+    pointer: ILatestPointer;
+    payload: ITarballPayload;
+}
+/**
+ * Build publish artifacts from bundle contents.
+ *
+ * 1. Computes SHA-256 hashes for each bundle.
+ * 2. Builds the author-signed payload.
+ * 3. Calls the `sign` callback to get the detached Ed25519 signature.
+ * 4. Packs everything into a `.peers-pkg.tar.gz`.
+ * 5. Returns the tarball bytes, their SHA-256, and an {@link ILatestPointer}.
+ */
+export declare function buildPublishArtifacts(opts: IBuildPublishArtifactsOpts): Promise<IPublishArtifacts>;

package/dist/package-installer/package-publisher.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Pure artifact builder for publishing Peers packages.
+ *
+ * Accepts bundle contents and a signing callback, produces a signed tarball
+ * and an {@link ILatestPointer}-compatible JSON object. Does not perform any
+ * I/O — callers (the system tool, tests) provide bundle strings and receive
+ * artifacts in memory.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPublishArtifacts = buildPublishArtifacts;
+const file_types_1 = require("../data/files/file.types");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const package_author_signing_1 = require("./package-author-signing");
+const package_tarball_1 = require("./package-tarball");
+/**
+ * Build publish artifacts from bundle contents.
+ *
+ * 1. Computes SHA-256 hashes for each bundle.
+ * 2. Builds the author-signed payload.
+ * 3. Calls the `sign` callback to get the detached Ed25519 signature.
+ * 4. Packs everything into a `.peers-pkg.tar.gz`.
+ * 5. Returns the tarball bytes, their SHA-256, and an {@link ILatestPointer}.
+ */
+async function buildPublishArtifacts(opts) {
+    const { packageId, version, bundles, sign, publicKey } = opts;
+    const versionTag = opts.versionTag ?? "stable";
+    const packageVersionId = opts.packageVersionId ?? (0, utils_1.newid)();
+    const packageBundleFileHash = (0, file_types_1.computeFileHash)(bundles.packageBundle);
+    const routesBundleFileHash = bundles.routesBundle
+        ? (0, file_types_1.computeFileHash)(bundles.routesBundle)
+        : undefined;
+    const uiBundleFileHash = bundles.uiBundle ? (0, file_types_1.computeFileHash)(bundles.uiBundle) : undefined;
+    const now = new Date().toISOString();
+    const pvFields = {
+        packageId,
+        packageVersionId,
+        version,
+        versionTag,
+        packageBundleFileHash,
+        routesBundleFileHash,
+        uiBundleFileHash,
+        appNavs: opts.appNavs,
+        createdBy: opts.createdBy,
+        createdAt: now,
+    };
+    const payload = (0, package_author_signing_1.buildAuthorSignedPayload)(pvFields, publicKey);
+    const packageAuthorSignature = await sign(payload);
+    const tarballPayload = {
+        ...payload,
+        packageAuthorSignature,
+    };
+    const tarball = await (0, package_tarball_1.packPeersTarball)({
+        payload: tarballPayload,
+        packageBundle: bundles.packageBundle,
+        routesBundle: bundles.routesBundle,
+        uiBundle: bundles.uiBundle,
+    });
+    const tarballHash = (0, keys_1.hashBytes)(tarball);
+    const tarballFileName = `v${version}-${versionTag}.peers-pkg.tar.gz`;
+    const pointer = {
+        packageVersionId,
+        version,
+        versionTag,
+        path: tarballFileName,
+        sha256: tarballHash,
+        publishedAt: new Date().toISOString(),
+    };
+    return { tarball, tarballHash, pointer, payload: tarballPayload };
+}

package/dist/package-installer/package-publisher.test.d.ts

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

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

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const file_types_1 = require("../data/files/file.types");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const package_author_signing_1 = require("./package-author-signing");
+const package_publisher_1 = require("./package-publisher");
+const package_tarball_1 = require("./package-tarball");
+function makeOpts(overrides) {
+    const keys = (0, keys_1.newKeys)();
+    return {
+        packageId: (0, utils_1.newid)(),
+        version: "1.0.0",
+        bundles: {
+            packageBundle: 'console.log("main");',
+        },
+        publicKey: keys.publicKey,
+        sign: (payload) => (0, package_author_signing_1.signPackageAuthor)({ ...payload, packageBundleFileHash: payload.packageBundleFileHash }, keys.secretKey),
+        ...overrides,
+    };
+}
+describe("package-publisher", () => {
+    describe("buildPublishArtifacts", () => {
+        it("round-trips through unpackPeersTarball and verifies signature", async () => {
+            const keys = (0, keys_1.newKeys)();
+            const opts = makeOpts({
+                publicKey: keys.publicKey,
+                sign: (payload) => (0, package_author_signing_1.signPackageAuthor)(payload, keys.secretKey),
+            });
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(opts);
+            expect(result.tarball).toBeInstanceOf(Uint8Array);
+            expect(result.tarball.length).toBeGreaterThan(0);
+            const unpacked = await (0, package_tarball_1.unpackPeersTarball)(result.tarball);
+            expect(unpacked.packageBundle).toBe(opts.bundles.packageBundle);
+            expect(unpacked.payload.packageId).toBe(opts.packageId);
+            expect(unpacked.payload.version).toBe("1.0.0");
+            expect(unpacked.payload.versionTag).toBe("stable");
+            expect(unpacked.payload.publicKey).toBe(keys.publicKey);
+            const sigResult = (0, package_author_signing_1.verifyPackageAuthorSignature)({
+                ...unpacked.payload,
+                packageAuthorSignature: unpacked.payload.packageAuthorSignature,
+            }, keys.publicKey);
+            expect(sigResult.valid).toBe(true);
+        });
+        it("pointer SHA-256 matches tarball bytes", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts());
+            const actualHash = (0, keys_1.hashBytes)(result.tarball);
+            expect(result.pointer.sha256).toBe(actualHash);
+            expect(result.tarballHash).toBe(actualHash);
+        });
+        it("includes optional routes and UI bundles", async () => {
+            const opts = makeOpts({
+                bundles: {
+                    packageBundle: 'console.log("main");',
+                    routesBundle: 'console.log("routes");',
+                    uiBundle: 'console.log("ui");',
+                },
+            });
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(opts);
+            const unpacked = await (0, package_tarball_1.unpackPeersTarball)(result.tarball);
+            expect(unpacked.routesBundle).toBe('console.log("routes");');
+            expect(unpacked.uiBundle).toBe('console.log("ui");');
+            expect(unpacked.payload.routesBundleFileHash).toBe((0, file_types_1.computeFileHash)('console.log("routes");'));
+            expect(unpacked.payload.uiBundleFileHash).toBe((0, file_types_1.computeFileHash)('console.log("ui");'));
+        });
+        it("omits optional bundles when not provided", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts());
+            const unpacked = await (0, package_tarball_1.unpackPeersTarball)(result.tarball);
+            expect(unpacked.routesBundle).toBeUndefined();
+            expect(unpacked.uiBundle).toBeUndefined();
+            expect(unpacked.payload.routesBundleFileHash).toBeUndefined();
+            expect(unpacked.payload.uiBundleFileHash).toBeUndefined();
+        });
+        it("rejects tampered bundle hash via signature verification", async () => {
+            const keys = (0, keys_1.newKeys)();
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({
+                publicKey: keys.publicKey,
+                sign: (payload) => (0, package_author_signing_1.signPackageAuthor)(payload, keys.secretKey),
+            }));
+            const sigResult = (0, package_author_signing_1.verifyPackageAuthorSignature)({
+                ...result.payload,
+                packageBundleFileHash: "tampered-hash",
+            }, keys.publicKey);
+            expect(sigResult.valid).toBe(false);
+        });
+        it("rejects wrong key via signature verification", async () => {
+            const authorKeys = (0, keys_1.newKeys)();
+            const wrongKeys = (0, keys_1.newKeys)();
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({
+                publicKey: authorKeys.publicKey,
+                sign: (payload) => (0, package_author_signing_1.signPackageAuthor)(payload, authorKeys.secretKey),
+            }));
+            const sigResult = (0, package_author_signing_1.verifyPackageAuthorSignature)(result.payload, wrongKeys.publicKey);
+            expect(sigResult.valid).toBe(false);
+        });
+        it("defaults versionTag to stable", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts());
+            expect(result.pointer.versionTag).toBe("stable");
+            expect(result.payload.versionTag).toBe("stable");
+        });
+        it("respects custom versionTag", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({ versionTag: "beta" }));
+            expect(result.pointer.versionTag).toBe("beta");
+            expect(result.payload.versionTag).toBe("beta");
+            expect(result.pointer.path).toBe("v1.0.0-beta.peers-pkg.tar.gz");
+        });
+        it("uses provided packageVersionId", async () => {
+            const pvId = (0, utils_1.newid)();
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({ packageVersionId: pvId }));
+            expect(result.pointer.packageVersionId).toBe(pvId);
+            expect(result.payload.packageVersionId).toBe(pvId);
+        });
+        it("generates packageVersionId when not provided", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts());
+            expect(result.pointer.packageVersionId).toHaveLength(25);
+            expect(result.payload.packageVersionId).toBe(result.pointer.packageVersionId);
+        });
+        it("pointer path follows naming convention", async () => {
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({ version: "2.5.1", versionTag: "stable" }));
+            expect(result.pointer.path).toBe("v2.5.1-stable.peers-pkg.tar.gz");
+        });
+        it("pointer contains publishedAt ISO timestamp", async () => {
+            const before = new Date().toISOString();
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts());
+            const after = new Date().toISOString();
+            expect(result.pointer.publishedAt).toBeDefined();
+            expect(result.pointer.publishedAt >= before).toBe(true);
+            expect(result.pointer.publishedAt <= after).toBe(true);
+        });
+        it("bundle hashes in payload match actual content hashes", async () => {
+            const bundles = {
+                packageBundle: "const x = 1;",
+                routesBundle: "const r = 2;",
+                uiBundle: "const u = 3;",
+            };
+            const result = await (0, package_publisher_1.buildPublishArtifacts)(makeOpts({ bundles }));
+            expect(result.payload.packageBundleFileHash).toBe((0, file_types_1.computeFileHash)(bundles.packageBundle));
+            expect(result.payload.routesBundleFileHash).toBe((0, file_types_1.computeFileHash)(bundles.routesBundle));
+            expect(result.payload.uiBundleFileHash).toBe((0, file_types_1.computeFileHash)(bundles.uiBundle));
+        });
+    });
+});

package/dist/package-installer/package-remote-checker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Remote package update checker.
+ *
+ * Provides a memoized mechanism for checking a package's `updateUrl` for
+ * new versions and installing them into local data contexts.
+ */
+import type { DataContext } from "../context/data-context";
+import { type IPackageVersion } from "../data/package-versions";
+import { type IPackage } from "../data/packages";
+import { type IUnpackedTarball } from "./package-tarball";
+import type { IHttpDeps } from "./types";
+/**
+ * Schema for the `latest-<tag>.json` pointer file hosted at `<updateUrl>/`.
+ */
+export interface ILatestPointer {
+    packageVersionId: string;
+    version: string;
+    versionTag: string;
+    path: string;
+    sha256: string;
+    publishedAt: string;
+}
+/** Verified result from a remote check — ready to be installed into group contexts. */
+export interface IRemoteCheckResult {
+    packageId: string;
+    pointer: ILatestPointer;
+    unpacked: IUnpackedTarball;
+}
+/** Result from checking and installing a remote version into one group context. */
+export interface IRemoteInstallResult {
+    activated: boolean;
+    packageVersion: IPackageVersion;
+}
+/**
+ * Check a package's remote `updateUrl` for a new version. Memoized per
+ * `(updateUrl, tag)` for the lifetime of the process — re-check requires restart.
+ *
+ * @returns Verified payload + bundle data if a new version is available, null otherwise.
+ */
+export declare function checkPackageRemoteForNewVersion(packageId: string, updateUrl: string, tag: string, http: IHttpDeps): Promise<IRemoteCheckResult | null>;
+/**
+ * Check a remote once, then install it into this specific group only when this
+ * group does not already have the remote PackageVersion.
+ */
+export declare function checkAndInstallPackageRemoteVersion(dataContext: DataContext, pkg: IPackage, tag: string, http: IHttpDeps): Promise<IRemoteInstallResult | null>;
+/**
+ * Install a verified remote package version into a data context.
+ * Saves bundle files, creates the PV record, and runs activation policy.
+ */
+export declare function installRemotePackageVersion(dataContext: DataContext, result: IRemoteCheckResult): Promise<IRemoteInstallResult>;
+/**
+ * Clear the memoization cache. Primarily for testing.
+ */
+export declare function clearRemoteCheckCache(): void;

package/dist/package-installer/package-remote-checker.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Remote package update checker.
+ *
+ * Provides a memoized mechanism for checking a package's `updateUrl` for
+ * new versions and installing them into local data contexts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPackageRemoteForNewVersion = checkPackageRemoteForNewVersion;
+exports.checkAndInstallPackageRemoteVersion = checkAndInstallPackageRemoteVersion;
+exports.installRemotePackageVersion = installRemotePackageVersion;
+exports.clearRemoteCheckCache = clearRemoteCheckCache;
+const file_types_1 = require("../data/files/file.types");
+const package_versions_1 = require("../data/package-versions");
+const packages_1 = require("../data/packages");
+const keys_1 = require("../keys");
+const package_version_resolver_1 = require("../data/package-version-resolver");
+const package_author_signing_1 = require("./package-author-signing");
+const package_installer_1 = require("./package-installer");
+const package_propagation_1 = require("./package-propagation");
+const package_tarball_1 = require("./package-tarball");
+// Module-level memoization: unique by `updateUrl + ":" + tag`
+const remoteCheckCache = new Map();
+/**
+ * Check a package's remote `updateUrl` for a new version. Memoized per
+ * `(updateUrl, tag)` for the lifetime of the process — re-check requires restart.
+ *
+ * @returns Verified payload + bundle data if a new version is available, null otherwise.
+ */
+function checkPackageRemoteForNewVersion(packageId, updateUrl, tag, http) {
+    const cacheKey = `${updateUrl}:${tag}`;
+    const existing = remoteCheckCache.get(cacheKey);
+    if (existing)
+        return existing;
+    const promise = doRemoteCheck(packageId, updateUrl, tag, http).catch((err) => {
+        console.error(`[remote-checker] Error checking ${updateUrl} for ${tag}:`, err);
+        return null;
+    });
+    remoteCheckCache.set(cacheKey, promise);
+    return promise;
+}
+/**
+ * Check a remote once, then install it into this specific group only when this
+ * group does not already have the remote PackageVersion.
+ */
+async function checkAndInstallPackageRemoteVersion(dataContext, pkg, tag, http) {
+    if (!pkg.updateUrl || pkg.disabled)
+        return null;
+    const result = await checkPackageRemoteForNewVersion(pkg.packageId, pkg.updateUrl, tag, http);
+    if (!result)
+        return null;
+    const existing = await (0, package_versions_1.PackageVersions)(dataContext).get(result.pointer.packageVersionId);
+    if (existing)
+        return null;
+    return installRemotePackageVersion(dataContext, result);
+}
+async function doRemoteCheck(packageId, updateUrl, tag, http) {
+    const pointerUrl = `${updateUrl}/latest-${tag}.json`;
+    const pointer = await http.fetchJson(pointerUrl);
+    if (!pointer?.packageVersionId || !pointer?.path) {
+        return null;
+    }
+    const tarballUrl = `${updateUrl}/${pointer.path}`;
+    const tarballData = await http.fetchBinary(tarballUrl);
+    // Verify tarball integrity
+    const actualHash = (0, keys_1.hashBytes)(tarballData);
+    if (pointer.sha256 && actualHash !== pointer.sha256) {
+        throw new Error(`Tarball integrity check failed: expected ${pointer.sha256}, got ${actualHash}`);
+    }
+    const unpacked = await (0, package_tarball_1.unpackPeersTarball)(tarballData);
+    verifyPayloadMatchesPointer(packageId, pointer, unpacked);
+    // Verify bundle hashes match what the payload claims
+    const actualPkgHash = (0, file_types_1.computeFileHash)(unpacked.packageBundle);
+    if (actualPkgHash !== unpacked.payload.packageBundleFileHash) {
+        throw new Error("Package bundle hash does not match payload");
+    }
+    verifyOptionalBundleHash("Routes", unpacked.routesBundle, unpacked.payload.routesBundleFileHash);
+    verifyOptionalBundleHash("UI", unpacked.uiBundle, unpacked.payload.uiBundleFileHash);
+    // Verify author signature (the payload embeds the public key for verification)
+    const sigResult = (0, package_author_signing_1.verifyPackageAuthorSignature)({
+        packageId: unpacked.payload.packageId,
+        packageVersionId: unpacked.payload.packageVersionId,
+        version: unpacked.payload.version,
+        versionTag: unpacked.payload.versionTag,
+        packageBundleFileHash: unpacked.payload.packageBundleFileHash,
+        routesBundleFileHash: unpacked.payload.routesBundleFileHash,
+        uiBundleFileHash: unpacked.payload.uiBundleFileHash,
+        appNavs: unpacked.payload.appNavs,
+        createdBy: unpacked.payload.createdBy,
+        createdAt: unpacked.payload.createdAt,
+        packageAuthorSignature: unpacked.payload.packageAuthorSignature,
+    }, unpacked.payload.publicKey);
+    if (!sigResult.valid) {
+        throw new Error("Package author signature verification failed");
+    }
+    return { packageId, pointer, unpacked };
+}
+function verifyPayloadMatchesPointer(packageId, pointer, unpacked) {
+    const { payload } = unpacked;
+    const mismatches = [
+        ["packageId", packageId, payload.packageId],
+        ["packageVersionId", pointer.packageVersionId, payload.packageVersionId],
+        ["version", pointer.version, payload.version],
+        ["versionTag", pointer.versionTag, payload.versionTag],
+    ].filter(([, expected, actual]) => expected !== actual);
+    if (mismatches.length > 0) {
+        const details = mismatches
+            .map(([field, expected, actual]) => `${field}: expected ${expected}, got ${actual}`)
+            .join("; ");
+        throw new Error(`Payload does not match remote pointer: ${details}`);
+    }
+}
+function verifyOptionalBundleHash(label, bundle, expectedHash) {
+    if (bundle && !expectedHash) {
+        throw new Error(`${label} bundle is present but not covered by payload hash`);
+    }
+    if (!bundle && expectedHash) {
+        throw new Error(`${label} bundle hash is present but bundle is missing`);
+    }
+    if (!bundle || !expectedHash)
+        return;
+    const actualHash = (0, file_types_1.computeFileHash)(bundle);
+    if (actualHash !== expectedHash) {
+        throw new Error(`${label} bundle hash does not match payload`);
+    }
+}
+/**
+ * Install a verified remote package version into a data context.
+ * Saves bundle files, creates the PV record, and runs activation policy.
+ */
+async function installRemotePackageVersion(dataContext, result) {
+    const { packageId, unpacked } = result;
+    const pkg = await (0, packages_1.Packages)(dataContext).get(packageId);
+    if (!pkg) {
+        throw new Error(`Cannot install remote package version: package ${packageId} is not installed`);
+    }
+    if (!unpacked.payload.publicKey) {
+        throw new Error("Cannot install remote package version: payload publicKey is missing");
+    }
+    if (pkg.publishPublicKey && pkg.publishPublicKey !== unpacked.payload.publicKey) {
+        throw new Error(`Package publisher key mismatch for ${packageId}: expected ${pkg.publishPublicKey}, got ${unpacked.payload.publicKey}`);
+    }
+    // Save bundle files
+    const pkgFile = await (0, package_installer_1.saveBundleFile)(dataContext, unpacked.packageBundle, `${packageId}-package.bundle.js`, packageId);
+    let routesFile;
+    if (unpacked.routesBundle) {
+        routesFile = await (0, package_installer_1.saveBundleFile)(dataContext, unpacked.routesBundle, `${packageId}-routes.bundle.js`, packageId);
+    }
+    let uiFile;
+    if (unpacked.uiBundle) {
+        uiFile = await (0, package_installer_1.saveBundleFile)(dataContext, unpacked.uiBundle, `${packageId}-uis.bundle.js`, packageId);
+    }
+    // Create PV record
+    const pvHash = (0, package_versions_1.computePackageVersionHash)(unpacked.payload.version, unpacked.payload.versionTag, pkgFile.fileHash, routesFile?.fileHash, uiFile?.fileHash);
+    const pv = {
+        packageVersionId: unpacked.payload.packageVersionId,
+        packageId,
+        version: unpacked.payload.version,
+        versionTag: unpacked.payload.versionTag,
+        packageVersionHash: pvHash,
+        packageBundleFileId: pkgFile.fileId,
+        packageBundleFileHash: pkgFile.fileHash,
+        routesBundleFileId: routesFile?.fileId,
+        routesBundleFileHash: routesFile?.fileHash,
+        uiBundleFileId: uiFile?.fileId,
+        uiBundleFileHash: uiFile?.fileHash,
+        appNavs: unpacked.payload.appNavs,
+        packageAuthorSignature: unpacked.payload.packageAuthorSignature,
+        signature: "",
+        createdBy: unpacked.payload.createdBy ?? packageId,
+        createdAt: unpacked.payload.createdAt ?? new Date().toISOString(),
+    };
+    const pvTable = (0, package_versions_1.PackageVersions)(dataContext);
+    const savedPv = await pvTable.signAndSave(pv);
+    // TOFU: if package has no publishPublicKey, establish it now
+    if (!pkg.publishPublicKey) {
+        pkg.publishPublicKey = unpacked.payload.publicKey;
+        await (0, packages_1.Packages)(dataContext).signAndSave(pkg);
+    }
+    const activationResult = await (0, package_propagation_1.activateBestEligibleVersion)(dataContext, pkg);
+    // Also run the device-level resolver so this device picks up the new version
+    // (activateBestEligibleVersion only updates the group-level default).
+    const resolveResult = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dataContext, { force: true });
+    return {
+        activated: activationResult?.activated || resolveResult.upgraded,
+        packageVersion: savedPv,
+    };
+}
+/**
+ * Clear the memoization cache. Primarily for testing.
+ */
+function clearRemoteCheckCache() {
+    remoteCheckCache.clear();
+}

package/dist/package-installer/package-remote-checker.test.d.ts

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