@zerotal/core 1.0.0

package/src/router/domain.ts

@@ -0,0 +1,65 @@
+/**
+ * Host-aware routing support for `Router.group({ domain })`.
+ *
+ * A domain pattern like `:tenant.app.com` is compiled into a matcher that both
+ * tests a request's host and extracts the dynamic labels as subdomain params,
+ * exposed on the request via `ctx.subdomains`.
+ */
+
+export interface CompiledDomain {
+  /** The original pattern, e.g. ':tenant.app.com'. */
+  source: string;
+  regex: RegExp;
+  /** Param names in order, e.g. ['tenant']. */
+  params: string[];
+}
+
+/** Compile a domain pattern into a host matcher. `:label` segments are dynamic. */
+export function compileDomain(pattern: string): CompiledDomain {
+  const params: string[] = [];
+  const body = pattern
+    .split(".")
+    .map((segment) => {
+      if (segment.startsWith(":")) {
+        params.push(segment.slice(1));
+        return "([^.]+)";
+      }
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("\\.");
+  return { source: pattern, regex: new RegExp(`^${body}$`, "i"), params };
+}
+
+/**
+ * Match a request host against a compiled domain. The port is ignored.
+ * Returns the extracted subdomain params, or `null` when the host doesn't match.
+ *
+ * @example
+ * matchDomain(compileDomain(':tenant.app.com'), 'acme.app.com'); // { tenant: 'acme' }
+ * matchDomain(compileDomain(':tenant.app.com'), 'app.com');      // null
+ */
+export function matchDomain(compiled: CompiledDomain, host: string): Record<string, string> | null {
+  const hostname = (host.split(":")[0] ?? "").toLowerCase();
+  const match = compiled.regex.exec(hostname);
+  if (!match) return null;
+  const subdomains: Record<string, string> = {};
+  compiled.params.forEach((paramName, index) => {
+    subdomains[paramName] = match[index + 1]!;
+  });
+  return subdomains;
+}
+
+// ── Per-request subdomain store ───────────────────────────────────────────────
+// Set by the router's host dispatcher, read by HttpContext.subdomains.
+
+const _store = new WeakMap<Request, Record<string, string>>();
+
+/** @internal Record the subdomain params extracted for a request; read via {@link getRequestSubdomains}. */
+export function setRequestSubdomains(req: Request, params: Record<string, string>): void {
+  _store.set(req, params);
+}
+
+/** @internal The subdomain params extracted for a request, or `{}` if none were set. */
+export function getRequestSubdomains(req: Request): Record<string, string> {
+  return _store.get(req) ?? {};
+}

package/src/security/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Security primitives for Zerotal (the `@zerotal/core/security` subpath):
+ * {@link Crypt} for `APP_KEY`-keyed AES-256-GCM encryption and {@link Hash} for
+ * argon2id/bcrypt password hashing. Both are zero-config facades — no provider
+ * registration required — that read `APP_KEY` from the environment on first use.
+ *
+ * @example
+ * ```ts
+ * import { Crypt, Hash } from "@zerotal/core/security";
+ *
+ * const token = Crypt.encryptString("secret");
+ * Crypt.decryptString(token); // "secret"
+ *
+ * const digest = await Hash.make("hunter2");
+ * await Hash.verify("hunter2", digest); // true
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { Crypt, CryptKeyMissingError, DecryptionError } from "../crypt/Crypt.ts";
+export { Hash } from "../hash/Hash.ts";
+export type { HashAlgorithm } from "../hash/Hash.ts";

package/src/storage/FakeDisk.ts

@@ -0,0 +1,233 @@
+import type { StorageDriver, PutOptions } from "./types.ts";
+
+/** What {@link FakeDisk} remembers about a stored file. */
+export interface FakeStoredFile {
+  path: string;
+  contents: Uint8Array;
+  contentType: string | undefined;
+  visibility: "public" | "private" | undefined;
+  lastModified: number;
+}
+
+/**
+ * An in-memory storage disk for tests.
+ *
+ * Writing real files to test an upload leaves the suite dependent on a
+ * filesystem it has to clean up — and a test that forgets to passes the second
+ * time for the wrong reason. This keeps everything in a `Map`, so each test
+ * starts empty by construction, and adds the assertions that a plain driver has
+ * no reason to carry.
+ *
+ * Install it with `Storage.fake()`, which swaps it in for a named disk and
+ * returns it.
+ *
+ * @example
+ * const disk = Storage.fake();
+ *
+ * await app.multipart('/avatar', { avatar: fakeFile.image('me.png') });
+ *
+ * disk.assertExists('avatars/me.png');
+ * disk.assertCount(1);
+ */
+export class FakeDisk implements StorageDriver {
+  private readonly _files = new Map<string, FakeStoredFile>();
+
+  /**
+   * @param baseUrl - Prefix returned by {@link url}, so a test can assert on the
+   * URL a controller hands back.
+   */
+  constructor(private readonly baseUrl: string = "/storage") {}
+
+  // ── StorageDriver ─────────────────────────────────────────────────────
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    options: PutOptions = {},
+  ): Promise<void> {
+    this._files.set(_normalise(path), {
+      path: _normalise(path),
+      contents: await _bytes(content),
+      contentType: options.contentType,
+      visibility: options.visibility,
+      lastModified: Date.now(),
+    });
+  }
+
+  async append(path: string, content: string | Uint8Array): Promise<void> {
+    const existing = this._files.get(_normalise(path))?.contents ?? new Uint8Array(0);
+    const added = await _bytes(content);
+    const merged = new Uint8Array(existing.length + added.length);
+    merged.set(existing);
+    merged.set(added, existing.length);
+    await this.put(path, merged);
+  }
+
+  async get(path: string): Promise<string | null> {
+    const file = this._files.get(_normalise(path));
+    return file ? new TextDecoder().decode(file.contents) : null;
+  }
+
+  async stream(path: string): Promise<Blob | null> {
+    const file = this._files.get(_normalise(path));
+    return file ? new Blob([file.contents as BlobPart], { type: file.contentType ?? "" }) : null;
+  }
+
+  async getBuffer(path: string): Promise<Uint8Array | null> {
+    return this._files.get(_normalise(path))?.contents ?? null;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this._files.has(_normalise(path));
+  }
+
+  async delete(path: string): Promise<void> {
+    this._files.delete(_normalise(path));
+  }
+
+  url(path: string): string {
+    return `${this.baseUrl.replace(/\/+$/, "")}/${_normalise(path)}`;
+  }
+
+  async copy(source: string, destination: string): Promise<void> {
+    const file = this._files.get(_normalise(source));
+    if (!file) throw new Error(`[Zerotal/storage] Cannot copy missing file "${source}".`);
+    this._files.set(_normalise(destination), {
+      ...file,
+      path: _normalise(destination),
+      lastModified: Date.now(),
+    });
+  }
+
+  async move(source: string, destination: string): Promise<void> {
+    await this.copy(source, destination);
+    await this.delete(source);
+  }
+
+  async size(path: string): Promise<number | null> {
+    return this._files.get(_normalise(path))?.contents.length ?? null;
+  }
+
+  async lastModified(path: string): Promise<number | null> {
+    return this._files.get(_normalise(path))?.lastModified ?? null;
+  }
+
+  async temporaryUrl(path: string, expiresInSeconds: number): Promise<string> {
+    const expires = Math.floor(Date.now() / 1000) + expiresInSeconds;
+    return `${this.url(path)}?expires=${expires}&signature=fake`;
+  }
+
+  // ── Inspection ────────────────────────────────────────────────────────
+
+  /** Every stored path, in insertion order. */
+  paths(): string[] {
+    return [...this._files.keys()];
+  }
+
+  /** The full record for a stored file, or `undefined`. */
+  file(path: string): FakeStoredFile | undefined {
+    return this._files.get(_normalise(path));
+  }
+
+  /** Number of files currently stored. */
+  get count(): number {
+    return this._files.size;
+  }
+
+  /** Forget everything stored so far. */
+  clear(): void {
+    this._files.clear();
+  }
+
+  // ── Assertions ────────────────────────────────────────────────────────
+
+  /** Assert a file exists at `path`, optionally matching its exact contents. */
+  assertExists(path: string, contents?: string | Uint8Array): this {
+    const file = this._files.get(_normalise(path));
+    if (!file) {
+      throw new Error(
+        `assertExists: expected "${path}" on the disk, but it holds ${this._listing()}`,
+      );
+    }
+    if (contents !== undefined) {
+      const expected = typeof contents === "string" ? contents : new TextDecoder().decode(contents);
+      const actual = new TextDecoder().decode(file.contents);
+      if (actual !== expected) {
+        throw new Error(
+          `assertExists: "${path}" exists but its contents differ.\n` +
+            `  expected: ${JSON.stringify(expected.slice(0, 120))}\n` +
+            `  actual:   ${JSON.stringify(actual.slice(0, 120))}`,
+        );
+      }
+    }
+    return this;
+  }
+
+  /** Assert nothing is stored at `path`. */
+  assertMissing(path: string): this {
+    if (this._files.has(_normalise(path))) {
+      throw new Error(`assertMissing: expected "${path}" to be absent, but it is stored.`);
+    }
+    return this;
+  }
+
+  /**
+   * Assert a file exists whose path matches `pattern` — the way to assert on an
+   * upload stored under a generated name.
+   *
+   * @example
+   * disk.assertExistsMatching(/^avatars\/[0-9a-f-]+\.png$/);
+   */
+  assertExistsMatching(pattern: RegExp): this {
+    if (!this.paths().some((p) => pattern.test(p))) {
+      throw new Error(
+        `assertExistsMatching: no stored path matched ${pattern}. The disk holds ${this._listing()}`,
+      );
+    }
+    return this;
+  }
+
+  /** Assert the file at `path` was stored with the given content type. */
+  assertContentType(path: string, contentType: string): this {
+    this.assertExists(path);
+    const actual = this._files.get(_normalise(path))!.contentType;
+    if (actual !== contentType) {
+      throw new Error(
+        `assertContentType: expected "${path}" to be stored as "${contentType}" but it was ` +
+          `"${actual ?? "unset"}".`,
+      );
+    }
+    return this;
+  }
+
+  /** Assert exactly `expected` files are stored. */
+  assertCount(expected: number): this {
+    if (this._files.size !== expected) {
+      throw new Error(
+        `assertCount: expected ${expected} file(s) but the disk holds ${this._listing()}`,
+      );
+    }
+    return this;
+  }
+
+  /** Assert nothing at all was stored. */
+  assertNothingStored(): this {
+    return this.assertCount(0);
+  }
+
+  private _listing(): string {
+    const paths = this.paths();
+    return paths.length === 0 ? "no files." : `${paths.length}: [${paths.join(", ")}].`;
+  }
+}
+
+/** Drop a leading slash so `avatars/a.png` and `/avatars/a.png` are one file. */
+function _normalise(path: string): string {
+  return path.replace(/^\/+/, "");
+}
+
+async function _bytes(content: string | Uint8Array | Blob): Promise<Uint8Array> {
+  if (typeof content === "string") return new TextEncoder().encode(content);
+  if (content instanceof Uint8Array) return content;
+  return new Uint8Array(await content.arrayBuffer());
+}

package/src/storage/StorageFilesMiddleware.ts

@@ -0,0 +1,150 @@
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware } from "../middleware/BaseMiddleware.ts";
+import type { StorageManager } from "./StorageManager.ts";
+import type { DiskServeConfig, StorageConfigShape, StorageDriver } from "./types.ts";
+import { isInsidePublicRoot, publicRoot } from "./root.ts";
+import { UnsafePublicMountError } from "./errors.ts";
+import { resolve } from "node:path";
+
+/** One disk mounted at a URL prefix. */
+interface Mount {
+  disk: string;
+  prefix: string;
+  serve: DiskServeConfig;
+}
+
+export interface StorageFilesOptions {
+  /** Disks to serve, in match order. Built from config by {@link StorageProvider}. */
+  mounts?: Mount[];
+  /** The manager the files are read through. */
+  storage?: StorageManager;
+}
+
+/**
+ * Serves files from a storage disk over HTTP.
+ *
+ * Only disks that declare `serve` in `config/storage.ts` are reachable; the rest
+ * have no URL at all. That is the safe default for a disk holding private
+ * uploads — exposure is something you ask for, one disk at a time, rather than
+ * something you remember to switch off.
+ *
+ * `Router.static()` cannot do this job: it registers the files it finds at boot,
+ * so anything uploaded afterwards is invisible until a restart. This resolves
+ * per request, through the driver, so an S3-backed disk can be proxied the same
+ * way a local one is served.
+ *
+ * @example
+ * ```ts
+ * // config/storage.ts — public assets, and private files behind signed links
+ * disks: {
+ *   public:  { driver: "local", root: "./storage/public",
+ *              serve: { path: "/storage/public" } },
+ *   private: { driver: "local", root: "./storage/invoices",
+ *              serve: { path: "/files", signed: true } },
+ * }
+ * ```
+ */
+export class StorageFilesMiddleware extends BaseMiddleware<StorageFilesOptions> {
+  protected options: StorageFilesOptions = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const { mounts, storage } = this.options;
+    if (!mounts?.length || !storage) return next();
+
+    // Only GET and HEAD read files; anything else belongs to the application.
+    const method = http.request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return next();
+
+    const pathname = decodeURIComponent(http.url.pathname);
+    const mount = mounts.find((m) => pathname === m.prefix || pathname.startsWith(m.prefix + "/"));
+    if (!mount) return next();
+
+    const relative = pathname.slice(mount.prefix.length).replace(/^\/+/, "");
+    if (!relative) return next();
+
+    if (mount.serve.signed && !this._verifySignature(http, storage, relative)) {
+      // Deliberately 404, not 403: a bad signature should not confirm that the
+      // file exists to someone guessing paths.
+      return this._notFound();
+    }
+
+    let driver: StorageDriver;
+    try {
+      driver = storage.disk(mount.disk);
+    } catch {
+      return next(); // the disk vanished from config — not this middleware's file
+    }
+
+    const body = await this._read(driver, relative);
+    if (body === null) return this._notFound();
+
+    const headers = new Headers(mount.serve.headers ?? {});
+    // A traversal attempt never reaches here — the driver rejects it — so any
+    // path that resolved is one the disk owns.
+    const modified = await driver.lastModified(relative).catch(() => null);
+    if (modified !== null) headers.set("Last-Modified", new Date(modified).toUTCString());
+    if (!headers.has("Cache-Control")) {
+      headers.set(
+        "Cache-Control",
+        mount.serve.signed ? "private, no-store" : "public, max-age=300",
+      );
+    }
+
+    return new Response(method === "HEAD" ? null : body, { headers });
+  }
+
+  /** Prefer a streamable handle; fall back to bytes for drivers without one. */
+  private async _read(driver: StorageDriver, path: string): Promise<Blob | null> {
+    try {
+      if (driver.stream) return await driver.stream(path);
+      const bytes = await driver.getBuffer(path);
+      return bytes === null ? null : new Blob([bytes as BlobPart]);
+    } catch {
+      // A traversal rejection or an unreadable file both mean "no file here".
+      return null;
+    }
+  }
+
+  private _verifySignature(http: HttpContext, storage: StorageManager, path: string): boolean {
+    const expires = Number(http.url.searchParams.get("expires"));
+    const signature = http.url.searchParams.get("signature");
+    if (!Number.isFinite(expires) || !signature) return false;
+    try {
+      return storage.verifyTemporaryUrl(path, expires, signature);
+    } catch {
+      // Signing needs APP_KEY; without it no signature can be valid.
+      return false;
+    }
+  }
+
+  private _notFound(): Response {
+    return new Response("Not Found", { status: 404, headers: { "Cache-Control": "no-store" } });
+  }
+}
+
+/**
+ * Build the mount list from a storage config, in longest-prefix-first order.
+ *
+ * Also enforces the one rule that keeps the storage root private: a local disk
+ * served *without* `signed` has to live inside the public directory. Checked
+ * here because this runs at boot, so an unsafe config fails before the server
+ * accepts a request rather than the first time someone guesses a path.
+ *
+ * @throws {@link UnsafePublicMountError}
+ */
+export function mountsFrom(config: StorageConfigShape): Mount[] {
+  const mounts: Mount[] = [];
+  for (const [disk, cfg] of Object.entries(config.disks)) {
+    if (!cfg.serve) continue;
+    // Only local disks have a filesystem root to police. An S3 bucket is
+    // outside the storage root by nature, and its exposure is the bucket's own
+    // policy to decide.
+    if (cfg.driver === "local" && !cfg.serve.signed && !isInsidePublicRoot(cfg.root)) {
+      throw new UnsafePublicMountError(disk, resolve(cfg.root), publicRoot());
+    }
+    mounts.push({ disk, prefix: `/${cfg.serve.path.replace(/^\/+|\/+$/g, "")}`, serve: cfg.serve });
+  }
+  // Longest prefix first, so `/storage/private` is matched before `/storage`.
+  return mounts.sort((a, b) => b.prefix.length - a.prefix.length);
+}

package/src/storage/StorageManager.ts

@@ -0,0 +1,173 @@
+import type { StorageDriver, StorageConfigShape } from "./types.ts";
+import { DiskNotConfiguredError, DiskNotServedError } from "./errors.ts";
+import { LocalDriver } from "./drivers/LocalDriver.ts";
+import { S3Driver } from "./drivers/S3Driver.ts";
+import { FakeDisk } from "./FakeDisk.ts";
+
+export class StorageManager {
+  private _config: StorageConfigShape;
+  private _drivers: Map<string, StorageDriver> = new Map();
+  /** Drivers displaced by {@link fake}, keyed by disk name, for {@link restoreFakes}. */
+  private _realDrivers: Map<string, StorageDriver | undefined> = new Map();
+
+  constructor(config: StorageConfigShape) {
+    this._config = config;
+  }
+
+  /**
+   * Get the driver for the named disk (or the default disk if omitted).
+   *
+   * @example
+   * Storage.disk('local').put('avatars/alice.jpg', buffer);
+   * Storage.disk('s3').get('reports/2025.pdf');
+   * Storage.disk().exists('tmp/cache.json');
+   */
+  disk(name?: string): StorageDriver {
+    const diskName = name ?? this._config.default;
+
+    const cached = this._drivers.get(diskName);
+    if (cached) return cached;
+
+    const cfg = this._config.disks[diskName];
+    if (!cfg) throw new DiskNotConfiguredError(diskName);
+
+    let driver: StorageDriver;
+
+    // A served disk's URL base defaults to where it is mounted, so `url()` can
+    // never point somewhere nothing answers. An explicit `url` still wins — that
+    // is how you put a CDN in front.
+    const base = cfg.url ?? cfg.serve?.path;
+
+    if (cfg.driver === "local") {
+      driver = new LocalDriver(cfg.root, base);
+    } else {
+      driver = new S3Driver(cfg.key, cfg.secret, cfg.region, cfg.bucket, cfg.endpoint, base);
+    }
+
+    this._drivers.set(diskName, driver);
+    return driver;
+  }
+
+  /**
+   * Swap a disk for an in-memory {@link FakeDisk} and return it, so a test can
+   * exercise uploads without writing to the filesystem or reaching S3.
+   *
+   * The fake stays installed until {@link restoreFakes} — call that in an
+   * `afterEach`, or a later test expecting real storage will silently write
+   * into memory and find its files gone.
+   *
+   * @param name - Disk to replace; defaults to the configured default disk.
+   *
+   * @example
+   * const disk = Storage.fake('s3');
+   * await report.export();
+   * disk.assertExists('reports/2025.pdf');
+   */
+  fake(name?: string): FakeDisk {
+    const diskName = name ?? this._config.default;
+    const fake = new FakeDisk(this._config.disks[diskName]?.url ?? "/storage");
+    if (!this._realDrivers.has(diskName)) {
+      this._realDrivers.set(diskName, this._drivers.get(diskName));
+    }
+    this._drivers.set(diskName, fake);
+    return fake;
+  }
+
+  /** Restore every disk swapped by {@link fake}. Call in `afterEach`. */
+  restoreFakes(): void {
+    for (const [name, driver] of this._realDrivers) {
+      if (driver) this._drivers.set(name, driver);
+      else this._drivers.delete(name);
+    }
+    this._realDrivers.clear();
+  }
+
+  /**
+   * A URL a browser can actually fetch — the one thing a template wants.
+   *
+   * The disk's own config decides which kind, so the caller does not have to
+   * know whether the file is public:
+   *
+   * - **Served, unsigned** → a permanent URL under the disk's mount.
+   * - **Served with `signed`** → a time-limited signed URL.
+   * - **Not served** → {@link DiskNotServedError}, rather than a plausible
+   *   string that 404s.
+   *
+   * That last case is the point. `url()` on an unserved disk returns a path
+   * nothing answers, and a relative one at that — which resolves against
+   * whatever page embedded it and produces a broken image somewhere confusing.
+   * A URL you cannot fetch is not a URL, so asking for one is an error.
+   *
+   * @param path - Path on the disk.
+   * @param options.disk - Disk name; defaults to the configured default disk.
+   * @param options.expiresIn - Seconds a signed link stays valid. Defaults to
+   *   the disk's `serve.expiresIn`, then 900.
+   * @throws {@link DiskNotConfiguredError} when the disk does not exist.
+   * @throws {@link DiskNotServedError} when the disk has no public URL.
+   *
+   * @example
+   * // Public disk → /storage/avatars/alice.jpg
+   * await Storage.publicUrl("avatars/alice.jpg", { disk: "public" });
+   *
+   * // Signed disk → /invoices/q1.pdf?expires=…&signature=…
+   * await Storage.publicUrl("q1.pdf", { disk: "invoices" });
+   */
+  async publicUrl(
+    path: string,
+    options: { disk?: string; expiresIn?: number } = {},
+  ): Promise<string> {
+    const diskName = options.disk ?? this._config.default;
+    const cfg = this._config.disks[diskName];
+    if (!cfg) throw new DiskNotConfiguredError(diskName);
+
+    if (cfg.serve?.signed) {
+      const expiresIn = options.expiresIn ?? cfg.serve.expiresIn ?? 900;
+      return this.disk(diskName).temporaryUrl(path, expiresIn);
+    }
+
+    if (!cfg.serve && !cfg.url) throw new DiskNotServedError(diskName);
+
+    return this.disk(diskName).url(path);
+  }
+
+  /**
+   * Whether `disk` has a public URL at all — a served disk, or one pointed at a
+   * CDN. Use it to branch a template without catching an error.
+   */
+  isServed(disk?: string): boolean {
+    const cfg = this._config.disks[disk ?? this._config.default];
+    return Boolean(cfg && (cfg.serve || cfg.url));
+  }
+
+  /**
+   * Verify a signature produced by a local disk's `temporaryUrl()`. Returns
+   * `false` when the link has expired or the signature does not match
+   * (constant-time). Wire this into the route that serves protected files:
+   *
+   * @example
+   * Router.get('/files/:path*', ({ params, query, response }) => {
+   *   const path = params.path;
+   *   if (!Storage.verifyTemporaryUrl(path, Number(query('expires')), query('signature') ?? '')) {
+   *     return response.status(403).send('Invalid or expired link');
+   *   }
+   *   return response.stream(await Storage.disk().getBuffer(path));
+   * });
+   *
+   * S3 presigned URLs are verified by S3 itself and never pass through here.
+   */
+  verifyTemporaryUrl(path: string, expiresAt: number, signature: string): boolean {
+    return LocalDriver.verifyTemporaryUrl(path, expiresAt, signature);
+  }
+
+  /**
+   * Convenience over {@link verifyTemporaryUrl} that reads `?expires=&signature=`
+   * from a full request URL and checks them against `path`.
+   */
+  verifyTemporaryUrlFor(path: string, url: URL | string): boolean {
+    const u = typeof url === "string" ? new URL(url) : url;
+    const expires = Number(u.searchParams.get("expires"));
+    const signature = u.searchParams.get("signature");
+    if (!Number.isFinite(expires) || !signature) return false;
+    return LocalDriver.verifyTemporaryUrl(path, expires, signature);
+  }
+}

package/src/storage/config.ts

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { deepMerge } from "../support/deepMerge.ts";
+import type { StorageConfigShape } from "./types.ts";
+import { storageRoot, publicRoot } from "./root.ts";
+
+/**
+ * The built-in disks, derived from the storage root rather than hardcoding
+ * `./storage`.
+ *
+ * Computed per call because the root is read from the environment: a literal
+ * `"./storage/app"` here would sit outside a `ZT_STORAGE_ROOT` pointed at a
+ * mounted volume, and the default config would fail its own boundary check.
+ */
+function defaults(): StorageConfigShape {
+  return {
+    default: "local",
+    disks: {
+      // The default disk holds private uploads and has no `serve` block, so it
+      // is not reachable over HTTP. Hand out links to a file here with
+      // `temporaryUrl()`, or move the file to `public`.
+      local: { driver: "local", root: join(storageRoot(), "app") },
+      // The one public directory. Its filesystem path and its URL are the same
+      // shape on purpose — `storage/public/a.png` is `/storage/public/a.png` —
+      // so "is this file public?" is answered by where the file lives rather
+      // than by which config block someone edited last. No `url` is needed: a
+      // served disk's URL base defaults to where it is mounted.
+      public: {
+        driver: "local",
+        root: publicRoot(),
+        serve: { path: "/storage/public" },
+      },
+    },
+  };
+}
+
+export function StorageConfig(options: Partial<StorageConfigShape> = {}): StorageConfigShape {
+  // `disks` is a name-keyed object, so deepMerge MERGES custom disks with the
+  // built-in `local`/`public` defaults rather than replacing them.
+  return deepMerge(defaults(), options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    storage: StorageConfigShape;
+  }
+}