@pithy-sh/storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/storage
+
+General file storage in your own R2 bucket, with an owner, a quota, and a link you can take back.
+
+Uploads never proxy through your Worker — the client PUTs straight to a presigned URL, and anything past 100 MiB becomes resumable parts. Downloads deliberately do stream through it, because that is the only way a read can be authorized per request.
+
+```sh
+pithy add storage
+```
+
+**Documentation: [pithy.sh/docs/capabilities/storage](https://pithy.sh/docs/capabilities/storage).** Overview, adding it, using it, and the reference: the object model, provisioning, shares.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pithy-sh/storage",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/storage"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,70 @@
+{
+  "name": "storage",
+  "package": "@pithy-sh/storage",
+  "requiredBindings": [
+    { "type": "d1", "name": "DB" },
+    { "type": "r2", "name": "STORAGE_BUCKET" },
+    {
+      "type": "workflow",
+      "name": "STORAGE_SWEEP",
+      "job": "sweep",
+      "className": "StorageSweepWorkflow",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": ["secrets"],
+  "optionalCapabilities": ["auth"],
+  "migrationNamespace": "storage",
+  "secrets": [
+    {
+      "name": "storage-r2-credentials",
+      "origin": {
+        "kind": "obtained",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/r2/api/tokens/"
+      },
+      "rotation": {
+        "kind": "manual",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/r2/api/tokens/"
+      }
+    }
+  ],
+  "whenToEnable": "Put your users' files in your own R2, behind one ObjectStore seam any capability can hold. Uploads never pass through your Worker — the client PUTs straight to a presigned URL, so a 40 GiB file costs one request and not one byte of transfer — and anything over 100 MiB is split into resumable parts automatically. Downloads do stream through the Worker, deliberately: that is the only way a read can be authorized per request, honour Range and If-None-Match, and carry a Content-Disposition you chose. Uploaded bytes are treated as untrusted on the way back out: every object response carries nosniff and a locked-down CSP, and an active type (HTML, SVG, anything +xml, script) is served as an attachment whatever was stored — so a user's upload cannot execute on your origin, and this route is not where your own HTML belongs. Keys are server-derived and opaque, so a client can never name an object or guess the one beside it; you supply a logical path, and that path is what gets stored, indexed, and listed. It has per-owner byte quotas that count uploads still in flight, server-side copy, revocable share links (a presigned URL can only expire — a share can be taken back), and a daily Workflow that reconciles orphaned rows and orphaned objects in both directions. It takes no position on what the bytes are — no transcoding, no thumbnails, no AI. That is @pithy-sh/media, which already presigns through this ObjectStore against its own bucket and credential name, and inherits none of these tables or routes for doing so. Files belong to an authenticated owner, so add auth too.",
+  "scaffold": [
+    "Add a `storage({ ... })` block to pithy.config.ts. Every option has a working default; the one worth setting early is `quota`.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_storage_objects and pithy_storage_shares.",
+    "Run `pithy storage provision` to create the per-environment R2 buckets, write the credentials secret, and deploy the sweep worker. `pithy add` writes bindings and touches no Cloudflare account; provisioning is the separate, explicit step.",
+    "Supply an R2 S3 access-key pair to that command with --r2-access-key-id and --r2-secret-access-key, or set R2_CREDENTIALS in .dev.vars. Cloudflare exposes no API for minting one, so it cannot be created for you — make the pair under R2 -> Manage API tokens.",
+    "Add `@pithy-sh/secrets` if it is not already installed. The R2 credentials are read through it, so storage will not compose without it.",
+    "Add `@pithy-sh/auth` if it is not already installed. Every owner-scoped route reads the authenticated user from the AuthContext seam; with no auth capability composed those routes deny, which is the right default but not a useful one."
+  ],
+  "configOptions": [
+    {
+      "key": "basePath",
+      "default": "/storage",
+      "describe": "Where the object routes mount. Share fetches mount separately at `sharePath`, `/s` by default, kept short because the whole URL gets pasted around."
+    },
+    {
+      "key": "multipartThresholdBytes",
+      "default": 104857600,
+      "describe": "Uploads larger than this are split into resumable parts; smaller ones get a single presigned PUT. 100 MiB. It cannot exceed R2's ~5 GiB single-part cap, because above that multipart is the only way to store the bytes at all."
+    },
+    {
+      "key": "partSizeBytes",
+      "default": 67108864,
+      "describe": "Bytes per part, for every part but the last. 64 MiB. R2 allows at most 10,000 parts, so this fixes the largest object you can store — about 625 GiB. Raise it for larger objects; the cost is that every retry re-sends a bigger part."
+    },
+    {
+      "key": "defaultVisibility",
+      "default": "private",
+      "describe": "Visibility for an upload that does not name one. Private, so a forgotten field can never publish a file."
+    },
+    {
+      "key": "pendingTtlSeconds",
+      "default": 86400,
+      "describe": "How long an unfinished upload holds its quota reservation before the daily sweep reclaims it. One day: long enough for a slow multipart upload, short enough that an abandoned one does not hold a quota forever. Edit the `quota` object by hand to cap per-owner bytes — it is unlimited by default."
+    }
+  ]
+}

package/src/capability.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { DatabaseSpecMap } from "@pithy-sh/core/src/data/databases";
+import type { KvNamespaceSpecMap } from "@pithy-sh/core/src/kv/namespaces";
+import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
+import type { Migration } from "kysely/migration";
+import { StorageConfig, type StorageConfigInput } from "./config/config";
+import { storageTables } from "./data/tables";
+import { registerStorageRoutes } from "./http/routes";
+import { storage_0001_objects } from "./migrations/0001_objects";
+import { storageSecretsRegistry } from "./secret/registry";
+import { storageExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+import { storageWorkflows } from "./workflows/specs";
+
+/**
+ * Where storage's migrations sort in the app database. Unique per database; the registry composes keys
+ * like `0800_storage_0001_objects`. Sits after matchmaking (700).
+ */
+export const STORAGE_MIGRATION_ORDER = 800;
+
+export type StorageOptions = StorageConfigInput & {
+  /** Mount the object routes somewhere other than `/storage`. */
+  basePath?: string;
+  /** Mount share fetches somewhere other than `/s`. Short by default — the whole URL gets pasted around. */
+  sharePath?: string;
+};
+
+/**
+ * The storage capability, with its resolved config attached. The workflow slice is kept literal so a
+ * composed project types `c.var.workflows.trigger("storage/sweep", { dryRun: true })` precisely — an
+ * unregistered key or a mistyped payload is a compile error, not a 500.
+ */
+export interface StorageCapability
+  extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "storage", typeof storageWorkflows> {
+  /** The resolved storage config. */
+  storageConfig: StorageConfig;
+}
+
+/**
+ * The storage capability: general file storage on the adopter's own R2 bucket — uploads that never
+ * proxy through the Worker, downloads that do, and a D1 record of what exists and who owns it.
+ *
+ * The bucket is `STORAGE_BUCKET`, deliberately separate from media's `MEDIA_BUCKET`. Buckets are free
+ * — cost is bytes and operations — so two cost nothing, and the separation buys independent teardown
+ * and independent public-access posture. `visibility: 'public'` is a plausible thing for a file store
+ * to offer and never appropriate for media's originals.
+ *
+ * `dependsOn: ["secrets"]` is real: the R2 credential bundle is read through the aggregated registry
+ * at startup, so a project composing storage without `@pithy-sh/secrets` must fail at assembly, not at
+ * the first presign. Auth is *not* listed — it is a seam. Ownership scoping reads `c.var.auth.userId`,
+ * so without `@pithy-sh/auth` every owner-scoped route denies rather than opens, which is the right
+ * failure and needs no dependency edge. It belongs in the manifest's `optionalCapabilities`.
+ */
+export function storage(options: StorageOptions = {}): StorageCapability {
+  const { basePath, sharePath, ...configInput } = options;
+  // Parse at assembly — an out-of-range part size or a threshold below it fails on deploy, not on the
+  // first large upload.
+  const resolved = StorageConfig.parse(configInput);
+
+  const migrations: Record<string, Migration> = { "0001_objects": storage_0001_objects };
+  const requiredBindings: BindingSpecInput[] = [
+    // The app database — the objects and shares tables live here.
+    { type: "d1", name: "DB" },
+    // The bucket the bytes live in. Deliberately separate from media's `MEDIA_BUCKET`.
+    { type: "r2", name: "STORAGE_BUCKET" },
+    // The sweep's Workflow binding, derived from the spec rather than written again — one declaration,
+    // so a binding rename cannot leave the two disagreeing. Optional: the binding exists only once
+    // `pithy storage provision` has deployed the sweep worker, and an unprovisioned project must still
+    // serve every upload and download route.
+    ...workflowBindings(storageWorkflows),
+  ];
+
+  const capability = defineCapability({
+    name: "storage",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    dependsOn: ["secrets"],
+    secretRegistry: storageSecretsRegistry,
+    workflows: storageWorkflows,
+    requiredBindings,
+    config: StorageConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: storageTables(),
+        migrationOrder: STORAGE_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    routes: registerStorageRoutes({ config: resolved, basePath, sharePath }),
+    seeds: [storageExampleSeed],
+  });
+
+  return Object.assign(capability, { storageConfig: resolved });
+}
+
+export function isStorageCapability(capability: Capability): capability is StorageCapability {
+  return capability.name === "storage" && "storageConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare config
+// in `vitest.workers.config.ts`: the app `DB` database the `pithy_storage_*` tables live in, and the
+// `STORAGE_BUCKET` R2 bucket objects are written to.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    STORAGE_BUCKET: R2Bucket;
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { StorageVisibility } from "../data/storageObject";
+import {
+  DEFAULT_MULTIPART_THRESHOLD_BYTES,
+  DEFAULT_PART_SIZE_BYTES,
+  MAX_PART_SIZE_BYTES,
+  MAX_UPLOAD_PARTS,
+  MIN_PART_SIZE_BYTES,
+} from "../object/multipart";
+
+/**
+ * The storage capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field is
+ * `.describe()`d: the descriptions feed the self-documenting CLI (CLAUDE.md §Config).
+ *
+ * Three decisions live here, and each has a real trade behind it.
+ *
+ * **Quota is unlimited by default, but the field is always present.** A default cap would silently
+ * break the first adopter who stores something large; an absent field would mean bolting quotas on
+ * later as a breaking change. So the knob exists from day one and starts off.
+ *
+ * **Multipart threshold 100 MiB, part size 64 MiB.** R2 caps an upload at 10,000 parts, so part size
+ * fixes the practical object ceiling: 10,000 × 64 MiB ≈ 625 GiB. Raise `partSizeBytes` to raise the
+ * ceiling (R2's own object cap is 4.995 TiB); the cost is that every retry re-sends a larger part.
+ *
+ * **Default visibility is private.** The safe default is the one where forgetting to set a field
+ * cannot leak a file.
+ */
+
+/** The largest single-part upload R2 accepts — 5 GiB, less 5 MiB. Above it, multipart is not optional. */
+const MAX_SINGLE_PART_BYTES = 5 * 1024 * 1024 * 1024 - 5 * 1024 * 1024;
+
+export const StorageQuota = z
+  .object({
+    bytesPerOwner: z
+      .number()
+      .int()
+      .positive()
+      .nullable()
+      .default(null)
+      .describe(
+        "The total bytes one owner may store, counting uploads still in flight. Null is unlimited — the default, because a cap that arrives by surprise breaks an adopter who was already storing more than it.",
+      ),
+  })
+  .describe("Per-owner storage limits. Checked when an upload starts, against pending and stored bytes together.");
+export type StorageQuota = z.output<typeof StorageQuota>;
+
+export const StorageConfig = z
+  .object({
+    quota: StorageQuota.prefault({}).describe("Per-owner byte limits. Unlimited unless configured."),
+    multipartThresholdBytes: z
+      .number()
+      .int()
+      .min(MIN_PART_SIZE_BYTES)
+      .max(MAX_SINGLE_PART_BYTES)
+      .default(DEFAULT_MULTIPART_THRESHOLD_BYTES)
+      .describe(
+        "Uploads larger than this go multipart; smaller ones get one presigned PUT. It cannot exceed R2's ~5 GiB single-part cap, because above that multipart is the only way to store the bytes at all.",
+      ),
+    partSizeBytes: z
+      .number()
+      .int()
+      .min(MIN_PART_SIZE_BYTES)
+      .max(MAX_PART_SIZE_BYTES)
+      .default(DEFAULT_PART_SIZE_BYTES)
+      .describe(
+        "Bytes per multipart part, for every part but the last. R2 allows at most 10,000 parts, so this fixes the largest object you can store: 64 MiB gives ~625 GiB. The floor is S3's 5 MiB rule for non-final parts.",
+      ),
+    defaultVisibility: StorageVisibility.default("private").describe(
+      "Visibility for an upload that does not name one. Private, so a forgotten field can never publish a file.",
+    ),
+    pendingTtlSeconds: z
+      .number()
+      .int()
+      .positive()
+      .default(24 * 60 * 60)
+      .describe(
+        "How long a `pending` row holds its quota reservation before the orphan sweep reclaims it. Long enough for a slow multipart upload to finish; short enough that an abandoned one does not hold a quota forever.",
+      ),
+  })
+  .describe("Configuration for the storage capability — quotas, multipart sizing, and default visibility.")
+  .check((ctx) => {
+    // A ceiling below the part size would mean the first "multipart" upload is a single short part,
+    // which R2 accepts but which makes the threshold meaningless. Say so rather than silently allowing it.
+    if (ctx.value.multipartThresholdBytes < ctx.value.partSizeBytes) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["multipartThresholdBytes"],
+        message: `multipartThresholdBytes (${ctx.value.multipartThresholdBytes}) is below partSizeBytes (${ctx.value.partSizeBytes}). Every multipart upload would then be a single part.`,
+      });
+    }
+  });
+export type StorageConfig = z.output<typeof StorageConfig>;
+export type StorageConfigInput = z.input<typeof StorageConfig>;
+
+/**
+ * The largest object this config can store: part size × R2's 10,000-part cap. Surfaced so the CLI and
+ * docs can state a real number rather than a rule of thumb.
+ */
+export function maxObjectBytes(config: StorageConfig): number {
+  return config.partSizeBytes * MAX_UPLOAD_PARTS;
+}

package/src/data/share.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One revocable share link — the row in `pithy_storage_shares`.
+ *
+ * **Why this is a table and not a presigned URL.** A presigned URL cannot be revoked, only expired.
+ * Once minted it is valid until its signature lapses, and nothing the owner does can call it back —
+ * so "share this file, and let me take it back" is impossible to build on presigning alone. A share
+ * is therefore a row: the token is looked up on every fetch, and revoking is a write, effective on
+ * the next request.
+ *
+ * That is also why `revokedAt` is a timestamp rather than a deleted row. A revoked share stays
+ * readable as history, and a fetch against it answers `storage/share_revoked` (410 Gone) instead of
+ * the `storage/not_found` a deleted row would produce — which tells the holder the link existed and
+ * was withdrawn, rather than leaving them guessing.
+ */
+export const StorageShare = z
+  .object({
+    token: z
+      .string()
+      .min(1)
+      .describe("The share token — the primary key, and the whole credential. High-entropy and server-generated."),
+    objectId: z.uuid().describe("The object this share grants read access to. References `pithy_storage_objects.id`."),
+    expiresAt: SQLiteDate.nullable().describe(
+      "When the link stops working. Null never expires — only revocation ends it.",
+    ),
+    revokedAt: SQLiteDate.nullable().describe("When the owner withdrew the link. Null while it is live."),
+    createdAt: SQLiteDate.describe("When the link was minted."),
+  })
+  .describe("One revocable share link — the row in `pithy_storage_shares`.");
+export type StorageShare = z.output<typeof StorageShare>;
+export type StorageShareRow = z.input<typeof StorageShare>;

package/src/data/storageObject.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One stored file — the row in `pithy_storage_objects`.
+ *
+ * Two identifiers, deliberately. `key` is the R2 object key: server-derived, opaque, unique, and
+ * never shown to a client. `path` is the adopter's logical name (`invoices/2026/q3.pdf`): indexed and
+ * listed from SQL, and never interpolated into a key. Separating them is what removes traversal,
+ * collision, and injection surfaces at once, and it keeps the key format an internal detail we can
+ * change without breaking an adopter's paths.
+ *
+ * `id` is a UUID, not an autoincrement integer, because it is externally exposed in every route path
+ * (CLAUDE.md §ID strategy) — a sequential id would let anyone enumerate how many files exist and
+ * probe for neighbors.
+ *
+ * `size` is declared by the client at init and *confirmed* against R2 at completion. It is nullable
+ * because a caller may not know it up front; a null size reserves no quota, which is why the handler
+ * requires it whenever a quota is configured.
+ */
+
+export const StorageVisibility = z
+  .enum(["private", "public"])
+  .describe(
+    "Who may read an object without a share link: `private` is the owner alone, `public` is anyone with the id. Visibility is authorization, not a bucket setting — the bucket itself stays private.",
+  );
+export type StorageVisibility = z.infer<typeof StorageVisibility>;
+
+export const StorageObjectStatus = z
+  .enum(["pending", "stored", "failed"])
+  .describe(
+    "Where an upload is: `pending` reserved the row and its quota but has no bytes yet, `stored` has bytes R2 confirmed, `failed` was abandoned. A `pending` row past its TTL is what the orphan sweep reclaims.",
+  );
+export type StorageObjectStatus = z.infer<typeof StorageObjectStatus>;
+
+export const StorageObject = z
+  .object({
+    id: z.uuid().describe("The object's public id — a UUID, because it appears in every route path."),
+    key: z
+      .string()
+      .min(1)
+      .describe("The opaque R2 object key, server-derived (`obj/<uuid>`). Unique, and never sent to a client."),
+    path: z
+      .string()
+      .min(1)
+      .describe("The adopter's logical path (`invoices/2026/q3.pdf`). Indexed and listable; never part of the key."),
+    ownerId: z
+      .string()
+      .nullable()
+      .describe("The authenticated user who owns the file, from AuthContext. Null for system-owned objects."),
+    contentType: z
+      .string()
+      .min(1)
+      .describe(
+        "The MIME type. Declared at init and overwritten at completion with what R2 stored — a presigned PUT cannot sign a content type, so only the completed row is authoritative. An active type is still neutralised on serve.",
+      ),
+    size: z
+      .number()
+      .int()
+      .nonnegative()
+      .nullable()
+      .describe("Byte count. Declared at init so the pending row reserves quota; confirmed against R2 at completion."),
+    visibility: StorageVisibility.describe("Whether anyone with the id may read this object, or only its owner."),
+    checksum: z
+      .string()
+      .nullable()
+      .describe("Lowercase hex SHA-256 of the bytes, when one is known. Null until a completion supplies it."),
+    status: StorageObjectStatus.describe("The upload's lifecycle state."),
+    uploadId: z
+      .string()
+      .nullable()
+      .describe("The multipart upload id while one is in flight. Null for a single-PUT upload and after completion."),
+    createdAt: SQLiteDate.describe("When the upload was initiated — the age the orphan sweep measures."),
+    updatedAt: SQLiteDate.describe("When the row last changed state."),
+  })
+  .describe("One stored file — the row in `pithy_storage_objects`.");
+export type StorageObject = z.output<typeof StorageObject>;
+export type StorageObjectRow = z.input<typeof StorageObject>;

package/src/data/tables.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { StorageShare } from "./share";
+import { StorageObject } from "./storageObject";
+
+/** The objects table. `CamelCasePlugin` snake-cases it to `pithy_storage_objects`. */
+export const STORAGE_OBJECTS_TABLE = "pithyStorageObjects";
+/** The share-links table. `CamelCasePlugin` snake-cases it to `pithy_storage_shares`. */
+export const STORAGE_SHARES_TABLE = "pithyStorageShares";
+
+/** The storage tables map. Both are always present — neither is behind a config flag. */
+export function storageTables(): Record<string, z.ZodObject> {
+  return {
+    [STORAGE_OBJECTS_TABLE]: StorageObject,
+    [STORAGE_SHARES_TABLE]: StorageShare,
+  };
+}
+
+/** The typed Kysely database over the storage tables. */
+export type StorageTables = {
+  [STORAGE_OBJECTS_TABLE]: typeof StorageObject;
+  [STORAGE_SHARES_TABLE]: typeof StorageShare;
+};
+export type StorageDatabase = Kysely<DatabaseSchema<StorageTables>>;
+
+/** Build the storage database from the `DB` binding (CamelCasePlugin installed). */
+export function storageDatabase(d1: D1Database): StorageDatabase {
+  return createDatabase(d1, {
+    [STORAGE_OBJECTS_TABLE]: StorageObject,
+    [STORAGE_SHARES_TABLE]: StorageShare,
+  }) as unknown as StorageDatabase;
+}