@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/files/types.js

@@ -0,0 +1,276 @@
+export function parseMaxSize(maxSize) {
+    const match = maxSize.match(/^(\d+)(kb|mb|gb)$/i);
+    if (!match)
+        throw new Error(`Invalid maxSize format: "${maxSize}". Use e.g. "10mb", "500kb".`);
+    const value = Number(match[1]);
+    const unit = (match[2] ?? "").toLowerCase();
+    switch (unit) {
+        case "kb":
+            return value * 1024;
+        case "mb":
+            return value * 1024 * 1024;
+        case "gb":
+            return value * 1024 * 1024 * 1024;
+        default:
+            throw new Error(`Unknown unit: ${unit}`);
+    }
+}
+function extractExtension(fileName) {
+    return fileName.split(".").pop()?.toLowerCase();
+}
+// Extension → acceptable MIME-type whitelist. Backs the cheap metadata
+// pre-check in validateFile AND the signature lookup in validateFileContent.
+// Kept small & conservative; add entries on demand rather than importing a
+// heavyweight mime DB.
+const EXTENSION_MIME_WHITELIST = {
+    jpg: ["image/jpeg", "image/jpg"],
+    jpeg: ["image/jpeg", "image/jpg"],
+    png: ["image/png"],
+    gif: ["image/gif"],
+    webp: ["image/webp"],
+    svg: ["image/svg+xml"],
+    pdf: ["application/pdf"],
+    txt: ["text/plain"],
+    csv: ["text/csv", "application/csv", "text/plain"],
+    json: ["application/json", "text/json"],
+    md: ["text/markdown", "text/plain"],
+    doc: ["application/msword"],
+    docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+};
+// Extension → declared MIME → canonical MIME. Windows resolves .csv's upload
+// MIME from Explorer's Excel file association, sending "application/vnd.ms-excel" for plain-text CSV.
+const EXTENSION_MIME_ALIASES = {
+    csv: { "application/vnd.ms-excel": "text/csv" },
+};
+// Object.hasOwn at both levels: a plain `in` check on `{}` resolves to
+// Object.prototype members ("constructor", …) for any ext/mimeType.
+function lookupMimeAlias(ext, normalizedMimeType) {
+    if (!Object.hasOwn(EXTENSION_MIME_ALIASES, ext))
+        return undefined;
+    const aliasesForExt = EXTENSION_MIME_ALIASES[ext];
+    if (!aliasesForExt || !Object.hasOwn(aliasesForExt, normalizedMimeType))
+        return undefined;
+    return aliasesForExt[normalizedMimeType];
+}
+// Same hasOwn guard as lookupMimeAlias above, for the ext-keyed whitelist.
+function lookupExtensionWhitelist(ext) {
+    if (!Object.hasOwn(EXTENSION_MIME_WHITELIST, ext))
+        return undefined;
+    return EXTENSION_MIME_WHITELIST[ext];
+}
+// Reverse of lookupExtensionWhitelist: every extension whose whitelist entry
+// includes this MIME type (e.g. "image/jpeg" -> ["jpg", "jpeg"]) — backs
+// validateFileContent's accept-based normalization below.
+function extensionsForMimeType(mimeType) {
+    return Object.entries(EXTENSION_MIME_WHITELIST)
+        .filter(([, mimeTypes]) => mimeTypes.includes(mimeType))
+        .map(([ext]) => ext);
+}
+// Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
+// a reliable binary signature. Used both at upload time (validateFileContent)
+// and at serve time (resolveServedContentType) — never trust the stored/
+// client-declared mimeType for Content-Type on its own, sniff the actual
+// bytes instead. Types without a stable signature (svg, txt, csv, json, md)
+// and anything that matches none of these fall back to
+// application/octet-stream in resolveServedContentType below — this also
+// guarantees text/html and image/svg+xml are never served inline, even for
+// an honestly-declared upload.
+const MAGIC_BYTE_SIGNATURES = [
+    {
+        mimeType: "image/png",
+        matches: (bytes) => startsWithBytes(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    },
+    { mimeType: "image/jpeg", matches: (bytes) => startsWithBytes(bytes, [0xff, 0xd8, 0xff]) },
+    {
+        mimeType: "image/gif",
+        matches: (bytes) => startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a"),
+    },
+    {
+        mimeType: "image/webp",
+        matches: (bytes) => startsWithAscii(bytes, "RIFF") && startsWithAscii(bytes, "WEBP", 8),
+    },
+    { mimeType: "application/pdf", matches: (bytes) => startsWithAscii(bytes, "%PDF-") },
+    // Full 8-byte OLE Compound File signature — legacy .doc/.xls/.ppt share it,
+    // so any OLE file sniffs as msword regardless of which one it really is.
+    {
+        mimeType: "application/msword",
+        matches: (bytes) => startsWithBytes(bytes, [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]),
+    },
+    // ZIP local-file-header signature — .docx/.xlsx/.pptx/plain .zip all share
+    // it; same caveat as OLE above.
+    {
+        mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        matches: (bytes) => startsWithBytes(bytes, [0x50, 0x4b, 0x03, 0x04]),
+    },
+];
+function startsWithBytes(bytes, signature) {
+    if (bytes.length < signature.length)
+        return false;
+    return signature.every((byte, i) => bytes[i] === byte);
+}
+function startsWithAscii(bytes, ascii, offset = 0) {
+    if (bytes.length < offset + ascii.length)
+        return false;
+    for (let i = 0; i < ascii.length; i++) {
+        if (bytes[offset + i] !== ascii.charCodeAt(i))
+            return false;
+    }
+    return true;
+}
+/**
+ * Canonical MIME type for a known binary magic-byte signature (png, jpeg,
+ * gif, webp, pdf, OLE, ZIP), or null for everything else — text formats
+ * (csv, txt, json, svg, md) have no signature and always return null. Every
+ * OLE Compound File (.doc/.xls/.ppt) returns "application/msword" and every
+ * ZIP (.docx/.xlsx/.pptx/.zip) returns the docx MIME — callers can't tell
+ * those apart by bytes alone.
+ */
+export function sniffMimeType(bytes) {
+    for (const signature of MAGIC_BYTE_SIGNATURES) {
+        if (signature.matches(bytes))
+            return signature.mimeType;
+    }
+    return null;
+}
+// Strips a `; charset=…`-style suffix and trims/lowercases — the one
+// normalization every mimeType comparison needs before comparing values.
+export function normalizeMimeType(mimeType) {
+    return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+}
+// image/jpg is not a registered IANA type but EXTENSION_MIME_WHITELIST above
+// accepts it as a jpg alias — sniffMimeType only ever returns the canonical
+// image/jpeg, so without this a legitimately-declared "image/jpg" upload
+// would mismatch its own sniffed type and get needlessly downgraded.
+const DECLARED_MIME_ALIASES = {
+    "image/jpg": "image/jpeg",
+};
+// The Content-Type a served file's bytes are safe to go out with. Bytes that
+// don't sniff as one of the known-safe binary signatures (including
+// svg/html/text formats, which have no reliable magic bytes) always
+// downgrade to application/octet-stream. Bytes that DO sniff safely still
+// downgrade unless the sniffed type matches what was declared at upload —
+// a mismatch (e.g. real PNG bytes uploaded as "text/html") is itself a
+// spoofing signal and is never trusted enough to pick a Content-Type from,
+// even one that would otherwise be harmless.
+export function resolveServedContentType(bytes, declaredMimeType) {
+    const sniffed = sniffMimeType(bytes);
+    if (!sniffed)
+        return "application/octet-stream";
+    const normalizedDeclared = normalizeMimeType(declaredMimeType);
+    const declared = DECLARED_MIME_ALIASES[normalizedDeclared] ?? normalizedDeclared;
+    return sniffed === declared ? sniffed : "application/octet-stream";
+}
+export function validateFile(metadata, options) {
+    if (options.maxSize) {
+        const maxBytes = parseMaxSize(options.maxSize);
+        if (metadata.size > maxBytes) {
+            return `file_too_large: ${metadata.size} bytes exceeds ${options.maxSize}`;
+        }
+    }
+    if (options.accept && options.accept.length > 0) {
+        const ext = extractExtension(metadata.fileName);
+        if (!ext || !options.accept.includes(ext)) {
+            return `invalid_file_type: ".${ext}" is not in [${options.accept.join(", ")}]`;
+        }
+        // Cheap metadata pre-check only: the client/runtime mimeType is no
+        // evidence of file content (Bun derives it from the filename itself).
+        const allowedMimes = lookupExtensionWhitelist(ext);
+        if (allowedMimes && metadata.mimeType) {
+            const normalized = normalizeMimeType(metadata.mimeType);
+            const isAliasedMime = lookupMimeAlias(ext, normalized) !== undefined;
+            if (!allowedMimes.includes(normalized) && !isAliasedMime) {
+                return `mime_mismatch: extension ".${ext}" does not match mimeType "${metadata.mimeType}"`;
+            }
+        }
+    }
+    return null;
+}
+function signatureMimeTypesForExtension(ext) {
+    const whitelist = lookupExtensionWhitelist(ext);
+    if (!whitelist)
+        return [];
+    return whitelist.filter((candidate) => MAGIC_BYTE_SIGNATURES.some((signature) => signature.mimeType === candidate));
+}
+// Separate from validateFile: metadata is known before the upload body is
+// fully read, content-verification only after — callers reject early on
+// metadata without buffering bytes they'll then have to reject anyway.
+//
+// When the sniffed signature doesn't match the declared extension but the
+// sniffed type's OWN extension is in a non-empty `accept`, the upload
+// normalizes to that type instead of being rejected — this only widens which
+// of the field's own allowed formats a mislabeled upload can settle into,
+// never which formats are accepted. With no `accept` restriction at all
+// (undefined or empty, same "unrestricted" meaning validateFile gives it),
+// any recognized signature normalizes the same way, since there is no
+// declared list left to widen.
+export function validateFileContent(fileName, content, accept) {
+    const ext = extractExtension(fileName);
+    if (!ext)
+        return { kind: "ok" };
+    const signatureMimeTypes = signatureMimeTypesForExtension(ext);
+    if (signatureMimeTypes.length === 0)
+        return { kind: "ok" };
+    const sniffed = sniffMimeType(content);
+    if (sniffed && signatureMimeTypes.includes(sniffed))
+        return { kind: "ok" };
+    if (sniffed) {
+        const candidateExtensions = extensionsForMimeType(sniffed);
+        const hasAcceptRestriction = accept !== undefined && accept.length > 0;
+        const normalizedExtension = hasAcceptRestriction
+            ? candidateExtensions.find((candidate) => accept.includes(candidate))
+            : candidateExtensions[0];
+        if (normalizedExtension) {
+            return { kind: "normalized", extension: normalizedExtension, mimeType: sniffed };
+        }
+    }
+    return {
+        kind: "rejected",
+        error: `content_mismatch: ".${ext}" upload bytes are ${sniffed ?? "unrecognized"}, expected ${signatureMimeTypes.join(" or ")}`,
+    };
+}
+/**
+ * Rewrites an aliased declared mimeType to its canonical form and, in the
+ * same call, sniffs the bytes — a renamed binary (a real .xls/.xlsx saved
+ * as .csv) must fail here rather than through an optional, skippable step.
+ */
+export function resolveUploadMimeType(fileName, declaredMimeType, content) {
+    const ext = extractExtension(fileName);
+    const normalizedDeclared = normalizeMimeType(declaredMimeType);
+    const canonical = ext ? lookupMimeAlias(ext, normalizedDeclared) : undefined;
+    if (!canonical)
+        return { kind: "ok", mimeType: declaredMimeType };
+    if (sniffMimeType(content) !== null) {
+        return {
+            kind: "rejected",
+            error: `content_mismatch: bytes of ".${ext}" upload declared as "${declaredMimeType}" are a binary format`,
+        };
+    }
+    return { kind: "ok", mimeType: canonical };
+}
+export function assertSafeStorageKey(key) {
+    if (key.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`storage key contains a path-traversal segment: "${key}"`);
+    }
+}
+export function buildStorageKey(tenantId, entityType, entityId, fieldName, fileName, uniqueId, 
+// Set when validateFileContent normalized the upload to a different real
+// type — the storage key then reflects the sniffed type, not the user's
+// (wrong) original extension.
+extensionOverride) {
+    const rawExt = extensionOverride ?? fileName.split(".").pop() ?? "";
+    const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
+    return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
+}
+/** Fixed leading segment so one S3 lifecycle rule (Prefix: "exports/") can expire export bundles for every tenant without matching a buildStorageKey() upload. */
+export function tenantExportPrefix(tenantId) {
+    return `exports/${tenantId}/`;
+}
+/**
+ * Every storage-key prefix a tenant's binaries can live under. A tenant-destroy
+ * prefix sweep must list ALL of these, not just buildStorageKey()'s
+ * `${tenantId}/` — new key layouts (like tenantExportPrefix) that don't put
+ * the tenant first need adding here too, or a sweep silently stops covering them.
+ */
+export function tenantStoragePrefixes(tenantId) {
+    return [`${tenantId}/`, tenantExportPrefix(tenantId)];
+}

