@serve.zone/interfaces 32.20.1 → 32.22.0

package/ts/data/gateway.ts

@@ -1,4 +1,11 @@
 import type { TDnsRecordType } from './dns.js';
+import { hasExactKeys, readDataElements, readDataProperties } from '../private/dataproperties.js';
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import {
+  ipPrefixContains,
+  parseCanonicalIpAddress,
+  parseCanonicalIpPrefix,
+} from '../private/ipaddress.js';
 
 /**
  * Type of platform acting as a gateway client against a gateway (dcrouter).
@@ -115,6 +122,11 @@ export interface IGatewayCapabilities {
     read: boolean;
     export: boolean;
     forceRenew: boolean;
+    /**
+     * `getGatewayClientCertificate` and `releaseGatewayClientCertificate` are served: an exact
+     * certificate for one owned hostname, with no route behind it. Absent means unsupported.
+     */
+    exactIssuance?: boolean;
   };
   email: {
     domains: boolean;
@@ -127,6 +139,11 @@ export interface IGatewayCapabilities {
   dns: {
     authoritative: boolean;
     providerManaged: boolean;
+    /**
+     * `syncGatewayClientDnsRecord` is served: an address record at a value the client chooses
+     * inside its `allowedDnsRecordAddresses`. Absent means unsupported.
+     */
+    clientRecords?: boolean;
   };
   http3: {
     enabled: boolean;
@@ -176,6 +193,11 @@ export interface IGatewayClient {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /**
+   * Canonical address prefixes the client's own address records may point into; see
+   * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+   */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
   enabled: boolean;
   tokenCount?: number;
@@ -195,6 +217,11 @@ export interface IGatewayClientProvisioningSpec {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /**
+   * Canonical address prefixes the client's own address records may point into; see
+   * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+   */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
   enabled?: boolean;
 }
@@ -226,6 +253,8 @@ interface IGatewayClientContextBase {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /** Absent on gateways that predate address records; read it as an empty allowance. */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
 }
 
@@ -459,3 +488,282 @@ export interface IGatewayRouteSyncResult {
   dns?: IGatewayRouteDnsResult;
   message?: string;
 }
+
+/**
+ * Bounds of the gateway-client address record and certificate contracts.
+ *
+ * A gateway applies `defaultTtl` to a record that names none, and refuses a TTL outside
+ * `minTtl`..`maxTtl` as it refuses an allowance list longer than `maxAllowedDnsRecordAddresses`.
+ */
+export const gatewayClientHostnameContract = Object.freeze({
+  minTtl: 60,
+  maxTtl: 86_400,
+  defaultTtl: 300,
+  maxAllowedDnsRecordAddresses: 64,
+  maxAppIdLength: 128,
+  maxHostnameLength: 253,
+});
+
+/**
+ * What one gateway client owns a hostname for: its app and the exact hostname.
+ *
+ * The gateway client itself is never named here. The gateway resolves it from the authenticating
+ * gateway-client credential, so a client cannot act for another one. One ownership holds at most
+ * one address record and one certificate for its hostname, and a hostname is held by at most one
+ * ownership: a second client or app, a gateway route claim, or a record the gateway does not
+ * manage makes the hostname a conflict rather than a shared name.
+ */
+export interface IGatewayClientHostnameOwnership {
+  /** 1 to 128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. */
+  appId: string;
+  /** Lowercase fully qualified hostname without a trailing dot and without a wildcard. */
+  hostname: string;
+}
+
+/** Address record types a gateway client may publish at a value it chooses. */
+export type TGatewayClientDnsRecordType = 'A' | 'AAAA';
+
+/**
+ * One address record a gateway client asks the gateway to publish for its hostname.
+ *
+ * The value is the canonical literal of the record's family (a dotted quad for `A`, RFC 5952 text
+ * for `AAAA`) and must lie inside the client's `allowedDnsRecordAddresses`. The record is never
+ * proxied: a client that chooses its own address asks for exactly that address to be served.
+ */
+export interface IGatewayClientDnsRecord {
+  type: TGatewayClientDnsRecordType;
+  value: string;
+  /** Seconds, `minTtl`..`maxTtl`; `defaultTtl` when omitted. */
+  ttl?: number;
+}
+
+/**
+ * Outcome of one address record synchronization, in the gateway route DNS vocabulary.
+ *
+ * - `managed-created` / `managed-updated` / `managed-unchanged` / `managed-deleted`: done.
+ * - `target-invalid`: the value is outside the client's address allowance.
+ * - `zone-unmanaged`: no zone the gateway manages holds the hostname.
+ * - `zone-unavailable`: the zone's DNS provider or authority cannot be reached; retryable.
+ * - `record-conflict`: another ownership, a gateway route claim, or an unmanaged record holds
+ *   the hostname. The gateway never overwrites or adopts it.
+ * - `mutation-failed`: writing the record failed; retryable.
+ */
+export type TGatewayClientDnsRecordStatus = Extract<
+  TGatewayRouteDnsStatus,
+  | 'managed-created'
+  | 'managed-updated'
+  | 'managed-unchanged'
+  | 'managed-deleted'
+  | 'target-invalid'
+  | 'zone-unmanaged'
+  | 'zone-unavailable'
+  | 'record-conflict'
+  | 'mutation-failed'
+>;
+
+/** Result of `syncGatewayClientDnsRecord`. */
+export interface IGatewayClientDnsRecordSyncResult {
+  success: boolean;
+  /** True when the same request may succeed later without any change on the client's side. */
+  retryable: boolean;
+  status: TGatewayClientDnsRecordStatus;
+  hostname: string;
+  zoneName?: string;
+  /** The record this ownership holds after the call; absent after a deletion or a refusal. */
+  record?: IGatewayRouteDnsRecord;
+  /** The records that hold the hostname, as evidence for `record-conflict`. */
+  conflictingRecords?: IGatewayRouteDnsRecord[];
+  /** Unix epoch milliseconds at which the gateway checked the DNS state. */
+  checkedAt: number;
+  /** Unix epoch milliseconds at which authoritative DNS confirmed the desired state. */
+  authoritativeVerifiedAt?: number;
+  message?: string;
+}
+
+/**
+ * The certificate a gateway issued for one owned hostname, with its private key.
+ *
+ * Secret-bearing: a receiver keeps the key sealed and never logs or caches the response as is.
+ */
+export interface IGatewayClientCertificate {
+  hostname: string;
+  /** PEM leaf certificate followed by its chain. */
+  certificatePem: string;
+  /** PEM private key of the leaf certificate. */
+  privateKeyPem: string;
+  /** Unix epoch milliseconds. */
+  validFrom: number;
+  /** Unix epoch milliseconds. */
+  validUntil: number;
+  /** Unix epoch milliseconds after which asking again yields a renewed certificate. */
+  renewAfter: number;
+}
+
+/**
+ * Why a gateway does not issue a certificate for an ownership.
+ *
+ * - `zone-unmanaged`: no zone the gateway manages with verified authority holds the hostname.
+ * - `hostname-conflict`: another ownership or a gateway route claim holds the hostname.
+ * - `issuance-failed`: the certificate authority refused the order; `retryAfter` says when a new
+ *   order is placed.
+ * - `issuance-unavailable`: the gateway's ACME configuration or DNS authority is not ready.
+ */
+export type TGatewayClientCertificateRefusal =
+  | 'zone-unmanaged'
+  | 'hostname-conflict'
+  | 'issuance-failed'
+  | 'issuance-unavailable';
+
+/** Result of `getGatewayClientCertificate`. */
+export type TGatewayClientCertificateResult =
+  | {
+      status: 'ready';
+      certificate: IGatewayClientCertificate;
+    }
+  | {
+      /** An issuance runs; ask again after `retryAfterMs`. */
+      status: 'pending';
+      hostname: string;
+      retryAfterMs: number;
+    }
+  | {
+      status: 'refused';
+      hostname: string;
+      code: TGatewayClientCertificateRefusal;
+      retryable: boolean;
+      /** Unix epoch milliseconds before which asking again cannot change the answer. */
+      retryAfter?: number;
+      message?: string;
+    };
+
+/** Result of `releaseGatewayClientCertificate`. */
+export type TGatewayClientCertificateReleaseResult =
+  | {
+      success: true;
+      /** `released` when material or an issuance was held; `unchanged` when nothing was. */
+      action: 'released' | 'unchanged';
+    }
+  | {
+      success: false;
+      retryable: boolean;
+      message: string;
+    };
+
+const gatewayHostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const gatewayAppId = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/** True for a lowercase fully qualified hostname of two or more labels, without wildcard or dot. */
+export const isGatewayClientHostname = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= gatewayClientHostnameContract.maxHostnameLength
+  && valueArg.split('.').length >= 2
+  && valueArg.split('.').every((labelArg) => gatewayHostnameLabel.test(labelArg))
+);
+
+/** Validates one hostname ownership and names every reason it is refused. */
+export const validateGatewayClientHostnameOwnership = (
+  valueArg: unknown,
+  pathArg = 'ownership',
+): string[] => {
+  const ownership = readDataProperties(valueArg);
+  if (ownership === null || !hasExactKeys(ownership, ['appId', 'hostname'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  const appId = ownership.appId;
+  if (typeof appId !== 'string' || appId.length > gatewayClientHostnameContract.maxAppIdLength
+    || !gatewayAppId.test(appId)) {
+    errors.push(`${pathArg} appId must be 1 to ${gatewayClientHostnameContract.maxAppIdLength} `
+      + 'characters of letters, digits, dot, underscore, colon or hyphen, starting with a letter or digit');
+  }
+  if (!isGatewayClientHostname(ownership.hostname)) {
+    errors.push(`${pathArg} hostname must be a lowercase fully qualified hostname `
+      + 'without a trailing dot or wildcard');
+  }
+  return errors;
+};
+
+/** True for one canonical address prefix of either family whose host bits are zero. */
+export const isGatewayAddressPrefix = (valueArg: unknown): valueArg is string =>
+  parseCanonicalIpPrefix(valueArg) !== null;
+
+/** Validates a client's address allowance and names every reason it is refused. */
+export const validateGatewayAllowedDnsRecordAddresses = (
+  valueArg: unknown,
+  pathArg = 'allowedDnsRecordAddresses',
+): string[] => {
+  const maximum = gatewayClientHostnameContract.maxAllowedDnsRecordAddresses;
+  const prefixes = readDataElements(valueArg, maximum);
+  if (prefixes === null) {
+    return [`${pathArg} must be a list of at most ${maximum} address prefixes`];
+  }
+  const errors: string[] = [];
+  prefixes.forEach((prefixArg, indexArg) => {
+    if (!isGatewayAddressPrefix(prefixArg)) {
+      errors.push(`${pathArg}[${indexArg}] must be a canonical address prefix whose host bits are zero`);
+    } else if (prefixes.indexOf(prefixArg) !== indexArg) {
+      errors.push(`${pathArg}[${indexArg}] repeats ${prefixArg}`);
+    }
+  });
+  return errors;
+};
+
+/** True when the value is a canonical literal of the record type that can address one host. */
+const isGatewayClientDnsRecordAddress = (
+  typeArg: TGatewayClientDnsRecordType,
+  valueArg: unknown,
+): valueArg is string => {
+  if (typeArg === 'A') {
+    return isPlausibleUnicastIpv4(valueArg);
+  }
+  const address = parseCanonicalIpAddress(valueArg);
+  // `::` is unspecified and `ff00::/8` is multicast; neither addresses one host.
+  return address?.family === 6 && address.value !== 0n && address.value >> 120n !== 0xffn;
+};
+
+/** Validates one requested address record and names every reason it is refused. */
+export const validateGatewayClientDnsRecord = (valueArg: unknown, pathArg = 'record'): string[] => {
+  const record = readDataProperties(valueArg);
+  if (record === null || !hasExactKeys(record, ['type', 'value'], ['ttl'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const type = record.type;
+  if (type !== 'A' && type !== 'AAAA') {
+    return [`${pathArg} type must be A or AAAA`];
+  }
+  const errors: string[] = [];
+  if (!isGatewayClientDnsRecordAddress(type, record.value)) {
+    errors.push(type === 'A'
+      ? `${pathArg} value must be a canonical IPv4 host address (not 0.0.0.0/8, multicast or reserved)`
+      : `${pathArg} value must be a canonical RFC 5952 IPv6 host address (not unspecified or multicast)`);
+  }
+  const { minTtl, maxTtl } = gatewayClientHostnameContract;
+  if (Object.hasOwn(record, 'ttl') && !(typeof record.ttl === 'number'
+    && Number.isSafeInteger(record.ttl) && record.ttl >= minTtl && record.ttl <= maxTtl)) {
+    errors.push(`${pathArg} ttl must be an integer from ${minTtl} to ${maxTtl} seconds`);
+  }
+  return errors;
+};
+
+/**
+ * True when a valid record's value lies inside one of the allowance's prefixes of its family.
+ *
+ * A prefix that is not canonical allows nothing, so an allowance a gateway would refuse never
+ * widens what a record may point at.
+ */
+export const isGatewayClientDnsRecordAllowed = (
+  recordArg: IGatewayClientDnsRecord,
+  allowedDnsRecordAddressesArg: readonly string[] | undefined,
+): boolean => {
+  if (validateGatewayClientDnsRecord(recordArg).length > 0) {
+    return false;
+  }
+  const address = parseCanonicalIpAddress(recordArg.value);
+  const allowance = allowedDnsRecordAddressesArg === undefined
+    ? []
+    : readDataElements(allowedDnsRecordAddressesArg, gatewayClientHostnameContract.maxAllowedDnsRecordAddresses);
+  return address !== null && allowance !== null && allowance.some((prefixArg) => {
+    const prefix = parseCanonicalIpPrefix(prefixArg);
+    return prefix !== null && ipPrefixContains(prefix, address);
+  });
+};

package/ts/data/index.ts

@@ -3,6 +3,7 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
@@ -40,6 +41,9 @@ export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrant, IRuntimeNetworkRouterProjection } from './networkrouter.js';
 export type { IRuntimeNetworkHostIngress, IRuntimeNetworkHostPacketGrant, IRuntimeNetworkHostProjection } from './networkhost.js';
 export { runtimeNetworkHostContract } from './networkhost.js';
+export type { IRuntimeNetworkWorkloadIngress, IRuntimeNetworkWorkloadIngressPacketGrant,
+  IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
+export { runtimeNetworkWorkloadIngressContract } from './networkworkloadingress.js';
 export * from './networkprotection.js';
 export * from './networksigning.js';
 export * from './privatenetwork.js';
@@ -48,6 +52,7 @@ export * from './releaseversion.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';
 export * from './runtimestorageclaim.js';
+export * from './runtimelocalstorageclaim.js';
 export * from './runtimesession.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';

package/ts/data/networkprojection.ts

@@ -9,6 +9,8 @@ import { routerPacketGrantsOf, snapshotRouterProjection,
   type IRuntimeNetworkRouterPacketGrant, type IRuntimeNetworkRouterProjection } from './networkrouter.js';
 import { hostPacketGrantsOf, snapshotHostProjection,
   type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
+import { snapshotWorkloadIngressProjection, workloadIngressPacketGrantsOf,
+  type IRuntimeNetworkWorkloadIngressPacketGrant, type IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
 import { buildPrivateNetworkFqdn, composeServicePrivateNetworkDnsPolicy,
   snapshotPrivateNetwork, snapshotServicePrivateNetworks } from './privatenetwork.js';
 import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkDigest,
@@ -167,6 +169,21 @@ export interface IRuntimeNetworkProjection extends IRuntimeNetworkNodeScope {
    * host-origin flow; any other controller kind carrying it is refused.
    */
   host?: IRuntimeNetworkHostProjection;
+  /**
+   * One-way workload ingress selections of a `cloudly` projection: the cluster ingress workload dials
+   * exact target workload ports across organizations (`IRuntimeNetworkWorkloadIngressPacketGrant`).
+   * Omitted, it keeps the canonical bytes and grants no such flow; any other controller kind
+   * carrying it is refused.
+   */
+  workloadIngress?: IRuntimeNetworkWorkloadIngressProjection;
+  /**
+   * Ids of the protected authority's platform endpoints whose address this projection's node's own
+   * host carries, such as a relay listener or a Corestore beside the node on one machine. The node
+   * delivers workload flows to them locally instead of forwarding them. Sorted, unique and never
+   * empty when present; omitted, it keeps the canonical bytes and states that no endpoint is local.
+   * It grants nothing: a workload still reaches only the endpoints it selects.
+   */
+  hostPlatformEndpointIds?: string[];
   digest: TSha256Digest;
 }
 
@@ -322,9 +339,16 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
   requireNetwork(new TextEncoder().encode(networkCanonical(captured)).length <= runtimeNetworkProjectionContract.maximumCanonicalBytes);
   const hasRouter = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'router');
   const hasHost = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'host');
+  const hasWorkloadIngress = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'workloadIngress');
+  const hasHostPlatformEndpoints = captured !== null && typeof captured === 'object'
+    && Object.hasOwn(captured, 'hostPlatformEndpointIds');
   const item = networkRecord(captured, ['id', 'generation', 'previous', 'controller', 'nodeId', 'runtimeNamespace',
     'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest',
-    ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : [])]);
+    ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : []), ...(hasWorkloadIngress ? ['workloadIngress'] : []),
+    ...(hasHostPlatformEndpoints ? ['hostPlatformEndpointIds'] : [])]);
+  const hostPlatformEndpointIds = hasHostPlatformEndpoints
+    ? networkSorted(networkList(item.hostPlatformEndpointIds, 64, networkId), value => value) : [];
+  requireNetwork(!hasHostPlatformEndpoints || hostPlatformEndpointIds.length > 0);
   return { ...networkRevision(item), ...networkScope(item),
     protectedAuthority: snapshotRuntimeNetworkProtectedAuthority(item.protectedAuthority),
     allocationAuthorities: networkSorted(networkList(item.allocationAuthorities, 16, snapshotRuntimeNetworkProtectedAuthority), refKey),
@@ -335,6 +359,8 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
     withdrawals: networkSorted(networkList(item.withdrawals, 4096, packetGrant), networkCanonical),
     ...(hasRouter ? { router: snapshotRouterProjection(item.router) } : {}),
     ...(hasHost ? { host: snapshotHostProjection(item.host) } : {}),
+    ...(hasWorkloadIngress ? { workloadIngress: snapshotWorkloadIngressProjection(item.workloadIngress) } : {}),
+    ...(hasHostPlatformEndpoints ? { hostPlatformEndpointIds } : {}),
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
 });
 
@@ -434,6 +460,7 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
       }
       requireNetwork(!projection.retiredLeases.some(retired => networkEqual(retired, networkReferenceOf(lease))));
     }
+    for (const id of projection.hostPlatformEndpointIds ?? []) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
     for (let index = 0; index < projection.endpoints.length; index++) for (let previous = 0; previous < index; previous++) {
       requireNetwork(!networkOverlaps(projection.endpoints[index].lease.ipv4.linkSubnet, projection.endpoints[previous].lease.ipv4.linkSubnet));
     }
@@ -444,6 +471,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
     requireNetwork((projection.router?.withdrawals ?? []).every(grant => !routerGrants.has(networkCanonical(grant))));
     const hostGrants = new Set(hostPacketGrantsOf(projection).map(networkCanonical));
     requireNetwork((projection.host?.withdrawals ?? []).every(grant => !hostGrants.has(networkCanonical(grant))));
+    const workloadIngressGrants = new Set(workloadIngressPacketGrantsOf(projection).map(networkCanonical));
+    requireNetwork((projection.workloadIngress?.withdrawals ?? []).every(grant => !workloadIngressGrants.has(networkCanonical(grant))));
     requireNetwork(projection.digest === await computeRuntimeNetworkProjectionDigest(projection));
     return projection;
   } catch { return failNetwork(); }
