@volter/world-core 3.0.161 → 3.0.163

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;

package/dist/src/sockets.js

@@ -1,3 +1,4 @@
+import { runWithStorageTenant, storageTenant } from "./request-scope.js";
 // 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
@@ -14,7 +15,7 @@ const nextSession = new Map();
 const keyOf = (service, root) => `${service}\0${root ?? ''}`;
 /** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
 export function openSessions(service, root, socket) {
-    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
  *  machine's clock would reject it; called as the vendor serves a request ("A request answered by a session"). */
@@ -39,9 +40,11 @@ export function socketWrite(service, root, write) {
         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.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.message ?? error).slice(0, 120)));
     }
 }
 /** A declared socket path's parameters for a request's path, or undefined when it does not match: a `{name}` segment
@@ -66,7 +69,7 @@ function socketParams(declared, path) {
     }
 }
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
-export function socketUpgrade(service, root, decls, engines, context, hostOf, pathOf = (request) => new URL(request.url).pathname, decide = async () => undefined) {
+export function socketUpgrade(service, root, decls, engines, context, hostOf, pathOf, decide) {
     const matchFor = (request) => {
         const path = pathOf(request).replace(/\/+$/, '') || '/';
         for (const d of decls) {
@@ -113,18 +116,19 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 },
                 decide,
             };
-            const o = { session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };
+            const tenant = storageTenant(service), run = (fn) => runWithStorageTenant(service, tenant, fn);
+            const o = { 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.message ?? error).slice(0, 120)));
+                o.queue = o.queue.then(() => o.run(async () => engine.open(session, await o.context()))).catch((error) => session.close(1011, String(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.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.message ?? error).slice(0, 120)));
         },
         close: (peer) => {
             const o = byPeer.get(peer);
@@ -140,7 +144,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
             // 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) => {
+                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?.message ?? error)}`);
                 });
         },

package/dist/src/world-account-name.d.ts

@@ -0,0 +1,2 @@
+/** The retained World-account name grammar, shared by registration and read-only authority selection. */
+export declare function isWorldAccountName(value: unknown): value is string;

package/dist/src/world-account-name.js

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

package/generated/pack-facts.json

