@serve.zone/interfaces 32.51.0 → 32.53.0

package/ts/data/clusternodehostname.ts

@@ -0,0 +1,153 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+
+/**
+ * The static hostname a cluster node runs under, and the scheme Cloudly names a node by default.
+ *
+ * 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 (`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
+ * what enrollment already requires of a host. A fully qualified name is DNS, not the host's name.
+ */
+export const clusterNodeHostnameContract = Object.freeze({
+  /** The default hostname is this prefix followed by the node's name. */
+  defaultPrefix: 'cloudly-worker-',
+  /** One DNS label. */
+  maximumHostnameLength: 63,
+  /** What is left of one label after `defaultPrefix`. */
+  maximumNameLength: 48,
+  /** `requestedBy` is an identity's user id. */
+  maximumRequestedByLength: 256,
+  error: 'Cluster node hostname contract rejected.',
+} as const);
+
+const hostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** True for one lowercase RFC 1123 label of 1 to 63 characters: a node's static hostname. */
+export const isClusterNodeHostname = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= clusterNodeHostnameContract.maximumHostnameLength
+  && hostnameLabel.test(valueArg)
+);
+
+/** True for a node name the default scheme can carry: a label of at most 48 characters. */
+export const isClusterNodeName = (valueArg: unknown): valueArg is string => (
+  isClusterNodeHostname(valueArg) && valueArg.length <= clusterNodeHostnameContract.maximumNameLength
+);
+
+/** `cloudly-worker-<name>`; throws for a name the scheme cannot carry. */
+export const deriveDefaultClusterNodeHostname = (nameArg: string): string => {
+  if (!isClusterNodeName(nameArg)) {
+    throw new Error(clusterNodeHostnameContract.error);
+  }
+  return `${clusterNodeHostnameContract.defaultPrefix}${nameArg}`;
+};
+
+/**
+ * The node name an observed hostname suggests, or `null` when it suggests none.
+ *
+ * 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-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 => {
+  const label = hostnameArg.split('.')[0];
+  if (!isClusterNodeHostname(label)) {
+    return null;
+  }
+  const prefix = clusterNodeHostnameContract.defaultPrefix;
+  if (label.startsWith(prefix) && isClusterNodeName(label.slice(prefix.length))) {
+    return label.slice(prefix.length);
+  }
+  return isClusterNodeName(label) ? label : null;
+};
+
+/** The hostname Cloudly wants a node to carry; `IClusterNode.data.hostnameIntent`. */
+export interface IClusterNodeHostnameIntent {
+  /** The node's name: the input of the default scheme, and what a reset to the default uses. */
+  name: string;
+  /** The static hostname the node should carry; the default derived from `name` or any other label. */
+  hostname: string;
+  /** Counts accepted intents from 1; a change names the generation it replaces. */
+  generation: number;
+  /** Unix milliseconds on Cloudly's clock when this intent was accepted. */
+  requestedAt: number;
+  /** The administrator who asked for it; absent for the intent enrollment or a migration recorded. */
+  requestedBy?: string;
+}
+
+/** True when the intent's hostname is the default its name derives. */
+export const isDefaultClusterNodeHostname = (intentArg: IClusterNodeHostnameIntent): boolean => (
+  isClusterNodeName(intentArg.name) && intentArg.hostname === deriveDefaultClusterNodeHostname(intentArg.name)
+);
+
+const fail = (): never => { throw new Error(clusterNodeHostnameContract.error); };
+function requireValue(valueArg: unknown): asserts valueArg {
+  if (!valueArg) fail();
+}
+const counter = (valueArg: unknown, minimumArg: number): number => {
+  requireValue(typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minimumArg);
+  return valueArg;
+};
+
+/** Exact, detached and frozen; refuses every key and value this contract does not state. */
+export const snapshotClusterNodeHostnameIntent = (valueArg: unknown): IClusterNodeHostnameIntent => {
+  const keys = ['name', 'hostname', 'generation', 'requestedAt'];
+  const value = readExactDataRecord(valueArg, keys) ?? readExactDataRecord(valueArg, [...keys, 'requestedBy']);
+  requireValue(value !== null);
+  requireValue(isClusterNodeName(value.name) && isClusterNodeHostname(value.hostname));
+  const intent: IClusterNodeHostnameIntent = {
+    name: value.name, hostname: value.hostname,
+    generation: counter(value.generation, 1), requestedAt: counter(value.requestedAt, 1),
+  };
+  if (Object.hasOwn(value, 'requestedBy')) {
+    const requestedBy = value.requestedBy;
+    requireValue(typeof requestedBy === 'string' && requestedBy.length > 0
+      && requestedBy.length <= clusterNodeHostnameContract.maximumRequestedByLength
+      && /^[\x21-\x7e]+$/.test(requestedBy));
+    intent.requestedBy = requestedBy;
+  }
+  return Object.freeze(intent);
+};
+
+/**
+ * Every reason Cloudly answers instead of renaming a node or resetting it to the default. Each
+ * travels by name as a `TypedResponseError`, and a refused request changes nothing.
+ */
+export const clusterNodeHostnameRefusals = Object.freeze([
+  /** No node of that id exists. */
+  'node-missing',
+  /** The requested hostname is not one lowercase RFC 1123 label (`isClusterNodeHostname`). */
+  'hostname-invalid',
+  /**
+   * The node would carry no name the default scheme can carry (`isClusterNodeName`). A rename keeps
+   * the name of the node's intent; a node without an intent takes
+   * `proposeClusterNodeName(<requested hostname>)`, and is refused when that is `null`. A reset
+   * names no valid name, or names none while the node has no intent whose name it could reuse.
+   */
+  'name-invalid',
+  /** Another node of the cluster carries that hostname, as reported or as its intent. */
+  'hostname-in-use',
+  /** The node's intent already is that hostname under that name. */
+  'hostname-unchanged',
+  /**
+   * Cloudly holds state naming the node by its current hostname that it cannot move to the new
+   * hostname with the change, such as a rollout in flight that targets the node.
+   */
+  'node-hostname-referenced',
+  /** The node does not run the Pallet-era node runtime, the only one that applies a hostname. */
+  'node-runtime-unsupported',
+  /**
+   * `expectedGeneration` is not the node's current intent generation: read the node again. This
+   * fence alone serializes changes; an intent the node has not converged to may always be replaced.
+   */
+  'conflict',
+] as const);
+
+/** One of the reasons Cloudly answers instead of a hostname change. */
+export type TClusterNodeHostnameRefusalCode = typeof clusterNodeHostnameRefusals[number];

