@serve.zone/interfaces 32.48.0 → 32.50.0

package/ts/data/index.ts

@@ -36,6 +36,7 @@ export * from './nodeenrollment.js';
 export * from './noderuntimebinding.js';
 export * from './noderetirement.js';
 export * from './networkaddressplan.js';
+export * from './networkapplication.js';
 export * from './networkauthority.js';
 export * from './networkcredential.js';
 export * from './networkdelivery.js';

package/ts/data/networkapplication.ts

@@ -0,0 +1,188 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { IRuntimeNetworkNodeScope } from './networkprojection.js';
+import { computeRuntimeNetworkProjectionDigest, snapshotRuntimeNetworkNodeScope,
+  snapshotRuntimeNetworkProjection } from './networkprojection.js';
+import type { IRuntimeSessionBinding } from './runtimesession.js';
+import { snapshotRuntimeSessionBinding } from './runtimesession.js';
+import { captureNetwork, failNetwork, networkDigest, networkEqual, networkHash, networkId, networkRecord,
+  networkReference, networkReferenceOf, networkRevision, networkSafe, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * A node's durable statement that its packet authority is bounded by one admitted projection.
+ *
+ * Every packet table the node holds was composed from `projection`, or the node holds none: the
+ * flows its kernel admits are a subset of that projection's grants. Only the node's joined native
+ * packet owner can supply it — the journaled application of the projection's policies on every
+ * role, or the release of every table — never an admission ACK, a single table inspection or a
+ * caller-selected flag. A crash, a reboot or a restored guard only removes authority, so a receipt
+ * never becomes false; applying a successor projection supersedes it.
+ *
+ * `nativeJournal` names the node-private joined packet journal that applied the projection, or is
+ * null when the node holds no packet table at all. The receipts of one node form one monotonic
+ * chain; a receipt never names an older projection than its predecessor. These portable values
+ * neither inspect a kernel nor authenticate their producer: the receiver binds the report to the
+ * current authenticated session or its own reporter history.
+ */
+export interface IRuntimeNetworkProjectionApplicationReceipt extends IRuntimeNetworkNodeScope {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  projection: IRuntimeAuthorityReference;
+  reporterSessionId: string;
+  bootId: string;
+  nativeJournal: IRuntimeAuthorityReference | null;
+  digest: TSha256Digest;
+}
+
+export interface IReportRuntimeNetworkProjectionApplicationRequest {
+  session: IRuntimeSessionBinding;
+  receipt: IRuntimeNetworkProjectionApplicationReceipt;
+}
+export interface IReportRuntimeNetworkProjectionApplicationResponse {
+  status: 'accepted' | 'replay';
+  receipt: IRuntimeAuthorityReference;
+  authorityUse: 'current' | 'historical';
+}
+
+export const runtimeNetworkProjectionApplicationContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-network-projection-application-receipt',
+  claim: 'packet-authority-within-the-grants-of-the-named-projection',
+  receiptSource: 'joined-native-packet-journal-or-no-packet-table',
+  appliedPrevious: 'only-a-receipt-naming-the-exact-previous-projection',
+  olderProjection: 'advances-the-chain-never-applied-previous',
+  acknowledgement: 'an-admission-ack-is-never-an-application-receipt',
+  authentication: 'current-authenticated-session-or-receiver-reporter-history',
+} as const);
+
+const bootIdPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const scopeOf = (value: IRuntimeNetworkNodeScope): IRuntimeNetworkNodeScope =>
+  ({ controller: value.controller, nodeId: value.nodeId, runtimeNamespace: value.runtimeNamespace });
+const bootId = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && bootIdPattern.test(value) && value !== '00000000-0000-0000-0000-000000000000');
+  return value;
+};
+
+/** Exact-key structural snapshot; digest and chain rules are `admitRuntimeNetworkProjectionApplicationReceipt`'s. */
+export const snapshotRuntimeNetworkProjectionApplicationReceipt = (
+  value: unknown,
+): IRuntimeNetworkProjectionApplicationReceipt => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'generation', 'previous', 'controller', 'nodeId',
+    'runtimeNamespace', 'projection', 'reporterSessionId', 'bootId', 'nativeJournal', 'digest']);
+  const scope = snapshotRuntimeNetworkNodeScope({ controller: item.controller, nodeId: item.nodeId,
+    runtimeNamespace: item.runtimeNamespace });
+  return { ...networkRevision(item), ...scope, projection: networkReference(item.projection),
+    reporterSessionId: networkId(item.reporterSessionId), bootId: bootId(item.bootId),
+    nativeJournal: item.nativeJournal === null ? null : networkReference(item.nativeJournal),
+    digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkProjectionApplicationReceiptDigest = (
+  value: IRuntimeNetworkProjectionApplicationReceipt,
+): Promise<TSha256Digest> => networkHash(runtimeNetworkProjectionApplicationContract.digestDomain,
+  snapshotRuntimeNetworkProjectionApplicationReceipt(value));
+
+/**
+ * Pure chain binding of one reported receipt. `previousReceiptValue` is the receiver's current
+ * receipt for the node, or null while it holds none; `headValue` is the receiver's current
+ * projection for the node. The owner must authenticate the reporter and fence its writes.
+ *
+ * The receipt names the head's projection chain at a generation the head has reached: the head
+ * itself, exactly, or an older generation. An older one is a receipt minted before the node
+ * admitted the head; it advances the chain and is never usable as `appliedPrevious`.
+ */
+export const admitRuntimeNetworkProjectionApplicationReceipt = async (
+  value: unknown, previousReceiptValue: unknown | null, trustedScopeValue: unknown, headValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; receipt: IRuntimeNetworkProjectionApplicationReceipt }> => {
+  try {
+    const receipt = snapshotRuntimeNetworkProjectionApplicationReceipt(value);
+    const previous = previousReceiptValue === null ? null : snapshotRuntimeNetworkProjectionApplicationReceipt(previousReceiptValue);
+    const scope = snapshotRuntimeNetworkNodeScope(captureNetwork(trustedScopeValue));
+    const head = snapshotRuntimeNetworkProjection(headValue);
+    requireNetwork(networkEqual(scopeOf(receipt), scope) && networkEqual(scopeOf(head), scope));
+    requireNetwork(receipt.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(receipt)
+      && head.digest === await computeRuntimeNetworkProjectionDigest(head));
+    requireNetwork(receipt.projection.id === head.id && receipt.projection.generation <= head.generation);
+    if (receipt.projection.generation === head.generation) requireNetwork(networkEqual(receipt.projection, networkReferenceOf(head)));
+    if (previous === null) requireNetwork(receipt.generation === 1 && receipt.previous === null);
+    else {
+      requireNetwork(networkEqual(scopeOf(previous), scope)
+        && previous.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(previous));
+      if (networkEqual(receipt, previous)) return { status: 'replay', receipt };
+      requireNetwork(receipt.id === previous.id && receipt.generation === previous.generation + 1
+        && networkEqual(receipt.previous, networkReferenceOf(previous))
+        && receipt.projection.id === previous.projection.id
+        && receipt.projection.generation >= previous.projection.generation);
+      if (receipt.projection.generation === previous.projection.generation) {
+        requireNetwork(networkEqual(receipt.projection, previous.projection));
+      }
+    }
+    return { status: 'accepted', receipt };
+  } catch { return failNetwork(); }
+};
+
+/**
+ * The `appliedPrevious` argument of `admitRuntimeNetworkProjection` for the successor of
+ * `previousProjectionValue`: the receipt's projection when it is exactly that projection, else
+ * null. `receiptValue` must be the receiver's own admitted receipt for the node (a node passes its
+ * own durable receipt, a controller the latest receipt it admitted), never an ACK field.
+ */
+export const selectRuntimeNetworkProjectionAppliedPrevious = async (
+  receiptValue: unknown | null, previousProjectionValue: unknown,
+): Promise<IRuntimeAuthorityReference | null> => {
+  try {
+    // Snapshot both caller-owned inputs before the first asynchronous operation.
+    const previous = snapshotRuntimeNetworkProjection(previousProjectionValue);
+    const receipt = receiptValue === null ? null : snapshotRuntimeNetworkProjectionApplicationReceipt(receiptValue);
+    requireNetwork(previous.digest === await computeRuntimeNetworkProjectionDigest(previous));
+    if (receipt === null) return null;
+    requireNetwork(networkEqual(scopeOf(receipt), scopeOf(previous))
+      && receipt.digest === await computeRuntimeNetworkProjectionApplicationReceiptDigest(receipt));
+    return networkEqual(receipt.projection, networkReferenceOf(previous)) ? networkReferenceOf(receipt.projection) : null;
+  } catch { return failNetwork(); }
+};
+
+export const snapshotReportRuntimeNetworkProjectionApplicationRequest = (
+  value: unknown,
+): IReportRuntimeNetworkProjectionApplicationRequest => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['session', 'receipt']);
+  return { session: snapshotRuntimeSessionBinding(item.session),
+    receipt: snapshotRuntimeNetworkProjectionApplicationReceipt(item.receipt) };
+});
+
+/**
+ * Both trusted bindings come from the receiver's fenced physical-session/history owner: the
+ * current session, and the session history entry that names the receipt's reporter. A receipt
+ * minted under an earlier session of the same node still drains from its outbox as `historical`.
+ */
+export const bindReportRuntimeNetworkProjectionApplicationRequest = (
+  value: unknown, trustedCurrentSessionValue: unknown, trustedReporterSessionValue: unknown,
+): { request: IReportRuntimeNetworkProjectionApplicationRequest; authorityUse: 'current' | 'historical' } => networkSafe(() => {
+  const request = snapshotReportRuntimeNetworkProjectionApplicationRequest(value);
+  const current = snapshotRuntimeSessionBinding(captureNetwork(trustedCurrentSessionValue));
+  const reporter = snapshotRuntimeSessionBinding(captureNetwork(trustedReporterSessionValue));
+  requireNetwork(networkEqual(request.session, current) && networkEqual(scopeOf(request.receipt), scopeOf(current))
+    && networkEqual(scopeOf(reporter), scopeOf(current)) && reporter.reporterSessionId === request.receipt.reporterSessionId);
+  const authorityUse = reporter.reporterSessionId === current.reporterSessionId ? 'current' : 'historical';
+  requireNetwork(authorityUse === 'current' ? networkEqual(reporter, current)
+    : reporter.sessionEpoch < current.sessionEpoch && reporter.credentialGeneration <= current.credentialGeneration);
+  return { request, authorityUse };
+});
+
+export const snapshotReportRuntimeNetworkProjectionApplicationResponse = (
+  value: unknown,
+): IReportRuntimeNetworkProjectionApplicationResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['status', 'receipt', 'authorityUse']);
+  requireNetwork((item.status === 'accepted' || item.status === 'replay')
+    && (item.authorityUse === 'current' || item.authorityUse === 'historical'));
+  return { status: item.status, receipt: networkReference(item.receipt), authorityUse: item.authorityUse };
+});
+
+/** Compare the response with the exact SENT receipt, never with a response-derived value. */
+export const bindReportRuntimeNetworkProjectionApplicationResponse = (
+  value: unknown, sentReceiptValue: unknown,
+): IReportRuntimeNetworkProjectionApplicationResponse => networkSafe(() => {
+  const response = snapshotReportRuntimeNetworkProjectionApplicationResponse(value);
+  requireNetwork(networkEqual(response.receipt, networkReference(captureNetwork(sentReceiptValue))));
+  return response;
+});

