@volter/twin 0.1.0

package/inject.cjs

@@ -0,0 +1,429 @@
+'use strict';
+// @volter/twin/inject — zero-edit backend injection.
+//
+// Redirect a process's calls to real vendor hosts (api.stripe.com, slack.com,
+// api.github.com, *.atlassian.net, api.linear.app, S3 endpoints, and other
+// configured vendor API hosts) to local twins, WITHOUT
+// changing the app: the app constructs its SDK exactly as in production.
+//
+//   node --require @volter/twin/inject app.js
+//   NODE_OPTIONS="--require @volter/twin/inject" <your start command>
+//
+// Twin URLs come from the environment (only configured vendors are redirected):
+//   STRIPE_TWIN_URL=http://127.0.0.1:12111
+//   SLACK_TWIN_URL  GITHUB_TWIN_URL  JIRA_TWIN_URL  LINEAR_TWIN_URL  S3_TWIN_URL
+//   OPENROUTER_TWIN_URL  CLERK_TWIN_URL  WEBRISK_TWIN_URL  RESEND_TWIN_URL  SENTRY_TWIN_URL
+//   POLAR_TWIN_URL  ANTHROPIC_TWIN_URL  ELEVENLABS_TWIN_URL  GOOGLEFAVICON_TWIN_URL  BROWSERASSETS_TWIN_URL
+//   VITAL_TWIN_URL  CALCOM_TWIN_URL  OPENWEATHER_TWIN_URL  GOOGLEMAPS_TWIN_URL  MAPBOX_TWIN_URL  STREAM_TWIN_URL
+//   DYNAMODB_TWIN_URL  TIMESTREAM_TWIN_URL  (point these at the consolidated `aws` twin, same as S3_TWIN_URL)
+//   …or combined: TWIN_INJECT="stripe=http://127.0.0.1:12111,github=http://127.0.0.1:12120"
+//
+// It patches http/https `request`/`get` and global `fetch` at the process
+// boundary. Every Node vendor SDK in this set routes through one of those
+// (stripe-node → https; @octokit → fetch; @slack/web-api & jira.js → axios →
+// http/https; @linear/sdk → fetch), so no per-SDK shim is needed.
+const http = require('http');
+const https = require('https');
+const { EventEmitter } = require('events');
+const { Readable } = require('stream');
+const Module = require('module');
+const { createPublicKey, createVerify } = require('crypto');
+
+// vendor → predicate(hostname). A vendor is only active if its twin URL is set.
+const VENDOR_HOSTS = {
+  stripe: (h) => h === 'api.stripe.com',
+  slack: (h) => h === 'slack.com' || h === 'www.slack.com' || h === 'api.slack.com',
+  github: (h) => h === 'api.github.com',
+  jira: (h) => h === 'atlassian.net' || h.endsWith('.atlassian.net'),
+  linear: (h) => h === 'api.linear.app',
+  openrouter: (h) => h === 'openrouter.ai',
+  anthropic: (h) => h === 'api.anthropic.com',
+  clerk: (h) => h === 'api.clerk.com',
+  webrisk: (h) => h === 'webrisk.googleapis.com',
+  resend: (h) => h === 'api.resend.com',
+  sentry: (h) => h === 'sentry.io' || h.endsWith('.ingest.sentry.io'),
+  polar: (h) => h === 'api.polar.sh' || h === 'sandbox-api.polar.sh',
+  elevenlabs: (h) => h === 'api.elevenlabs.io',
+  vital: (h) => h === 'api.tryvital.io' || h === 'api.sandbox.tryvital.io',
+  calcom: (h) => h === 'api.cal.com',
+  openweather: (h) => h === 'api.openweathermap.org',
+  googlemaps: (h) => h === 'maps.googleapis.com',
+  mapbox: (h) => h === 'api.mapbox.com',
+  stream: (h) => h === 'chat.stream-io-api.com',
+  googlefavicon: (h) => h === 'www.google.com' || h === 'google.com' || h === 't2.gstatic.com',
+  browserassets: (h) =>
+    h === 'cdnjs.cloudflare.com' ||
+    h === 'www.googletagmanager.com' ||
+    h === 'www.google-analytics.com' ||
+    h === 'connect.facebook.net' ||
+    h === 'snap.licdn.com' ||
+    h === 'px.ads.linkedin.com' ||
+    h === 'static.hotjar.com' ||
+    h === 'fonts.googleapis.com' ||
+    h === 'fonts.gstatic.com' ||
+    h === 'api.fontshare.com' ||
+    h === 'images.subscribe.dev' ||
+    h === 'www.youtube.com' ||
+    h === 'www.youtube-nocookie.com' ||
+    h === 'i.ytimg.com',
+  s3: (h) =>
+    h === 's3.amazonaws.com' ||
+    h.endsWith('.s3.amazonaws.com') ||
+    /^s3[.-][a-z0-9-]+\.amazonaws\.com$/.test(h) ||
+    /\.s3[.-][a-z0-9-]+\.amazonaws\.com$/.test(h) ||
+    /^s3\.dualstack\.[a-z0-9-]+\.amazonaws\.com$/.test(h) ||
+    /\.s3\.dualstack\.[a-z0-9-]+\.amazonaws\.com$/.test(h) ||
+    h.endsWith('.s3-accelerate.amazonaws.com') ||
+    h.endsWith('.s3-accelerate.dualstack.amazonaws.com') ||
+    h.endsWith('.r2.cloudflarestorage.com'),
+  // DynamoDB + Timestream are served by the SAME consolidated `aws` twin as s3 (it routes by
+  // X-Amz-Target). Point DYNAMODB_TWIN_URL / TIMESTREAM_TWIN_URL at the aws twin's URL.
+  dynamodb: (h) => /^dynamodb\.[a-z0-9-]+\.amazonaws\.com$/.test(h),
+  timestream: (h) => /(^|\.)(ingest|query)\.timestream\.[a-z0-9-]+\.amazonaws\.com$/.test(h),
+};
+
+function decodeBase64UrlJson(part) {
+  try {
+    const padded = String(part).replace(/-/g, '+').replace(/_/g, '/');
+    const json = Buffer.from(padded + '='.repeat((4 - (padded.length % 4)) % 4), 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+function decodeBase64Url(part) {
+  const padded = String(part || '').replace(/-/g, '+').replace(/_/g, '/');
+  return Buffer.from(padded + '='.repeat((4 - (padded.length % 4)) % 4), 'base64');
+}
+
+function verifyJwtWithCachedJwks(token, jwks) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3 || !jwks || !Array.isArray(jwks.keys)) return null;
+  const header = decodeBase64UrlJson(parts[0]);
+  const payload = decodeBase64UrlJson(parts[1]);
+  if (!header || !payload || header.alg !== 'RS256') return null;
+  const key = jwks.keys.find((candidate) => candidate && candidate.kid === header.kid) || jwks.keys[0];
+  if (!key) return null;
+  try {
+    const verifier = createVerify('RSA-SHA256');
+    verifier.update(`${parts[0]}.${parts[1]}`);
+    verifier.end();
+    const publicKey = createPublicKey({ key: { kty: 'RSA', n: key.n, e: key.e }, format: 'jwk' });
+    if (!verifier.verify(publicKey, decodeBase64Url(parts[2]))) return null;
+  } catch {
+    return null;
+  }
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === 'number' && now >= payload.exp) return null;
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return null;
+  const issuer = String(payload.iss || '');
+  const isTwinIssuer = issuer.includes('twin.clerk') || issuer.includes('clerk.twin') || issuer.includes('accounts.dev');
+  return isTwinIssuer ? payload : null;
+}
+
+function installClerkFastifyTwinShim() {
+  if (!process.env.CLERK_TWIN_URL || Module.__volterClerkFastifyShimInstalled) return;
+  Module.__volterClerkFastifyShimInstalled = true;
+  let cachedJwks = null;
+  const originalLoad = Module._load;
+  Module._load = function volterTwinLoad(request, parent, isMain) {
+    if (request === '@clerk/fastify') {
+      return {
+        clerkPlugin: async function clerkPlugin() {
+          const baseUrl = String(process.env.CLERK_TWIN_URL || '').replace(/\/$/, '');
+          if (!baseUrl) return;
+          const response = await fetch(`${baseUrl}/.well-known/jwks.json`);
+          if (!response.ok) throw new Error(`Clerk twin JWKS fetch failed: ${response.status}`);
+          cachedJwks = await response.json();
+        },
+        getAuth: function getAuth(req) {
+          const auth = req && (req.headers?.authorization || req.headers?.Authorization);
+          const token = typeof auth === 'string' && auth.startsWith('Bearer ') ? auth.slice('Bearer '.length) : '';
+          const payload = token ? verifyJwtWithCachedJwks(token, cachedJwks) : null;
+          return {
+            userId: typeof payload?.sub === 'string' ? payload.sub : null,
+            sessionId: typeof payload?.sid === 'string' ? payload.sid : null,
+            orgId: typeof payload?.org_id === 'string' ? payload.org_id : null,
+          };
+        },
+      };
+    }
+    return originalLoad.apply(this, arguments);
+  };
+}
+
+installClerkFastifyTwinShim();
+
+function readMap(env) {
+  const map = {};
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    const url = env[`${vendor.toUpperCase()}_TWIN_URL`];
+    if (url) map[vendor] = url.replace(/\/$/, '');
+  }
+  if (env.TWIN_INJECT) {
+    for (const pair of env.TWIN_INJECT.split(',')) {
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      const vendor = pair.slice(0, eq).trim();
+      const url = pair.slice(eq + 1).trim();
+      if (vendor && url && VENDOR_HOSTS[vendor]) map[vendor] = url.replace(/\/$/, '');
+    }
+  }
+  return map;
+}
+
+function resolveTwin(hostname, map) {
+  for (const vendor of Object.keys(VENDOR_HOSTS)) {
+    if (map[vendor] && VENDOR_HOSTS[vendor](hostname)) return { vendor, origin: map[vendor] };
+  }
+  return null;
+}
+
+function isLocalOrPrivateHost(hostname) {
+  const h = String(hostname || '').toLowerCase();
+  if (!h) return true;
+  if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.test')) return true;
+  if (h === '0.0.0.0' || h === '127.0.0.1' || h === '::1' || h === '[::1]') return true;
+  if (/^127\./.test(h)) return true;
+  if (/^10\./.test(h)) return true;
+  if (/^192\.168\./.test(h)) return true;
+  const m = h.match(/^172\.(\d+)\./);
+  if (m) {
+    const n = Number(m[1]);
+    if (n >= 16 && n <= 31) return true;
+  }
+  return false;
+}
+
+function strictEgressEnabled() {
+  return process.env.VOLTER_TWIN_STRICT_EGRESS === '1' || process.env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+}
+
+function shouldBlockUntwinned(url) {
+  return strictEgressEnabled() && url && !isLocalOrPrivateHost(url.hostname) && !resolveTwin(url.hostname, MAP);
+}
+
+// --- request-args → { url, method, headers, callback } across every overload ---
+function describe(args, defaultProtocol) {
+  const input = args[0];
+  let options = {};
+  let callback;
+  if (typeof args[1] === 'function') callback = args[1];
+  else {
+    options = args[1] || {};
+    if (typeof args[2] === 'function') callback = args[2];
+  }
+  let url = null;
+  let headers = {};
+  let method = 'GET';
+  if (input instanceof URL || typeof input === 'string') {
+    try { url = new URL(String(input)); } catch { url = null; }
+    headers = options.headers || {};
+    method = options.method || 'GET';
+  } else {
+    const merged = Object.assign({}, input || {}, options);
+    headers = merged.headers || {};
+    method = merged.method || 'GET';
+    const proto = String(merged.protocol || defaultProtocol);
+    const host = merged.hostname || merged.host;
+    const path = merged.path || '/';
+    if (host) {
+      try { url = new URL(`${proto.endsWith(':') ? proto : `${proto}:`}//${host}${path}`); } catch { url = null; }
+    }
+  }
+  return { url, method: String(method).toUpperCase(), headers, callback };
+}
+
+let ORIGINALS = null; // captured once, used to forward to the twin without re-entering the patch
+
+function forward(origin, method, fullPath, headers, body) {
+  return new Promise((resolve, reject) => {
+    let target;
+    try { target = new URL(origin); } catch (error) { reject(new Error(`bad twin URL "${origin}": ${error.message}`)); return; }
+    const mod = target.protocol === 'https:' ? ORIGINALS.httpsRequest : ORIGINALS.httpRequest;
+    const fwdHeaders = Object.assign({}, headers);
+    delete fwdHeaders['accept-encoding']; delete fwdHeaders['Accept-Encoding'];
+    const req = mod({
+      protocol: target.protocol,
+      hostname: target.hostname,
+      port: target.port,
+      method,
+      path: fullPath,
+      headers: fwdHeaders,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('error', reject);
+      res.on('end', () => resolve({ statusCode: res.statusCode || 200, headers: res.headers || {}, body: Buffer.concat(chunks) }));
+    });
+    req.on('error', reject);
+    if (body && body.length) req.write(body);
+    req.end();
+  });
+}
+
+// A stand-in ClientRequest: collects the body, forwards to the twin on end(),
+// then emits the twin's response as an IncomingMessage-shaped Readable.
+function fakeClientRequest(origin, method, fullPath, headers, callback) {
+  const request = new EventEmitter();
+  const bodyChunks = [];
+  // Some SDKs (e.g. stripe-node's NodeHttpClient) only call write()/end() from
+  // inside a `req.once('socket', …)` handler — so we must emit a socket. The
+  // socket reports `connecting: false` so callers write+end immediately.
+  const socket = new EventEmitter();
+  socket.connecting = false;
+  socket.setKeepAlive = () => socket;
+  socket.setTimeout = () => socket;
+  socket.unref = () => socket;
+  socket.ref = () => socket;
+  socket.destroy = () => socket;
+  request.socket = socket;
+  request.connection = socket;
+  process.nextTick(() => request.emit('socket', socket));
+  request.write = (chunk, enc, cb) => {
+    if (chunk) bodyChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), typeof enc === 'string' ? enc : 'utf8'));
+    if (typeof enc === 'function') enc();
+    else if (typeof cb === 'function') cb();
+    return true;
+  };
+  request.end = (chunk, enc, cb) => {
+    if (typeof chunk === 'function') { cb = chunk; chunk = undefined; }
+    else if (typeof enc === 'function') { cb = enc; enc = undefined; }
+    if (chunk) request.write(chunk, enc);
+    forward(origin, method, fullPath, headers, Buffer.concat(bodyChunks))
+      .then(({ statusCode, headers: resHeaders, body }) => {
+        const res = Readable.from([body]);
+        res.statusCode = statusCode;
+        res.statusMessage = statusCode >= 400 ? 'Error' : 'OK';
+        res.headers = Object.assign({}, resHeaders);
+        res.rawHeaders = [];
+        if (typeof callback === 'function') callback(res);
+        request.emit('response', res);
+        if (typeof cb === 'function') cb();
+      })
+      .catch((error) => request.emit('error', error));
+    return request;
+  };
+  request.setHeader = () => {};
+  request.getHeader = () => undefined;
+  request.removeHeader = () => {};
+  request.setNoDelay = () => {};
+  request.setSocketKeepAlive = () => {};
+  request.flushHeaders = () => {};
+  request.setTimeout = (_timeout, cb) => { if (typeof cb === 'function') request.once('timeout', cb); return request; };
+  request.abort = () => request.emit('abort');
+  request.destroy = () => { request.emit('close'); return request; };
+  return request;
+}
+
+function blockedClientRequest(hostname) {
+  const request = new EventEmitter();
+  const error = new Error(`[twin-inject] blocked untwinned external request to ${hostname}`);
+  const socket = new EventEmitter();
+  socket.connecting = false;
+  socket.setKeepAlive = () => socket;
+  socket.setTimeout = () => socket;
+  socket.unref = () => socket;
+  socket.ref = () => socket;
+  socket.destroy = () => socket;
+  request.socket = socket;
+  request.connection = socket;
+  request.write = () => true;
+  request.end = (_chunk, _enc, cb) => {
+    process.nextTick(() => {
+      request.emit('error', error);
+      if (typeof cb === 'function') cb(error);
+    });
+    return request;
+  };
+  request.setHeader = () => {};
+  request.getHeader = () => undefined;
+  request.removeHeader = () => {};
+  request.setNoDelay = () => {};
+  request.setSocketKeepAlive = () => {};
+  request.flushHeaders = () => {};
+  request.setTimeout = (_timeout, cb) => { if (typeof cb === 'function') request.once('timeout', cb); return request; };
+  request.abort = () => request.emit('abort');
+  request.destroy = () => { request.emit('close'); return request; };
+  return request;
+}
+
+let MAP = {};
+let installed = false;
+
+function patchedFactory(originalRequest, defaultProtocol) {
+  return function patchedRequest(...args) {
+    const { url, method, headers, callback } = describe(args, defaultProtocol);
+    const twin = url && resolveTwin(url.hostname, MAP);
+    if (twin) {
+      const fwdHeaders = Object.assign({}, headers);
+      if (!fwdHeaders.host && !fwdHeaders.Host) fwdHeaders.host = url.host;
+      return fakeClientRequest(twin.origin, method, url.pathname + url.search, fwdHeaders, callback);
+    }
+    if (shouldBlockUntwinned(url)) return blockedClientRequest(url.hostname);
+    return originalRequest.apply(this, args);
+  };
+}
+
+function install(mapOverride) {
+  MAP = Object.assign({}, MAP, mapOverride || readMap(process.env));
+  const active = Object.keys(MAP);
+  if (!active.length || installed) return { active };
+
+  ORIGINALS = {
+    httpRequest: http.request.bind(http),
+    httpGet: http.get.bind(http),
+    httpsRequest: https.request.bind(https),
+    httpsGet: https.get.bind(https),
+    fetch: typeof globalThis.fetch === 'function' ? globalThis.fetch : null,
+  };
+
+  http.request = patchedFactory(ORIGINALS.httpRequest, 'http:');
+  https.request = patchedFactory(ORIGINALS.httpsRequest, 'https:');
+  http.get = function patchedHttpGet(...args) { const req = http.request(...args); req.end(); return req; };
+  https.get = function patchedHttpsGet(...args) { const req = https.request(...args); req.end(); return req; };
+
+  if (ORIGINALS.fetch) {
+    const originalFetch = ORIGINALS.fetch;
+    globalThis.fetch = function patchedFetch(input, init) {
+      let urlStr;
+      try { urlStr = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input && input.url; } catch { urlStr = undefined; }
+      let url = null;
+      if (urlStr) { try { url = new URL(urlStr); } catch { url = null; } }
+      const twin = url && resolveTwin(url.hostname, MAP);
+      if (!twin) {
+        if (shouldBlockUntwinned(url)) return Promise.reject(new Error(`[twin-inject] blocked untwinned external fetch to ${url.hostname}`));
+        return originalFetch(input, init);
+      }
+      const target = `${twin.origin}${url.pathname}${url.search}`;
+      const reqInit = Object.assign({}, init);
+      if (!reqInit.method && typeof input === 'object' && input && input.method) reqInit.method = input.method;
+      if (!reqInit.headers && typeof input === 'object' && input && input.headers) reqInit.headers = input.headers;
+      if (reqInit.body === undefined && typeof input === 'object' && input && input.body != null) reqInit.body = input.body;
+      return originalFetch(target, reqInit);
+    };
+  }
+
+  installed = true;
+  for (const vendor of active) {
+    process.stderr.write(`[twin-inject] ${vendor}: redirecting to ${MAP[vendor]}\n`);
+  }
+  return { active };
+}
+
+function restore() {
+  if (!installed || !ORIGINALS) { MAP = {}; return; }
+  http.request = ORIGINALS.httpRequest;
+  http.get = ORIGINALS.httpGet;
+  https.request = ORIGINALS.httpsRequest;
+  https.get = ORIGINALS.httpsGet;
+  if (ORIGINALS.fetch) globalThis.fetch = ORIGINALS.fetch;
+  installed = false;
+  MAP = {};
+}
+
+module.exports = { install, restore, readMap, resolveTwin, VENDOR_HOSTS };
+
+// Auto-install when loaded as a preload (`--require`). No-op if no twin URLs are set.
+install();

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@volter/twin",
+  "version": "0.1.0",
+  "description": "Local twins of SaaS APIs — the kernel + control plane: append-only event log, projection, mirror/simulator/fork modes, egress write-ledger, connectors, and the operator control plane (status/plan/lease/refs/queue/fork). Point your real vendor SDK at a faithful, stateful local replica.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "control-plane",
+    "event-sourcing",
+    "kernel"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "inject.cjs",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!test-fixtures/*.SOURCE.md",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/control-plane"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/control-plane#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"
+  },
+  "bin": {
+    "volter-twin": "dist/src/cli.js"
+  },
+  "scripts": {
+    "cli": "bun run src/cli.ts",
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/prepare-publish.mjs prepack",
+    "postpack": "node scripts/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}