@peers-app/peers-sdk 0.20.6 → 0.21.1

package/dist/device-pairing/types.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devicePairingStateSchema = exports.devicePairingPhaseSchema = exports.signedPairingInstallationReceiptSchema = exports.pairingInstallationReceiptContentsSchema = exports.pairingCredentialEnvelopeSchema = exports.pairingCredentialContentsSchema = exports.signedPairingApprovalSchema = exports.pairingApprovalContentsSchema = exports.pairingDescriptionSchema = exports.pairingDevicePresentationSchema = exports.devicePairingTranscriptSchema = exports.devicePairingIceServersAckSchema = exports.devicePairingRoomReadyAckSchema = exports.devicePairingSignalingAckSchema = exports.devicePairingSignalingErrorCodeSchema = exports.devicePairingDeleteRoomRequestSchema = exports.devicePairingJoinRoomRequestSchema = exports.devicePairingCreateRoomRequestSchema = exports.pairingSignalSchema = exports.unsignedPairingSignalSchema = exports.pairingIceServerSchema = exports.pairingIceCandidateSchema = exports.pairingSessionDescriptionSchema = exports.devicePairingInvitationSchema = exports.pairingRoleSchema = exports.pairingEndpointNonceSchema = exports.pairingHashSchema = exports.pairingRoomSecretSchema = exports.pairingRoomIdSchema = void 0;
+const zod_1 = require("zod");
+const devices_1 = require("../data/devices");
+const zod_types_1 = require("../types/zod-types");
+const constants_1 = require("./constants");
+const base64UrlSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/);
+/** A random 128-bit pairing-room identifier encoded as unpadded base64url. */
+exports.pairingRoomIdSchema = base64UrlSchema.length(22);
+/** A random 256-bit pairing-room secret encoded as unpadded base64url. */
+exports.pairingRoomSecretSchema = base64UrlSchema.length(43);
+/** A SHA-256 value encoded as unpadded base64url. */
+exports.pairingHashSchema = base64UrlSchema.length(43);
+/** A random 256-bit endpoint nonce encoded as unpadded base64url. */
+exports.pairingEndpointNonceSchema = base64UrlSchema.length(43);
+/** Source and destination roles in a two-party pairing room. */
+exports.pairingRoleSchema = zod_1.z.enum(["source", "destination"]);
+/** Versioned invitation shared out-of-band from the signed-in source. */
+exports.devicePairingInvitationSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomSecret: exports.pairingRoomSecretSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    serviceOrigin: zod_1.z
+        .string()
+        .url()
+        .max(2048)
+        .refine((value) => {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.origin === value;
+    }, "Expected an HTTP(S) origin without a path"),
+})
+    .strict();
+/** WebRTC session description carried inside an authenticated signaling message. */
+exports.pairingSessionDescriptionSchema = zod_1.z
+    .object({
+    type: zod_1.z.enum(["offer", "answer"]),
+    sdp: zod_1.z
+        .string()
+        .min(1)
+        .max(64 * 1024),
+    endpointNonce: exports.pairingEndpointNonceSchema,
+})
+    .strict();
+/** ICE candidate carried inside an authenticated signaling message. */
+exports.pairingIceCandidateSchema = zod_1.z
+    .object({
+    candidate: zod_1.z.string().min(1).max(4096),
+    sdpMid: zod_1.z.string().max(256).nullable().optional(),
+    sdpMLineIndex: zod_1.z.number().int().min(0).max(65535).nullable().optional(),
+    usernameFragment: zod_1.z.string().max(256).nullable().optional(),
+})
+    .strict();
+const iceUrlSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine((value) => value.startsWith("stun:") || value.startsWith("turn:") || value.startsWith("turns:"), "Expected a STUN or TURN URL");
+/** Validated ICE server configuration issued to a pairing-room member. */
+exports.pairingIceServerSchema = zod_1.z
+    .object({
+    urls: zod_1.z.union([iceUrlSchema, zod_1.z.array(iceUrlSchema).min(1).max(16)]),
+    username: zod_1.z.string().min(1).max(256).optional(),
+    credential: zod_1.z.string().min(1).max(512).optional(),
+})
+    .strict()
+    .refine((value) => (value.username === undefined && value.credential === undefined) ||
+    (value.username !== undefined && value.credential !== undefined), "TURN username and credential must be supplied together");
+const pairingSignalBase = {
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    senderRole: exports.pairingRoleSchema,
+    sequence: zod_1.z.number().int().positive(),
+};
+/** Unsigned offer, answer, or ICE message before its signaling MAC is attached. */
+exports.unsignedPairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("offer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("answer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("candidate"),
+        payload: exports.pairingIceCandidateSchema,
+    })
+        .strict(),
+]);
+/** HMAC-authenticated offer, answer, or ICE signaling message. */
+exports.pairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("offer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("answer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("candidate"),
+        payload: exports.pairingIceCandidateSchema,
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+]);
+/** Request from the source to create a bounded signaling room. */
+exports.devicePairingCreateRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    roomAccessTokenHash: exports.pairingHashSchema,
+})
+    .strict();
+/** Request from the destination to occupy the second room slot. */
+exports.devicePairingJoinRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomAccessToken: exports.pairingHashSchema,
+})
+    .strict();
+/** Request from the source to tear down its signaling room. */
+exports.devicePairingDeleteRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomAccessToken: exports.pairingHashSchema,
+})
+    .strict();
+/** Public signaling-service error codes that do not echo attacker input. */
+exports.devicePairingSignalingErrorCodeSchema = zod_1.z.enum([
+    "invalid",
+    "not-found",
+    "occupied",
+    "expired",
+    "forbidden",
+    "rate-limited",
+    "too-large",
+    "out-of-order",
+]);
+const devicePairingSignalingFailureSchema = zod_1.z
+    .object({
+    ok: zod_1.z.literal(false),
+    code: exports.devicePairingSignalingErrorCodeSchema,
+})
+    .strict();
+/** Acknowledgement returned by every signaling-room command. */
+exports.devicePairingSignalingAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z.object({ ok: zod_1.z.literal(true) }).strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Acknowledgement proving room creation/join and its service-authoritative expiry. */
+exports.devicePairingRoomReadyAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z
+        .object({
+        ok: zod_1.z.literal(true),
+        expiresAt: zod_1.z.number().int().positive(),
+    })
+        .strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Acknowledgement containing room-bound, short-lived ICE configuration. */
+exports.devicePairingIceServersAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z
+        .object({
+        ok: zod_1.z.literal(true),
+        iceServers: zod_1.z.array(exports.pairingIceServerSchema).min(1).max(8),
+    })
+        .strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Canonical transcript input derived independently by both endpoints. */
+exports.devicePairingTranscriptSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    sourceIdentity: devices_1.deviceInfoSchema,
+    destinationIdentity: devices_1.deviceInfoSchema,
+    sourceEndpointNonce: exports.pairingEndpointNonceSchema,
+    destinationEndpointNonce: exports.pairingEndpointNonceSchema,
+    offerFingerprint: zod_1.z.string().min(1).max(256),
+    answerFingerprint: zod_1.z.string().min(1).max(256),
+})
+    .strict();
+/** Renderer-safe presentation of the remote endpoint. */
+exports.pairingDevicePresentationSchema = zod_1.z
+    .object({
+    deviceName: devices_1.displayNameSchema.optional(),
+    userName: devices_1.displayNameSchema.optional(),
+    deviceType: zod_1.z.string().max(64).optional(),
+})
+    .strict();
+/** Payload exchanged by `pairing.describe` after the normal Connection handshake. */
+exports.pairingDescriptionSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    device: devices_1.deviceInfoSchema,
+    presentation: exports.pairingDevicePresentationSchema,
+})
+    .strict();
+/** Contents of a signed, single-use user approval. */
+exports.pairingApprovalContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    approvalId: exports.pairingEndpointNonceSchema,
+    transcriptHash: exports.pairingHashSchema,
+    role: exports.pairingRoleSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+})
+    .strict();
+/** Signed approval bound to one transcript and endpoint identity. */
+exports.signedPairingApprovalSchema = zod_1.z
+    .object({
+    contents: exports.pairingApprovalContentsSchema,
+    signature: base64UrlSchema.length(86),
+    publicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Account credentials encrypted directly to the temporary destination identity. */
+exports.pairingCredentialContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    userId: zod_types_1.zodPeerId,
+    secretKey: base64UrlSchema.length(86),
+})
+    .strict();
+/** Signed-and-boxed credential envelope sent over the WebRTC Connection. */
+exports.pairingCredentialEnvelopeSchema = zod_1.z
+    .object({
+    contents: base64UrlSchema.min(1).max(4096),
+    nonce: base64UrlSchema.length(32),
+    fromPublicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Contents of the temporary destination identity's signed installation receipt. */
+exports.pairingInstallationReceiptContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    initializedDevice: devices_1.deviceInfoSchema,
+    installedAt: zod_1.z.number().int().positive(),
+})
+    .strict();
+/** Receipt proving installation on the authenticated temporary destination endpoint. */
+exports.signedPairingInstallationReceiptSchema = zod_1.z
+    .object({
+    contents: exports.pairingInstallationReceiptContentsSchema,
+    signature: base64UrlSchema.length(86),
+    publicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Renderer-visible phases of the short-lived pairing ceremony. */
+exports.devicePairingPhaseSchema = zod_1.z.enum([
+    "idle",
+    "inviting",
+    "connecting",
+    "comparing",
+    "waiting-for-approval",
+    "transferring",
+    "complete",
+    "rejected",
+    "error",
+]);
+/** Sanitized pairing state safe to publish across the host/renderer boundary. */
+exports.devicePairingStateSchema = zod_1.z
+    .object({
+    sessionId: zod_types_1.zodPeerId.optional(),
+    role: exports.pairingRoleSchema.optional(),
+    phase: exports.devicePairingPhaseSchema,
+    expiresAt: zod_1.z.number().int().positive().optional(),
+    remoteDevice: exports.pairingDevicePresentationSchema.optional(),
+    sas: zod_1.z
+        .string()
+        .regex(/^\d{6}$/)
+        .optional(),
+    error: zod_1.z.string().max(256).optional(),
+})
+    .strict();

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./device/get-trust-level-fn";
 export * from "./device/socket.type";
 export * from "./device/socket-io-binary-peer";
 export * from "./device/tx-encoding";
+export * from "./device-pairing";
 export * from "./events";
 export * from "./group-invite";
 export * from "./keys";

package/dist/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./device/get-trust-level-fn"), exports);
 __exportStar(require("./device/socket.type"), exports);
 __exportStar(require("./device/socket-io-binary-peer"), exports);
 __exportStar(require("./device/tx-encoding"), exports);
+__exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./group-invite"), exports);
 __exportStar(require("./keys"), exports);

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

@@ -1,3 +1,4 @@
+export * from "./package-author-signer";
 export * from "./package-author-signing";
 export * from "./package-cloner";
 export * from "./package-creator";

package/dist/package-installer/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./package-author-signer"), exports);
 __exportStar(require("./package-author-signing"), exports);
 __exportStar(require("./package-cloner"), exports);
 __exportStar(require("./package-creator"), exports);

package/dist/package-installer/package-author-signer.d.ts

@@ -0,0 +1,25 @@
+import { type AuthorSignableFields } from "./package-author-signing";
+/**
+ * Load and decrypt the package author signing secret key from the user's personal group.
+ * Returns `undefined` when the key is missing or cannot be decrypted.
+ *
+ * @param packageId - Package whose `packageSigningKey_<id>` secret pvar to load
+ * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
+ */
+export declare function loadPackageSigningKey(packageId: string, getUserSecretKey: () => Promise<string>): Promise<string | undefined>;
+/**
+ * Sign a package version with the package author's key.
+ *
+ * Safe to call from Electron (main process) or PWA (single-process client). The
+ * signing key is loaded from a secret persistent variable and never returned to
+ * callers — only the detached signature is.
+ *
+ * Returns the base64url detached signature, or `undefined` if the signing key
+ * isn't available or signing fails. Callers that require a signature (e.g.
+ * remote publish) should treat `undefined` as an error; create/promote may leave
+ * `packageAuthorSignature` unset.
+ *
+ * @param pvFields - Author-signable PackageVersion fields
+ * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
+ */
+export declare function trySignPackageAuthorVersion(pvFields: AuthorSignableFields, getUserSecretKey: () => Promise<string>): Promise<string | undefined>;

package/dist/package-installer/package-author-signer.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPackageSigningKey = loadPackageSigningKey;
+exports.trySignPackageAuthorVersion = trySignPackageAuthorVersion;
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const persistent_vars_1 = require("../data/persistent-vars");
+const keys_1 = require("../keys");
+const package_author_signing_1 = require("./package-author-signing");
+/**
+ * Load and decrypt the package author signing secret key from the user's personal group.
+ * Returns `undefined` when the key is missing or cannot be decrypted.
+ *
+ * @param packageId - Package whose `packageSigningKey_<id>` secret pvar to load
+ * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
+ */
+async function loadPackageSigningKey(packageId, getUserSecretKey) {
+    try {
+        const userContext = await (0, user_context_singleton_1.getUserContext)();
+        const secretKey = await getUserSecretKey();
+        const keyName = `${package_author_signing_1.PACKAGE_SIGNING_KEY_PREFIX}${packageId}`;
+        const keyPvar = await (0, persistent_vars_1.PersistentVars)(userContext.userDataContext).findOne({ name: keyName });
+        if (!keyPvar?.value?.value || !keyPvar.isSecret) {
+            return undefined;
+        }
+        return (0, keys_1.decryptData)(keyPvar.value.value, secretKey) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sign a package version with the package author's key.
+ *
+ * Safe to call from Electron (main process) or PWA (single-process client). The
+ * signing key is loaded from a secret persistent variable and never returned to
+ * callers — only the detached signature is.
+ *
+ * Returns the base64url detached signature, or `undefined` if the signing key
+ * isn't available or signing fails. Callers that require a signature (e.g.
+ * remote publish) should treat `undefined` as an error; create/promote may leave
+ * `packageAuthorSignature` unset.
+ *
+ * @param pvFields - Author-signable PackageVersion fields
+ * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
+ */
+async function trySignPackageAuthorVersion(pvFields, getUserSecretKey) {
+    try {
+        const signingKey = await loadPackageSigningKey(pvFields.packageId, getUserSecretKey);
+        if (!signingKey) {
+            return undefined;
+        }
+        return (0, package_author_signing_1.signPackageAuthor)(pvFields, signingKey);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { DataContext } from "../context/data-context";
+import type { IPackageVersion } from "../data/package-versions";
 import type { IInstallOpts, IInstallResult, IPackageInfo, IPackageInstallerDeps } from "./types";
 /**
  * Install or update a dev PackageVersion from locally-built bundle files.
@@ -9,6 +10,20 @@ import type { IInstallOpts, IInstallResult, IPackageInfo, IPackageInstallerDeps
  * triggers the package loader and device version resolution.
  */
 export declare function installPackageFromBundles(dataContext: DataContext, deps: IPackageInstallerDeps, packageId: string, opts?: IInstallOpts): Promise<IInstallResult>;
+/**
+ * Ensure a PackageVersion has `appNavs` from its package definition.
+ * No-ops when appNavs are already present or the package cannot be loaded.
+ *
+ * Used to repair PVs that were created with `skipLoad` (startup sync while the
+ * group was not on `dev`) and later activated/promoted without nav metadata.
+ *
+ * @param dataContext - Group or personal data context holding the PV
+ * @param deps - Filesystem / path helpers
+ * @param packageId - Package that owns the version
+ * @param packageVersionId - Specific PV to repair
+ * @returns The PV after any update, or `undefined` if not found
+ */
+export declare function ensurePackageVersionAppNavs(dataContext: DataContext, deps: IPackageInstallerDeps, packageId: string, packageVersionId: string): Promise<IPackageVersion | undefined>;
 /**
  * Install bundles for all non-disabled packages in a data context.
  * Errors are caught per-package so one failure doesn't block others.
@@ -30,3 +45,15 @@ export declare function saveBundleFile(dataContext: DataContext, content: string
  * Uses `deps.fs.readJson` instead of `require()` — no cache issues.
  */
 export declare function getPackageInfo(deps: IPackageInstallerDeps, localPath: string): Promise<IPackageInfo>;
+/**
+ * Resolve the local filesystem path for a package based on device vars.
+ * Awaits the loading promise to ensure the DB-stored value is available
+ * before reading. Falls back to paths from other data contexts on this device,
+ * then to `{packagesRootDir}/{name-slug}` when that directory exists.
+ *
+ * @param packageId - Package to resolve
+ * @param dataContext - Preferred data context for the `packageLocalPath_*` device var
+ * @param deps - Filesystem / path helpers used by the package installer
+ * @returns Absolute (or deps-resolved) path to the package directory
+ */
+export declare function getPackageLocalPath(packageId: string, dataContext: DataContext, deps: IPackageInstallerDeps): Promise<string>;

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

@@ -1,15 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installPackageFromBundles = installPackageFromBundles;
+exports.ensurePackageVersionAppNavs = ensurePackageVersionAppNavs;
 exports.installAllPackageBundles = installAllPackageBundles;
 exports.saveBundleFile = saveBundleFile;
 exports.getPackageInfo = getPackageInfo;
+exports.getPackageLocalPath = getPackageLocalPath;
 const file_types_1 = require("../data/files/file.types");
 const files_1 = require("../data/files/files");
 const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
 const persistent_vars_1 = require("../data/persistent-vars");
+const rpc_types_1 = require("../rpc-types");
 const utils_1 = require("../utils");
 /**
  * Install or update a dev PackageVersion from locally-built bundle files.
@@ -50,14 +53,22 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     const uiHash = uiBundle ? (0, file_types_1.computeFileHash)(uiBundle) : undefined;
     // 5. Compute PV hash
     const pvHash = (0, package_versions_1.computePackageVersionHash)(version, "", packageHash, routesHash, uiHash);
-    // 6. Early exit if unchanged
+    // 6. Early exit if unchanged (still repair missing appNavs — see syncDevBundles skipLoad)
     const pvTable = (0, package_versions_1.PackageVersions)(dataContext);
     const existingPv = await pvTable.findOne({ packageId, versionTag });
     if (existingPv && existingPv.packageVersionHash === pvHash) {
+        if (existingPv.appNavs?.length) {
+            return {
+                packageVersion: existingPv,
+                loaded: undefined,
+                unchanged: true,
+            };
+        }
+        const loaded = await loadAndPersistAppNavs(dataContext, packageId, existingPv, localPath);
         return {
             packageVersion: existingPv,
-            loaded: undefined,
-            unchanged: true,
+            loaded,
+            unchanged: !loaded?.appNavs?.length,
         };
     }
     // 7. Save bundle files (deduped by hash)
@@ -91,22 +102,13 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
         createdAt: now,
     };
     const savedPv = await pvTable.signAndSave(pv);
-    // 9. Load package (unless skipLoad)
+    // 9. Load package for in-memory use and/or appNavs backfill.
+    // `skipLoad` is used by startup sync when the group is not on `dev` (avoid
+    // activating), but we must still persist appNavs or the apps list stays empty
+    // after that PV is later activated/promoted.
     let loaded;
-    if (!opts?.skipLoad) {
-        const pkg = await (0, packages_1.Packages)(dataContext).get(packageId);
-        if (pkg) {
-            loaded = await dataContext.packageLoader.loadPackage(pkg, {
-                force: true,
-                localPath,
-                packageVersionId: savedPv.packageVersionId,
-            });
-            // Extract appNavs from loaded instance onto the PV
-            if (loaded?.appNavs && JSON.stringify(loaded.appNavs) !== JSON.stringify(savedPv.appNavs)) {
-                savedPv.appNavs = loaded.appNavs;
-                await pvTable.signAndSave(savedPv);
-            }
-        }
+    if (!opts?.skipLoad || !savedPv.appNavs?.length) {
+        loaded = await loadAndPersistAppNavs(dataContext, packageId, savedPv, localPath);
     }
     // 10. Update package record if needed (description, first-install activation)
     const pkg = await (0, packages_1.Packages)(dataContext).get(packageId);
@@ -134,6 +136,69 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     }
     return { packageVersion: savedPv, loaded, unchanged: false };
 }
+/**
+ * Load a package bundle and persist `appNavs` onto the PackageVersion when the
+ * definition provides them.
+ *
+ * If the PV already has a `packageAuthorSignature`, refresh it (or clear it when
+ * the signing key is unavailable) because `appNavs` is part of the author-signed
+ * payload.
+ */
+async function loadAndPersistAppNavs(dataContext, packageId, pv, localPath) {
+    const pkg = await (0, packages_1.Packages)(dataContext).get(packageId);
+    if (!pkg)
+        return undefined;
+    const loaded = await dataContext.packageLoader.loadPackage(pkg, {
+        force: true,
+        localPath,
+        packageVersionId: pv.packageVersionId,
+    });
+    if (!loaded?.appNavs?.length)
+        return loaded;
+    if (JSON.stringify(loaded.appNavs) === JSON.stringify(pv.appNavs))
+        return loaded;
+    pv.appNavs = loaded.appNavs;
+    if (pv.packageAuthorSignature) {
+        const authorSig = await rpc_types_1.rpcServerCalls.signPackageAuthorVersion({
+            packageId: pv.packageId,
+            packageVersionId: pv.packageVersionId,
+            version: pv.version,
+            versionTag: pv.versionTag ?? "",
+            packageBundleFileHash: pv.packageBundleFileHash,
+            routesBundleFileHash: pv.routesBundleFileHash,
+            uiBundleFileHash: pv.uiBundleFileHash,
+            appNavs: pv.appNavs,
+            createdBy: pv.createdBy,
+            createdAt: pv.createdAt,
+        });
+        pv.packageAuthorSignature = authorSig;
+    }
+    await (0, package_versions_1.PackageVersions)(dataContext).signAndSave(pv);
+    return loaded;
+}
+/**
+ * Ensure a PackageVersion has `appNavs` from its package definition.
+ * No-ops when appNavs are already present or the package cannot be loaded.
+ *
+ * Used to repair PVs that were created with `skipLoad` (startup sync while the
+ * group was not on `dev`) and later activated/promoted without nav metadata.
+ *
+ * @param dataContext - Group or personal data context holding the PV
+ * @param deps - Filesystem / path helpers
+ * @param packageId - Package that owns the version
+ * @param packageVersionId - Specific PV to repair
+ * @returns The PV after any update, or `undefined` if not found
+ */
+async function ensurePackageVersionAppNavs(dataContext, deps, packageId, packageVersionId) {
+    const pv = await (0, package_versions_1.PackageVersions)(dataContext).get(packageVersionId);
+    if (!pv)
+        return undefined;
+    if (pv.appNavs?.length)
+        return pv;
+    const localPath = await getPackageLocalPath(packageId, dataContext, deps);
+    await loadAndPersistAppNavs(dataContext, packageId, pv, localPath);
+    return pv;
+}
 /**
  * Install bundles for all non-disabled packages in a data context.
  * Errors are caught per-package so one failure doesn't block others.
@@ -247,6 +312,11 @@ function packageNameToFolderSlug(name) {
  * Awaits the loading promise to ensure the DB-stored value is available
  * before reading. Falls back to paths from other data contexts on this device,
  * then to `{packagesRootDir}/{name-slug}` when that directory exists.
+ *
+ * @param packageId - Package to resolve
+ * @param dataContext - Preferred data context for the `packageLocalPath_*` device var
+ * @param deps - Filesystem / path helpers used by the package installer
+ * @returns Absolute (or deps-resolved) path to the package directory
  */
 async function getPackageLocalPath(packageId, dataContext, deps) {
     const candidates = [];

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

@@ -440,6 +440,55 @@ describe("installPackageFromBundles", () => {
         const secondCall = mockSignAndSavePV.mock.calls[1][0];
         expect(secondCall.appNavs).toEqual(appNavs);
     });
+    it("backfills appNavs even when skipLoad is true", async () => {
+        const { deps } = setupBasicInstall();
+        const appNavs = [{ name: "App", iconClassName: "bi bi-app", navigationPath: "app" }];
+        const mockLoadPackage = jest.fn().mockResolvedValue({ packageId, appNavs });
+        const dc = mockDataContext({
+            packageLoader: { loadPackage: mockLoadPackage },
+        });
+        await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, {
+            skipLoad: true,
+            skipResolve: true,
+        });
+        expect(mockLoadPackage).toHaveBeenCalled();
+        expect(mockSignAndSavePV).toHaveBeenCalledTimes(2);
+        expect(mockSignAndSavePV.mock.calls[1][0].appNavs).toEqual(appNavs);
+    });
+    it("repairs missing appNavs on unchanged early-return", async () => {
+        const { deps } = setupBasicInstall();
+        const packageHash = (0, file_types_1.computeFileHash)(packageBundle);
+        const routesHash = (0, file_types_1.computeFileHash)(routesBundle);
+        const uiHash = (0, file_types_1.computeFileHash)(uiBundle);
+        const { computePackageVersionHash } = jest.requireActual("../data/package-versions");
+        const expectedPvHash = computePackageVersionHash("1.2.3", "", packageHash, routesHash, uiHash);
+        const appNavs = [{ name: "App", iconClassName: "bi bi-app", navigationPath: "app" }];
+        mockFindOnePV.mockResolvedValue({
+            packageVersionId: (0, utils_1.newid)(),
+            packageId,
+            version: "1.2.3",
+            versionTag: "dev",
+            packageVersionHash: expectedPvHash,
+            packageBundleFileHash: packageHash,
+            routesBundleFileHash: routesHash,
+            uiBundleFileHash: uiHash,
+            appNavs: undefined,
+            signature: "sig",
+            createdBy: "user1",
+            createdAt: "2024-01-01T00:00:00.000Z",
+        });
+        const mockLoadPackage = jest.fn().mockResolvedValue({ packageId, appNavs });
+        const dc = mockDataContext({
+            packageLoader: { loadPackage: mockLoadPackage },
+        });
+        const result = await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, {
+            skipLoad: true,
+            skipResolve: true,
+        });
+        expect(mockLoadPackage).toHaveBeenCalled();
+        expect(result.packageVersion.appNavs).toEqual(appNavs);
+        expect(mockSignAndSavePV).toHaveBeenCalledTimes(1);
+    });
     it("calls updatePackagePrefs and resolveDevicePackageVersion when skipResolve is false", async () => {
         const { deps } = setupBasicInstall();
         const dc = mockDataContext();