package/ts/data/index.ts

@@ -72,6 +72,7 @@ export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';
 export * from './clusternode.js';
+export * from './clusternodehostname.js';
 export * from './settings.js';
 export * from './sparklegacyretirement.js';
 export * from './sparknodereport.js';

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/data/sparknodereport.ts

@@ -1,7 +1,8 @@
 import { isReleaseVersion } from './releaseversion.js';
-import { readExactDataRecord } from '../private/dataproperties.js';
+import { readDataProperties, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
+import { isClusterNodeHostname } from './clusternodehostname.js';
 
 /** Host observations only. Container and workload readiness belong to Pallet. */
 export interface ISparkNodeReport {
@@ -22,8 +23,32 @@ export interface ISparkNodeReport {
     localRuntimeReady: true;
     workloadReadiness: 'unverified';
   };
+  /**
+   * The outcome of Spark's last attempt to apply a desired hostname (`sparkNodeHostContract`), when
+   * it made one since it started. Whether the node carries the hostname is `runtime.hostname`.
+   */
+  hostApply?: ISparkNodeHostApply;
 }
 
+/** Whether Spark applied a desired hostname: `applied` once the host carries it. */
+export type TSparkNodeHostApplyOutcome = 'applied' | 'failed';
+
+/** One attempt to apply the desired hostname of one generation. */
+export interface ISparkNodeHostApply {
+  /** The `ISparkNodeDesiredHost.generation` the attempt applied. */
+  generation: number;
+  /** The hostname it applied. */
+  hostname: string;
+  outcome: TSparkNodeHostApplyOutcome;
+  /** `failed` only, and required there: why, as operator text. */
+  reason?: string;
+}
+
+/** Bounds of `ISparkNodeHostApply.reason`. */
+export const sparkNodeHostApplyContract = Object.freeze({
+  maximumReasonLength: 512,
+} as const);
+
 /** HTTPS POST body. Never log, persist, or return nodeToken. */
 export interface ISparkNodeHeartbeatRequest {
   nodeId: string;
@@ -101,9 +126,28 @@ const integer = (valueArg: unknown, minimumArg: number): number => {
   return value;
 };
 
+/** One `hostApply`: exactly its keys, a reason exactly when it failed. */
+const snapshotSparkNodeHostApply = (valueArg: unknown): ISparkNodeHostApply => {
+  const keys = ['generation', 'hostname', 'outcome'];
+  const value = readExactDataRecord(valueArg, keys) ?? record(valueArg, [...keys, 'reason']);
+  requireValue(isClusterNodeHostname(value.hostname));
+  const generation = integer(value.generation, 1);
+  if (value.outcome === 'applied') {
+    requireValue(value.reason === undefined);
+    return Object.freeze({ generation, hostname: value.hostname, outcome: 'applied' });
+  }
+  requireValue(value.outcome === 'failed');
+  return Object.freeze({ generation, hostname: value.hostname, outcome: 'failed',
+    reason: text(value.reason, /^[\x20-\x7e]+$/, sparkNodeHostApplyContract.maximumReasonLength) });
+};
+
 /** Exact inert JSON records; detaches and freezes before any consumer awaits. */
 export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport => {
-  const value = record(valueArg, ['observedAt', 'metrics', 'runtime']);
+  const reportKeys = ['observedAt', 'metrics', 'runtime'];
+  const properties = readDataProperties(valueArg);
+  requireValue(properties !== null);
+  const hasHostApply = Object.hasOwn(properties, 'hostApply');
+  const value = record(valueArg, hasHostApply ? [...reportKeys, 'hostApply'] : reportKeys);
   const metrics = record(value.metrics, ['cpuUsagePercent', 'memoryUsedMB', 'memoryAvailableMB',
     'diskUsedGB', 'diskAvailableGB']);
   const runtime = record(value.runtime, ['hostname', 'platform', 'arch', 'osRelease', 'bundle',
@@ -130,6 +174,7 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
       }),
       localRuntimeReady: true, workloadReadiness: 'unverified',
     }),
+    ...(hasHostApply ? { hostApply: snapshotSparkNodeHostApply(value.hostApply) } : {}),
   });
 };
 
