@serve.zone/interfaces 30.7.0 → 30.8.1

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,25 @@
 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';
+
+/** 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';