@zerotal/flow 1.0.0

package/src/types.ts

@@ -0,0 +1,315 @@
+// ── Core shared types for @zerotal/flow ────────────────────────────────────────
+//
+// The wire-format types that round-trip between server and client: the serialized
+// component snapshot, the inbound `call` frame, and the outbound server frames
+// (`patch`, `flash`, `redirect`, `error`, …).
+
+/**
+ * A single serialized property: `[value, synthMetadata]`.
+ * @category Snapshot
+ */
+export type SnapshotTuple = [data: unknown, meta: Record<string, unknown>];
+
+/**
+ * The "data" map inside a snapshot: `propertyName → [value, meta]`.
+ * @category Snapshot
+ */
+export type SnapshotData = Record<string, SnapshotTuple>;
+
+/**
+ * Metadata for a child Component component embedded inside a parent's render output.
+ * Stored in memo.children (excluded from HMAC signing — same as Livewire).
+ * @category Snapshot
+ */
+export interface ChildMemo {
+  /** The JSX `key` prop that identifies this slot in the parent's template. */
+  key: string;
+  /** Stable component ID (data-flow-id on the [data-flow-root] element). */
+  id: string;
+  /** Child class name — used to route WebSocket actions. */
+  name: string;
+}
+
+/**
+ * Component identity / routing metadata embedded in the snapshot.
+ * @category Snapshot
+ */
+export interface SnapshotMemo {
+  id: string;
+  name: string;
+  path: string;
+  children: string[];
+  /** @on listener map: eventName → methodName. Excluded from HMAC (server-derived). */
+  listeners?: Record<string, string> | undefined;
+  /**
+   * Named slot HTML passed down by the parent's template (`slotName → html`; the
+   * default slot is keyed `"default"`). Rendered in the parent's scope, then carried
+   * in the child's snapshot so the child can re-render its own actions with the slot
+   * content intact. Signed (server-generated, never trusted from the client).
+   */
+  slots?: Record<string, string> | undefined;
+  /**
+   * `@presence` props → their resolved channel, so the client subscribes to the right
+   * presence channel(s) and refreshes the member list on join/leave. Signed (the channel
+   * is server-resolved from the component, not trusted from the client).
+   */
+  presence?: Array<{ prop: string; channel: string }> | undefined;
+  /**
+   * `@shared` props → their resolved channel, so the client subscribes and dispatches
+   * `$shared` (re-read the room store + re-render) when the channel signals a change.
+   * Signed (server-resolved from the component, not trusted from the client).
+   */
+  shared?: Array<{ prop: string; channel: string }> | undefined;
+  /**
+   * The authenticated user this snapshot was issued to, or `undefined` when it was issued
+   * to an anonymous request. Signed, and checked on every hydrate.
+   *
+   * The HMAC proves a snapshot has not been *tampered with*; it says nothing about who it
+   * belongs to. Without this binding, `@locked accountId = 42` — documented as tamper-proof
+   * server-authoritative state — could be replayed verbatim by any other authenticated
+   * user who obtained a snapshot signed for someone else, with the framework's own
+   * signature vouching for it. Middleware still re-runs, so auth is re-checked; the data is
+   * what the snapshot says.
+   */
+  sub?: string | undefined;
+  /**
+   * Issue time, epoch seconds. Signed, and checked on every hydrate against
+   * `SNAPSHOT_MAX_AGE_SECONDS` so a captured snapshot is not valid indefinitely.
+   */
+  iat?: number | undefined;
+}
+
+/**
+ * The full snapshot that round-trips between server and client.
+ * @category Snapshot
+ */
+export interface Snapshot {
+  data: SnapshotData;
+  memo: SnapshotMemo;
+  checksum: string;
+}
+
+/**
+ * Outbound WS frame sent by the client to the server.
+ * @category Frames
+ */
+export interface CallFrame {
+  type: "call";
+  component: string;
+  method: string;
+  args: unknown[];
+  updates: Record<string, unknown>;
+  snapshot: Snapshot;
+}
+
+/**
+ * Patch frame sent by the server to the client after a successful action.
+ *
+ * The snapshot travels as a **delta** by default: only changed fields (`dataDelta`)
+ * and removed keys (`dataRemoved`) are sent, alongside the new `memo` and full-snapshot
+ * `checksum`. The client rebuilds the full snapshot from its prior copy + the delta (an
+ * exact reconstruction, since the server diffed against the client's own snapshot). The
+ * legacy `snapshot` field remains as a full fallback. `html` is omitted when the
+ * re-render is byte-identical to the last patch on this connection (HTML suppression).
+ * @category Frames
+ */
+export interface PatchFrame {
+  type: "patch";
+  component: string;
+  html?: string;
+  // Delta encoding (default on WebSocket patches):
+  memo?: SnapshotMemo;
+  checksum?: string;
+  dataDelta?: SnapshotData;
+  dataRemoved?: string[];
+  // Full snapshot — legacy/fallback path (e.g. when there is no client base to diff against).
+  snapshot?: Snapshot;
+  scripts?: string[];
+  errors?: Record<string, string[]>;
+  title?: string;
+  /** True when the action (or a rejected client write) failed — drives `showOnError`. */
+  actionError?: boolean;
+  /**
+   * True for a mid-`@task` streaming patch: the client applies the DOM/snapshot but keeps the
+   * triggering action's loading state on and does not release the per-component send queue —
+   * only the final (non-partial) patch does. Absent on ordinary patches.
+   */
+  partial?: boolean;
+}
+
+/**
+ * Where a toast is anchored on screen.
+ * @category Flash
+ */
+export type FlashPosition =
+  "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+
+/**
+ * Button fill style.
+ * @category Flash
+ */
+export type FlashActionVariant = "solid" | "soft" | "ghost";
+
+/**
+ * Constrained, inline styling for a toast action button. Kept to a small,
+ * purge-proof set (toasts are built at runtime, so arbitrary Tailwind classes
+ * would be stripped) — pick a `color`, a fill `variant`, and/or `uppercase`.
+ * @category Flash
+ */
+export interface FlashActionStyle {
+  /** Accent: a level name (`success`/`error`/`warning`/`info`), `neutral`, or any CSS color. */
+  color?: string;
+  /** Fill style — `soft` (default), `solid`, or `ghost`. */
+  variant?: FlashActionVariant;
+  /** Render the label uppercase (adds letter-spacing). */
+  uppercase?: boolean;
+}
+
+/**
+ * An interactive button inside a toast. `method` names a `@expose` action on the
+ * component that emitted the flash; clicking the button invokes it over the WS
+ * bridge (with optional `args`), then dismisses the toast.
+ * @category Flash
+ */
+export interface FlashAction extends FlashActionStyle {
+  label: string;
+  method: string;
+  args?: unknown[];
+}
+
+/**
+ * A `@expose` method (+ args) invoked when the toast is dismissed.
+ * @category Flash
+ */
+export interface FlashCallback {
+  method: string;
+  args?: unknown[];
+}
+
+/**
+ * A flash notification payload (server → client). `message`/`level` are the core;
+ * everything else is an optional per-toast override of the `<Flash>` defaults.
+ * @category Flash
+ */
+export interface FlashMessage {
+  message: string;
+  level: "success" | "error" | "warning" | "info";
+  /** Bold header rendered above the message. */
+  title?: string;
+  /** Override the `<Flash>` container position for this toast. */
+  position?: FlashPosition;
+  /** Auto-dismiss after N ms. `0` (or negative) keeps it until dismissed. */
+  duration?: number;
+  /** Render a close (×) button. Forced on when the toast doesn't auto-dismiss. */
+  dismissible?: boolean;
+  /** Custom icon (emoji/text), or `false` to hide the status icon. */
+  icon?: string | false;
+  /** Show a countdown progress bar (only meaningful while auto-dismissing). */
+  progressBar?: boolean;
+  /** Action buttons (e.g. "Undo") that each invoke a `@expose` method on click. */
+  actions?: FlashAction[];
+  /** A `@expose` method invoked when the toast is dismissed (any path). */
+  onClose?: FlashCallback;
+}
+
+/**
+ * Flash notification frame.
+ * @category Frames
+ */
+export interface FlashFrame extends FlashMessage {
+  type: "flash";
+}
+
+/**
+ * Programmatic redirect frame.
+ * @category Frames
+ */
+export interface RedirectFrame {
+  type: "redirect";
+  url: string;
+  sessionToken?: string;
+}
+
+/**
+ * Error frame (action threw, onError ran).
+ * @category Frames
+ */
+export interface ErrorFrame {
+  type: "error";
+  component: string;
+  message: string;
+  /**
+   * Dev-only error detail — the server attaches these only under the `serve --dev` worker so the
+   * client can render a full-screen error overlay. Never sent in production (no stack leak).
+   */
+  name?: string;
+  stack?: string;
+  action?: string;
+}
+
+/**
+ * Stream frame.
+ * @category Frames
+ */
+export interface StreamFrame {
+  type: "stream";
+  ref: string;
+  content: string;
+  replace: boolean;
+}
+
+/**
+ * Cross-component event frame.
+ * @category Frames
+ */
+export interface EventFrame {
+  type: "event";
+  name: string;
+  data: Record<string, unknown>;
+}
+
+/**
+ * File download frame.
+ * @category Frames
+ */
+export interface DownloadFrame {
+  type: "download";
+  filename: string;
+  content: string;
+  mime: string;
+}
+
+/**
+ * Sent after WS actions that mutated @session props; the client fetches the relay endpoint.
+ * @category Frames
+ */
+export interface SessionFrame {
+  type: "session";
+  token: string;
+}
+
+/**
+ * Sent when the WS connection opens; `dev` enables client-side fast refresh on reconnect.
+ * @category Frames
+ */
+export interface ReadyFrame {
+  type: "ready";
+  dev?: boolean;
+}
+
+/**
+ * Union of every frame the server can push to the client over the WebSocket bridge.
+ * @category Frames
+ */
+export type ServerFrame =
+  | PatchFrame
+  | FlashFrame
+  | RedirectFrame
+  | ErrorFrame
+  | StreamFrame
+  | EventFrame
+  | DownloadFrame
+  | SessionFrame
+  | ReadyFrame;
+
+export type FlashLevel = FlashMessage["level"];

