@serve.zone/interfaces 32.47.0 → 32.49.0

package/ts/data/networkprojection.ts

@@ -666,7 +666,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
     }
     const members = new Map(projection.memberships.map(member => [ownerKey(member), member])), aliases = new Set<string>();
     for (const member of projection.memberships) {
-      composeServicePrivateNetworkDnsPolicy(member, member.attachments.map(attachment => networks.get(attachment.networkId)));
+      composeServicePrivateNetworkDnsPolicy(member, member.attachments.map(attachment => networks.get(attachment.networkId)),
+        current.resolvers);
       for (const attachment of member.attachments) for (const alias of attachment.aliases) {
         const name = buildPrivateNetworkFqdn(networks.get(attachment.networkId), alias);
         requireNetwork(!aliases.has(name)); aliases.add(name);
@@ -756,7 +757,8 @@ export const composeRuntimeNetworkProjectionDnsViews = async (
   const members = new Map(projection.memberships.map(member => [ownerKey(member), member]));
   return local.filter(endpoint => selected === null || selected.some(source => networkEqual(networkReferenceOf(endpoint.lease), source))).map(endpoint => {
     const member = members.get(ownerKey(endpoint.lease))!;
-    const policy = composeServicePrivateNetworkDnsPolicy(member, member.attachments.map(attachment => networks.get(attachment.networkId)));
+    const policy = composeServicePrivateNetworkDnsPolicy(member,
+      member.attachments.map(attachment => networks.get(attachment.networkId)), projection.protectedAuthority.resolvers);
     const records: IRuntimeNetworkDnsView['records'] = [];
     for (const target of projection.memberships) {
       if (target.organizationId !== member.organizationId) continue;

package/ts/data/privatenetwork.ts

@@ -2,6 +2,7 @@ import {
   readDataElements, readDataProperty, readExactDataRecord,
 } from '../private/dataproperties.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import { runtimeNetworkAuthorityContract } from './networkauthority.js';
 
 /** Cloudly owns these definitions. Membership never follows node placement. */
 export interface IPrivateNetworkPolicy {
@@ -126,6 +127,13 @@ const ipv4 = (value: unknown): string => {
   requireValue(isPlausibleUnicastIpv4(value));
   return value;
 };
+const endpoint = (value: Record<string, unknown>): { address: string; port: number } => {
+  const port = counter(value.port);
+  requireValue(port <= 65535);
+  return { address: ipv4(value.address), port };
+};
+const byEndpoint = (left: { address: string; port: number }, right: { address: string; port: number }): number =>
+  left.address < right.address ? -1 : left.address > right.address ? 1 : left.port - right.port;
 const publicSuffix = (value: unknown): string => {
   requireValue(typeof value === 'string' && value.length <= 253 && value.endsWith('.'));
   const labels = value.slice(0, -1).split('.');
@@ -141,12 +149,8 @@ export const snapshotPrivateNetworkPolicy = (value: unknown): IPrivateNetworkPol
   requireValue(policy.connectivity === 'member-full-mesh');
   if (policy.externalDns === null) return { connectivity: 'member-full-mesh', externalDns: null };
   const external = object(policy.externalDns, ['upstreams', 'allowAnyPublicName', 'permittedSuffixes']);
-  const upstreams = array(external.upstreams, privateNetworkContract.maximumUpstreams, entry => {
-    const upstream = object(entry, ['address', 'port']);
-    const port = counter(upstream.port);
-    requireValue(port <= 65535);
-    return { address: ipv4(upstream.address), port };
-  });
+  const upstreams = array(external.upstreams, privateNetworkContract.maximumUpstreams,
+    entry => endpoint(object(entry, ['address', 'port'])));
   requireValue(upstreams.length > 0 && new Set(upstreams.map(upstream => `${upstream.address}:${upstream.port}`)).size === upstreams.length);
   requireValue(typeof external.allowAnyPublicName === 'boolean');
   const permittedSuffixes = sorted(array(external.permittedSuffixes, privateNetworkContract.maximumPermittedSuffixes, publicSuffix));
@@ -223,6 +227,11 @@ export interface IServicePrivateNetworkDnsPolicy {
   networkSuffixes: Array<{ networkId: string; networkRevision: number; dnsSuffix: string }>;
   /** Empty or exactly the selected default network; never an ordered network union. */
   searchDomains: string[];
+  /**
+   * The networks' intersection for an attached service. A service attached to no
+   * network forwards any public name to the authority's resolvers, or has none
+   * when the authority declares no resolver.
+   */
   externalDns: {
     upstreams: Array<{ address: string; port: number }>;
     allowAnyPublicName: boolean;
@@ -243,12 +252,23 @@ const minimalSuffixes = (values: string[]): string[] => {
  * membership authentication, endpoint readiness, a DNS lease or a packet grant.
  * The caller must fence these exact revisions before issuing runtime authority.
  * An inactive/missing/extra network is rejected, never silently omitted.
+ *
+ * `resolvers` is the complete resolver list of the protected authority the
+ * membership is projected under. It decides external resolution only for a
+ * service attached to no private network: such a service forwards any public
+ * name to the first `maximumUpstreams` of those resolvers in address and port
+ * order, and an authority declaring none leaves it without external resolution.
+ * An attached service is decided by its networks alone, so a network denying
+ * external DNS keeps denying it whatever the authority declares.
  */
 export const composeServicePrivateNetworkDnsPolicy = (
-  membershipValue: unknown, networksValue: unknown,
+  membershipValue: unknown, networksValue: unknown, resolversValue: unknown,
 ): IServicePrivateNetworkDnsPolicy => safe(() => {
   const member = snapshotServicePrivateNetworks(membershipValue);
   const networks = array(networksValue, privateNetworkContract.maximumAttachments, snapshotPrivateNetwork);
+  const resolvers = array(resolversValue, runtimeNetworkAuthorityContract.maximumResolvers,
+    entry => endpoint(object(entry, ['id', 'address', 'port']))).sort(byEndpoint);
+  requireValue(new Set(resolvers.map(resolver => `${resolver.address}:${resolver.port}`)).size === resolvers.length);
   requireValue(networks.length === member.attachments.length
     && new Set(networks.map(network => network.id)).size === networks.length
     && new Set(networks.map(network => network.networkDnsKey)).size === networks.length
@@ -261,11 +281,15 @@ export const composeServicePrivateNetworkDnsPolicy = (
   const searchDomains = member.defaultNetworkId === null ? []
     : [networkSuffixes.find(network => network.networkId === member.defaultNetworkId)!.dnsSuffix];
   let externalDns: IServicePrivateNetworkDnsPolicy['externalDns'] = null;
-  if (ordered.length > 0 && ordered.every(network => network.policy.externalDns !== null)) {
-    const policies = ordered.map(network => network.policy.externalDns!);
+  const policies: Array<NonNullable<IPrivateNetworkPolicy['externalDns']>> = [];
+  for (const network of ordered) if (network.policy.externalDns !== null) policies.push(network.policy.externalDns);
+  if (ordered.length === 0 && resolvers.length > 0) {
+    externalDns = { upstreams: resolvers.slice(0, privateNetworkContract.maximumUpstreams),
+      allowAnyPublicName: true, permittedSuffixes: [] };
+  } else if (ordered.length > 0 && policies.length === ordered.length) {
     const upstreams = policies[0].upstreams.filter(upstream => policies.every(policy => policy.upstreams.some(
       candidate => candidate.address === upstream.address && candidate.port === upstream.port,
-    ))).sort((left, right) => left.address < right.address ? -1 : left.address > right.address ? 1 : left.port - right.port);
+    ))).sort(byEndpoint);
     // null is the unrestricted public-name set during intersection, not denial.
     let permittedSuffixes: string[] | null = null;
     for (const policy of policies) {

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;