@serve.zone/interfaces 28.4.0 → 29.0.0

package/ts/data/runtimeconfig.ts

@@ -0,0 +1,395 @@
+import type {
+  IImmutableContainerInvocationPlatformEvidenceV1,
+  IImmutableContainerInvocationV1,
+  TSha256Digest,
+} from './immutableimage.js';
+import {
+  buildDigestPinnedImageReference,
+  isSha256Digest,
+  validateImmutableContainerInvocation,
+  verifyImmutableContainerInvocationDigest,
+} from './immutableimage.js';
+import type { IRuntimeAssignmentV1, IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
+import { snapshotRuntimeAssignmentV1, validateRuntimeAssignmentV1 } from './runtimeassignment.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+
+/** A container target only; declaration does not publish a host or gateway port. */
+export interface IRuntimeConfigTargetPortV1 {
+  name: string;
+  port: number;
+  /** Inclusive; equal to port for a single port. */
+  portEnd: number;
+  protocol: 'tcp' | 'udp';
+}
+
+export interface IRuntimeConfigReadinessTimingV1 {
+  /** Measured from the evidenced container start; no probes before this delay. */
+  initialDelayMs: number;
+  /** Failures during this startup grace cannot mark the workload unhealthy. */
+  startupGraceMs: number;
+  /** Probe start-to-start interval; probes must never overlap. */
+  intervalMs: number;
+  /** Per-probe deadline, including connection, TLS and HTTP response headers. */
+  timeoutMs: number;
+  /** Consecutive successful probes needed before ready becomes true. */
+  successThreshold: number;
+  /** Consecutive failures after startup grace needed to declare unhealthy. */
+  failureThreshold: number;
+}
+
+export type TRuntimeConfigReadinessV1 = IRuntimeConfigReadinessTimingV1 & (
+  | { kind: 'process' }
+  | { kind: 'tcp'; targetPort: string; port: number }
+  | {
+    kind: 'http';
+    targetPort: string;
+    port: number;
+    scheme: 'http' | 'https';
+    /**
+     * Host header name and HTTPS SNI/certificate hostname. Connect only to the
+     * evidenced container endpoint, never resolve this name as a probe target.
+     * HTTPS verifies system trust and this hostname; no insecure TLS mode.
+     */
+    host: string;
+    /** Canonical origin-form request target, including any nonsecret query. */
+    path: string;
+    /** Sorted unique final HTTP response status codes. */
+    expectedStatusCodes: number[];
+    /** A redirect response is evaluated as received; it cannot redirect probes. */
+    followRedirects: false;
+  }
+);
+
+export interface IRuntimeConfigLogPolicyV1 {
+  /** Maximum UTF-8 bytes in one captured stdout/stderr line. */
+  maximumLineBytes: number;
+  /** Maximum bytes waiting for delivery; overflow requires explicit evidence. */
+  maximumBufferedBytes: number;
+  /** Retention of archived logs; durable payloads belong to SmartBucket. */
+  retentionMs: number;
+}
+
+/**
+ * Controller-owned resolved nonsecret execution intent. OCI command, effective
+ * environment, working directory and identity policy must be resolved before
+ * sealing; consumers must not choose resource limits or identity policies.
+ * Secrets, network identity and storage claims remain separately assignment-bound
+ * owner references. This document contains no registry credentials or host paths.
+ */
+export interface IRuntimeConfigV1 extends IRuntimeAuthorityReferenceV1 {
+  schemaVersion: 1;
+  organizationId: string;
+  serviceId: string;
+  image: {
+    registryHost: string;
+    repository: string;
+    /** Root descriptor digest, which may be an OCI platform index. */
+    imageDigest: TSha256Digest;
+    invocation: IImmutableContainerInvocationV1;
+  };
+  /** Complete effective public environment; secret values must never be inlined. */
+  environment: Record<string, string>;
+  workingDirectory: string;
+  /** null explicitly requests no CPU quota; zero and omitted values are invalid. */
+  cpuMillis: number | null;
+  memoryBytes: number;
+  readonlyRootfs: boolean;
+  /**
+   * Both identity fields must be numbers or both must be null. The null pair
+   * explicitly selects the pinned platform image's OCI User, including primary
+   * and supplemental group resolution against its immutable root filesystem.
+   * An absent OCI User retains the image/runtime specification's root identity.
+   * The execution owner must delegate that resolution to the qualified runtime;
+   * it must not guess a GID for a UID-only or named image user.
+   */
+  runAsUser: number | null;
+  /** Numeric override paired with runAsUser, or null for the image identity policy. */
+  runAsGroup: number | null;
+  /** Sorted unique names, with no overlapping ranges for the same transport. */
+  targetPorts: IRuntimeConfigTargetPortV1[];
+  readiness: TRuntimeConfigReadinessV1;
+  /**
+   * SmartData owns log metadata and SmartBucket owns archived payloads. This
+   * policy does not authorize persistent local files. Any CRI log capture uses
+   * disposable process-local transport artifacts and must evidence bounded
+   * buffering, backpressure and lost data; it must not silently truncate logs.
+   */
+  logs: IRuntimeConfigLogPolicyV1;
+}
+
+export interface IRuntimeConfigAssignmentBindingV1 {
+  config: IRuntimeConfigV1;
+  assignment: IRuntimeAssignmentV1;
+  platformEvidence: IImmutableContainerInvocationPlatformEvidenceV1;
+}
+
+export const runtimeConfigV1Contract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-config-v1',
+  maximumCanonicalBytes: 262_144,
+  maximumEnvironmentEntries: 128,
+  maximumTargetPorts: 64,
+  maximumReadinessDurationMs: 3_600_000,
+  maximumLogRetentionMs: 31_536_000_000,
+} as const);
+
+const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
+const encoder = new TextEncoder();
+const isInteger = (valueArg: unknown, minimumArg: number, maximumArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && !Object.is(valueArg, -0)
+  && valueArg >= minimumArg && valueArg <= maximumArg;
+const isIdentifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
+  typeof valueArg === 'string' && isSha256Digest(valueArg);
+const isPortName = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[a-z0-9][a-z0-9_.-]{0,62}$/.test(valueArg);
+const isExactRecord = (
+  valueArg: unknown, keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const keys = Object.keys(valueArg);
+  return keys.length === keysArg.length && keys.every((keyArg) => keysArg.includes(keyArg));
+};
+
+/**
+ * Bound traversal before canonicalization and copy descriptor values so input
+ * getters/toJSON never run. The canonical helper supplies scalar Unicode and
+ * safe-integer validation. Detached output is obtained before any async work.
+ */
+const snapshotBoundedJson = (valueArg: unknown): unknown => {
+  let nodes = 0;
+  let stringBytes = 0;
+  const ancestors = new Set<object>();
+  const accountString = (value: string): void => {
+    if (value.length > runtimeConfigV1Contract.maximumCanonicalBytes) fail('runtime config string is oversized');
+    stringBytes += encoder.encode(value).byteLength;
+    if (stringBytes > runtimeConfigV1Contract.maximumCanonicalBytes) fail('runtime config is oversized');
+  };
+  const copy = (value: unknown, depth: number): unknown => {
+    if (++nodes > 8192 || depth > 12) fail('runtime config exceeds structural bounds');
+    if (typeof value === 'string') { accountString(value); return value; }
+    if (value === null || typeof value === 'boolean' || typeof value === 'number') return value;
+    if (!value || typeof value !== 'object') fail('runtime config contains a non-JSON value');
+    if (ancestors.has(value)) fail('runtime config contains a cycle');
+    ancestors.add(value);
+    try {
+      const array = Array.isArray(value);
+      const prototype = Object.getPrototypeOf(value);
+      if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) {
+        fail('runtime config requires plain records and arrays');
+      }
+      const keys = Reflect.ownKeys(value);
+      if (keys.length > 257) fail('runtime config object exceeds key bounds');
+      if (array) {
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+        const length = lengthDescriptor?.value;
+        if (!isInteger(length, 0, 256) || keys.length !== length + 1) {
+          fail('runtime config requires bounded dense arrays');
+        }
+        const result: unknown[] = [];
+        for (let index = 0; index < length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+            fail('runtime config array contains a missing or non-data entry');
+          }
+          result.push(copy(descriptor.value, depth + 1));
+        }
+        return result;
+      }
+      const result: Record<string, unknown> = Object.create(null);
+      for (const key of keys) {
+        if (typeof key !== 'string') fail('runtime config contains a symbol key');
+        accountString(key);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+          fail('runtime config requires enumerable data properties');
+        }
+        result[key] = copy(descriptor.value, depth + 1);
+      }
+      return result;
+    } finally { ancestors.delete(value); }
+  };
+  const canonical = canonicalizeStrictJson(copy(valueArg, 0), fail);
+  if (encoder.encode(canonical).byteLength > runtimeConfigV1Contract.maximumCanonicalBytes) {
+    fail('runtime config canonical JSON is oversized');
+  }
+  return JSON.parse(canonical);
+};
+
+const timingKeys = ['initialDelayMs', 'startupGraceMs', 'intervalMs', 'timeoutMs',
+  'successThreshold', 'failureThreshold'] as const;
+const assertReadiness = (valueArg: unknown, portsArg: IRuntimeConfigTargetPortV1[]): void => {
+  if (!valueArg || typeof valueArg !== 'object') fail('runtime config readiness is required');
+  const value = valueArg as Record<string, unknown>;
+  const keys = value.kind === 'process' ? ['kind', ...timingKeys]
+    : value.kind === 'tcp' ? ['kind', ...timingKeys, 'targetPort', 'port']
+      : value.kind === 'http' ? ['kind', ...timingKeys, 'targetPort', 'port',
+        'scheme', 'host', 'path', 'expectedStatusCodes', 'followRedirects'] : [];
+  if (keys.length === 0 || !isExactRecord(value, keys)
+    || !isInteger(value.initialDelayMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
+    || !isInteger(value.startupGraceMs, 0, runtimeConfigV1Contract.maximumReadinessDurationMs)
+    || !isInteger(value.intervalMs, 100, runtimeConfigV1Contract.maximumReadinessDurationMs)
+    || !isInteger(value.timeoutMs, 1, 60_000)
+    || !isInteger(value.successThreshold, 1, 100)
+    || !isInteger(value.failureThreshold, 1, 100)
+    || value.timeoutMs > value.intervalMs || value.initialDelayMs > value.startupGraceMs) {
+    fail('runtime config readiness must use explicit bounded timing and exact schema');
+  }
+  if (value.kind === 'process') return;
+  const target = portsArg.find((portArg) => portArg.name === value.targetPort);
+  if (!isPortName(value.targetPort) || !target || target.protocol !== 'tcp'
+    || !isInteger(value.port, target.port, target.portEnd)) {
+    fail('runtime config readiness must select a declared TCP target and port');
+  }
+  if (value.kind === 'tcp') return;
+  if ((value.scheme !== 'http' && value.scheme !== 'https') || value.followRedirects !== false
+    || typeof value.host !== 'string' || value.host.length > 253
+    || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/.test(value.host)
+    || typeof value.path !== 'string' || value.path.length > 4096
+    || !value.path.startsWith('/') || value.path.startsWith('//')
+    || /[^\x21-\x7e]|[\\#]/.test(value.path)
+    || /%(?![0-9A-F]{2})/.test(value.path)
+    || !Array.isArray(value.expectedStatusCodes) || value.expectedStatusCodes.length === 0
+    || value.expectedStatusCodes.length > 32) {
+    fail('runtime config HTTP readiness must use an exact bounded request policy');
+  }
+  const parsed = new URL(value.path, 'http://runtime.invalid');
+  if (`${parsed.pathname}${parsed.search}` !== value.path) fail('runtime config HTTP path must be canonical');
+  let previousCode = 0;
+  for (const code of value.expectedStatusCodes) {
+    if (!isInteger(code, 200, 599) || code <= previousCode) {
+      fail('runtime config HTTP status expectations must be sorted unique final codes');
+    }
+    previousCode = code;
+  }
+};
+
+const assertConfig = (valueArg: unknown): IRuntimeConfigV1 => {
+  if (!isExactRecord(valueArg, ['schemaVersion', 'id', 'generation', 'organizationId', 'serviceId',
+    'image', 'environment', 'workingDirectory', 'cpuMillis', 'memoryBytes', 'readonlyRootfs',
+    'runAsUser', 'runAsGroup', 'targetPorts', 'readiness', 'logs', 'digest'])
+    || valueArg.schemaVersion !== 1 || !isIdentifier(valueArg.id)
+    || !isInteger(valueArg.generation, 1, Number.MAX_SAFE_INTEGER)
+    || !isIdentifier(valueArg.organizationId) || !isIdentifier(valueArg.serviceId)
+    || !isDigest(valueArg.digest)) fail('runtime config must use its exact v1 schema');
+  const image = valueArg.image;
+  if (!isExactRecord(image, ['registryHost', 'repository', 'imageDigest', 'invocation'])
+    || typeof image.registryHost !== 'string' || image.registryHost.length > 253
+    || typeof image.repository !== 'string' || image.repository.length > 255
+    || !isDigest(image.imageDigest)
+    || validateImmutableContainerInvocation(image.invocation).length !== 0) {
+    fail('runtime config image must contain exact immutable invocation evidence');
+  }
+  buildDigestPinnedImageReference(image.registryHost as string, image.repository as string,
+    image.imageDigest as TSha256Digest);
+  const environment = valueArg.environment;
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)
+    || Object.keys(environment).length > runtimeConfigV1Contract.maximumEnvironmentEntries) {
+    fail('runtime config requires an explicit bounded nonsecret environment');
+  }
+  for (const [key, value] of Object.entries(environment)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key) || typeof value !== 'string'
+      || value.includes('\u0000') || encoder.encode(value).byteLength > 8192) {
+      fail('runtime config environment must contain bounded string entries');
+    }
+  }
+  const directory = valueArg.workingDirectory;
+  if (typeof directory !== 'string' || !directory.startsWith('/')
+    || encoder.encode(directory).byteLength > 4096 || /[\u0000-\u001f\u007f]/.test(directory)
+    || (directory !== '/' && directory.split('/').slice(1).some((partArg) => !partArg || partArg === '.' || partArg === '..'))
+    || !(valueArg.cpuMillis === null || isInteger(valueArg.cpuMillis, 1, 1_000_000))
+    || !isInteger(valueArg.memoryBytes, 16 * 1024 * 1024, 2 ** 50)
+    || typeof valueArg.readonlyRootfs !== 'boolean'
+    || !((valueArg.runAsUser === null && valueArg.runAsGroup === null)
+      || (isInteger(valueArg.runAsUser, 0, 2 ** 31 - 1) && isInteger(valueArg.runAsGroup, 0, 2 ** 31 - 1)))) {
+    fail('runtime config requires canonical directory and explicit resource and identity policies');
+  }
+  const ports = valueArg.targetPorts;
+  if (!Array.isArray(ports) || ports.length > runtimeConfigV1Contract.maximumTargetPorts) {
+    fail('runtime config target ports must be a bounded array');
+  }
+  let previousName = '';
+  const validatedPorts: IRuntimeConfigTargetPortV1[] = [];
+  for (const port of ports) {
+    if (!isExactRecord(port, ['name', 'port', 'portEnd', 'protocol'])
+      || !isPortName(port.name) || port.name <= previousName
+      || !isInteger(port.port, 1, 65535) || !isInteger(port.portEnd, port.port, 65535)
+      || (port.protocol !== 'tcp' && port.protocol !== 'udp')
+      || validatedPorts.some((previousArg) => previousArg.protocol === port.protocol
+        && (port.port as number) <= previousArg.portEnd && (port.portEnd as number) >= previousArg.port)) {
+      fail('runtime config target ports require sorted unique names and nonoverlapping transport ranges');
+    }
+    previousName = port.name;
+    validatedPorts.push(port as unknown as IRuntimeConfigTargetPortV1);
+  }
+  assertReadiness(valueArg.readiness, validatedPorts);
+  const logs = valueArg.logs;
+  if (!isExactRecord(logs, ['maximumLineBytes', 'maximumBufferedBytes', 'retentionMs'])
+    || !isInteger(logs.maximumLineBytes, 1, 1_048_576)
+    || !isInteger(logs.maximumBufferedBytes, 1, 67_108_864)
+    || logs.maximumBufferedBytes < logs.maximumLineBytes
+    || !isInteger(logs.retentionMs, 1, runtimeConfigV1Contract.maximumLogRetentionMs)) {
+    fail('runtime config logs require explicit bounded line, buffer and retention limits');
+  }
+  return valueArg as unknown as IRuntimeConfigV1;
+};
+
+/**
+ * Detached exact-schema snapshot for synchronous persistence assertions. Digest
+ * integrity, scope authorization, admission and runtime readiness are not implied.
+ */
+export const snapshotRuntimeConfigV1 = (valueArg: unknown): IRuntimeConfigV1 =>
+  assertConfig(snapshotBoundedJson(valueArg));
+
+/** Domain-separated canonical JSON excludes only the config's own digest. */
+export const computeRuntimeConfigV1Digest = async (configArg: IRuntimeConfigV1): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = snapshotRuntimeConfigV1(configArg);
+  return `sha256:${await createCanonicalJsonSha256Hex(canonicalizeStrictJson({
+    domain: runtimeConfigV1Contract.digestDomain, payload,
+  }, fail), fail)}`;
+};
+
+const validateSnapshot = async (configArg: IRuntimeConfigV1): Promise<string[]> => {
+  if (!await verifyImmutableContainerInvocationDigest(configArg.image.invocation)) {
+    return ['runtime config immutable invocation digest does not match'];
+  }
+  return configArg.digest === await computeRuntimeConfigV1Digest(configArg)
+    ? [] : ['runtime config digest does not match'];
+};
+
+export const validateRuntimeConfigV1 = async (valueArg: unknown): Promise<string[]> => {
+  try { return await validateSnapshot(snapshotRuntimeConfigV1(valueArg)); }
+  catch { return ['runtime config must use its exact canonical v1 schema']; }
+};
+
+/**
+ * Bind valid content to one exact assignment and select its platform evidence.
+ * No assignment digest is embedded in the config, avoiding circular hashes.
+ * This proves content consistency only: the caller must authenticate the
+ * controller, durably admit the attempt, resolve other owner references, and
+ * verify runtime and readiness evidence before effects or route publication.
+ */
+export const bindRuntimeConfigV1ToAssignment = async (
+  configArg: unknown, assignmentArg: unknown,
+): Promise<IRuntimeConfigAssignmentBindingV1> => {
+  const config = snapshotRuntimeConfigV1(configArg);
+  const assignment = snapshotRuntimeAssignmentV1(snapshotBoundedJson(assignmentArg));
+  if ((await validateSnapshot(config)).length !== 0
+    || (await validateRuntimeAssignmentV1(assignment)).length !== 0) {
+    fail('runtime config binding requires valid config, invocation and assignment digests');
+  }
+  const reference = assignment.workload.config;
+  if (reference.id !== config.id || reference.generation !== config.generation
+    || reference.digest !== config.digest || assignment.organizationId !== config.organizationId
+    || assignment.serviceId !== config.serviceId
+    || assignment.workload.registryHost !== config.image.registryHost
+    || assignment.workload.repository !== config.image.repository
+    || assignment.workload.imageDigest !== config.image.imageDigest) {
+    fail('runtime config does not match the exact assignment reference, ownership and image');
+  }
+  const platformEvidence = config.image.invocation.evidence.find(
+    (entryArg) => entryArg.platform === assignment.workload.platform,
+  );
+  if (!platformEvidence) fail('runtime config lacks exact assignment platform evidence');
+  return { config, assignment, platformEvidence };
+};