@serve.zone/interfaces 32.48.0 → 32.49.0

package/changelog.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2026-10-06 - 32.49.0
+
+### Features
+
+- The App Store has a runtime catalog contract, so App Store updates that keep the contract no longer
+  need Onebox or Cloudly releases. `appstore.appStoreCatalogContract` (`serve.zone/appstore-catalog`,
+  major 1, minor 0, sha256, ed25519) defines `IAppStoreCatalog`: every app with every published
+  version, each version carrying its `config` and `configDigest`, under a strictly increasing
+  `revision`, `publishedAt` and `sourceRevision`. A publisher ships it as an
+  `IAppStoreCatalogEnvelope` (`catalogDigest` plus Ed25519 `signatures` by key id).
+  `appstore.validateAppStoreCatalog` judges a catalog with exact keys at every level, digest-pinned
+  images, semver or `branch` versions with a listed `latestVersion` that is not withdrawn (under
+  semver the highest such one), unique app ids and versions, and judges every supported version
+  config in full through
+  `appstore.validateAppStoreVersionConfig`: the member rules the `@serve.zone/appstore` resolver
+  applied before an install, now owned here (`validateAppStoreVersionPortModel` for `port`,
+  `targetPorts`, `domains` and `publicPortMappings`; `validateAppStoreVersionStorage` for the exact
+  member set, `platformRequirements`, storage classes, requests, legacy `volumes`, storage feature ids
+  and destination collisions; `validateAppStorePublishedPorts`; `appStoreVersionConfigKeys`). Each
+  storage request is judged by the same storage contract as `platform.normalizeStorageRequest`, so
+  its members, capacity, protection, delivery and mount path are refused with that contract's
+  messages and bounds; the version config adds the rules between requests (declared classes and what
+  they back, unique ids and destinations, reserved legacy names, storage feature ids), lowercase
+  request ids and one file directly below `/run/secrets` per file delivery. Port entries are read as
+  exactly their types, so a string port or an unknown member is refused rather than coerced or
+  ignored. `requiresFeatures` now gates single versions: a version naming a feature the consumer
+  does not fulfil stays listed, is not installable there, and its config is not interpreted, so the
+  rest of the catalog still loads. A published version is never removed: a publisher withdraws it
+  with `withdrawn: { at, reason }` (`IAppStoreCatalogWithdrawal`), which keeps the entry, its config
+  and its digest, and `judgeAppStoreCatalogInstallTarget` refuses a withdrawn or feature-gated
+  version as an install or upgrade target. `judgeAppStoreCatalogContract` refuses another id, another
+  major or a newer minor as `contractUnsupported`; `judgeAppStoreCatalogSuccession` refuses a revision
+  that does not increase (`revisionRegressed`), a published `app@version` that is no longer listed
+  (`publishedVersionRemoved`) or whose config digest changed (`publishedVersionMutated`), and a
+  withdrawal that is revoked or rewritten (`publishedWithdrawalChanged`).
+  `computeAppStoreCatalogConfigDigest`, `computeAppStoreCatalogDigest`,
+  `computeAppStoreCatalogSigningKeyId` and `createAppStoreCatalogSignaturePayload` define the exact
+  bytes (browser-safe, Web Crypto). The Node-only `./runtime` export adds
+  `createAppStoreCatalogSigningKey`, `signAppStoreCatalog` and `verifyAppStoreCatalogEnvelope`, which
+  checks shape, digest and a trusted signature before it reads the contract and schema, and answers
+  `{ accepted, envelope, keyId }` or a `TAppStoreCatalogRefusalReason`. `TAppStoreCatalogStatus` is
+  discriminated by `availability`: `ready` always carries the `active` catalog (a restored
+  last-known-good one counts), `unavailable` always carries a `reason` and no active catalog; both
+  state the last attempt, the next retry and the last refusal.
+  `requests.appstore.getAppStoreCatalogStatus` and `refreshAppStoreCatalog` answer it, and
+  `getAppStoreTemplates` may answer it as `catalogStatus`.
+
 ## 2026-10-05 - 32.48.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '32.48.0',
+    version: '32.49.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/appstore/catalog.d.ts