@@ -25,6 +25,9 @@
       "resources": [],
       "endpointEnvNone": "@ai-sdk/gateway calls https://ai-gateway.vercel.sh/v4/ai and an OpenAI client is given https://ai-gateway.vercel.sh/v1 in code; the World claims the host",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -110,6 +113,9 @@
         "note": "the SDKs' base URL (the TypeScript and Python SDKs and Claude Code read ANTHROPIC_BASE_URL)"
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -174,6 +180,9 @@
         "note": "The AWS SDKs read AWS_ENDPOINT_URL as every service's endpoint (https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)."
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -360,6 +369,9 @@
       "credentialDoor": {
         "path": "/_twin/app-credentials",
         "body": {},
+        "account": {
+          "field": "account"
+        },
         "fill": {
           "CLERK_SECRET_KEY": "secret_key",
           "CLERK_API_KEY": "secret_key",
@@ -782,6 +794,9 @@
         "note": "Python e2b 2.45.0 and the JS SDK read E2B_API_URL; the JS SDK reads E2B_SANDBOX_URL and sends sandbox id/port headers; vendor hosts route through the World proxy"
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/teams",
         "body": {
           "name": "World team"
@@ -1003,6 +1018,9 @@
         "note": "Google GenAI SDK reads this base URL; other callers retain the routed vendor host."
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -1079,6 +1097,9 @@
         "app"
       ],
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -1213,6 +1234,9 @@
       ],
       "endpointEnvNone": "Google's OAuth libraries read no base-URL variable: the endpoints are the discovery document's, claimed by the host rules.",
       "credentialDoor": {
+        "account": {
+          "field": "world_account"
+        },
         "path": "/_twin/credentials",
         "body": {
           "client_email": "world@world-project.iam.gserviceaccount.com",
@@ -1657,11 +1681,20 @@
       "endpointEnv": {
         "name": "LIVEKIT_URL",
         "templates": {
-          "LIVEKIT_URL": "ws://${host}:${port}",
-          "LIVEKIT_API_KEY": "twin-livekit-key",
-          "LIVEKIT_API_SECRET": "twin-livekit-secret-for-the-worlds-own-server"
+          "LIVEKIT_URL": "ws://${host}:${port}"
         },
-        "note": "Credentials and URL are the same ones the World starts its LiveKit server with."
+        "note": "The native server uses a private key; its twin front accepts only keys issued for retained World accounts."
+      },
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "account": {
+          "field": "account"
+        },
+        "fill": {
+          "LIVEKIT_API_KEY": "api_key",
+          "LIVEKIT_API_SECRET": "api_secret"
+        }
       },
       "sidePorts": [
         {
@@ -1696,6 +1729,9 @@
       "resources": [],
       "endpointEnvNone": "Open Autonomy reads MODEL_GATEWAY_URL and defaults to api-gateway.merge.dev; the World claims the host",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/organizations",
         "body": {},
         "fill": {
@@ -1734,6 +1770,9 @@
       "resources": [],
       "endpointEnvNone": "the SDKs call https://api.mistral.ai/v1 unless given a base URL in code or config; the World claims the host",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -1808,6 +1847,9 @@
         "note": "npm and bun read the registry from npm_config_registry (and .npmrc's `registry`)."
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -1871,6 +1913,9 @@
         "api_key"
       ],
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -1982,6 +2027,9 @@
         "note": "the twin's own URL; applications reach it at <region>.connect.psdb.cloud, which the injector redirects, with the password the credentialDoor issued."
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {
           "organization": "world",
@@ -2306,6 +2354,9 @@
         "received"
       ],
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -2377,6 +2428,9 @@
       ],
       "endpointEnvNone": "an SDK sends to its DSN's host and sentry-cli to SENTRY_URL (sentry.io by default); the DSN the World issues names the World's ingest host, claimed by the host rules",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -2485,6 +2539,9 @@
         "app"
       ],
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -2602,6 +2659,9 @@
       "credentialDoor": {
         "path": "/_twin/app-credentials",
         "body": {},
+        "account": {
+          "field": "account"
+        },
         "fill": {
           "STRIPE_SECRET_KEY": "secret_key",
           "STRIPE_API_KEY": "secret_key",
@@ -2675,7 +2735,11 @@
       "managedDatabase": {
         "kind": "postgres",
         "arg": "--database",
-        "note": "the project's database is the World's managed postgres: the database the application's migrations and queries use, whose URL the credential door answers"
+        "user": "world",
+        "database": "world",
+        "clock": "wall",
+        "credentialField": "database_url",
+        "note": "the selected Supabase twin owns its private PostgreSQL data plane; the credential door answers its URL, application migrations own application tables, and SQL uses wall time"
       },
       "serveExport": "createSupabaseTwinServer"
     },
@@ -2886,6 +2950,9 @@
       ],
       "endpointEnvNone": "Tinybird's clients take the API host as configuration (@chronark/zod-bird's baseUrl, tinybird-cli's --host), defaulting to https://api.tinybird.co, which the World routes by host; no SDK reads a base-URL variable of its own",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -3205,6 +3272,9 @@
         "note": "Redis reads its REST URL; QStash and Workflow read QSTASH_URL. Direct SDK transports use the twin endpoint and issued token; other clients also use host routing."
       },
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {
           "owner": "owner@world.test"
@@ -3270,6 +3340,9 @@
       ],
       "endpointEnvNone": "the applications reach api.vercel.com and the Edge Config connection string's host, which the World routes to the twin",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {
           "team": "world",
@@ -3508,6 +3581,9 @@
         "upload"
       ],
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {
@@ -3546,6 +3622,9 @@
       "resources": [],
       "endpointEnvNone": "the SDK calls https://api.x.ai/v1 unless given a base URL in code; the World claims the host",
       "credentialDoor": {
+        "account": {
+          "field": "account"
+        },
         "path": "/_twin/app-credentials",
         "body": {},
         "fill": {

package/inject.cjs

@@ -358,8 +358,8 @@ function strictEgressEnabled() {
 }
 
 // THE WORLD'S DECISION (docs/contributing/architecture.md, "Capability decisions"): every seam below asks
-// capability-decision.cjs and enforces its answer. This process is a host process, whose declaration is the open one; a
-// local light guest, whose HTTP leaves through its guest listener; or a process of an image run, which carries its
+// capability-decision.cjs and enforces its answer. This process is a host process, whose declaration is the open one; or
+// a process of an image run, which carries its
 // image's declaration (VOLTER_WORLD_DECLARATION) and is confined from the host's network. What the World grants is its
 // published policy. The seams supply what they observe: the twin route, the vendors sharing a host, the World's doors.
 function worldGrant() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.161",
+  "version": "3.0.163",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",