@pithy-sh/storage 0.3.0 → 0.5.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 (84) 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.d.ts +4 -3
  12. package/dist/error/errors.d.ts.map +1 -1
  13. package/dist/error/errors.js +2 -2
  14. package/dist/http/handlers.d.ts +45 -14
  15. package/dist/http/handlers.d.ts.map +1 -1
  16. package/dist/http/handlers.js +169 -66
  17. package/dist/http/responses.d.ts +6 -0
  18. package/dist/http/responses.d.ts.map +1 -1
  19. package/dist/http/responses.js +2 -1
  20. package/dist/http/routes.d.ts +13 -2
  21. package/dist/http/routes.d.ts.map +1 -1
  22. package/dist/http/routes.js +37 -9
  23. package/dist/http/schemas.d.ts +6 -0
  24. package/dist/http/schemas.d.ts.map +1 -1
  25. package/dist/http/schemas.js +6 -5
  26. package/dist/http/scopes.d.ts +25 -0
  27. package/dist/http/scopes.d.ts.map +1 -0
  28. package/dist/http/scopes.js +32 -0
  29. package/dist/http/serve.d.ts +5 -2
  30. package/dist/http/serve.d.ts.map +1 -1
  31. package/dist/index.d.ts +2 -0
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +5 -3
  34. package/dist/migrations/0002_ownership.d.ts +5 -0
  35. package/dist/migrations/0002_ownership.d.ts.map +1 -0
  36. package/dist/migrations/0002_ownership.js +114 -0
  37. package/dist/object/cloudflare.d.ts +2 -1
  38. package/dist/object/cloudflare.d.ts.map +1 -1
  39. package/dist/object/cloudflare.js +2 -2
  40. package/dist/provision/provisionStorage.d.ts +14 -2
  41. package/dist/provision/provisionStorage.d.ts.map +1 -1
  42. package/dist/provision/provisionStorage.js +19 -4
  43. package/dist/provision/resolveStorageConfig.js +1 -1
  44. package/dist/quota/ceiling.d.ts +36 -0
  45. package/dist/quota/ceiling.d.ts.map +1 -0
  46. package/dist/quota/ceiling.js +31 -0
  47. package/dist/quota/quota.d.ts +24 -7
  48. package/dist/quota/quota.d.ts.map +1 -1
  49. package/dist/quota/quota.js +40 -12
  50. package/dist/secret/bundleToken.d.ts +24 -0
  51. package/dist/secret/bundleToken.d.ts.map +1 -0
  52. package/dist/secret/bundleToken.js +74 -0
  53. package/dist/secret/registry.d.ts +5 -1
  54. package/dist/secret/registry.d.ts.map +1 -1
  55. package/dist/secret/registry.js +7 -3
  56. package/dist/seeds/example.d.ts.map +1 -1
  57. package/dist/seeds/example.js +3 -0
  58. package/dist/test-utils/liveStorage.d.ts.map +1 -1
  59. package/dist/test-utils/liveStorage.js +5 -2
  60. package/dist/version.generated.d.ts +1 -1
  61. package/dist/version.generated.js +1 -1
  62. package/package.json +5 -5
  63. package/pithy.manifest.json +20 -10
  64. package/src/capability.ts +52 -8
  65. package/src/config/config.ts +24 -6
  66. package/src/data/storageObject.ts +22 -6
  67. package/src/error/errors.ts +6 -5
  68. package/src/http/handlers.ts +212 -79
  69. package/src/http/responses.ts +13 -1
  70. package/src/http/routes.ts +64 -10
  71. package/src/http/schemas.ts +10 -4
  72. package/src/http/scopes.ts +39 -0
  73. package/src/http/serve.ts +5 -2
  74. package/src/index.ts +2 -0
  75. package/src/migrations/0002_ownership.ts +176 -0
  76. package/src/object/cloudflare.ts +2 -2
  77. package/src/provision/provisionStorage.ts +22 -3
  78. package/src/quota/ceiling.ts +44 -0
  79. package/src/quota/quota.ts +63 -20
  80. package/src/secret/bundleToken.ts +81 -0
  81. package/src/secret/registry.ts +6 -8
  82. package/src/seeds/example.ts +3 -0
  83. package/src/test-utils/liveStorage.ts +3 -6
  84. package/src/version.generated.ts +1 -1
