@volter/world-core 3.0.161 → 3.0.163

package/src/index.ts

@@ -63,8 +63,8 @@ export { assetContentType, packAsset } from './pack-assets.ts';
 export { bytesResponse, contentTypeOf, fileResponse } from './file-response.ts';
 
 // ── the kernel's deterministic helpers ─────────────────────────────────────────────────────────
-export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, base62From, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.ts';
-export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, base62From, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.ts';
+export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.ts';
 export { blobDigest } from './blob-store.ts';
 // compressed bytes a wire carries (a SARIF upload), over web streams
 export { gunzip, gzip } from './bytes.ts';
@@ -109,3 +109,6 @@ export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowser
 
 export * as managedOriginalInputs from './managed-original-inputs.ts';
 export * as managedGoPrograms from './managed-go-programs.ts';
+
+export { worldSecret, worldAccount } from './derived-core.ts';
+export { isWorldAccountName } from './world-account-name.ts';

package/src/machines.ts

@@ -3,14 +3,12 @@
 // `POST /_twin/machine-pool`, recorded in the pack's own tree; a handler reaches it as `ctx.machines`. `docker` runs
 // each machine as a local container with its internal ports published on loopback; `none` runs nothing; `fake`
 // records what it was asked (capability verification). Nothing here runs at module scope, and `node:child_process`
-// is reached only when a compute pool is asked to act. The light pool delegates to the host's Substrate adapter.
+// is reached only when a compute pool is asked to act.
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { nodeBuiltin } from './serve-http.ts';
 import { refuseRequiredMachineTransport } from '../required-credential-transport.cjs';
 
 export type MachineSpec = { name: string; image: string; env?: Record<string, string>; ports?: number[]; command?: string[]; checks?: Array<{ port: number; type: 'http' | 'tcp'; path?: string }>; resetOnStop?: boolean; mounts?: Array<{ name: string; path: string }>; signal?: AbortSignal; startTimeoutMs?: number };
-export type GuestImage = { context: string; dockerfile?: string; runtime?: 'node' | 'bun' | 'python' | 'deno'; command?: string[]; cwd?: string; env?: Record<string, string>; prepared?: boolean };
-export type LightPoolOptions = { images?: Record<string, GuestImage> };
 export type MachineRun = { ports: Array<{ internal: number; host: number; url?: string }> };
 export type MachineStatus = { state: 'started' | 'paused' | 'stopped' | 'exited' | 'failed'; exitCode?: number; reason?: string };
 export type MachineFileStat = { type: 'file' | 'directory'; size: number; mode: number; mtime: string };
