@zerotal/core 1.0.0

package/src/storage/drivers/LocalDriver.ts

@@ -0,0 +1,138 @@
+import { unlink, stat, copyFile, rename, appendFile, mkdir } from "node:fs/promises";
+import { resolve, sep, dirname } from "node:path";
+import { safeEqual, hmacHex } from "../../support/crypto.ts";
+import type { StorageDriver, PutOptions } from "../types.ts";
+import { PathTraversalError, StorageKeyMissingError } from "../errors.ts";
+import { assertInsideStorageRoot } from "../root.ts";
+
+/**
+ * Local filesystem driver — backed by Bun.file / Bun.write.
+ * Suitable for single-server deployments and local development.
+ */
+export class LocalDriver implements StorageDriver {
+  private readonly _rootAbs: string;
+
+  constructor(
+    private _root: string,
+    private _urlBase: string | undefined = undefined,
+  ) {
+    // Absolute, normalised root used to confine every resolved path.
+    this._rootAbs = resolve(_root);
+    // …and the root itself is confined to the storage root, so a disk cannot be
+    // pointed at the filesystem at large. Checked here rather than in config so
+    // it holds for every LocalDriver, however it was constructed.
+    assertInsideStorageRoot(this._rootAbs, "disk");
+  }
+
+  /**
+   * Resolve `path` against the disk root and reject anything that escapes it.
+   * `resolve()` collapses `..`/`.` segments; we then verify the result is the
+   * root itself or a descendant of it, defeating `../../etc/passwd`-style
+   * traversal on every operation (get/put/delete/copy/move).
+   */
+  private _fullPath(path: string): string {
+    const full = resolve(this._rootAbs, path.replace(/^[/\\]+/, ""));
+    if (full !== this._rootAbs && !full.startsWith(this._rootAbs + sep)) {
+      throw new PathTraversalError(path);
+    }
+    return full;
+  }
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    _options?: PutOptions,
+  ): Promise<void> {
+    await Bun.write(this._fullPath(path), content);
+  }
+
+  async append(path: string, content: string | Uint8Array): Promise<void> {
+    const full = this._fullPath(path);
+    // `dirname`, not a regex: a hand-rolled one that only knows `/` silently
+    // matches nothing on a Windows path and then creates a *directory* where
+    // the file should go.
+    await mkdir(dirname(full), { recursive: true });
+    await appendFile(full, content);
+  }
+
+  async get(path: string): Promise<string | null> {
+    const file = Bun.file(this._fullPath(path));
+    if (!(await file.exists())) return null;
+    return file.text();
+  }
+
+  async stream(path: string): Promise<Blob | null> {
+    // `Bun.file` is a lazy handle, so returning it hands the file to the
+    // response without pulling it through memory first.
+    const file = Bun.file(this._fullPath(path));
+    return (await file.exists()) ? file : null;
+  }
+
+  async getBuffer(path: string): Promise<Uint8Array | null> {
+    const file = Bun.file(this._fullPath(path));
+    if (!(await file.exists())) return null;
+    return new Uint8Array(await file.arrayBuffer());
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return Bun.file(this._fullPath(path)).exists();
+  }
+
+  async delete(path: string): Promise<void> {
+    await unlink(this._fullPath(path)).catch(() => {});
+  }
+
+  url(path: string): string {
+    const base = this._urlBase?.replace(/\/$/, "") ?? "";
+    return `${base}/${path.replace(/^\//, "")}`;
+  }
+
+  async copy(source: string, destination: string): Promise<void> {
+    await copyFile(this._fullPath(source), this._fullPath(destination));
+  }
+
+  async move(source: string, destination: string): Promise<void> {
+    await rename(this._fullPath(source), this._fullPath(destination));
+  }
+
+  async size(path: string): Promise<number | null> {
+    return stat(this._fullPath(path))
+      .then((s) => s.size)
+      .catch(() => null);
+  }
+
+  async lastModified(path: string): Promise<number | null> {
+    return stat(this._fullPath(path))
+      .then((s) => s.mtimeMs)
+      .catch(() => null);
+  }
+
+  /**
+   * Local signed URL — encodes path + expiry in a HMAC-signed query string,
+   * keyed off `APP_KEY` (throws when it is unset, so a signed URL is never
+   * emitted with a guessable key). The signature is validated server-side by
+   * your application's route handler; verify it with {@link verifyTemporaryUrl}.
+   */
+  async temporaryUrl(path: string, expiresInSeconds: number): Promise<string> {
+    const expiresAt = Math.floor(Date.now() / 1000) + expiresInSeconds;
+    const sig = hmacHex(`${path}:${expiresAt}`, _signingKey());
+    const base = this._urlBase?.replace(/\/$/, "") ?? "";
+    return `${base}/${path.replace(/^\//, "")}?expires=${expiresAt}&signature=${sig}`;
+  }
+
+  /**
+   * Verify a signature produced by {@link temporaryUrl}. Returns `false` when
+   * the link has expired or the signature does not match (constant-time).
+   */
+  static verifyTemporaryUrl(path: string, expiresAt: number, signature: string): boolean {
+    if (Math.floor(Date.now() / 1000) > expiresAt) return false;
+    return safeEqual(signature, hmacHex(`${path}:${expiresAt}`, _signingKey()));
+  }
+}
+
+/** The APP_KEY used to sign temporary URLs. Throws when it is not configured. */
+function _signingKey(): string {
+  const key = Bun.env["APP_KEY"];
+  if (!key) throw new StorageKeyMissingError();
+  return key;
+}

