@volter/world-core 2.0.37 → 3.0.0

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

@@ -1,3 +1,4 @@
+import type { TwinStream } from './twin-fetch.js';
 export type HttpHandler = (request: Request) => Response | Promise<Response>;
 export type WebSocketPeer = {
     send: (data: string | Uint8Array) => unknown;
@@ -5,6 +6,8 @@ export type WebSocketPeer = {
 };
 export type WebSocketUpgrade = {
     accepts: (request: Request) => boolean;
+    /** The subprotocol the server selects for this request, answered in `Sec-WebSocket-Protocol`; none when undefined. */
+    protocol?: (request: Request) => string | undefined;
     open: (peer: WebSocketPeer, request: Request) => void;
     message: (peer: WebSocketPeer, data: string | Uint8Array) => void | Promise<void>;
     close: (peer: WebSocketPeer) => void;
@@ -46,3 +49,14 @@ export declare function serveHttp(options: ServeHttpOptions): Promise<HttpServer
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export declare function nodeBuiltin<T = unknown>(name: string): T;
+/** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
+ *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
+ *  `net` reached at call time, never imported. */
+export declare function serveStream(options: {
+    port?: number;
+    hostname?: string;
+    stream: TwinStream;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/serve-http.js

@@ -5,7 +5,7 @@
 // asynchronous on Node — Bun's synchronous bind is the special case.
 //
 // Nothing here runs at module scope, and `node:http` is reached through `process.getBuiltinModule`
-// rather than a static import: this module rides into mirror-UI client bundles through the kernel's
+// rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
 /** A decorator the request journal installs: every server made through the seam serves through it. */
 let decorate;
@@ -16,6 +16,11 @@ export const WORLD_BOOT_PATH = '/__volter/world-boot';
 export async function serveHttp(options) {
     // Inside a World every server made through the seam answers which boot it belongs to, so the World can tell its own
     // twin from a leftover World's that holds the same port. Outside a World nothing changes.
+    // a pack's fetch carries the upgrade its sockets take (pack-fetch.ts), read before anything wraps the fetch: served on
+    // its own or in a World, its sockets answer
+    const carried = options.upgrade ?? options.fetch.upgrade;
+    if (carried)
+        options = { ...options, upgrade: carried };
     const worldBoot = globalThis.process?.env?.VOLTER_WORLD_BOOT_ID;
     if (worldBoot) {
         const served = options.fetch;
@@ -32,6 +37,8 @@ export async function serveHttp(options) {
         const server = bun.serve({ ...options, hostname, port: options.port ?? 0,
             ...(upgrade ? {
                 fetch: (request, server) => {
+                    // Bun answers the first subprotocol the client offers by itself; a header set here would be a second one, which a
+                    // client refuses (measured, Bun 1.2.20: Node's client reads `realtime`; with the header added, a duplicate)
                     if (request.headers.get('upgrade')?.toLowerCase() === 'websocket' && upgrade.accepts(request) && server.upgrade(request, { data: { request } }))
                         return undefined;
                     return options.fetch(request);
@@ -52,6 +59,21 @@ export async function serveHttp(options) {
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export function nodeBuiltin(name) { return builtin(name); }
+/** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
+ *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
+ *  `net` reached at call time, never imported. */
+export async function serveStream(options) {
+    const net = builtin('node:net');
+    const server = net.createServer((socket) => {
+        const conn = options.stream({ write: (bytes) => { socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '127.0.0.1');
+        socket.on('data', (chunk) => conn.data(new Uint8Array(chunk)));
+        socket.on('close', () => conn.close());
+        socket.on('error', () => conn.close());
+    });
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname ?? '127.0.0.1', () => resolve()); });
+    const address = server.address();
+    return { port: typeof address === 'object' && address ? address.port : options.port ?? 0, stop: () => { server.close(); } };
+}
 function builtin(name) {
     const get = process.getBuiltinModule;
     if (typeof get !== 'function')
@@ -306,10 +328,12 @@ async function serveOnNode(options) {
     let socketServer;
     if (options.upgrade) {
         const { WebSocketServer } = await import('ws');
-        socketServer = new WebSocketServer({ noServer: true });
         const upgrade = options.upgrade;
+        const requestOf = (req) => new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry) => typeof entry[1] === 'string')) });
+        // the subprotocol the socket selects, answered as Bun's branch answers it
+        socketServer = new WebSocketServer({ noServer: true, handleProtocols: (_offered, req) => upgrade.protocol?.(requestOf(req)) ?? false });
         server.on('upgrade', (req, socket, head) => {
-            const request = new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry) => typeof entry[1] === 'string')) });
+            const request = requestOf(req);
             if (!upgrade.accepts(request)) {
                 socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
                 return;

package/dist/src/serve.d.ts

@@ -19,6 +19,10 @@ export type TwinCredentialShape = {
  *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
  *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
 export declare const CALLER_HEADER = "x-volter-caller";
+/** The caller as it travels in CALLER_HEADER: percent-encoded, since a key's name is a person's words (`preview pr-8 ·
+ *  org token ci`) and a header carries bytes only. `callerFromHeader` reads it back; a value it cannot decode stands. */
+export declare const callerForHeader: (caller: string) => string;
+export declare const callerFromHeader: (value: string) => string;
 export type TwinRequestJournalEntry = {
     at?: string;
     method: string;
@@ -157,6 +161,8 @@ export type AtomicTwinWriteDecision<T> = {
     value: T;
     write: TwinWriteInput;
 };
+/** A recorded request as it was sent: each string the log keeps as a blob, read back. */
+export declare function recordedInput(input: unknown): Promise<unknown>;
 /**
  * Decide a state-dependent local write and append it under the same cross-process action lock.
  * Use this when acceptance or the new fields depend on current projected state; a caller-side

package/dist/src/serve.js

@@ -18,11 +18,21 @@ import { hashFieldValue } from "./hash.js";
 import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from "./actions.js";
 import { observeWorldPaths, worldPaths } from "./storage.js";
 import { getActiveWorldStore } from "./world-store.js";
+import { getActiveBlobStore } from "./blob-store.js";
 import { parseTraceparent } from "./trace-context.js";
 /** The header a World puts on a request it forwards to a twin: who made it (`key:<name>`, `person:<who>`, `token`,
  *  `token:read`). The World replaces any a caller sent; the serve seam records it in the twin's request journal and
  *  removes it before the twin's handler. A twin reached on its own port, not through a World, records what it was sent. */
 export const CALLER_HEADER = 'x-volter-caller';
+/** The caller as it travels in CALLER_HEADER: percent-encoded, since a key's name is a person's words (`preview pr-8 ·
+ *  org token ci`) and a header carries bytes only. `callerFromHeader` reads it back; a value it cannot decode stands. */
+export const callerForHeader = (caller) => encodeURIComponent(caller);
+export const callerFromHeader = (value) => { try {
+    return decodeURIComponent(value);
+}
+catch {
+    return value;
+} };
 /** The journal's closed segments, oldest first: `requests.jsonl.<n>` beside the live file. */
 function journalSegments(path) {
     const base = path.slice(path.lastIndexOf('/') + 1);
@@ -239,21 +249,18 @@ export function journalTwinRequest(service, entry, root) {
 // factory's closure. They are recoverable without touching a single pack, because handling a
 // request makes the pack call the kernel, and every kernel state path funnels through
 // `worldPaths(service, root)` (storage.ts). Observing the FIRST such call a server makes is the
-// twin naming itself: `datadog` under `/tmp/world/data/datadog`. It is cached per server, so only
+// twin naming itself: `deepgram` under `/tmp/world/data/deepgram`. It is cached per server, so only
 // the first request pays for it. A server whose first request touches no state falls back to the
-// call site (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>`) and the process's `--root`
+// call site (a catalog checkout or `@volter/twin-<vendor>`) and the process's `--root`
 // argument, which is how the world runtime launches every twin.
 export const TWIN_JOURNAL_IDENTITY = Symbol.for('volter.twin.requestJournal.identity');
 const JOURNAL_SHIM_INSTALLED = Symbol.for('volter.twin.requestJournal.installed');
 /** One capture slot per in-flight request, so two twins co-located in ONE process (the shared
  *  host) can never read each other's identity off a racing sibling's first request.
  *
- *  LAZY ON PURPOSE, and this is load-bearing rather than style. Mirror-UI packs import their own
- *  server module into the BROWSER bundle and rely on Bun tree-shaking the server-only half away
- *  (see any `*-mirror-ui.ts` header). A module-scope `new AsyncLocalStorage()` is a side effect,
- *  so it survives tree-shaking and lands in the client — where `node:async_hooks` does not
- *  resolve, `new` throws at bundle evaluation, and the React app never mounts. That took out
- *  every mirror UI in the estate at once. Nothing in this module may run at module scope. */
+ *  LAZY ON PURPOSE: kernel modules ride into browser bundles (kernel imports are free of side effects), and a module-scope
+ *  `new AsyncLocalStorage()` survives tree-shaking into a client, where `node:async_hooks` does not resolve and `new`
+ *  throws at bundle evaluation. Nothing in this module may run at module scope. */
 let identityCapture;
 function identitySlot() {
     identityCapture ??= new AsyncLocalStorage();
@@ -279,7 +286,7 @@ const INFRA_PACKAGES = new Set(['world-runtime', 'world-tooling', 'world-attach'
 export function vendorFromStack(stack) {
     if (!stack)
         return undefined;
-    const pattern = /(?:packages[\\/]twin[\\/]|@volter[\\/]twin-)([A-Za-z0-9_-]+)/g;
+    const pattern = /(?:twin-packs-p[23][\\/]|@volter[\\/]twin-)([A-Za-z0-9_-]+)/g;
     for (const match of stack.matchAll(pattern)) {
         const name = match[1];
         if (!INFRA_PACKAGES.has(name))
@@ -298,7 +305,7 @@ export function vendorFromStack(stack) {
  * service is an argument rather than a fact about the pack.
  */
 export function installTwinRequestJournal() {
-    // a browser bundle (a mirror UI carrying the kernel): nothing to wrap, nothing to touch
+    // a browser bundle carrying the kernel: nothing to wrap, nothing to touch
     if (typeof window !== 'undefined' || typeof document !== 'undefined')
         return false;
     const bun = globalThis.Bun;
@@ -338,7 +345,8 @@ function journalingFetch(config, callSiteVendor) {
         const inner = config.fetch;
         const journaling = async function (request, server) {
             // who made it is read here and goes no further: no twin's handler (a tunnel's, a proxy's) hands it on
-            const caller = request.headers.get(CALLER_HEADER) ?? undefined;
+            const sent = request.headers.get(CALLER_HEADER);
+            const caller = sent === null ? undefined : callerFromHeader(sent);
             if (caller !== undefined) {
                 const headers = new Headers(request.headers);
                 headers.delete(CALLER_HEADER);
@@ -404,6 +412,53 @@ installTwinRequestJournal();
 export function twinResources(service, root) {
     return projectResources(service, root);
 }
+/** The largest string a write's recorded request keeps in the log itself. */
+const INPUT_INLINE_MAX = 64 * 1024;
+/**
+ * A write's recorded request, with each string longer than INPUT_INLINE_MAX (an attached file's base64: an npm
+ * publish's tarball) kept once as a content-addressed blob under the service's state and named in its place as
+ * `{ $blob, bytes }`. The request stays whole and deterministic, and a body several writes record is kept once, never
+ * copied into the log (docs/contributing/architecture.md, "The log keeps a large request once"). `recordedInput` reads
+ * it back whole.
+ */
+async function offloadInput(service, input, root) {
+    if (typeof input === 'string') {
+        if (input.length <= INPUT_INLINE_MAX)
+            return input;
+        // hashed as it is (UTF-8), and encoded only when its blob is new: each write of a request records the same body
+        const key = join(worldPaths(service, root).dir, 'inputs', createHash('sha256').update(input, 'utf8').digest('hex'));
+        const blobs = getActiveBlobStore();
+        if (!(await blobs.exists(key)))
+            await blobs.put(key, Buffer.from(input, 'utf8'));
+        return { $blob: key, bytes: Buffer.byteLength(input, 'utf8') };
+    }
+    if (Array.isArray(input))
+        return Promise.all(input.map((v) => offloadInput(service, v, root)));
+    if (input && typeof input === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(input))
+            out[k] = await offloadInput(service, v, root);
+        return out;
+    }
+    return input;
+}
+/** A recorded request as it was sent: each string the log keeps as a blob, read back. */
+export async function recordedInput(input) {
+    if (Array.isArray(input))
+        return Promise.all(input.map(recordedInput));
+    if (input && typeof input === 'object') {
+        const ref = input;
+        if (typeof ref.$blob === 'string' && typeof ref.bytes === 'number' && Object.keys(input).length === 2) {
+            const bytes = await getActiveBlobStore().get(ref.$blob);
+            return bytes ? new TextDecoder().decode(bytes) : undefined;
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(input))
+            out[k] = await recordedInput(v);
+        return out;
+    }
+    return input;
+}
 function actionForTwinWrite(service, write) {
     const occurredAt = write.occurredAt ?? new Date().toISOString();
     // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
@@ -493,7 +548,7 @@ export function resolveTwinRead(service, pathname, opts = {}) {
 // provably untouched (no network I/O, no egress). Pushing the action to the real
 // vendor is a separate, explicit step that records egress + confirms the action.
 export async function applyTwinWrite(service, write, root) {
-    const action = actionForTwinWrite(service, write);
+    const action = actionForTwinWrite(service, write.input === undefined ? write : { ...write, input: await offloadInput(service, write.input, root) });
     // A LOCAL VENDOR WRITE IS AN OCCURRENCE. Two calls are two actions, even byte-identical in the
     // same instant, and the ordinal in the action id says which occurrence this is. The kernel used
     // to derive identity from (content + occurredAt millisecond) and drop a repeat as `replayed`,
@@ -501,8 +556,8 @@ export async function applyTwinWrite(service, write, root) {
     // under a pinned world clock, where every write in a world shares one instant. That default cost
     // github, slack and jira live defects while the recipe told each pack to defend itself with a
     // per-write ordinal and a fifth of the catalog opted out via `uniqueness`. A default every pack
-    // must remember to defend against is not a default. See docs/contributing/adding-a-twin.md
-    // #5-build-on-the-shared-kernel--dont-reinvent, "A local write is an occurrence".
+    // must remember to defend against is not a default. See docs/contributing/architecture.md,
+    // "The state kernel", "A local write is an occurrence".
     //
     // AT-MOST-ONCE is opt in, by KEY: `idempotencyKey` makes the id a function of the caller's own
     // request identity, so a re-issue collapses onto the first and answers `replayed`. Content can

package/dist/src/signing.d.ts

@@ -0,0 +1,135 @@
+import { sealedBoxKeyPair, sealedBoxOpen } from './sealed-box.js';
+type Row = Record<string, unknown>;
+export type Jwk = {
+    kty: 'RSA';
+    use: 'sig';
+    alg: 'RS256';
+    kid: string;
+    n: string;
+    e: string;
+};
+export type Jwks = {
+    keys: Jwk[];
+};
+/** A signing key: an RSA private key as a PEM (its public half, given or derived, is what a JWKS serves and names by
+ *  `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs none. */
+export type SigningKey = {
+    alg: 'RS256' | 'RS384' | 'RS512';
+    privatePem: string;
+    publicPem?: string;
+} | {
+    alg: 'HS256' | 'HS384' | 'HS512';
+    secret: string;
+};
+/** The algorithms `jwtSign` signs with. */
+export 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. */
+export type JwtVerdict = {
+    valid: boolean;
+    payload?: Row;
+    reason?: 'malformed' | 'unexpected_alg' | 'no_matching_key' | 'bad_signature' | 'expired' | 'not_yet_valid';
+};
+/** 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),
+ *  unless the claims name their own. RS256 tokens carry the key's `kid`. */
+export declare function jwtSign(claims: Row, key: SigningKey, opts: {
+    now: number;
+    expiresInSeconds?: number;
+    kidPrefix?: string;
+}): string;
+/** A JWT's header and payload, unverified. */
+export declare function jwtDecode(token: string): {
+    header: Row;
+    payload: Row;
+};
+/** A token checked: an RS256 one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
+ *  then its `exp`/`nbf` at `now` (seconds). */
+export declare function jwtVerify(token: string, key: Jwks | {
+    alg: 'HS256' | 'HS384' | 'HS512';
+    secret: string;
+}, opts: {
+    now: number;
+}): 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
+ *  (OAuth 1.0a's HMAC-SHA1). The secret is its text, or its bytes where the vendor keys with a decoded secret (Svix's
+ *  `whsec_` base64). */
+export declare const hmac: (secret: string | Uint8Array, value: string | Uint8Array, encoding?: "hex" | "base64" | "base64url", algorithm?: "sha1" | "sha256" | "sha512") => string;
+/** A SHA-256, hex (a key stored by its hash, a deterministic id). */
+export declare const sha256: (value: string) => string;
+/** A digest of a value in the algorithm and encoding a vendor names (GoTrue's SHA-224 token hashes, a PKCE challenge's
+ *  base64url SHA-256). */
+export declare function digest(algorithm: 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512', value: string | Uint8Array, encoding?: 'hex' | 'base64' | 'base64url'): string;
+/** RFC 3986 percent-encoding as RFC 5849 §3.6 uses it (unreserved: A-Z a-z 0-9 - . _ ~). */
+export declare const oauth1Encode: (s: string) => string;
+/** The `Authorization: OAuth k="v", …` header's parameters, decoded, in order; undefined when it is not one. */
+export declare function oauth1Header(value: string | null | undefined): Array<[string, string]> | undefined;
+/** The signature base string (RFC 5849 §3.4.1): the method, the base URL (no query) and the parameters signed, each
+ *  percent-encoded and sorted by name and value. */
+export declare function oauth1BaseString(method: string, baseUrl: string, pairs: ReadonlyArray<readonly [string, string]>): string;
+/** The HMAC-SHA1 signature (RFC 5849 §3.4.2) over a base string, keyed by the consumer secret and the token secret. */
+export declare const oauth1Signature: (base: string, consumerSecret: string, tokenSecret?: string) => string;
+/** A digest of a value as its bytes (a key or an id drawn from a hash's bytes, a deterministic embedding). */
+export declare function digestBytes(algorithm: 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512', value: string | Uint8Array): Uint8Array;
+/** An MD5, hex (an object's ETag, as S3 and storage APIs give it); never a secret's protection. */
+export declare const md5: (value: string | Uint8Array) => string;
+/** A version-4-shaped UUID derived from `seed`: the same seed gives the same id every run (R9). */
+export declare function uuidFrom(seed: string): string;
+/** `count` lowercase letters derived from `seed` (a 20-letter project ref, a slug's suffix), the same every run. */
+export declare function lettersFrom(seed: string, count?: number): string;
+/** Two strings compared in constant time. */
+export declare function equalSecrets(a: string, b: string): boolean;
+/** Bytes signed with a private key (RSA with SHA-256, or Ed25519), in the encoding asked: a certificate's signature,
+ *  a transparency log's checkpoint. */
+export declare function signWith(privatePem: string, data: string | Uint8Array, encoding?: 'base64' | 'hex' | 'base64url'): string;
+/** Whether a signature holds over bytes under a public key or a certificate's (PEM, or a certificate's DER): any
+ *  scheme a vendor uses (ECDSA, RSA, Ed25519), since verifying draws nothing. The digest is SHA-256 unless named. */
+export declare function verifyWith(publicKey: string | Uint8Array, data: string | Uint8Array, signature: string | Uint8Array, opts?: {
+    digest?: 'sha256' | 'sha384' | 'sha512';
+    encoding?: 'base64' | 'hex';
+}): boolean;
+/** A public key's PEM and its DER (SubjectPublicKeyInfo), from a public or private key's PEM or a certificate. */
+export declare function publicKeyOf(key: string): {
+    pem: string;
+    der: Uint8Array;
+};
+/** An X.509 certificate read (PEM or DER): its bytes, names, validity and key, and whether an issuer's key signed it;
+ *  undefined when it is not one. */
+export declare function certificateOf(cert: string | Uint8Array): {
+    der: Uint8Array;
+    subject: string;
+    issuer: string;
+    subjectAltName: string | undefined;
+    notBefore: string;
+    notAfter: string;
+    publicKey: {
+        pem: string;
+        der: Uint8Array;
+    };
+    issuedBy(issuer: string | Uint8Array): boolean;
+} | undefined;
+/** What a handler signs and hashes with: `ctx.crypto`. */
+export declare const handlerCrypto: {
+    readonly jwtSign: typeof jwtSign;
+    readonly jwtVerify: typeof jwtVerify;
+    readonly jwtDecode: typeof jwtDecode;
+    readonly jwks: typeof jwks;
+    readonly keyId: typeof keyId;
+    readonly hmac: (secret: string | Uint8Array, value: string | Uint8Array, encoding?: "hex" | "base64" | "base64url", algorithm?: "sha1" | "sha256" | "sha512") => string;
+    readonly sha256: (value: string) => string;
+    readonly md5: (value: string | Uint8Array) => string;
+    readonly digest: typeof digest;
+    readonly uuidFrom: typeof uuidFrom;
+    readonly lettersFrom: typeof lettersFrom;
+    readonly equalSecrets: typeof equalSecrets;
+    readonly sealedBoxKeyPair: typeof sealedBoxKeyPair;
+    readonly sealedBoxOpen: typeof sealedBoxOpen;
+    readonly signWith: typeof signWith;
+    readonly verifyWith: typeof verifyWith;
+    readonly publicKeyOf: typeof publicKeyOf;
+    readonly certificateOf: typeof certificateOf;
+};
+export type HandlerCrypto = typeof handlerCrypto;
+export {};

package/dist/src/signing.js

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