@@ -155,3 +200,68 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg: unknown): ISparkNode
     protocol: readProtocolOffer(value),
   });
 };
+
+/** HTTPS POST body asking for the hostname Cloudly wants the node to carry. Never log, persist, or return nodeToken. */
+export interface ISparkNodeHostRequest {
+  nodeId: string;
+  nodeToken: string;
+  /** Read and negotiated before the node is authenticated; see `sparkNodeHostContract`. */
+  protocol: IProtocolOffer;
+}
+
+/**
+ * The hostname Cloudly wants the node to carry: `IClusterNode.data.hostnameIntent`, as the node
+ * applies it.
+ *
+ * `hostname: null` with `generation: 0` states that Cloudly holds no intent for the node, and Spark
+ * leaves the host's hostname as it is. Applying is idempotent: a host that already carries the
+ * hostname is left alone, and every answer states the whole desired value rather than a change.
+ */
+export interface ISparkNodeDesiredHost {
+  nodeId: string;
+  hostname: string | null;
+  generation: number;
+  /** The controller's offer, so the node judges the answer it acts on. */
+  protocol: IProtocolOffer;
+}
+
+/**
+ * The node runtime's desired-host route.
+ *
+ * Authenticated with the node's Spark credential exactly like `sparkNodeHeartbeatContract`, and
+ * judged in the same server order: protocol offer first, against this server's `sparkNode` offer
+ * and within `maxRequestBytes`, answered with `protocolRefusalStatus` and an `IProtocolRefusal` body
+ * on refusal, before the node is authenticated. Spark reports the outcome of applying the answer as
+ * `ISparkNodeReport.hostApply` on its next heartbeat.
+ */
+export const sparkNodeHostContract = Object.freeze({
+  endpoint: '/spark/nodes/host',
+  maxRequestBytes: 1024,
+  maxResponseBytes: 1024,
+  protocolRefusalStatus: protocolRefusalHttpStatus,
+} as const);
+
+export const snapshotSparkNodeHostRequest = (valueArg: unknown): ISparkNodeHostRequest => {
+  const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol']);
+  return Object.freeze({
+    nodeId: nodeId(value.nodeId),
+    nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
+    protocol: readProtocolOffer(value),
+  });
+};
+
+export const snapshotSparkNodeDesiredHost = (valueArg: unknown): ISparkNodeDesiredHost => {
+  const value = record(valueArg, ['nodeId', 'hostname', 'generation', 'protocol']);
+  const hostname = value.hostname;
+  if (hostname === null) {
+    requireValue(value.generation === 0);
+  } else {
+    requireValue(isClusterNodeHostname(hostname));
+  }
+  return Object.freeze({
+    nodeId: nodeId(value.nodeId),
+    hostname,
+    generation: hostname === null ? 0 : integer(value.generation, 1),
+    protocol: readProtocolOffer(value),
+  });
+};

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

