@serve.zone/interfaces 30.7.0 → 30.9.0

package/ts/data/networksigning.ts

@@ -0,0 +1,84 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './runtimeassignment.js';
+import type { IRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { snapshotRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
+import { captureNetwork, failNetwork, networkController, networkDigest, networkEqual, networkHash,
+  networkRecord, networkReference, networkReferenceOf, networkRevision, networkSafe, requireNetwork } from '../private/networkcontract.js';
+
+export interface ISignedRuntimeNetworkProjectionV1 {
+  schemaVersion: 1;
+  authority: IRuntimeAuthorityReferenceV1;
+  projection: IRuntimeNetworkProjectionV1;
+  /** Ed25519 signature of the complete domain-separated envelope, lowercase hex. */
+  signature: string;
+}
+
+export const snapshotSignedRuntimeNetworkProjectionV1 = (value: unknown): ISignedRuntimeNetworkProjectionV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'authority', 'projection', 'signature']);
+  requireNetwork(item.schemaVersion === 1 && typeof item.signature === 'string' && /^[a-f0-9]{128}$/.test(item.signature));
+  return { schemaVersion: 1, authority: networkReference(item.authority), projection: snapshotRuntimeNetworkProjectionV1(item.projection), signature: item.signature };
+});
+
+/**
+ * Dedicated controller signing authority, installed through the CURRENT authenticated
+ * physical session. Never obtain trusted authority from an envelope being verified.
+ * null revokes signing; rotation requires a new complete signed projection for DNS.
+ * Existing packet grants still require applied denial or independent fencing.
+ */
+export interface IRuntimeNetworkSigningAuthorityV1 {
+  schemaVersion: 1;
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReferenceV1 | null;
+  controller: IRuntimeControllerV1;
+  algorithm: 'Ed25519';
+  /** Canonical 32-byte raw public key, lowercase hex. No private material. */
+  publicKey: string | null;
+  digest: TSha256Digest;
+}
+
+export const runtimeNetworkSigningV1Contract = Object.freeze({
+  authorityDigestDomain: 'serve.zone/runtime-network-signing-authority-v1',
+  signatureDomain: 'serve.zone/runtime-network-projection-signature-v1',
+  trust: 'current-authenticated-physical-session-and-durable-revision-fence',
+  rotation: 'replace-dns-authority-with-new-signed-projection',
+  revocation: 'no-implicit-packet-denial-or-allocation-reuse',
+} as const);
+
+export const snapshotRuntimeNetworkSigningAuthorityV1 = (value: unknown): IRuntimeNetworkSigningAuthorityV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'id', 'generation', 'previous', 'controller', 'algorithm', 'publicKey', 'digest']);
+  requireNetwork(item.schemaVersion === 1 && item.algorithm === 'Ed25519');
+  requireNetwork(item.publicKey === null || (typeof item.publicKey === 'string'
+    && /^[a-f0-9]{64}$/.test(item.publicKey) && item.publicKey !== '0'.repeat(64)));
+  return { schemaVersion: 1, ...networkRevision(item), controller: networkController(item.controller),
+    algorithm: 'Ed25519', publicKey: item.publicKey, digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkSigningAuthorityV1Digest = (value: IRuntimeNetworkSigningAuthorityV1): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkSigningV1Contract.authorityDigestDomain, snapshotRuntimeNetworkSigningAuthorityV1(value));
+
+/**
+ * Detached content/CAS check. Caller must fence the live peer and commit atomically.
+ * A newly enrolled node bootstraps the controller's CURRENT authority at any generation;
+ * it must not fabricate local history or use this bootstrap path to erase existing trust.
+ */
+export const admitRuntimeNetworkSigningAuthorityV1 = async (
+  value: unknown, previousValue: unknown | null, trustedSessionValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; authority: IRuntimeNetworkSigningAuthorityV1 }> => {
+  try {
+    const authority = snapshotRuntimeNetworkSigningAuthorityV1(value);
+    const previous = previousValue === null ? null : snapshotRuntimeNetworkSigningAuthorityV1(previousValue);
+    const session = snapshotRuntimeSessionBindingV1(trustedSessionValue);
+    requireNetwork(networkEqual(authority.controller, session.controller));
+    requireNetwork(authority.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(authority));
+    if (previous === null) return { status: 'accepted', authority };
+    requireNetwork(previous.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(previous)
+      && authority.id === previous.id && networkEqual(previous.controller, authority.controller));
+    if (authority.generation === previous.generation) {
+      requireNetwork(networkEqual(authority, previous)); return { status: 'replay', authority };
+    }
+    requireNetwork(networkEqual(authority.previous, networkReferenceOf(previous)));
+    return { status: 'accepted', authority };
+  } catch { return failNetwork(); }
+};

