@serve.zone/interfaces 32.48.0 → 32.49.0

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/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;