@volter/world-core 2.0.36 → 3.0.0

package/src/signing.ts

@@ -0,0 +1,231 @@
+// SIGNING ON THE CONTEXT (docs/contributing/architecture.md, "What an author writes, and how": the tokens-and-keys row)
+// — one deterministic implementation of what vendors sign with, given to handlers as `ctx.crypto`, so no pack reaches
+// `node:crypto` itself: JWTs (RS256 with a pack's instance key, HS256 with a shared secret), their verification, a
+// JWKS for a public key, an HMAC and a SHA-256. Nothing here is random: a key is the pack's data (a PEM it declares),
+// and every value a signature carries comes from the call.
+// A namespace, never named imports: a browser client bundles the kernel, and the browser's `node:crypto` polyfill has no
+// createPublicKey or timingSafeEqual; named, the bundle fails to build. They are reached only when a signature is made.
+import * as nodeCrypto from 'node:crypto';
+import { sealedBoxKeyPair, sealedBoxOpen } from './sealed-box.ts';
+
+type Row = Record<string, unknown>;
+export type Jwk = { kty: 'RSA'; use: 'sig'; alg: 'RS256'; kid: string; n: string; e: string };
+export type Jwks = { keys: Jwk[] };
+/** A signing key: an RSA private key as a PEM (its public half, given or derived, is what a JWKS serves and names by
+ *  `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs none. */
+export type SigningKey = { alg: 'RS256' | 'RS384' | 'RS512'; privatePem: string; publicPem?: string } | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string };
+/** The algorithms `jwtSign` signs with. */
+export const SIGNING_ALGORITHMS: ReadonlyArray<SigningKey['alg']> = ['RS256', 'RS384', 'RS512', 'HS256', 'HS384', 'HS512'];
+const digestOf = (alg: string): string => `sha${alg.slice(2)}`;
+/** Whether a token holds: its signature and its `exp`/`nbf` at `now` (seconds), with the payload when it does. */
+export type JwtVerdict = { valid: boolean; payload?: Row; reason?: 'malformed' | 'unexpected_alg' | 'no_matching_key' | 'bad_signature' | 'expired' | 'not_yet_valid' };
+
+const base64url = (input: Buffer | string): string => Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+const fromBase64url = (s: string): Buffer => Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+const jsonPart = (value: unknown): string => base64url(JSON.stringify(value));
+
+/** A public key's id: a prefix and the first 16 hex of SHA-256 over its DER (what its JWKS and every token name). */
+export function keyId(publicPem: string, prefix = 'ins_'): string {
+  const der = nodeCrypto.createPublicKey(publicPem).export({ type: 'spki', format: 'der' });
+  return `${prefix}${nodeCrypto.createHash('sha256').update(der).digest('hex').slice(0, 16)}`;
+}
+
+/** A JWT: `iat` and `nbf` are `now` (seconds, the World's), `exp` `now` plus the lifetime (60 s when none is given),
+ *  unless the claims name their own. RS256 tokens carry the key's `kid`. */
+export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expiresInSeconds?: number; kidPrefix?: string }): string {
+  const header = 'privatePem' in key
+    ? { alg: key.alg, typ: 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
+    : { alg: key.alg, typ: 'JWT' };
+  const payload = { iat: opts.now, exp: opts.now + (opts.expiresInSeconds ?? 60), nbf: opts.now, ...claims };
+  const input = `${jsonPart(header)}.${jsonPart(payload)}`;
+  if ('secret' in key) return `${input}.${base64url(nodeCrypto.createHmac(digestOf(key.alg), key.secret).update(input).digest())}`;
+  const signer = nodeCrypto.createSign(`RSA-SHA${key.alg.slice(2)}`);
+  signer.update(input);
+  signer.end();
+  return `${input}.${base64url(signer.sign(key.privatePem))}`;
+}
+
+/** A JWT's header and payload, unverified. */
+export function jwtDecode(token: string): { header: Row; payload: Row } {
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new Error('malformed jwt');
+  const part = (s: string): Row => JSON.parse(fromBase64url(s).toString('utf8')) as Row;
+  return { header: part(parts[0]!), payload: part(parts[1]!) };
+}
+
+function timely(payload: Row, now: number): JwtVerdict {
+  if (typeof payload.exp === 'number' && now >= payload.exp) return { valid: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && now < payload.nbf) return { valid: false, reason: 'not_yet_valid' };
+  return { valid: true, payload };
+}
+
+/** A token checked: an RS256 one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
+ *  then its `exp`/`nbf` at `now` (seconds). */
+export function jwtVerify(token: string, key: Jwks | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string }, opts: { now: number }): JwtVerdict {
+  let decoded: { header: Row; payload: Row };
+  try { decoded = jwtDecode(token); } catch { return { valid: false, reason: 'malformed' }; }
+  const [h, p, s] = token.split('.') as [string, string, string];
+  if ('secret' in key) {
+    if (decoded.header.alg !== key.alg) return { valid: false, reason: 'unexpected_alg' };
+    const expected = Buffer.from(base64url(nodeCrypto.createHmac(digestOf(key.alg), key.secret).update(`${h}.${p}`).digest()), 'utf8');
+    const given = Buffer.from(s, 'utf8');
+    if (given.length !== expected.length || !nodeCrypto.timingSafeEqual(given, expected)) return { valid: false, reason: 'bad_signature' };
+    return timely(decoded.payload, opts.now);
+  }
+  if (!['RS256', 'RS384', 'RS512'].includes(String(decoded.header.alg))) return { valid: false, reason: 'unexpected_alg' };
+  // a token naming a key the set does not hold matches none; one naming no key is tried against the set's only key
+  const jwk = decoded.header.kid !== undefined ? key.keys.find((k) => k.kid === decoded.header.kid) : key.keys.length === 1 ? key.keys[0] : undefined;
+  if (!jwk) return { valid: false, reason: 'no_matching_key' };
+  const verifier = nodeCrypto.createVerify(`RSA-SHA${String(decoded.header.alg).slice(2)}`);
+  verifier.update(`${h}.${p}`);
+  verifier.end();
+  const publicKey = nodeCrypto.createPublicKey({ key: { kty: 'RSA', n: jwk.n, e: jwk.e }, format: 'jwk' });
+  if (!verifier.verify(publicKey, fromBase64url(s))) return { valid: false, reason: 'bad_signature' };
+  return timely(decoded.payload, opts.now);
+}
+
+/** The JWKS that verifies every token a public key's pair signs. */
+export function jwks(publicPem: string, kidPrefix?: string): Jwks {
+  const jwk = nodeCrypto.createPublicKey(publicPem).export({ format: 'jwk' }) as { n?: string; e?: string };
+  return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid: keyId(publicPem, kidPrefix), n: String(jwk.n), e: String(jwk.e) }] };
+}
+
+/** An HMAC of a value, hex or base64 (a webhook's signature, a signed id): SHA-256 unless the vendor names another
+ *  (OAuth 1.0a's HMAC-SHA1). The secret is its text, or its bytes where the vendor keys with a decoded secret (Svix's
+ *  `whsec_` base64). */
+export const hmac = (secret: string | Uint8Array, value: string | Uint8Array, encoding: 'hex' | 'base64' | 'base64url' = 'hex', algorithm: 'sha1' | 'sha256' | 'sha512' = 'sha256'): string => {
+  const bytes = nodeCrypto.createHmac(algorithm, secret).update(value).digest();
+  return encoding === 'base64url' ? base64url(bytes) : bytes.toString(encoding);
+};
+
+/** A SHA-256, hex (a key stored by its hash, a deterministic id). */
+export const sha256 = (value: string): string => nodeCrypto.createHash('sha256').update(value).digest('hex');
+
+/** A digest of a value in the algorithm and encoding a vendor names (GoTrue's SHA-224 token hashes, a PKCE challenge's
+ *  base64url SHA-256). */
+export function digest(algorithm: 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512', value: string | Uint8Array, encoding: 'hex' | 'base64' | 'base64url' = 'hex'): string {
+  const bytes = nodeCrypto.createHash(algorithm).update(value).digest();
+  return encoding === 'base64url' ? base64url(bytes) : bytes.toString(encoding);
+}
+
+// ── OAuth 1.0a (RFC 5849): the signature a request carries, which the vendor checks against the secrets it holds ──────
+
+/** RFC 3986 percent-encoding as RFC 5849 §3.6 uses it (unreserved: A-Z a-z 0-9 - . _ ~). */
+export const oauth1Encode = (s: string): string =>
+  encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+/** The `Authorization: OAuth k="v", …` header's parameters, decoded, in order; undefined when it is not one. */
+export function oauth1Header(value: string | null | undefined): Array<[string, string]> | undefined {
+  const m = value ? /^OAuth\s+(.*)$/is.exec(value.trim()) : null;
+  if (!m) return undefined;
+  const out: Array<[string, string]> = [];
+  for (const part of m[1]!.split(',')) {
+    const kv = /^\s*([^=\s]+)\s*=\s*"([^"]*)"\s*$/.exec(part);
+    if (!kv) { if (part.trim() === '') continue; return undefined; }
+    try {
+      out.push([decodeURIComponent(kv[1]!), decodeURIComponent(kv[2]!)]);
+    } catch {
+      return undefined;
+    }
+  }
+  return out;
+}
+
+/** The signature base string (RFC 5849 §3.4.1): the method, the base URL (no query) and the parameters signed, each
+ *  percent-encoded and sorted by name and value. */
+export function oauth1BaseString(method: string, baseUrl: string, pairs: ReadonlyArray<readonly [string, string]>): string {
+  const encoded = pairs.map(([k, v]) => [oauth1Encode(k), oauth1Encode(v)] as const).sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1));
+  return `${method.toUpperCase()}&${oauth1Encode(baseUrl)}&${oauth1Encode(encoded.map(([k, v]) => `${k}=${v}`).join('&'))}`;
+}
+
+/** The HMAC-SHA1 signature (RFC 5849 §3.4.2) over a base string, keyed by the consumer secret and the token secret. */
+export const oauth1Signature = (base: string, consumerSecret: string, tokenSecret = ''): string =>
+  hmac(`${oauth1Encode(consumerSecret)}&${oauth1Encode(tokenSecret)}`, base, 'base64', 'sha1');
+
+/** A digest of a value as its bytes (a key or an id drawn from a hash's bytes, a deterministic embedding). */
+export function digestBytes(algorithm: 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512', value: string | Uint8Array): Uint8Array {
+  return new Uint8Array(nodeCrypto.createHash(algorithm).update(value).digest());
+}
+
+/** An MD5, hex (an object's ETag, as S3 and storage APIs give it); never a secret's protection. */
+export const md5 = (value: string | Uint8Array): string => nodeCrypto.createHash('md5').update(value).digest('hex');
+
+/** A version-4-shaped UUID derived from `seed`: the same seed gives the same id every run (R9). */
+export function uuidFrom(seed: string): string {
+  const h = sha256(seed);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${'89ab'[Number.parseInt(h[16]!, 16) % 4]}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+/** `count` lowercase letters derived from `seed` (a 20-letter project ref, a slug's suffix), the same every run. */
+export function lettersFrom(seed: string, count = 20): string {
+  let out = '';
+  for (let round = 0; out.length < count; round += 1) {
+    for (const byte of sha256(`${seed}:${round}`).match(/../g)!) {
+      if (out.length === count) break;
+      out += String.fromCharCode(97 + (Number.parseInt(byte, 16) % 26));
+    }
+  }
+  return out;
+}
+
+/** Two strings compared in constant time. */
+export function equalSecrets(a: string, b: string): boolean {
+  const left = Buffer.from(a, 'utf8');
+  const right = Buffer.from(b, 'utf8');
+  return left.length === right.length && nodeCrypto.timingSafeEqual(left, right);
+}
+
+/** A key's type, from its PEM: the schemes the kernel signs with are the deterministic ones. */
+function signingKey(privatePem: string): nodeCrypto.KeyObject {
+  const key = nodeCrypto.createPrivateKey(privatePem);
+  // ECDSA draws a random nonce for every signature, so the same write signs differently on every run: a World signs
+  // with RSA (PKCS #1 v1.5) or Ed25519, whose signatures are functions of the key and the bytes
+  if (key.asymmetricKeyType !== 'rsa' && key.asymmetricKeyType !== 'ed25519') throw new Error(`signWith: a ${key.asymmetricKeyType} key signs randomly; a World signs with an RSA or Ed25519 key`);
+  return key;
+}
+
+/** Bytes signed with a private key (RSA with SHA-256, or Ed25519), in the encoding asked: a certificate's signature,
+ *  a transparency log's checkpoint. */
+export function signWith(privatePem: string, data: string | Uint8Array, encoding: 'base64' | 'hex' | 'base64url' = 'base64'): string {
+  const key = signingKey(privatePem);
+  const bytes = nodeCrypto.sign(key.asymmetricKeyType === 'ed25519' ? null : 'sha256', typeof data === 'string' ? Buffer.from(data) : data, key);
+  return encoding === 'base64url' ? base64url(bytes) : bytes.toString(encoding);
+}
+
+/** Whether a signature holds over bytes under a public key or a certificate's (PEM, or a certificate's DER): any
+ *  scheme a vendor uses (ECDSA, RSA, Ed25519), since verifying draws nothing. The digest is SHA-256 unless named. */
+export function verifyWith(publicKey: string | Uint8Array, data: string | Uint8Array, signature: string | Uint8Array, opts: { digest?: 'sha256' | 'sha384' | 'sha512'; encoding?: 'base64' | 'hex' } = {}): boolean {
+  try {
+    const key = typeof publicKey !== 'string' || publicKey.includes('CERTIFICATE') ? new nodeCrypto.X509Certificate(typeof publicKey === 'string' ? publicKey : Buffer.from(publicKey)).publicKey : nodeCrypto.createPublicKey(publicKey);
+    const sig = typeof signature === 'string' ? Buffer.from(signature, opts.encoding ?? 'base64') : signature;
+    return nodeCrypto.verify(key.asymmetricKeyType === 'ed25519' ? null : (opts.digest ?? 'sha256'), typeof data === 'string' ? Buffer.from(data) : data, key, sig);
+  } catch {
+    return false;
+  }
+}
+
+/** A public key's PEM and its DER (SubjectPublicKeyInfo), from a public or private key's PEM or a certificate. */
+export function publicKeyOf(key: string): { pem: string; der: Uint8Array } {
+  const k = key.includes('CERTIFICATE') ? new nodeCrypto.X509Certificate(key).publicKey : nodeCrypto.createPublicKey(key);
+  return { pem: String(k.export({ type: 'spki', format: 'pem' })), der: new Uint8Array(k.export({ type: 'spki', format: 'der' })) };
+}
+
+/** An X.509 certificate read (PEM or DER): its bytes, names, validity and key, and whether an issuer's key signed it;
+ *  undefined when it is not one. */
+export function certificateOf(cert: string | Uint8Array): { der: Uint8Array; subject: string; issuer: string; subjectAltName: string | undefined; notBefore: string; notAfter: string; publicKey: { pem: string; der: Uint8Array }; issuedBy(issuer: string | Uint8Array): boolean } | undefined {
+  try {
+    const c = new nodeCrypto.X509Certificate(typeof cert === 'string' ? cert : Buffer.from(cert));
+    return {
+      der: new Uint8Array(c.raw), subject: c.subject, issuer: c.issuer, subjectAltName: c.subjectAltName,
+      notBefore: new Date(c.validFrom).toISOString(), notAfter: new Date(c.validTo).toISOString(),
+      publicKey: publicKeyOf(c.toString()),
+      issuedBy: (issuer) => { try { return c.verify(new nodeCrypto.X509Certificate(typeof issuer === 'string' ? issuer : Buffer.from(issuer)).publicKey); } catch { return false; } },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** What a handler signs and hashes with: `ctx.crypto`. */
+export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf } as const;
+export type HandlerCrypto = typeof handlerCrypto;

package/src/sigv4.ts

@@ -0,0 +1,158 @@
+// AWS Signature Version 4, VERIFIED: what an AWS-shaped twin (S3, Secrets Manager, R2's S3 endpoint) checks before it
+// answers a signed request. The published algorithm (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html,
+// "Create a signed AWS API request"), the same one executor.ts signs with, run from the other side: the request names
+// its access key, its credential scope and the headers it signed; the twin finds the key's secret, builds the canonical
+// request from what arrived, and compares signatures. A presigned URL carries the same parts in its query
+// (X-Amz-Credential, X-Amz-SignedHeaders, X-Amz-Signature; its payload `UNSIGNED-PAYLOAD`).
+//
+// Where the request reached the twin rather than the vendor, the host it signed is the vendor's: the World's injector
+// names it (`x-volter-twin-original-host`), else the Host the request carries, else its URL's. S3 signs its path as
+// sent and every other service encodes it a second time (the specification's own clause, as in executor.ts). A
+// streaming upload (`STREAMING-AWS4-HMAC-SHA256-PAYLOAD`) is checked by its seed signature; its chunk signatures are
+// not (the twin's reading: the seed binds the request, and the chunks are the body the twin keeps).
+import * as nodeCrypto from 'node:crypto';
+
+export type SigV4Verdict =
+  | { ok: true; keyId: string; region: string; service: string }
+  | { ok: false; reason: 'unsigned' | 'malformed' | 'unknown_key' | 'bad_signature' | 'expired'; keyId?: string };
+
+/** The path a request arrived with, where the kernel routed it by another (a virtual-hosted bucket put in front of the
+ *  path: pack-fetch's `routed`); a client signed the path it sent. */
+export const ORIGINAL_PATH_HEADER = 'x-volter-original-path';
+
+const rfc3986 = (v: string): string => encodeURIComponent(v).replace(/[!\x27()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+const sha256Hex = (data: string | Uint8Array): string => nodeCrypto.createHash('sha256').update(data).digest('hex');
+const hmac = (key: Uint8Array | string, data: string): Buffer => nodeCrypto.createHmac('sha256', key).update(data).digest();
+
+/** The time a SigV4 date names (`20260105T093000Z`), in epoch milliseconds. */
+const dateOf = (amz: string): number => Date.parse(`${amz.slice(0, 4)}-${amz.slice(4, 6)}-${amz.slice(6, 8)}T${amz.slice(9, 11)}:${amz.slice(11, 13)}:${amz.slice(13, 15)}Z`);
+
+/**
+ * Whether `request` is signed with SigV4 by a key `secretOf` knows (its secret, or undefined for a key the twin never
+ * issued). `body` is the bytes it carries (the payload hash of
+ * a service that sends no `x-amz-content-sha256`); `now` is the World's instant, in epoch milliseconds, for a presigned
+ * URL's expiry. The caller decides what an unsigned request is (a public read, or a refusal).
+ */
+export async function verifySigV4(request: Request, body: Uint8Array | string | undefined, secretOf: (keyId: string) => string | undefined | Promise<string | undefined>, now: number): Promise<SigV4Verdict> {
+  const url = new URL(request.url);
+  const header = request.headers.get('authorization') ?? '';
+  const presigned = url.searchParams.get('X-Amz-Algorithm') === 'AWS4-HMAC-SHA256';
+  let credential: string; let signedHeaders: string; let signature: string; let amzDate: string; let payloadHash: string;
+  if (/^AWS4-HMAC-SHA256\s/i.test(header)) {
+    const parts = Object.fromEntries(header.replace(/^AWS4-HMAC-SHA256\s+/i, '').split(/,\s*/).map((p) => { const at = p.indexOf('='); return [p.slice(0, at).trim(), p.slice(at + 1).trim()]; }));
+    if (!parts.Credential || !parts.SignedHeaders || !parts.Signature) return { ok: false, reason: 'malformed' };
+    credential = parts.Credential; signedHeaders = parts.SignedHeaders; signature = parts.Signature;
+    amzDate = request.headers.get('x-amz-date') ?? '';
+    const declared = request.headers.get('x-amz-content-sha256');
+    payloadHash = declared ?? sha256Hex(body ?? '');
+  } else if (presigned) {
+    credential = url.searchParams.get('X-Amz-Credential') ?? ''; signedHeaders = url.searchParams.get('X-Amz-SignedHeaders') ?? '';
+    signature = url.searchParams.get('X-Amz-Signature') ?? ''; amzDate = url.searchParams.get('X-Amz-Date') ?? '';
+    payloadHash = 'UNSIGNED-PAYLOAD';
+    const expires = Number(url.searchParams.get('X-Amz-Expires') ?? '');
+    if (!Number.isFinite(expires) || !/^\d{8}T\d{6}Z$/.test(amzDate)) return { ok: false, reason: 'malformed' };
+    if (now > dateOf(amzDate) + expires * 1000) return { ok: false, reason: 'expired' };
+  } else {
+    return { ok: false, reason: 'unsigned' };
+  }
+  const [keyId = '', dateStamp = '', region = '', service = '', terminal = ''] = credential.split('/');
+  if (!keyId || terminal !== 'aws4_request' || !/^\d{8}$/.test(dateStamp) || !/^\d{8}T\d{6}Z$/.test(amzDate)) return { ok: false, reason: 'malformed', ...(keyId ? { keyId } : {}) };
+  const secret = await secretOf(keyId);
+  if (secret === undefined) return { ok: false, reason: 'unknown_key', keyId };
+
+  // A canonical request binds the declared hash; the declaration must also describe the bytes received.
+  // S3's UNSIGNED-PAYLOAD and streaming markers are separate wire modes, not ordinary payload digests.
+  // https://docs.aws.amazon.com/AmazonS3/latest/developerguide/sig-v4-header-based-auth.html
+  const declaredPayload = request.headers.get('x-amz-content-sha256');
+  if (declaredPayload !== null && /^[0-9a-f]{64}$/i.test(declaredPayload)
+    && declaredPayload.toLowerCase() !== sha256Hex(body ?? '')) {
+    return { ok: false, reason: 'bad_signature', keyId };
+  }
+
+  const host = request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host;
+  const sentPath = request.headers.get(ORIGINAL_PATH_HEADER) ?? url.pathname;
+  const raw = sentPath === '' ? '/' : sentPath;
+  const canonicalUri = service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+  const canonicalQuery = [...url.searchParams.entries()]
+    .filter(([k]) => !(presigned && k === 'X-Amz-Signature'))
+    .map(([k, v]) => [rfc3986(k), rfc3986(v)] as const)
+    .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+  const names = signedHeaders.toLowerCase().split(';').filter(Boolean);
+  const value = (name: string): string => (name === 'host' ? host : (request.headers.get(name) ?? '')).trim().replace(/\s+/g, ' ');
+  const canonicalHeaders = names.map((n) => `${n}:${value(n)}\n`).join('');
+  const canonicalRequest = [request.method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, names.join(';'), payloadHash].join('\n');
+  const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+  let key: Buffer = hmac(`AWS4${secret}`, dateStamp);
+  for (const part of [region, service, 'aws4_request']) key = hmac(key, part);
+  const expected = hmac(key, stringToSign).toString('hex');
+  const given = Buffer.from(signature.toLowerCase(), 'utf8');
+  const want = Buffer.from(expected, 'utf8');
+  if (given.length !== want.length || !nodeCrypto.timingSafeEqual(given, want)) return { ok: false, reason: 'bad_signature', keyId };
+  return { ok: true, keyId, region, service };
+}
+
+/**
+ * The SigV4 headers a client adds (`authorization`, `x-amz-date`, and for S3 `x-amz-content-sha256`), signed over the
+ * request as it will be sent: its method, URL, the headers it carries (host, `x-amz-*` and the content type are signed)
+ * and its body, at `at`. What a walk sends as an AWS SDK sends it; the verifier above is its other side.
+ */
+export function signSigV4(input: { method: string; url: string; headers?: Record<string, string>; body?: string | Uint8Array; keyId: string; secret: string; region: string; service: string; at: Date }): Record<string, string> {
+  const url = new URL(input.url);
+  const amzDate = `${input.at.toISOString().slice(0, 19).replace(/[:-]/g, '')}Z`;
+  const dateStamp = amzDate.slice(0, 8);
+  const payloadHash = sha256Hex(input.body ?? '');
+  const raw = url.pathname === '' ? '/' : url.pathname;
+  const canonicalUri = input.service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+  const canonicalQuery = [...url.searchParams.entries()]
+    .map(([k, v]) => [rfc3986(k), rfc3986(v)] as const)
+    .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+  const added: Record<string, string> = { 'x-amz-date': amzDate, ...(input.service === 's3' ? { 'x-amz-content-sha256': payloadHash } : {}) };
+  const signable = new Map<string, string>([['host', url.host]]);
+  for (const [name, value] of Object.entries({ ...(input.headers ?? {}), ...added })) {
+    const n = name.toLowerCase();
+    if (n.startsWith('x-amz-') || n === 'content-type') signable.set(n, value.trim().replace(/\s+/g, ' '));
+  }
+  const names = [...signable.keys()].sort();
+  const canonicalRequest = [input.method.toUpperCase(), canonicalUri, canonicalQuery, names.map((n) => `${n}:${signable.get(n)!}\n`).join(''), names.join(';'), payloadHash].join('\n');
+  const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+  let key: Buffer = hmac(`AWS4${input.secret}`, dateStamp);
+  for (const part of [input.region, input.service, 'aws4_request']) key = hmac(key, part);
+  return { ...added, authorization: `AWS4-HMAC-SHA256 Credential=${input.keyId}/${scope}, SignedHeaders=${names.join(';')}, Signature=${hmac(key, stringToSign).toString('hex')}` };
+}
+
+/**
+ * A presigned URL signed again with a key: its date, expiry, region, service and signed headers are the URL's own
+ * (X-Amz-Date, X-Amz-Expires, X-Amz-Credential's scope, X-Amz-SignedHeaders, `host` when it names none), its key and
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it.
+ */
+export function presignSigV4(input: { method: string; url: string; keyId: string; secret: string; host?: string }): string {
+  const url = new URL(input.url);
+  const q = url.searchParams;
+  const [, dateStamp = '', region = '', service = ''] = (q.get('X-Amz-Credential') ?? '').split('/');
+  const amzDate = q.get('X-Amz-Date') ?? '';
+  q.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+  q.set('X-Amz-Credential', `${input.keyId}/${dateStamp}/${region}/${service}/aws4_request`);
+  if (!q.has('X-Amz-SignedHeaders')) q.set('X-Amz-SignedHeaders', 'host');
+  q.delete('X-Amz-Signature');
+  const raw = url.pathname === '' ? '/' : url.pathname;
+  const canonicalUri = service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+  const canonicalQuery = [...q.entries()]
+    .map(([k, v]) => [rfc3986(k), rfc3986(v)] as const)
+    .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+  const names = (q.get('X-Amz-SignedHeaders') ?? 'host').toLowerCase().split(';').filter(Boolean);
+  const canonicalHeaders = names.map((n) => `${n}:${n === 'host' ? (input.host ?? url.host) : ''}\n`).join('');
+  const canonicalRequest = [input.method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, names.join(';'), 'UNSIGNED-PAYLOAD'].join('\n');
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, `${dateStamp}/${region}/${service}/aws4_request`, sha256Hex(canonicalRequest)].join('\n');
+  let key: Buffer = hmac(`AWS4${input.secret}`, dateStamp);
+  for (const part of [region, service, 'aws4_request']) key = hmac(key, part);
+  q.set('X-Amz-Signature', hmac(key, stringToSign).toString('hex'));
+  return url.toString();
+}

package/src/smtp.ts

@@ -0,0 +1,76 @@
+// A vendor's mail to a person, sent over SMTP (plain, no authentication) to the host the vendor's settings name — in a
+// World, the World's mail twin — as the vendor's own mailer sends it (GoTrue's confirmation and magic links). A handler
+// reaches it as `ctx.mail`. The World's egress rule is applied before the socket opens: a sealed World or one with a
+// network policy refuses a host outside it; a local World with neither lets a configured outside host be reached, as it
+// lets the application reach one. The socket is opened only when a mail is sent (nothing at import).
+
+/** Where a mail goes: the SMTP host and port, and the sender. */
+export type SmtpRoute = { host: string; port: number; from: string; senderName?: string };
+/** One mail: its recipient, subject and HTML body. */
+export type Mail = { to: string; subject: string; html: string };
+
+type Socket = import('node:net').Socket;
+
+class SmtpSession {
+  private buffer = '';
+  private waiting: Array<(line: string) => void> = [];
+  constructor(private readonly socket: Socket) {
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk: string) => {
+      this.buffer += chunk;
+      let end: number;
+      // a reply is complete at a line whose code is followed by a space (multi-line replies use a dash)
+      while ((end = this.buffer.search(/^\d{3} .*\r?\n/m)) >= 0) {
+        const lineEnd = this.buffer.indexOf('\n', end);
+        const reply = this.buffer.slice(0, lineEnd + 1);
+        this.buffer = this.buffer.slice(lineEnd + 1);
+        this.waiting.shift()?.(reply.trim().split(/\r?\n/).pop()!);
+      }
+    });
+  }
+  reply(): Promise<string> { return new Promise((resolve) => this.waiting.push(resolve)); }
+  async command(line: string, expect: number): Promise<void> {
+    const next = this.reply();
+    this.socket.write(`${line}\r\n`);
+    const reply = await next;
+    if (!reply.startsWith(String(expect))) throw new Error(`SMTP ${line.split(' ')[0]}: ${reply}`);
+  }
+}
+
+/** How long a mail may take, connect to QUIT (a host that never answers must not hold the request open). */
+const SMTP_TIMEOUT_MS = 10_000;
+
+/** Send one mail. Throws when it cannot be delivered (refused by the World's egress rule, unreachable, or refused by the
+ *  server), so the vendor answers its own mailer failure. */
+export async function sendMail(route: SmtpRoute, mail: Mail, headers: Record<string, string> = {}): Promise<void> {
+  const [{ connect }, { worldEgressRefusal }] = await Promise.all([
+    import('node:net'),
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => string | null }>,
+  ]);
+  const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`);
+  if (refusal !== null) throw new Error(refusal);
+  const socket = connect(route.port, route.host);
+  socket.setTimeout(SMTP_TIMEOUT_MS, () => socket.destroy(new Error(`SMTP ${route.host}:${route.port}: no answer in ${SMTP_TIMEOUT_MS} ms`)));
+  const session = new SmtpSession(socket);
+  const greeting = session.reply();
+  const failed = new Promise<never>((_, reject) => { socket.once('error', reject); socket.once('close', () => reject(new Error('SMTP connection closed'))); });
+  failed.catch(() => {});
+  const step = <T>(p: Promise<T>): Promise<T> => Promise.race([p, failed]);
+  await step(new Promise<void>((resolve) => { socket.once('connect', () => resolve()); }));
+  try {
+    if (!(await step(greeting)).startsWith('220')) throw new Error('SMTP: no greeting');
+    await step(session.command(`EHLO ${route.from.split('@')[1] ?? 'localhost'}`, 250));
+    await step(session.command(`MAIL FROM:<${route.from}>`, 250));
+    await step(session.command(`RCPT TO:<${mail.to}>`, 250));
+    await step(session.command('DATA', 354));
+    const from = route.senderName ? `"${route.senderName.replace(/"/g, '')}" <${route.from}>` : route.from;
+    const lines = [
+      `From: ${from}`, `To: ${mail.to}`, `Subject: ${mail.subject}`, 'MIME-Version: 1.0', 'Content-Type: text/html; charset=utf-8',
+      ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`), '', ...mail.html.split(/\r?\n/).map((l) => (l.startsWith('.') ? `.${l}` : l)),
+    ];
+    await step(session.command(`${lines.join('\r\n')}\r\n.`, 250));
+    await step(session.command('QUIT', 221)).catch(() => {});
+  } finally {
+    socket.destroy();
+  }
+}

package/src/sockets.ts

@@ -0,0 +1,140 @@
+// A vendor's persistent wire (architecture, "Other wires: sockets"): a WebSocket its clients hold open, on which the
+// vendor sends what happens as it happens (Discord's Gateway: a bot identifies, is told the guilds it is in, and is sent
+// each message, member and interaction as it lands). The manifest declares the socket (`sockets`); the pack's engine
+// (`semantics/sockets.ts`, one export per socket id) speaks its protocol: what a session is sent when it opens, what it
+// answers each frame, and which frames a write of the World sends it. The kernel holds the open sessions, serves the
+// upgrade through the serve seam, and offers every write to every open session of the vendor, after the write's
+// webhooks. A session's own counters (a sequence number, a heartbeat) are the connection's, never the World's state.
+// Nothing here runs at module scope beyond the empty registry.
+import type { EventWrite } from './events.ts';
+import type { ScenarioEngine } from './scenario.ts';
+import type { WebSocketPeer, WebSocketUpgrade } from './serve-http.ts';
+
+/** A socket the vendor serves: its path (and host, when the vendor serves it on a host of its own), as the manifest
+ *  declares it. */
+/** A vendor's socket: its id, path and host; `protocols` are the subprotocols its server selects from those a client
+ *  offers in `Sec-WebSocket-Protocol` (OpenAI Realtime's `realtime`), the first offered that it lists. */
+export type SocketDecl = { id: string; path: string; host?: string; note: string; source?: string; protocols?: ReadonlyArray<string> };
+
+/** One open connection, as its engine sees it: its own state, and the frames it sends (an object is sent as JSON). */
+export type SocketSession = {
+  readonly id: number;
+  readonly socket: string;
+  state: Record<string, unknown>;
+  send(frame: unknown): void;
+  close(code?: number, reason?: string): void;
+  /** A reply this session will send, by its correlation key: settles when the engine calls `fulfil(key, value)`, and
+   *  rejects when `ms` pass or the session closes (a request answered by a session: the tunnel's relay). */
+  expect(key: string, ms: number): Promise<unknown>;
+  /** Settles what `expect(key)` awaits; false when nothing awaits it (a late or unknown reply). */
+  fulfil(key: string, value: unknown): boolean;
+  /** The World's scenario's decision for a turn this session asks (a model vendor's turn spoken over a socket: a voice
+   *  agent's reply), the turn given as the pack's scenario adapter reads a request; undefined when the pack has no
+   *  scenario or the World carries none. A fault decision is the engine's to answer in its own frames. */
+  decide(asked: unknown): Promise<ScenarioServed | undefined>;
+};
+
+/** What the World's scenario serves a turn: a handler's decision, a miss, or a fault (scenario.ts `serve`). */
+export type ScenarioServed = Awaited<ReturnType<ScenarioEngine<unknown>['serve']>>;
+
+/** A socket's protocol, over the handler contract's context (a read of the World as the request that opened it). */
+export type SocketEngine<C> = {
+  open?(session: SocketSession, ctx: C): void | Promise<void>;
+  message(session: SocketSession, data: string, ctx: C): void | Promise<void>;
+  /** A write of the World: the frames it sends this session, if any (the engine decides who is told what). */
+  write?(session: SocketSession, write: EventWrite, ctx: C): void | Promise<void>;
+  /** The session ended (the client hung up, or the engine closed it): the World is read and written as at a frame, so
+   *  what the end settles is written (a call's final status). */
+  close?(session: SocketSession, ctx: C): void | Promise<void>;
+};
+
+type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }> };
+const sessions = new Map<string, Set<Open>>();
+let nextSession = 1;
+const keyOf = (service: string, root: string | undefined): string => `${service}\0${root ?? ''}`;
+
+/** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
+export function openSessions(service: string, root: string | undefined, socket: string): SocketSession[] {
+  return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket).map((o) => o.session);
+}
+
+/** Offer a write to every open session of the vendor, each in its turn after what it is already doing. Queued, never
+ *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
+export function socketWrite(service: string, root: string | undefined, write: EventWrite): void {
+  const open = sessions.get(keyOf(service, root));
+  if (!open?.size) return;
+  for (const o of open) {
+    const { engine } = o;
+    if (!engine.write) continue;
+    o.queue = o.queue.then(async () => engine.write!(o.session, write, await o.context())).catch((error) => o.session.close(1011, String((error as Error).message ?? error).slice(0, 120)));
+  }
+}
+
+/** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
+export function socketUpgrade<C>(
+  service: string,
+  root: string | undefined,
+  decls: ReadonlyArray<SocketDecl>,
+  engines: Record<string, SocketEngine<C>>,
+  context: (request: Request, decl: SocketDecl) => Promise<C>,
+  hostOf: (request: Request) => string,
+  pathOf: (request: Request) => string = (request) => new URL(request.url).pathname,
+  decide: (asked: unknown) => Promise<ScenarioServed | undefined> = async () => undefined,
+): WebSocketUpgrade {
+  const declFor = (request: Request): SocketDecl | undefined => decls.find((d) => {
+    const path = pathOf(request).replace(/\/+$/, '') || '/';
+    return (d.path.replace(/\/+$/, '') || '/') === path && (!d.host || d.host.toLowerCase() === hostOf(request)) && engines[d.id] !== undefined;
+  });
+  const byPeer = new WeakMap<WebSocketPeer, Open>();
+  const key = keyOf(service, root);
+  return {
+    accepts: (request) => declFor(request) !== undefined,
+    // the subprotocol the server answers with: the first the client offers that the socket declares, or, for a socket
+    // that declares none, the first offered (what the ws library and Bun answer by themselves)
+    protocol: (request) => {
+      const offered = (request.headers.get('sec-websocket-protocol') ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+      const declared = declFor(request)?.protocols;
+      return declared ? offered.find((p) => declared.includes(p)) : offered[0];
+    },
+    open: (peer, request) => {
+      const decl = declFor(request)!;
+      const engine = engines[decl.id]! as SocketEngine<unknown>;
+      const pending: Open['pending'] = new Map();
+      const session: SocketSession = {
+        id: nextSession++, socket: decl.id, state: {},
+        send: (frame) => { peer.send(typeof frame === 'string' || frame instanceof Uint8Array ? frame : JSON.stringify(frame)); },
+        close: (code, reason) => { peer.close(code, reason); },
+        expect: (key, ms) => new Promise((resolve, reject) => {
+          const timer = setTimeout(() => { pending.delete(key); reject(new Error('no reply in time')); }, ms);
+          pending.set(key, { resolve, reject, timer });
+        }),
+        fulfil: (key, value) => {
+          const p = pending.get(key);
+          if (!p) return false;
+          clearTimeout(p.timer); pending.delete(key); p.resolve(value);
+          return true;
+        },
+        decide,
+      };
+      const o: Open = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+      byPeer.set(peer, o);
+      (sessions.get(key) ?? sessions.set(key, new Set()).get(key)!).add(o);
+      if (engine.open) o.queue = o.queue.then(async () => engine.open!(session, await o.context())).catch((error) => session.close(1011, String((error as Error).message ?? error).slice(0, 120)));
+    },
+    message: (peer, data) => {
+      const o = byPeer.get(peer);
+      if (!o) return;
+      const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+      o.queue = o.queue.then(async () => o.engine.message(o.session, text, await o.context())).catch((error) => o.session.close(1011, String((error as Error).message ?? error).slice(0, 120)));
+    },
+    close: (peer) => {
+      const o = byPeer.get(peer);
+      if (!o) return;
+      sessions.get(key)?.delete(o);
+      // what awaited this session's replies is told it closed
+      for (const [k, p] of o.pending) { clearTimeout(p.timer); p.reject(new Error('the session closed')); o.pending.delete(k); }
+      // the end is written after what the session is still doing, over its own context
+      if (o.engine.close) o.queue = o.queue.then(async () => o.engine.close!(o.session, await o.context())).catch(() => {});
+    },
+  };
+}

package/src/state-system.ts

@@ -9,7 +9,7 @@
 //               from the vendor (the pack's refresh adapter). Reads never egress.
 // The binding is a file in the twin's state dir (`root.json`), written by `volter twin <vendor>
 // root`, read here — no env var, no pack code. The adapters come from the pack's descriptor
-// (protocol 2 `stateSystem`) or its anchored exports, registered by whoever mounts the twin.
+// (`stateSystem`), registered by whoever mounts the twin.
 // CHECKS run before any entry is performed: a check that fails lands the entry as `refused` with
 // its reason and the deploy stops there. Checks are the world's files; the runtime loads them.
 import { dirname, join } from 'node:path';
@@ -58,7 +58,7 @@ export function clearRoot(service: string, root?: string): void {
  *  writes a root log by hand); `ingest` folds one signed webhook. All over the kernel executor. */
 export type StateSystemAdapters = {
   perform?: PerformAction;
-  refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string }) => Promise<unknown>;
+  refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string; scope?: string }) => Promise<unknown>;
   ingest?: (request: Request, ctx: { root?: string; secret?: string }) => Response | Promise<Response>;
 };