package/ts/private/networkcontract.ts

@@ -0,0 +1,117 @@
+import type { TSha256Digest } from '../data/immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from '../data/runtimeassignment.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
+
+export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
+export function requireNetwork(value: unknown): asserts value { if (!value) failNetwork(); }
+export const networkCanonical = (value: unknown): string => canonicalizeStrictJson(value, failNetwork);
+export const networkEqual = (left: unknown, right: unknown): boolean => networkCanonical(left) === networkCanonical(right);
+export const networkSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failNetwork(); } };
+
+/** Bound decoded transport input before canonicalization; never execute getters/toJSON. */
+export const captureNetwork = (value: unknown): unknown => networkSafe(() => {
+  const encoder = new TextEncoder(), ancestors = new Set<object>();
+  let nodes = 0, bytes = 0;
+  const account = (text: string) => {
+    requireNetwork(text.length <= 1_048_576);
+    bytes += encoder.encode(text).length;
+    requireNetwork(bytes <= 1_048_576);
+  };
+  const copy = (item: unknown, depth: number): unknown => {
+    requireNetwork(++nodes <= 65_536 && depth <= 24);
+    if (typeof item === 'string') { account(item); return item; }
+    if (item === null || typeof item === 'boolean') return item;
+    if (typeof item === 'number') {
+      requireNetwork(Number.isSafeInteger(item) && !Object.is(item, -0)); return item;
+    }
+    requireNetwork(item !== null && typeof item === 'object' && !ancestors.has(item));
+    const array = Array.isArray(item), prototype = Object.getPrototypeOf(item), keys = Reflect.ownKeys(item);
+    requireNetwork(array ? prototype === Array.prototype : prototype === Object.prototype || prototype === null);
+    requireNetwork(keys.length <= 4097);
+    ancestors.add(item);
+    try {
+      if (array) {
+        const length = Object.getOwnPropertyDescriptor(item, 'length')?.value;
+        requireNetwork(Number.isSafeInteger(length) && length >= 0 && length <= 4096 && keys.length === length + 1);
+        const result: unknown[] = [];
+        for (let index = 0; index < length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(item, String(index));
+          requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+          result.push(copy(descriptor.value, depth + 1));
+        }
+        return result;
+      }
+      const result: Record<string, unknown> = Object.create(null);
+      for (const key of keys) {
+        requireNetwork(typeof key === 'string'); account(key);
+        const descriptor = Object.getOwnPropertyDescriptor(item, key);
+        requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+        result[key] = copy(descriptor.value, depth + 1);
+      }
+      return result;
+    } finally { ancestors.delete(item); }
+  };
+  const result = copy(value, 0);
+  requireNetwork(encoder.encode(networkCanonical(result)).length <= 1_048_576);
+  return result;
+});
+
+export const networkRecord = (value: unknown, keys: string[]): Record<string, unknown> => {
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  const actual = Object.keys(value);
+  requireNetwork(actual.length === keys.length && keys.every(key => Object.hasOwn(value, key)));
+  return value as Record<string, unknown>;
+};
+export const networkList = <T>(value: unknown, maximum: number, read: (item: unknown) => T): T[] => {
+  requireNetwork(Array.isArray(value) && value.length <= maximum); return value.map(read);
+};
+export const networkSorted = <T>(values: T[], key: (item: T) => string): T[] => {
+  requireNetwork(values.every((value, index) => index === 0 || key(values[index - 1]) < key(value))); return values;
+};
+export const networkId = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value)); return value;
+};
+export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER - 1): number => {
+  requireNetwork(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= maximum); return value;
+};
+export const networkDigest = (value: unknown): TSha256Digest => {
+  requireNetwork(typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)); return value as TSha256Digest;
+};
+export const networkController = (value: unknown): IRuntimeControllerV1 => {
+  const item = networkRecord(value, ['kind', 'id', 'epoch']);
+  requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');
+  return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
+};
+export const networkReference = (value: unknown): IRuntimeAuthorityReferenceV1 => {
+  const item = networkRecord(value, ['id', 'generation', 'digest']);
+  return { id: networkId(item.id), generation: networkCounter(item.generation), digest: networkDigest(item.digest) };
+};
+export const networkReferenceOf = (value: IRuntimeAuthorityReferenceV1): IRuntimeAuthorityReferenceV1 =>
+  ({ id: value.id, generation: value.generation, digest: value.digest });
+export const networkRevision = (item: Record<string, unknown>) => {
+  const id = networkId(item.id), generation = networkCounter(item.generation);
+  const previous = item.previous === null ? null : networkReference(item.previous);
+  requireNetwork(generation === 1 ? previous === null : previous?.id === id && previous.generation === generation - 1);
+  return { id, generation, previous };
+};
+export const networkHash = async (domain: string, value: { digest: TSha256Digest }): Promise<TSha256Digest> => {
+  const { digest: omitted, ...payload } = value;
+  return `sha256:${await createCanonicalJsonSha256Hex(networkCanonical({ domain, payload }), failNetwork)}`;
+};
+export const networkIpv4 = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && value.length <= 15);
+  const parts = value.split('.');
+  requireNetwork(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+  return value;
+};
+export const networkIpv4Number = (value: string): number => value.split('.').reduce((sum, part) => sum * 256 + Number(part), 0);
+export const networkPrefixBounds = (value: string): [number, number] => {
+  const [address, bits] = value.split('/'), first = networkIpv4Number(address);
+  return [first, first + 2 ** (32 - Number(bits)) - 1];
+};
+export const networkContains = (outer: string, inner: string): boolean => {
+  const [a, b] = networkPrefixBounds(outer), [c, d] = networkPrefixBounds(inner); return a <= c && b >= d;
+};
+export const networkOverlaps = (left: string, right: string): boolean => {
+  const [a, b] = networkPrefixBounds(left), [c, d] = networkPrefixBounds(right); return a <= d && c <= b;
+};