@@ -27,7 +25,7 @@ export type MachineProcess = { pid: number; events: AsyncIterable<{ stdout?: str
 export type ExecSpec = { args: string[]; env?: Record<string, string>; cwd?: string };
 export type MachineHttpReply = { port: number; method: string; path: string; requestText?: string; status: number; headers?: Record<string, string>; body?: string };
 export type MachinePool = {
-  readonly kind: 'docker' | 'none' | 'fake' | 'light';
+  readonly kind: 'docker' | 'none' | 'fake';
   /** Optional capability admission, before vendor resource creation; starts no process. */
   admitRun?(spec: MachineSpec): Promise<void>;
   /** runs the image; a failure (no container runtime, an image that will not start) rejects with the runtime's message */
@@ -51,33 +49,7 @@ export function isMachineCapabilityGap(error: unknown): boolean {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === 'WORLD_MACHINE_CAPABILITY_GAP';
 }
 export const MACHINE_POOL = '_machine_pool';
-export const POOL_KINDS = ['docker', 'none', 'fake', 'light'] as const;
-
-/** The host owns provider bootstrapping. Browser/kernel imports stay inert, and a missing
- * host provider refuses rather than falling back to metadata-only success. */
-function lightPool(world: string, root: string | undefined, options: LightPoolOptions): MachinePool {
-  let ready: Promise<MachinePool> | undefined;
-  const load = (): Promise<MachinePool> => ready ??= (async () => {
-    const entry = typeof process === 'undefined' ? undefined : process.env.VOLTER_WORLD_GUEST_RUNNER;
-    if (!entry) throw new Error('light guest runner is unavailable: run this twin inside a World');
-    const provider = await import(entry);
-    return provider.createLightGuestPool({ world, root, ...options }) as MachinePool;
-  })();
-  return {
-    kind: 'light',
-    admitRun: async (spec) => { await (await load()).admitRun?.(spec); },
-    run: async (spec) => (await load()).run(spec),
-    exec: async (name, spec) => (await load()).exec(name, spec),
-    request: async (name, port, request) => (await load()).request(name, port, request),
-    status: async (name) => (await load()).status(name),
-    ports: async (name) => (await load()).ports(name),
-    files: async (name) => (await load()).files(name),
-    pause: async (name) => (await load()).pause(name),
-    resume: async (name) => (await load()).resume(name),
-    stop: async (name) => (await load()).stop(name),
-    remove: async (name) => (await load()).remove(name),
-  };
-}
+export const POOL_KINDS = ['docker', 'none', 'fake'] as const;
 
 /** A container's name for a machine: the World's prefix, the World's own mark (a machine id repeats across Worlds and
  *  branches, which mint alike), then the vendor's machine name made safe for docker. */
@@ -100,8 +72,8 @@ function dockerPool(world: string): MachinePool {
       const state = JSON.parse(await docker(['inspect', '--format', '{{json .State}}', containerName(world, name)]));
       return state.Running ? { state: 'started' } : { state: 'exited', exitCode: state.ExitCode, ...(state.Error ? { reason: state.Error } : {}) };
     },
-    async ports() { throw new Error('port discovery requires the light guest backing'); },
-    async files() { throw new Error('file access requires the light guest backing'); },
+    async ports() { throw new Error('port discovery is unavailable'); },
+    async files() { throw new Error('file access is unavailable'); },
     async run(spec) {
       refuseRequiredMachineTransport(process.env, 'Docker machine application transport');
       const name = containerName(world, spec.name);
@@ -187,8 +159,8 @@ function dockerPool(world: string): MachinePool {
 }
 
 /** The pool of a kind, for a World (`world`: the mark its containers carry). */
-export function machinePool(kind: MachinePool['kind'], world = 'world', httpReplies: readonly MachineHttpReply[] = [], light: LightPoolOptions = {}, root?: string): MachinePool {
-  if (kind === 'light') return lightPool(world, root, light);
+export function machinePool(kind: MachinePool['kind'], world = 'world', httpReplies: readonly MachineHttpReply[] = []): MachinePool {
+  if (!POOL_KINDS.includes(kind)) throw new Error(`kind must be one of ${POOL_KINDS.join(', ')}`);
   if (kind === 'docker') return dockerPool(world);
   if (kind === 'fake') {
     const asked: NonNullable<MachinePool['asked']> = [];
@@ -237,14 +209,14 @@ export function machinePool(kind: MachinePool['kind'], world = 'world', httpRepl
 
 /** A vendor's pool in a World, one per World and kind for the life of the process (a fake pool keeps what it was asked). */
 const pools = new Map<string, MachinePool>();
-export function poolFor(service: string, root: string | undefined, kind: MachinePool['kind'], httpReplies: readonly MachineHttpReply[] = [], light: LightPoolOptions = {}): MachinePool {
-  const key = `${service}\0${root ?? ''}\0${kind}${kind === 'light' ? JSON.stringify(light) : ''}`;
+export function poolFor(service: string, root: string | undefined, kind: MachinePool['kind'], httpReplies: readonly MachineHttpReply[] = []): MachinePool {
+  const key = `${service}\0${root ?? ''}\0${kind}`;
   let pool = pools.get(key);
   if (!pool) {
     // the World's mark: a short digest of the vendor and the World's tree, so two Worlds' machines never share a name
     let h = 0;
     for (const ch of `${service}:${root ?? ''}`) h = (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0;
-    pool = machinePool(kind, h.toString(16).padStart(8, '0'), httpReplies, light, root);
+    pool = machinePool(kind, h.toString(16).padStart(8, '0'), httpReplies);
     pools.set(key, pool);
   }
   return pool;

package/src/pack-fetch.ts

@@ -1,3 +1,4 @@
+import { runWithStorageTenant } from './request-scope.ts';
 import { parseExactJson } from './exact-json.ts';
 import { redisServiceTimes } from './redis/service-times.ts';
 import { readHostPort } from './host-port.ts';
@@ -502,7 +503,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     redisServiceTimes.lap('2 content and lane routes, decoding, routing');
     if (request.method === 'GET' && path === '/twin' && m.discovery) {
       const d = m.discovery;
-      const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
+      const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: docker | none | fake }.' }] : [])];
       // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
       const laneDiscovery = await laneDoor(request, '/twin');
       const resources: Record<string, { relations: Array<{ field: string; to: string }> }> = {};
@@ -546,7 +547,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
         try { enrollment = parseExactJson(await request.clone().text()); } catch {}
         const kind = enrollment.kind;
         if (!POOL_KINDS.includes(kind as never)) return Response.json({ message: `kind must be one of ${POOL_KINDS.join(', ')}` }, { status: 400 });
-        await applyTwinWrite(m.service, { operation: 'machine_pool.enroll', subjectType: MACHINE_POOL, subjectId: 'pool', fields: { kind, ...(kind === 'fake' && Array.isArray(enrollment.httpReplies) ? { httpReplies: enrollment.httpReplies } : {}), ...(kind === 'light' ? { images: enrollment.images ?? {} } : {}) }, occurredAt: (await open(request, 'machine-pool', 'POST', '/_twin/machine-pool', {})).occurredAt, actor: { kind: 'system' } }, options.root);
+        await applyTwinWrite(m.service, { operation: 'machine_pool.enroll', subjectType: MACHINE_POOL, subjectId: 'pool', fields: { kind, ...(kind === 'fake' && Array.isArray(enrollment.httpReplies) ? { httpReplies: enrollment.httpReplies } : {}) }, occurredAt: (await open(request, 'machine-pool', 'POST', '/_twin/machine-pool', {})).occurredAt, actor: { kind: 'system' } }, options.root);
         if (kind === 'fake') resetFakePool(m.service, options.root);
         return Response.json({ kind }, { status: 201 });
       }
@@ -656,7 +657,16 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   };
   const cors = m.cors ? withCors(m.cors, labelled) : labelled;
   // at a World's place every cookie the twin sets is kept to the twin's base path (twin-fetch.ts, placedCookies)
-  const served = async (request: Request): Promise<Response> => placedCookies(request, await cors(request));
+  const selectedAccount = async (request: Request): Promise<string | undefined> => {
+    if (m.tenant?.storage !== 'namespaced' || !parts.tenant) return undefined;
+    const authority = routed(request.clone()), path = new URL(authority.url).pathname;
+    return runWithStorageTenant(m.service, undefined, async () => (await parts.tenant!(await open(authority, 'account-authority', request.method, path, {}))) ?? '__unselected__');
+  };
+  const served = async (request: Request): Promise<Response> => {
+    const path = new URL(routed(request.clone()).url).pathname;
+    if (m.tenant?.storage !== 'namespaced' || !parts.tenant || path === '/twin' || path.startsWith('/twin/')) return placedCookies(request, await cors(request));
+    return runWithStorageTenant(m.service, await selectedAccount(request), async () => placedCookies(request, await cors(request)));
+  };
   // which paths this pack's API serves, for a vendor's lane router that asks (unlessOnlyRoot)
   const serves = (method: string, path: string): boolean => Boolean(matchOperation(routes, method, path));
   // the vendor's sockets: a request to a declared socket's path opens a session of its engine, over a context of the
@@ -666,7 +676,19 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     (request, d, params) => open(request, `socket:${d.id}`, 'GET', d.path, params), hostOf, (request) => new URL(routed(request).url).pathname,
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
     async (asked) => engineOf()?.serve(asked)) : undefined;
-  const upgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
+  const rawUpgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
+  const opening = new WeakMap<WebSocketPeer, Promise<void>>();
+  const upgrade: WebSocketUpgrade | undefined = rawUpgrade && m.tenant?.storage === 'namespaced' && parts.tenant ? {
+    accepts: request => rawUpgrade.accepts(request),
+    protocol: request => rawUpgrade.protocol?.(request),
+    open(peer, request) {
+      const ready = selectedAccount(request).then(account => runWithStorageTenant(m.service, account, () => rawUpgrade.open(peer, request)));
+      opening.set(peer, ready);
+      void ready.catch(error => peer.close(1011, String(error instanceof Error ? error.message : error).slice(0, 120)));
+    },
+    async message(peer, data) { await opening.get(peer); return rawUpgrade.message(peer, data); },
+    close(peer) { const ready = opening.get(peer); opening.delete(peer); void ready?.then(() => rawUpgrade.close(peer), () => undefined); },
+  } : rawUpgrade;
   // the broadcasts the vendor takes over RTMP: a publisher's connection, its publish ruled by the pack's dialect over a
   // context of its own (operation `live:<id>`), its recording kept as the World's bookkeeping and blobs (live/ingest.ts)
   const ownIngest = m.live?.length ? liveIngest<HandlerContext>({
@@ -692,7 +714,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     ...lanesOwners(parts.lanes ?? {}),
   });
   const owners = (): Record<string, DerivedOwner> => flatOwners(ownersByUnit());
-  return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock, workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}), ...(ingest ? { ingest } : {}) }), options.readOnly);
+  return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock: async (request: Request) => runWithStorageTenant(m.service, await selectedAccount(request), () => advanceClock(request)), workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}), ...(ingest ? { ingest } : {}) }), options.readOnly);
 }
 
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first

