@volter/world-core 2.0.0

package/src/client-bundle.ts

@@ -0,0 +1,29 @@
+// A mirror's browser client from its `client/<name>.tsx` entry, runtime-neutral (the serve seam's helpers,
+// docs/contributing/architecture.md#the-serve-seam): under Bun the same `Bun.build` every mirror ran at
+// serve time; under Node the PREBUILT `<name>.bundle.js` beside the entry, written at pack time
+// by scripts/publish/build.mjs into dist/client/. Built once per process and kept; a failed build
+// is retried on the next call. Nothing here runs at module scope.
+import { existsSync, readFileSync } from 'node:fs';
+
+const bundles = new Map<string, Promise<string>>();
+type BunBuild = { build: (o: { entrypoints: string[]; target: 'browser'; minify: boolean }) => Promise<{ success: boolean; logs: Array<{ message: string }>; outputs: Array<{ text: () => Promise<string> }> }> };
+
+export function bundleClient(entry: string): Promise<string> {
+  let pending = bundles.get(entry);
+  if (!pending) {
+    const bun = (globalThis as { Bun?: Partial<BunBuild> }).Bun;
+    pending = (bun && typeof bun.build === 'function'
+      ? (bun as BunBuild).build({ entrypoints: [entry], target: 'browser', minify: true }).then(async (result) => {
+          if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || `client build failed: ${entry}`);
+          return result.outputs[0]!.text();
+        })
+      : Promise.resolve().then(() => {
+          const prebuilt = entry.replace(/\.tsx?$/, '.bundle.js');
+          if (!existsSync(prebuilt)) throw new Error(`client bundle missing at ${prebuilt} — the package's \`build\` writes it (scripts/publish/build.mjs); Node serves the prebuilt client`);
+          return readFileSync(prebuilt, 'utf8');
+        }))
+      .catch((error) => { bundles.delete(entry); throw error; });
+    bundles.set(entry, pending);
+  }
+  return pending;
+}

package/src/credential.ts