@@ -1,6 +1,17 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import {
5
+ type AccessCaller,
6
+ type AccessLevel,
7
+ accessLevel,
8
+ disclosedTenancy,
9
+ keepReadable,
10
+ type PermissionHook,
11
+ readablePredicate,
12
+ } from "@pithy-sh/core/src/access/access";
13
+ import { resolveVisibility } from "@pithy-sh/core/src/access/visibility";
14
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
4
15
  import type { StorageConfig } from "../config/config";
5
16
  import { StorageShare } from "../data/share";
6
17
  import { StorageObject } from "../data/storageObject";
@@ -16,7 +27,8 @@ import { deriveObjectKey } from "../object/key";
16
27
  import { collectParts, needsMultipart, planMultipart } from "../object/multipart";
17
28
  import type { ObjectStore } from "../object/store";
18
29
  import type { UploadedPart } from "../object/uploadedPart";
19
- import { assertWithinQuota, insertReservingQuota, updateSettlingQuota } from "../quota/quota";
30
+ import type { StorageCeiling } from "../quota/ceiling";
31
+ import { assertWithinQuota, insertReservingQuota, type QuotaCheck, updateSettlingQuota } from "../quota/quota";
20
32
  import type {
21
33
  CompleteUploadInput,
22
34
  CopyObjectInput,
@@ -42,28 +54,87 @@ import type {
42
54
  * addresses, so a key in a response body is a capability leak waiting for the first adopter who logs
43
55
  * their API responses.
44
56
  *
45
- * **A file you cannot see reads as missing.** `assertOwner` answers `storage/not_found` for a private
46
- * object owned by someone else and `storage/forbidden` only when the object is already public —
47
- * because a 403 on a private object confirms it exists, which is exactly the oracle an enumeration
48
- * attack wants. Public objects have nothing left to hide, so there the honest answer is the useful one.
57
+ * **Whose a file is, and who may reach it.** Every file is written with its owner, the organization in
58
+ * force, and a visibility — `private`, `organization` or `public` — from the project's policy. Every route
59
+ * asks core's access rules, and the adopter's permission hook if they supplied one, before it acts:
60
+ * reading is the visibility's, and changing a file — completing, aborting, copying, renaming,
61
+ * re-scoping, sharing, deleting — is its owner's, acting for its organization, or a role holding
62
+ * `storage:manage` there.
63
+ *
64
+ * **A file you cannot see reads as missing.** A caller who may not read a file gets `storage/not_found`,
65
+ * and `storage/forbidden` only when they may read it but not change it — because a 403 on a file they
66
+ * cannot see confirms it exists, which is exactly the oracle an enumeration attack wants. A file they
67
+ * can already read has nothing left to hide, so there the honest answer is the useful one.
49
68
  */
50
69
 
70
+ /** The power a role holds to edit, delete and re-scope any file in its own organization. */
71
+ export const STORAGE_MANAGE_POWER = "storage:manage";
72
+
73
+ /** The capability's name, as the permission hook sees it. */
74
+ const CAPABILITY = "storage";
75
+
51
76
  /** Everything a handler needs, all injectable. */
52
77
  export interface HandlerDeps {
53
78
  /** The storage database. */
54
79
  db: StorageDatabase;
55
80
  /** The object plane — presigning, the multipart lifecycle, and binding-backed reads. */
56
81
  store: ObjectStore;
57
- /** The resolved storage config: quota, multipart sizing, default visibility. */
82
+ /** The resolved storage config: quota, multipart sizing, the visibility policy. */
58
83
  config: StorageConfig;
59
- /** The authenticated caller from the core `AuthContext` seam, or null for an unauthenticated read. */
60
- ownerId: string | null;
84
+ /** Who is asking: the signed-in user from `AuthContext`, if any, and the organization they act for. */
85
+ caller: AccessCaller;
86
+ /** The adopter's permission hook, if they supplied one. */
87
+ permission?: PermissionHook;
88
+ /** The Worker env, handed to the permission hook. */
89
+ env: Record<string, unknown>;
61
90
  /** Mints an object id. */
62
91
  newId: () => string;
63
92
  /** Mints a share token. */
64
93
  newToken: () => string;
65
94
  /** The current time. */
66
95
  now: () => Date;
96
+ /**
97
+ * The byte ceiling for this request's writes, and whose bytes it covers.
98
+ *
99
+ * Absent means the configured `quota.bytesPerOwner`, per owner, which is what a project composing no
100
+ * entitlement provider has always had. The default resolver fills it from the `storageBytes` meter when the
101
+ * provider enforces one, so a plan's quota — or a subject's pinned one, or `unrestricted` — becomes the
102
+ * ceiling, summed across the organization when the plan is an organization's, and an advisory meter leaves
103
+ * the configured number in force.
104
+ */
105
+ quotaLimit?: () => Promise<StorageCeiling>;
106
+ }
107
+
108
+ /**
109
+ * The quota a write of a row held for `ownerId` in `organizationId` is checked against: the ceiling, and
110
+ * whose bytes it sums. The resolved ceiling where the request has one, the configured one otherwise.
111
+ *
112
+ * **A ceiling that covers an organization covers only that organization's rows**, so a row about to be held
113
+ * for a different one — or for none — would sit outside the very sum it is checked against, and never count.
114
+ * That is refused rather than written: it means the billing subject and the organization in force disagree,
115
+ * which is wiring for the adopter to fix, and under-counting has no recovery.
116
+ */
117
+ async function quotaFor(
118
+ deps: HandlerDeps,
119
+ ownerId: string | null,
120
+ organizationId: string | null,
121
+ ): Promise<Pick<QuotaCheck, "ownerId" | "organizationId" | "limitBytes" | "metered">> {
122
+ const ceiling = deps.quotaLimit
123
+ ? await deps.quotaLimit()
124
+ : { limitBytes: deps.config.quota.bytesPerOwner, tenant: null, metered: false };
125
+ const { metered } = ceiling;
126
+ if (ceiling.tenant === null || ceiling.limitBytes === null || ownerId === null) {
127
+ return { ownerId, limitBytes: ceiling.limitBytes, metered };
128
+ }
129
+ if (organizationId !== ceiling.tenant) {
130
+ throw new InternalError({
131
+ message: "This file cannot be counted against the plan it is billed to, so nothing was written.",
132
+ action:
133
+ "Make the payments subject resolver and the organization in force agree — both should answer the organization the caller acts for.",
134
+ detail: `The storageBytes ceiling covers organization ${ceiling.tenant}; the file would be held for ${organizationId ?? "no organization"}.`,
135
+ });
136
+ }
137
+ return { ownerId, organizationId: ceiling.tenant, limitBytes: ceiling.limitBytes, metered };
67
138
  }
68
139
 
69
140
  /** The client-facing shape of a stored file. Deliberately without `key` and `uploadId`. */
@@ -71,9 +142,10 @@ export interface StorageObjectView {
71
142
  id: string;
72
143
  path: string;
73
144
  ownerId: string | null;
145
+ organizationId: string | null;
74
146
  contentType: string;
75
147
  size: number | null;
76
- visibility: "private" | "public";
148
+ visibility: StorageObject["visibility"];
77
149
  checksum: string | null;
78
150
  status: "pending" | "stored" | "failed";
79
151
  createdAt: Date;
@@ -107,12 +179,20 @@ export interface ShareView {
107
179
  createdAt: Date;
108
180
  }
109
181
 
110
- /** Drop the server-only fields. The single place a row becomes something a client may see. */
111
- function view(object: StorageObject): StorageObjectView {
182
+ /**
183
+ * Drop the server-only fields. The single place a row becomes something a client may see.
184
+ *
185
+ * The owner and organization are the caller's to see only when they act for the file's organization
186
+ * ({@link disclosedTenancy}). A public file reached from anywhere else names neither: reading a file is not
187
+ * learning which organization its owner belongs to.
188
+ */
189
+ function view(object: StorageObject, caller: AccessCaller): StorageObjectView {
190
+ const tenancy = disclosedTenancy(object, caller);
112
191
  return {
113
192
  id: object.id,
114
193
  path: object.path,
115
- ownerId: object.ownerId,
194
+ ownerId: tenancy.ownerId,
195
+ organizationId: tenancy.organizationId,
116
196
  contentType: object.contentType,
117
197
  size: object.size,
118
198
  visibility: object.visibility,
@@ -129,33 +209,56 @@ async function findObject(deps: HandlerDeps, id: string): Promise<StorageObject
129
209
  return row ? StorageObject.parse(row) : null;
130
210
  }
131
211
 
132
- /** Load one row or throw `storage/not_found`. */
212
+ /**
213
+ * Load one row or throw `storage/not_found`, asking nobody whether the caller may see it — for a share
214
+ * link, where the token is the credential and the rules have already been spent by whoever minted it.
215
+ */
133
216
  async function loadObject(deps: HandlerDeps, id: string): Promise<StorageObject> {
134
217
  const object = await findObject(deps, id);
135
218
  if (!object) throw new StorageNotFoundError({ detail: `no storage object ${id}` });
136
219
  return object;
137
220
  }
138
221
 
139
- /**
140
- * Require the caller to own the object. A private object they do not own is reported as **missing**,
141
- * so the route cannot be used to test whether an id exists. A public object is reported as
142
- * **forbidden**, because its existence is already public knowledge and "missing" would just be a lie.
143
- */
144
- function assertOwner(object: StorageObject, ownerId: string | null): void {
145
- if (ownerId !== null && object.ownerId === ownerId) return;
146
- if (object.visibility === "public") {
147
- throw new StorageForbiddenError({ detail: `object ${object.id} is owned by ${object.ownerId ?? "the system"}` });
222
+ /** What the caller may do with one file, asking the rules and the hook. */
223
+ function levelOf(deps: HandlerDeps, object: StorageObject): Promise<AccessLevel> {
224
+ return accessLevel({
225
+ record: object,
226
+ caller: deps.caller,
227
+ capability: CAPABILITY,
228
+ managePower: STORAGE_MANAGE_POWER,
229
+ hook: deps.permission,
230
+ env: deps.env,
231
+ });
232
+ }
233
+
234
+ /** Who is asking, for a log line. */
235
+ function callerName(deps: HandlerDeps): string {
236
+ return deps.caller.userId ?? "an anonymous caller";
237
+ }
238
+
239
+ /** Load a file the caller may read, or answer not found — for a file that is absent and one they cannot see alike. */
240
+ async function loadReadable(deps: HandlerDeps, id: string): Promise<StorageObject> {
241
+ const object = await findObject(deps, id);
242
+ if (!object || (await levelOf(deps, object)) === "none") {
243
+ throw new StorageNotFoundError({ detail: `no storage object ${id} readable by ${callerName(deps)}` });
148
244
  }
149
- throw new StorageNotFoundError({ detail: `object ${object.id} is not owned by ${ownerId ?? "an anonymous caller"}` });
245
+ return object;
150
246
  }
151
247
 
152
- /** Require the caller to be allowed to *read* the object: it is public, or it is theirs. */
153
- function assertReadable(object: StorageObject, ownerId: string | null): void {
154
- if (object.visibility === "public") return;
155
- if (ownerId !== null && object.ownerId === ownerId) return;
156
- throw new StorageNotFoundError({
157
- detail: `object ${object.id} is not readable by ${ownerId ?? "an anonymous caller"}`,
158
- });
248
+ /**
249
+ * Load a file the caller may change. Not found when they cannot read it; forbidden only when they can,
250
+ * because by then they already know it exists.
251
+ */
252
+ async function loadWritable(deps: HandlerDeps, id: string): Promise<StorageObject> {
253
+ const object = await findObject(deps, id);
254
+ const level = object ? await levelOf(deps, object) : "none";
255
+ if (!object || level === "none") {
256
+ throw new StorageNotFoundError({ detail: `no storage object ${id} readable by ${callerName(deps)}` });
257
+ }
258
+ if (level !== "write") {
259
+ throw new StorageForbiddenError({ detail: `${callerName(deps)} may read object ${id} but not change it` });
260
+ }
261
+ return object;
159
262
  }
160
263
 
161
264
  /** Require the object's bytes to actually be there. A `pending` row has a record but no content. */
@@ -186,11 +289,14 @@ async function saveObject(deps: HandlerDeps, object: StorageObject): Promise<Sto
186
289
  */
187
290
  export async function initUpload(deps: HandlerDeps, input: CreateUploadInput): Promise<UploadInitResult> {
188
291
  const now = deps.now();
292
+ // Whose it is comes from the request, never the body, and a level the policy does not allow is
293
+ // refused before a byte of R2 is reserved.
294
+ const organizationId = deps.caller.acting?.organizationId ?? null;
295
+ const visibility = resolveVisibility(deps.config.visibility, input.visibility, organizationId);
189
296
 
190
297
  await assertWithinQuota({
191
298
  db: deps.db,
192
- ownerId: deps.ownerId,
193
- limitBytes: deps.config.quota.bytesPerOwner,
299
+ ...(await quotaFor(deps, deps.caller.userId, organizationId)),
194
300
  additionalBytes: input.size,
195
301
  });
196
302
 
@@ -220,10 +326,11 @@ export async function initUpload(deps: HandlerDeps, input: CreateUploadInput): P
220
326
  id: deps.newId(),
221
327
  key,
222
328
  path: input.path,
223
- ownerId: deps.ownerId,
329
+ ownerId: deps.caller.userId,
330
+ organizationId,
224
331
  contentType: input.contentType,
225
332
  size: input.size,
226
- visibility: input.visibility ?? deps.config.defaultVisibility,
333
+ visibility,
227
334
  checksum: null,
228
335
  status: "pending",
229
336
  uploadId,
@@ -233,8 +340,7 @@ export async function initUpload(deps: HandlerDeps, input: CreateUploadInput): P
233
340
  try {
234
341
  await insertReservingQuota({
235
342
  db: deps.db,
236
- ownerId: deps.ownerId,
237
- limitBytes: deps.config.quota.bytesPerOwner,
343
+ ...(await quotaFor(deps, deps.caller.userId, organizationId)),
238
344
  additionalBytes: input.size,
239
345
  record: StorageObject.encode(object),
240
346
  });
@@ -245,7 +351,7 @@ export async function initUpload(deps: HandlerDeps, input: CreateUploadInput): P
245
351
  throw error;
246
352
  }
247
353
 
248
- return { object: view(object), upload };
354
+ return { object: view(object, deps.caller), upload };
249
355
  }
250
356
 
251
357
  /**
@@ -275,11 +381,10 @@ export async function completeUpload(
275
381
  id: string,
276
382
  input: CompleteUploadInput,
277
383
  ): Promise<StorageObjectView> {
278
- const object = await loadObject(deps, id);
279
- assertOwner(object, deps.ownerId);
384
+ const object = await loadWritable(deps, id);
280
385
  // Completing twice is a no-op rather than an error: a client that retried a dropped response gets
281
386
  // the same answer, which is what makes the route safe to retry at all.
282
- if (object.status === "stored") return view(object);
387
+ if (object.status === "stored") return view(object, deps.caller);
283
388
  if (object.status !== "pending") {
284
389
  throw new StorageUploadIncompleteError({ detail: `object ${id} is ${object.status} and cannot be completed` });
285
390
  }
@@ -319,13 +424,15 @@ export async function completeUpload(
319
424
  // An upload smaller than it declared claims nothing further, so it is written unconditionally. A
320
425
  // quota an adopter lowered under an in-flight upload must not turn a shrinking completion into a
321
426
  // deletion of bytes the owner was, at reservation time, granted.
322
- if (overshoot <= 0) return view(await saveObject(deps, settled));
427
+ if (overshoot <= 0) return view(await saveObject(deps, settled), deps.caller);
323
428
 
429
+ // Resolved before the settlement's `try`: a ceiling that cannot be read, or that covers another
430
+ // organization, refuses this request — it is not a verdict on the bytes, so it must not discard them.
431
+ const quota = await quotaFor(deps, object.ownerId, object.organizationId);
324
432
  try {
325
433
  await updateSettlingQuota({
326
434
  db: deps.db,
327
- ownerId: object.ownerId,
328
- limitBytes: deps.config.quota.bytesPerOwner,
435
+ ...quota,
329
436
  additionalBytes: overshoot,
330
437
  record: StorageObject.encode(settled),
331
438
  });
@@ -338,7 +445,7 @@ export async function completeUpload(
338
445
  await saveObject(deps, { ...object, status: "failed", uploadId: null, updatedAt: deps.now() });
339
446
  throw error;
340
447
  }
341
- return view(settled);
448
+ return view(settled, deps.caller);
342
449
  }
343
450
 
344
451
  /**
@@ -356,8 +463,7 @@ export async function completeUpload(
356
463
  * than sheltered forever by a row that counts toward no quota (`workflows/sweep.ts`).
357
464
  */
358
465
  export async function abortUpload(deps: HandlerDeps, id: string): Promise<StorageObjectView> {
359
- const object = await loadObject(deps, id);
360
- assertOwner(object, deps.ownerId);
466
+ const object = await loadWritable(deps, id);
361
467
  if (object.status === "stored") {
362
468
  throw new StorageUploadIncompleteError({
363
469
  message: "That upload already finished.",
@@ -370,7 +476,10 @@ export async function abortUpload(deps: HandlerDeps, id: string): Promise<Storag
370
476
  // too, so aborting never leaves an object the sweep has to find later.
371
477
  await deps.store.delete(object.key);
372
478
 
373
- return view(await saveObject(deps, { ...object, status: "failed", uploadId: null, updatedAt: deps.now() }));
479
+ return view(
480
+ await saveObject(deps, { ...object, status: "failed", uploadId: null, updatedAt: deps.now() }),
481
+ deps.caller,
482
+ );
374
483
  }
375
484
 
376
485
  /** Where a resuming client stands: what R2 already holds, and a live URL for everything it does not. */
@@ -396,8 +505,7 @@ export interface UploadPartsResult {
396
505
  * its parts discarded — re-presigning against either would hand out URLs addressing nothing.
397
506
  */
398
507
  export async function listUploadParts(deps: HandlerDeps, id: string): Promise<UploadPartsResult> {
399
- const object = await loadObject(deps, id);
400
- assertOwner(object, deps.ownerId);
508
+ const object = await loadWritable(deps, id);
401
509
  const uploadId = object.uploadId;
402
510
  if (object.status !== "pending" || !uploadId) {
403
511
  throw new StorageUploadIncompleteError({
@@ -461,8 +569,10 @@ function decodeCursor(value: string | undefined): ListCursor | null {
461
569
  const DEFAULT_LIST_LIMIT = 50;
462
570
 
463
571
  /**
464
- * One page of the caller's files, ordered by logical path. Scoped to the authenticated owner: there
465
- * is no way to list another owner's files, and no parameter that could be made to.
572
+ * One page of the files the caller may see, ordered by logical path: their own, their organization's,
573
+ * and — only when `includePublic=true` — every public file. The rules run in SQL, so there is no
574
+ * parameter that lists anyone else's private files; the hook is asked about each row on the page and may
575
+ * remove one, so a page can come back short while its cursor still says there is more.
466
576
  */
467
577
  export async function listObjects(
468
578
  deps: HandlerDeps,
@@ -474,7 +584,12 @@ export async function listObjects(
474
584
  let statement = deps.db
475
585
  .selectFrom(STORAGE_OBJECTS_TABLE)
476
586
  .selectAll()
477
- .where("ownerId", "=", deps.ownerId)
587
+ .where(
588
+ readablePredicate(deps.caller, {
589
+ managePower: STORAGE_MANAGE_POWER,
590
+ includePublic: query.includePublic === "true",
591
+ }),
592
+ )
478
593
  .orderBy("path", "asc")
479
594
  .orderBy("id", "asc")
480
595
  // One extra row is what distinguishes "this page is full" from "there is another page", without
@@ -495,16 +610,23 @@ export async function listObjects(
495
610
 
496
611
  const rows = await statement.execute();
497
612
  const page = rows.slice(0, limit).map((row) => StorageObject.parse(row));
498
- const objects = page.map(view);
613
+ // The cursor is the page's, computed before the hook runs: a row the hook removes is still a row the
614
+ // next page must start after.
615
+ const kept = await keepReadable(page, {
616
+ capability: CAPABILITY,
617
+ caller: deps.caller,
618
+ hook: deps.permission,
619
+ env: deps.env,
620
+ });
621
+ const objects = kept.map((object) => view(object, deps.caller));
499
622
  if (rows.length <= limit) return { objects };
500
623
  const last = page[page.length - 1];
501
624
  return last ? { objects, cursor: encodeCursor({ path: last.path, id: last.id }) } : { objects };
502
625
  }
503
626
 
504
- /** Load an object for reading, enforcing public-or-owner and that its bytes exist. */
627
+ /** Load an object for reading, enforcing who may read it and that its bytes exist. */
505
628
  export async function readableObject(deps: HandlerDeps, id: string): Promise<StorageObject> {
506
- const object = await loadObject(deps, id);
507
- assertReadable(object, deps.ownerId);
629
+ const object = await loadReadable(deps, id);
508
630
  assertStored(object);
509
631
  return object;
510
632
  }
@@ -525,21 +647,28 @@ export async function presignObject(deps: HandlerDeps, id: string): Promise<{ ur
525
647
  return { url, expiresInSeconds: PRESIGNED_URL_TTL_SECONDS };
526
648
  }
527
649
 
528
- /** Rename a file, change who may read it, or both. The key never moves — only the row changes. */
650
+ /**
651
+ * Rename a file, change who may read it, or both. The key never moves — only the row changes. A level the
652
+ * policy does not allow is refused, and `organization` on a file written with no organization is too.
653
+ */
529
654
  export async function updateObject(
530
655
  deps: HandlerDeps,
531
656
  id: string,
532
657
  input: UpdateObjectInput,
533
658
  ): Promise<StorageObjectView> {
534
- const object = await loadObject(deps, id);
535
- assertOwner(object, deps.ownerId);
659
+ const object = await loadWritable(deps, id);
660
+ const visibility =
661
+ input.visibility === undefined
662
+ ? object.visibility
663
+ : resolveVisibility(deps.config.visibility, input.visibility, object.organizationId);
536
664
  return view(
537
665
  await saveObject(deps, {
538
666
  ...object,
539
667
  path: input.path ?? object.path,
540
- visibility: input.visibility ?? object.visibility,
668
+ visibility,
541
669
  updatedAt: deps.now(),
542
670
  }),
671
+ deps.caller,
543
672
  );
544
673
  }
545
674
 
@@ -547,23 +676,32 @@ export async function updateObject(
547
676
  * Copy a file server-side. The bytes are copied by R2 and never enter the Worker; the copy is a new
548
677
  * object with its own id, its own key, and its own share links — it is not an alias.
549
678
  *
550
- * Owner-scoped, like every other mutating route: you may copy your own files. Copying a *public* file
679
+ * A change, like every other mutating route: you may copy a file you may change. Copying a *public* file
551
680
  * you do not own is a plausible feature and deliberately not this one — it would let any reader
552
681
  * duplicate bytes into their own quota on the owner's storage bill, which is a decision an adopter
553
- * should make explicitly rather than inherit.
682
+ * should make explicitly rather than inherit. The copy is the caller's, in the organization they act for.
554
683
  */
555
684
  export async function copyObject(deps: HandlerDeps, id: string, input: CopyObjectInput): Promise<StorageObjectView> {
556
- const source = await loadObject(deps, id);
557
- assertOwner(source, deps.ownerId);
685
+ const source = await loadWritable(deps, id);
558
686
  assertStored(source);
559
687
 
688
+ const organizationId = deps.caller.acting?.organizationId ?? null;
560
689
  await assertWithinQuota({
561
690
  db: deps.db,
562
- ownerId: deps.ownerId,
563
- limitBytes: deps.config.quota.bytesPerOwner,
691
+ ...(await quotaFor(deps, deps.caller.userId, organizationId)),
564
692
  additionalBytes: source.size ?? 0,
565
693
  });
566
694
 
695
+ // A copy starts private even when the source was public. Republishing is a decision, and a copy made to
696
+ // take a private working copy of your own public file should not re-publish it by default. Where the policy
697
+ // allows no private file, it starts at the policy's default instead. Either way the level goes through the
698
+ // one check every write does, so the kit never writes a file outside its own policy.
699
+ const visibility = resolveVisibility(
700
+ deps.config.visibility,
701
+ deps.config.visibility.allowed.includes("private") ? "private" : undefined,
702
+ organizationId,
703
+ );
704
+
567
705
  const key = deriveObjectKey();
568
706
  await deps.store.copy(source.key, key);
569
707
  const now = deps.now();
@@ -572,10 +710,9 @@ export async function copyObject(deps: HandlerDeps, id: string, input: CopyObjec
572
710
  id: deps.newId(),
573
711
  key,
574
712
  path: input.path,
575
- ownerId: deps.ownerId,
576
- // A copy starts private even when the source was public. Republishing is a decision, and a copy
577
- // made to take a private working copy of your own public file should not re-publish it by default.
578
- visibility: "private",
713
+ ownerId: deps.caller.userId,
714
+ organizationId,
715
+ visibility,
579
716
  status: "stored",
580
717
  uploadId: null,
581
718
  createdAt: now,
@@ -586,8 +723,7 @@ export async function copyObject(deps: HandlerDeps, id: string, input: CopyObjec
586
723
  // owner, and concurrent copies of one 1 GiB file against a 1 GiB quota must not all pass.
587
724
  await insertReservingQuota({
588
725
  db: deps.db,
589
- ownerId: deps.ownerId,
590
- limitBytes: deps.config.quota.bytesPerOwner,
726
+ ...(await quotaFor(deps, deps.caller.userId, organizationId)),
591
727
  additionalBytes: source.size ?? 0,
592
728
  record: StorageObject.encode(copy),
593
729
  });
@@ -597,7 +733,7 @@ export async function copyObject(deps: HandlerDeps, id: string, input: CopyObjec
597
733
  await deps.store.delete(key).catch(() => {});
598
734
  throw error;
599
735
  }
600
- return view(copy);
736
+ return view(copy, deps.caller);
601
737
  }
602
738
 
603
739
  /**
@@ -609,8 +745,7 @@ export async function copyObject(deps: HandlerDeps, id: string, input: CopyObjec
609
745
  * sweep collects an object whose row went first.
610
746
  */
611
747
  export async function deleteObject(deps: HandlerDeps, id: string): Promise<{ id: string; deleted: true }> {
612
- const object = await loadObject(deps, id);
613
- assertOwner(object, deps.ownerId);
748
+ const object = await loadWritable(deps, id);
614
749
  if (object.uploadId) await deps.store.abortMultipart(object.key, object.uploadId).catch(() => {});
615
750
  await deps.store.delete(object.key).catch(() => {});
616
751
  await deps.db.deleteFrom(STORAGE_OBJECTS_TABLE).where("id", "=", id).execute();
@@ -619,8 +754,7 @@ export async function deleteObject(deps: HandlerDeps, id: string): Promise<{ id:
619
754
 
620
755
  /** Mint a revocable share link for one file. */
621
756
  export async function createShare(deps: HandlerDeps, id: string, input: CreateShareInput): Promise<ShareView> {
622
- const object = await loadObject(deps, id);
623
- assertOwner(object, deps.ownerId);
757
+ const object = await loadWritable(deps, id);
624
758
  assertStored(object);
625
759
 
626
760
  const now = deps.now();
@@ -646,8 +780,7 @@ export async function revokeShare(deps: HandlerDeps, token: string): Promise<{ t
646
780
  const row = await deps.db.selectFrom(STORAGE_SHARES_TABLE).selectAll().where("token", "=", token).executeTakeFirst();
647
781
  if (!row) throw new StorageNotFoundError({ detail: `no share token ${token}` });
648
782
  const share = StorageShare.parse(row);
649
- const object = await loadObject(deps, share.objectId);
650
- assertOwner(object, deps.ownerId);
783
+ await loadWritable(deps, share.objectId);
651
784
  if (share.revokedAt) return { token, revokedAt: share.revokedAt };
652
785
 
653
786
  const revokedAt = deps.now();
@@ -24,7 +24,19 @@ export const StorageObjectResponse = z
24
24
  .object({
25
25
  id: z.string().describe("The file's id. What every other route takes as `:id`."),
26
26
  path: z.string().describe("The file's logical path, as the owner named it. Never an R2 key."),
27
- ownerId: z.string().nullable().describe("The id of the user who owns the file, or null for a system-owned file."),
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
+ ),
28
40
  contentType: z
29
41
  .string()
30
42
  .describe("The file's MIME type: as declared at upload, replaced at completion by the type R2 stored."),