package/src/packRegistry.ts

@@ -221,12 +221,18 @@ export type TwinPack = {
    *  answer: `init` writes `$issue:<service>` for each, and `up`, once this twin is running, POSTs the body to the door
    *  and sets each name to its field (`file:<field>` materializes one file; `directory:<field>` a relative-file map). A twin that holds its keys (refusing any it
    *  did not issue) declares one, so a World's applications hold keys it issued rather than fixtures it refuses. */
-  credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
+  credentialDoor?: {
+    path: string;
+    body: Record<string, unknown>;
+    fill: Record<string, string>;
+    account?: { field: string } & ({ tenancy?: never; source?: never } | { tenancy: string; source: string });
+    deployment?: { field: string; object: string; source: string; organizationOutputs?: string[] };
+  };
   /** Another pack of this vendor issues the API's credentials; architecture, descriptor World wiring. */
   credentialIssuer?: string;
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };
   managedService?: { kind: string; scheme: string; note: string; configurationArg?: '--configuration'; originalInputs?: { version: 1; manifestArg: '--original-inputs'; rootArg: '--original-root'; digestArg: '--original-inputs-sha256'; paths: string[] } };
-  managedDatabase?: { kind: 'postgres'; arg: string; note: string };
+  managedDatabase?: { kind: 'postgres'; arg: string; user: string; database: string; clock: 'wall'; credentialField: string; note: string };
   sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; scheme?: string; note: string }>;
   stateSystem?: StateSystemAdapters;
   /** The pack has no vendor-backed half, and why (copied from the manifest by packOf). */

