@volter/world-core 3.0.161 → 3.0.162

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,12 @@ 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 } };
   /** 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`

package/src/sockets.ts

@@ -1,3 +1,4 @@
+import { runWithStorageTenant, storageTenant } from './request-scope.ts';
 // 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
@@ -49,7 +50,7 @@ export type SocketEngine<C> = {
   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>; due: number }> };
+type Open = { tenant?: string; run: <T>(fn: () => T) => T; 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>; due: number }> };
 const sessions = new Map<string, Set<Open>>();
 /** A World's next session number, per World (its service and root): a session's id is the World's, never the
  *  process's, so a life replayed on a fresh World numbers its sessions as it did the first time. */
@@ -58,7 +59,7 @@ const keyOf = (service: string, root: string | undefined): string => `${service}
 
 /** 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);
+  return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket && o.tenant === storageTenant(service)).map((o) => o.session);
 }
 
 /** What a session awaits that the World's clock has run out (a life's `wait` past a relay's timeout), rejected as the
@@ -77,8 +78,9 @@ export function socketWrite(service: string, root: string | undefined, write: Ev
   if (!open?.size) return;
   for (const o of open) {
     const { engine } = o;
+    if (o.tenant !== storageTenant(service)) continue;
     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)));
+    o.queue = o.queue.then(() => o.run(async () => engine.write!(o.session, write, await o.context()))).catch((error) => o.session.close(1011, String((error as Error).message ?? error).slice(0, 120)));
   }
 }
 
@@ -105,8 +107,8 @@ export function socketUpgrade<C>(
   engines: Record<string, SocketEngine<C>>,
   context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>,
   hostOf: (request: Request) => string,
-  pathOf: (request: Request) => string = (request) => new URL(request.url).pathname,
-  decide: (asked: unknown) => Promise<ScenarioServed | undefined> = async () => undefined,
+  pathOf: (request: Request) => string,
+  decide: (asked: unknown) => Promise<ScenarioServed | undefined>,
 ): WebSocketUpgrade {
   const matchFor = (request: Request): { decl: SocketDecl; params: Record<string, string> } | undefined => {
     const path = pathOf(request).replace(/\/+$/, '') || '/';
@@ -149,16 +151,17 @@ export function socketUpgrade<C>(
         },
         decide,
       };
-      const o: Open = { session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };
+      const tenant = storageTenant(service), run = <T>(fn: () => T): T => runWithStorageTenant(service, tenant, fn);
+      const o: Open = { tenant, run, session, engine, context: () => context(request.clone(), decl, params), 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)));
+      if (engine.open) o.queue = o.queue.then(() => o.run(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)));
+      o.queue = o.queue.then(() => o.run(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);
@@ -168,7 +171,7 @@ export function socketUpgrade<C>(
       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
       // the session is gone, so a failure has no frame to go in: it is reported, never swallowed
-      if (o.engine.close) o.queue = o.queue.then(async () => o.engine.close!(o.session, await o.context())).catch((error) => {
+      if (o.engine.close) o.queue = o.queue.then(() => o.run(async () => o.engine.close!(o.session, await o.context()))).catch((error) => {
         console.error(`${service}: the ${o.session.socket} socket's end was not written: ${String((error as Error)?.message ?? error)}`);
       });
     },

package/src/world-account-name.ts

@@ -0,0 +1,4 @@
+/** The retained World-account name grammar, shared by registration and read-only authority selection. */
+export function isWorldAccountName(value: unknown): value is string {
+  return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
+}