package/ts/data/networkprojection.ts

@@ -788,9 +788,11 @@ export const bindRuntimeNetworkWorkloadLeaseToAssignment = async (leaseValue: un
 };
 
 /**
- * Pure revision decision. appliedPrevious must be the receiver's exact durable,
- * joined application receipt, never an incoming ACK field. All prior accepted
- * material/apply journals survive until effects and DNS/allocation quarantine end.
+ * Pure revision decision. appliedPrevious must come from the receiver's exact durable,
+ * joined application receipt (`IRuntimeNetworkProjectionApplicationReceipt`, selected by
+ * `selectRuntimeNetworkProjectionAppliedPrevious`), never from an incoming ACK field. Only a
+ * receipt naming exactly `previousValue` releases its carried withdrawals and tombstones. All
+ * prior accepted material/apply journals survive until effects and DNS/allocation quarantine end.
  */
 export const admitRuntimeNetworkProjection = async (
   value: unknown, previousValue: unknown | null, trustedScopeValue: unknown, appliedPreviousValue: unknown | null,

package/ts/private/keylist.ts

@@ -0,0 +1,6 @@
+/**
+ * A key list that names every key of a record type, so a member added to the type cannot be
+ * forgotten by a validator built on the list: an incomplete list does not type-check.
+ */
+export type TCompleteKeyList<TRecord, TKeys extends readonly (keyof TRecord)[]> =
+  Exclude<keyof TRecord, TKeys[number]> extends never ? TKeys : never;

package/ts/requests/appstore.ts

@@ -4,6 +4,7 @@ import type { IService } from '../data/service.js';
 import type {
   IAppStoreApp,
   IAppStoreAppMeta,
+  TAppStoreCatalogStatus,
   IAppStoreInstallRequest,
   IAppStoreVersionConfig,
   IUpgradeableAppStoreService,
@@ -71,6 +72,43 @@ export interface IReq_Any_GetAppStoreTemplates extends plugins.typedrequestInter
   };
   response: {
     apps: IAppStoreApp[];
+    /**
+     * The catalog state behind `apps`. Optional while consumers still serve a bundled catalog;
+     * a consumer that loads the catalog at runtime always answers it.
+     */
+    catalogStatus?: TAppStoreCatalogStatus;
+  };
+}
+
+/** The App Store catalog's state: availability, the active catalog, the last attempt and refusal. */
+export interface IReq_Any_GetAppStoreCatalogStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_GetAppStoreCatalogStatus
+> {
+  method: 'getAppStoreCatalogStatus';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    status: TAppStoreCatalogStatus;
+  };
+}
+
+/**
+ * Runs one bounded catalog load attempt now, outside the refresh schedule, and answers the state
+ * after it. The attempt's outcome is `status.lastAttempt`; a refused or failed attempt keeps the
+ * active catalog in place and is not a request error.
+ */
+export interface IReq_Any_RefreshAppStoreCatalog extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_RefreshAppStoreCatalog
+> {
+  method: 'refreshAppStoreCatalog';
+  request: {
+    identity: IIdentity;
+  };
+  response: {
+    status: TAppStoreCatalogStatus;
   };
 }
 

