@ultimat3/storage 1.0.0

package/src/errors.ts

@@ -0,0 +1,153 @@
+// The X_* codes owned by @ultimat3/storage. Every `fix` is an exact edit or command: a
+// rejected upload must tell the caller which constraint fired and where that constraint is
+// configured, or the caller retries the same bytes forever.
+
+import { errorDocsUrl, registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const STORAGE_OWNED_ERROR_CODES = [
+  'X_STORAGE_DISK_UNKNOWN',
+  'X_STORAGE_NOT_FOUND',
+  'X_STORAGE_PATH_UNSAFE',
+  'X_STORAGE_TOO_LARGE',
+  'X_STORAGE_TYPE_REJECTED',
+  'X_STORAGE_CHECKSUM_MISMATCH',
+] as const;
+
+/**
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `storageNotImplemented()` throws it and this package
+ * keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
+ * `X_IMAGE_UNSUPPORTED` / `X_IMAGE_DECODE_FAILED` are core's too and surface unwrapped (`image.ts`).
+ */
+export const STORAGE_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+
+/** Every code storage can throw through `StorageError`: the owned ones plus the borrowed one. */
+export const STORAGE_ERROR_CODES = [
+  ...STORAGE_OWNED_ERROR_CODES,
+  ...STORAGE_BORROWED_ERROR_CODES,
+] as const;
+
+export type StorageOwnedErrorCode = (typeof STORAGE_OWNED_ERROR_CODES)[number];
+export type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[number];
+
+export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string>> = {
+  X_STORAGE_DISK_UNKNOWN: 'no disk with that name is configured',
+  X_STORAGE_NOT_FOUND: 'no object at that key',
+  X_STORAGE_PATH_UNSAFE: 'object key escapes its prefix',
+  X_STORAGE_TOO_LARGE: 'payload exceeds the upload size limit',
+  X_STORAGE_TYPE_REJECTED: 'content type is not allowed for this upload',
+  X_STORAGE_CHECKSUM_MISMATCH: 'bytes do not match the declared checksum',
+};
+
+// One unconditional call, so a second package claiming one of storage's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(STORAGE_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+export interface StorageErrorInit {
+  readonly code: StorageErrorCode;
+  readonly cause: string;
+  readonly fix: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export class StorageError extends UltimateError {
+  override readonly name = 'StorageError';
+
+  constructor(init: StorageErrorInit) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: errorDocsUrl(init.code),
+      meta: init.meta,
+    });
+  }
+}
+
+export function isStorageError(value: unknown): value is StorageError {
+  return value instanceof StorageError;
+}
+
+export const diskUnknown = (name: string, configured: readonly string[]): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_DISK_UNKNOWN',
+    cause: `no disk named "${name}" (configured: ${
+      configured.length > 0 ? configured.join(', ') : 'none'
+    })`,
+    fix: `add "${name}" to storage.disks in app.config.ts, or call disk('${
+      configured[0] ?? 'local'
+    }')`,
+    meta: { name, configured },
+  });
+
+/**
+ * The `fix` is the shipped API call, not a CLI invocation: `x storage ls` is not in the command
+ * registry, so following it lands on `X_CLI_UNKNOWN_COMMAND` — an instruction that costs the
+ * reader a round-trip and teaches them a command that does not exist.
+ */
+export const objectNotFound = (disk: string, key: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_NOT_FOUND',
+    cause: `disk "${disk}" has no object at "${key}"`,
+    fix: `disk('${disk}').list({ prefix: '${key.split('/').slice(0, -1).join('/')}' })`,
+    meta: { disk, key },
+  });
+
+export const pathUnsafe = (key: string, reason: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_PATH_UNSAFE',
+    cause: `key ${JSON.stringify(key)} ${reason}`,
+    fix: 'build the key with scopedKey(orgId, ...parts) — relative, forward slashes, no ".."',
+    meta: { key, reason },
+  });
+
+export const tooLarge = (key: string, bytes: number, maxBytes: number): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `"${key}" is ${bytes}B, over the policy limit of ${maxBytes}B`,
+    fix: `raise maxBytes in the upload policy (uploadPolicy({ maxBytes: ${bytes} })), or compress the file first`,
+    meta: { key, bytes, maxBytes },
+  });
+
+/** The declared type is not on the allowlist at all. */
+export const contentTypeNotAllowed = (
+  key: string,
+  declared: string,
+  allowed: readonly string[],
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared}, which is not in the policy allowlist (${allowed.join(', ')})`,
+    fix: `add '${declared}' to allowedContentTypes in the upload policy, or upload one of: ${allowed.join(', ')}`,
+    meta: { key, declared, allowed },
+  });
+
+/** The bytes say one thing and the client said another — the bytes win. */
+export const contentTypeMismatch = (key: string, declared: string, sniffed: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared} but its magic bytes are ${sniffed}`,
+    fix: `re-upload with Content-Type: ${sniffed}, or upload a genuine ${declared} file`,
+    meta: { key, declared, sniffed },
+  });
+
+export const checksumMismatch = (key: string, declared: string, actual: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_CHECKSUM_MISMATCH',
+    cause: `"${key}" declared sha256 ${declared} but the bytes hash to ${actual}`,
+    fix: 'recompute the checksum over the exact bytes you send, or omit it and let the driver hash',
+    meta: { key, declared, actual },
+  });
+
+/** An interface-complete driver whose remote half is not bound yet. Always carries a fix. */
+export const storageNotImplemented = (feature: string, fix: string): StorageError =>
+  new StorageError({
+    code: 'X_NOT_IMPLEMENTED',
+    cause: `${feature} is declared but not implemented in @ultimat3/storage`,
+    fix,
+    meta: { feature },
+  });

