@serve.zone/interfaces 32.48.0 → 32.50.0

package/ts/appstore/catalog.ts

@@ -0,0 +1,851 @@
+/**
+ * The App Store catalog contract: the one signed document a consumer loads at runtime.
+ *
+ * A catalog carries every app, every published version and every version's runtime config, so a
+ * consumer that holds one verified catalog holds the whole App Store. What a consumer has to
+ * understand is the contract — the shapes below, their digests and signature, and the gates a
+ * version declares. Everything else is data: new apps and versions, image digests, changelogs and
+ * descriptions arrive with the next catalog revision and need no consumer release.
+ *
+ * This module is browser-safe: digests use Web Crypto. Ed25519 signing and verification live in
+ * the Node-only `./runtime` export (`runtime.appstorecatalog.ts`).
+ */
+import type { TSha256Digest } from '../data/immutableimage.js';
+import { getDigestFromPinnedImageReference, isSha256Digest } from '../data/immutableimage.js';
+import {
+  canonicalizeStrictJson,
+  compareWireTokens,
+  createCanonicalJsonSha256Hex,
+} from '../private/canonicaljson.js';
+import { hasExactKeys, readDataElements, readDataProperties } from '../private/dataproperties.js';
+import type { TCompleteKeyList } from '../private/keylist.js';
+import { validateAppStoreVersionConfig } from './versionconfig.js';
+import type {
+  IAppStoreVersionConfig,
+  IServezoneAppStoreAppInfo,
+  TAppStoreUpgradeStrategy,
+} from './types.js';
+
+/**
+ * The contract identity, digest domains and bounds every catalog producer and consumer shares.
+ *
+ * `major` changes when a catalog written against it cannot be read by a consumer of the previous
+ * major. `minor` changes when catalog-level structure is added; a consumer reads every catalog of
+ * its own major whose minor is not newer than its own, and refuses the rest as
+ * `contractUnsupported`. New version-config capabilities do not need a minor: they are gated per
+ * version through `requiresFeatures` (see `IAppStoreVersionConfig.requiresFeatures`).
+ */
+export const appStoreCatalogContract = Object.freeze({
+  id: 'serve.zone/appstore-catalog',
+  major: 1,
+  minor: 0,
+  digestAlgorithm: 'sha256',
+  signatureAlgorithm: 'ed25519',
+  configDigestDomain: 'serve.zone/appstore-catalog/version-config',
+  catalogDigestDomain: 'serve.zone/appstore-catalog/catalog',
+  signatureDomain: 'serve.zone/appstore-catalog/signature',
+  signingKeyIdDomain: 'serve.zone/appstore-catalog/signing-key',
+  maximumApps: 1024,
+  maximumVersionsPerApp: 1024,
+  maximumSignatures: 8,
+  maximumTags: 32,
+  maximumLinks: 32,
+  maximumConfigListEntries: 256,
+  maximumRequiredFeatures: 64,
+} as const);
+
+/** Which contract a catalog was written against. */
+export interface IAppStoreCatalogContractIdentity {
+  id: typeof appStoreCatalogContract.id;
+  major: number;
+  minor: number;
+}
+
+/**
+ * A version's runtime config as a catalog carries it.
+ *
+ * The members that only exist to resolve a live source (`source`, `resolvedSource`,
+ * `resolvedImageDigest`), the per-version `upgradeStrategy` and the `appStoreVersion` override
+ * are not part of a signed catalog: the catalog is self-contained, the image is digest-pinned,
+ * the app states its upgrade strategy once and the version entry names its own version.
+ */
+export type TAppStoreCatalogVersionConfig = Omit<
+  IAppStoreVersionConfig,
+  'source' | 'resolvedSource' | 'resolvedImageDigest' | 'upgradeStrategy' | 'appStoreVersion'
+>;
+
+const versionConfigKeyList = [
+  'image',
+  'port',
+  'containerArgs',
+  'targetPorts',
+  'domains',
+  'publicPortMappings',
+  'envVars',
+  'volumes',
+  'storageClasses',
+  'storageRequests',
+  'publishedPorts',
+  'platformRequirements',
+  'platformOidc',
+  'minOneboxVersion',
+  'minCloudlyVersion',
+  'changelog',
+  'breaking',
+  'requiresManualReview',
+  'migrationRequired',
+  'backupBeforeUpgrade',
+  'requiresFeatures',
+  'healthCheck',
+] as const;
+
+/** Every member a catalog version config may carry; any other member is refused. */
+export const appStoreCatalogVersionConfigKeys: TCompleteKeyList<
+  TAppStoreCatalogVersionConfig,
+  typeof versionConfigKeyList
+> = Object.freeze(versionConfigKeyList);
+
+/** Why and when a publisher withdrew a published version. */
+export interface IAppStoreCatalogWithdrawal {
+  /** Canonical UTC timestamp, not later than the catalog's `publishedAt`. */
+  at: string;
+  /** One line an operator reads, e.g. the advisory that caused it. */
+  reason: string;
+}
+
+/**
+ * One published version. Once published, `app@version` stays in every later catalog with the same
+ * `configDigest` (`judgeAppStoreCatalogSuccession`).
+ */
+export interface IAppStoreCatalogVersion {
+  version: string;
+  config: TAppStoreCatalogVersionConfig;
+  /** `computeAppStoreCatalogConfigDigest(config)`. */
+  configDigest: TSha256Digest;
+  /**
+   * Present once the publisher withdrew the version. A withdrawn version stays listed with its
+   * config, so installed services keep reading it, but it is never an install or upgrade target
+   * (`judgeAppStoreCatalogInstallTarget`). A withdrawal is final: every later catalog carries the
+   * same record.
+   */
+  withdrawn?: IAppStoreCatalogWithdrawal;
+}
+
+/** The upgrade strategies a self-contained catalog can express; live digest tracking is not one. */
+export type TAppStoreCatalogUpgradeStrategy = Exclude<TAppStoreUpgradeStrategy, 'dockerDigest'>;
+
+export interface IAppStoreCatalogApp {
+  info: IServezoneAppStoreAppInfo;
+  /**
+   * Names a listed version that is not withdrawn; under `semver` the highest of them. When every
+   * version is withdrawn, the app is withdrawn and `latestVersion` names a listed version (under
+   * `semver` the highest).
+   */
+  latestVersion: string;
+  /**
+   * Absent means `semver`: every version is `MAJOR.MINOR.PATCH` and `latestVersion` is the
+   * highest. `branch` versions are opaque tokens and `latestVersion` is the publisher's choice.
+   */
+  upgradeStrategy?: TAppStoreCatalogUpgradeStrategy;
+  versions: IAppStoreCatalogVersion[];
+}
+
+export interface IAppStoreCatalog {
+  contract: IAppStoreCatalogContractIdentity;
+  /**
+   * Strictly increasing across every catalog a publisher signs. A consumer activates a catalog
+   * only when its revision is greater than the active one (`judgeAppStoreCatalogSuccession`).
+   */
+  revision: number;
+  /** `Date.prototype.toISOString()` form, UTC. */
+  publishedAt: string;
+  /** The source commit the catalog was generated from (40 or 64 lower-case hex). */
+  sourceRevision: string;
+  apps: IAppStoreCatalogApp[];
+}
+
+/** An Ed25519 signature over `createAppStoreCatalogSignaturePayload(catalogDigest)`. */
+export interface IAppStoreCatalogSignature {
+  /** `computeAppStoreCatalogSigningKeyId(publicKey)` of the signing key. */
+  keyId: TSha256Digest;
+  /** 64-byte Ed25519 signature, lower-case hex. */
+  signature: string;
+}
+
+/** What a publisher ships and a consumer stores as its last-known-good catalog. */
+export interface IAppStoreCatalogEnvelope {
+  catalog: IAppStoreCatalog;
+  /** `computeAppStoreCatalogDigest(catalog)`. */
+  catalogDigest: TSha256Digest;
+  /** At least one; a consumer needs one valid signature by a key it trusts. */
+  signatures: IAppStoreCatalogSignature[];
+}
+
+/** A signing key a consumer trusts. Shipped with the consumer release, never fetched. */
+export interface IAppStoreCatalogTrustedKey {
+  keyId: TSha256Digest;
+  /** Raw 32-byte Ed25519 public key, lower-case hex. */
+  publicKey: string;
+}
+
+/** Whether a consumer holds a verified catalog. Nothing outside the App Store depends on it. */
+export type TAppStoreCatalogAvailability = TAppStoreCatalogStatus['availability'];
+
+export type TAppStoreCatalogRefusalReason =
+  /** The catalog names another contract id, another major, or a newer minor. */
+  | 'contractUnsupported'
+  /** No valid signature by a trusted key, or a signature by a trusted key that does not verify. */
+  | 'signatureInvalid'
+  /** `catalogDigest` or a `configDigest` does not match its content. */
+  | 'digestMismatch'
+  /** The envelope or catalog does not satisfy this contract's exact schema. */
+  | 'schemaInvalid'
+  /** The revision is not greater than the active catalog's revision. */
+  | 'revisionRegressed'
+  /** A version the active catalog published carries a different config digest. */
+  | 'publishedVersionMutated'
+  /** A version the active catalog published is no longer listed. */
+  | 'publishedVersionRemoved'
+  /** A withdrawal the active catalog published is revoked or rewritten. */
+  | 'publishedWithdrawalChanged';
+
+export interface IAppStoreCatalogRefusal {
+  reason: TAppStoreCatalogRefusalReason;
+  message: string;
+}
+
+/** A refusal as a consumer records it in its status. */
+export interface IAppStoreCatalogRefusalRecord extends IAppStoreCatalogRefusal {
+  at: string;
+  /** The refused catalog's revision, when it could be read. */
+  revision?: number;
+}
+
+/** Where the active catalog came from. */
+export type TAppStoreCatalogOrigin = 'registry' | 'operatorImport';
+
+export interface IAppStoreCatalogActiveState {
+  contract: IAppStoreCatalogContractIdentity;
+  revision: number;
+  catalogDigest: TSha256Digest;
+  publishedAt: string;
+  sourceRevision: string;
+  /** When this consumer activated it. */
+  loadedAt: string;
+  /** The trusted key whose signature this consumer verified. */
+  keyId: TSha256Digest;
+  origin: TAppStoreCatalogOrigin;
+}
+
+export type TAppStoreCatalogAttemptOutcome = 'activated' | 'unchanged' | 'refused' | 'failed';
+
+export interface IAppStoreCatalogAttempt {
+  at: string;
+  outcome: TAppStoreCatalogAttemptOutcome;
+  /** Why a `refused` or `failed` attempt ended; absent for the other outcomes. */
+  message?: string;
+}
+
+/** What every catalog status states, whatever its availability. */
+export interface IAppStoreCatalogStatusBase {
+  /** The contract this consumer reads. */
+  supportedContract: IAppStoreCatalogContractIdentity;
+  /** The feature ids this consumer fulfils, in canonical order. */
+  supportedFeatureIds: string[];
+  lastAttempt?: IAppStoreCatalogAttempt;
+  nextAttemptAt?: string;
+  /** The most recent catalog this consumer refused, kept while the active one stays in place. */
+  refused?: IAppStoreCatalogRefusalRecord;
+}
+
+/**
+ * A verified catalog is active: the last-known-good one restored at start or the latest one
+ * accepted since. A later refused or failed attempt leaves it active and the status `ready`.
+ */
+export interface IAppStoreCatalogReadyStatus extends IAppStoreCatalogStatusBase {
+  availability: 'ready';
+  active: IAppStoreCatalogActiveState;
+  reason?: never;
+}
+
+/** 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. */
+  reason: string;
+  active?: never;
+}
+
+/**
+ * The App Store domain's state as an operator sees it, discriminated by `availability`.
+ *
+ * Loading a catalog never gates the boot, readiness or health of anything else. While no verified
+ * catalog is active, `availability` is `unavailable`, `reason` says why and only App Store
+ * install, upgrade and upgrade-preview actions are refused with that reason.
+ */
+export type TAppStoreCatalogStatus = IAppStoreCatalogReadyStatus | IAppStoreCatalogUnavailableStatus;
+
+/** The consumer side of `requiresFeatures`. */
+export interface IAppStoreCatalogValidationOptions {
+  /** Feature ids this consumer fulfils, e.g. `appStoreStorageFeatureIds` values. */
+  supportedFeatureIds: Iterable<string>;
+}
+
+const withdrawalReasonMaximumLength = 512;
+const semverPattern = /^(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})\.(0|[1-9][0-9]{0,14})$/;
+const versionTokenPattern = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/;
+const appIdPattern = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const iconNamePattern = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const tagPattern = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+const linkLabelPattern = /^[A-Za-z][A-Za-z0-9 _-]{0,63}$/;
+const featureIdPattern = /^(?=.{1,128}$)[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
+const sourceRevisionPattern = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const publicKeyPattern = /^[0-9a-f]{64}$/;
+const signaturePattern = /^[0-9a-f]{128}$/;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
+const multilineControlCharacterPattern = /[\u0000-\u0008\u000b-\u001f\u007f]/;
+
+const isNonNegativeSafeInteger = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0;
+
+const isPort = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 1 && valueArg <= 65535;
+
+const isLine = (valueArg: unknown, maximumLengthArg: number): valueArg is string =>
+  typeof valueArg === 'string'
+  && valueArg.length > 0
+  && valueArg.length <= maximumLengthArg
+  && valueArg.trim() === valueArg
+  && !controlCharacterPattern.test(valueArg);
+
+const isText = (valueArg: unknown, maximumLengthArg: number): valueArg is string =>
+  typeof valueArg === 'string'
+  && valueArg.length > 0
+  && valueArg.length <= maximumLengthArg
+  && !multilineControlCharacterPattern.test(valueArg);
+
+const isHttpsUrl = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string' || valueArg.length > 2048) return false;
+  try {
+    const url = new URL(valueArg);
+    return url.protocol === 'https:' && url.username === '' && url.password === '';
+  } catch {
+    return false;
+  }
+};
+
+const isCanonicalTimestamp = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') return false;
+  const time = Date.parse(valueArg);
+  return Number.isFinite(time) && new Date(time).toISOString() === valueArg;
+};
+
+const compareSemver = (leftArg: string, rightArg: string): number => {
+  const left = leftArg.split('.').map(Number);
+  const right = rightArg.split('.').map(Number);
+  for (let index = 0; index < 3; index++) {
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+};
+
+/** True when a value is a canonical feature-id list: valid ids, strictly increasing. */
+const isCanonicalFeatureIdList = (valueArg: unknown): valueArg is string[] => {
+  const entries = readDataElements(valueArg, appStoreCatalogContract.maximumRequiredFeatures);
+  if (entries === null) return false;
+  let previous: string | null = null;
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || !featureIdPattern.test(entry)) return false;
+    if (previous !== null && compareWireTokens(previous, entry) >= 0) return false;
+    previous = entry;
+  }
+  return true;
+};
+
+/**
+ * The feature ids a version config requires that the consumer does not fulfil.
+ *
+ * Empty when the version is installable by this consumer. A malformed `requiresFeatures` is a
+ * schema error that `validateAppStoreCatalog` reports; here it yields no missing ids.
+ */
+export const getAppStoreCatalogMissingFeatureIds = (
+  configArg: unknown,
+  supportedFeatureIdsArg: Iterable<string>,
+): string[] => {
+  const config = readDataProperties(configArg);
+  if (config === null || !isCanonicalFeatureIdList(config.requiresFeatures)) return [];
+  const supported = new Set(supportedFeatureIdsArg);
+  return config.requiresFeatures.filter((featureIdArg) => !supported.has(featureIdArg));
+};
+
+/**
+ * Whether a catalog is written against a contract this consumer reads.
+ *
+ * `null` when it is. A malformed or absent `contract` member is `schemaInvalid`; a well-formed
+ * identity naming another id, another major or a newer minor is `contractUnsupported`.
+ */
+export const judgeAppStoreCatalogContract = (catalogArg: unknown): IAppStoreCatalogRefusal | null => {
+  const catalog = readDataProperties(catalogArg);
+  const identity = catalog === null ? null : readDataProperties(catalog.contract);
+  if (identity === null || !hasExactKeys(identity, ['id', 'major', 'minor'])
+    || typeof identity.id !== 'string'
+    || !isNonNegativeSafeInteger(identity.major) || !isNonNegativeSafeInteger(identity.minor)) {
+    return {
+      reason: 'schemaInvalid',
+      message: 'catalog.contract must be exactly { id, major, minor } with non-negative integers',
+    };
+  }
+  const supported = `${appStoreCatalogContract.id} ${appStoreCatalogContract.major}.${appStoreCatalogContract.minor}`;
+  if (identity.id !== appStoreCatalogContract.id
+    || identity.major !== appStoreCatalogContract.major
+    || identity.minor > appStoreCatalogContract.minor) {
+    return {
+      reason: 'contractUnsupported',
+      message: `catalog contract ${identity.id} ${identity.major}.${identity.minor} is not readable by this consumer (reads ${supported})`,
+    };
+  }
+  return null;
+};
+
+const validateHealthCheck = (valueArg: unknown, labelArg: string, errorsArg: string[]): void => {
+  const healthCheck = readDataProperties(valueArg);
+  if (healthCheck === null || !hasExactKeys(healthCheck, [], ['path', 'port', 'expectedStatus'])) {
+    errorsArg.push(`${labelArg} must be an object with only path, port and expectedStatus`);
+    return;
+  }
+  if (healthCheck.path !== undefined
+    && (!isLine(healthCheck.path, 2048) || !healthCheck.path.startsWith('/'))) {
+    errorsArg.push(`${labelArg}.path must be an absolute request path`);
+  }
+  if (healthCheck.port !== undefined && !isPort(healthCheck.port)) {
+    errorsArg.push(`${labelArg}.port must be a port number`);
+  }
+  if (healthCheck.expectedStatus !== undefined
+    && !(isNonNegativeSafeInteger(healthCheck.expectedStatus)
+      && healthCheck.expectedStatus >= 100 && healthCheck.expectedStatus <= 599)) {
+    errorsArg.push(`${labelArg}.expectedStatus must be an HTTP status code`);
+  }
+};
+
+/**
+ * The contract's judgement of one version config: the catalog member set, image pinning, the
+ * gates and upgrade flags, and every member rule `validateAppStoreVersionConfig` applies.
+ */
+const validateCatalogVersionConfig = (
+  configArg: Record<string, unknown>,
+  labelArg: string,
+  errorsArg: string[],
+): void => {
+  if (!hasExactKeys(configArg, ['image'], appStoreCatalogVersionConfigKeys)) {
+    const unknown = Object.keys(configArg)
+      .filter((keyArg) => !appStoreCatalogVersionConfigKeys.some((knownArg) => knownArg === keyArg));
+    errorsArg.push(unknown.length > 0
+      ? `${labelArg} has unknown field(s) ${unknown.sort().join(', ')}`
+      : `${labelArg}.image is required`);
+    return;
+  }
+  if (typeof configArg.image !== 'string' || getDigestFromPinnedImageReference(configArg.image) === undefined) {
+    errorsArg.push(`${labelArg}.image must be a digest-pinned image reference (name@sha256:...)`);
+  }
+  for (const key of ['minOneboxVersion', 'minCloudlyVersion'] as const) {
+    const value = configArg[key];
+    if (value !== undefined && (typeof value !== 'string' || !semverPattern.test(value))) {
+      errorsArg.push(`${labelArg}.${key} must be MAJOR.MINOR.PATCH`);
+    }
+  }
+  if (configArg.changelog !== undefined && !isText(configArg.changelog, 65536)) {
+    errorsArg.push(`${labelArg}.changelog must be bounded text`);
+  }
+  for (const key of ['breaking', 'requiresManualReview', 'migrationRequired', 'backupBeforeUpgrade'] as const) {
+    if (configArg[key] !== undefined && typeof configArg[key] !== 'boolean') {
+      errorsArg.push(`${labelArg}.${key} must be a boolean`);
+    }
+  }
+  if (configArg.healthCheck !== undefined) {
+    validateHealthCheck(configArg.healthCheck, `${labelArg}.healthCheck`, errorsArg);
+  }
+  errorsArg.push(...validateAppStoreVersionConfig(configArg, labelArg));
+};
+
+const validateAppInfo = (valueArg: unknown, labelArg: string, errorsArg: string[]): string | null => {
+  const info = readDataProperties(valueArg);
+  if (info === null
+    || !hasExactKeys(
+      info,
+      ['id', 'name', 'description', 'category'],
+      ['iconName', 'iconUrl', 'tags', 'maintainer', 'links'],
+    )) {
+    errorsArg.push(`${labelArg} must be exactly { id, name, description, category } plus optional iconName, iconUrl, tags, maintainer, links`);
+    return null;
+  }
+  const id = typeof info.id === 'string' && appIdPattern.test(info.id) ? info.id : null;
+  if (id === null) errorsArg.push(`${labelArg}.id must be a lower-case app id`);
+  if (!isLine(info.name, 128)) errorsArg.push(`${labelArg}.name must be a single line`);
+  if (!isText(info.description, 4096)) errorsArg.push(`${labelArg}.description must be bounded text`);
+  if (!isLine(info.category, 64)) errorsArg.push(`${labelArg}.category must be a single line`);
+  if (info.iconName !== undefined && !(typeof info.iconName === 'string' && iconNamePattern.test(info.iconName))) {
+    errorsArg.push(`${labelArg}.iconName must be a lower-case icon name`);
+  }
+  if (info.iconUrl !== undefined && !isHttpsUrl(info.iconUrl)) {
+    errorsArg.push(`${labelArg}.iconUrl must be an https URL`);
+  }
+  if (info.maintainer !== undefined && !isLine(info.maintainer, 128)) {
+    errorsArg.push(`${labelArg}.maintainer must be a single line`);
+  }
+  if (info.tags !== undefined) {
+    const tags = readDataElements(info.tags, appStoreCatalogContract.maximumTags);
+    if (tags === null
+      || tags.some((tagArg) => typeof tagArg !== 'string' || !tagPattern.test(tagArg))
+      || new Set(tags).size !== tags.length) {
+      errorsArg.push(`${labelArg}.tags must be a bounded list of unique lower-case tags`);
+    }
+  }
+  if (info.links !== undefined) {
+    const links = readDataProperties(info.links);
+    if (links === null
+      || Object.keys(links).length > appStoreCatalogContract.maximumLinks
+      || Object.entries(links).some(([labelKeyArg, urlArg]) => !linkLabelPattern.test(labelKeyArg) || !isHttpsUrl(urlArg))) {
+      errorsArg.push(`${labelArg}.links must map short labels to https URLs`);
+    }
+  }
+  return id;
+};
+
+const validateWithdrawal = (
+  valueArg: unknown,
+  labelArg: string,
+  publishedAtArg: string | null,
+  errorsArg: string[],
+): void => {
+  const withdrawal = readDataProperties(valueArg);
+  if (withdrawal === null || !hasExactKeys(withdrawal, ['at', 'reason'])) {
+    errorsArg.push(`${labelArg} must be exactly { at, reason }`);
+    return;
+  }
+  if (!isCanonicalTimestamp(withdrawal.at)) {
+    errorsArg.push(`${labelArg}.at must be a canonical UTC timestamp`);
+  } else if (publishedAtArg !== null && Date.parse(withdrawal.at) > Date.parse(publishedAtArg)) {
+    errorsArg.push(`${labelArg}.at must not be later than catalog.publishedAt`);
+  }
+  if (!isLine(withdrawal.reason, withdrawalReasonMaximumLength)) {
+    errorsArg.push(`${labelArg}.reason must be a single line`);
+  }
+};
+
+const validateCatalogApp = (
+  valueArg: unknown,
+  labelArg: string,
+  supportedFeatureIdsArg: ReadonlySet<string>,
+  publishedAtArg: string | null,
+  errorsArg: string[],
+): string | null => {
+  const app = readDataProperties(valueArg);
+  if (app === null || !hasExactKeys(app, ['info', 'latestVersion', 'versions'], ['upgradeStrategy'])) {
+    errorsArg.push(`${labelArg} must be exactly { info, latestVersion, versions } plus optional upgradeStrategy`);
+    return null;
+  }
+  const id = validateAppInfo(app.info, `${labelArg}.info`, errorsArg);
+  const strategy = app.upgradeStrategy ?? 'semver';
+  if (strategy !== 'semver' && strategy !== 'branch') {
+    errorsArg.push(`${labelArg}.upgradeStrategy must be semver or branch`);
+    return id;
+  }
+  const versionPattern = strategy === 'semver' ? semverPattern : versionTokenPattern;
+  const entries = readDataElements(app.versions, appStoreCatalogContract.maximumVersionsPerApp);
+  if (entries === null || entries.length === 0) {
+    errorsArg.push(`${labelArg}.versions must be a non-empty bounded array`);
+    return id;
+  }
+  const versions: string[] = [];
+  const withdrawnVersions = new Set<string>();
+  entries.forEach((entryArg, indexArg) => {
+    const versionLabel = `${labelArg}.versions[${indexArg}]`;
+    const entry = readDataProperties(entryArg);
+    if (entry === null || !hasExactKeys(entry, ['version', 'config', 'configDigest'], ['withdrawn'])) {
+      errorsArg.push(`${versionLabel} must be exactly { version, config, configDigest } plus optional withdrawn`);
+      return;
+    }
+    if (typeof entry.version !== 'string' || !versionPattern.test(entry.version)) {
+      errorsArg.push(`${versionLabel}.version must be ${strategy === 'semver' ? 'MAJOR.MINOR.PATCH' : 'a version token'}`);
+    } else if (versions.includes(entry.version)) {
+      errorsArg.push(`${versionLabel}.version '${entry.version}' is listed twice`);
+    } else {
+      versions.push(entry.version);
+      if (entry.withdrawn !== undefined) withdrawnVersions.add(entry.version);
+    }
+    if (entry.withdrawn !== undefined) {
+      validateWithdrawal(entry.withdrawn, `${versionLabel}.withdrawn`, publishedAtArg, errorsArg);
+    }
+    if (typeof entry.configDigest !== 'string' || !isSha256Digest(entry.configDigest)) {
+      errorsArg.push(`${versionLabel}.configDigest must be a canonical sha256 digest`);
+    }
+    const config = readDataProperties(entry.config);
+    if (config === null) {
+      errorsArg.push(`${versionLabel}.config must be an object`);
+      return;
+    }
+    if (config.requiresFeatures !== undefined && !isCanonicalFeatureIdList(config.requiresFeatures)) {
+      errorsArg.push(`${versionLabel}.config.requiresFeatures must be a strictly increasing list of feature ids`);
+      return;
+    }
+    const missing = isCanonicalFeatureIdList(config.requiresFeatures)
+      ? config.requiresFeatures.filter((featureIdArg) => !supportedFeatureIdsArg.has(featureIdArg))
+      : [];
+    // A version gated on a feature this consumer lacks may use members this consumer does not
+    // know. It stays listed, is never installed here, and its config is not interpreted.
+    if (missing.length === 0) validateCatalogVersionConfig(config, `${versionLabel}.config`, errorsArg);
+  });
+  // While any version is installable, latestVersion names one of those; a fully withdrawn app
+  // still names a listed version.
+  const availableVersions = versions.filter((versionArg) => !withdrawnVersions.has(versionArg));
+  const latestCandidates = availableVersions.length > 0 ? availableVersions : versions;
+  const latestVersion = typeof app.latestVersion === 'string' ? app.latestVersion : null;
+  if (latestVersion === null || !versions.includes(latestVersion)) {
+    errorsArg.push(`${labelArg}.latestVersion must name a listed version`);
+  } else if (!latestCandidates.includes(latestVersion)) {
+    errorsArg.push(`${labelArg}.latestVersion must not name a withdrawn version while another is not withdrawn`);
+  } else if (strategy === 'semver'
+    && latestCandidates.some((versionArg) => compareSemver(versionArg, latestVersion) > 0)) {
+    errorsArg.push(`${labelArg}.latestVersion must be the highest listed version that is not withdrawn`);
+  }
+  return id;
+};
+
+/**
+ * Every reason a value is not a catalog this consumer can read; empty when it is.
+ *
+ * Exact keys at every level: a member this contract does not define is refused, because a
+ * consumer that silently ignored it could not be trusted to honour it. The one exception is the
+ * config of a version whose `requiresFeatures` names a feature the consumer does not fulfil.
+ */
+export const validateAppStoreCatalog = (
+  catalogArg: unknown,
+  optionsArg: IAppStoreCatalogValidationOptions,
+): string[] => {
+  const catalog = readDataProperties(catalogArg);
+  if (catalog === null
+    || !hasExactKeys(catalog, ['contract', 'revision', 'publishedAt', 'sourceRevision', 'apps'])) {
+    return ['catalog must be exactly { contract, revision, publishedAt, sourceRevision, apps }'];
+  }
+  const errors: string[] = [];
+  const contractRefusal = judgeAppStoreCatalogContract(catalog);
+  if (contractRefusal !== null) errors.push(contractRefusal.message);
+  if (!isNonNegativeSafeInteger(catalog.revision) || catalog.revision < 1) {
+    errors.push('catalog.revision must be a positive integer');
+  }
+  if (!isCanonicalTimestamp(catalog.publishedAt)) {
+    errors.push('catalog.publishedAt must be a canonical UTC timestamp');
+  }
+  if (typeof catalog.sourceRevision !== 'string' || !sourceRevisionPattern.test(catalog.sourceRevision)) {
+    errors.push('catalog.sourceRevision must be a lower-case hex commit id');
+  }
+  const apps = readDataElements(catalog.apps, appStoreCatalogContract.maximumApps);
+  if (apps === null) {
+    errors.push('catalog.apps must be a bounded array');
+    return errors;
+  }
+  const supportedFeatureIds = new Set(optionsArg.supportedFeatureIds);
+  const publishedAt = isCanonicalTimestamp(catalog.publishedAt) ? catalog.publishedAt : null;
+  const ids: string[] = [];
+  apps.forEach((appArg, indexArg) => {
+    const id = validateCatalogApp(appArg, `catalog.apps[${indexArg}]`, supportedFeatureIds, publishedAt, errors);
+    if (id === null) return;
+    if (ids.includes(id)) errors.push(`catalog.apps[${indexArg}].info.id '${id}' is listed twice`);
+    else ids.push(id);
+  });
+  return errors;
+};
+
+/** The envelope's own members; the catalog inside is judged by `validateAppStoreCatalog`. */
+export const validateAppStoreCatalogEnvelopeShape = (envelopeArg: unknown): string[] => {
+  const envelope = readDataProperties(envelopeArg);
+  if (envelope === null || !hasExactKeys(envelope, ['catalog', 'catalogDigest', 'signatures'])) {
+    return ['envelope must be exactly { catalog, catalogDigest, signatures }'];
+  }
+  const errors: string[] = [];
+  if (readDataProperties(envelope.catalog) === null) errors.push('envelope.catalog must be an object');
+  if (typeof envelope.catalogDigest !== 'string' || !isSha256Digest(envelope.catalogDigest)) {
+    errors.push('envelope.catalogDigest must be a canonical sha256 digest');
+  }
+  const signatures = readDataElements(envelope.signatures, appStoreCatalogContract.maximumSignatures);
+  if (signatures === null || signatures.length === 0) {
+    errors.push(`envelope.signatures must hold 1 to ${appStoreCatalogContract.maximumSignatures} signatures`);
+    return errors;
+  }
+  const keyIds: string[] = [];
+  signatures.forEach((signatureArg, indexArg) => {
+    const signature = readDataProperties(signatureArg);
+    if (signature === null || !hasExactKeys(signature, ['keyId', 'signature'])
+      || typeof signature.keyId !== 'string' || !isSha256Digest(signature.keyId)
+      || typeof signature.signature !== 'string' || !signaturePattern.test(signature.signature)) {
+      errors.push(`envelope.signatures[${indexArg}] must be { keyId: sha256 digest, signature: 128 lower-case hex }`);
+      return;
+    }
+    if (keyIds.includes(signature.keyId)) errors.push(`envelope.signatures[${indexArg}].keyId is listed twice`);
+    else keyIds.push(signature.keyId);
+  });
+  return errors;
+};
+
+/** Every reason a value is not an envelope whose catalog this consumer can read. */
+export const validateAppStoreCatalogEnvelope = (
+  envelopeArg: unknown,
+  optionsArg: IAppStoreCatalogValidationOptions,
+): string[] => {
+  const shapeErrors = validateAppStoreCatalogEnvelopeShape(envelopeArg);
+  if (shapeErrors.length > 0) return shapeErrors;
+  const envelope = readDataProperties(envelopeArg);
+  return envelope === null
+    ? ['envelope must be an object']
+    : validateAppStoreCatalog(envelope.catalog, optionsArg);
+};
+
+/** Narrows a value `validateAppStoreCatalogEnvelope` accepts. */
+export const isAppStoreCatalogEnvelope = (
+  envelopeArg: unknown,
+  optionsArg: IAppStoreCatalogValidationOptions,
+): envelopeArg is IAppStoreCatalogEnvelope => validateAppStoreCatalogEnvelope(envelopeArg, optionsArg).length === 0;
+
+const failDigestInput = (reasonArg: string): never => {
+  throw new Error(`App Store catalog digest input rejected: ${reasonArg}`);
+};
+
+/**
+ * SHA-256 over the strict canonical JSON of a domain-separated value: object keys in UTF-16 code
+ * unit order, no whitespace, safe integers only. A value canonical JSON cannot represent — a
+ * fractional number, an accessor, a cycle — throws.
+ */
+const computeDomainDigest = async (valueArg: Record<string, unknown>): Promise<TSha256Digest> => {
+  const hex = await createCanonicalJsonSha256Hex(
+    canonicalizeStrictJson(valueArg, failDigestInput),
+    failDigestInput,
+  );
+  return `sha256:${hex}`;
+};
+
+/** The digest a catalog version entry carries as `configDigest`. */
+export const computeAppStoreCatalogConfigDigest = (configArg: unknown): Promise<TSha256Digest> =>
+  computeDomainDigest({ domain: appStoreCatalogContract.configDigestDomain, config: configArg });
+
+/** The digest an envelope carries as `catalogDigest`. */
+export const computeAppStoreCatalogDigest = (catalogArg: unknown): Promise<TSha256Digest> =>
+  computeDomainDigest({ domain: appStoreCatalogContract.catalogDigestDomain, catalog: catalogArg });
+
+/** The key id of a raw Ed25519 public key (32 bytes, lower-case hex). */
+export const computeAppStoreCatalogSigningKeyId = async (publicKeyArg: string): Promise<TSha256Digest> => {
+  if (!publicKeyPattern.test(publicKeyArg)) {
+    throw new Error('App Store catalog signing key must be 32 bytes of lower-case hex');
+  }
+  return computeDomainDigest({ domain: appStoreCatalogContract.signingKeyIdDomain, publicKey: publicKeyArg });
+};
+
+/** The exact bytes a catalog signature covers. */
+export const createAppStoreCatalogSignaturePayload = (catalogDigestArg: TSha256Digest): Uint8Array => {
+  if (!isSha256Digest(catalogDigestArg)) {
+    throw new Error('App Store catalog digest must be a canonical sha256 digest');
+  }
+  return new TextEncoder().encode(canonicalizeStrictJson(
+    { domain: appStoreCatalogContract.signatureDomain, catalogDigest: catalogDigestArg },
+    failDigestInput,
+  ));
+};
+
+/**
+ * The first version entry whose `configDigest` does not match its config, or `null`.
+ *
+ * Judge the catalog with `validateAppStoreCatalog` first; an entry it would refuse is skipped.
+ */
+export const findAppStoreCatalogConfigDigestMismatch = async (
+  catalogArg: IAppStoreCatalog,
+): Promise<string | null> => {
+  for (const app of catalogArg.apps) {
+    for (const version of app.versions) {
+      if (await computeAppStoreCatalogConfigDigest(version.config) !== version.configDigest) {
+        return `${app.info.id}@${version.version} configDigest does not match its config`;
+      }
+    }
+  }
+  return null;
+};
+
+/** 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[] };
+
+/**
+ * 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.
+ */
+export const judgeAppStoreCatalogInstallTarget = (
+  versionArg: IAppStoreCatalogVersion,
+  supportedFeatureIdsArg: Iterable<string>,
+): TAppStoreCatalogInstallTargetRefusal | null => {
+  if (versionArg.withdrawn !== undefined) return { reason: 'versionWithdrawn', withdrawal: versionArg.withdrawn };
+  const missingFeatureIds = getAppStoreCatalogMissingFeatureIds(versionArg.config, supportedFeatureIdsArg);
+  return missingFeatureIds.length > 0 ? { reason: 'featuresUnsupported', missingFeatureIds } : null;
+};
+
+export type TAppStoreCatalogSuccession =
+  | { outcome: 'activate' }
+  | { outcome: 'unchanged' }
+  | { outcome: 'refused'; refusal: IAppStoreCatalogRefusal };
+
+const sameWithdrawal = (
+  leftArg: IAppStoreCatalogWithdrawal | undefined,
+  rightArg: IAppStoreCatalogWithdrawal | undefined,
+): boolean => leftArg?.at === rightArg?.at && leftArg?.reason === rightArg?.reason;
+
+/**
+ * Whether a verified candidate may replace the active verified catalog.
+ *
+ * The same digest is `unchanged`. Otherwise the revision must be greater, and the candidate must
+ * keep the active catalog's full history: every `app@version` it lists stays listed
+ * (`publishedVersionRemoved`) with its `configDigest` (`publishedVersionMutated`), and every
+ * withdrawal stays exactly as published (`publishedWithdrawalChanged`). A candidate may add apps
+ * and versions and withdraw versions; it cannot remove, rewrite or reinstate one.
+ */
+export const judgeAppStoreCatalogSuccession = (
+  activeArg: IAppStoreCatalogEnvelope | null,
+  candidateArg: IAppStoreCatalogEnvelope,
+): TAppStoreCatalogSuccession => {
+  if (activeArg === null) return { outcome: 'activate' };
+  if (activeArg.catalogDigest === candidateArg.catalogDigest) return { outcome: 'unchanged' };
+  const refuse = (reasonArg: TAppStoreCatalogRefusalReason, messageArg: string): TAppStoreCatalogSuccession =>
+    ({ outcome: 'refused', refusal: { reason: reasonArg, message: messageArg } });
+  if (candidateArg.catalog.revision <= activeArg.catalog.revision) {
+    return refuse(
+      'revisionRegressed',
+      `catalog revision ${candidateArg.catalog.revision} is not greater than active revision ${activeArg.catalog.revision}`,
+    );
+  }
+  const candidateVersions = new Map<string, IAppStoreCatalogVersion>();
+  for (const app of candidateArg.catalog.apps) {
+    for (const version of app.versions) candidateVersions.set(`${app.info.id}@${version.version}`, version);
+  }
+  for (const app of activeArg.catalog.apps) {
+    for (const published of app.versions) {
+      const key = `${app.info.id}@${published.version}`;
+      const candidate = candidateVersions.get(key);
+      if (candidate === undefined) {
+        return refuse('publishedVersionRemoved', `${key} was published and is no longer listed`);
+      }
+      if (candidate.configDigest !== published.configDigest) {
+        return refuse(
+          'publishedVersionMutated',
+          `${key} was published with ${published.configDigest} and now carries ${candidate.configDigest}`,
+        );
+      }
+      if (published.withdrawn !== undefined && !sameWithdrawal(published.withdrawn, candidate.withdrawn)) {
+        return refuse(
+          'publishedWithdrawalChanged',
+          candidate.withdrawn === undefined
+            ? `${key} was withdrawn and a withdrawal is final`
+            : `${key} was withdrawn at ${published.withdrawn.at} and its withdrawal record changed`,
+        );
+      }
+    }
+  }
+  return { outcome: 'activate' };
+};