@@ -150,6 +150,13 @@ export interface IReq_Any_Cloudly_CreateNodeJumpCommand extends plugins.typedreq
     role?: IClusterNode['data']['role'];
     nodeType?: IClusterNode['data']['nodeType'];
     ttlMs?: number;
+    /**
+     * The new node's name (`data.isClusterNodeName`). The setup command names the host
+     * `cloudly-worker-<nodeName>` (`data.deriveDefaultClusterNodeHostname`) before it enrolls, so
+     * the node enrolls under its default hostname. Absent, the node keeps the hostname it has and
+     * its name is proposed from that (`data.proposeClusterNodeName`).
+     */
+    nodeName?: string;
   };
   response: {
     jumpCode: string;
@@ -356,6 +363,66 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extend
   };
 }
 
+/**
+ * An administrator renames a node: the static hostname Cloudly wants it to carry
+ * (`IClusterNode.data.hostnameIntent.hostname`).
+ *
+ * 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-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
+ * generation on the host and the node has converged when its report states the new hostname. A new
+ * intent may replace one the node has not converged to, whether it is still applying, failed or
+ * never reached the node. `expectedGeneration` is the generation of the node's current intent, `0`
+ * when it has none, and serializes concurrent changes. Every refusal is one of
+ * `data.clusterNodeHostnameRefusals` and changes nothing.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeHostname
+> {
+  method: 'setClusterNodeHostname';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    expectedGeneration: number;
+    /** One lowercase RFC 1123 label (`data.isClusterNodeHostname`). */
+    hostname: string;
+  };
+  response: {
+    /** The node as it now stands, carrying the new intent. */
+    node: IClusterNode;
+  };
+}
+
+/**
+ * An administrator resets a node to the default scheme: hostname `cloudly-worker-<name>`
+ * (`data.deriveDefaultClusterNodeHostname`).
+ *
+ * `name` replaces the node's name when stated; absent, the name of the node's current intent is
+ * used, and a node without an intent is refused `name-invalid`. Recorded, applied and replaceable
+ * exactly like `setClusterNodeHostname`, with the same refusals.
+ */
+export interface IReq_Any_Cloudly_ResetClusterNodeHostname extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_ResetClusterNodeHostname
+> {
+  method: 'resetClusterNodeHostname';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    expectedGeneration: number;
+    /** The node's name (`data.isClusterNodeName`). */
+    name?: string;
+  };
+  response: {
+    /** The node as it now stands, carrying the new intent. */
+    node: IClusterNode;
+  };
+}
+
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_Cloudly_CreateNodeAction

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({