@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/http/utils/metaTags.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Symbol-keyed metadata tags that middleware factories attach to their
+ * returned `MiddlewareHandler` so `createApp` can pick them up at route-
+ * registration time and populate the route registry.
+ *
+ * Each tag has a stable type so the registry-extraction logic is type-safe.
+ * Symbol-keyed (rather than string-keyed) so consumer middleware can't
+ * accidentally collide with framework tags.
+ *
+ * Middleware that wants to be discoverable in the registry attaches the tag
+ * via `(handler as Tagged<...>)[SCHEMA_META] = { ... }` after construction.
+ * Code that reads tags uses `getMetaTag(handler, SCHEMA_META)` to safely
+ * extract the value.
+ */
+import type { ZodType } from "zod";
+export declare const SCHEMA_META: unique symbol;
+export declare const AUTH_META: unique symbol;
+export declare const PERMISSION_META: unique symbol;
+export declare const RATE_LIMIT_META: unique symbol;
+export declare const IDEMPOTENCY_META: unique symbol;
+export interface SchemaMeta {
+    target: "json" | "query" | "param" | "header";
+    schema: ZodType;
+    description?: string;
+    example?: unknown;
+}
+export interface AuthMeta {
+    /** `false` when `requireAuth({ optional: true })` was used. */
+    required: boolean;
+    /** Provider name (`"firebase"`, `"clerk"`, etc.) for documentation/observability. */
+    providerName?: string;
+}
+export interface PermissionMeta {
+    permissions: string[];
+}
+export interface RateLimitMeta {
+    windowMs: number;
+    max: number;
+    scope?: string;
+}
+export interface IdempotencyMeta {
+    ttlSec: number;
+    scope?: string;
+}
+/** Type-safe getter for a tag on a middleware handler. */
+export declare function getMetaTag<T>(handler: unknown, tag: symbol): T | undefined;
+/** Type-safe setter — middleware factories use this to tag their result. */
+export declare function setMetaTag<T>(handler: object, tag: symbol, value: T): void;
+//# sourceMappingURL=metaTags.d.ts.map

package/lib/http/utils/metaTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaTags.d.ts","sourceRoot":"","sources":["../../../src/http/utils/metaTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,eAAO,MAAM,WAAW,eAAqC,CAAC;AAC9D,eAAO,MAAM,SAAS,eAAmC,CAAC;AAC1D,eAAO,MAAM,eAAe,eAAyC,CAAC;AACtE,eAAO,MAAM,eAAe,eAAyC,CAAC;AACtE,eAAO,MAAM,gBAAgB,eAA0C,CAAC;AAExE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAI1E;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAE1E"}

package/lib/http/utils/metaTags.js

@@ -0,0 +1,32 @@
+/**
+ * Symbol-keyed metadata tags that middleware factories attach to their
+ * returned `MiddlewareHandler` so `createApp` can pick them up at route-
+ * registration time and populate the route registry.
+ *
+ * Each tag has a stable type so the registry-extraction logic is type-safe.
+ * Symbol-keyed (rather than string-keyed) so consumer middleware can't
+ * accidentally collide with framework tags.
+ *
+ * Middleware that wants to be discoverable in the registry attaches the tag
+ * via `(handler as Tagged<...>)[SCHEMA_META] = { ... }` after construction.
+ * Code that reads tags uses `getMetaTag(handler, SCHEMA_META)` to safely
+ * extract the value.
+ */
+export const SCHEMA_META = Symbol.for("ship-api.schema-meta");
+export const AUTH_META = Symbol.for("ship-api.auth-meta");
+export const PERMISSION_META = Symbol.for("ship-api.permission-meta");
+export const RATE_LIMIT_META = Symbol.for("ship-api.rate-limit-meta");
+export const IDEMPOTENCY_META = Symbol.for("ship-api.idempotency-meta");
+/** Type-safe getter for a tag on a middleware handler. */
+export function getMetaTag(handler, tag) {
+    if (handler === null || handler === undefined)
+        return undefined;
+    if (typeof handler !== "function" && typeof handler !== "object")
+        return undefined;
+    return handler[tag];
+}
+/** Type-safe setter — middleware factories use this to tag their result. */
+export function setMetaTag(handler, tag, value) {
+    handler[tag] = value;
+}
+//# sourceMappingURL=metaTags.js.map

