@pithy-sh/storage 0.2.10 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/dist/capability.d.ts +12 -3
  2. package/dist/capability.d.ts.map +1 -1
  3. package/dist/capability.js +35 -9
  4. package/dist/config/config.d.ts +20 -4
  5. package/dist/config/config.d.ts.map +1 -1
  6. package/dist/config/config.js +23 -6
  7. package/dist/data/storageObject.d.ts +12 -0
  8. package/dist/data/storageObject.d.ts.map +1 -1
  9. package/dist/data/storageObject.js +13 -2
  10. package/dist/data/tables.js +1 -1
  11. package/dist/error/errors.js +2 -2
  12. package/dist/http/handlers.d.ts +48 -16
  13. package/dist/http/handlers.d.ts.map +1 -1
  14. package/dist/http/handlers.js +169 -66
  15. package/dist/http/responses.d.ts +173 -0
  16. package/dist/http/responses.d.ts.map +1 -0
  17. package/dist/http/responses.js +92 -0
  18. package/dist/http/routes.d.ts +13 -2
  19. package/dist/http/routes.d.ts.map +1 -1
  20. package/dist/http/routes.js +134 -22
  21. package/dist/http/schemas.d.ts +6 -0
  22. package/dist/http/schemas.d.ts.map +1 -1
  23. package/dist/http/schemas.js +7 -6
  24. package/dist/http/scopes.d.ts +25 -0
  25. package/dist/http/scopes.d.ts.map +1 -0
  26. package/dist/http/scopes.js +32 -0
  27. package/dist/http/serve.d.ts +5 -2
  28. package/dist/http/serve.d.ts.map +1 -1
  29. package/dist/index.d.ts +2 -0
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +5 -3
  32. package/dist/migrations/0002_ownership.d.ts +5 -0
  33. package/dist/migrations/0002_ownership.d.ts.map +1 -0
  34. package/dist/migrations/0002_ownership.js +114 -0
  35. package/dist/object/cloudflare.d.ts +3 -2
  36. package/dist/object/cloudflare.d.ts.map +1 -1
  37. package/dist/object/cloudflare.js +3 -3
  38. package/dist/object/store.d.ts +2 -7
  39. package/dist/object/store.d.ts.map +1 -1
  40. package/dist/object/store.js +1 -6
  41. package/dist/object/uploadedPart.d.ts +11 -0
  42. package/dist/object/uploadedPart.d.ts.map +1 -0
  43. package/dist/object/uploadedPart.js +12 -0
  44. package/dist/provision/provisionStorage.d.ts +14 -2
  45. package/dist/provision/provisionStorage.d.ts.map +1 -1
  46. package/dist/provision/provisionStorage.js +19 -4
  47. package/dist/provision/resolveStorageConfig.js +1 -1
  48. package/dist/quota/ceiling.d.ts +36 -0
  49. package/dist/quota/ceiling.d.ts.map +1 -0
  50. package/dist/quota/ceiling.js +31 -0
  51. package/dist/quota/quota.d.ts +24 -7
  52. package/dist/quota/quota.d.ts.map +1 -1
  53. package/dist/quota/quota.js +40 -12
  54. package/dist/secret/bundleToken.d.ts +24 -0
  55. package/dist/secret/bundleToken.d.ts.map +1 -0
  56. package/dist/secret/bundleToken.js +74 -0
  57. package/dist/secret/registry.d.ts +5 -1
  58. package/dist/secret/registry.d.ts.map +1 -1
  59. package/dist/secret/registry.js +7 -3
  60. package/dist/seeds/example.d.ts.map +1 -1
  61. package/dist/seeds/example.js +3 -0
  62. package/dist/test-utils/liveStorage.d.ts.map +1 -1
  63. package/dist/test-utils/liveStorage.js +5 -2
  64. package/dist/version.generated.d.ts +1 -1
  65. package/dist/version.generated.d.ts.map +1 -1
  66. package/dist/version.generated.js +1 -1
  67. package/package.json +7 -7
  68. package/pithy.manifest.json +20 -10
  69. package/src/capability.ts +52 -8
  70. package/src/config/config.ts +24 -6
  71. package/src/data/storageObject.ts +22 -6
  72. package/src/error/errors.ts +2 -2
  73. package/src/http/handlers.ts +215 -81
  74. package/src/http/responses.ts +168 -0
  75. package/src/http/routes.ts +245 -46
  76. package/src/http/schemas.ts +11 -5
  77. package/src/http/scopes.ts +39 -0
  78. package/src/http/serve.ts +5 -2
  79. package/src/index.ts +2 -0
  80. package/src/migrations/0002_ownership.ts +176 -0
  81. package/src/object/cloudflare.ts +4 -3
  82. package/src/object/store.ts +6 -10
  83. package/src/object/uploadedPart.ts +17 -0
  84. package/src/provision/provisionStorage.ts +22 -3
  85. package/src/quota/ceiling.ts +44 -0
  86. package/src/quota/quota.ts +63 -20
  87. package/src/secret/bundleToken.ts +81 -0
  88. package/src/secret/registry.ts +6 -8
  89. package/src/seeds/example.ts +3 -0
  90. package/src/test-utils/liveStorage.ts +3 -6
  91. package/src/version.generated.ts +1 -1