package/src/storage/drivers/S3Driver.ts

@@ -0,0 +1,169 @@
+import { S3Client } from "bun";
+import type { StorageDriver, PutOptions } from "../types.ts";
+import { UnsupportedOperationError } from "../errors.ts";
+
+/** Returns true when err is an S3 "object not found" error. */
+function _isNotFound(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  // Bun throws an error named 'S3Error' with a code property for S3 failures.
+  // NoSuchKey / 404 is the only case we treat as "absent" — all others propagate.
+  const s3Err = err as { code?: string };
+  return (
+    err.name === "S3Error" &&
+    (s3Err.code === "NoSuchKey" ||
+      err.message.includes("does not exist") ||
+      err.message.includes("NoSuchKey"))
+  );
+}
+
+/**
+ * S3-compatible storage driver — works with AWS S3, Cloudflare R2, MinIO, etc.
+ * Powered by Bun's native `s3()` client: zero npm dependencies, automatic SigV4
+ * signing, connection reuse, and built-in retry/backoff.
+ *
+ * @example
+ * StorageConfig({
+ *   disks: {
+ *     r2: {
+ *       driver:   's3',
+ *       key:      Bun.env.R2_KEY!,
+ *       secret:   Bun.env.R2_SECRET!,
+ *       region:   'auto',
+ *       bucket:   'my-bucket',
+ *       endpoint: `https://${Bun.env.CF_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+ *     },
+ *   },
+ * });
+ */
+export class S3Driver implements StorageDriver {
+  private _s3: S3Client;
+  private _bucket: string;
+  private _region: string;
+  private _endpoint: string | undefined;
+  private _urlBase: string | undefined;
+
+  constructor(
+    key: string,
+    secret: string,
+    region: string,
+    bucket: string,
+    endpoint?: string,
+    urlBase?: string,
+  ) {
+    this._bucket = bucket;
+    this._region = region;
+    this._endpoint = endpoint;
+    this._urlBase = urlBase;
+    this._s3 = new S3Client({
+      accessKeyId: key,
+      secretAccessKey: secret,
+      region,
+      bucket,
+      ...(endpoint && { endpoint }),
+    });
+  }
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    options?: PutOptions,
+  ): Promise<void> {
+    await this._s3.write(path, content, {
+      type: options?.contentType ?? "application/octet-stream",
+    });
+  }
+
+  async append(_path: string, _content: string | Uint8Array): Promise<void> {
+    // An S3 object is immutable: "appending" means downloading, concatenating
+    // and re-uploading the whole object. A caller appending a log line per
+    // request would not survive that, so this refuses instead.
+    throw new UnsupportedOperationError("append", "s3");
+  }
+
+  async get(path: string): Promise<string | null> {
+    try {
+      return await this._s3.file(path).text();
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async getBuffer(path: string): Promise<Uint8Array | null> {
+    try {
+      return new Uint8Array(await this._s3.file(path).arrayBuffer());
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await this._s3.file(path).stat();
+      return true;
+    } catch (err) {
+      if (_isNotFound(err)) return false;
+      throw err;
+    }
+  }
+
+  async delete(path: string): Promise<void> {
+    await this._s3.delete(path);
+  }
+
+  url(path: string): string {
+    if (this._urlBase) {
+      return `${this._urlBase.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+    }
+    return this._publicUrl(path);
+  }
+
+  async copy(source: string, destination: string): Promise<void> {
+    // Pass the S3File (a Blob) directly — Bun streams source → destination
+    // without buffering the object locally.
+    await this._s3.write(destination, this._s3.file(source));
+  }
+
+  async move(source: string, destination: string): Promise<void> {
+    await this.copy(source, destination);
+    await this.delete(source);
+  }
+
+  async size(path: string): Promise<number | null> {
+    try {
+      const stat = await this._s3.file(path).stat();
+      return stat.size;
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async lastModified(path: string): Promise<number | null> {
+    try {
+      const stat = await this._s3.file(path).stat();
+      const lm = stat.lastModified;
+      return lm instanceof Date ? lm.getTime() : new Date(lm as unknown as string).getTime();
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async temporaryUrl(path: string, expiresInSeconds: number): Promise<string> {
+    return this._s3.file(path).presign({ expiresIn: expiresInSeconds });
+  }
+
+  private _publicUrl(path: string): string {
+    const cleanPath = path.replace(/^\//, "");
+    if (this._endpoint) {
+      const ep = this._endpoint.replace(/\/$/, "");
+      if (!ep.includes(`${this._bucket}.s3.`)) {
+        return `${ep}/${this._bucket}/${cleanPath}`;
+      }
+      return `${ep}/${cleanPath}`;
+    }
+    return `https://${this._bucket}.s3.${this._region}.amazonaws.com/${cleanPath}`;
+  }
+}

package/src/storage/errors.ts

@@ -0,0 +1,135 @@
+import { ZerotalError } from "../errors/ZerotalError.ts";
+
+/** Base class for all storage errors. */
+export class StorageError extends ZerotalError {
+  constructor(
+    message: string,
+    code = "E_STORAGE",
+    status = 500,
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, status, context);
+  }
+}
+
+/** Thrown when a disk name is not present in the storage config. */
+export class DiskNotConfiguredError extends StorageError {
+  constructor(disk: string) {
+    super(
+      `[Zerotal Storage] Disk "${disk}" is not configured.`,
+      "E_STORAGE_DISK_NOT_CONFIGURED",
+      500,
+      { disk },
+    );
+  }
+}
+
+/** Thrown when a requested path would escape the disk's root directory. */
+export class PathTraversalError extends StorageError {
+  constructor(path: string) {
+    super(
+      `[Zerotal Storage] Path "${path}" escapes the disk root. ` +
+        `Relative segments that resolve outside the configured root are rejected.`,
+      "E_STORAGE_PATH_TRAVERSAL",
+      400,
+      { path },
+    );
+  }
+}
+
+/** Thrown when a signing operation is attempted without an APP_KEY configured. */
+export class StorageKeyMissingError extends StorageError {
+  constructor() {
+    super(
+      "[Zerotal Storage] Signed URLs require APP_KEY. Generate one with `zerotal key:generate`.",
+      "E_STORAGE_NO_KEY",
+      500,
+    );
+  }
+}
+
+/**
+ * Thrown when a driver is asked for something its backend cannot do.
+ *
+ * The contract is one API over very different backends, and a couple of
+ * operations only make sense on some of them — appending to an object in S3
+ * means rewriting the whole object. Refusing loudly beats emulating badly.
+ */
+export class UnsupportedOperationError extends StorageError {
+  constructor(operation: string, driver: string) {
+    super(
+      `[Zerotal Storage] The ${driver} driver does not support ${operation}().`,
+      "E_STORAGE_UNSUPPORTED",
+      500,
+      { operation, driver },
+    );
+  }
+}
+
+/**
+ * Thrown when a local disk is rooted outside the storage root.
+ *
+ * The per-disk traversal guard stops a *path* escaping its disk; this stops the
+ * *disk* being pointed somewhere it has no business reading or writing. A
+ * misconfigured root is not a runtime edge case to degrade around — it is a
+ * config bug, and it fails at construction so it surfaces on boot rather than
+ * on the first upload.
+ */
+export class StorageRootEscapeError extends StorageError {
+  constructor(path: string, root: string, what: string) {
+    super(
+      `[Zerotal Storage] The ${what} root "${path}" is outside the storage root "${root}".\n` +
+        `Every local disk must live inside the storage root. Move it under that ` +
+        `directory, or set ZT_STORAGE_ROOT if your data volume is mounted elsewhere.`,
+      "E_STORAGE_ROOT_ESCAPE",
+      500,
+      { path, root },
+    );
+  }
+}
+
+/**
+ * Thrown when a public URL is asked for a disk that has none.
+ *
+ * A disk with no `serve` block and no `url` base is not reachable over HTTP.
+ * Handing back a path anyway produces the worst kind of failure — a link that
+ * looks right, resolves relative to whatever page embedded it, and 404s
+ * somewhere unrelated to the disk.
+ */
+export class DiskNotServedError extends StorageError {
+  constructor(disk: string) {
+    super(
+      `[Zerotal Storage] The "${disk}" disk has no public URL.\n` +
+        `Add a \`serve\` block to expose it (\`serve: { path: "/files" }\`, or ` +
+        `\`{ path: "/files", signed: true }\` for signed links), or set \`url\` to ` +
+        `point at a CDN. Use Storage.isServed("${disk}") to branch instead of catching.`,
+      "E_STORAGE_DISK_NOT_SERVED",
+      500,
+      { disk },
+    );
+  }
+}
+
+/**
+ * Thrown when a disk outside the public directory is served without signing.
+ *
+ * Everything under the storage root is private except `storage/public`. A disk
+ * rooted elsewhere can still be exposed — but only behind `signed: true`, where
+ * each request carries a signature you issued. Serving it openly would make
+ * private files world-readable through a URL prefix, which is the mistake this
+ * refuses to let a config express.
+ */
+export class UnsafePublicMountError extends StorageError {
+  constructor(disk: string, root: string, publicRoot: string) {
+    super(
+      `[Zerotal Storage] The "${disk}" disk is served without \`signed\`, but its root ` +
+        `"${root}" is outside the public directory "${publicRoot}".\n` +
+        `Everything under the storage root is private except that directory. Either ` +
+        `move the disk inside it, or serve it with \`signed: true\` so each request ` +
+        `has to carry a signature you issued.`,
+      "E_STORAGE_UNSAFE_PUBLIC_MOUNT",
+      500,
+      { disk, root, publicRoot },
+    );
+  }
+}

package/src/storage/facades/Storage.ts

@@ -0,0 +1,3 @@
+import { createFacade } from "../../facade/Facade.ts";
+
+export const Storage = createFacade("storage");

package/src/storage/global.d.ts

@@ -0,0 +1,7 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+interface Request {
+  readonly params?: Record<string, string>;
+}

package/src/storage/index.ts

@@ -0,0 +1,22 @@
+export { StorageManager } from "./StorageManager.ts";
+export { StorageProvider } from "../provider/StorageProvider.ts";
+export { Storage } from "./facades/Storage.ts";
+export { StorageConfig } from "./config.ts";
+export { LocalDriver } from "./drivers/LocalDriver.ts";
+export { StorageFilesMiddleware, mountsFrom } from "./StorageFilesMiddleware.ts";
+export type { StorageFilesOptions } from "./StorageFilesMiddleware.ts";
+export { S3Driver } from "./drivers/S3Driver.ts";
+export { FakeDisk } from "./FakeDisk.ts";
+export type { FakeStoredFile } from "./FakeDisk.ts";
+export type {
+  StorageDriver,
+  StorageConfigShape,
+  DiskConfig,
+  LocalDiskConfig,
+  S3DiskConfig,
+  PutOptions,
+  DiskServeConfig,
+} from "./types.ts";
+
+// Typed error vocabulary
+export * from "./errors.ts";

package/src/storage/root.ts

@@ -0,0 +1,59 @@
+import { resolve, sep } from "node:path";
+import { StorageRootEscapeError } from "./errors.ts";
+
+/**
+ * The one directory every local disk must live inside.
+ *
+ * A per-disk root already stops `../../etc/passwd` from escaping *that* disk,
+ * but nothing stopped the disk itself from being rooted at `/etc` in the first
+ * place — a config typo, a copied snippet, or a path built from user input, and
+ * a "storage" disk is reading the filesystem. This is the outer boundary: every
+ * local root resolves inside it or the driver refuses to exist.
+ *
+ * Defaults to `<cwd>/storage`. `ZT_STORAGE_ROOT` moves it — for a deployment
+ * whose data volume is mounted elsewhere, or a test that works in a temp
+ * directory. It is read on every call rather than cached so that a change takes
+ * effect immediately.
+ */
+export function storageRoot(): string {
+  return resolve(Bun.env["ZT_STORAGE_ROOT"] ?? "storage");
+}
+
+/**
+ * The one directory whose contents are readable without a signature.
+ *
+ * Everything under {@link storageRoot} is private; this is the single carve-out.
+ * Keeping it a real directory rather than a naming convention means "is this
+ * file public?" is answered by where it lives, which is checkable, instead of by
+ * which config block someone edited last.
+ */
+export function publicRoot(): string {
+  return resolve(storageRoot(), "public");
+}
+
+/** Whether `path` resolves to the public directory or something beneath it. */
+export function isInsidePublicRoot(path: string): boolean {
+  const root = publicRoot();
+  const full = resolve(path);
+  return full === root || full.startsWith(root + sep);
+}
+
+/** Whether `path` resolves to the storage root or something beneath it. */
+export function isInsideStorageRoot(path: string): boolean {
+  const root = storageRoot();
+  const full = resolve(path);
+  return full === root || full.startsWith(root + sep);
+}
+
+/**
+ * Throw unless `path` resolves inside {@link storageRoot}.
+ *
+ * @param path - The path to check; resolved against the working directory.
+ * @param what - What is being rooted there, for the error message.
+ * @throws {@link StorageRootEscapeError}
+ */
+export function assertInsideStorageRoot(path: string, what = "disk"): void {
+  if (!isInsideStorageRoot(path)) {
+    throw new StorageRootEscapeError(path, storageRoot(), what);
+  }
+}

package/src/storage/types.ts

@@ -0,0 +1,104 @@
+export interface PutOptions {
+  contentType?: string;
+  visibility?: "public" | "private";
+}
+
+export interface StorageDriver {
+  put(path: string, content: string | Uint8Array | Blob, options?: PutOptions): Promise<void>;
+  get(path: string): Promise<string | null>;
+  getBuffer(path: string): Promise<Uint8Array | null>;
+  exists(path: string): Promise<boolean>;
+  delete(path: string): Promise<void>;
+  /** Return a public URL for the given path. */
+  url(path: string): string;
+
+  /** Copy a file within the same disk. */
+  copy(source: string, destination: string): Promise<void>;
+  /** Move (rename) a file within the same disk. */
+  move(source: string, destination: string): Promise<void>;
+  /** Return the file size in bytes, or null if not found. */
+  size(path: string): Promise<number | null>;
+  /** Return the last-modified timestamp (ms since epoch), or null if not found. */
+  lastModified(path: string): Promise<number | null>;
+  /**
+   * Return a temporary URL valid for `expiresInSeconds` seconds.
+   * For local driver this is a signed token URL; for S3 it is a presigned URL.
+   */
+  temporaryUrl(path: string, expiresInSeconds: number): Promise<string>;
+  /**
+   * Append to the end of a file, creating it when absent.
+   *
+   * Only a filesystem can do this. An object store rewrites the whole object on
+   * every write, so emulating an append there would quietly turn one line of a
+   * log into a full download-and-upload of the day's file — {@link S3Driver}
+   * throws {@link UnsupportedOperationError} rather than pretend. Use it for
+   * things that are genuinely local and line-oriented, like the log trail.
+   */
+  append(path: string, content: string | Uint8Array): Promise<void>;
+  /**
+   * A lazy handle for `path`, or `null` when absent.
+   *
+   * Optional. When a backend can hand back something streamable, serving a file
+   * does not have to read it into memory first — which is the difference
+   * between serving a 2 GB video and falling over. {@link StorageFilesMiddleware}
+   * uses it when present and falls back to {@link getBuffer} when not.
+   */
+  stream?(path: string): Promise<Blob | null>;
+}
+
+/**
+ * How a disk is exposed over HTTP by {@link StorageFilesMiddleware}.
+ *
+ * Omit it and the disk is not reachable over the network at all — which is the
+ * right default for anything holding private uploads.
+ */
+export interface DiskServeConfig {
+  /** URL prefix the disk is served under, e.g. `/storage`. */
+  path: string;
+  /**
+   * Require a valid `?expires=&signature=` on every request, as produced by
+   * `temporaryUrl()`. Use it to expose a private disk without making it public:
+   * only someone holding a link you signed can read a file, and only until it
+   * expires.
+   */
+  signed?: boolean;
+  /**
+   * How long a signed link stays valid, in seconds. Only meaningful with
+   * `signed`. Defaults to 900 (15 minutes).
+   */
+  expiresIn?: number;
+  /** Extra response headers, e.g. `Cache-Control`. */
+  headers?: Record<string, string>;
+}
+
+export interface LocalDiskConfig {
+  driver: "local";
+  /** Absolute or relative root directory for file storage. */
+  root: string;
+  /** Optional base URL for url() — e.g. '/storage' or 'https://cdn.example.com'. */
+  url?: string;
+  /** Expose this disk over HTTP. Omit to keep it unreachable. */
+  serve?: DiskServeConfig;
+}
+
+export interface S3DiskConfig {
+  driver: "s3";
+  key: string;
+  secret: string;
+  region: string;
+  bucket: string;
+  /** Override endpoint for R2, MinIO, etc. E.g. 'https://<account>.r2.cloudflarestorage.com' */
+  endpoint?: string;
+  /** Custom public URL base (e.g. CDN or R2 public domain). */
+  url?: string;
+  /** Expose this disk over HTTP, proxied through the app. Omit to keep it unreachable. */
+  serve?: DiskServeConfig;
+}
+
+export type DiskConfig = LocalDiskConfig | S3DiskConfig;
+
+export interface StorageConfigShape {
+  /** Name of the default disk. */
+  default: string;
+  disks: Record<string, DiskConfig>;
+}

package/src/support/appKey.ts

@@ -0,0 +1,38 @@
+/**
+ * APP_KEY strength check.
+ *
+ * `APP_KEY` is the single secret every signing and encryption primitive derives
+ * from — sessions, signed URLs, Flow snapshots, remember-me tokens. Because
+ * each derives its working key by hashing the value through SHA-256, *any* length
+ * "works" mechanically, so a short or low-entropy key (`APP_KEY=secret`) silently
+ * weakens the whole framework with no error. This surfaces that at boot instead.
+ */
+
+/** Minimum key material, in bytes. `key:generate` mints 32 random bytes. */
+export const MIN_APP_KEY_BYTES = 32;
+
+/**
+ * Bytes of key material an `APP_KEY` carries: the decoded length for a
+ * `base64:`-prefixed value, otherwise its UTF-8 byte length.
+ */
+export function appKeyByteLength(key: string): number {
+  const raw = key.startsWith("base64:")
+    ? Buffer.from(key.slice(7), "base64")
+    : Buffer.from(key, "utf8");
+  return raw.length;
+}
+
+/**
+ * A warning message when `key` is too weak to key the framework's cryptography,
+ * or `null` when it is absent (handled at point-of-use) or strong enough.
+ */
+export function appKeyStrengthWarning(key: string | undefined): string | null {
+  if (!key) return null; // absence is enforced where the key is actually needed
+  const bytes = appKeyByteLength(key);
+  if (bytes >= MIN_APP_KEY_BYTES) return null;
+  return (
+    `[Zerotal] APP_KEY carries only ${bytes} bytes of key material (minimum ${MIN_APP_KEY_BYTES}). ` +
+    `Every session, signed URL, and Flow snapshot derives from it, so a short key weakens them all. ` +
+    `Generate a strong one with \`bun zt key:generate\`.`
+  );
+}