package/src/protobuf.ts

@@ -17,7 +17,6 @@ export type ProtoSchema = {
 const VARINT = new Set(['int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'bool']);
 const FIXED64 = new Set(['fixed64', 'sfixed64', 'double']);
 const FIXED32 = new Set(['fixed32', 'sfixed32', 'float']);
-const LONG = new Set(['int64', 'uint64', 'sint64', 'fixed64', 'sfixed64']);
 const WRAPPERS: Record<string, string> = {
   'google.protobuf.DoubleValue': 'double', 'google.protobuf.FloatValue': 'float', 'google.protobuf.Int64Value': 'int64',
   'google.protobuf.UInt64Value': 'uint64', 'google.protobuf.Int32Value': 'int32', 'google.protobuf.UInt32Value': 'uint32',
@@ -150,8 +149,21 @@ class Reader {
     const out = this.b.subarray(this.at, this.at + n); this.at += n; return out;
   }
   bytes(): Uint8Array { return this.take(Number(this.varint())); }
-  skip(wire: number): void {
+  skip(wire: number, number?: number): void {
     if (wire === 0) this.varint(); else if (wire === 1) this.take(8); else if (wire === 5) this.take(4); else if (wire === 2) this.bytes();
+    else if (wire === 3) {
+      while (!this.done) {
+        const tag = this.varint();
+        if (tag > 0xffffffffn || (tag >> 3n) === 0n) throw new Error('protobuf: invalid group field tag');
+        const field = Number(tag >> 3n), kind = Number(tag & 7n);
+        if (kind === 4) {
+          if (number !== undefined && field !== number) throw new Error('protobuf: mismatched group end');
+          return;
+        }
+        this.skip(kind, field);
+      }
+      throw new Error('protobuf: unterminated group');
+    }
     else throw new Error(`protobuf: wire type ${wire} is not supported`);
   }
 }
@@ -253,3 +265,28 @@ export function decodeMessage(schema: ProtoSchema, type: string, bytes: Uint8Arr
   }
   return wellKnownOut(type, out);
 }
+
+/** Rewrite selected length-delimited fields without decoding/re-encoding the rest of a message.
+ * Undefined keeps the original field bytes; null removes that occurrence. Nested rewrites use this same visitor.
+ * This is for transparent vendor fronts: unknown fields, ordering and untouched encodings survive unchanged. */
+export function rewriteProtobufFields(
+  bytes: Uint8Array,
+  fields: Readonly<Record<number, (value: Uint8Array) => Uint8Array | null | undefined>>,
+): Uint8Array {
+  const reader = new Reader(bytes), writer = new Writer();
+  while (!reader.done) {
+    const start = reader.at, tag = reader.varint();
+    if (tag > 0xffffffffn || (tag >> 3n) === 0n) throw new Error('protobuf: invalid field tag');
+    const number = Number(tag >> 3n), wire = Number(tag & 7n);
+    const rewrite = Object.hasOwn(fields, number) ? fields[number] : undefined;
+    if (wire === 2 && rewrite) {
+      const changed = rewrite(reader.bytes());
+      if (changed === undefined) writer.raw(bytes.subarray(start, reader.at));
+      else if (changed !== null) { writer.tag(number, wire); writer.bytes(changed); }
+    } else {
+      reader.skip(wire, number);
+      writer.raw(bytes.subarray(start, reader.at));
+    }
+  }
+  return writer.done();
+}

package/src/request-scope.ts

@@ -84,3 +84,12 @@ export function refuseReadOnlyWrite(service: string): void {
   writeScopeStore!.getStore()!.refusals.push(error);
   throw error;
 }
+
+/** Request-local service tenancy. Created lazily so imports remain inert. */
+let tenantStore: AsyncLocalStorage<ReadonlyMap<string, string | undefined>> | undefined;
+export function storageTenant(service: string): string | undefined { return tenantStore?.getStore()?.get(service); }
+export function runWithStorageTenant<T>(service: string, tenant: string | undefined, fn: () => T): T {
+  tenantStore ??= new AsyncLocalStorage<ReadonlyMap<string, string | undefined>>();
+  const scope = new Map(tenantStore.getStore()); scope.set(service, tenant);
+  return tenantStore.run(scope, fn);
+}

package/src/runtime.ts

@@ -21,8 +21,8 @@ export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.ts';
-export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
-export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
+export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
+export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.ts';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.ts';
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver, SeedCall } from './derived-core.ts';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
@@ -352,9 +352,14 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
 export { foldHistory } from './log.ts';
 export { volterHome } from './volter-home.ts';
-export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat, GuestImage, LightPoolOptions } from './machines.ts';
+export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat } from './machines.ts';
 
 
 export { boardFrameKey } from './board-keys.ts';
 
 export * as managedOriginalInputs from './managed-original-inputs.ts';