package/lib/http/utils/metaTags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaTags.js","sourceRoot":"","sources":["../../../src/http/utils/metaTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC9D,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AACtE,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AA+BxE,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAI,OAAgB,EAAE,GAAW;IACzD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChE,IAAI,OAAO,OAAO,KAAK,UAAU,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACnF,OAAQ,OAAyC,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAI,OAAe,EAAE,GAAW,EAAE,KAAQ;IACjE,OAA6B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAC9C,CAAC"}

package/lib/http/utils/publicSuffix.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `publicSuffix` — defensive eTLD table for cookie-domain validation.
+ *
+ * A *public suffix* (also called eTLD — "effective TLD") is the level
+ * at which independent organizations register subdomains. Setting a
+ * cookie `Domain` attribute on a public suffix leaks the cookie to
+ * every site registered under that suffix; browsers SHOULD reject it
+ * but historically did not, and tools / WAFs that proxy cookies don't
+ * always honor the rule.
+ *
+ * The defense is simple: refuse to set a cookie whose `domain`
+ * attribute *is* a known public suffix. `domain: ".com"` rejects;
+ * `domain: ".example.com"` accepts.
+ *
+ * Coverage in this table is **conservative**: it lists the gTLDs and
+ * common country-code patterns that real consumer apps interact with.
+ * It is not the full Mozilla PSL — that's ~10 000 entries and ships
+ * via `tldts` for adopters who want full coverage. Swapping in `tldts`
+ * is a one-commit follow-up under P1/P2 if maintenance proves painful.
+ * Exotic country TLDs not in this table receive permissive treatment
+ * (accepted) — the framework default of "no `domain` attribute set"
+ * remains the right secure default, and this validator only fires
+ * when the consumer explicitly overrides.
+ */
+/**
+ * Test whether a cookie-domain configuration value would leak the
+ * cookie to every site under a public suffix. Returns `null` when
+ * the value is safe (or empty), otherwise an explanatory string the
+ * caller folds into the thrown error message.
+ */
+export declare function checkCookieDomainAgainstPublicSuffix(domain: string | undefined): string | null;
+/** Exposed for tests; do not depend on this outside the framework. */
+export declare const _publicSuffixSet: ReadonlySet<string>;
+//# sourceMappingURL=publicSuffix.d.ts.map

package/lib/http/utils/publicSuffix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicSuffix.d.ts","sourceRoot":"","sources":["../../../src/http/utils/publicSuffix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA4NH;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAgC9F;AAED,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,qBAAkB,CAAC"}

package/lib/http/utils/publicSuffix.js