package/src/image.ts

@@ -0,0 +1,148 @@
+// Single responsibility: the image transform contract — deterministic variant keys and srcset
+// math, plus the byte path bound to `@ultimat3/core`'s pipeline. `@ultimat3/seo` builds
+// `<img srcset>` from `srcsetDescriptors()` without decoding a byte, and when it does need the
+// bytes, `transformImage()` returns exactly the size `fitDimensions()` already promised.
+
+import {
+  blurDataUrl,
+  BLUR_PLACEHOLDER_WIDTH as CORE_BLUR_PLACEHOLDER_WIDTH,
+  probeImage,
+  transformImageBytes,
+} from '@ultimat3/core';
+import { assertSafeKey, keyExtname } from './path';
+
+export const IMAGE_FORMATS = ['avif', 'webp', 'jpeg', 'png'] as const;
+export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+
+/** `cover` fills the box and crops the overflow; `contain` fits inside it, no crop. */
+export type ImageFit = 'cover' | 'contain';
+
+export interface ImageTransform {
+  readonly width?: number | undefined;
+  readonly height?: number | undefined;
+  readonly format?: ImageFormat | undefined;
+  /** 1-100. Omitted means the format default (`DEFAULT_QUALITY`). */
+  readonly quality?: number | undefined;
+  readonly fit?: ImageFit | undefined;
+}
+
+export interface ImageSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+export const DEFAULT_QUALITY = 80;
+export const DEFAULT_SRCSET_WIDTHS = [320, 640, 960, 1280, 1920] as const;
+/** Small enough to inline in HTML; big enough to blur convincingly. Core owns the number. */
+export const BLUR_PLACEHOLDER_WIDTH = CORE_BLUR_PLACEHOLDER_WIDTH;
+
+const FORMAT_EXTENSIONS: Readonly<Record<ImageFormat, string>> = {
+  avif: 'avif',
+  webp: 'webp',
+  jpeg: 'jpg',
+  png: 'png',
+};
+
+/**
+ * Derived, not stored: the same source + transform always yields the same key, so a variant
+ * is a cache lookup rather than a database row.
+ */
+export function variantKey(sourceKey: string, transform: ImageTransform): string {
+  const safe = assertSafeKey(sourceKey);
+  const stem = safe.slice(0, safe.length - keyExtname(safe).length);
+  const format = transform.format ?? 'webp';
+  const parts: string[] = [];
+  if (transform.width !== undefined) parts.push(`w${transform.width}`);
+  if (transform.height !== undefined) parts.push(`h${transform.height}`);
+  if (transform.fit !== undefined) parts.push(transform.fit);
+  const quality = transform.quality ?? DEFAULT_QUALITY;
+  if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
+  if (parts.length === 0) parts.push('full');
+  return assertSafeKey(`${stem}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
+}
+
+export interface SrcsetDescriptor {
+  readonly width: number;
+  readonly key: string;
+  /** The `srcset` entry suffix, e.g. `640w`. */
+  readonly descriptor: string;
+}
+
+export interface SrcsetOptions {
+  readonly widths?: readonly number[] | undefined;
+  readonly format?: ImageFormat | undefined;
+  readonly quality?: number | undefined;
+  /** Intrinsic size of the source. Widths above it are dropped — upscaling is never useful. */
+  readonly intrinsic?: ImageSize | undefined;
+}
+
+/** The widths + variant keys `@ultimat3/seo` turns into a `srcset` attribute. */
+export function srcsetDescriptors(
+  sourceKey: string,
+  options: SrcsetOptions = {},
+): readonly SrcsetDescriptor[] {
+  const widths = options.widths ?? DEFAULT_SRCSET_WIDTHS;
+  const max = options.intrinsic?.width;
+  return widths
+    .filter((width) => width > 0 && (max === undefined || width <= max))
+    .map((width) => ({
+      width,
+      key: variantKey(sourceKey, {
+        width,
+        format: options.format ?? 'webp',
+        quality: options.quality,
+      }),
+      descriptor: `${width}w`,
+    }));
+}
+
+/** Aspect-ratio fitting. `cover` rounds up so the box is always fully covered. */
+export function fitDimensions(source: ImageSize, transform: ImageTransform): ImageSize {
+  const ratio = source.height / source.width;
+  const { width, height } = transform;
+  if (width === undefined && height === undefined) return source;
+  if (height === undefined) {
+    const target = Math.min(width ?? source.width, source.width);
+    return { width: target, height: Math.round(target * ratio) };
+  }
+  if (width === undefined) {
+    const target = Math.min(height, source.height);
+    return { width: Math.round(target / ratio), height: target };
+  }
+  // `cover` crops to the exact box; `contain` scales down until both sides fit.
+  if (transform.fit === 'cover') return { width, height };
+  const scale = Math.min(width / source.width, height / source.height);
+  return { width: Math.round(source.width * scale), height: Math.round(source.height * scale) };
+}
+
+/**
+ * Decode, resize, encode — core's pipeline, which encodes **png and jpeg only**. `avif` and
+ * `webp` stay key/`srcset` math: asking for their bytes rejects with core's
+ * `X_IMAGE_UNSUPPORTED` (not re-wrapped — one failure, one code), and producing them means a
+ * CDN or a custom `ImageTransformDriver`. PNG is also the only output that keeps alpha.
+ *
+ * The output box is `fitDimensions()`, always: that is the size `@ultimat3/seo` has already
+ * written into the `<img>` tag, and bytes that disagreed with it would be the layout shift
+ * this whole path exists to prevent.
+ */
+export async function transformImage(
+  bytes: Uint8Array,
+  transform: ImageTransform,
+): Promise<Uint8Array> {
+  // Header read, not a decode — the source size is needed before the box can be chosen.
+  const size = fitDimensions(probeImage(bytes), transform);
+  return transformImageBytes(bytes, {
+    width: size.width,
+    height: size.height,
+    // The box already carries the fitted aspect ratio, so `cover` crops nothing real; it is
+    // what stops a rounded edge leaving a transparent (in JPEG: black) sliver inside it.
+    fit: 'cover',
+    format: transform.format ?? 'webp',
+    quality: transform.quality ?? DEFAULT_QUALITY,
+  });
+}
+
+/** A `data:` URI small enough to inline as the LQIP behind a real image. Always PNG. */
+export async function blurPlaceholder(bytes: Uint8Array): Promise<string> {
+  return blurDataUrl(bytes, BLUR_PLACEHOLDER_WIDTH);
+}

package/src/index.ts

@@ -0,0 +1,111 @@
+// Single responsibility: the public API of @ultimat3/storage. Explicit named exports only —
+// every consumer imports from here, so this list is the package's contract.
+
+export type {
+  ListOptions,
+  ListPage,
+  PutOptions,
+  SignedUrlMethod,
+  SignedUrlOptions,
+  StorageBody,
+  StorageDriver,
+  StorageObject,
+  StorageRead,
+} from './driver';
+export {
+  DEFAULT_CONTENT_TYPE,
+  DEFAULT_LIST_LIMIT,
+  etagOf,
+  sha256Base64,
+  toBytes,
+} from './driver';
+export type { LocalDriverOptions } from './driver-local';
+export { localDriver } from './driver-local';
+export type {
+  S3ClientLike,
+  S3DriverOptions,
+  S3FileLike,
+  S3ListEntryLike,
+  S3ListResultLike,
+  S3StatLike,
+} from './driver-s3';
+export { s3Driver } from './driver-s3';
+export type { StorageErrorCode, StorageErrorInit } from './errors';
+export {
+  checksumMismatch,
+  contentTypeMismatch,
+  contentTypeNotAllowed,
+  diskUnknown,
+  isStorageError,
+  objectNotFound,
+  pathUnsafe,
+  STORAGE_ERROR_CODES,
+  STORAGE_ERROR_TITLES,
+  StorageError,
+  storageNotImplemented,
+  tooLarge,
+} from './errors';
+export type {
+  ImageFit,
+  ImageFormat,
+  ImageSize,
+  ImageTransform,
+  SrcsetDescriptor,
+  SrcsetOptions,
+} from './image';
+export {
+  BLUR_PLACEHOLDER_WIDTH,
+  blurPlaceholder,
+  DEFAULT_QUALITY,
+  DEFAULT_SRCSET_WIDTHS,
+  fitDimensions,
+  IMAGE_FORMATS,
+  srcsetDescriptors,
+  transformImage,
+  variantKey,
+} from './image';
+
+export {
+  assertSafeKey,
+  isSafeKey,
+  isWithinOrg,
+  joinKey,
+  keyDirname,
+  keyExtname,
+  MAX_KEY_LENGTH,
+  ORG_PREFIX,
+  orgPrefix,
+  scopedKey,
+} from './path';
+export type {
+  SignedUrlConstraints,
+  SignedUrlFailure,
+  SignedUrlInput,
+  SignedUrlVerification,
+  VerifySignedUrlInput,
+} from './signed-url';
+export {
+  buildSignedUrl,
+  canonicalRequest,
+  DEFAULT_SIGNED_URL_BASE,
+  DEFAULT_SIGNED_URL_TTL_MS,
+  SIGNED_URL_FAILURES,
+  SIGNED_URL_PARAMS,
+  SIGNED_URL_VERSION,
+  signConstraints,
+  timingSafeEqual,
+  verifySignedUrl,
+} from './signed-url';
+export type { Storage, StorageConfig } from './storage';
+export { defineStorage, disk, resetStorage, storage } from './storage';
+export type { UploadCandidate, UploadPolicy, UploadPolicyInit, ValidatedUpload } from './upload';
+export {
+  contentTypeMatches,
+  DEFAULT_MAX_UPLOAD_BYTES,
+  DOCUMENT_CONTENT_TYPES,
+  IMAGE_CONTENT_TYPES,
+  normalizeContentType,
+  sniffContentType,
+  uploadPolicy,
+  validateUpload,
+} from './upload';

package/src/path.ts

@@ -0,0 +1,99 @@
+// Single responsibility: object keys. Every key that reaches a driver passes through here,
+// because one `..` in a user-supplied filename turns a local disk into arbitrary file write
+// and an S3 disk into a cross-tenant read. Rejection is total: no sanitising, no rewriting —
+// a key that needed fixing was built wrong, and silently fixing it hides the bug.
+
+import { pathUnsafe } from './errors';
+
+/** S3's own limit; keeping local and remote disks interchangeable requires the same ceiling. */
+export const MAX_KEY_LENGTH = 1024;
+export const ORG_PREFIX = 'org';
+
+// `%2e%2e%2f` decodes to `../` in any layer that decodes twice (proxy, then framework).
+const ENCODED_SEPARATOR = /%(?:2e|2f|5c|00)/i;
+
+/** NUL and friends: a C-string API downstream truncates at the NUL and opens a different file. */
+function hasControlByte(key: string): boolean {
+  for (let index = 0; index < key.length; index += 1) {
+    const code = key.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+function unsafeReason(key: string): string | undefined {
+  if (key.length === 0) return 'is empty';
+  if (key.length > MAX_KEY_LENGTH) {
+    return `is ${key.length} chars, over the ${MAX_KEY_LENGTH} limit`;
+  }
+  if (hasControlByte(key)) return 'contains a NUL or control byte';
+  if (key.includes('\\')) return 'contains a backslash';
+  if (key.startsWith('/')) return 'is absolute (leading "/")';
+  if (ENCODED_SEPARATOR.test(key)) return 'contains a percent-encoded separator (%2e/%2f/%5c)';
+  for (const segment of key.split('/')) {
+    if (segment.length === 0) return 'contains an empty segment ("//" or a trailing "/")';
+    if (segment === '.' || segment === '..') return `contains a "${segment}" segment`;
+    if (segment !== segment.trim()) return `has a padded segment ${JSON.stringify(segment)}`;
+  }
+  return undefined;
+}
+
+export function isSafeKey(key: string): boolean {
+  return unsafeReason(key) === undefined;
+}
+
+/** Returns the key unchanged, so it composes: `Bun.file(join(root, assertSafeKey(key)))`. */
+export function assertSafeKey(key: string): string {
+  const reason = unsafeReason(key);
+  if (reason !== undefined) throw pathUnsafe(key, reason);
+  return key;
+}
+
+/**
+ * Join parts into one validated key. Parts may themselves contain `/`; every resulting
+ * segment is checked, so a part of `../other` fails instead of escaping.
+ */
+export function joinKey(...parts: readonly string[]): string {
+  const segments: string[] = [];
+  for (const part of parts) {
+    for (const segment of part.split('/')) segments.push(segment);
+  }
+  return assertSafeKey(segments.join('/'));
+}
+
+/** An org id is exactly one segment. `a/b` would silently widen the tenant namespace. */
+function assertOrgId(orgId: string): string {
+  if (orgId.length === 0) throw pathUnsafe(orgId, 'is an empty org id');
+  if (orgId.includes('/') || orgId.includes('\\')) {
+    throw pathUnsafe(orgId, 'is an org id containing a path separator');
+  }
+  return orgId;
+}
+
+/** `org/<orgId>/` — the tenant boundary, present in every multi-tenant key. */
+export function orgPrefix(orgId: string): string {
+  return `${joinKey(ORG_PREFIX, assertOrgId(orgId))}/`;
+}
+
+/** The only blessed way to build a tenant-scoped key. */
+export function scopedKey(orgId: string, ...parts: readonly string[]): string {
+  return joinKey(ORG_PREFIX, assertOrgId(orgId), ...parts);
+}
+
+/** Guard for read paths: a key handed in by a client must still belong to the actor's org. */
+export function isWithinOrg(key: string, orgId: string): boolean {
+  return isSafeKey(key) && key.startsWith(orgPrefix(orgId));
+}
+
+/** `org/o1/a/b.png` -> `org/o1/a`. Empty for a top-level key. */
+export function keyDirname(key: string): string {
+  const cut = key.lastIndexOf('/');
+  return cut === -1 ? '' : key.slice(0, cut);
+}
+
+/** `a/b.tar.gz` -> `.gz`. Empty when the basename has no dot. */
+export function keyExtname(key: string): string {
+  const base = key.slice(key.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  return dot <= 0 ? '' : base.slice(dot);
+}

package/src/signed-url.ts

@@ -0,0 +1,185 @@
+// Single responsibility: time-limited signed URLs for direct upload and download.
+// The HMAC covers the *constraints* (key, method, expiry, max size, content type), not just
+// the key — otherwise a client that receives a URL for a 2MB PNG edits `?x-max=` and uploads
+// a 2GB executable. Verification never throws and never short-circuits on expiry before the
+// signature, so a forged URL can never learn "the signature was fine, just late".
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import type { SignedUrlMethod } from './driver';
+import { assertSafeKey, isSafeKey } from './path';
+
+export const SIGNED_URL_VERSION = 'v1';
+export const DEFAULT_SIGNED_URL_TTL_MS = 900_000;
+/** The dev server mounts the download/upload route here; S3 disks never use it. */
+export const DEFAULT_SIGNED_URL_BASE = '/_storage';
+
+export const SIGNED_URL_PARAMS = {
+  method: 'x-method',
+  expires: 'x-exp',
+  maxBytes: 'x-max',
+  contentType: 'x-ct',
+  signature: 'x-sig',
+} as const;
+
+export interface SignedUrlConstraints {
+  readonly key: string;
+  readonly method: SignedUrlMethod;
+  /** Epoch ms. */
+  readonly expiresAt: number;
+  readonly maxBytes: number | undefined;
+  readonly contentType: string | undefined;
+}
+
+export interface SignedUrlInput {
+  /** Never a literal in app.config.ts — read it from an env var. */
+  readonly secret: string;
+  readonly key: string;
+  readonly method?: SignedUrlMethod | undefined;
+  readonly expiresInMs?: number | undefined;
+  readonly maxBytes?: number | undefined;
+  readonly contentType?: string | undefined;
+  readonly baseUrl?: string | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+export const SIGNED_URL_FAILURES = [
+  'malformed',
+  'unsafe-key',
+  'signature-mismatch',
+  'expired',
+] as const;
+
+export type SignedUrlFailure = (typeof SIGNED_URL_FAILURES)[number];
+
+export type SignedUrlVerification =
+  | { readonly ok: true; readonly constraints: SignedUrlConstraints }
+  | { readonly ok: false; readonly reason: SignedUrlFailure; readonly detail: string };
+
+/** Newline-separated and order-fixed: an ambiguous canonical form is a forgeable one. */
+export function canonicalRequest(constraints: SignedUrlConstraints): string {
+  return [
+    SIGNED_URL_VERSION,
+    constraints.method,
+    constraints.key,
+    String(constraints.expiresAt),
+    constraints.maxBytes === undefined ? '' : String(constraints.maxBytes),
+    constraints.contentType ?? '',
+  ].join('\n');
+}
+
+const encoder = new TextEncoder();
+
+export async function signConstraints(
+  secret: string,
+  constraints: SignedUrlConstraints,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const mac = await crypto.subtle.sign('HMAC', key, encoder.encode(canonicalRequest(constraints)));
+  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** Length is public (fixed-width hex); the byte comparison must not early-exit. */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return diff === 0;
+}
+
+const trimBase = (base: string): string => base.replace(/\/+$/, '');
+const encodeKey = (key: string): string => key.split('/').map(encodeURIComponent).join('/');
+
+export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
+  const key = assertSafeKey(input.key);
+  const clock = input.clock ?? systemClock;
+  const constraints: SignedUrlConstraints = {
+    key,
+    method: input.method ?? 'GET',
+    expiresAt: clock.now().getTime() + (input.expiresInMs ?? DEFAULT_SIGNED_URL_TTL_MS),
+    maxBytes: input.maxBytes,
+    contentType: input.contentType,
+  };
+  const params = new URLSearchParams();
+  params.set(SIGNED_URL_PARAMS.method, constraints.method);
+  params.set(SIGNED_URL_PARAMS.expires, String(constraints.expiresAt));
+  if (constraints.maxBytes !== undefined) {
+    params.set(SIGNED_URL_PARAMS.maxBytes, String(constraints.maxBytes));
+  }
+  if (constraints.contentType !== undefined) {
+    params.set(SIGNED_URL_PARAMS.contentType, constraints.contentType);
+  }
+  params.set(SIGNED_URL_PARAMS.signature, await signConstraints(input.secret, constraints));
+  const base = trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE);
+  return `${base}/${encodeKey(key)}?${params.toString()}`;
+}
+
+export interface VerifySignedUrlInput {
+  /** Absolute or route-relative — both parse. */
+  readonly url: string;
+  readonly secret: string;
+  readonly baseUrl?: string | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+const fail = (reason: SignedUrlFailure, detail: string): SignedUrlVerification => ({
+  ok: false,
+  reason,
+  detail,
+});
+
+function parseConstraints(url: URL, base: string): SignedUrlConstraints | SignedUrlFailure {
+  if (!url.pathname.startsWith(`${base}/`)) return 'malformed';
+  const key = url.pathname
+    .slice(base.length + 1)
+    .split('/')
+    .map(decodeURIComponent)
+    .join('/');
+  if (!isSafeKey(key)) return 'unsafe-key';
+  const method = url.searchParams.get(SIGNED_URL_PARAMS.method) ?? 'GET';
+  if (method !== 'GET' && method !== 'PUT') return 'malformed';
+  const expiresAt = Number(url.searchParams.get(SIGNED_URL_PARAMS.expires));
+  if (!Number.isSafeInteger(expiresAt) || expiresAt <= 0) return 'malformed';
+  const rawMax = url.searchParams.get(SIGNED_URL_PARAMS.maxBytes);
+  const maxBytes = rawMax === null ? undefined : Number(rawMax);
+  if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {
+    return 'malformed';
+  }
+  return {
+    key,
+    method,
+    expiresAt,
+    maxBytes,
+    contentType: url.searchParams.get(SIGNED_URL_PARAMS.contentType) ?? undefined,
+  };
+}
+
+export async function verifySignedUrl(input: VerifySignedUrlInput): Promise<SignedUrlVerification> {
+  let url: URL;
+  try {
+    url = new URL(input.url, 'http://storage.invalid');
+  } catch {
+    return fail('malformed', `${input.url} is not a URL`);
+  }
+  const signature = url.searchParams.get(SIGNED_URL_PARAMS.signature);
+  if (signature === null) return fail('malformed', `no ${SIGNED_URL_PARAMS.signature} parameter`);
+  const parsed = parseConstraints(url, trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE));
+  if (typeof parsed === 'string') return fail(parsed, `${url.pathname} is not a signable request`);
+
+  const expected = await signConstraints(input.secret, parsed);
+  if (!timingSafeEqual(expected, signature)) {
+    return fail('signature-mismatch', 'the constraints do not match the signature');
+  }
+  const now = (input.clock ?? systemClock).now().getTime();
+  if (now > parsed.expiresAt) {
+    return fail('expired', `expired ${now - parsed.expiresAt}ms ago`);
+  }
+  return { ok: true, constraints: parsed };
+}