@volter/world-core 3.0.160 → 3.0.162

package/dist/src/pack-fetch.js

@@ -1,3 +1,4 @@
+import { runWithStorageTenant } from "./request-scope.js";
 import { parseExactJson } from "./exact-json.js";
 import { redisServiceTimes } from "./redis/service-times.js";
 import { readHostPort } from "./host-port.js";
@@ -472,7 +473,7 @@ export function createPackFetch(parts, options = {}) {
         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 = {};
@@ -525,7 +526,7 @@ export function createPackFetch(parts, options = {}) {
                 const kind = enrollment.kind;
                 if (!POOL_KINDS.includes(kind))
                     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 });
@@ -657,7 +658,18 @@ export function createPackFetch(parts, options = {}) {
     };
     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) => placedCookies(request, await cors(request));
+    const selectedAccount = async (request) => {
+        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) => {
+        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, path) => 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
@@ -668,7 +680,19 @@ export function createPackFetch(parts, options = {}) {
     const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (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();
+    const upgrade = 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({
@@ -694,7 +718,7 @@ export function createPackFetch(parts, options = {}) {
         ...lanesOwners(parts.lanes ?? {}),
     });
     const owners = () => 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) => 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
  *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */

package/dist/src/packRegistry.d.ts

@@ -202,6 +202,9 @@ export type TwinPack = {
         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;
@@ -226,6 +229,10 @@ export type TwinPack = {
     managedDatabase?: {
         kind: 'postgres';
         arg: string;
+        user: string;
+        database: string;
+        clock: 'wall';
+        credentialField: string;
         note: string;
     };
     sidePorts?: Array<{

package/dist/src/protobuf.d.ts

@@ -26,3 +26,7 @@ export type ProtoSchema = {
 export declare function encodeMessage(schema: ProtoSchema, type: string, value: unknown): Uint8Array;
 /** A message's binary encoding as its JSON form (proto3 JSON; a field at its default is left out). */
 export declare function decodeMessage(schema: ProtoSchema, type: string, bytes: Uint8Array): unknown;
+/** 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 declare function rewriteProtobufFields(bytes: Uint8Array, fields: Readonly<Record<number, (value: Uint8Array) => Uint8Array | null | undefined>>): Uint8Array;

package/dist/src/protobuf.js

@@ -8,7 +8,6 @@
 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 = {
     'google.protobuf.DoubleValue': 'double', 'google.protobuf.FloatValue': 'float', 'google.protobuf.Int64Value': 'int64',
     'google.protobuf.UInt64Value': 'uint64', 'google.protobuf.Int32Value': 'int32', 'google.protobuf.UInt32Value': 'uint32',
@@ -208,7 +207,7 @@ class Reader {
         return out;
     }
     bytes() { return this.take(Number(this.varint())); }
-    skip(wire) {
+    skip(wire, number) {
         if (wire === 0)
             this.varint();
         else if (wire === 1)
@@ -217,6 +216,21 @@ class Reader {
             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`);
     }
@@ -336,3 +350,30 @@ export function decodeMessage(schema, type, bytes) {
     }
     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, fields) {
+    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/dist/src/request-scope.d.ts

@@ -28,3 +28,5 @@ export declare function writesRefused(): boolean;
 /** The write seam's check: throws (and records) the refusal when a write attempted here is a
  *  read-only request's. Called by every appender before it writes anything. */
 export declare function refuseReadOnlyWrite(service: string): void;
+export declare function storageTenant(service: string): string | undefined;
+export declare function runWithStorageTenant<T>(service: string, tenant: string | undefined, fn: () => T): T;

package/dist/src/request-scope.js

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

package/dist/src/runtime.d.ts

@@ -12,8 +12,8 @@ export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
 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.js';
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.js';
-export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';
-export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.js';
+export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';
+export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.js';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.js';
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver, SeedCall } from './derived-core.js';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.js';
@@ -86,6 +86,9 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';
 export { foldHistory } from './log.js';
 export { volterHome } from './volter-home.js';
-export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat, GuestImage, LightPoolOptions } from './machines.js';
+export type { MachinePool, MachineSpec, MachineProcess, MachineStatus, MachineFiles, MachineFileStat } from './machines.js';
 export { boardFrameKey } from './board-keys.js';
 export * as managedOriginalInputs from './managed-original-inputs.js';
+export { worldSecret, worldAccount } from './derived-core.js';
+export { rewriteProtobufFields } from './protobuf.js';
+export { attachWebSocketRelay } from './serve-http.js';

package/dist/src/runtime.js

@@ -18,7 +18,7 @@ export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispa
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
 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.js";
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from "./events.js";
-export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from "./signing.js";
+export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from "./signing.js";
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
 // routes every live vendor call through. The MECHANISM is here; the per-vendor ceiling/window/
@@ -109,3 +109,6 @@ export { foldHistory } from "./log.js";
 export { volterHome } from "./volter-home.js";
 export { boardFrameKey } from "./board-keys.js";
 export * as managedOriginalInputs from "./managed-original-inputs.js";
+export { worldSecret, worldAccount } from "./derived-core.js";
+export { rewriteProtobufFields } from "./protobuf.js";
+export { attachWebSocketRelay } from "./serve-http.js";

package/dist/src/serve-http.d.ts

@@ -69,3 +69,14 @@ export declare function serveStream(options: {
     port: number;
     stop: () => void;
 }>;
+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 declare function attachWebSocketRelay(server: import('node:http').Server, route: (request: import('node:http').IncomingMessage) => WebSocketRelay | undefined): Promise<{
+    stop: () => void;
+}>;

package/dist/src/serve-http.js

@@ -471,3 +471,135 @@ async function serveOnNode(options) {
             server.closeAllConnections(); }),
     };
 }
+/** 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, route) {
+    const { WebSocket: Client, WebSocketServer } = await socketLibrary();
+    const routes = new WeakMap();
+    const pairs = new Set();
+    const accepted = new WebSocketServer({ noServer: true, handleProtocols: (_offered, request) => routes.get(request)?.protocol || false });
+    let stopped = false;
+    const reject = (socket, status, message) => {
+        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, socket, head) => {
+        let selected;
+        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 };
+        pairs.add(pair);
+        const pending = [];
+        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) => code === 1005 ? 1000 : code === 1006 ? 1011 : code;
+        const frameOf = (data, binary) => {
+            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) => {
+            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 = [];
+            response.on('data', (chunk) => 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/dist/src/signing.d.ts

@@ -31,12 +31,23 @@ export type SigningKey = {
 };
 /** The algorithms `jwtSign` signs with. */
 export declare const SIGNING_ALGORITHMS: ReadonlyArray<SigningKey['alg']>;
-/** 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';
+};
 /** 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 declare function keyId(publicPem: string, prefix?: string): string;
 /** A JWT: `iat` and `nbf` are `now` (seconds, the World's), `exp` `now` plus the lifetime (60 s when none is given),
@@ -47,19 +58,29 @@ export declare function jwtSign(claims: Row, key: SigningKey, opts: {
     kidPrefix?: string;
     typ?: string;
 }): string;
-/** A JWT's header and payload, unverified. */
-export declare function jwtDecode(token: string): {
+/** A JWT over exactly the supplied claims, without adding temporal claims. The caller owns their policy. */
+export declare function jwtSignClaims(claims: Row, key: SigningKey, opts?: {
+    kidPrefix?: string;
+    typ?: string;
+}): string;
+/** 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 declare function jwtDecode(token: string, opts?: JwtDecodeOptions): {
     header: Row;
     payload: Row;
 };
 /** 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 declare function jwtVerify(token: string, key: Jwks | {
-    alg: 'HS256' | 'HS384' | 'HS512';
-    secret: string;
-}, opts: {
+export declare function jwtVerify(token: string, key: JwtVerificationKey, opts: {
     now: number;
 }): JwtVerdict;
+/** 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 declare function jwtVerifySignature(token: string, key: JwtVerificationKey | ((decoded: {
+    header: Row;
+    payload: Row;
+}) => JwtVerificationKey), opts?: JwtSignatureOptions): JwtVerdict;
 /** The JWKS that verifies every token a public key's pair signs. */
 export declare function jwks(publicPem: string, kidPrefix?: string): Jwks;
 /** An HMAC of a value, hex or base64 (a webhook's signature, a signed id): SHA-256 unless the vendor names another
@@ -125,7 +146,9 @@ export declare function certificateOf(cert: string | Uint8Array): {
 /** What a handler signs and hashes with: `ctx.crypto`. */
 export declare const handlerCrypto: {
     readonly jwtSign: typeof jwtSign;
+    readonly jwtSignClaims: typeof jwtSignClaims;
     readonly jwtVerify: typeof jwtVerify;
+    readonly jwtVerifySignature: typeof jwtVerifySignature;
     readonly jwtDecode: typeof jwtDecode;
     readonly jwks: typeof jwks;
     readonly keyId: typeof keyId;

package/dist/src/signing.js

@@ -22,6 +22,10 @@ export function keyId(publicPem, prefix = 'ins_') {
 /** 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, key, opts) {
+    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, key, opts = {}) {
     // 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;
@@ -32,8 +36,7 @@ export function jwtSign(claims, key, opts) {
     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')
@@ -43,12 +46,16 @@ export function jwtSign(claims, key, opts) {
     signer.end();
     return `${input}.${base64url(signer.sign(key.privatePem))}`;
 }
-/** A JWT's header and payload, unverified. */
-export function jwtDecode(token) {
+/** 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, opts = {}) {
+    if (opts.strict && typeof token !== 'string')
+        throw new Error('malformed jwt');
     const parts = token.split('.');
-    if (parts.length !== 3)
+    if (parts.length !== 3 || opts.strict && parts.some(part => !/^[A-Za-z0-9_-]+$/.test(part)))
         throw new Error('malformed jwt');
-    const part = (s) => parseExactJson(fromBase64url(s).toString('utf8'));
+    const parse = opts.integers === 'number' ? JSON.parse : parseExactJson;
+    const part = (s) => parse(fromBase64url(s).toString('utf8'));
     return { header: part(parts[0]), payload: part(parts[1]) };
 }
 function timely(payload, now) {
@@ -61,27 +68,36 @@ function timely(payload, now) {
 /** 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, key, opts) {
+    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, key, opts = {}) {
     let decoded;
     try {
-        decoded = jwtDecode(token);
+        decoded = jwtDecode(token, opts);
     }
     catch {
         return { valid: false, reason: 'malformed' };
     }
+    const selected = typeof key === 'function' ? key(decoded) : key;
     const [h, p, s] = token.split('.');
-    if ('secret' in key) {
-        if (decoded.header.alg !== key.alg)
+    if ('secret' in selected) {
+        if (decoded.header.alg !== selected.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');
+        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'))
@@ -90,7 +106,7 @@ export function jwtVerify(token, key, opts) {
         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}`);
@@ -98,7 +114,7 @@ export function jwtVerify(token, key, opts) {
     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. */
 export function jwks(publicPem, kidPrefix) {
@@ -256,7 +272,7 @@ export function certificateOf(cert) {
     }
 }
 /** 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 };
+export const handlerCrypto = { jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, base62From, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf };
 /** A [KSUID](https://github.com/segmentio/ksuid) as 27 base62 characters (0-9A-Za-z, most significant first): `seconds`
  *  past KSUID's epoch (1400000000) in four bytes, then `n` in four, then twelve bytes derived from `seed`, so KSUIDs
  *  made in one second sort by `n`, at `width` characters (27 unless a vendor's id is longer or shorter). Deterministic:

package/dist/src/sockets.d.ts

@@ -51,4 +51,4 @@ export declare function expireSocketWaits(service: string, root: string | undefi
  *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
 export declare function socketWrite(service: string, root: string | undefined, write: EventWrite): void;
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
-export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>, hostOf: (request: Request) => string, pathOf?: (request: Request) => string, decide?: (asked: unknown) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;
+export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>, hostOf: (request: Request) => string, pathOf: (request: Request) => string, decide: (asked: unknown) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;