@ultimat3/storage 1.0.0

package/src/storage.ts

@@ -0,0 +1,76 @@
+// Single responsibility: named disks (Laravel's model) and the one module-level accessor.
+// Call sites name a disk, never a driver — swapping `local` for `s3` in app.config.ts must
+// not touch a single `storage.disk('uploads').put(...)` call.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import type { StorageDriver } from './driver';
+import { diskUnknown } from './errors';
+
+export interface StorageConfig {
+  readonly disks: Readonly<Record<string, StorageDriver>>;
+  /** Disk used when `disk()` is called with no name. Defaults to the first declared disk. */
+  readonly default?: string | undefined;
+}
+
+export interface Storage {
+  readonly defaultDisk: string;
+  readonly diskNames: readonly string[];
+  disk(name?: string): StorageDriver;
+}
+
+let current: Storage | undefined;
+
+/**
+ * Build the disk map and install it as the process-wide storage. There is exactly one, the
+ * same way there is exactly one `app.config.ts` — a second registry is a second source of truth.
+ */
+export function defineStorage(config: StorageConfig): Storage {
+  const names = Object.keys(config.disks);
+  if (names.length === 0) {
+    throw new ConfigInvalidError({
+      cause: 'defineStorage() was called with no disks',
+      fix: "add a disk: defineStorage({ disks: { local: localDriver({ root: '.storage' }) } })",
+    });
+  }
+  const first = names[0] ?? '';
+  const defaultDisk = config.default ?? first;
+  if (!names.includes(defaultDisk)) {
+    throw new ConfigInvalidError({
+      cause: `storage.default is "${defaultDisk}" but the configured disks are: ${names.join(', ')}`,
+      fix: `set storage.default to one of: ${names.join(', ')} in app.config.ts`,
+    });
+  }
+  const storageInstance: Storage = {
+    defaultDisk,
+    diskNames: Object.freeze([...names]),
+    disk(name?: string): StorageDriver {
+      const wanted = name ?? defaultDisk;
+      const driver = config.disks[wanted];
+      if (driver === undefined) throw diskUnknown(wanted, names);
+      return driver;
+    },
+  };
+  current = storageInstance;
+  return storageInstance;
+}
+
+/** The configured storage. Throws rather than lazily inventing a disk behind your back. */
+export function storage(): Storage {
+  if (current === undefined) {
+    throw new ConfigInvalidError({
+      cause: 'storage() was called before defineStorage()',
+      fix: "call defineStorage({ disks: { local: localDriver({ root: '.storage' }) } }) in app.config.ts",
+    });
+  }
+  return current;
+}
+
+/** Shorthand for the common call. `disk()` alone resolves the default disk. */
+export function disk(name?: string): StorageDriver {
+  return storage().disk(name);
+}
+
+/** Test seam: drop the module-level storage so the next test defines its own. */
+export function resetStorage(): void {
+  current = undefined;
+}

package/src/upload.ts