@@ -0,0 +1,140 @@
+// THE SEALED CREDENTIAL STORE (docs/concepts/the-model.md, rule 5; custody ruled 2026-09-01:
+// lives in core since v2 — a world that wraps reality seals its credential beside itself, and the
+// kernel executor is the only reader). Originally the twins host's; the host re-exports it.
+// cloud-side, idiomatic — like any web service). Real vendor credentials are:
+//   • WRITE-ONLY through the API: placement and deletion are the tenant's act; reads
+//     return metadata (placedAt, a fingerprint) and NEVER the secret — there is no
+//     read-back door, and none may ever be added.
+//   • ENVELOPE-ENCRYPTED: each credential gets its own random 256-bit DEK (AES-GCM);
+//     the DEK is wrapped by the deployment KEK, which lives in the platform's secret
+//     store (wrangler secret TWINS_CRED_KEK) and never in any bucket. KEK rotation is
+//     a re-wrap of DEKs, not a re-encryption of payloads.
+//   • OUTSIDE every namespace tree (beside keys and links, under '-/creds/'), so no
+//     flush, snapshot, or door can ever carry one.
+//   • CONSUMED only by the remote backing arm and the sync plane, through
+//     `openSealedCredential` — an in-process seam, never an HTTP surface.
+//
+// The payload is a JSON object; the convention the forward arm consumes is
+// `{ headers: { authorization: "Bearer …", … } }` — credential APPLICATION is a value
+// (which headers), never a per-vendor mechanism. WebCrypto only: workerd-clean.
+//
+// `secret` is the RAW material for the strategies that cannot be expressed as a header: a vendor
+// that reads its key from a query parameter, or one that wants a signature computed per request
+// (docs/concepts/the-model.md#the-rules, rule 5, "applies the credential by strategy"). It is optional and unread unless
+// the pack declares such a strategy, so a header-authenticated vendor seals exactly what it sealed
+// before. It is never logged and never enters pack code — the executor is the only reader.
+
+export type CredentialPayload = { headers: Record<string, string>; secret?: string; keyId?: string } & Record<string, unknown>;
+
+/** The at-rest form. All byte fields base64. The fingerprint is a short SHA-256 prefix
+ *  of the payload — enough for an operator to recognize "the key ending a1b2…", never
+ *  enough to recover anything. */
+export type SealedCredential = {
+  v: 1;
+  dekIv: string;
+  wrappedDek: string;
+  iv: string;
+  ciphertext: string;
+  placedAt: string;
+  fingerprint: string;
+  /** when a vendor last rotated a field of it (an OAuth refresh token): placedAt and fingerprint stay the credential's
+   *  identity across rotations, the ledgers keyed by the fingerprint with them */
+  rotatedAt?: string;
+};
+
+export interface CredentialStorage {
+  getSealed(namespace: string, vendor: string): Promise<SealedCredential | null>;
+  putSealed(namespace: string, vendor: string, sealed: SealedCredential): Promise<void>;
+  deleteSealed(namespace: string, vendor: string): Promise<void>;
+  /** Purge every vendor's sealed record for the namespace — the lifecycle DELETE calls
+   *  this: a deleted namespace's credentials must not survive to be inherited by
+   *  whoever re-provisions the name (review B1: the resurrection theft chain). */
+  deleteNamespace(namespace: string): Promise<void>;
+}
+
+export class MemoryCredentialStorage implements CredentialStorage {
+  readonly records = new Map<string, SealedCredential>();
+  async getSealed(namespace: string, vendor: string): Promise<SealedCredential | null> {
+    return this.records.get(`${namespace}/${vendor}`) ?? null;
+  }
+  async putSealed(namespace: string, vendor: string, sealed: SealedCredential): Promise<void> {
+    this.records.set(`${namespace}/${vendor}`, sealed);
+  }
+  async deleteSealed(namespace: string, vendor: string): Promise<void> {
+    this.records.delete(`${namespace}/${vendor}`);
+  }
+  async deleteNamespace(namespace: string): Promise<void> {
+    for (const key of [...this.records.keys()]) if (key.startsWith(`${namespace}/`)) this.records.delete(key);
+  }
+}
+
+const toB64 = (bytes: Uint8Array): string => {
+  // Chunked (review B3): a spread of the whole payload blows the arg-count stack well
+  // below the 4 MB body cap (verified ~1 MB on Bun, tens of KB on V8).
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += 0x1000) bin += String.fromCharCode(...bytes.subarray(i, i + 0x1000));
+  return btoa(bin);
+};
+const fromB64 = (b64: string): Uint8Array<ArrayBuffer> => {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(new ArrayBuffer(bin.length));
+  for (let i = 0; i < bin.length; i += 1) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+};
+
+/** The KEK secret string (any length ≥ 16) normalizes to 32 key bytes via SHA-256 —
+ *  operators paste one strong secret; the digest is the AES key material. */
+async function importKek(secret: string): Promise<CryptoKey> {
+  // ≥32 chars (review M3): SHA-256 with no stretching is fine for MACHINE secrets
+  // (`openssl rand -base64 32`) and hopeless against a short human passphrase — the
+  // floor forces the former.
+  if (secret.length < 32) throw new Error('credential KEK must be at least 32 characters (generate with: openssl rand -base64 32)');
+  const material = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
+  return await crypto.subtle.importKey('raw', material, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+export async function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot = ''): Promise<SealedCredential> {
+  const kek = await importKek(kekSecret);
+  const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+  const dekBytes = crypto.getRandomValues(new Uint8Array(32));
+  const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['encrypt']);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const dekIv = crypto.getRandomValues(new Uint8Array(12));
+  // The SLOT ('{namespace}/{vendor}') rides as AAD (audit L16): a sealed record
+  // transplanted to another slot by a bucket-level writer refuses to open there.
+  const aad = new TextEncoder().encode(slot);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad }, dek, plaintext));
+  const wrappedDek = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv: dekIv }, kek, dekBytes));
+  // KEYED fingerprint (review m1): an unsalted hash prefix is an offline oracle for
+  // low-entropy payloads; HMAC under KEK-derived material keeps the operator UX
+  // (recognizable short id) with no oracle.
+  const macMaterial = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`fingerprint:${kekSecret}`));
+  const macKey = await crypto.subtle.importKey('raw', macMaterial, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const digest = new Uint8Array(await crypto.subtle.sign('HMAC', macKey, plaintext));
+  return {
+    v: 1,
+    dekIv: toB64(dekIv),
+    wrappedDek: toB64(wrappedDek),
+    iv: toB64(iv),
+    ciphertext: toB64(ciphertext),
+    placedAt,
+    fingerprint: [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join(''),
+  };
+}
+
+export async function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot = ''): Promise<CredentialPayload> {
+  const kek = await importKek(kekSecret);
+  let dekBytes: ArrayBuffer;
+  try {
+    dekBytes = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.dekIv) }, kek, fromB64(sealed.wrappedDek));
+  } catch {
+    throw new Error('credential unseal failed: wrong KEK or corrupted record');
+  }
+  const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['decrypt']);
+  try {
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+    return JSON.parse(new TextDecoder().decode(plaintext)) as CredentialPayload;
+  } catch {
+    throw new Error('credential unseal failed: wrong KEK or corrupted record');
+  }
+}