@@ -0,0 +1,276 @@
+/**
+ * `publicSuffix` — defensive eTLD table for cookie-domain validation.
+ *
+ * A *public suffix* (also called eTLD — "effective TLD") is the level
+ * at which independent organizations register subdomains. Setting a
+ * cookie `Domain` attribute on a public suffix leaks the cookie to
+ * every site registered under that suffix; browsers SHOULD reject it
+ * but historically did not, and tools / WAFs that proxy cookies don't
+ * always honor the rule.
+ *
+ * The defense is simple: refuse to set a cookie whose `domain`
+ * attribute *is* a known public suffix. `domain: ".com"` rejects;
+ * `domain: ".example.com"` accepts.
+ *
+ * Coverage in this table is **conservative**: it lists the gTLDs and
+ * common country-code patterns that real consumer apps interact with.
+ * It is not the full Mozilla PSL — that's ~10 000 entries and ships
+ * via `tldts` for adopters who want full coverage. Swapping in `tldts`
+ * is a one-commit follow-up under P1/P2 if maintenance proves painful.
+ * Exotic country TLDs not in this table receive permissive treatment
+ * (accepted) — the framework default of "no `domain` attribute set"
+ * remains the right secure default, and this validator only fires
+ * when the consumer explicitly overrides.
+ */
+const PUBLIC_SUFFIXES = new Set([
+    // ─── gTLDs (single label) ────────────────────────────────────────
+    "com",
+    "net",
+    "org",
+    "edu",
+    "gov",
+    "mil",
+    "int",
+    "info",
+    "biz",
+    "name",
+    "pro",
+    "cc",
+    "io",
+    "dev",
+    "ai",
+    "co",
+    "app",
+    "me",
+    "tv",
+    "xyz",
+    "tech",
+    "online",
+    "store",
+    "shop",
+    "site",
+    "top",
+    "live",
+    "world",
+    "today",
+    "news",
+    "social",
+    "digital",
+    "cloud",
+    "link",
+    "ly",
+    "to",
+    "nu",
+    "tk",
+    "team",
+    "studio",
+    "design",
+    "page",
+    "blog",
+    "host",
+    "space",
+    "fun",
+    "agency",
+    "club",
+    // ─── ccTLDs (single label, 2 letters — the common ones) ─────────
+    "us",
+    "uk",
+    "ca",
+    "au",
+    "nz",
+    "de",
+    "fr",
+    "es",
+    "it",
+    "nl",
+    "pl",
+    "ru",
+    "jp",
+    "cn",
+    "kr",
+    "hk",
+    "tw",
+    "sg",
+    "my",
+    "th",
+    "vn",
+    "ph",
+    "id",
+    "in",
+    "br",
+    "mx",
+    "ar",
+    "cl",
+    "pe",
+    "za",
+    "ng",
+    "eg",
+    "sa",
+    "ae",
+    "il",
+    "tr",
+    "gr",
+    "pt",
+    "ie",
+    "dk",
+    "no",
+    "se",
+    "fi",
+    "ch",
+    "at",
+    "be",
+    "cz",
+    "hu",
+    "ro",
+    "ua",
+    "bg",
+    "sk",
+    "si",
+    "hr",
+    "lt",
+    "lv",
+    "ee",
+    "is",
+    "lu",
+    "mt",
+    "cy",
+    "li",
+    "md",
+    "by",
+    "rs",
+    "ba",
+    "mk",
+    "al",
+    "ge",
+    "am",
+    "az",
+    "kz",
+    "uz",
+    "kg",
+    "ke",
+    "tz",
+    "ug",
+    "zw",
+    "ma",
+    "tn",
+    "dz",
+    // ─── Multi-label eTLDs (common public-registration patterns) ────
+    "co.uk",
+    "co.jp",
+    "co.kr",
+    "co.nz",
+    "co.za",
+    "co.in",
+    "co.id",
+    "co.il",
+    "co.th",
+    "co.ma",
+    "co.ke",
+    "co.ug",
+    "co.zw",
+    "co.tz",
+    "com.au",
+    "com.br",
+    "com.mx",
+    "com.ar",
+    "com.cn",
+    "com.hk",
+    "com.sg",
+    "com.my",
+    "com.ph",
+    "com.vn",
+    "com.tr",
+    "com.tw",
+    "com.pl",
+    "com.ua",
+    "com.ru",
+    "com.sa",
+    "com.ng",
+    "com.eg",
+    "com.pe",
+    "com.ec",
+    "com.uy",
+    "com.bo",
+    "com.py",
+    "com.gt",
+    "com.es",
+    "com.fr",
+    "ac.uk",
+    "gov.uk",
+    "org.uk",
+    "net.uk",
+    "sch.uk",
+    "mod.uk",
+    "plc.uk",
+    "ltd.uk",
+    "me.uk",
+    "ne.jp",
+    "or.jp",
+    "ad.jp",
+    "ac.jp",
+    "gov.jp",
+    "lg.jp",
+    "go.jp",
+    "gov.au",
+    "edu.au",
+    "org.au",
+    "asn.au",
+    "id.au",
+    "net.au",
+    "ac.nz",
+    "co.nz",
+    "gen.nz",
+    "geek.nz",
+    "kiwi.nz",
+    "maori.nz",
+    "net.nz",
+    "org.nz",
+    "school.nz",
+    "edu.cn",
+    "gov.cn",
+    "net.cn",
+    "org.cn",
+    "ac.cn",
+    "edu.hk",
+    "gov.hk",
+    "net.hk",
+    "org.hk",
+    "idv.hk",
+]);
+/**
+ * Test whether a cookie-domain configuration value would leak the
+ * cookie to every site under a public suffix. Returns `null` when
+ * the value is safe (or empty), otherwise an explanatory string the
+ * caller folds into the thrown error message.
+ */
+export function checkCookieDomainAgainstPublicSuffix(domain) {
+    if (domain == null)
+        return null;
+    const trimmed = domain.trim();
+    if (trimmed.length === 0)
+        return null;
+    // Strip a single leading dot — `.example.com` and `example.com`
+    // mean the same thing to modern browsers (the leading-dot syntax is
+    // legacy compatibility).
+    const noLeadingDot = trimmed.startsWith(".") ? trimmed.slice(1) : trimmed;
+    const noTrailingDot = noLeadingDot.endsWith(".") ? noLeadingDot.slice(0, -1) : noLeadingDot;
+    if (noTrailingDot.length === 0) {
+        return "empty domain after normalization";
+    }
+    const normalized = noTrailingDot.toLowerCase();
+    // Reject if the value is itself a known public suffix — applies to
+    // both single-label (`com`, `uk`) and multi-label (`co.uk`, `com.au`)
+    // entries. The "single dotless input is a host name" intuition only
+    // holds for hosts NOT in the eTLD set; common gTLDs and ccTLDs would
+    // otherwise sneak through.
+    if (PUBLIC_SUFFIXES.has(normalized)) {
+        return (`"${trimmed}" is a public suffix (eTLD). A cookie with this ` +
+            `Domain attribute would be sent to every site under it, allowing ` +
+            `cross-tenant session leakage. Use a more specific domain — e.g. ` +
+            `".your-org.${normalized}" or "tenant.your-org.${normalized}".`);
+    }
+    return null;
+}
+/** Exposed for tests; do not depend on this outside the framework. */
+export const _publicSuffixSet = PUBLIC_SUFFIXES;
+//# sourceMappingURL=publicSuffix.js.map

