@serve.zone/interfaces 32.55.0 → 32.56.0

package/ts/data/clusteringress.ts

@@ -2,7 +2,11 @@ import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { isUtcCalendarDay } from '../private/utccalendarday.js';
 import { validateProtocolOfferOn } from '../protocol.js';
 import { hasExactKeys, readDataElements, readExactDataRecord } from '../private/dataproperties.js';
-import { parseCanonicalIpPrefix } from '../private/ipaddress.js';
+import {
+  formatCanonicalIpPrefix,
+  ipv4PrefixOfMapped,
+  parseCanonicalIpPrefix,
+} from '../private/ipaddress.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { validateClusterRelay } from './cluster.js';
 import type { TServiceRuntimeRefusal } from './serviceruntime.js';
@@ -82,7 +86,11 @@ export interface IClusterHttpRoute {
    * family (`192.0.2.10/32`, `2001:db8::/64`); a request from any other source is refused.
    * Absent means every source. When present it lists 1 to
    * `clusterIngressLimits.maximumSourceAllowListEntries` distinct prefixes, none of length zero:
-   * an unrestricted route omits the member rather than spelling "everyone" a second way.
+   * an unrestricted route omits the member rather than spelling "everyone" a second way. No prefix
+   * lies inside the IPv4-mapped range `::ffff:0:0/96`: the ingress compares an IPv4-mapped client
+   * as IPv4, so such a prefix could never match and the ingress refuses the whole table carrying
+   * it; an IPv4 source is written as IPv4 (`192.0.2.0/24`, not `::ffff:c000:200/120`). A shorter
+   * IPv6 prefix that merely contains that range is accepted and admits only IPv6 sources.
    *
    * Cloudly sets it on a hostname that is not public, to the addresses the gateway forwards from,
    * so the gateway that checked the source stays the only way in. An ingress that applies it
@@ -236,7 +244,11 @@ const validateAuthentication = (valueArg: unknown, pathArg: string): string[] =>
 /**
  * Validates one source allowlist (`IClusterHttpRoute.sourceAllowList`) and names every reason it is
  * refused: 1 to `clusterIngressLimits.maximumSourceAllowListEntries` distinct canonical address
- * prefixes whose host bits are zero, none of length zero.
+ * prefixes whose host bits are zero, none of length zero and none inside the IPv4-mapped range
+ * `::ffff:0:0/96` (prefix length 96 or more with the `::ffff` head). The ingress compares an
+ * IPv4-mapped client as IPv4, so a mapped entry could never match and the ingress refuses the whole
+ * table that carries one; the reason names the IPv4 prefix to write instead. A shorter IPv6 prefix
+ * that merely contains the mapped range still matches the IPv6 sources it names and is accepted.
  */
 export const validateClusterRouteSourceAllowList = (
   valueArg: unknown,
@@ -250,11 +262,19 @@ export const validateClusterRouteSourceAllowList = (
   const errors: string[] = [];
   prefixes.forEach((prefixArg, indexArg) => {
     const prefix = parseCanonicalIpPrefix(prefixArg);
+    const mappedIpv4 = prefix === null ? null : ipv4PrefixOfMapped(prefix);
     if (prefix === null) {
       errors.push(`${pathArg}[${indexArg}] must be a canonical address prefix whose host bits are zero`);
     } else if (prefix.length === 0) {
       errors.push(`${pathArg}[${indexArg}] must not admit a whole address family; `
         + 'an unrestricted route omits sourceAllowList');
+    } else if (mappedIpv4 !== null) {
+      // Its IPv4 form of `::ffff:0:0/96` would be `0.0.0.0/0`, itself refused above.
+      errors.push(`${pathArg}[${indexArg}] must not be IPv4-mapped: an IPv4-mapped prefix never matches, `
+        + 'because the ingress compares clients as IPv4; '
+        + (mappedIpv4.length === 0
+          ? 'its IPv4 form admits a whole address family, and an unrestricted route omits sourceAllowList'
+          : `write ${formatCanonicalIpPrefix(mappedIpv4)}`));
     } else if (prefixes.indexOf(prefixArg) !== indexArg) {
       errors.push(`${pathArg}[${indexArg}] repeats ${prefixArg}`);
     }

package/ts/data/deploymentpreflight.ts

@@ -117,9 +117,14 @@ export type TDeploymentPreflightWarningCode =
  * `RECOVERY_REDEPLOY_OVER_FAILED_RUNTIME` documents that an existing-service
  * reserve preflight suppressed the CURRENT_RUNTIME_DIGEST_MISSING and
  * RUNTIME_ATTESTATION_MISMATCH blockers because the current runtime provides
- * no consistent attested digest and the service's most recent deployment
- * operation ended 'failed' or 'cleaned' (a recovery redeploy over a known-bad
- * runtime).
+ * no consistent attested digest and either
+ * - the service's most recent deployment operation ended 'failed' or
+ *   'cleaned' (a recovery redeploy over a known-bad runtime), or
+ * - the retained deployment plan breaks the plan contract, so it can never be
+ *   executed again (for example a Swarm-era plan without
+ *   `containerInvocation`), and no deployment operation is in flight: the
+ *   most recent one is absent or ended 'succeeded', 'rolled-back', 'failed'
+ *   or 'cleaned' (a recovery redeploy over an unexecutable plan).
  * `PLATFORM_BINDING_READINESS_DEFERRED` documents that the promote preflight
  * of a held greenfield service that was never promoted accepted a Corestore
  * `database` or `objectstorage` binding that is enabled but not yet `ready`.

package/ts/data/settings.ts

@@ -45,7 +45,8 @@ export interface ICloudlySettings {
    * cluster ingress serves to them (`IClusterHttpRoute.sourceAllowList`), so the gateway that checks
    * the hostname's source profile stays the only way in. Absent: no non-public hostname is served
    * by a cluster ingress. A value is accepted only when `validateClusterRouteSourceAllowList`
-   * answers no error.
+   * answers no error; an IPv4 source is written as IPv4 (`192.0.2.0/24`), never as an IPv4-mapped
+   * IPv6 prefix (`::ffff:c000:200/120`), which the ingress could never match.
    */
   dcrouterForwardSourceAddresses?: string[];
   dcrouterMailSubmissionHost?: string;

package/ts/private/ipaddress.ts

@@ -64,6 +64,10 @@ const parseIpv6 = (valueArg: string): bigint | null => {
   return groups.reduce((sumArg, groupArg) => (sumArg << 16n) | BigInt(parseInt(groupArg, 16)), 0n);
 };
 
+/** The dotted-quad text of one IPv4 address. */
+const formatIpv4 = (valueArg: bigint): string =>
+  [24n, 16n, 8n, 0n].map((shiftArg) => ((valueArg >> shiftArg) & 0xffn).toString()).join('.');
+
 /** The RFC 5952 text of one IPv6 address. */
 const formatIpv6 = (valueArg: bigint): string => {
   const groups: number[] = [];
@@ -138,3 +142,22 @@ export const ipPrefixContains = (prefixArg: IIpPrefixValue, addressArg: IIpAddre
   const hostBits = BigInt(familyBits(prefixArg.family) - prefixArg.length);
   return addressArg.value >> hostBits === prefixArg.network >> hostBits;
 };
+
+/** The canonical text of one prefix, the spelling `parseCanonicalIpPrefix` reads back. */
+export const formatCanonicalIpPrefix = (prefixArg: IIpPrefixValue): string =>
+  `${prefixArg.family === 4 ? formatIpv4(prefixArg.network) : formatIpv6(prefixArg.network)}/${prefixArg.length}`;
+
+/** Length of the IPv4-mapped IPv6 range `::ffff:0:0/96` (RFC 4291 section 2.5.5.2). */
+const ipv4MappedPrefixLength = 96;
+
+/**
+ * The IPv4 prefix an IPv6 prefix inside the IPv4-mapped range `::ffff:0:0/96` spells
+ * (`::ffff:c000:200/120` is `192.0.2.0/24`), or `null` for any other prefix. A shorter IPv6 prefix
+ * that merely contains the range is not mapped: it still names IPv6 addresses outside it.
+ */
+export const ipv4PrefixOfMapped = (prefixArg: IIpPrefixValue): IIpPrefixValue | null =>
+  prefixArg.family === 6
+    && prefixArg.length >= ipv4MappedPrefixLength
+    && prefixArg.network >> 32n === 0xffffn
+    ? { family: 4, network: prefixArg.network & 0xffffffffn, length: prefixArg.length - ipv4MappedPrefixLength }
+    : null;