@pithy-sh/storage 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,313 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import type { Context, Hono } from "hono";
+import type { StorageConfig } from "../config/config";
+import { storageDatabase } from "../data/tables";
+import { objectStore } from "../object/store";
+import { STORAGE_R2_SECRET } from "../secret/registry";
+import { requireAuth } from "./guard";
+import {
+  abortUpload,
+  completeUpload,
+  copyObject,
+  createShare,
+  deleteObject,
+  type HandlerDeps,
+  initUpload,
+  listObjects,
+  listUploadParts,
+  presignObject,
+  readableObject,
+  resolveShare,
+  revokeShare,
+  updateObject,
+} from "./handlers";
+import {
+  CompleteUploadInput,
+  CopyObjectInput,
+  CreateShareInput,
+  CreateUploadInput,
+  ListObjectsQuery,
+  ObjectIdParam,
+  ObjectReadQuery,
+  ShareTokenParam,
+  UpdateObjectInput,
+} from "./schemas";
+import {
+  parseConditions,
+  parseRangeHeader,
+  rangeNotSatisfiable,
+  serveMetadata,
+  serveObject,
+  toObjectRange,
+} from "./serve";
+
+/**
+ * The storage routes, their declared verification strategies, and what each accepts:
+ *
+ *   POST   /storage                 → start an upload            (bearer | session)
+ *                                     json: CreateUploadInput
+ *   GET    /storage                 → list your files            (bearer | session, owner-scoped)
+ *                                     query: ListObjectsQuery
+ *   DELETE /storage/shares/:token   → revoke a share             (bearer | session, owner-scoped)
+ *                                     param: ShareTokenParam
+ *   POST   /storage/:id/complete    → finalize a multipart       (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam, json: CompleteUploadInput
+ *   POST   /storage/:id/abort       → abandon an upload          (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam — no body
+ *   GET    /storage/:id/parts       → resume a multipart         (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam
+ *   POST   /storage/:id/copy        → server-side copy           (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam, json: CopyObjectInput
+ *   POST   /storage/:id/shares      → mint a revocable share     (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam, json: CreateShareInput
+ *   GET    /storage/:id/url         → presigned direct URL       (bearer | session, owner-or-public)
+ *                                     param: ObjectIdParam
+ *   GET    /storage/:id             → stream the bytes           (public when `visibility: 'public'`,
+ *                                                                 otherwise bearer | session + owner)
+ *                                     param: ObjectIdParam, query: ObjectReadQuery
+ *   HEAD   /storage/:id             → metadata only              (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam
+ *   PATCH  /storage/:id             → rename or change access    (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam, json: UpdateObjectInput
+ *   DELETE /storage/:id             → delete file and row        (bearer | session, owner-scoped)
+ *                                     param: ObjectIdParam
+ *   GET    /s/:token                → fetch via a share link     (public — the token is the credential)
+ *                                     param: ShareTokenParam, query: ObjectReadQuery
+ *
+ * **Every validator sits after the guard.** An unauthenticated request with a malformed body is a
+ * 401, never a 400 — shape is not something a caller learns before being verified. `POST
+ * /storage/:id/abort` carries no json validator because it reads no body: adding one would 400 the
+ * bodyless POST every client sends today.
+ *
+ * `GET /storage/:id` is the one route with two strategies, because a public file must be readable by
+ * someone with no session at all. It is therefore **not** wrapped in {@link requireAuth}: the guard
+ * would deny before the handler could see that the object is public. Authorization happens inside the
+ * handler instead, against `c.var.auth` — which is `null` with no auth capability composed, so a
+ * private object is denied by default and only an explicitly public one is served.
+ *
+ * **Static segments are registered before `:param` ones.** Hono matches in registration order, so
+ * `/storage/shares/:token` has to come before `/storage/:id` or a DELETE to `/storage/shares/abc`
+ * would be read as deleting the object whose id is `shares`.
+ *
+ * **Uploads never proxy bytes through the Worker; downloads do.** That asymmetry is the design, not
+ * an inconsistency — `serve.ts` carries the reasoning.
+ */
+export interface StorageRoutesOptions {
+  /** The resolved storage config. */
+  config: StorageConfig;
+  /** Where the object routes mount. Defaults to `/storage`. */
+  basePath?: string;
+  /** Where share fetches mount. Defaults to `/s` — short, because the whole URL gets pasted around. */
+  sharePath?: string;
+  /** Test seam: resolve handler deps from the request. Defaults to the env-based resolver. */
+  resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
+}
+
+/** The bindings the storage routes read off the Worker env. */
+interface StorageEnv extends SecretsStoreEnv {
+  /** The app database the `pithy_storage_*` tables live in. */
+  DB: D1Database;
+  /** The bucket objects are stored in. */
+  STORAGE_BUCKET: R2Bucket;
+}
+
+/**
+ * Read one binding, or fail with a message naming the binding and how to add it. A `?.` here would
+ * turn a missing binding into a `TypeError` at the first query, attributed to nothing.
+ */
+function requireBinding<T>(env: unknown, name: string, kind: string): T {
+  const value = (env as Record<string, unknown>)[name];
+  if (!value) {
+    throw new InternalError({
+      message: "Storage is not configured.",
+      action: `Bind ${kind} named ${name} in wrangler.jsonc, then redeploy.`,
+      detail: `@pithy-sh/storage requires the ${name} binding; none was present on env.`,
+    });
+  }
+  return value as T;
+}
+
+/** Build the default per-request dependency resolver from the resolved config. */
+function defaultResolveDeps(config: StorageConfig): (c: Context<PithyHonoEnv>) => Promise<HandlerDeps> {
+  return async (c) => {
+    const env = c.env as unknown as StorageEnv;
+    const bucket = requireBinding<R2Bucket>(env, "STORAGE_BUCKET", "an R2 bucket");
+    const d1 = requireBinding<D1Database>(env, "DB", "a D1 database");
+    return {
+      db: storageDatabase(d1),
+      // Credentials resolve lazily inside the store, so a request that only reads bytes through the
+      // binding never touches the secrets store.
+      store: objectStore({ bucket, env, secretName: STORAGE_R2_SECRET }),
+      config,
+      ownerId: c.var.auth?.userId ?? null,
+      newId: () => crypto.randomUUID(),
+      // 32 bytes of CSPRNG output, base64url. The token *is* the credential for a share link, so its
+      // entropy is the only thing standing between a link and anyone guessing one.
+      newToken: () => shareToken(),
+      now: () => new Date(),
+    };
+  };
+}
+
+/** A 256-bit share token, base64url-encoded and unpadded so it is safe in a path segment. */
+function shareToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  const binary = String.fromCharCode(...bytes);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Register the storage sub-router. Returned as the capability's `routes` hook. */
+export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/storage";
+  const share = options.sharePath ?? "/s";
+  const resolve = options.resolveDeps ?? defaultResolveDeps(options.config);
+
+  /** Stream one object, honoring `Range` and `If-None-Match`. Shared by the id route and the share route. */
+  const stream = async (
+    c: Context<PithyHonoEnv>,
+    deps: HandlerDeps,
+    object: Awaited<ReturnType<typeof readableObject>>,
+    download: boolean,
+  ) => {
+    const requested = parseRangeHeader(c.req.header("range"), object.size);
+    if (requested.kind === "unsatisfiable") return rangeNotSatisfiable(object.size ?? 0);
+
+    const result = await deps.store.get(object.key, {
+      range: toObjectRange(requested),
+      onlyIf: parseConditions(c.req.header("if-none-match")),
+    });
+    if (!result) {
+      // The row says stored but R2 has nothing. Reported as missing rather than as a 500: from the
+      // caller's side the file is gone, and the orphan sweep is what reconciles the two stores.
+      return c.notFound();
+    }
+    return serveObject({
+      metadata: result.metadata,
+      body: result.body,
+      range: result.range,
+      path: object.path,
+      visibility: object.visibility,
+      download,
+    });
+  };
+
+  return (app) => {
+    app.post(base, requireAuth(), zValidator("json", CreateUploadInput, validationHook), async (c) => {
+      return c.json(await initUpload(await resolve(c), c.req.valid("json")), 201);
+    });
+
+    app.get(base, requireAuth(), zValidator("query", ListObjectsQuery, validationHook), async (c) => {
+      return c.json(await listObjects(await resolve(c), c.req.valid("query")));
+    });
+
+    // Static before `:id` — see the file doc comment.
+    app.delete(
+      `${base}/shares/:token`,
+      requireAuth(),
+      zValidator("param", ShareTokenParam, validationHook),
+      async (c) => {
+        return c.json(await revokeShare(await resolve(c), c.req.valid("param").token));
+      },
+    );
+
+    app.post(
+      `${base}/:id/complete`,
+      requireAuth(),
+      zValidator("param", ObjectIdParam, validationHook),
+      zValidator("json", CompleteUploadInput, validationHook),
+      async (c) => {
+        return c.json(await completeUpload(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
+      },
+    );
+
+    // No json validator: this route reads no body, and a client that sends none must keep working.
+    app.post(`${base}/:id/abort`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
+      return c.json(await abortUpload(await resolve(c), c.req.valid("param").id));
+    });
+
+    // The resume path: what R2 already holds, and a fresh URL for every part still missing. Minting
+    // on demand is what keeps a part URL's TTL short without making a stalled upload unrecoverable.
+    app.get(`${base}/:id/parts`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
+      return c.json(await listUploadParts(await resolve(c), c.req.valid("param").id));
+    });
+
+    app.post(
+      `${base}/:id/copy`,
+      requireAuth(),
+      zValidator("param", ObjectIdParam, validationHook),
+      zValidator("json", CopyObjectInput, validationHook),
+      async (c) => {
+        return c.json(await copyObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
+      },
+    );
+
+    app.post(
+      `${base}/:id/shares`,
+      requireAuth(),
+      zValidator("param", ObjectIdParam, validationHook),
+      zValidator("json", CreateShareInput, validationHook),
+      async (c) => {
+        return c.json(await createShare(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
+      },
+    );
+
+    app.get(`${base}/:id/url`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
+      return c.json(await presignObject(await resolve(c), c.req.valid("param").id));
+    });
+
+    // No `requireAuth`: a public object must be readable without a session. The handler authorizes.
+    app.get(
+      `${base}/:id`,
+      zValidator("param", ObjectIdParam, validationHook),
+      zValidator("query", ObjectReadQuery, validationHook),
+      async (c) => {
+        const deps = await resolve(c);
+        const object = await readableObject(deps, c.req.valid("param").id);
+        return stream(c, deps, object, c.req.valid("query").download === "1");
+      },
+    );
+
+    app.on("HEAD", `${base}/:id`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
+      const deps = await resolve(c);
+      const object = await readableObject(deps, c.req.valid("param").id);
+      const metadata = await deps.store.head(object.key);
+      if (!metadata) return c.notFound();
+      return serveMetadata({ metadata, path: object.path, visibility: object.visibility });
+    });
+
+    app.patch(
+      `${base}/:id`,
+      requireAuth(),
+      zValidator("param", ObjectIdParam, validationHook),
+      zValidator("json", UpdateObjectInput, validationHook),
+      async (c) => {
+        return c.json(await updateObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
+      },
+    );
+
+    app.delete(`${base}/:id`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
+      return c.json(await deleteObject(await resolve(c), c.req.valid("param").id));
+    });
+
+    // Public by design: the token is the credential, and it is checked on every fetch — which is what
+    // makes revocation possible at all.
+    app.get(
+      `${share}/:token`,
+      zValidator("param", ShareTokenParam, validationHook),
+      zValidator("query", ObjectReadQuery, validationHook),
+      async (c) => {
+        const deps = await resolve(c);
+        const object = await resolveShare(deps, c.req.valid("param").token);
+        return stream(c, deps, object, c.req.valid("query").download === "1");
+      },
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,214 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { StorageVisibility } from "../data/storageObject";
+import { MAX_OBJECT_KEY_BYTES } from "../object/key";
+import { ReportedPart } from "../object/multipart";
+
+/**
+ * The request schemas for the storage routes. Every path parameter, query string and body is parsed
+ * here before a handler sees it (CLAUDE.md §Zod: validate at every boundary), declared on the route
+ * line with `zValidator(target, Schema, validationHook)` — so reading `routes.ts` tells you what a
+ * route accepts without opening a handler. A failure maps to `validation/invalid_input` through
+ * `fromZodError`.
+ *
+ * Two shapes deserve a note.
+ *
+ * **`path` is bounded and control-character-free, but otherwise unconstrained.** It is the adopter's
+ * logical name and never becomes an R2 key, so `../` is not a traversal — it is just an odd file
+ * name. What it *is* is a value that gets stored, listed, and eventually rendered somewhere, so a NUL
+ * or a newline in it is rejected: those break log lines, headers, and `Content-Disposition` rather
+ * than escaping a prefix. The length bound matches R2's key limit even though the path is not a key,
+ * because an unbounded text column is an easy way to fill someone's database.
+ *
+ * **`size` is required on upload-init.** A presigned PUT signs `Content-Length`, so the client must
+ * commit to a byte count before a URL can be minted at all. It is also what the `pending` row
+ * reserves against the owner's quota — a null size would reserve nothing and make the quota a
+ * suggestion under concurrency (see `quota/quota.ts`).
+ */
+
+/**
+ * Whether a path is free of C0 control characters and DEL. Written as a scan rather than a regex
+ * because a regex spelling this needs literal control-character escapes, which Biome rejects — and
+ * the rule it rejects them under is a good one.
+ */
+function isPrintablePath(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return false;
+  }
+  return true;
+}
+
+/** The logical path field, shared by upload-init, rename, and copy so the three cannot drift apart. */
+const logicalPath = z
+  .string()
+  .min(1)
+  .max(MAX_OBJECT_KEY_BYTES)
+  .refine(isPrintablePath, { error: "A path may not contain control characters." })
+  .describe(
+    "The file's logical name, e.g. `invoices/2026/q3.pdf`. Stored, indexed, and listable by prefix; never part of the R2 key, so slashes are naming, not directories.",
+  );
+
+/**
+ * The `:id` path parameter every single-object route carries. Deliberately a bounded generic string
+ * and **not** `z.uuid()`: ids are minted with `crypto.randomUUID()`, but this is a shape check, not a
+ * lookup. A well-formed id nobody owns must still reach the handler and answer `storage/not_found`
+ * (404) — the answer that keeps the route from being an enumeration oracle. A UUID check would turn
+ * that into a 400 and hand back a shape the caller could probe against.
+ */
+export const ObjectIdParam = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe("The object id from the path. Bounded so an unbounded string never reaches the database."),
+  })
+  .describe("The path parameter identifying one stored object.");
+export type ObjectIdParam = z.output<typeof ObjectIdParam>;
+
+/**
+ * The `:token` path parameter the two share routes carry. Bounded only — a minted token is 43
+ * base64url characters, but the bound exists to stop an unbounded string reaching the shares table,
+ * not to pre-empt the lookup. An unknown-but-well-formed token still answers `storage/not_found`.
+ */
+export const ShareTokenParam = z
+  .object({
+    token: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe("The share token from the path — the credential itself, checked against the shares table."),
+  })
+  .describe("The path parameter identifying one share link.");
+export type ShareTokenParam = z.output<typeof ShareTokenParam>;
+
+/**
+ * The query string an object read accepts. Only `?download=1` means anything; every other value is
+ * simply not a download, which is what the bare string comparison said before and still says. Typed
+ * as a bounded string rather than `z.literal("1")` because `?download=0` is a request that works
+ * today, and a literal would answer it with a 400.
+ */
+export const ObjectReadQuery = z
+  .object({
+    download: z
+      .string()
+      .max(16)
+      .optional()
+      .describe("`1` serves the bytes as an attachment. Anything else, or omitted, serves them inline."),
+  })
+  .describe("Query parameters for reading an object's bytes, by id or through a share link.");
+export type ObjectReadQuery = z.output<typeof ObjectReadQuery>;
+
+export const CreateUploadInput = z
+  .object({
+    path: logicalPath,
+    contentType: z
+      .string()
+      .min(1)
+      .max(255)
+      .describe(
+        "The file's MIME type, as you intend it. A declaration, not a constraint: a presigned PUT cannot sign a content type, so completion replaces this with the type R2 actually stored.",
+      ),
+    size: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        "The exact byte count. Required: the presigned PUT signs Content-Length, and the pending row reserves these bytes against the owner's quota the moment it is written.",
+      ),
+    visibility: StorageVisibility.optional().describe(
+      "Who may read the file once stored. Omitted takes the configured default, which is private.",
+    ),
+  })
+  .describe("A request to start an upload — what the file is called, what it is, and how big it is.");
+export type CreateUploadInput = z.output<typeof CreateUploadInput>;
+
+export const CompleteUploadInput = z
+  .object({
+    parts: z
+      .array(ReportedPart)
+      .default([])
+      .describe(
+        "Every part's number and the ETag R2 answered its PUT with. Empty for a single-PUT upload, which has no parts to assemble.",
+      ),
+    checksum: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/)
+      .optional()
+      .describe(
+        "Lowercase hex SHA-256 the client computed over the bytes it sent. Recorded, not verified server-side.",
+      ),
+  })
+  .describe("A request to finalize an upload — the parts to assemble, and optionally what was sent.");
+export type CompleteUploadInput = z.output<typeof CompleteUploadInput>;
+
+export const UpdateObjectInput = z
+  .object({
+    path: logicalPath.optional(),
+    visibility: StorageVisibility.optional().describe(
+      "Change who may read the file. Takes effect on the next request.",
+    ),
+  })
+  .describe("A rename, a visibility change, or both. At least one field must be present.")
+  .check((ctx) => {
+    // An empty patch is almost always a client bug — a field name that did not survive serialization.
+    // Answering 200 to it would hide that; answering 400 names it.
+    if (ctx.value.path === undefined && ctx.value.visibility === undefined) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: [],
+        message: "Send a path, a visibility, or both — an empty patch changes nothing.",
+      });
+    }
+  });
+export type UpdateObjectInput = z.output<typeof UpdateObjectInput>;
+
+export const CopyObjectInput = z
+  .object({ path: logicalPath })
+  .describe("A server-side copy — the new file's logical path. The bytes never leave R2.");
+export type CopyObjectInput = z.output<typeof CopyObjectInput>;
+
+/** One year. A share that outlives the memory of granting it is indistinguishable from a public file. */
+const MAX_SHARE_TTL_SECONDS = 365 * 24 * 60 * 60;
+
+export const CreateShareInput = z
+  .object({
+    expiresInSeconds: z
+      .number()
+      .int()
+      .positive()
+      .max(MAX_SHARE_TTL_SECONDS)
+      .optional()
+      .describe(
+        "How long the link works, in seconds. Omitted never expires — revocation is then the only way to end it, which is a deliberate choice rather than a default.",
+      ),
+  })
+  .describe("A request to mint a revocable share link for one file.");
+export type CreateShareInput = z.output<typeof CreateShareInput>;
+
+export const ListObjectsQuery = z
+  .object({
+    prefix: z
+      .string()
+      .max(MAX_OBJECT_KEY_BYTES)
+      .optional()
+      .describe("Only files whose logical path starts with this. Omitted lists everything you own."),
+    cursor: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The `cursor` a previous page returned. Opaque — pass it back unchanged to advance."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Files per page. Defaults to 50, capped at 100 so one request cannot scan an entire owner's files."),
+  })
+  .describe("Query parameters for the owner's file listing.");
+export type ListObjectsQuery = z.output<typeof ListObjectsQuery>;