package/lib/http/utils/publicSuffix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicSuffix.js","sourceRoot":"","sources":["../../../src/http/utils/publicSuffix.ts"],"names":[],"mappings":"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"}

package/lib/http/utils/uploads.d.ts

@@ -0,0 +1,92 @@
+import type { Context } from "hono";
+import { type ZodType, z } from "zod";
+/**
+ * `parseUpload(c, schema)` — Web-Standards file-upload helper.
+ *
+ * Replaces v3's Multer integration. Reads `c.req.parseBody({ all: true })`,
+ * validates against a Zod schema, returns the typed result. File fields
+ * use `fileSchema({ maxBytes, mimeTypes })` (below) which validates size
+ * and MIME via *magic bytes* (not the upload's claimed Content-Type — that
+ * can be spoofed).
+ *
+ * **Memory model — be honest**: Hono's `parseBody()` reads the entire
+ * multipart body into memory before this function returns, capped by
+ * `app.use(bodyLimit({ maxSize: ... }))` if applied (default Hono is
+ * effectively unbounded — *always* configure a body limit for upload
+ * routes). For true streaming uploads, drop down to
+ * `c.req.raw.body` (a `ReadableStream`) and pipe directly to S3/GCS/disk.
+ *
+ * Usage:
+ * ```ts
+ * import { z } from "zod";
+ * import { parseUpload, fileSchema } from "@sixthsummit/ship-api/http/utils/uploads";
+ *
+ * const schema = z.object({
+ *   avatar: fileSchema({ maxBytes: 5_000_000, mimeTypes: ["image/png", "image/jpeg"] }),
+ *   description: z.string().max(500),
+ * });
+ *
+ * app.post("/profile", requireAuth({ provider }), async (c) => {
+ *   const body = await parseUpload(c, schema);
+ *   await storage.put(`avatars/${user.id}`, body.avatar);
+ *   await profileService.update(user.id, { description: body.description });
+ *   return c.json({ ok: true });
+ * });
+ * ```
+ *
+ * Validation errors throw `ValidationError` (mapped by `registerErrorHandlers`
+ * to 400), preserving the AppError taxonomy.
+ */
+export declare function parseUpload<S extends ZodType>(c: Context, schema: S): Promise<z.infer<S>>;
+export interface FileSchemaOptions {
+    /** Maximum file size in bytes. Files larger than this fail validation. */
+    maxBytes?: number;
+    /**
+     * Permitted MIME types validated via magic bytes (NOT the client-supplied
+     * Content-Type — that's trivially spoofable). Validation uses the
+     * `file-type` package. If omitted, MIME is not checked.
+     */
+    mimeTypes?: readonly string[];
+    /**
+     * Optional override for the magic-byte detector. Defaults to
+     * `file-type`'s `fileTypeFromBuffer`. Useful for tests or to plug in a
+     * stricter / different detector.
+     */
+    detectMime?: (file: File) => Promise<string | undefined>;
+    /**
+     * **F20 — explicit replacement for `allowUndetectedMime`.** When the
+     * magic-byte detector returns `undefined` (the file's bytes don't
+     * match any known type), skip the `mimeTypes` allowlist check and
+     * accept the file. Same behavior as the legacy `allowUndetectedMime`
+     * but the name spells out the permissive semantics — adopters
+     * reading "skip MIME validation for undetected files" can't
+     * mistake it for "validate everything defensively."
+     *
+     * Default `false` (fail closed). Set `true` when accepting CSV /
+     * JSON / generic binary blobs that lack distinctive magic bytes.
+     */
+    skipMimeValidationForUndetected?: boolean;
+    /**
+     * **F20 — default-deny escalation.** When `true`, reject any file
+     * whose magic bytes can't be classified, *regardless of whether
+     * `mimeTypes` is set*. Without this, a `parseUpload` call with no
+     * `mimeTypes` allowlist accepts everything — including files with
+     * no detectable signature that an attacker could pass off as
+     * legitimate text-but-aren't payloads (SVG-XSS staging, etc.).
+     * Default `false` for backwards compatibility.
+     */
+    requireDetectableMime?: boolean;
+    /**
+     * @deprecated since v4.0.0-alpha.4 (F20). Renamed to
+     * `skipMimeValidationForUndetected` for explicit semantics. Setting
+     * this still works for one minor cycle but emits a one-time
+     * `console.warn`. Will be removed in v4.1.0.
+     */
+    allowUndetectedMime?: boolean;
+}
+export declare function fileSchema(opts?: FileSchemaOptions): ZodType<File>;
+/** Exposed for tests; do not depend on this outside the framework. */
+export declare const _F20Internals: {
+    emittedDeprecationWarnings: Set<string>;
+};
+//# sourceMappingURL=uploads.d.ts.map

