@volter/world-core 2.0.0

package/network-policy.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+const WORLD_NETWORK_POLICY_ENV = 'VOLTER_WORLD_NETWORK_POLICY';
+
+function object(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).some(key => !keys.includes(key))) {
+    throw new Error(`${label} has an invalid shape`);
+  }
+  return value;
+}
+
+function origins(value) {
+  if (!Array.isArray(value) || value.length > 256) throw new Error('World network egress must be an array of at most 256 exact HTTPS origins');
+  const normalized = value.map(origin => {
+    if (typeof origin !== 'string' || origin.length > 2048) throw new Error('World network egress origins must be strings');
+    let url;
+    try { url = new URL(origin); } catch { throw new Error(`Invalid World network origin: ${origin}`); }
+    if (url.protocol !== 'https:' || url.origin !== origin || url.username || url.password
+        || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(url.hostname)
+        || url.hostname.split('.').some(label => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'))
+        || /^[\d.]+$/.test(url.hostname) || url.hostname === 'localhost' || url.hostname.endsWith('.localhost')) {
+      throw new Error(`World network requires an exact canonical HTTPS origin: ${origin}`);
+    }
+    return origin;
+  });
+  return Object.freeze([...new Set(normalized)].sort());
+}
+
+function normalizeWorldNetwork(value) {
+  const network = object(value, ['egress'], 'World network');
+  return Object.freeze({ egress: origins(network.egress) });
+}
+
+function createWorldNetworkPolicy(world, network) {
+  if (typeof world !== 'string' || !world || world.length > 256) throw new Error('World network policy requires its World identity');
+  return Object.freeze({ version: 1, world, egress: normalizeWorldNetwork(network).egress });
+}
+
+function parseWorldNetworkPolicy(value) {
+  const policy = object(value, ['version', 'world', 'egress'], 'World network policy');
+  if (policy.version !== 1) throw new Error('Unsupported World network policy version');
+  return createWorldNetworkPolicy(policy.world, { egress: policy.egress });
+}
+
+function worldNetworkPolicyFromEnv(env) {
+  const serialized = env[WORLD_NETWORK_POLICY_ENV];
+  if (serialized === undefined) return undefined;
+  if (typeof serialized !== 'string' || serialized.length > 65536) throw new Error('Invalid published World network policy');
+  const policy = parseWorldNetworkPolicy(JSON.parse(serialized));
+  if (!env.VOLTER_WORLD || policy.world !== env.VOLTER_WORLD) throw new Error('World network policy does not belong to the attached World');
+  return policy;
+}
+
+function allowsWorldNetworkEgress(policy, value) {
+  let url;
+  try { url = new URL(String(value)); } catch { return false; }
+  return url.protocol === 'https:' && !url.username && !url.password && policy.egress.includes(url.origin);
+}
+
+/** Loopback and private addresses stay inside the machine a World runs on: never refused. */
+function isWorldInternalHost(hostname) {
+  const h = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (!h) return true;
+  if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.test') || h === '0.0.0.0' || h === '::1') return true;
+  const v4 = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+  if (v4) {
+    const a = Number(v4[1]); const b = Number(v4[2]);
+    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+  }
+  return h.includes(':') && (h.startsWith('fc') || h.startsWith('fd') || h.startsWith('fe80:'));
+}
+
+/**
+ * Why this World refuses an outbound request to `value`, or null when it allows it. The one rule
+ * every enforcement point applies: the injector for application processes, and a twin's own
+ * World-internal outbound calls (a queue delivering to its destination), which run in a host the
+ * injector does not attach to. Internal addresses pass; strict egress refuses everything else; a
+ * published network policy refuses what it does not list. An unreadable policy refuses.
+ */
+function worldEgressRefusal(value, env = process.env) {
+  let url;
+  try { url = new URL(String(value)); } catch { return `unparseable destination ${String(value)}`; }
+  if (isWorldInternalHost(url.hostname)) return null;
+  if (env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true') return `sealed World refuses untwinned host ${url.hostname}`;
+  let policy;
+  try { policy = worldNetworkPolicyFromEnv(env); } catch (error) { return `World network policy unreadable (${error.message}); refusing ${url.hostname}`; }
+  if (policy !== undefined && !allowsWorldNetworkEgress(policy, url)) return `World network policy does not allow ${url.origin}`;
+  return null;
+}
+
+module.exports = { isWorldInternalHost, worldEgressRefusal, WORLD_NETWORK_POLICY_ENV, normalizeWorldNetwork, createWorldNetworkPolicy, parseWorldNetworkPolicy, worldNetworkPolicyFromEnv, allowsWorldNetworkEgress };

package/network-policy.d.cts

@@ -0,0 +1,10 @@
+export interface WorldNetwork { readonly egress: readonly string[] }
+export interface WorldNetworkPolicy extends WorldNetwork { readonly version: 1; readonly world: string }
+export const WORLD_NETWORK_POLICY_ENV: 'VOLTER_WORLD_NETWORK_POLICY';
+export function normalizeWorldNetwork(value: unknown): WorldNetwork;
+export function createWorldNetworkPolicy(world: string, network: WorldNetwork): WorldNetworkPolicy;
+export function parseWorldNetworkPolicy(value: unknown): WorldNetworkPolicy;
+export function worldNetworkPolicyFromEnv(env: Readonly<Record<string, string | undefined>>): WorldNetworkPolicy | undefined;
+export function allowsWorldNetworkEgress(policy: WorldNetworkPolicy, value: string | URL): boolean;
+export function isWorldInternalHost(hostname: string): boolean;
+export function worldEgressRefusal(value: string | URL, env?: Readonly<Record<string, string | undefined>>): string | null;

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@volter/world-core",
+  "version": "2.0.0",
+  "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "event-sourcing",
+    "kernel"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "inject.cjs",
+    "attach.cjs",
+    "stream-bridge.cjs",
+    "network-policy.cjs",
+    "network-policy.d.cts",
+    "app-route.cjs",
+    "vendor-hosts.cjs",
+    "app-route.d.cts",
+    "generated",
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!test-fixtures/*.SOURCE.md",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/world-core"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/world-core#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./args": {
+      "types": "./dist/src/args.d.ts",
+      "default": "./dist/src/args.js"
+    },
+    "./schemas": {
+      "types": "./dist/src/schemas.d.ts",
+      "default": "./dist/src/schemas.js"
+    },
+    "./inject": "./inject.cjs",
+    "./attach": "./attach.cjs",
+    "./stream-bridge": "./stream-bridge.cjs",
+    "./network-policy": {
+      "types": "./network-policy.d.cts",
+      "default": "./network-policy.cjs"
+    },
+    "./app-route": {
+      "types": "./app-route.d.cts",
+      "default": "./app-route.cjs"
+    },
+    "./vendor-hosts": "./vendor-hosts.cjs",
+    "./generated/pack-facts.json": "./generated/pack-facts.json",
+    "./lifecycle": {
+      "types": "./dist/src/lifecycle.d.ts",
+      "default": "./dist/src/lifecycle.js"
+    }
+  },
+  "scripts": {
+    "cli": "bun run src/cli.ts",
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "zod": "^4.4.2",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "@types/ws": "^8.5.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}