package/src/uploads/FileUploads.ts

@@ -0,0 +1,94 @@
+// ── FileUploads mixin ─────────────────────────────────────────────────────────
+//
+// The TypeScript equivalent of Livewire's `WithFileUploads` trait. File uploads work
+// like any other input: a `<FileUpload>` / file `<input flow:model>` POSTs the bytes to
+// `/__flow/upload` (over HTTP), shows live progress, then `$set`s a signed reference
+// that the base Component resolves into a `TemporaryUploadedFile` (signature verified).
+// This mixin adds the ergonomic server-side actions for managing those pending uploads —
+// chiefly removing a chosen file before it's stored — without bloating the base class.
+//
+//   class Avatar extends ComponentWith(FileUploads) {
+//     @expose photo: TemporaryUploadedFile | null = null;
+//     @expose async save() {
+//       this.path = await this.photo?.store("avatars"); // persist permanently
+//       this.photo = null;
+//     }
+//     async render() {
+//       // <FileUpload bind={this.photo} accept="image/*" />
+//       // + a remove button → onClick={() => this.removeUpload("photo")}
+//     }
+//   }
+//
+// Multiple files: bind the property to an array and pass `multiple` to <FileUpload>;
+// `removeUpload(prop, index)` drops one entry, or all when `index` is omitted.
+
+import { Component } from "../Component.ts";
+import { expose } from "../decorators.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AbstractComponentCtor = abstract new (...args: any[]) => Component;
+
+/**
+ * Component mixin that adds server-side file-upload management — flow's
+ * equivalent of Livewire's `WithFileUploads` trait.
+ *
+ * @remarks
+ * Uploading itself needs no mixin: a `<FileUpload>` / file `<input flow:model>`
+ * POSTs bytes to `/__flow/upload` (over HTTP, with live progress) and then
+ * `$set`s a signed reference that the base Component resolves into a
+ * {@link TemporaryUploadedFile}. This mixin adds the ergonomic action for managing
+ * those pending uploads — chiefly {@link WithUploads.removeUpload | removeUpload},
+ * for clearing a chosen file before it's stored — without bloating the base class.
+ * Bind a single property to accept one file, or an array (with `multiple` on
+ * `<FileUpload>`) to accept several.
+ *
+ * @typeParam TBase - The (abstract) Component constructor being extended.
+ * @param Base - The component class to mix into.
+ * @returns A subclass of `Base` with upload-management actions.
+ *
+ * @example
+ * ```tsx
+ * class Avatar extends ComponentWith(FileUploads) {
+ *   @expose photo: TemporaryUploadedFile | null = null;
+ *   @expose path = "";
+ *
+ *   @expose async save() {
+ *     this.path = (await this.photo?.store("avatars")) ?? this.path;
+ *     this.photo = null;
+ *   }
+ *
+ *   async render() {
+ *     return (
+ *       <div>
+ *         <FileUpload bind={this.photo} accept="image/*" />
+ *         <button onClick={() => this.removeUpload("photo")}>Remove</button>
+ *         <button onClick={this.save}>Save</button>
+ *       </div>
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export function FileUploads<TBase extends AbstractComponentCtor>(Base: TBase) {
+  abstract class WithUploads extends Base {
+    /**
+     * Remove a pending upload (Livewire's `removeUpload`). For a single-file property it
+     * clears it (null); for a multiple-file array it removes the item at `index`, or all
+     * when `index` is omitted.
+     *
+     * @param prop - Name of the component property holding the pending upload(s).
+     * @param index - For array-valued properties, the item to remove; omit to remove all.
+     */
+    @expose removeUpload(prop: string, index?: number): void {
+      const self = this as unknown as Record<string, unknown>;
+      const cur = self[prop];
+      if (Array.isArray(cur)) {
+        self[prop] =
+          index === undefined || index === null ? [] : cur.filter((_, i) => i !== Number(index));
+      } else {
+        self[prop] = null;
+      }
+    }
+  }
+  return WithUploads;
+}