+
+export { worldSecret, worldAccount } from './derived-core.ts';
+
+export { rewriteProtobufFields } from './protobuf.ts';
+export { attachWebSocketRelay } from './serve-http.ts';

package/src/serve-http.ts

@@ -418,3 +418,114 @@ async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHo
     stop: (closeActive = true) => new Promise<void>((resolve) => { if (closeActive) { for (const controller of active) controller.abort(); for (const peer of socketServer?.clients ?? []) peer.terminate(); } socketServer?.close(); server.close(() => { if (closeActive && active.size) reportCleanup('forced stop left pending handler cleanup', `${active.size} request(s)`); resolve(); }); if (closeActive) server.closeAllConnections(); }),
   };
 }
+
+
+export type WebSocketRelay = {
+  url: string;
+  headers?: Record<string, string | string[] | undefined>;
+  outgoing?: (frame: string | Uint8Array) => string | Uint8Array | Promise<string | Uint8Array>;
+};
+
+/** Attach an authenticated native WebSocket relay to an existing Node front.
+ * The shared socket library owns handshake, fragmentation, masking, compression and control frames.
+ * Payload transforms are ordered; unknown vendor messages remain opaque bytes. */
+export async function attachWebSocketRelay(
+  server: import('node:http').Server,
+  route: (request: import('node:http').IncomingMessage) => WebSocketRelay | undefined,
+): Promise<{ stop: () => void }> {
+  const { WebSocket: Client, WebSocketServer } = await socketLibrary();
+  const routes = new WeakMap<import('node:http').IncomingMessage, import('ws').WebSocket>();
+  const pairs = new Set<{ upstream: import('ws').WebSocket; downstream?: import('ws').WebSocket }>();
+  const accepted = new WebSocketServer({ noServer: true, handleProtocols: (_offered, request) => routes.get(request)?.protocol || false });
+  let stopped = false;
+  const reject = (socket: import('node:stream').Duplex, status: number, message: string) => {
+    const body = new TextEncoder().encode(message);
+    socket.end('HTTP/1.1 ' + status + ' Rejected\r\nConnection: close\r\nContent-Type: text/plain\r\nContent-Length: ' + body.length + '\r\n\r\n' + message);
+  };
+  const upgrade = (request: import('node:http').IncomingMessage, socket: import('node:stream').Duplex, head: Buffer) => {
+    let selected: WebSocketRelay | undefined;
+    try { if (!stopped) selected = route(request); }
+    catch { reject(socket, 401, 'invalid authorization token'); return; }
+    if (!selected) { reject(socket, 404, 'WebSocket route is not served'); return; }
+    const headers = { ...selected.headers };
+    // Each hop has its own RFC6455 handshake; the library regenerates these headers.
+    for (const name of Object.keys(headers)) if (/^(host|connection|upgrade|sec-websocket-(key|version|extensions|protocol))$/i.test(name)) delete headers[name];
+    const protocols = String(request.headers['sec-websocket-protocol'] ?? '').split(',').map(value => value.trim()).filter(Boolean);
+    const upstream = new Client(selected.url, protocols, { headers });
+    const pair: { upstream: import('ws').WebSocket; downstream?: import('ws').WebSocket } = { upstream };
+    pairs.add(pair);
+    const pending: Array<string | Uint8Array> = [];
+    let queue = Promise.resolve(), closed = false;
+    const dispose = () => {
+      if (closed) return;
+      closed = true;
+      pairs.delete(pair);
+      upstream.terminate();
+      pair.downstream?.terminate();
+      socket.destroy();
+    };
+    const closeCode = (code: number): number => code === 1005 ? 1000 : code === 1006 ? 1011 : code;
+    const frameOf = (data: import('ws').RawData, binary: boolean): string | Uint8Array => {
+      const raw = Array.isArray(data) ? Buffer.concat(data) : data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+      return binary ? new Uint8Array(raw) : Buffer.from(raw).toString('utf8');
+    };
+    const send = (frame: string | Uint8Array) => {
+      queue = queue.then(async () => {
+        const output = await (selected!.outgoing?.(frame) ?? frame);
+        if (!closed && pair.downstream?.readyState === Client.OPEN) pair.downstream.send(output, { binary: typeof output !== 'string' });
+      }).catch(dispose);
+    };
+    upstream.on('message', (data, binary) => {
+      const frame = frameOf(data, binary);
+      if (!pair.downstream) pending.push(frame); else send(frame);
+    });
+    upstream.once('open', () => {
+      if (closed || stopped || socket.destroyed) { dispose(); return; }
+      routes.set(request, upstream);
+      accepted.handleUpgrade(request, socket, head, downstream => {
+        pair.downstream = downstream;
+        downstream.on('message', (data, binary) => {
+          const frame = frameOf(data, binary);
+          if (!closed && upstream.readyState === Client.OPEN) upstream.send(frame, { binary: typeof frame !== 'string' });
+        });
+        downstream.on('error', dispose);
+        downstream.once('close', (code, reason) => { if (!closed && upstream.readyState === Client.OPEN) upstream.close(closeCode(code), reason); });
+        for (const frame of pending.splice(0)) send(frame);
+      });
+    });
+    upstream.once('unexpected-response', (_request, response) => {
+      if (pair.downstream) { dispose(); return; }
+      const chunks: Uint8Array[] = [];
+      response.on('data', (chunk: Uint8Array) => chunks.push(chunk));
+      response.once('end', () => {
+        const body = Buffer.concat(chunks);
+        const carried = Object.entries(response.headers).filter(([name]) => !/^(connection|content-length|transfer-encoding)$/i.test(name))
+          .flatMap(([name, values]) => (Array.isArray(values) ? values : [values]).filter(value => value !== undefined).map(value => name + ': ' + value));
+        const header = Buffer.from(['HTTP/1.1 ' + (response.statusCode ?? 502) + ' ' + (response.statusMessage ?? 'Rejected'),
+          'Connection: close', 'Content-Length: ' + body.length, ...carried, '', ''].join('\r\n'));
+        socket.end(Buffer.concat([header, body]));
+        pairs.delete(pair);
+        closed = true;
+        upstream.terminate();
+      });
+      response.once('error', dispose);
+    });
+    upstream.on('error', dispose);
+    upstream.once('close', (code, reason) => {
+      if (pair.downstream && pair.downstream.readyState === Client.OPEN) pair.downstream.close(closeCode(code), reason);
+      else if (!pair.downstream) socket.destroy();
+      pairs.delete(pair);
+    });
+    socket.once('error', dispose);
+    socket.once('close', () => { if (!pair.downstream) dispose(); });
+  };
+  server.on('upgrade', upgrade);
+  return { stop: () => {
+    stopped = true;
+    server.off('upgrade', upgrade);
+    for (const pair of pairs) { pair.upstream.terminate(); pair.downstream?.terminate(); }
+    pairs.clear();
+    for (const peer of accepted.clients) peer.terminate();
+    accepted.close();
+  } };
+}