@@ -0,0 +1,168 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+
4
+ import { z } from "zod";
5
+ import { StorageObjectStatus, StorageVisibility } from "../data/storageObject";
6
+ import { UploadedPart } from "../object/uploadedPart";
7
+
8
+ /**
9
+ * What the storage routes return as JSON, as Zod objects a client can validate against and the OpenAPI
10
+ * contract can describe. The byte-serving routes (`GET` and `HEAD /storage/:id`, `GET /s/:token`) answer
11
+ * with the object itself rather than JSON, and `routes.ts` describes those inline.
12
+ *
13
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. These describe JSON on
14
+ * the wire, so a date is the ISO-8601 string `c.json` writes, and nothing here carries a codec or a
15
+ * transform: parsing a response hands back exactly what went in, which is what lets
16
+ * `routes.workers.test.ts` parse a real answer and compare it with the original.
17
+ *
18
+ * **A field added here later is `.optional()` as well as `.nullable()`.** A client generated from the
19
+ * contract reads Workers on older releases too, and a required key they cannot send fails it outright.
20
+ */
21
+
22
+ /** A stored file as a client sees it. The object key and the R2 upload id never appear. */
23
+ export const StorageObjectResponse = z
24
+ .object({
25
+ id: z.string().describe("The file's id. What every other route takes as `:id`."),
26
+ path: z.string().describe("The file's logical path, as the owner named it. Never an R2 key."),
27
+ ownerId: z
28
+ .string()
29
+ .nullable()
30
+ .describe(
31
+ "The id of the user who owns the file. Null for a system-owned file, and for any file read by someone not acting for its organization.",
32
+ ),
33
+ organizationId: z
34
+ .string()
35
+ .nullable()
36
+ .optional()
37
+ .describe(
38
+ "The organization the file was written under. Null when none was in force, and for any file read by someone not acting for it; absent from a Worker that predates it.",
39
+ ),
40
+ contentType: z
41
+ .string()
42
+ .describe("The file's MIME type: as declared at upload, replaced at completion by the type R2 stored."),
43
+ size: z
44
+ .number()
45
+ .int()
46
+ .nullable()
47
+ .describe("The file's size in bytes: as declared at upload, replaced at completion by what R2 stored."),
48
+ visibility: StorageVisibility,
49
+ checksum: z
50
+ .string()
51
+ .nullable()
52
+ .describe(
53
+ "Lowercase hex SHA-256 the client reported at completion, or R2's own when it reported none. Null until stored.",
54
+ ),
55
+ status: StorageObjectStatus,
56
+ createdAt: z.iso.datetime().describe("When the upload was started, ISO-8601."),
57
+ updatedAt: z.iso.datetime().describe("When the record last changed, ISO-8601."),
58
+ })
59
+ .describe("One stored file, without its object key or upload id.");
60
+ export type StorageObjectResponse = z.infer<typeof StorageObjectResponse>;
61
+
62
+ /** One part of a multipart upload, with the URL its bytes go to. */
63
+ export const UploadPartTargetResponse = z
64
+ .object({
65
+ partNumber: z.number().int().describe("The part's 1-based index within the upload."),
66
+ offset: z.number().int().describe("Where the part starts in the file, in bytes from 0."),
67
+ length: z.number().int().describe("How many bytes the part carries."),
68
+ url: z.string().describe("The presigned URL to PUT exactly these bytes to. Valid for an hour."),
69
+ })
70
+ .describe("One part of a multipart upload and where to send it.");
71
+ export type UploadPartTargetResponse = z.infer<typeof UploadPartTargetResponse>;
72
+
73
+ /** Where the bytes go: one URL, or one per part. */
74
+ export const UploadTargetResponse = z
75
+ .discriminatedUnion("kind", [
76
+ z
77
+ .object({
78
+ kind: z.literal("single").describe("One PUT carries the whole file."),
79
+ url: z.string().describe("The presigned URL to PUT the whole file to. It signs the declared size."),
80
+ })
81
+ .describe("A single-PUT upload."),
82
+ z
83
+ .object({
84
+ kind: z.literal("multipart").describe("The file goes up in parts, each to its own URL."),
85
+ uploadId: z.string().describe("R2's id for the multipart upload."),
86
+ partSize: z.number().int().describe("The size of every part but the last, in bytes."),
87
+ parts: z.array(UploadPartTargetResponse).describe("Every part, in order, each with its own URL."),
88
+ })
89
+ .describe("A multipart upload, used once the file is past the configured threshold."),
90
+ ])
91
+ .describe("Where to send the file's bytes.");
92
+ export type UploadTargetResponse = z.infer<typeof UploadTargetResponse>;
93
+
94
+ /** What starting an upload returns. */
95
+ export const UploadInitResponse = z
96
+ .object({
97
+ object: StorageObjectResponse,
98
+ upload: UploadTargetResponse,
99
+ })
100
+ .describe("The upload was started: the pending file's record, and where its bytes go.");
101
+ export type UploadInitResponse = z.infer<typeof UploadInitResponse>;
102
+
103
+ /** One page of the caller's files. */
104
+ export const ObjectListResponse = z
105
+ .object({
106
+ objects: z.array(StorageObjectResponse).describe("The caller's files on this page, ordered by logical path."),
107
+ cursor: z
108
+ .string()
109
+ .optional()
110
+ .describe("Pass this back as `cursor` to read the next page. Absent on the last page."),
111
+ })
112
+ .describe("One page of the caller's files.");
113
+ export type ObjectListResponse = z.infer<typeof ObjectListResponse>;
114
+
115
+ /** Where a resuming client stands. */
116
+ export const UploadPartsResponse = z
117
+ .object({
118
+ uploadId: z.string().describe("R2's id for the multipart upload."),
119
+ partSize: z.number().int().describe("The size of every part but the last, in bytes."),
120
+ partCount: z.number().int().describe("How many parts the upload has in all."),
121
+ uploaded: z.array(UploadedPart).describe("The parts R2 already holds. Do not send these again."),
122
+ missing: z.array(UploadPartTargetResponse).describe("The parts still to send, each with a freshly presigned URL."),
123
+ })
124
+ .describe("A multipart upload's progress: what R2 holds, and a live URL for every part it does not.");
125
+ export type UploadPartsResponse = z.infer<typeof UploadPartsResponse>;
126
+
127
+ /** A presigned direct-download URL. */
128
+ export const PresignedUrlResponse = z
129
+ .object({
130
+ url: z.string().describe("A presigned GET for the file's bytes. Anyone holding it can read them until it lapses."),
131
+ expiresInSeconds: z.number().int().describe("How long the URL works, in seconds from now."),
132
+ })
133
+ .describe("A short-lived direct-download URL that bypasses the Worker.");
134
+ export type PresignedUrlResponse = z.infer<typeof PresignedUrlResponse>;
135
+
136
+ /** What deleting a file returns. */
137
+ export const ObjectDeletedResponse = z
138
+ .object({
139
+ id: z.string().describe("The id of the file that was deleted."),
140
+ deleted: z.literal(true).describe("Always true: the file, its record and its share links are gone."),
141
+ })
142
+ .describe("The file was deleted.");
143
+ export type ObjectDeletedResponse = z.infer<typeof ObjectDeletedResponse>;
144
+
145
+ /** A minted share link. */
146
+ export const ShareResponse = z
147
+ .object({
148
+ token: z
149
+ .string()
150
+ .describe("The share token. The link is the share path followed by this, and it is the credential."),
151
+ objectId: z.string().describe("The id of the file the link reads."),
152
+ expiresAt: z.iso
153
+ .datetime()
154
+ .nullable()
155
+ .describe("When the link stops working, ISO-8601, or null when it never expires."),
156
+ createdAt: z.iso.datetime().describe("When the link was minted, ISO-8601."),
157
+ })
158
+ .describe("A revocable share link for one file.");
159
+ export type ShareResponse = z.infer<typeof ShareResponse>;
160
+
161
+ /** What revoking a share link returns. */
162
+ export const ShareRevokedResponse = z
163
+ .object({
164
+ token: z.string().describe("The share token that was revoked."),
165
+ revokedAt: z.iso.datetime().describe("When the link was first revoked, ISO-8601. Revoking again keeps this time."),
166
+ })
167
+ .describe("The share link was revoked.");
168
+ export type ShareRevokedResponse = z.infer<typeof ShareRevokedResponse>;
@@ -2,15 +2,21 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
5
- import { zValidator } from "@hono/zod-validator";
5
+ import { accessCaller, type PermissionHook } from "@pithy-sh/core/src/access/access";
6
+ import { UsageQuery, UsageResponse, usageRollup } from "@pithy-sh/core/src/access/usage";
6
7
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
8
+ import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
7
9
  import { InternalError } from "@pithy-sh/core/src/error/pithyError";