package/dist/files/zip-stream.d.ts

@@ -0,0 +1,31 @@
+import { getTemporal } from "../time/index.js";
+export interface ZipEntry {
+    /** Pfad im ZIP, slash-separated. ASCII (kein UTF-8-Flag gesetzt). */
+    readonly path: string;
+    /** Body als AsyncIterable — kann lazy generated sein (kein Upfront-Memory). */
+    readonly data: AsyncIterable<Uint8Array>;
+    /**
+     * Optional Modification-Time. Default = Now. ZIP nutzt MS-DOS-Format
+     * (2-Sek-Aufloesung). Wer Audit-Trail-Zeitpunkte haben will, setzt
+     * den Generation-Timestamp ueber alle Entries.
+     */
+    readonly mtime?: InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+}
+/**
+ * Erzeugt einen ZIP-Stream als `AsyncIterable<Uint8Array>`. Caller (z.B.
+ * `FileStorageProvider.writeStream`) konsumiert chunk-fuer-chunk, kein
+ * Entry haengt im Memory bis fertig.
+ *
+ * Streaming-Lifecycle pro Entry:
+ *   1. Local File Header (mit CRC32+size=0 als Placeholder; wir nutzen
+ *      KEINE Streaming-Data-Descriptor weil Storage-Provider Random-
+ *      Access nicht garantiert — wir collecten den Body in Memory pro
+ *      Entry um CRC + size **vor** dem Header zu kennen.
+ *      Trade-off: 1 Entry-Body im Memory at-a-time; bei <100 MB Files
+ *      OK, bei >1 GB single-Files braeuchte ZIP64+Streaming-Descriptor).
+ *   2. File Body (raw bytes)
+ * Am Ende:
+ *   3. Central Directory (eine Liste-Entry pro File mit CRC + size)
+ *   4. EOCD (End Of Central Directory)
+ */
+export declare function createZipStream(entries: AsyncIterable<ZipEntry>): AsyncIterable<Uint8Array>;