package/ts/requests/runtimesession.ts

@@ -1,6 +1,35 @@
 import * as plugins from '../plugins.js';
 import type * as data from '../data/runtimesession.js';
 import type * as terminal from '../data/runtimeterminalreceipt.js';
+import type * as network from '../data/networkdelivery.js';
+import type * as protection from '../data/networkprotection.js';
+
+/** Current authenticated peer reports its durable complete native protection journal. */
+export interface IReq_Pallet_Controller_ReportRuntimeNetworkProtectionV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeNetworkProtectionV1
+> {
+  method: 'reportRuntimeNetworkProtectionV1';
+  request: protection.IReportRuntimeNetworkProtectionRequestV1;
+  response: protection.IReportRuntimeNetworkProtectionResponseV1;
+}
+
+/** Dedicated signing trust installed only through the current authenticated physical peer. */
+export interface IReq_Controller_Pallet_ApplyRuntimeNetworkSigningAuthorityV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ApplyRuntimeNetworkSigningAuthorityV1
+> {
+  method: 'applyRuntimeNetworkSigningAuthorityV1';
+  request: network.IApplyRuntimeNetworkSigningAuthorityRequestV1;
+  response: network.IApplyRuntimeNetworkAuthorityResponseV1;
+}
+
+/** Complete signed node state; an ACK asserts admission only. */
+export interface IReq_Controller_Pallet_ApplyRuntimeNetworkProjectionV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ApplyRuntimeNetworkProjectionV1
+> {
+  method: 'applyRuntimeNetworkProjectionV1';
+  request: network.IApplyRuntimeNetworkProjectionRequestV1;
+  response: network.IApplyRuntimeNetworkAuthorityResponseV1;
+}
 
 /** WSS-only Pallet bootstrap. Derive physical peer/process/idempotency server-side. */
 export interface IReq_Pallet_Cloudly_RegisterPalletRuntimeSessionV1 extends plugins.typedrequestInterfaces.implementsTR<

package/ts/runtime.networkprojection.ts