package/ts/requests/runtimesession.ts

@@ -4,6 +4,7 @@ import type * as binding from '../data/noderuntimebinding.js';
 import type * as terminal from '../data/runtimeterminalreceipt.js';
 import type * as network from '../data/networkdelivery.js';
 import type * as protection from '../data/networkprotection.js';
+import type * as application from '../data/networkapplication.js';
 import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
@@ -32,6 +33,19 @@ export interface IReq_Pallet_Controller_ReportRuntimeNetworkProtection extends p
   response: protection.IReportRuntimeNetworkProtectionResponse;
 }
 
+/**
+ * Current authenticated peer reports its durable joined application receipt: the projection that
+ * bounds its packet authority. The controller passes it as `appliedPrevious` only while it names
+ * the exact head; an admission ACK never stands in for it.
+ */
+export interface IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeNetworkProjectionApplication
+> {
+  method: 'reportRuntimeNetworkProjectionApplication';
+  request: application.IReportRuntimeNetworkProjectionApplicationRequest;
+  response: application.IReportRuntimeNetworkProjectionApplicationResponse;
+}
+
 /**
  * Current authenticated Pallet session only. Cloudly reads the current pallet runtime and exact
  * owner records, then grants one held prepared handoff; serialized session content is no proof.

package/ts/runtime.appstorecatalog.ts

@@ -0,0 +1,195 @@
+/**
+ * Ed25519 signing and verification of App Store catalog envelopes (Node-only).
+ *
+ * A consumer authenticates before it interprets: the envelope's digest and signature are checked
+ * before the catalog's contract and schema are read.
+ */
+import * as plugins from './plugins.runtime.js';
+import type { TSha256Digest } from './data/immutableimage.js';
+import { isSha256Digest } from './data/immutableimage.js';
+import { canonicalizeStrictJson } from './private/canonicaljson.js';
+import { readDataElements, readDataProperties } from './private/dataproperties.js';
+import {
+  appStoreCatalogContract,
+  computeAppStoreCatalogDigest,
+  computeAppStoreCatalogSigningKeyId,
+  createAppStoreCatalogSignaturePayload,
+  findAppStoreCatalogConfigDigestMismatch,
+  isAppStoreCatalogEnvelope,
+  judgeAppStoreCatalogContract,
+  validateAppStoreCatalog,
+  validateAppStoreCatalogEnvelope,
+  validateAppStoreCatalogEnvelopeShape,
+} from './appstore/catalog.js';
+import type {
+  IAppStoreCatalog,
+  IAppStoreCatalogEnvelope,
+  IAppStoreCatalogRefusal,
+  IAppStoreCatalogSignature,
+  IAppStoreCatalogTrustedKey,
+  IAppStoreCatalogValidationOptions,
+  TAppStoreCatalogRefusalReason,
+} from './appstore/catalog.js';
+
+/** A catalog signing key. The private half is process-local; keep it in the publisher's secret store. */
+export interface IAppStoreCatalogSigningKey {
+  keyId: TSha256Digest;
+  /** Raw 32-byte Ed25519 public key, lower-case hex. */
+  publicKey: string;
+  privateKey: plugins.crypto.KeyObject;
+}
+
+export interface IAppStoreCatalogVerificationOptions extends IAppStoreCatalogValidationOptions {
+  /** The keys this consumer trusts, shipped with its release. */
+  trustedKeys: readonly IAppStoreCatalogTrustedKey[];
+}
+
+export type TAppStoreCatalogVerification =
+  | { accepted: true; envelope: IAppStoreCatalogEnvelope; keyId: TSha256Digest }
+  | { accepted: false; refusal: IAppStoreCatalogRefusal };
+
+const rawPublicKeyOf = (keyArg: plugins.crypto.KeyObject): string => {
+  const jwk = keyArg.export({ format: 'jwk' });
+  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+    throw new Error('App Store catalog signing key must be an Ed25519 key');
+  }
+  return Buffer.from(jwk.x, 'base64url').toString('hex');
+};
+
+const publicKeyObjectOf = (publicKeyArg: string): plugins.crypto.KeyObject =>
+  plugins.crypto.createPublicKey({
+    format: 'jwk',
+    key: { kty: 'OKP', crv: 'Ed25519', x: Buffer.from(publicKeyArg, 'hex').toString('base64url') },
+  });
+
+/** 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 };
+};
+
+/**
+ * Signs only a catalog this contract accepts, whose every `configDigest` matches its config.
+ *
+ * `optionsArg.supportedFeatureIds` should name every feature id the catalog uses, so the
+ * publisher judges every version config in full.
+ */
+export const signAppStoreCatalog = async (
+  catalogArg: IAppStoreCatalog,
+  signingKeysArg: readonly IAppStoreCatalogSigningKey[],
+  optionsArg: IAppStoreCatalogValidationOptions,
+): Promise<IAppStoreCatalogEnvelope> => {
+  const errors = validateAppStoreCatalog(catalogArg, optionsArg);
+  if (errors.length > 0) {
+    throw new Error(`App Store catalog refused for signing: ${errors.join('; ')}`);
+  }
+  const mismatch = await findAppStoreCatalogConfigDigestMismatch(catalogArg);
+  if (mismatch !== null) throw new Error(`App Store catalog refused for signing: ${mismatch}`);
+  if (signingKeysArg.length === 0) throw new Error('App Store catalog needs at least one signing key');
+  const catalogDigest = await computeAppStoreCatalogDigest(catalogArg);
+  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) {
+      throw new Error(`App Store catalog signing key ${key.keyId} does not match its private key`);
+    }
+    signatures.push({
+      keyId: key.keyId,
+      signature: plugins.crypto.sign(null, payload, privateKey).toString('hex'),
+    });
+  }
+  return { catalog: structuredClone(catalogArg), catalogDigest, signatures };
+};
+
+const refuse = (reasonArg: TAppStoreCatalogRefusalReason, messageArg: string): TAppStoreCatalogVerification =>
+  ({ accepted: false, refusal: { reason: reasonArg, message: messageArg } });
+
+const failCanonicalInput = (reasonArg: string): never => {
+  throw new Error(reasonArg);
+};
+
+/**
+ * Judges an envelope a consumer fetched or an operator imported.
+ *
+ * In order: exact envelope shape, `catalogDigest` against the catalog, one valid signature by a
+ * trusted key (and no failing one), the contract identity, the catalog schema, every
+ * `configDigest`. The accepted envelope is an inert copy of the input. Succession against the
+ * active catalog is the caller's next step (`judgeAppStoreCatalogSuccession`).
+ */
+export const verifyAppStoreCatalogEnvelope = async (
+  envelopeArg: unknown,
+  optionsArg: IAppStoreCatalogVerificationOptions,
+): Promise<TAppStoreCatalogVerification> => {
+  let inert: unknown;
+  try {
+    inert = JSON.parse(canonicalizeStrictJson(envelopeArg, failCanonicalInput, 'envelope'));
+  } catch (error) {
+    return refuse('schemaInvalid', error instanceof Error ? error.message : 'envelope is not canonical JSON');
+  }
+  const shapeErrors = validateAppStoreCatalogEnvelopeShape(inert);
+  const envelope = readDataProperties(inert);
+  const signatures = envelope === null
+    ? null
+    : readDataElements(envelope.signatures, appStoreCatalogContract.maximumSignatures);
+  if (shapeErrors.length > 0 || envelope === null || signatures === null
+    || typeof envelope.catalogDigest !== 'string' || !isSha256Digest(envelope.catalogDigest)) {
+    return refuse('schemaInvalid', shapeErrors.join('; ') || 'envelope must be an object');
+  }
+
+  if (await computeAppStoreCatalogDigest(envelope.catalog) !== envelope.catalogDigest) {
+    return refuse('digestMismatch', 'catalogDigest does not match the catalog');
+  }
+  const trustedKeys = new Map<string, string>();
+  for (const trustedKey of optionsArg.trustedKeys) {
+    let keyId: TSha256Digest;
+    try {
+      keyId = await computeAppStoreCatalogSigningKeyId(trustedKey.publicKey);
+    } catch {
+      return refuse('signatureInvalid', `trusted key ${trustedKey.keyId} is not a raw Ed25519 public key`);
+    }
+    if (keyId !== trustedKey.keyId) {
+      return refuse('signatureInvalid', `trusted key ${trustedKey.keyId} does not match its public key`);
+    }
+    trustedKeys.set(keyId, trustedKey.publicKey);
+  }
+  const payload = createAppStoreCatalogSignaturePayload(envelope.catalogDigest);
+  let verifiedKeyId: TSha256Digest | null = null;
+  for (const signatureArg of signatures) {
+    const signature = readDataProperties(signatureArg);
+    if (signature === null || typeof signature.keyId !== 'string' || !isSha256Digest(signature.keyId)
+      || typeof signature.signature !== 'string') {
+      return refuse('schemaInvalid', 'envelope.signatures entries must be objects');
+    }
+    const publicKey = trustedKeys.get(signature.keyId);
+    if (publicKey === undefined) continue;
+    const valid = plugins.crypto.verify(
+      null,
+      payload,
+      publicKeyObjectOf(publicKey),
+      Buffer.from(signature.signature, 'hex'),
+    );
+    if (!valid) {
+      return refuse('signatureInvalid', `signature by trusted key ${signature.keyId} does not verify`);
+    }
+    verifiedKeyId = signature.keyId;
+  }
+  if (verifiedKeyId === null) {
+    return refuse('signatureInvalid', 'no signature by a trusted key');
+  }
+
+  const contractRefusal = judgeAppStoreCatalogContract(envelope.catalog);
+  if (contractRefusal !== null) return { accepted: false, refusal: contractRefusal };
+  if (!isAppStoreCatalogEnvelope(inert, optionsArg)) {
+    return refuse('schemaInvalid', validateAppStoreCatalogEnvelope(inert, optionsArg).join('; '));
+  }
+  const mismatch = await findAppStoreCatalogConfigDigestMismatch(inert.catalog);
+  if (mismatch !== null) return refuse('digestMismatch', mismatch);
+  return { accepted: true, envelope: inert, keyId: verifiedKeyId };
+};

package/ts/runtime.ts

@@ -46,6 +46,7 @@ export * from './runtime.corestore.js';
 export * from './runtime.corestore.databaseexportpackage.js';
 export * from './runtime.corestore.relay.js';
 export * from './runtime.assignmentsecret.js';
+export * from './runtime.appstorecatalog.js';
 
 export interface ISealedResolvedSecretMaterialEntry {
   secretVersionId: string;