package/src/signing.ts

@@ -19,8 +19,11 @@ export type SigningKey = { alg: 'RS256' | 'RS384' | 'RS512' | 'EdDSA'; privatePe
 /** The algorithms `jwtSign` signs with. */
 export const SIGNING_ALGORITHMS: ReadonlyArray<SigningKey['alg']> = ['RS256', 'RS384', 'RS512', 'EdDSA', '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. */
+/** A token check's result, with its payload on success. `jwtVerify` checks time as well as the signature. */
 export type JwtVerdict = { valid: boolean; payload?: Row; reason?: 'malformed' | 'unexpected_alg' | 'no_matching_key' | 'bad_signature' | 'expired' | 'not_yet_valid' };
+export type JwtVerificationKey = Jwks | { alg: 'HS256' | 'HS384' | 'HS512'; secret: string };
+export type JwtDecodeOptions = { strict?: boolean; integers?: 'exact' | 'number' };
+export type JwtSignatureOptions = JwtDecodeOptions & { hmacSignature?: 'canonical' | 'bytes' };
 
 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');
@@ -35,6 +38,11 @@ export function keyId(publicPem: string, prefix = 'ins_'): string {
 /** 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. A token of a key pair carries the key's `kid`. */
 export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expiresInSeconds?: number; kidPrefix?: string; typ?: string }): string {
+  return jwtSignClaims({ iat: opts.now, exp: opts.now + (opts.expiresInSeconds ?? 60), nbf: opts.now, ...claims }, key, opts);
+}
+
+/** A JWT over exactly the supplied claims, without adding temporal claims. The caller owns their policy. */
+export function jwtSignClaims(claims: Row, key: SigningKey, opts: { kidPrefix?: string; typ?: string } = {}): string {
   // a key of another kind than its algorithm's is refused by name (an RSA key under EdDSA would fail inside the signer)
   if ('privatePem' in key) {
     const kind = nodeCrypto.createPrivateKey(key.privatePem).asymmetricKeyType;
@@ -44,8 +52,7 @@ export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expir
   const header = 'privatePem' in key
     ? { alg: key.alg, typ: opts.typ ?? 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
     : { alg: key.alg, typ: opts.typ ?? 'JWT' };
-  const payload = { iat: opts.now, exp: opts.now + (opts.expiresInSeconds ?? 60), nbf: opts.now, ...claims };
-  const input = `${jsonPart(header)}.${jsonPart(payload)}`;
+  const input = `${jsonPart(header)}.${jsonPart(claims)}`;
   if ('secret' in key) return `${input}.${base64url(nodeCrypto.createHmac(digestOf(key.alg), key.secret).update(input).digest())}`;
   if (key.alg === 'EdDSA') return `${input}.${base64url(nodeCrypto.sign(null, Buffer.from(input), key.privatePem))}`;
   const signer = nodeCrypto.createSign(`RSA-SHA${key.alg.slice(2)}`);
@@ -54,11 +61,14 @@ export function jwtSign(claims: Row, key: SigningKey, opts: { now: number; expir
   return `${input}.${base64url(signer.sign(key.privatePem))}`;
 }
 
-/** A JWT's header and payload, unverified. */
-export function jwtDecode(token: string): { header: Row; payload: Row } {
+/** A JWT's header and payload, unverified. Strict compact framing and ordinary JSON numbers are explicit
+ *  protocol policies; existing kernel callers retain permissive decoding and exact integer values. */
+export function jwtDecode(token: string, opts: JwtDecodeOptions = {}): { header: Row; payload: Row } {
+  if (opts.strict && typeof token !== 'string') throw new Error('malformed jwt');
   const parts = token.split('.');
-  if (parts.length !== 3) throw new Error('malformed jwt');
-  const part = (s: string): Row => parseExactJson(fromBase64url(s).toString('utf8')) as Row;
+  if (parts.length !== 3 || opts.strict && parts.some(part => !/^[A-Za-z0-9_-]+$/.test(part))) throw new Error('malformed jwt');
+  const parse = opts.integers === 'number' ? JSON.parse : parseExactJson;
+  const part = (s: string): Row => parse(fromBase64url(s).toString('utf8')) as Row;
   return { header: part(parts[0]!), payload: part(parts[1]!) };
 }
 
@@ -70,33 +80,43 @@ function timely(payload: Row, now: number): JwtVerdict {
 
 /** A token checked: an RS256 or EdDSA 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 {
+export function jwtVerify(token: string, key: JwtVerificationKey, opts: { now: number }): JwtVerdict {
+  const verdict = jwtVerifySignature(token, key);
+  return verdict.valid ? timely(verdict.payload!, opts.now) : verdict;
+}
+
+/** A token's signature checked without an `exp`/`nbf` policy. An issuer selector sees unverified claims and may
+ *  enforce its vendor's claim shape and key ownership before returning a key. HMAC signatures use canonical
+ *  text by default; a protocol that compares decoded bytes selects that existing wire policy explicitly. */
+export function jwtVerifySignature(token: string, key: JwtVerificationKey | ((decoded: { header: Row; payload: Row }) => JwtVerificationKey), opts: JwtSignatureOptions = {}): JwtVerdict {
   let decoded: { header: Row; payload: Row };
-  try { decoded = jwtDecode(token); } catch { return { valid: false, reason: 'malformed' }; }
+  try { decoded = jwtDecode(token, opts); } catch { return { valid: false, reason: 'malformed' }; }
+  const selected = typeof key === 'function' ? key(decoded) : key;
   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 ('secret' in selected) {
+    if (decoded.header.alg !== selected.alg) return { valid: false, reason: 'unexpected_alg' };
+    const bytes = nodeCrypto.createHmac(digestOf(selected.alg), selected.secret).update(`${h}.${p}`).digest();
+    const expected = opts.hmacSignature === 'bytes' ? bytes : Buffer.from(base64url(bytes), 'utf8');
+    const given = opts.hmacSignature === 'bytes' ? fromBase64url(s) : 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);
+    return { valid: true, payload: decoded.payload };
   }
   if (!['RS256', 'RS384', 'RS512', 'EdDSA'].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;
+  const jwk = decoded.header.kid !== undefined ? selected.keys.find((k) => k.kid === decoded.header.kid) : selected.keys.length === 1 ? selected.keys[0] : undefined;
   if (!jwk) return { valid: false, reason: 'no_matching_key' };
   if ((jwk.kty === 'OKP') !== (decoded.header.alg === 'EdDSA')) return { valid: false, reason: 'unexpected_alg' };
   if (jwk.kty === 'OKP') {
     const edKey = nodeCrypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' });
     if (!nodeCrypto.verify(null, Buffer.from(`${h}.${p}`), edKey, fromBase64url(s))) return { valid: false, reason: 'bad_signature' };
-    return timely(decoded.payload, opts.now);
+    return { valid: true, payload: decoded.payload };
   }
   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);
+  return { valid: true, payload: decoded.payload };
 }
 
 /** The JWKS that verifies every token a public key's pair signs. */
@@ -259,7 +279,7 @@ export function certificateOf(cert: string | Uint8Array): { der: Uint8Array; sub
 }
 
 /** What a handler signs and hashes with: `ctx.crypto`. */
-export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, base62From, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf } as const;
+export const handlerCrypto = { jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, base62From, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf } as const;
 export type HandlerCrypto = typeof handlerCrypto;
 
 /** A [KSUID](https://github.com/segmentio/ksuid) as 27 base62 characters (0-9A-Za-z, most significant first): `seconds`