@@ -0,0 +1,64 @@
+import * as plugins from './plugins.runtime.js';
+import type { IRuntimeAuthorityReferenceV1 } from './data/runtimeassignment.js';
+import type { IRuntimeNetworkProjectionV1 } from './data/networkprojection.js';
+import { snapshotRuntimeNetworkNodeScopeV1, snapshotRuntimeNetworkProjectionV1, validateRuntimeNetworkProjectionV1 } from './data/networkprojection.js';
+import type { IRuntimeNetworkSigningAuthorityV1, ISignedRuntimeNetworkProjectionV1 } from './data/networksigning.js';
+import { computeRuntimeNetworkSigningAuthorityV1Digest, runtimeNetworkSigningV1Contract,
+  snapshotRuntimeNetworkSigningAuthorityV1, snapshotSignedRuntimeNetworkProjectionV1 } from './data/networksigning.js';
+import { failNetwork, networkCanonical, networkEqual, networkReferenceOf, requireNetwork } from './private/networkcontract.js';
+
+/** The private KeyObject is process-local. Persist only through the controller's encrypted secret store. */
+export const createRuntimeNetworkSigningKeyV1 = (): { publicKey: string; privateKey: plugins.crypto.KeyObject } => {
+  const pair = plugins.crypto.generateKeyPairSync('ed25519');
+  const jwk = pair.publicKey.export({ format: 'jwk' });
+  requireNetwork(jwk.kty === 'OKP' && jwk.crv === 'Ed25519' && typeof jwk.x === 'string');
+  return { publicKey: Buffer.from(jwk.x, 'base64url').toString('hex'), privateKey: pair.privateKey };
+};
+
+const signatureBytes = (authority: IRuntimeAuthorityReferenceV1, projection: IRuntimeNetworkProjectionV1): Uint8Array =>
+  new TextEncoder().encode(networkCanonical({ domain: runtimeNetworkSigningV1Contract.signatureDomain, schemaVersion: 1, authority, projection }));
+const validateAuthority = async (authority: IRuntimeNetworkSigningAuthorityV1, projection: IRuntimeNetworkProjectionV1): Promise<void> => {
+  requireNetwork(authority.publicKey !== null && networkEqual(authority.controller, projection.controller)
+    && authority.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(authority));
+};
+
+/** Sign only validated complete state and a matching dedicated private key. */
+export const signRuntimeNetworkProjectionV1 = async (
+  projectionValue: unknown, authorityValue: unknown, privateKey: plugins.crypto.KeyObject,
+): Promise<ISignedRuntimeNetworkProjectionV1> => {
+  try {
+    const input = snapshotRuntimeNetworkProjectionV1(projectionValue), authority = snapshotRuntimeNetworkSigningAuthorityV1(authorityValue);
+    requireNetwork(privateKey instanceof plugins.crypto.KeyObject && privateKey.type === 'private' && privateKey.asymmetricKeyType === 'ed25519');
+    const publicKey = plugins.crypto.createPublicKey(privateKey).export({ format: 'jwk' });
+    requireNetwork(typeof publicKey.x === 'string' && Buffer.from(publicKey.x, 'base64url').toString('hex') === authority.publicKey);
+    const projection = await validateRuntimeNetworkProjectionV1(input);
+    await validateAuthority(authority, projection);
+    const reference = networkReferenceOf(authority);
+    const signature = plugins.crypto.sign(null, signatureBytes(reference, projection), privateKey).toString('hex');
+    return { schemaVersion: 1, authority: reference, projection, signature };
+  } catch { return failNetwork(); }
+};
+
+/**
+ * trustedAuthorityValue is receiver-owned persisted trust, NEVER envelope material.
+ * This verifies content/scope/signature only. The owner still performs atomic revision
+ * admission, live-session fencing, allocation barriers and conservative DNS time checks.
+ */
+export const verifyRuntimeNetworkProjectionV1 = async (
+  value: unknown, trustedAuthorityValue: unknown, trustedScopeValue: unknown,
+): Promise<ISignedRuntimeNetworkProjectionV1> => {
+  try {
+    const signed = snapshotSignedRuntimeNetworkProjectionV1(value);
+    const authority = snapshotRuntimeNetworkSigningAuthorityV1(trustedAuthorityValue);
+    const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
+    requireNetwork(networkEqual(signed.authority, networkReferenceOf(authority))
+      && signed.projection.nodeId === trusted.nodeId && signed.projection.runtimeNamespace === trusted.runtimeNamespace
+      && networkEqual(signed.projection.controller, trusted.controller));
+    await validateAuthority(authority, signed.projection);
+    const key = plugins.crypto.createPublicKey({ format: 'jwk', key: { kty: 'OKP', crv: 'Ed25519',
+      x: Buffer.from(authority.publicKey!, 'hex').toString('base64url') } });
+    requireNetwork(plugins.crypto.verify(null, signatureBytes(signed.authority, signed.projection), key, Buffer.from(signed.signature, 'hex')));
+    await validateRuntimeNetworkProjectionV1(signed.projection);
+    return signed;
+  } catch { return failNetwork(); }
+};

package/ts/runtime.ts

@@ -39,6 +39,7 @@ import {
 } from './runtime.workloadinit.js';
 
 export * from './runtime.workloadinit.js';
+export * from './runtime.networkprojection.js';
 export * from './runtime.corestore.js';
 export * from './runtime.corestore.databaseexportpackage.js';
 export * from './runtime.cloudlylegacydeploymentsettlement.js';