@@ -0,0 +1,193 @@
+// Single responsibility: the constraint policy for direct-to-storage uploads — size,
+// allowlist, checksum — and the content-type sniff that enforces it.
+// WHY sniff: `Content-Type` is attacker-controlled. A `.png` that is really an HTML document
+// is a stored-XSS delivery vehicle the moment any surface serves it back with the declared
+// type, so the magic bytes decide and a contradiction is rejected outright.
+
+import { sha256Base64 } from './driver';
+import { checksumMismatch, contentTypeMismatch, contentTypeNotAllowed, tooLarge } from './errors';
+import { assertSafeKey } from './path';
+
+export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+
+export const IMAGE_CONTENT_TYPES = [
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+] as const;
+
+export const DOCUMENT_CONTENT_TYPES = [
+  'application/pdf',
+  'application/zip',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+] as const;
+
+export interface UploadPolicy {
+  readonly maxBytes: number;
+  readonly allowedContentTypes: readonly string[];
+  /** When true a candidate without a `checksum` is rejected, not silently trusted. */
+  readonly requireChecksum: boolean;
+}
+
+export interface UploadPolicyInit {
+  readonly maxBytes?: number | undefined;
+  readonly allowedContentTypes?: readonly string[] | undefined;
+  readonly requireChecksum?: boolean | undefined;
+}
+
+export function uploadPolicy(init: UploadPolicyInit = {}): UploadPolicy {
+  return {
+    maxBytes: init.maxBytes ?? DEFAULT_MAX_UPLOAD_BYTES,
+    allowedContentTypes: init.allowedContentTypes ?? IMAGE_CONTENT_TYPES,
+    requireChecksum: init.requireChecksum ?? false,
+  };
+}
+
+export interface UploadCandidate {
+  readonly key: string;
+  /** Whatever the client claimed. Trusted for nothing except the error message. */
+  readonly declaredContentType: string;
+  readonly bytes: Uint8Array;
+  /** base64 SHA-256. */
+  readonly checksum?: string | undefined;
+}
+
+export interface ValidatedUpload {
+  readonly key: string;
+  /** Safe to serve: the declared type, but only after the magic bytes agreed with it. */
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+  readonly size: number;
+  readonly checksum: string;
+}
+
+interface MagicRule {
+  readonly type: string;
+  readonly parts: readonly { readonly offset: number; readonly pattern: readonly number[] }[];
+}
+
+const ascii = (text: string): readonly number[] => [...text].map((char) => char.charCodeAt(0));
+
+const MAGIC_RULES: readonly MagicRule[] = [
+  {
+    type: 'image/png',
+    parts: [{ offset: 0, pattern: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }],
+  },
+  { type: 'image/jpeg', parts: [{ offset: 0, pattern: [0xff, 0xd8, 0xff] }] },
+  { type: 'image/gif', parts: [{ offset: 0, pattern: ascii('GIF87a') }] },
+  { type: 'image/gif', parts: [{ offset: 0, pattern: ascii('GIF89a') }] },
+  {
+    type: 'image/webp',
+    parts: [
+      { offset: 0, pattern: ascii('RIFF') },
+      { offset: 8, pattern: ascii('WEBP') },
+    ],
+  },
+  { type: 'application/pdf', parts: [{ offset: 0, pattern: ascii('%PDF-') }] },
+  { type: 'video/mp4', parts: [{ offset: 4, pattern: ascii('ftyp') }] },
+  // Every OOXML document and epub is a zip; the container is as far as magic bytes go.
+  { type: 'application/zip', parts: [{ offset: 0, pattern: [0x50, 0x4b, 0x03, 0x04] }] },
+];
+
+const matches = (bytes: Uint8Array, rule: MagicRule): boolean =>
+  rule.parts.every((part) =>
+    part.pattern.every((byte, index) => bytes[part.offset + index] === byte),
+  );
+
+function sniffText(bytes: Uint8Array): string | undefined {
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return undefined;
+  }
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    const printable = code >= 0x20 || code === 0x09 || code === 0x0a || code === 0x0d;
+    if (!printable) return undefined;
+  }
+  const head = text.slice(0, 512).trimStart().toLowerCase();
+  if (
+    head.startsWith('<!doctype html') ||
+    head.startsWith('<html') ||
+    head.startsWith('<head') ||
+    head.startsWith('<script') ||
+    head.startsWith('<body')
+  ) {
+    return 'text/html';
+  }
+  if (head.startsWith('<svg') || (head.startsWith('<?xml') && head.includes('<svg'))) {
+    return 'image/svg+xml';
+  }
+  return 'text/plain';
+}
+
+/** `undefined` means "no rule recognised it", never "it is fine". */
+export function sniffContentType(bytes: Uint8Array): string | undefined {
+  for (const rule of MAGIC_RULES) {
+    if (matches(bytes, rule)) return rule.type;
+  }
+  return sniffText(bytes);
+}
+
+const ALIASES: Readonly<Record<string, string>> = {
+  'image/jpg': 'image/jpeg',
+  'image/x-png': 'image/png',
+  'application/x-pdf': 'application/pdf',
+};
+
+/** Strip parameters and case: `IMAGE/PNG; charset=binary` and `image/png` are one type. */
+export function normalizeContentType(value: string): string {
+  const base = (value.split(';')[0] ?? '').trim().toLowerCase();
+  return ALIASES[base] ?? base;
+}
+
+const ZIP_CONTAINERS = new Set<string>([...DOCUMENT_CONTENT_TYPES, 'application/epub+zip']);
+const TEXT_FAMILY = new Set([
+  'text/plain',
+  'text/csv',
+  'text/markdown',
+  'application/json',
+  'application/xml',
+  'text/xml',
+]);
+
+/** A generic sniff (zip container, plain text) may stand in for a specific declared type. */
+export function contentTypeMatches(declared: string, sniffed: string): boolean {
+  const type = normalizeContentType(declared);
+  if (type === sniffed) return true;
+  if (sniffed === 'application/zip') return ZIP_CONTAINERS.has(type);
+  if (sniffed === 'text/plain') return TEXT_FAMILY.has(type);
+  return false;
+}
+
+/** Throws the first violated constraint. Order is cheapest-first: size, key, type, checksum. */
+export function validateUpload(
+  candidate: UploadCandidate,
+  policy: UploadPolicy = uploadPolicy(),
+): ValidatedUpload {
+  const key = assertSafeKey(candidate.key);
+  const size = candidate.bytes.byteLength;
+  if (size > policy.maxBytes) throw tooLarge(key, size, policy.maxBytes);
+
+  const declared = normalizeContentType(candidate.declaredContentType);
+  if (!policy.allowedContentTypes.includes(declared)) {
+    throw contentTypeNotAllowed(key, declared, policy.allowedContentTypes);
+  }
+  const sniffed = sniffContentType(candidate.bytes);
+  if (sniffed !== undefined && !contentTypeMatches(declared, sniffed)) {
+    throw contentTypeMismatch(key, declared, sniffed);
+  }
+
+  const checksum = sha256Base64(candidate.bytes);
+  const claimed = candidate.checksum;
+  if (claimed !== undefined && claimed !== checksum) throw checksumMismatch(key, claimed, checksum);
+  if (claimed === undefined && policy.requireChecksum) {
+    throw checksumMismatch(key, 'none', checksum);
+  }
+  return { key, contentType: declared, bytes: candidate.bytes, size, checksum };
+}