@@ -461,6 +490,12 @@ export const getRuntimeNetworkProjectionRouterPacketGrants = async (value: unkno
 export const getRuntimeNetworkProjectionHostPacketGrants = async (value: unknown): Promise<IRuntimeNetworkHostPacketGrant[]> =>
   hostPacketGrantsOf(await validateRuntimeNetworkProjection(value));
 
+/** One-way workload ingress authority comes only from explicit signed `cloudly` selections of exact target ports. */
+export const getRuntimeNetworkProjectionWorkloadIngressPacketGrants = async (
+  value: unknown,
+): Promise<IRuntimeNetworkWorkloadIngressPacketGrant[]> =>
+  workloadIngressPacketGrantsOf(await validateRuntimeNetworkProjection(value));
+
 /** Complete offline DNS material, including authorized names never previously queried. */
 /** Select exact local receivers before expansion; all targets still come from
  * the complete validated projection. Selection supplies no attachment authority. */
@@ -526,6 +561,7 @@ export const admitRuntimeNetworkProjection = async (
     if (previousInput === null) {
       requireNetwork(projection.generation === 1 && applied === null && projection.withdrawals.length === 0
         && (projection.router?.withdrawals.length ?? 0) === 0 && (projection.host?.withdrawals.length ?? 0) === 0
+        && (projection.workloadIngress?.withdrawals.length ?? 0) === 0
         && projection.retiredLeases.length === 0 && projection.retiredHandoffs.length === 0);
       return { status: 'accepted', projection };
     }
@@ -567,6 +603,15 @@ export const admitRuntimeNetworkProjection = async (
     for (const grant of previousHostGrants) requireNetwork(hostGrants.has(networkCanonical(grant)) || hostWithdrawals.has(networkCanonical(grant)));
     const knownHostWithdrawals = new Set([...previousHostGrants, ...(previous.host?.withdrawals ?? [])].map(networkCanonical));
     requireNetwork((projection.host?.withdrawals ?? []).every(grant => knownHostWithdrawals.has(networkCanonical(grant))));
+    const workloadIngressGrants = new Set(workloadIngressPacketGrantsOf(projection).map(networkCanonical));
+    const workloadIngressWithdrawals = new Set((projection.workloadIngress?.withdrawals ?? []).map(networkCanonical));
+    const previousWorkloadIngressGrants = workloadIngressPacketGrantsOf(previous);
+    for (const grant of previousWorkloadIngressGrants) requireNetwork(workloadIngressGrants.has(networkCanonical(grant))
+      || workloadIngressWithdrawals.has(networkCanonical(grant)));
+    const knownWorkloadIngressWithdrawals = new Set([...previousWorkloadIngressGrants,
+      ...(previous.workloadIngress?.withdrawals ?? [])].map(networkCanonical));
+    requireNetwork((projection.workloadIngress?.withdrawals ?? []).every(grant =>
+      knownWorkloadIngressWithdrawals.has(networkCanonical(grant))));
     const knownLeases = [...previous.endpoints.map(endpoint => networkReferenceOf(endpoint.lease)), ...previous.retiredLeases];
     const knownHandoffs = [...(previous.handoff ? [networkReferenceOf(previous.handoff)] : []), ...previous.retiredHandoffs];
     requireNetwork(projection.retiredLeases.every(retired => knownLeases.some(known => networkEqual(known, retired)))
@@ -578,6 +623,9 @@ export const admitRuntimeNetworkProjection = async (
       for (const grant of previous.withdrawals) requireNetwork(withdrawn.has(networkCanonical(grant)));
       for (const grant of previous.router?.withdrawals ?? []) requireNetwork(routerWithdrawals.has(networkCanonical(grant)));
       for (const grant of previous.host?.withdrawals ?? []) requireNetwork(hostWithdrawals.has(networkCanonical(grant)));
+      for (const grant of previous.workloadIngress?.withdrawals ?? []) {
+        requireNetwork(workloadIngressWithdrawals.has(networkCanonical(grant)));
+      }
       requireCarried(previous.retiredLeases, projection.retiredLeases); requireCarried(previous.retiredHandoffs, projection.retiredHandoffs);
     }
     for (const old of previous.endpoints) {

package/ts/data/networkworkloadingress.ts

@@ -0,0 +1,107 @@
+import type { IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
+import type { IRuntimeNetworkWorkloadLease } from './networkprojection.js';
+import { networkCanonical, networkCounter, networkEqual, networkList, networkRecord, networkReference,
+  networkReferenceOf, networkSameScope, networkSorted, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * Exact one-way flow authority from one workload to one port of another: the cluster ingress
+ * workload dials the target workload's lease address on exactly this protocol and port.
+ *
+ * Unlike the projection's workload grants it needs neither the same organization nor a shared
+ * private network, and it opens one port instead of every port; nothing flows the other way except
+ * the replies of a connection the source opened.
+ */
+export interface IRuntimeNetworkWorkloadIngressPacketGrant {
+  source: IRuntimeAuthorityReference;
+  destination: { lease: IRuntimeAuthorityReference; protocol: 'tcp' | 'udp'; port: number };
+}
+
+/** One target port the ingress workload may dial, and the Cloudly decision that authorized it. */
+export interface IRuntimeNetworkWorkloadIngress {
+  /** Exact lease of the ingress workload, an endpoint of this projection. */
+  source: IRuntimeAuthorityReference;
+  /** Exact lease of the target workload, another endpoint of this projection. */
+  destination: IRuntimeAuthorityReference;
+  protocol: 'tcp' | 'udp';
+  /** The target workload's own listening port inside its network namespace. */
+  port: number;
+  /** Covered by the projection signature; it never enters the packet grant's identity. */
+  authorization: IRuntimeAuthorityReference;
+}
+
+/**
+ * Workload ingress selections plus retained denials. Only a projection of a `cloudly` controller may
+ * carry it; omitting it keeps the projection's canonical bytes and grants no workload ingress flow.
+ */
+export interface IRuntimeNetworkWorkloadIngressProjection {
+  /**
+   * Strictly increasing by the canonical form of `[source.id, destination.id, protocol, port]`, so
+   * one entry per tuple. Each entry names at least one endpoint placed on this projection's node.
+   */
+  grants: IRuntimeNetworkWorkloadIngress[];
+  withdrawals: IRuntimeNetworkWorkloadIngressPacketGrant[];
+}
+
+export const runtimeNetworkWorkloadIngressContract = Object.freeze({
+  controllerKind: 'cloudly',
+  source: 'ingress-workload-lease',
+  destination: 'target-workload-lease-address-exact-port',
+  maximumGrants: 1024,
+  maximumWithdrawals: 4096,
+} as const);
+
+const grantKey = (value: {
+  source: IRuntimeAuthorityReference; destination: IRuntimeAuthorityReference; protocol: string; port: number;
+}): string => networkCanonical([value.source.id, value.destination.id, value.protocol, value.port]);
+const protocol = (value: unknown): 'tcp' | 'udp' => {
+  requireNetwork(value === 'tcp' || value === 'udp'); return value;
+};
+
+const packetGrant = (value: unknown): IRuntimeNetworkWorkloadIngressPacketGrant => {
+  const item = networkRecord(value, ['source', 'destination']);
+  const destination = networkRecord(item.destination, ['lease', 'protocol', 'port']);
+  return { source: networkReference(item.source), destination: { lease: networkReference(destination.lease),
+    protocol: protocol(destination.protocol), port: networkCounter(destination.port, 65535) } };
+};
+
+const grant = (value: unknown): IRuntimeNetworkWorkloadIngress => {
+  const item = networkRecord(value, ['source', 'destination', 'protocol', 'port', 'authorization']);
+  const result = { source: networkReference(item.source), destination: networkReference(item.destination),
+    protocol: protocol(item.protocol), port: networkCounter(item.port, 65535), authorization: networkReference(item.authorization) };
+  requireNetwork(result.source.id !== result.destination.id);
+  return result;
+};
+
+/** Internal parser: the enclosing projection has already captured caller input. */
+export const snapshotWorkloadIngressProjection = (value: unknown): IRuntimeNetworkWorkloadIngressProjection => {
+  const item = networkRecord(value, ['grants', 'withdrawals']);
+  return {
+    grants: networkSorted(networkList(item.grants, runtimeNetworkWorkloadIngressContract.maximumGrants, grant), grantKey),
+    withdrawals: networkSorted(networkList(item.withdrawals, runtimeNetworkWorkloadIngressContract.maximumWithdrawals,
+      packetGrant), networkCanonical),
+  };
+};
+
+/** Internal composition after capture. The public helper validates the whole projection. */
+export const workloadIngressPacketGrantsOf = (projection: {
+  controller: IRuntimeController;
+  nodeId: string;
+  runtimeNamespace: string;
+  workloadIngress?: IRuntimeNetworkWorkloadIngressProjection;
+  endpoints: Array<{ lease: IRuntimeNetworkWorkloadLease }>;
+}): IRuntimeNetworkWorkloadIngressPacketGrant[] => {
+  const selected = projection.workloadIngress;
+  if (!selected) return [];
+  requireNetwork(projection.controller.kind === runtimeNetworkWorkloadIngressContract.controllerKind);
+  const leaseOf = (reference: IRuntimeAuthorityReference): IRuntimeNetworkWorkloadLease => {
+    const endpoint = projection.endpoints.find(candidate => networkEqual(networkReferenceOf(candidate.lease), reference));
+    requireNetwork(endpoint); return endpoint.lease;
+  };
+  const result = selected.grants.map((entry): IRuntimeNetworkWorkloadIngressPacketGrant => {
+    const source = leaseOf(entry.source), destination = leaseOf(entry.destination);
+    requireNetwork(networkSameScope(source, projection) || networkSameScope(destination, projection));
+    return { source: networkReferenceOf(source),
+      destination: { lease: networkReferenceOf(destination), protocol: entry.protocol, port: entry.port } };
+  });
+  return result.sort((left, right) => networkCanonical(left) < networkCanonical(right) ? -1 : 1);
+};