@@ -0,0 +1,300 @@
+/**
+ * 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 type { TCompleteKeyList } from '../private/keylist.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 declare const appStoreCatalogContract: Readonly<{
+    readonly id: "serve.zone/appstore-catalog";
+    readonly major: 1;
+    readonly minor: 0;
+    readonly digestAlgorithm: "sha256";
+    readonly signatureAlgorithm: "ed25519";
+    readonly configDigestDomain: "serve.zone/appstore-catalog/version-config";
+    readonly catalogDigestDomain: "serve.zone/appstore-catalog/catalog";
+    readonly signatureDomain: "serve.zone/appstore-catalog/signature";
+    readonly signingKeyIdDomain: "serve.zone/appstore-catalog/signing-key";
+    readonly maximumApps: 1024;
+    readonly maximumVersionsPerApp: 1024;
+    readonly maximumSignatures: 8;
+    readonly maximumTags: 32;
+    readonly maximumLinks: 32;
+    readonly maximumConfigListEntries: 256;
+    readonly maximumRequiredFeatures: 64;
+}>;
+/** 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'>;
+declare const versionConfigKeyList: readonly ["image", "port", "containerArgs", "targetPorts", "domains", "publicPortMappings", "envVars", "volumes", "storageClasses", "storageRequests", "publishedPorts", "platformRequirements", "platformOidc", "minOneboxVersion", "minCloudlyVersion", "changelog", "breaking", "requiresManualReview", "migrationRequired", "backupBeforeUpgrade", "requiresFeatures", "healthCheck"];
+/** Every member a catalog version config may carry; any other member is refused. */
+export declare const appStoreCatalogVersionConfigKeys: TCompleteKeyList<TAppStoreCatalogVersionConfig, typeof 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>;
+}
+/**
+ * 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 declare const getAppStoreCatalogMissingFeatureIds: (configArg: unknown, supportedFeatureIdsArg: Iterable<string>) => string[];
+/**
+ * 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 declare const judgeAppStoreCatalogContract: (catalogArg: unknown) => IAppStoreCatalogRefusal | null;
+/**
+ * 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 declare const validateAppStoreCatalog: (catalogArg: unknown, optionsArg: IAppStoreCatalogValidationOptions) => string[];
+/** The envelope's own members; the catalog inside is judged by `validateAppStoreCatalog`. */
+export declare const validateAppStoreCatalogEnvelopeShape: (envelopeArg: unknown) => string[];
+/** Every reason a value is not an envelope whose catalog this consumer can read. */
+export declare const validateAppStoreCatalogEnvelope: (envelopeArg: unknown, optionsArg: IAppStoreCatalogValidationOptions) => string[];
+/** Narrows a value `validateAppStoreCatalogEnvelope` accepts. */
+export declare const isAppStoreCatalogEnvelope: (envelopeArg: unknown, optionsArg: IAppStoreCatalogValidationOptions) => envelopeArg is IAppStoreCatalogEnvelope;
+/** The digest a catalog version entry carries as `configDigest`. */
+export declare const computeAppStoreCatalogConfigDigest: (configArg: unknown) => Promise<TSha256Digest>;
+/** The digest an envelope carries as `catalogDigest`. */
+export declare const computeAppStoreCatalogDigest: (catalogArg: unknown) => Promise<TSha256Digest>;
+/** The key id of a raw Ed25519 public key (32 bytes, lower-case hex). */
+export declare const computeAppStoreCatalogSigningKeyId: (publicKeyArg: string) => Promise<TSha256Digest>;
+/** The exact bytes a catalog signature covers. */
+export declare const createAppStoreCatalogSignaturePayload: (catalogDigestArg: TSha256Digest) => Uint8Array;
+/**
+ * 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 declare const findAppStoreCatalogConfigDigestMismatch: (catalogArg: IAppStoreCatalog) => Promise<string | 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 declare const judgeAppStoreCatalogInstallTarget: (versionArg: IAppStoreCatalogVersion, supportedFeatureIdsArg: Iterable<string>) => TAppStoreCatalogInstallTargetRefusal | null;
+export type TAppStoreCatalogSuccession = {
+    outcome: 'activate';
+} | {
+    outcome: 'unchanged';
+} | {
+    outcome: 'refused';
+    refusal: IAppStoreCatalogRefusal;
+};
+/**
+ * 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 declare const judgeAppStoreCatalogSuccession: (activeArg: IAppStoreCatalogEnvelope | null, candidateArg: IAppStoreCatalogEnvelope) => TAppStoreCatalogSuccession;
+export {};