@jokerized/decksmith 0.1.0

package/dist/types/server/upload.d.ts

@@ -0,0 +1,107 @@
+/**
+ * What arrives on the socket, treated as hostile.
+ *
+ * Three jobs, in order: get the bytes off the wire without letting the sender
+ * choose how much memory we spend, turn them into a file and a set of fields,
+ * and — if the file is a zip — get its contents onto disk without letting an
+ * entry name decide where "onto disk" is.
+ *
+ * Everything here is pure except `readBody`, which is why the zip half can be
+ * tested against an actually malicious archive with no server running.
+ */
+import type { IncomingMessage } from "node:http";
+/** 20 MB. A paper with its figures is a megabyte or two; ten times that is slack. */
+export declare const MAX_UPLOAD_BYTES: number;
+/**
+ * Caps on the archive AFTER decompression, which is the number that matters:
+ * deflate tops out near 1032:1, so the upload cap alone would allow a 20 MB zip
+ * to become 20 GB. See `readZip` for why the declared sizes are trustworthy
+ * enough to cap on.
+ */
+export interface ZipLimits {
+    maxEntries: number;
+    maxTotalBytes: number;
+    maxEntryBytes: number;
+}
+export declare const ZIP_LIMITS: ZipLimits;
+/** Extensions we will accept as the document itself. */
+export declare const MARKDOWN_EXTS: string[];
+/**
+ * An upload problem the sender can fix, as opposed to a bug. Carries the hint
+ * separately so the API can render "what went wrong" and "what to do" apart.
+ */
+export declare class UploadError extends Error {
+    readonly hint: string;
+    readonly status: number;
+    constructor(message: string, hint: string, status?: number);
+}
+export declare function readBody(req: IncomingMessage, limit?: number): Promise<Buffer>;
+export interface Upload {
+    /** The uploaded file's name as the browser reported it. Never used as a path. */
+    filename: string;
+    bytes: Uint8Array;
+    /** Every non-file field, last one wins. */
+    fields: Record<string, string>;
+}
+/**
+ * multipart/form-data, with no dependency.
+ *
+ * `new Response(body, { headers }).formData()` is undici's parser, which ships
+ * in Node — measured against a hand-built body with a filename containing a
+ * space, a UTF-8 payload and two scalar fields, and it returns a real `File`
+ * with the right bytes. It throws a bare TypeError on a malformed body, which
+ * is not a sentence anyone can act on, so it is translated here.
+ */
+export declare function parseMultipart(body: Buffer, contentType: string): Promise<Upload>;
+/** A zip starts "PK". Asked before unzipping so a PDF reads as a PDF. */
+export declare function looksLikeZip(bytes: Uint8Array): boolean;
+/**
+ * ZIP SLIP. An entry name is attacker-controlled text, not a path, and the only
+ * safe way to treat it is to rebuild the path from segments we have each
+ * inspected. Returns the relative path to write, or `null` when the name cannot
+ * be made safe.
+ *
+ * Rejected, each because it has been used to escape a directory somewhere:
+ * absolute paths; a Windows drive letter or UNC prefix; any `..` segment,
+ * including one hidden behind backslashes, which unzip implementations on
+ * Windows treat as a separator and POSIX ones do not; and NUL, which truncates
+ * the path in any C library the bytes later pass through.
+ *
+ * Note what is NOT a hole: a zip can carry a symlink, and a symlink pointing at
+ * /etc is the other classic escape — but fflate reports entries as bytes and we
+ * write them with `writeFile`, so a symlink entry lands as an ordinary file
+ * containing its target's text. There is no code path here that calls `symlink`.
+ */
+export declare function safeEntryPath(name: string): string | null;
+/** Belt and braces: the joined path must still be inside the root. */
+export declare function insideRoot(root: string, joined: string): boolean;
+export interface ZipContents {
+    /** Safe relative path (posix separators) → bytes. */
+    files: Record<string, Uint8Array>;
+    warnings: string[];
+}
+/**
+ * Unzip within the limits, or refuse.
+ *
+ * Two passes over the central directory. The first decompresses nothing — a
+ * filter returning false skips the inflate — and is where names and sizes are
+ * judged; the second extracts only what the first approved. Splitting them
+ * means a hostile entry is refused before any of the archive has been expanded,
+ * and it keeps the decision out of a callback that runs inside library code.
+ *
+ * MEASURED, because the cap depends on it: fflate allocates exactly the
+ * declared uncompressed size and truncates the inflate to it. An archive whose
+ * header lies — patched to claim 10 bytes for a 5 MB member — yields 10 bytes
+ * of memory and 10 bytes of garbage, not 5 MB. So capping on the declared sizes
+ * is a real memory bound and not a promise the attacker gets to keep. The
+ * post-hoc total below is there for the day that stops being true.
+ */
+export declare function readZip(bytes: Uint8Array, limits?: ZipLimits): ZipContents;
+/**
+ * Which file in the archive is the document.
+ *
+ * Shallowest wins, then a name that says so, then alphabetical — a paper's zip
+ * is usually one markdown at the top and a folder of figures, and when it is
+ * not, "the one nearest the root" is the guess a person would make.
+ */
+export declare function pickMarkdown(files: Record<string, Uint8Array>): string;

package/dist/types/source/assets.d.ts

@@ -0,0 +1,11 @@
+import { type Source } from "../types.js";
+/** Fetch every figure into `dir`, rewrite `src` to the local name, measure it. */
+export declare function fetchFigures(source: Source, dir: string): Promise<Source>;
+/**
+ * Intrinsic size from the file header. Just enough PNG/JPEG/GIF to answer the
+ * one question layout asks — four field reads do not justify a dependency.
+ */
+export declare function imageSize(b: Buffer): {
+    width: number;
+    height: number;
+};

package/dist/types/source/fonts.d.ts

@@ -0,0 +1,15 @@
+export interface FontBundle {
+    /** Belongs at the head of the theme's font stack. */
+    family: string;
+    /** `@font-face` CSS with every `url()` rewritten to a bare name in `dir`. */
+    css: string;
+    /** The woff2 basenames written into `dir`, beside `fonts.css`. */
+    files: string[];
+}
+/** The family a language needs shipped, or null when the renderer supplies one. */
+export declare function familyFor(lang: string): string | null;
+/**
+ * Write `dir/fonts.css` plus its woff2 for `lang`, covering `glyphs`. Returns
+ * null for languages the renderer already resolves, which needs no bundle.
+ */
+export declare function bundleFont(lang: string, glyphs: string, dir: string): Promise<FontBundle | null>;

package/dist/types/source/markdown.d.ts

@@ -0,0 +1,8 @@
+import { type Source } from "../types.js";
+export interface ParseOptions {
+    /** Stable document id. Defaults to a content hash, so re-parsing is idempotent. */
+    id?: string;
+    /** BCP-47 override. Defaults to a script sniff, which is what picks the font. */
+    lang?: string;
+}
+export declare function parseMarkdown(md: string, opts?: ParseOptions): Source;