8
- import { validationHook } from "@pithy-sh/core/src/http/validation";
10
+ import { describeRoute, type RouteResponse } from "@pithy-sh/core/src/http/routeSpec";
11
+ import { validate } from "@pithy-sh/core/src/http/validation";
12
+ import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
9
13
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
10
14
  import type { Context, Hono } from "hono";
15
+ import type { Kysely } from "kysely";
11
16
  import type { StorageConfig } from "../config/config";
12
- import { storageDatabase } from "../data/tables";
17
+ import { STORAGE_OBJECTS_TABLE, storageDatabase } from "../data/tables";
13
18
  import { objectStore } from "../object/store";
19
+ import { storageCeiling } from "../quota/ceiling";
14
20
  import { STORAGE_R2_SECRET } from "../secret/registry";
15
21
  import { requireAuth } from "./guard";
16
22
  import {
@@ -29,6 +35,16 @@ import {
29
35
  revokeShare,
30
36
  updateObject,
31
37
  } from "./handlers";
38
+ import {
39
+ ObjectDeletedResponse,
40
+ ObjectListResponse,
41
+ PresignedUrlResponse,
42
+ ShareResponse,
43
+ ShareRevokedResponse,
44
+ StorageObjectResponse,
45
+ UploadInitResponse,
46
+ UploadPartsResponse,
47
+ } from "./responses";
32
48
  import {
33
49
  CompleteUploadInput,
34
50
  CopyObjectInput,
@@ -40,6 +56,7 @@ import {
40
56
  ShareTokenParam,
41
57
  UpdateObjectInput,
42
58
  } from "./schemas";
59
+ import { STORAGE_USAGE_READ_SCOPE } from "./scopes";
43
60
  import {
44
61
  parseConditions,
45
62
  parseRangeHeader,
@@ -54,8 +71,10 @@ import {
54
71
  *
55
72
  * POST /storage → start an upload (bearer | session)
56
73
  * json: CreateUploadInput
57
- * GET /storage → list your files (bearer | session, owner-scoped)
74
+ * GET /storage → list the files you may see (bearer | session)
58
75
  * query: ListObjectsQuery
76
+ * GET /storage/admin/usage → files and bytes held (control-plane, storage:usage:read)
77
+ * query: UsageQuery
59
78
  * DELETE /storage/shares/:token → revoke a share (bearer | session, owner-scoped)
60
79
  * param: ShareTokenParam
61
80
  * POST /storage/:id/complete → finalize a multipart (bearer | session, owner-scoped)
@@ -71,7 +90,7 @@ import {
71
90
  * GET /storage/:id/url → presigned direct URL (bearer | session, owner-or-public)
72
91
  * param: ObjectIdParam
73
92
  * GET /storage/:id → stream the bytes (public when `visibility: 'public'`,
74
- * otherwise bearer | session + owner)
93
+ * otherwise bearer | session + readable)
75
94
  * param: ObjectIdParam, query: ObjectReadQuery
76
95
  * HEAD /storage/:id → metadata only (bearer | session, owner-scoped)
77
96
  * param: ObjectIdParam
@@ -87,6 +106,12 @@ import {
87
106
  * /storage/:id/abort` carries no json validator because it reads no body: adding one would 400 the
88
107
  * bodyless POST every client sends today.
89
108
  *
109
+ * **"Owner-scoped" above means the access rules, not the owner alone.** Every route reads a file only if its
110
+ * visibility admits the caller — its owner acting for its organization, any member for `organization`,
111
+ * anyone for `public` — and changes one only for its owner or a role holding `storage:manage` in its
112
+ * organization, with the adopter's permission hook asked about both. A file the caller may not read is
113
+ * not found, never forbidden (`handlers.ts`).
114
+ *
90
115
  * `GET /storage/:id` is the one route with two strategies, because a public file must be readable by
91
116
  * someone with no session at all. It is therefore **not** wrapped in {@link requireAuth}: the guard
92
117
  * would deny before the handler could see that the object is public. Authorization happens inside the
@@ -107,6 +132,8 @@ export interface StorageRoutesOptions {
107
132
  basePath?: string;
108
133
  /** Where share fetches mount. Defaults to `/s` — short, because the whole URL gets pasted around. */
109
134
  sharePath?: string;
135
+ /** The adopter's permission hook: allow, deny, or the default rules, asked on every file read and write. */
136
+ permission?: PermissionHook;
110
137
  /** Test seam: resolve handler deps from the request. Defaults to the env-based resolver. */
111
138
  resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
112
139
  }
@@ -136,7 +163,10 @@ function requireBinding<T>(env: unknown, name: string, kind: string): T {
136
163
  }
137
164
 
138
165
  /** Build the default per-request dependency resolver from the resolved config. */
139
- function defaultResolveDeps(config: StorageConfig): (c: Context<PithyHonoEnv>) => Promise<HandlerDeps> {
166
+ function defaultResolveDeps(
167
+ config: StorageConfig,
168
+ permission: PermissionHook | undefined,
169
+ ): (c: Context<PithyHonoEnv>) => Promise<HandlerDeps> {
140
170
  return async (c) => {
141
171
  const env = c.env as unknown as StorageEnv;
142
172
  const bucket = requireBinding<R2Bucket>(env, "STORAGE_BUCKET", "an R2 bucket");
@@ -147,16 +177,31 @@ function defaultResolveDeps(config: StorageConfig): (c: Context<PithyHonoEnv>) =
147
177
  // binding never touches the secrets store.
148
178
  store: objectStore({ bucket, env, secretName: STORAGE_R2_SECRET }),
149
179
  config,
150
- ownerId: c.var.auth?.userId ?? null,
180
+ caller: await accessCaller(c.var),
181
+ ...(permission ? { permission } : {}),
182
+ env: c.env,
151
183
  newId: () => crypto.randomUUID(),
152
184
  // 32 bytes of CSPRNG output, base64url. The token *is* the credential for a share link, so its
153
185
  // entropy is the only thing standing between a link and anyone guessing one.
154
186
  newToken: () => shareToken(),
155
187
  now: () => new Date(),
188
+ // The ceiling from the `storageBytes` meter where the entitlement provider enforces one — the
189
+ // caller's plan, or what was pinned for them — and the configured `bytesPerOwner` where it does not.
190
+ // Read once per request, and only by a write that needs it.
191
+ quotaLimit: memoized(() => storageCeiling(c, config)),
156
192
  };
157
193
  };
158
194
  }
159
195
 
196
+ /** One computation per request, however many writes ask for it. */
197
+ function memoized<T>(compute: () => Promise<T>): () => Promise<T> {
198
+ let pending: Promise<T> | undefined;
199
+ return () => {
200
+ pending ??= compute();
201
+ return pending;
202
+ };
203
+ }
204
+
160
205
  /** A 256-bit share token, base64url-encoded and unpadded so it is safe in a path segment. */
161
206
  function shareToken(): string {
162
207
  const bytes = crypto.getRandomValues(new Uint8Array(32));
@@ -164,11 +209,25 @@ function shareToken(): string {
164
209
  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
165
210
  }
166
211
 
212
+ /** `requireAuth()` lets either a bearer token or a session through. */
213
+ const AUTHENTICATED: readonly VerificationStrategy[] = ["bearer", "session"];
214
+
215
+ /** What a byte read can answer: the whole file, the range asked for, or nothing new since the caller's copy. */
216
+ const BYTE_RESPONSES: Readonly<Record<number, RouteResponse>> = {
217
+ 200: {
218
+ description:
219
+ "The whole file. Served as its stored type, or as `application/octet-stream` when none was stored or the stored one could run in a browser.",
220
+ contentType: "application/octet-stream",
221
+ },
222
+ 206: { description: "The byte range the `Range` header asked for.", contentType: "application/octet-stream" },
223
+ 304: { description: "The caller's copy matches `If-None-Match`. No body." },
224
+ };
225
+
167
226
  /** Register the storage sub-router. Returned as the capability's `routes` hook. */
168
227
  export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
169
228
  const base = options.basePath ?? "/storage";
170
229
  const share = options.sharePath ?? "/s";
171
- const resolve = options.resolveDeps ?? defaultResolveDeps(options.config);
230
+ const resolve = options.resolveDeps ?? defaultResolveDeps(options.config, options.permission);
172
231
 
173
232
  /** Stream one object, honoring `Range` and `If-None-Match`. Shared by the id route and the share route. */
174
233
  const stream = async (
@@ -200,19 +259,68 @@ export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono
200
259
  };
201
260
 
202
261
  return (app) => {
203
- app.post(base, requireAuth(), zValidator("json", CreateUploadInput, validationHook), async (c) => {
204
- return c.json(await initUpload(await resolve(c), c.req.valid("json")), 201);
205
- });
262
+ app.post(
263
+ base,
264
+ describeRoute({
265
+ summary: "Start an upload.",
266
+ description:
267
+ "Reserves the file and its quota, then answers with the presigned URL, or one URL per part, to PUT the bytes to. The bytes never pass through the Worker.",
268
+ verification: AUTHENTICATED,
269
+ responses: { 201: UploadInitResponse },
270
+ }),
271
+ requireAuth(),
272
+ validate("json", CreateUploadInput),
273
+ async (c) => {
274
+ return c.json(await initUpload(await resolve(c), c.req.valid("json")), 201);
275
+ },
276
+ );
206
277
 
207
- app.get(base, requireAuth(), zValidator("query", ListObjectsQuery, validationHook), async (c) => {
208
- return c.json(await listObjects(await resolve(c), c.req.valid("query")));
209
- });
278
+ app.get(
279
+ base,
280
+ describeRoute({
281
+ summary: "List the files the caller may see.",
282
+ description:
283
+ "The caller's own files and their organization's, by path. `includePublic=true` adds every public file.",
284
+ verification: AUTHENTICATED,
285
+ responses: { 200: ObjectListResponse },
286
+ }),
287
+ requireAuth(),
288
+ validate("query", ListObjectsQuery),
289
+ async (c) => {
290
+ return c.json(await listObjects(await resolve(c), c.req.valid("query")));
291
+ },
292
+ );
210
293
 
211
294
  // Static before `:id` — see the file doc comment.
295
+ app.get(
296
+ `${base}/admin/usage`,
297
+ describeRoute({
298
+ summary: "Count files held, per organization or per owner.",
299
+ description:
300
+ "Stored files and their bytes. A per-owner read names its organization, so no figure ever spans two.",
301
+ verification: "control-plane",
302
+ scopes: [STORAGE_USAGE_READ_SCOPE],
303
+ responses: { 200: UsageResponse },
304
+ }),
305
+ requireControlPlane(STORAGE_USAGE_READ_SCOPE),
306
+ validate("query", UsageQuery),
307
+ async (c) => {
308
+ const d1 = requireBinding<D1Database>(c.env, "DB", "a D1 database");
309
+ const db = storageDatabase(d1) as unknown as Kysely<unknown>;
310
+ return c.json((await usageRollup(db, STORAGE_OBJECTS_TABLE, c.req.valid("query"))) satisfies UsageResponse);
311
+ },
312
+ );
313
+
212
314
  app.delete(
213
315
  `${base}/shares/:token`,
316
+ describeRoute({
317
+ summary: "Revoke a share link.",
318
+ description: "Takes effect on the next fetch. Revoking twice is a no-op that keeps the first time.",
319
+ verification: AUTHENTICATED,
320
+ responses: { 200: ShareRevokedResponse },
321
+ }),
214
322
  requireAuth(),
215
- zValidator("param", ShareTokenParam, validationHook),
323
+ validate("param", ShareTokenParam),
216
324
  async (c) => {
217
325
  return c.json(await revokeShare(await resolve(c), c.req.valid("param").token));
218
326
  },
@@ -220,30 +328,64 @@ export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono
220
328
 
221
329
  app.post(
222
330
  `${base}/:id/complete`,
331
+ describeRoute({
332
+ summary: "Finish an upload.",
333
+ description:
334
+ "Assembles a multipart upload, then confirms the bytes against R2. Completing a stored file again answers with it unchanged.",
335
+ verification: AUTHENTICATED,
336
+ responses: { 200: StorageObjectResponse },
337
+ }),
223
338
  requireAuth(),
224
- zValidator("param", ObjectIdParam, validationHook),
225
- zValidator("json", CompleteUploadInput, validationHook),
339
+ validate("param", ObjectIdParam),
340
+ validate("json", CompleteUploadInput),
226
341
  async (c) => {
227
342
  return c.json(await completeUpload(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
228
343
  },
229
344
  );
230
345
 
231
346
  // No json validator: this route reads no body, and a client that sends none must keep working.
232
- app.post(`${base}/:id/abort`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
233
- return c.json(await abortUpload(await resolve(c), c.req.valid("param").id));
234
- });
347
+ app.post(
348
+ `${base}/:id/abort`,
349
+ describeRoute({
350
+ summary: "Abandon an upload.",
351
+ description: "Discards whatever R2 holds for the upload. The record stays, marked failed.",
352
+ verification: AUTHENTICATED,
353
+ responses: { 200: StorageObjectResponse },
354
+ }),
355
+ requireAuth(),
356
+ validate("param", ObjectIdParam),
357
+ async (c) => {
358
+ return c.json(await abortUpload(await resolve(c), c.req.valid("param").id));
359
+ },
360
+ );
235
361
 
236
362
  // The resume path: what R2 already holds, and a fresh URL for every part still missing. Minting
237
363
  // on demand is what keeps a part URL's TTL short without making a stalled upload unrecoverable.
238
- app.get(`${base}/:id/parts`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
239
- return c.json(await listUploadParts(await resolve(c), c.req.valid("param").id));
240
- });
364
+ app.get(
365
+ `${base}/:id/parts`,
366
+ describeRoute({
367
+ summary: "Resume a multipart upload.",
368
+ verification: AUTHENTICATED,
369
+ responses: { 200: UploadPartsResponse },
370
+ }),
371
+ requireAuth(),
372
+ validate("param", ObjectIdParam),
373
+ async (c) => {
374
+ return c.json(await listUploadParts(await resolve(c), c.req.valid("param").id));
375
+ },
376
+ );
241
377
 
242
378
  app.post(
243
379
  `${base}/:id/copy`,
380
+ describeRoute({
381
+ summary: "Copy a file.",
382
+ description: "R2 copies the bytes. The copy is a new private file with its own id.",
383
+ verification: AUTHENTICATED,
384
+ responses: { 201: StorageObjectResponse },
385
+ }),
244
386
  requireAuth(),
245
- zValidator("param", ObjectIdParam, validationHook),
246
- zValidator("json", CopyObjectInput, validationHook),
387
+ validate("param", ObjectIdParam),
388
+ validate("json", CopyObjectInput),
247
389
  async (c) => {
248
390
  return c.json(await copyObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
249
391
  },
@@ -251,23 +393,46 @@ export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono
251
393
 
252
394
  app.post(
253
395
  `${base}/:id/shares`,
396
+ describeRoute({
397
+ summary: "Mint a share link.",
398
+ verification: AUTHENTICATED,
399
+ responses: { 201: ShareResponse },
400
+ }),
254
401
  requireAuth(),
255
- zValidator("param", ObjectIdParam, validationHook),
256
- zValidator("json", CreateShareInput, validationHook),
402
+ validate("param", ObjectIdParam),
403
+ validate("json", CreateShareInput),
257
404
  async (c) => {
258
405
  return c.json(await createShare(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
259
406
  },
260
407
  );
261
408
 
262
- app.get(`${base}/:id/url`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
263
- return c.json(await presignObject(await resolve(c), c.req.valid("param").id));
264
- });
409
+ app.get(
410
+ `${base}/:id/url`,
411
+ describeRoute({
412
+ summary: "Mint a direct download URL.",
413
+ description: "For a file the caller may read. The URL cannot be revoked, so it lapses in five minutes.",
414
+ verification: AUTHENTICATED,
415
+ responses: { 200: PresignedUrlResponse },
416
+ }),
417
+ requireAuth(),
418
+ validate("param", ObjectIdParam),
419
+ async (c) => {
420
+ return c.json(await presignObject(await resolve(c), c.req.valid("param").id));
421
+ },
422
+ );
265
423
 
266
424
  // No `requireAuth`: a public object must be readable without a session. The handler authorizes.
267
425
  app.get(
268
426
  `${base}/:id`,
269
- zValidator("param", ObjectIdParam, validationHook),
270
- zValidator("query", ObjectReadQuery, validationHook),
427
+ describeRoute({
428
+ summary: "Read a file's bytes.",
429
+ description:
430
+ "Public files need no credential. Any other needs the bearer token or session of someone it is visible to, and reads as missing to anyone else. Honors `Range` and `If-None-Match`.",
431
+ verification: ["public", "bearer", "session"],
432
+ responses: BYTE_RESPONSES,
433
+ }),
434
+ validate("param", ObjectIdParam),
435
+ validate("query", ObjectReadQuery),
271
436
  async (c) => {
272
437
  const deps = await resolve(c);
273
438
  const object = await readableObject(deps, c.req.valid("param").id);
@@ -275,34 +440,68 @@ export function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono
275
440
  },
276
441
  );
277
442
 
278
- app.on("HEAD", `${base}/:id`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
279
- const deps = await resolve(c);
280
- const object = await readableObject(deps, c.req.valid("param").id);
281
- const metadata = await deps.store.head(object.key);
282
- if (!metadata) return c.notFound();
283
- return serveMetadata({ metadata, path: object.path, visibility: object.visibility });
284
- });
443
+ app.on(
444
+ "HEAD",
445
+ `${base}/:id`,
446
+ describeRoute({
447
+ summary: "Read a file's headers without its bytes.",
448
+ verification: AUTHENTICATED,
449
+ responses: { 200: { description: "The headers a GET would carry, with no body." } },
450
+ }),
451
+ requireAuth(),
452
+ validate("param", ObjectIdParam),
453
+ async (c) => {
454
+ const deps = await resolve(c);
455
+ const object = await readableObject(deps, c.req.valid("param").id);
456
+ const metadata = await deps.store.head(object.key);
457
+ if (!metadata) return c.notFound();
458
+ return serveMetadata({ metadata, path: object.path, visibility: object.visibility });
459
+ },
460
+ );
285
461
 
286
462
  app.patch(
287
463
  `${base}/:id`,
464
+ describeRoute({
465
+ summary: "Rename a file or change who may read it.",
466
+ verification: AUTHENTICATED,
467
+ responses: { 200: StorageObjectResponse },
468
+ }),
288
469
  requireAuth(),
289
- zValidator("param", ObjectIdParam, validationHook),
290
- zValidator("json", UpdateObjectInput, validationHook),
470
+ validate("param", ObjectIdParam),
471
+ validate("json", UpdateObjectInput),
291
472
  async (c) => {
292
473
  return c.json(await updateObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
293
474
  },
294
475
  );
295
476
 
296
- app.delete(`${base}/:id`, requireAuth(), zValidator("param", ObjectIdParam, validationHook), async (c) => {
297
- return c.json(await deleteObject(await resolve(c), c.req.valid("param").id));
298
- });
477
+ app.delete(
478
+ `${base}/:id`,
479
+ describeRoute({
480
+ summary: "Delete a file.",
481
+ description: "Its share links go with it.",
482
+ verification: AUTHENTICATED,
483
+ responses: { 200: ObjectDeletedResponse },
484
+ }),
485
+ requireAuth(),
486
+ validate("param", ObjectIdParam),
487
+ async (c) => {
488
+ return c.json(await deleteObject(await resolve(c), c.req.valid("param").id));
489
+ },
490
+ );
299
491
 
300
492
  // Public by design: the token is the credential, and it is checked on every fetch — which is what
301
493
  // makes revocation possible at all.
302
494
  app.get(
303
495
  `${share}/:token`,
304
- zValidator("param", ShareTokenParam, validationHook),
305
- zValidator("query", ObjectReadQuery, validationHook),
496
+ describeRoute({
497
+ summary: "Read a file through a share link.",
498
+ description:
499
+ "The token is the credential. A revoked or expired link answers 410. Honors `Range` and `If-None-Match`.",
500
+ verification: "public",
501
+ responses: BYTE_RESPONSES,
502
+ }),
503
+ validate("param", ShareTokenParam),
504
+ validate("query", ObjectReadQuery),
306
505
  async (c) => {
307
506
  const deps = await resolve(c);
308
507
  const object = await resolveShare(deps, c.req.valid("param").token);
@@ -9,7 +9,7 @@ import { ReportedPart } from "../object/multipart";
9
9
  /**
10
10
  * The request schemas for the storage routes. Every path parameter, query string and body is parsed
11
11
  * here before a handler sees it (CLAUDE.md §Zod: validate at every boundary), declared on the route
12
- * line with `zValidator(target, Schema, validationHook)` — so reading `routes.ts` tells you what a
12
+ * line with `validate(target, Schema)` — so reading `routes.ts` tells you what a
13
13
  * route accepts without opening a handler. A failure maps to `validation/invalid_input` through
14
14
  * `fromZodError`.
15
15
  *
@@ -120,7 +120,7 @@ export const CreateUploadInput = z
120
120
  "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.",
121
121
  ),
122
122
  visibility: StorageVisibility.optional().describe(
123
- "Who may read the file once stored. Omitted takes the configured default, which is private.",
123
+ "Who may read the file once stored. Omitted takes the configured `visibility.default`, which is private; a level outside `visibility.allowed` is refused, never coerced.",
124
124
  ),
125
125
  })
126
126
  .describe("A request to start an upload — what the file is called, what it is, and how big it is.");
@@ -149,7 +149,7 @@ export const UpdateObjectInput = z
149
149
  .object({
150
150
  path: logicalPath.optional(),
151
151
  visibility: StorageVisibility.optional().describe(
152
- "Change who may read the file. Takes effect on the next request.",
152
+ "Change who may read the file. Takes effect on the next request. A level outside `visibility.allowed` is refused.",
153
153
  ),
154
154
  })
155
155
  .describe("A rename, a visibility change, or both. At least one field must be present.")
@@ -196,7 +196,13 @@ export const ListObjectsQuery = z
196
196
  .string()
197
197
  .max(MAX_OBJECT_KEY_BYTES)
198
198
  .optional()
199
- .describe("Only files whose logical path starts with this. Omitted lists everything you own."),
199
+ .describe("Only files whose logical path starts with this. Omitted lists everything you may see."),
200
+ includePublic: z
201
+ .enum(["true", "false"])
202
+ .optional()
203
+ .describe(
204
+ "`true` adds every public file to your own and your organization's. Off by default, so nobody receives what they did not ask for.",
205
+ ),
200
206
  cursor: z
201
207
  .string()
202
208
  .min(1)
@@ -210,5 +216,5 @@ export const ListObjectsQuery = z
210
216
  .optional()
211
217
  .describe("Files per page. Defaults to 50, capped at 100 so one request cannot scan an entire owner's files."),
212
218
  })
213
- .describe("Query parameters for the owner's file listing.");
219
+ .describe("Query parameters for the file listing: your own files, your organization's, and public ones on request.");
214
220
  export type ListObjectsQuery = z.output<typeof ListObjectsQuery>;