package/src/uploads/TemporaryUploadedFile.ts

@@ -0,0 +1,274 @@
+import { sign, verify } from "./sign.ts";
+
+/**
+ * The plain metadata describing a pending upload on the temp disk — the fields
+ * that travel in an {@link UploadRef} and round-trip through the snapshot.
+ *
+ * @remarks
+ * Every field here is included in the signed payload because each one steers later
+ * I/O: `tmpPath`/`size`/`mime` identify the bytes, `originalName` derives the
+ * stored file's extension, and `tempDisk` selects the disk reads/writes resolve
+ * against.
+ */
+export interface TufData {
+  /** Path of the uploaded bytes on the temp disk. */
+  tmpPath: string;
+  /** The client-supplied original filename (used to derive the stored extension). */
+  originalName: string;
+  /** The upload's MIME type. */
+  mime: string;
+  /** Size of the upload in bytes. */
+  size: number;
+  /** Name of the temp disk the bytes live on (default disk when omitted). */
+  tempDisk?: string | undefined;
+}
+
+/**
+ * What the `/__flow/upload` endpoint returns and the client `$set`s onto a
+ * component property — {@link TufData} plus a self-describing marker and its own
+ * HMAC signature.
+ *
+ * @remarks
+ * The signature lets the server trust a client-supplied ref: on `$set` it is
+ * verified (see {@link TemporaryUploadedFile.fromSignedRef}) before wrapping into
+ * a {@link TemporaryUploadedFile}. A forged or altered ref fails verification and
+ * is discarded.
+ */
+export interface UploadRef extends TufData {
+  /** Discriminator marking this object as a flow upload reference. */
+  __flow_upload: true;
+  /** HMAC signature over the signed payload of {@link TufData} fields. */
+  sig: string;
+}
+
+function payload(d: TufData): string {
+  // Every field that steers later I/O MUST be signed:
+  //  - originalName → store() derives the permanent file's extension from it, so
+  //    an unsigned name lets a client swap a validated .png ref for an .html/.svg
+  //    one (stored-XSS / content-type confusion on a public disk).
+  //  - tempDisk → bytes()/store()/temporaryUrl() resolve against it, so an
+  //    unsigned value lets a client redirect reads/writes to a different disk.
+  return `${d.tmpPath}|${d.size}|${d.mime}|${d.originalName}|${d.tempDisk ?? ""}`;
+}
+
+/** Build a signed reference (server side, in the upload endpoint). */
+export function makeSignedRef(d: TufData): UploadRef {
+  return { __flow_upload: true, ...d, sig: sign(payload(d)) };
+}
+
+export function isUploadRef(v: unknown): v is UploadRef {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as Record<string, unknown>)["__flow_upload"] === true &&
+    typeof (v as Record<string, unknown>)["sig"] === "string" &&
+    typeof (v as Record<string, unknown>)["tmpPath"] === "string"
+  );
+}
+
+type Disk = {
+  getBuffer(path: string): Promise<Uint8Array>;
+  put(path: string, data: Uint8Array, opts?: { contentType?: string }): Promise<void>;
+  delete(path: string): Promise<void>;
+  url(path: string): string;
+  temporaryUrl?(path: string, ttlSeconds: number): string;
+};
+
+async function disk(name?: string): Promise<Disk> {
+  const { Storage } = (await import("@zerotal/core/storage")) as unknown as {
+    Storage: { disk(n?: string): Disk };
+  };
+  return Storage.disk(name);
+}
+
+/**
+ * A Livewire-style temporary uploaded file — the server-side handle a component
+ * receives for a pending upload before it's promoted to permanent storage.
+ *
+ * @remarks
+ * Uploads bypass the WebSocket: the browser POSTs the bytes to `/__flow/upload`
+ * over HTTP, the endpoint stores them on a temp disk and returns a signed
+ * {@link UploadRef}, and the client `$set`s that ref onto a component property.
+ * The base Component verifies the signature and wraps it into a
+ * `TemporaryUploadedFile` (see {@link resolveUploadValue}). Component code then
+ * inspects it ({@link isImage}, {@link extension}, {@link temporaryUrl}) and calls
+ * {@link store} in an action to move it to permanent storage. The value
+ * round-trips through the HMAC-signed snapshot via its synth, so it survives
+ * across requests until stored.
+ *
+ * @example
+ * ```tsx
+ * class Avatar extends ComponentWith(FileUploads) {
+ *   @expose photo: TemporaryUploadedFile | null = null;
+ *   @expose path = "";
+ *
+ *   @expose async save() {
+ *     if (this.photo?.isImage()) {
+ *       this.path = await this.photo.store("avatars"); // -> "avatars/<uuid>.png"
+ *       this.photo = null;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class TemporaryUploadedFile {
+  /**
+   * Path of the uploaded bytes on the temp disk.
+   * @category Metadata
+   */
+  readonly tmpPath: string;
+  /**
+   * The client-supplied original filename.
+   * @category Metadata
+   */
+  readonly originalName: string;
+  /**
+   * The upload's MIME type.
+   * @category Metadata
+   */
+  readonly mime: string;
+  /**
+   * Size of the upload in bytes.
+   * @category Metadata
+   */
+  readonly size: number;
+  /**
+   * Name of the temp disk the bytes live on (default disk when undefined).
+   * @category Metadata
+   */
+  readonly tempDisk?: string | undefined;
+
+  constructor(d: TufData) {
+    this.tmpPath = d.tmpPath;
+    this.originalName = d.originalName;
+    this.mime = d.mime;
+    this.size = d.size;
+    this.tempDisk = d.tempDisk;
+  }
+
+  /**
+   * The original filename (alias of {@link originalName}).
+   * @category Metadata
+   */
+  get name(): string {
+    return this.originalName;
+  }
+  /**
+   * Whether the upload's MIME type is an image (`image/*`).
+   * @category Metadata
+   */
+  isImage(): boolean {
+    return this.mime.startsWith("image/");
+  }
+  /**
+   * The lowercased file extension derived from the original name, sanitized to
+   * `[a-z0-9]` only (so a crafted name can't smuggle path/control characters into
+   * the stored filename). Empty string when the name has no extension.
+   * @returns The sanitized extension without the leading dot.
+   * @category Metadata
+   */
+  extension(): string {
+    const parts = this.originalName.split(".");
+    if (parts.length < 2) return "";
+    // Strip anything but [a-z0-9] so a crafted name (e.g. "x.php%00", "x./..")
+    // cannot smuggle path or control characters into the stored filename.
+    return parts
+      .pop()!
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, "");
+  }
+  /**
+   * Extract the plain {@link TufData} for serialization (used by the snapshot synth).
+   * @returns The upload's metadata without any signature.
+   * @category Storage
+   */
+  toRef(): TufData {
+    return {
+      tmpPath: this.tmpPath,
+      originalName: this.originalName,
+      mime: this.mime,
+      size: this.size,
+      tempDisk: this.tempDisk,
+    };
+  }
+
+  /**
+   * Verify a client-supplied signed ref and wrap it. Returns null when the
+   * signature is invalid (a forged or tampered ref), so callers discard it rather
+   * than trusting attacker-controlled paths.
+   * @param ref - The signed reference the client `$set`.
+   * @returns A verified file, or `null` if the signature check fails.
+   * @category Storage
+   */
+  static fromSignedRef(ref: UploadRef): TemporaryUploadedFile | null {
+    if (!verify(payload(ref), ref.sig)) return null;
+    return new TemporaryUploadedFile(ref);
+  }
+  /**
+   * Rebuild from snapshot data that is already HMAC-trusted (the whole snapshot is
+   * signed), so no per-ref signature check is needed. Used by the snapshot synth.
+   * @param data - Trusted upload metadata from the snapshot.
+   * @category Storage
+   */
+  static fromTrustedRef(data: TufData): TemporaryUploadedFile {
+    return new TemporaryUploadedFile(data);
+  }
+
+  /**
+   * Read the temp file's raw bytes from its disk.
+   * @returns The upload's contents.
+   * @category Storage
+   */
+  async bytes(): Promise<Uint8Array> {
+    return (await disk(this.tempDisk)).getBuffer(this.tmpPath);
+  }
+
+  /**
+   * Move the temp file to permanent storage and delete the temp copy.
+   *
+   * @param directory - Destination directory on the target disk (trailing slashes trimmed).
+   * @param diskName - Target storage disk; the default disk when omitted.
+   * @param filename - Explicit filename; when omitted, a random UUID plus the
+   *   sanitized {@link extension} is used.
+   * @returns The stored path (`directory/filename`).
+   * @category Storage
+   */
+  async store(directory: string, diskName?: string, filename?: string): Promise<string> {
+    const ext = this.extension();
+    const name = filename ?? `${crypto.randomUUID()}${ext ? "." + ext : ""}`;
+    const dest = `${directory.replace(/\/+$/, "")}/${name}`;
+    const temp = await disk(this.tempDisk);
+    const target = await disk(diskName);
+    const bytes = await temp.getBuffer(this.tmpPath);
+    await target.put(dest, bytes, { contentType: this.mime });
+    await temp.delete(this.tmpPath).catch(() => {});
+    return dest;
+  }
+
+  /**
+   * A URL for previewing the still-temporary file — signed and expiring on disks
+   * that support it, falling back to a plain URL otherwise.
+   * @param ttlSeconds - Lifetime of the temporary URL in seconds (default `300`).
+   * @returns A URL to the temp file.
+   * @category Storage
+   */
+  async temporaryUrl(ttlSeconds = 300): Promise<string> {
+    const d = await disk(this.tempDisk);
+    return d.temporaryUrl ? d.temporaryUrl(this.tmpPath, ttlSeconds) : d.url(this.tmpPath);
+  }
+}
+
+/**
+ * Used by Component.$set: convert client-supplied upload refs (single or array) into
+ * `TemporaryUploadedFile` instances, verifying signatures. Non-upload values pass through.
+ * A forged/invalid ref resolves to null (clearing the property) rather than trusting it.
+ */
+export function resolveUploadValue(value: unknown): unknown {
+  if (isUploadRef(value)) return TemporaryUploadedFile.fromSignedRef(value);
+  if (Array.isArray(value) && value.some(isUploadRef)) {
+    return value
+      .map((v) => (isUploadRef(v) ? TemporaryUploadedFile.fromSignedRef(v) : v))
+      .filter((v) => v !== null);
+  }
+  return value;
+}

package/src/uploads/sign.ts

@@ -0,0 +1,18 @@
+// HMAC signing for upload references — same APP_KEY scheme as snapshot signing
+// (see dehydrate.ts), so temp-file tokens are consistent and tamper-proof.
+import { safeEqual, hmacHex } from "@zerotal/core";
+
+function appKey(): string {
+  const key = Bun.env["APP_KEY"];
+  if (!key) throw new Error("[Flow] APP_KEY is not set. Upload signing requires APP_KEY.");
+  return key;
+}
+
+export function sign(payload: string): string {
+  return hmacHex(payload, appKey());
+}
+
+export function verify(payload: string, sig: string): boolean {
+  // Constant-time comparison (digest length is a fixed public constant).
+  return safeEqual(sign(payload), sig);
+}