@serve.zone/interfaces 32.52.0 → 32.53.0

package/dist_ts/runtime.workloadinit.d.ts

@@ -1,16 +1,16 @@
 import type { TSha256Digest, TImmutableContainerPlatform } from './data/immutableimage.js';
 export declare const workloadInitReleaseContract: Readonly<{
-    readonly packageName: "@serve.zone/workloadinit";
-    readonly sourceRepository: "https://code.foss.global/serve.zone/workloadinit.git";
-    readonly imageRegistry: "code.foss.global";
-    readonly imageRepository: "serve.zone/workloadinit";
-    readonly imageIndexMediaType: "application/vnd.oci.image.index.v1+json";
-    readonly statementType: "https://in-toto.io/Statement/v1";
-    readonly predicateType: "https://slsa.dev/provenance/v1";
-    readonly buildType: "https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker";
-    readonly builderId: "https://serve.zone/builders/workloadinit-manual-release";
-    readonly signatureFormat: "cosign-dsse-bundle-v0.3";
-    readonly signatureAlgorithm: "ecdsa-p256-sha256";
+    readonly packageName: '@serve.zone/workloadinit';
+    readonly sourceRepository: 'https://code.foss.global/serve.zone/workloadinit.git';
+    readonly imageRegistry: 'code.foss.global';
+    readonly imageRepository: 'serve.zone/workloadinit';
+    readonly imageIndexMediaType: 'application/vnd.oci.image.index.v1+json';
+    readonly statementType: 'https://in-toto.io/Statement/v1';
+    readonly predicateType: 'https://slsa.dev/provenance/v1';
+    readonly buildType: 'https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker';
+    readonly builderId: 'https://serve.zone/builders/workloadinit-manual-release';
+    readonly signatureFormat: 'cosign-dsse-bundle-v0.3';
+    readonly signatureAlgorithm: 'ecdsa-p256-sha256';
 }>;
 export interface IWorkloadInitBuildToolVersions {
     dockerBuildx: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.52.0",
+  "version": "32.53.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -27,11 +27,12 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.2",
+    "@git.zone/tsbuild": "^6.0.0",
     "@git.zone/tsdoc": "^3.0.2",
     "@git.zone/tsrun": "^3.0.2",
     "@git.zone/tstest": "^7.2.0",
-    "@types/node": "26.6.3"
+    "@types/node": "26.6.3",
+    "typescript": "^6.0.3"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -3559,6 +3559,7 @@ Compatibility rules:
 - Every level has exact keys; an unknown member is `schemaInvalid` (`appstore.validateAppStoreCatalog`).
 - `requiresFeatures` gates one version: a consumer passes the feature ids it fulfils (`supportedFeatureIds`, e.g. `appStoreStorageFeatureIds` values). A version naming any other id stays listed, is refused for install and upgrade there, and its config is not interpreted, so a new config capability ships under a feature id without refusing the rest of the catalog (`appstore.getAppStoreCatalogMissingFeatureIds`).
 - A published `app@version` stays in every later catalog and never changes (`appstore.judgeAppStoreCatalogSuccession`): a later catalog that no longer lists it is `publishedVersionRemoved`, one that lists it with another `configDigest` is `publishedVersionMutated`, and a revision that does not increase is `revisionRegressed`.
+- A version names the oldest host releases that run it (`minOneboxVersion`, `minCloudlyVersion`). A host passes itself to `appstore.judgeAppStoreCatalogInstallTarget` as `{ kind: 'onebox' | 'cloudly', version }` (`IAppStoreCatalogConsumer`), which refuses a version needing a newer release of it as `consumerVersionTooOld`; the version stays listed and installs once the host is upgraded.
 - A publisher retires a version by withdrawing it, never by removing it. A withdrawn version keeps its entry, config and digest, so services installed from it keep reading it, and is refused as an install or upgrade target, like a version gated on a feature the consumer lacks (`appstore.judgeAppStoreCatalogInstallTarget`). A withdrawal is final: a later catalog that revokes or rewrites it is `publishedWithdrawalChanged`; a version withdrawn by mistake is republished under a new version.
 
 Digests are SHA-256 over strict canonical JSON (keys in UTF-16 code-unit order, safe integers only) of a domain-separated value: `computeAppStoreCatalogConfigDigest`, `computeAppStoreCatalogDigest` and `computeAppStoreCatalogSigningKeyId`. A signature covers `createAppStoreCatalogSignaturePayload(catalogDigest)`. These helpers use Web Crypto and are safe in the browser entry.
@@ -3583,6 +3584,14 @@ if (!verification.accepted) {
 
 `verifyAppStoreCatalogEnvelope` authenticates before it interprets: envelope shape, `catalogDigest`, one valid signature by a trusted key (a failing signature by a trusted key refuses the envelope), then contract, schema and every `configDigest`. The consumer then judges succession against its active catalog.
 
+A publisher keeps its signing key as a file: `importAppStoreCatalogSigningKeyPem(text)` reads one unencrypted PKCS#8 PEM Ed25519 private key (`openssl genpkey -algorithm ed25519`) into an `IAppStoreCatalogSigningKey` with its public key and key id, and `exportAppStoreCatalogSigningKeyPem(key)` writes one. `getAppStoreCatalogTrustedKey(key)` is the `IAppStoreCatalogTrustedKey` a consumer ships for it. A trusted key also converts from and to an SPKI PEM public key (`openssl pkey -pubout`) with `importAppStoreCatalogTrustedKeyPem` and `exportAppStoreCatalogTrustedKeyPem`. Each refuses another PEM label or key type and a key id that does not match its public key, and no error quotes its input.
+
+A service records the App Store version it runs as `IService.data.appStoreTemplate` (`IAppStoreServiceTemplateSnapshot`: `appId`, `version`, `configDigest`, `config`, `catalogRevision`), taken from a verified catalog by `appstore.createAppStoreServiceTemplateSnapshot`. It is server-managed (`TServiceWritableData` excludes it): the host writes it at install, upgrade and catalog adoption, and runtime paths read it, never the live catalog. While no catalog is active, an `unavailable` status states its `cause` (`loading`, `failed`, `refused`) for programs next to the operator's `reason`, and App Store install, upgrade and upgrade preview are refused with the retryable code `APPSTORE_CATALOG_UNAVAILABLE` (`IAppStoreCatalogUnavailableErrorData`). `IReq_Any_ImportAppStoreCatalog` imports an operator's envelope text (origin `operatorImport`) and answers the status after it, so an air-gapped host needs no registry.
+
+A host loads the catalog from the npm registries `appstore.resolveAppStoreCatalogRegistries(list)` answers: the configured list (Cloudly's `ICloudlySettings.appStoreCatalogRegistries`, an Onebox setting) in canonical form, or `appStoreCatalogDefaultRegistries` (npmjs) when it is empty. `appstore.validateAppStoreCatalogRegistries` is the one rule for a configured list: `https:` base URLs without credentials, query or fragment, each registry once.
+
+A host's App Store views carry the listing as `IAppStoreApp` and `IAppStoreAppMeta`: `versions` names the install targets, and the optional `versionStates` (`IAppStoreAppVersionState`) states every listed version, withdrawn and feature-gated ones included, with its `judgeAppStoreCatalogInstallTarget` answer as `installRefusal`.
+
 `TAppStoreCatalogStatus` is the operator's view, discriminated by `availability`: `ready` (`IAppStoreCatalogReadyStatus`) always carries the `active` catalog's revision, digest, key and origin, including a restored last-known-good catalog; `unavailable` (`IAppStoreCatalogUnavailableStatus`) always carries a `reason` and no active catalog. Both state `supportedContract`, `supportedFeatureIds`, `lastAttempt`, `nextAttemptAt` and the last `refused` catalog. Loading a catalog never gates the boot, readiness or health of anything else; while none is active only App Store install, upgrade and upgrade-preview are refused. `requests.appstore.IReq_Any_GetAppStoreCatalogStatus` reads it, `IReq_Any_RefreshAppStoreCatalog` runs one attempt now and answers the state after it, and `IReq_Any_GetAppStoreTemplates` may answer it as `catalogStatus`.
 
 The catalog validator judges every supported version config in full; no consumer needs a second validator. Besides the catalog's own rules (member set, image pinning, the feature gate, minimum versions, upgrade flags, `healthCheck`) it applies `appstore.validateAppStoreVersionConfig`, the member rules a host applies before it installs a version, in this order:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.52.0',
+  version: '32.53.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/appstore/catalog.ts

@@ -12,6 +12,7 @@
  */
 import type { TSha256Digest } from '../data/immutableimage.js';
 import { getDigestFromPinnedImageReference, isSha256Digest } from '../data/immutableimage.js';
+import { compareReleaseVersions, parseReleaseVersion } from '../data/releaseversion.js';
 import {
   canonicalizeStrictJson,
   compareWireTokens,
@@ -268,14 +269,39 @@ export interface IAppStoreCatalogReadyStatus extends IAppStoreCatalogStatusBase
   reason?: never;
 }
 
+/**
+ * Why no verified catalog is active, for programs; `reason` says it for operators.
+ *
+ * - `loading`: no attempt has ended since start and no last-known-good catalog was restored.
+ * - `failed`: the last attempt read no candidate (transport, integrity or packaging failed).
+ * - `refused`: the last attempt read a candidate and refused it (`refused` holds the record).
+ */
+export type TAppStoreCatalogUnavailableCause = 'loading' | 'failed' | 'refused';
+
 /** No verified catalog is active, neither a last-known-good one nor a fetched one. */
 export interface IAppStoreCatalogUnavailableStatus extends IAppStoreCatalogStatusBase {
   availability: 'unavailable';
-  /** Why no catalog is active, e.g. the last attempt's failure. */
+  /** Why no catalog is active, e.g. the last attempt's failure. For operators; never parse it. */
   reason: string;
+  /** Why no catalog is active, for programs. Every host that loads the catalog at runtime states it. */
+  cause?: TAppStoreCatalogUnavailableCause;
   active?: never;
 }
 
+/**
+ * The code a host answers, as `TypedResponseError.errorData` (`IAppStoreCatalogUnavailableErrorData`),
+ * when it refuses an App Store install, upgrade or upgrade preview because no verified catalog is
+ * active. Retryable: the same request succeeds once a catalog is active.
+ */
+export const appStoreCatalogUnavailableErrorCode = 'APPSTORE_CATALOG_UNAVAILABLE' as const;
+
+export interface IAppStoreCatalogUnavailableErrorData {
+  code: typeof appStoreCatalogUnavailableErrorCode;
+  retryable: true;
+  /** The status `cause` when the host states one. */
+  cause?: TAppStoreCatalogUnavailableCause;
+}
+
 /**
  * The App Store domain's state as an operator sees it, discriminated by `availability`.
  *
@@ -768,23 +794,167 @@ export const findAppStoreCatalogConfigDigestMismatch = async (
   return null;
 };
 
+/** The registries a consumer loads the catalog from when it configures none. */
+export const appStoreCatalogDefaultRegistries: readonly string[] = Object.freeze(['https://registry.npmjs.org']);
+
+const maximumRegistries = 16;
+const maximumRegistryUrlLength = 2048;
+
+/** The canonical base URL of one registry entry, or `null` when the entry is not admissible. */
+const readRegistryBaseUrl = (entryArg: unknown): string | null => {
+  if (typeof entryArg !== 'string' || entryArg.length > maximumRegistryUrlLength) return null;
+  let url: URL;
+  try {
+    url = new URL(entryArg);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' || url.username !== '' || url.password !== '' || url.search !== ''
+    || url.hash !== '' || entryArg.includes('?') || entryArg.includes('#')) {
+    return null;
+  }
+  return url.toString().replace(/\/+$/, '');
+};
+
+/**
+ * The errors of a configured registry list; empty when a consumer may load from it. Every entry is
+ * an `https:` base URL without credentials, query or fragment, no two name the same registry, and
+ * an empty list means `appStoreCatalogDefaultRegistries`. Errors name entries by index and never
+ * quote them, so a URL carrying credentials does not reach a log.
+ */
+export const validateAppStoreCatalogRegistries = (listArg: unknown): string[] => {
+  const entries = readDataElements(listArg, maximumRegistries);
+  if (entries === null) return [`registries must be a list of at most ${maximumRegistries} URLs`];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  entries.forEach((entryArg, indexArg) => {
+    const baseUrl = readRegistryBaseUrl(entryArg);
+    if (baseUrl === null) {
+      errors.push(`registries[${indexArg}] must be an https base URL without credentials, query or fragment`);
+    } else if (seen.has(baseUrl)) {
+      errors.push(`registries[${indexArg}] names a registry listed before it`);
+    } else {
+      seen.add(baseUrl);
+    }
+  });
+  return errors;
+};
+
+/**
+ * The registry base URLs a consumer asks, in order: the configured list in canonical form (no
+ * trailing slash), or `appStoreCatalogDefaultRegistries` when it is absent or empty. Throws the
+ * `validateAppStoreCatalogRegistries` errors for a list it refuses.
+ */
+export const resolveAppStoreCatalogRegistries = (listArg: readonly string[] | undefined): string[] => {
+  const errors = validateAppStoreCatalogRegistries(listArg ?? []);
+  if (errors.length > 0) throw new Error(`App Store catalog registries refused: ${errors.join('; ')}`);
+  const configured = (listArg ?? []).map((entryArg) => readRegistryBaseUrl(entryArg))
+    .filter((entryArg): entryArg is string => entryArg !== null);
+  return configured.length > 0 ? configured : [...appStoreCatalogDefaultRegistries];
+};
+
+/**
+ * The App Store version a service runs, as its host took it from a verified catalog.
+ *
+ * Server-managed: a host writes it when it installs or upgrades the service and when it adopts an
+ * existing service on catalog activation, and every runtime path reads this snapshot, never the
+ * live catalog. Published versions never change (`judgeAppStoreCatalogSuccession`), so a snapshot
+ * stays equal to its catalog entry for as long as the entry is listed.
+ */
+export interface IAppStoreServiceTemplateSnapshot {
+  appId: string;
+  version: string;
+  /** The catalog entry's `configDigest`: `computeAppStoreCatalogConfigDigest(config)`. */
+  configDigest: TSha256Digest;
+  config: TAppStoreCatalogVersionConfig;
+  /** The `revision` of the catalog the snapshot was taken from. */
+  catalogRevision: number;
+}
+
+/**
+ * The snapshot of `appId@version` from a verified catalog, or `null` when the catalog does not list
+ * it. Withdrawn versions are listed and snapshot like any other: a host adopting an installed
+ * service records the version it runs; whether a version is an install or upgrade target is
+ * `judgeAppStoreCatalogInstallTarget`. The config is a copy the caller owns.
+ */
+export const createAppStoreServiceTemplateSnapshot = (
+  catalogArg: IAppStoreCatalog,
+  appIdArg: string,
+  versionArg: string,
+): IAppStoreServiceTemplateSnapshot | null => {
+  const entry = catalogArg.apps.find((appArg) => appArg.info.id === appIdArg)
+    ?.versions.find((candidateArg) => candidateArg.version === versionArg);
+  if (entry === undefined) return null;
+  return {
+    appId: appIdArg,
+    version: entry.version,
+    configDigest: entry.configDigest,
+    config: structuredClone(entry.config),
+    catalogRevision: catalogArg.revision,
+  };
+};
+
+/** The hosts that consume the catalog; each version names its minimum release of each. */
+export type TAppStoreCatalogConsumerKind = 'onebox' | 'cloudly';
+
+/** The consumer judging a version: which host it is and the release it runs. */
+export interface IAppStoreCatalogConsumer {
+  kind: TAppStoreCatalogConsumerKind;
+  /** The host's own release, `MAJOR.MINOR.PATCH`. */
+  version: string;
+}
+
+const consumerMinimumVersionKeys = Object.freeze({
+  onebox: 'minOneboxVersion',
+  cloudly: 'minCloudlyVersion',
+} as const);
+
 /** Why a listed version is not an install or upgrade target for this consumer. */
 export type TAppStoreCatalogInstallTargetRefusal =
   | { reason: 'versionWithdrawn'; withdrawal: IAppStoreCatalogWithdrawal }
-  | { reason: 'featuresUnsupported'; missingFeatureIds: string[] };
+  | { reason: 'featuresUnsupported'; missingFeatureIds: string[] }
+  /** The version names a minimum release of this host (`minOneboxVersion`, `minCloudlyVersion`) newer than it runs. */
+  | {
+    reason: 'consumerVersionTooOld';
+    consumerKind: TAppStoreCatalogConsumerKind;
+    consumerVersion: string;
+    minimumVersion: string;
+  };
 
 /**
  * Whether a consumer may install a listed version, or upgrade a service to it; `null` when it may.
- * A withdrawn version and a version requiring a feature the consumer does not fulfil stay listed
- * and are refused here, and nowhere else is a second answer needed.
+ * A withdrawn version, a version requiring a feature the consumer does not fulfil and a version
+ * requiring a newer release of the consumer stay listed and are refused here, in that order, and
+ * nowhere else is a second answer needed.
+ *
+ * A host passes `consumerArg` on every call; without it the minimum release is not judged. A
+ * consumer version that is not `MAJOR.MINOR.PATCH` throws: it is the host's own constant.
  */
 export const judgeAppStoreCatalogInstallTarget = (
   versionArg: IAppStoreCatalogVersion,
   supportedFeatureIdsArg: Iterable<string>,
+  consumerArg?: IAppStoreCatalogConsumer,
 ): TAppStoreCatalogInstallTargetRefusal | null => {
+  const consumerVersion = consumerArg === undefined ? null : parseReleaseVersion(consumerArg.version);
+  if (consumerArg !== undefined && consumerVersion === null) {
+    throw new Error('App Store catalog consumer version must be MAJOR.MINOR.PATCH');
+  }
   if (versionArg.withdrawn !== undefined) return { reason: 'versionWithdrawn', withdrawal: versionArg.withdrawn };
   const missingFeatureIds = getAppStoreCatalogMissingFeatureIds(versionArg.config, supportedFeatureIdsArg);
-  return missingFeatureIds.length > 0 ? { reason: 'featuresUnsupported', missingFeatureIds } : null;
+  if (missingFeatureIds.length > 0) return { reason: 'featuresUnsupported', missingFeatureIds };
+  if (consumerArg === undefined || consumerVersion === null) return null;
+  const minimumVersion = versionArg.config[consumerMinimumVersionKeys[consumerArg.kind]];
+  if (minimumVersion === undefined) return null;
+  const minimum = parseReleaseVersion(minimumVersion);
+  if (minimum === null || compareReleaseVersions(consumerVersion, minimum) < 0) {
+    return {
+      reason: 'consumerVersionTooOld',
+      consumerKind: consumerArg.kind,
+      consumerVersion: consumerArg.version,
+      minimumVersion,
+    };
+  }
+  return null;
 };
 
 export type TAppStoreCatalogSuccession =

package/ts/appstore/types.ts

@@ -27,6 +27,7 @@ import type {
   TStorageResourceKind,
   TStorageSnapshotMode,
 } from '../platform/storage.js';
+import type { TAppStoreCatalogInstallTargetRefusal } from './catalog.js';
 
 export type TAppStorePlatformRequirement =
   | 'mongodb'
@@ -314,6 +315,18 @@ export const validateAppStoreVersionPlatformOidc = (
   return errors;
 };
 
+/** One listed version of an app as a host shows it: an install target, or why it is not one. */
+export interface IAppStoreAppVersionState {
+  version: string;
+  /**
+   * `null` when the host may install the version or upgrade a service to it; otherwise
+   * `versionWithdrawn` with the withdrawal, `featuresUnsupported` with the feature ids the host
+   * does not fulfil or `consumerVersionTooOld` with the host release the version requires, as
+   * `judgeAppStoreCatalogInstallTarget` answers it.
+   */
+  installRefusal: TAppStoreCatalogInstallTargetRefusal | null;
+}
+
 export interface IAppStoreApp {
   id: string;
   name: string;
@@ -323,6 +336,12 @@ export interface IAppStoreApp {
   iconUrl?: string;
   latestVersion: string;
   versions?: string[];
+  /**
+   * Every version the catalog lists, withdrawn and feature-gated ones included, in catalog order,
+   * each with whether this host may install it. `versions` names only the install targets; a view
+   * reads this member to show the others and why they are not offered.
+   */
+  versionStates?: IAppStoreAppVersionState[];
   tags?: string[];
   channel?: string;
   upgradeStrategy?: TAppStoreUpgradeStrategy;
@@ -346,6 +365,12 @@ export interface IAppStoreAppMeta {
   iconName?: string;
   latestVersion: string;
   versions: string[];
+  /**
+   * Every version the catalog lists, withdrawn and feature-gated ones included, in catalog order,
+   * each with whether this host may install it. `versions` names only the install targets; a view
+   * reads this member to show the others and why they are not offered.
+   */
+  versionStates?: IAppStoreAppVersionState[];
   maintainer?: string;
   links?: Record<string, string>;
   tags?: string[];

package/ts/data/clusternodehostname.ts

@@ -6,7 +6,7 @@ import { readExactDataRecord } from '../private/dataproperties.js';
  * Cloudly owns the hostname a node should carry (`IClusterNode.data.hostnameIntent`); Spark applies
  * it on the host and reports the hostname it observes, so a node has converged when its report
  * states the intent's hostname. The default scheme is `cloudly-worker-<name>`: `name` is the
- * operator's short name for the node (`ottilie`, `grasberg`), kept beside the hostname so the node
+ * operator's short name for the node (`alpha`, `bravo`), kept beside the hostname so the node
  * can always be reset to the default however it was renamed.
  *
  * A hostname here is one RFC 1123 label, lowercase: the node's short static hostname, which is
@@ -51,8 +51,8 @@ export const deriveDefaultClusterNodeHostname = (nameArg: string): string => {
  *
  * It reads the first label of the hostname, so a report that states a dotted name proposes its
  * short name. A label already in the default scheme proposes what follows the prefix
- * (`cloudly-worker-ottilie` → `ottilie`); any other valid label proposes itself unchanged
- * (`cloudlyworkergrasberg` stays `cloudlyworkergrasberg`). It never guesses a name out of a
+ * (`cloudly-worker-bravo` → `bravo`); any other valid label proposes itself unchanged
+ * (`cloudlyworkeralpha` stays `cloudlyworkeralpha`). It never guesses a name out of a
  * label in another scheme: an operator states that name when resetting the node to the default.
  */
 export const proposeClusterNodeName = (hostnameArg: string): string | null => {

package/ts/data/service.ts

@@ -1,6 +1,6 @@
 import type { IServiceRessources } from './docker.js';
 import type { IRegistryTarget } from './registry.js';
-import type { IAppStorePublishedPort } from '../appstore/index.js';
+import type { IAppStorePublishedPort, IAppStoreServiceTemplateSnapshot } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig, TServiceMailWritableConfig } from './mail.js';
 import type { IServiceWebPushConfig } from './webpush.js';
@@ -175,6 +175,12 @@ export interface IService {
     appTemplateId?: string;
     appTemplateVersion?: string;
     appStoreUpgradePolicy?: 'manual' | 'notify' | 'auto';
+    /**
+     * Server-managed snapshot of the App Store version the service runs (`appTemplateId`@
+     * `appTemplateVersion`), written at install, upgrade and catalog adoption. Runtime paths read
+     * it instead of the live catalog.
+     */
+    appStoreTemplate?: IAppStoreServiceTemplateSnapshot;
     hostedAppLifecycle?: IHostedAppLifecycleState;
     reconciliationStatus?: IServiceReconciliationStatus;
     environment: { [key: string]: string };
@@ -254,11 +260,13 @@ export interface IService {
 
 /**
  * Caller-writable service data. Immutable rollout state and SecretSet
- * attachments are changed only through their dedicated fenced APIs.
+ * attachments are changed only through their dedicated fenced APIs, and the
+ * App Store template snapshot only by the host's install and upgrade.
  */
 export type TServiceWritableData = Omit<
   IService['data'],
   | 'organizationId'
+  | 'appStoreTemplate'
   | 'immutableImageRequired'
   | 'imageDeployment'
   | 'imageRolloutStatus'

package/ts/data/settings.ts

@@ -63,6 +63,12 @@ export interface ICloudlySettings {
   coreMailDefaultMaxPendingInbound?: number;
   corebuildWorkerUrl?: string;
   corebuildWorkerUrls?: string[];
+  /**
+   * The npm registries Cloudly loads the App Store catalog from, in order. Absent or empty means
+   * `appstore.appStoreCatalogDefaultRegistries`; a value is accepted only when
+   * `appstore.validateAppStoreCatalogRegistries` answers no error.
+   */
+  appStoreCatalogRegistries?: string[];
 }
 
 export const cloudlySystemSecretOwner = Object.freeze({

package/ts/requests/appstore.ts

@@ -112,6 +112,28 @@ export interface IReq_Any_RefreshAppStoreCatalog extends plugins.typedrequestInt
   };
 }
 
+/**
+ * Imports a signed catalog envelope an operator carried in (an air-gapped host, or a catalog the
+ * registries do not serve yet) and answers the state after it. The host judges it exactly as a
+ * fetched one, authentication and succession included, and records it with origin
+ * `operatorImport`; the outcome is `status.lastAttempt`, and a refused envelope keeps the active
+ * catalog in place and is not a request error.
+ */
+export interface IReq_Any_ImportAppStoreCatalog extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_ImportAppStoreCatalog
+> {
+  method: 'importAppStoreCatalog';
+  request: {
+    identity: IIdentity;
+    /** The envelope file's text (`IAppStoreCatalogEnvelope` as JSON), e.g. `catalog.envelope.json`. */
+    envelopeText: string;
+  };
+  response: {
+    status: TAppStoreCatalogStatus;
+  };
+}
+
 export interface IReq_Any_GetAppStoreConfig extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_GetAppStoreConfig

package/ts/requests/hostedapp.ts

@@ -32,6 +32,12 @@ export interface IReq_GetHostedAppAccessConfiguration extends plugins.typedreque
       roles: data.IHostedAppRoleDefinition[];
       platformOidcSupported: boolean;
       platformOidcRegistration?: data.IHostedAppPlatformOidcRegistration;
+      /**
+       * Present when the host cannot read this app's roles and platform OIDC capability, e.g. the
+       * service holds no App Store template snapshot yet; `roles` is then empty and
+       * `platformOidcSupported` false. One such app never fails the whole listing.
+       */
+      unavailableReason?: string;
     }>;
   };
 }

package/ts/requests/node.ts

@@ -369,7 +369,7 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extend
  *
  * The node's name stays as it is: the new intent keeps the name of the node's current intent. A
  * node without an intent takes the name `data.proposeClusterNodeName(hostname)` (`foo` names the
- * node `foo`, `cloudly-worker-grasberg` names it `grasberg`), and is refused `name-invalid` when
+ * node `foo`, `cloudly-worker-alpha` names it `alpha`), and is refused `name-invalid` when
  * that is `null`.
  *
  * Cloudly records the intent and answers at once; Spark applies the intent of the latest

package/ts/runtime.appstorecatalog.ts

@@ -62,11 +62,96 @@ const publicKeyObjectOf = (publicKeyArg: string): plugins.crypto.KeyObject =>
     key: { kty: 'OKP', crv: 'Ed25519', x: Buffer.from(publicKeyArg, 'hex').toString('base64url') },
   });
 
+/** One PEM block of exactly this label and nothing around it but whitespace. */
+const isSinglePemBlock = (pemArg: string, labelArg: string): boolean =>
+  new RegExp(`^-----BEGIN ${labelArg}-----\\r?\\n(?:[A-Za-z0-9+/=]+\\r?\\n)+-----END ${labelArg}-----$`)
+    .test(pemArg.trim());
+
+const signingKeyOf = async (privateKeyArg: plugins.crypto.KeyObject): Promise<IAppStoreCatalogSigningKey> => {
+  const publicKey = rawPublicKeyOf(plugins.crypto.createPublicKey(privateKeyArg));
+  return { keyId: await computeAppStoreCatalogSigningKeyId(publicKey), publicKey, privateKey: privateKeyArg };
+};
+
+/** The Ed25519 private key of a signing key whose `publicKey` it matches; `keyId` is the caller's check. */
+const readSigningPrivateKey = (keyArg: IAppStoreCatalogSigningKey): plugins.crypto.KeyObject => {
+  const { privateKey } = keyArg;
+  if (!(privateKey instanceof plugins.crypto.KeyObject) || privateKey.type !== 'private'
+    || privateKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error('App Store catalog signing key must be an Ed25519 private key');
+  }
+  if (rawPublicKeyOf(plugins.crypto.createPublicKey(privateKey)) !== keyArg.publicKey) {
+    throw new Error(`App Store catalog signing key ${keyArg.keyId} does not match its private key`);
+  }
+  return privateKey;
+};
+
 /** A fresh Ed25519 catalog signing key with its key id. */
-export const createAppStoreCatalogSigningKey = async (): Promise<IAppStoreCatalogSigningKey> => {
-  const pair = plugins.crypto.generateKeyPairSync('ed25519');
-  const publicKey = rawPublicKeyOf(pair.publicKey);
-  return { keyId: await computeAppStoreCatalogSigningKeyId(publicKey), publicKey, privateKey: pair.privateKey };
+export const createAppStoreCatalogSigningKey = async (): Promise<IAppStoreCatalogSigningKey> =>
+  await signingKeyOf(plugins.crypto.generateKeyPairSync('ed25519').privateKey);
+
+/**
+ * Reads a catalog signing key from the text of a PKCS#8 PEM file holding an unencrypted Ed25519
+ * private key (`-----BEGIN PRIVATE KEY-----`, as `openssl genpkey -algorithm ed25519` writes it)
+ * and derives its public key and key id. Errors never quote the input.
+ */
+export const importAppStoreCatalogSigningKeyPem = async (pkcs8PemArg: string): Promise<IAppStoreCatalogSigningKey> => {
+  if (typeof pkcs8PemArg !== 'string' || !isSinglePemBlock(pkcs8PemArg, 'PRIVATE KEY')) {
+    throw new Error('App Store catalog signing key must be one unencrypted PKCS#8 PEM private key block');
+  }
+  let privateKey: plugins.crypto.KeyObject;
+  try {
+    privateKey = plugins.crypto.createPrivateKey({ key: pkcs8PemArg, format: 'pem' });
+  } catch {
+    throw new Error('App Store catalog signing key is not a readable PKCS#8 PEM private key');
+  }
+  if (privateKey.asymmetricKeyType !== 'ed25519') {
+    throw new Error('App Store catalog signing key must be an Ed25519 private key');
+  }
+  return await signingKeyOf(privateKey);
+};
+
+/** The PKCS#8 PEM text of a signing key, for the key file `importAppStoreCatalogSigningKeyPem` reads. */
+export const exportAppStoreCatalogSigningKeyPem = async (keyArg: IAppStoreCatalogSigningKey): Promise<string> => {
+  const privateKey = readSigningPrivateKey(keyArg);
+  if (await computeAppStoreCatalogSigningKeyId(keyArg.publicKey) !== keyArg.keyId) {
+    throw new Error(`App Store catalog signing key ${keyArg.keyId} does not match its public key`);
+  }
+  return privateKey.export({ format: 'pem', type: 'pkcs8' });
+};
+
+/** The trusted-key record a consumer ships for a signing key: its public half only. */
+export const getAppStoreCatalogTrustedKey = (keyArg: IAppStoreCatalogSigningKey): IAppStoreCatalogTrustedKey => ({
+  keyId: keyArg.keyId,
+  publicKey: keyArg.publicKey,
+});
+
+/**
+ * Reads a trusted key from the text of an SPKI PEM public key (`-----BEGIN PUBLIC KEY-----`, as
+ * `openssl pkey -pubout` writes it) holding an Ed25519 key. Errors never quote the input.
+ */
+export const importAppStoreCatalogTrustedKeyPem = async (spkiPemArg: string): Promise<IAppStoreCatalogTrustedKey> => {
+  if (typeof spkiPemArg !== 'string' || !isSinglePemBlock(spkiPemArg, 'PUBLIC KEY')) {
+    throw new Error('App Store catalog trusted key must be one SPKI PEM public key block');
+  }
+  let publicKeyObject: plugins.crypto.KeyObject;
+  try {
+    publicKeyObject = plugins.crypto.createPublicKey({ key: spkiPemArg, format: 'pem' });
+  } catch {
+    throw new Error('App Store catalog trusted key is not a readable SPKI PEM public key');
+  }
+  if (publicKeyObject.type !== 'public' || publicKeyObject.asymmetricKeyType !== 'ed25519') {
+    throw new Error('App Store catalog trusted key must be an Ed25519 public key');
+  }
+  const publicKey = rawPublicKeyOf(publicKeyObject);
+  return { keyId: await computeAppStoreCatalogSigningKeyId(publicKey), publicKey };
+};
+
+/** The SPKI PEM text of a trusted key whose `keyId` matches its public key. */
+export const exportAppStoreCatalogTrustedKeyPem = async (keyArg: IAppStoreCatalogTrustedKey): Promise<string> => {
+  if (await computeAppStoreCatalogSigningKeyId(keyArg.publicKey) !== keyArg.keyId) {
+    throw new Error(`App Store catalog trusted key ${keyArg.keyId} does not match its public key`);
+  }
+  return publicKeyObjectOf(keyArg.publicKey).export({ format: 'pem', type: 'spki' });
 };
 
 /**
@@ -91,13 +176,8 @@ export const signAppStoreCatalog = async (
   const payload = createAppStoreCatalogSignaturePayload(catalogDigest);
   const signatures: IAppStoreCatalogSignature[] = [];
   for (const key of signingKeysArg) {
-    const { privateKey } = key;
-    if (!(privateKey instanceof plugins.crypto.KeyObject) || privateKey.type !== 'private'
-      || privateKey.asymmetricKeyType !== 'ed25519') {
-      throw new Error('App Store catalog signing key must be an Ed25519 private key');
-    }
-    const publicKey = rawPublicKeyOf(plugins.crypto.createPublicKey(privateKey));
-    if (publicKey !== key.publicKey || await computeAppStoreCatalogSigningKeyId(publicKey) !== key.keyId) {
+    const privateKey = readSigningPrivateKey(key);
+    if (await computeAppStoreCatalogSigningKeyId(key.publicKey) !== key.keyId) {
       throw new Error(`App Store catalog signing key ${key.keyId} does not match its private key`);
     }
     signatures.push({