package/lib/http/utils/uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../../src/http/utils/uploads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,wBAAsB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAW/F;AAMD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AA0BD,wBAAgB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDtE;AAED,sEAAsE;AACtE,eAAO,MAAM,aAAa;;CAAiC,CAAC"}

package/lib/http/utils/uploads.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { ValidationError } from "../errors/ValidationError.js";
+/**
+ * `parseUpload(c, schema)` — Web-Standards file-upload helper.
+ *
+ * Replaces v3's Multer integration. Reads `c.req.parseBody({ all: true })`,
+ * validates against a Zod schema, returns the typed result. File fields
+ * use `fileSchema({ maxBytes, mimeTypes })` (below) which validates size
+ * and MIME via *magic bytes* (not the upload's claimed Content-Type — that
+ * can be spoofed).
+ *
+ * **Memory model — be honest**: Hono's `parseBody()` reads the entire
+ * multipart body into memory before this function returns, capped by
+ * `app.use(bodyLimit({ maxSize: ... }))` if applied (default Hono is
+ * effectively unbounded — *always* configure a body limit for upload
+ * routes). For true streaming uploads, drop down to
+ * `c.req.raw.body` (a `ReadableStream`) and pipe directly to S3/GCS/disk.
+ *
+ * Usage:
+ * ```ts
+ * import { z } from "zod";
+ * import { parseUpload, fileSchema } from "@sixthsummit/ship-api/http/utils/uploads";
+ *
+ * const schema = z.object({
+ *   avatar: fileSchema({ maxBytes: 5_000_000, mimeTypes: ["image/png", "image/jpeg"] }),
+ *   description: z.string().max(500),
+ * });
+ *
+ * app.post("/profile", requireAuth({ provider }), async (c) => {
+ *   const body = await parseUpload(c, schema);
+ *   await storage.put(`avatars/${user.id}`, body.avatar);
+ *   await profileService.update(user.id, { description: body.description });
+ *   return c.json({ ok: true });
+ * });
+ * ```
+ *
+ * Validation errors throw `ValidationError` (mapped by `registerErrorHandlers`
+ * to 400), preserving the AppError taxonomy.
+ */
+export async function parseUpload(c, schema) {
+    // `parseBody({ all: true })` is required for fields with multiple values
+    // (an upload field with multiple files surfaces as `string | File | (string | File)[]`).
+    const raw = await c.req.parseBody({ all: true });
+    const result = await schema.safeParseAsync(raw);
+    if (!result.success) {
+        const first = result.error.issues[0];
+        const path = first?.path?.length ? first.path.join(".") : "upload";
+        throw new ValidationError(`${path}: ${first?.message ?? "Invalid upload"}`);
+    }
+    return result.data;
+}
+async function defaultDetectMime(file) {
+    // file-type's recommended buffer size is 4100 bytes; the package only
+    // looks at the leading bytes for its signatures. Slicing avoids reading
+    // the whole file when only the head matters.
+    const head = await file.slice(0, 4100).arrayBuffer();
+    const { fileTypeFromBuffer } = await import("file-type");
+    const result = await fileTypeFromBuffer(new Uint8Array(head));
+    return result?.mime;
+}
+/**
+ * Tracks deprecation warnings emitted in the current process so the
+ * one-time `console.warn` (F20) doesn't spam logs on a hot upload
+ * path. Module-level set — wide enough scope to survive multiple
+ * `fileSchema` constructions, narrow enough to reset per process.
+ */
+const emittedDeprecationWarnings = new Set();
+function warnDeprecatedOnce(key, message) {
+    if (emittedDeprecationWarnings.has(key))
+        return;
+    emittedDeprecationWarnings.add(key);
+    console.warn(`[ship-api/uploads] deprecation: ${message}`);
+}
+export function fileSchema(opts = {}) {
+    // F20: resolve the rename + deprecation. Either explicit option wins;
+    // the legacy `allowUndetectedMime` still works for one minor cycle.
+    const skipForUndetected = opts.skipMimeValidationForUndetected ?? opts.allowUndetectedMime ?? false;
+    if (opts.allowUndetectedMime !== undefined) {
+        warnDeprecatedOnce("allowUndetectedMime", "`allowUndetectedMime` is deprecated — rename to " +
+            "`skipMimeValidationForUndetected` (same semantics, clearer name). " +
+            "The old name will be removed in v4.1.0.");
+    }
+    const requireDetectable = opts.requireDetectableMime ?? false;
+    return z
+        .instanceof(File, { message: "Expected an uploaded file" })
+        .superRefine(async (file, ctx) => {
+        if (opts.maxBytes !== undefined && file.size > opts.maxBytes) {
+            ctx.addIssue({
+                code: "custom",
+                message: `File exceeds maximum size of ${opts.maxBytes} bytes (got ${file.size})`,
+            });
+            return;
+        }
+        const detected = await (opts.detectMime ?? defaultDetectMime)(file);
+        // F20: explicit default-deny escalation. Fires regardless of
+        // whether `mimeTypes` is set, so a no-allowlist `parseUpload`
+        // can still reject magic-byte-undetectable files.
+        if (requireDetectable && !detected) {
+            ctx.addIssue({
+                code: "custom",
+                message: "File magic bytes could not be classified (requireDetectableMime: true)",
+            });
+            return;
+        }
+        if (opts.mimeTypes && opts.mimeTypes.length > 0) {
+            if (!detected) {
+                if (!skipForUndetected) {
+                    ctx.addIssue({
+                        code: "custom",
+                        message: "Could not determine file type from contents",
+                    });
+                }
+                return;
+            }
+            if (!opts.mimeTypes.includes(detected)) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `MIME type "${detected}" not allowed (permitted: ${opts.mimeTypes.join(", ")})`,
+                });
+            }
+        }
+    });
+}
+/** Exposed for tests; do not depend on this outside the framework. */
+export const _F20Internals = { emittedDeprecationWarnings };
+//# sourceMappingURL=uploads.js.map

package/lib/http/utils/uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["../../../src/http/utils/uploads.ts"],"names":[],"mappings":"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"}