package/dist/files/zip-stream.js

@@ -0,0 +1,207 @@
+import { getTemporal } from "../time/index.js";
+// Streaming-ZIP-Builder (S2.U3 Atom 3a) — pure-JS, dependency-frei.
+//
+// **Format-Wahl: STORE (kein DEFLATE).** Compression-frei + minimal —
+// fuer User-Data-Export-Bundles akzeptabel weil:
+//   - Storage-Provider (S3/R2) komprimiert eh on-the-wire (HTTP gzip)
+//   - JSON-Snippets sind klein, File-Binaries sind oft schon komprimiert
+//     (PNG/JPG/PDF/MP4/...)
+//   - DEFLATE braucht zlib + buffering pro Entry, killt das Streaming-
+//     Property
+//
+// **Streaming-Property:** Caller gibt `AsyncIterable<ZipEntry>`, jeder
+// Entry hat `data: AsyncIterable<Uint8Array>`. ZIP-Bytes werden
+// chunk-fuer-chunk yieldet — kein Entry haengt im Memory bis er fertig
+// ist. Storage-Provider's writeStream konsumiert direkt durch.
+//
+// **ZIP-Standard:** APPNOTE.TXT v6.3.10 (April 2022). STORE-Method,
+// kein ZIP64 (max 4 GB pro Entry, max 65535 Entries — fuer User-Daten-
+// Exports ausreichend; ZIP64-Support kommt wenn ein realer User mit
+// >4 GB single-File auftaucht). Kein UTF-8-Flag (filenames sind ASCII
+// in unserem Use-Case: "profile.json", "files/<id>.<ext>").
+//
+// **CRC32:** klassisches IEEE-802.3-Polynom (0xEDB88320). Lookup-Table
+// einmal initialisiert + cached.
+const ZIP_VERSION_NEEDED = 20; // 2.0 = STORE
+const ZIP_METHOD_STORE = 0;
+// Local file header signature: 0x04034b50 = "PK\x03\x04"
+const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+// Central directory file header signature: 0x02014b50 = "PK\x01\x02"
+const CENTRAL_DIR_HEADER_SIG = 0x02014b50;
+// End of central directory record signature: 0x06054b50 = "PK\x05\x06"
+const EOCD_SIG = 0x06054b50;
+const VERSION_MADE_BY = 0x031e; // 0x03 = UNIX, 0x1e = ZIP 3.0
+// General Purpose Flag Bit 11 (0x0800) = UTF-8 filename + comment encoding.
+// Wird default-on gesetzt: ASCII ist gueltiges UTF-8, also Win-Win.
+// Ohne Flag interpretieren aeltere ZIP-Tools filenames als CP437 — bei
+// Umlauten ("Bügel.pdf") wird das Mojibake.
+const GENERAL_PURPOSE_FLAGS = 0x0800;
+// External-Attrs (UNIX-Mode in High-Bytes) fuer regulaere Dateien mit
+// 0644-Permissions: `(S_IFREG | 0644) << 16 = 0o100644 << 16 = 0x81a40000`.
+// S_IFREG = 0o100000 (regular file), 0o644 = rw-r--r--. Ohne diese
+// Bits entpackt Info-ZIP mit Mode 0000 (EACCES beim Read).
+const UNIX_REGULAR_FILE_0644 = 0o100644 << 16; // 0x81a40000
+// ZIP-Format-Limits ohne ZIP64-Extension. Atom 3a-Scope ist STORE-only;
+// ZIP64 kommt wenn ein realer User-Export diese Caps reisst.
+const ZIP_MAX_ENTRY_SIZE = 0xffffffff; // uint32 → 4 GB
+const ZIP_MAX_ENTRIES = 0xffff; // uint16 → 65535
+/**
+ * Erzeugt einen ZIP-Stream als `AsyncIterable<Uint8Array>`. Caller (z.B.
+ * `FileStorageProvider.writeStream`) konsumiert chunk-fuer-chunk, kein
+ * Entry haengt im Memory bis fertig.
+ *
+ * Streaming-Lifecycle pro Entry:
+ *   1. Local File Header (mit CRC32+size=0 als Placeholder; wir nutzen
+ *      KEINE Streaming-Data-Descriptor weil Storage-Provider Random-
+ *      Access nicht garantiert — wir collecten den Body in Memory pro
+ *      Entry um CRC + size **vor** dem Header zu kennen.
+ *      Trade-off: 1 Entry-Body im Memory at-a-time; bei <100 MB Files
+ *      OK, bei >1 GB single-Files braeuchte ZIP64+Streaming-Descriptor).
+ *   2. File Body (raw bytes)
+ * Am Ende:
+ *   3. Central Directory (eine Liste-Entry pro File mit CRC + size)
+ *   4. EOCD (End Of Central Directory)
+ */
+export async function* createZipStream(entries) {
+    const centralDirRecords = [];
+    let offset = 0; // Bytes-Counter fuer central-dir entry's local-header-offset
+    for await (const entry of entries) {
+        // Body in Memory collecten — wir brauchen CRC32 + size VOR dem
+        // local-file-header (kein streaming-data-descriptor weil
+        // file-storage-providers nicht zwingend seek-able sind, aber wir
+        // wollen vermeiden dass der konsumierende Storage zwei-pass laesst).
+        const body = await collectBody(entry.data);
+        // Hard-Limit: STORE-Mode ohne ZIP64-Extension cappt bei uint32 (4 GB).
+        // Bei Ueberschreitung wuerde der Integer-Wrap silent ein korruptes
+        // ZIP produzieren (Decoder lesen Muell-Sizes). Lieber early-fail mit
+        // klarer Begruendung — Worker (Atom 3b) fängt das + setzt Job=failed.
+        if (body.byteLength > ZIP_MAX_ENTRY_SIZE) {
+            throw new Error(`ZIP-Entry "${entry.path}" exceeds 4 GB limit (${body.byteLength} bytes). ` +
+                `STORE-mode without ZIP64-extension caps at uint32. ` +
+                `Add ZIP64-support before exporting >4 GB single-files.`);
+        }
+        if (centralDirRecords.length >= ZIP_MAX_ENTRIES) {
+            throw new Error(`ZIP archive exceeds ${ZIP_MAX_ENTRIES}-entry limit. ` +
+                `Add ZIP64-support before exporting >${ZIP_MAX_ENTRIES} entries.`);
+        }
+        const crc = crc32(body);
+        const size = body.byteLength;
+        const filenameBytes = new TextEncoder().encode(entry.path);
+        const dosTime = toDosTime(entry.mtime ?? getTemporal().Now.instant());
+        // Local File Header
+        const lfh = new Uint8Array(30 + filenameBytes.byteLength);
+        const lfhView = new DataView(lfh.buffer);
+        lfhView.setUint32(0, LOCAL_FILE_HEADER_SIG, true);
+        lfhView.setUint16(4, ZIP_VERSION_NEEDED, true);
+        lfhView.setUint16(6, GENERAL_PURPOSE_FLAGS, true);
+        lfhView.setUint16(8, ZIP_METHOD_STORE, true);
+        lfhView.setUint16(10, dosTime.time, true);
+        lfhView.setUint16(12, dosTime.date, true);
+        lfhView.setUint32(14, crc, true);
+        lfhView.setUint32(18, size, true); // compressed size = uncompressed (STORE)
+        lfhView.setUint32(22, size, true);
+        lfhView.setUint16(26, filenameBytes.byteLength, true);
+        lfhView.setUint16(28, 0, true); // extra field length
+        lfh.set(filenameBytes, 30);
+        yield lfh;
+        yield body;
+        // Central-Directory-Eintrag fuer diesen Entry — wir collecten ihn,
+        // emittieren ihn am Ende.
+        const cdh = new Uint8Array(46 + filenameBytes.byteLength);
+        const cdhView = new DataView(cdh.buffer);
+        cdhView.setUint32(0, CENTRAL_DIR_HEADER_SIG, true);
+        cdhView.setUint16(4, VERSION_MADE_BY, true);
+        cdhView.setUint16(6, ZIP_VERSION_NEEDED, true);
+        cdhView.setUint16(8, GENERAL_PURPOSE_FLAGS, true);
+        cdhView.setUint16(10, ZIP_METHOD_STORE, true);
+        cdhView.setUint16(12, dosTime.time, true);
+        cdhView.setUint16(14, dosTime.date, true);
+        cdhView.setUint32(16, crc, true);
+        cdhView.setUint32(20, size, true);
+        cdhView.setUint32(24, size, true);
+        cdhView.setUint16(28, filenameBytes.byteLength, true);
+        cdhView.setUint16(30, 0, true); // extra field length
+        cdhView.setUint16(32, 0, true); // comment length
+        cdhView.setUint16(34, 0, true); // disk number start
+        cdhView.setUint16(36, 0, true); // internal file attrs
+        cdhView.setUint32(38, UNIX_REGULAR_FILE_0644, true);
+        cdhView.setUint32(42, offset, true); // local-header-offset
+        cdh.set(filenameBytes, 46);
+        centralDirRecords.push(cdh);
+        offset += lfh.byteLength + body.byteLength;
+    }
+    // Central Directory: alle entries hintereinander
+    const centralDirStart = offset;
+    let centralDirSize = 0;
+    for (const record of centralDirRecords) {
+        yield record;
+        centralDirSize += record.byteLength;
+    }
+    // EOCD (End Of Central Directory)
+    const eocd = new Uint8Array(22);
+    const eocdView = new DataView(eocd.buffer);
+    eocdView.setUint32(0, EOCD_SIG, true);
+    eocdView.setUint16(4, 0, true); // disk number
+    eocdView.setUint16(6, 0, true); // disk where central-dir starts
+    eocdView.setUint16(8, centralDirRecords.length, true); // entries on this disk
+    eocdView.setUint16(10, centralDirRecords.length, true); // total entries
+    eocdView.setUint32(12, centralDirSize, true);
+    eocdView.setUint32(16, centralDirStart, true);
+    eocdView.setUint16(20, 0, true); // .zip comment length
+    yield eocd;
+}
+async function collectBody(source) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of source) {
+        chunks.push(chunk);
+        total += chunk.byteLength;
+    }
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.byteLength;
+    }
+    return out;
+}
+// CRC32 — IEEE-802.3-Polynom (0xEDB88320, reversed). Lookup-Table einmal.
+let CRC32_TABLE = null;
+function buildCrcTable() {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[i] = c >>> 0;
+    }
+    return table;
+}
+function crc32(data) {
+    if (!CRC32_TABLE)
+        CRC32_TABLE = buildCrcTable();
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.byteLength; i++) {
+        const byte = data[i] ?? 0;
+        const idx = (crc ^ byte) & 0xff;
+        crc = ((CRC32_TABLE[idx] ?? 0) ^ (crc >>> 8)) >>> 0;
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+// MS-DOS Date+Time encoding fuer ZIP-Header.
+// Date: bits 9-15=year-1980, 5-8=month, 0-4=day.
+// Time: bits 11-15=hour, 5-10=minute, 0-4=second/2.
+//
+// **UTC** statt lokaler Zeitzone: in einem DSGVO-Kontext ist der
+// ZIP-mtime Teil des Auskunfts-Artefakts. Verschiedene Server-Zeitzonen
+// wuerden sonst verschiedene mtime-Werte fuer denselben Generation-
+// Instant produzieren — Audit-Drift. UTC ist der Standard fuer alle
+// server-side-Timestamps im Repo (Temporal.Instant ueberall).
+function toDosTime(i) {
+    const dt = i.toZonedDateTimeISO("UTC");
+    const year = dt.year;
+    const date = (((Math.max(year - 1980, 0) & 0x7f) << 9) | ((dt.month & 0x0f) << 5) | (dt.day & 0x1f)) >>> 0;
+    const time = (((dt.hour & 0x1f) << 11) | ((dt.minute & 0x3f) << 5) | ((dt.second >> 1) & 0x1f)) >>> 0;
+    return { date, time };
+}

package/dist/http/index.d.ts

@@ -0,0 +1,2 @@
+export type { EgressPolicy, ResolvedHost } from "@cosmicdrift/kumiko-http";
+export { BlockedHostError, buildPinnedRequest, egress, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "@cosmicdrift/kumiko-http";

package/dist/http/index.js

@@ -0,0 +1 @@
+export { BlockedHostError, buildPinnedRequest, egress, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "@cosmicdrift/kumiko-http";

package/dist/i18n/index.d.ts

@@ -0,0 +1,12 @@
+import type { Registry } from "../engine/types/index.js";
+export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
+export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
+export type I18nOptions = {
+    defaultLocale: string;
+};
+export type I18n = {
+    t(key: string, locale?: string, params?: Readonly<Record<string, unknown>>): string;
+    getAllKeys(): string[];
+};
+export declare function createI18n(registry: Registry, options: I18nOptions): I18n;

package/dist/i18n/index.js

@@ -0,0 +1,27 @@
+import { resolveTranslationValue } from "../ui-types/plural.js";
+export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
+export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
+export function createI18n(registry, options) {
+    const translations = registry.getAllTranslations();
+    const { defaultLocale } = options;
+    return {
+        t(key, locale, params) {
+            const entry = translations[key];
+            if (!entry)
+                return key;
+            const requestedLocale = locale ?? defaultLocale;
+            // Plural category selection needs the locale the value actually came
+            // from, not the requested one — falling back to defaultLocale must
+            // apply defaultLocale's plural rules to that defaultLocale text.
+            const hitLocale = entry[requestedLocale] !== undefined ? requestedLocale : defaultLocale;
+            const value = entry[hitLocale];
+            if (value === undefined)
+                return key;
+            return resolveTranslationValue(value, hitLocale, params);
+        },
+        getAllKeys() {
+            return Object.keys(translations);
+        },
+    };
+}

package/dist/i18n/mail-registry.d.ts

@@ -0,0 +1,7 @@
+import { type TranslationValue } from "../ui-types/plural.js";
+export declare function registerMailTranslations(locale: string, bundle: Readonly<Record<string, TranslationValue>>): void;
+export declare function hasMailTranslations(locale: string): boolean;
+export declare function mailT(locale: string, key: string, params?: Readonly<Record<string, string | number>>): string;
+/** Locale key mailT would actually use (exact → root → en). Use for appUrl
+ *  path negotiation so the link language matches the rendered mail body. */
+export declare function resolveMailLocale(locale: string): string;

package/dist/i18n/mail-registry.js

@@ -0,0 +1,34 @@
+import { resolveTranslationValue } from "../ui-types/plural.js";
+const tables = new Map();
+export function registerMailTranslations(locale, bundle) {
+    const prev = tables.get(locale) ?? {};
+    tables.set(locale, { ...prev, ...bundle });
+}
+export function hasMailTranslations(locale) {
+    const root = locale.split("-")[0] ?? locale;
+    return tables.has(locale) || tables.has(root);
+}
+export function mailT(locale, key, params) {
+    const root = locale.split("-")[0] ?? locale;
+    // Plural category selection needs the locale the value actually came
+    // from, not the requested one — a `pl` bundle falling back to `en`
+    // must apply English plural rules to that `en` text.
+    for (const localeToTry of [locale, root, "en"]) {
+        const value = tables.get(localeToTry)?.[key];
+        if (value !== undefined)
+            return resolveTranslationValue(value, localeToTry, params);
+    }
+    return key;
+}
+/** Locale key mailT would actually use (exact → root → en). Use for appUrl
+ *  path negotiation so the link language matches the rendered mail body. */
+export function resolveMailLocale(locale) {
+    const root = locale.split("-")[0] ?? locale;
+    if (tables.has(locale))
+        return locale;
+    if (tables.has(root))
+        return root;
+    if (tables.has("en"))
+        return "en";
+    return "en";
+}

package/dist/i18n/request-locale.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_LOCALE = "en";
+export declare function isValidLocaleTag(value: string): boolean;
+/** BCP-47 is case-insensitive; canonicalize the primary subtag to lowercase
+ *  so registry lookups (`mailT`, `hasMailTranslations`) hit registered keys. */
+export declare function canonicalizeLocaleTag(tag: string): string;
+/**
+ * Picks the best well-formed tag from an Accept-Language header (RFC 9110
+ * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
+ * breaks ties), and returns the first tag that passes isValidLocaleTag.
+ * Tags with q=0 (explicitly excluded) are dropped entirely.
+ */
+export declare function pickAcceptLanguage(header: string | undefined): string | undefined;
+/**
+ * Request-layer resolution: an explicit, validated X-Locale header wins;
+ * otherwise the best Accept-Language tag; otherwise undefined — no signal
+ * from this request, callers fall back further (the app's boot-configured
+ * defaultLocale, then DEFAULT_LOCALE — see dispatch-shared.ts).
+ */
+export declare function resolveHeaderLocale(options: {
+    readonly headerLocale?: string;
+    readonly acceptLanguage?: string;
+}): string | undefined;