@pithy-sh/storage 0.1.2 → 0.1.4

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 (86) hide show
  1. package/dist/capability.d.ts +45 -0
  2. package/dist/capability.d.ts.map +1 -0
  3. package/dist/capability.js +76 -0
  4. package/dist/config/config.d.ts +27 -0
  5. package/dist/config/config.d.ts.map +1 -0
  6. package/dist/config/config.js +49 -0
  7. package/dist/data/share.d.ts +27 -0
  8. package/dist/data/share.d.ts.map +1 -0
  9. package/dist/data/share.js +28 -0
  10. package/dist/data/storageObject.d.ts +55 -0
  11. package/dist/data/storageObject.d.ts.map +1 -0
  12. package/dist/data/storageObject.js +44 -0
  13. package/dist/data/tables.d.ts +23 -0
  14. package/dist/data/tables.d.ts.map +1 -0
  15. package/dist/data/tables.js +26 -0
  16. package/dist/error/errors.d.ts +60 -0
  17. package/dist/error/errors.d.ts.map +1 -0
  18. package/dist/error/errors.js +89 -0
  19. package/dist/http/guard.d.ts +20 -0
  20. package/dist/http/guard.d.ts.map +1 -0
  21. package/dist/http/guard.js +29 -0
  22. package/dist/http/handlers.d.ts +232 -0
  23. package/dist/http/handlers.d.ts.map +1 -0
  24. package/dist/http/handlers.js +507 -0
  25. package/dist/http/routes.d.ts +70 -0
  26. package/dist/http/routes.d.ts.map +1 -0
  27. package/dist/http/routes.js +135 -0
  28. package/dist/http/schemas.d.ts +74 -0
  29. package/dist/http/schemas.d.ts.map +1 -0
  30. package/dist/http/schemas.js +93 -0
  31. package/dist/http/serve.d.ts +121 -0
  32. package/dist/http/serve.d.ts.map +1 -0
  33. package/dist/http/serve.js +209 -0
  34. package/dist/index.d.ts +23 -0
  35. package/dist/index.d.ts.map +1 -0
  36. package/dist/index.js +14 -0
  37. package/dist/migrations/0001_objects.d.ts +24 -0
  38. package/dist/migrations/0001_objects.d.ts.map +1 -0
  39. package/dist/migrations/0001_objects.js +41 -0
  40. package/dist/object/cloudflare.d.ts +23 -0
  41. package/dist/object/cloudflare.d.ts.map +1 -0
  42. package/dist/object/cloudflare.js +48 -0
  43. package/dist/object/key.d.ts +29 -0
  44. package/dist/object/key.d.ts.map +1 -0
  45. package/dist/object/key.js +37 -0
  46. package/dist/object/multipart.d.ts +78 -0
  47. package/dist/object/multipart.d.ts.map +1 -0
  48. package/dist/object/multipart.js +131 -0
  49. package/dist/object/store.d.ts +203 -0
  50. package/dist/object/store.d.ts.map +1 -0
  51. package/dist/object/store.js +178 -0
  52. package/dist/provision/provisionStorage.d.ts +139 -0
  53. package/dist/provision/provisionStorage.d.ts.map +1 -0
  54. package/dist/provision/provisionStorage.js +112 -0
  55. package/dist/provision/resolveStorageConfig.d.ts +45 -0
  56. package/dist/provision/resolveStorageConfig.d.ts.map +1 -0
  57. package/dist/provision/resolveStorageConfig.js +33 -0
  58. package/dist/quota/quota.d.ts +127 -0
  59. package/dist/quota/quota.d.ts.map +1 -0
  60. package/dist/quota/quota.js +102 -0
  61. package/dist/secret/registry.d.ts +72 -0
  62. package/dist/secret/registry.d.ts.map +1 -0
  63. package/dist/secret/registry.js +84 -0
  64. package/dist/seeds/example.d.ts +5 -0
  65. package/dist/seeds/example.d.ts.map +1 -0
  66. package/dist/seeds/example.js +111 -0
  67. package/dist/test-utils/liveStorage.d.ts +52 -0
  68. package/dist/test-utils/liveStorage.d.ts.map +1 -0
  69. package/dist/test-utils/liveStorage.js +198 -0
  70. package/dist/version.generated.d.ts +7 -0
  71. package/dist/version.generated.d.ts.map +1 -0
  72. package/dist/version.generated.js +9 -0
  73. package/dist/workflows/retryPolicy.d.ts +39 -0
  74. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  75. package/dist/workflows/retryPolicy.js +43 -0
  76. package/dist/workflows/specs.d.ts +57 -0
  77. package/dist/workflows/specs.d.ts.map +1 -0
  78. package/dist/workflows/specs.js +60 -0
  79. package/dist/workflows/sweep.d.ts +84 -0
  80. package/dist/workflows/sweep.d.ts.map +1 -0
  81. package/dist/workflows/sweep.js +145 -0
  82. package/dist/workflows/worker.d.ts +51 -0
  83. package/dist/workflows/worker.d.ts.map +1 -0
  84. package/dist/workflows/worker.js +52 -0
  85. package/package.json +22 -11
  86. package/src/version.generated.ts +1 -1
@@ -0,0 +1,507 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { StorageObject } from "../data/storageObject.js";
4
+ import { StorageForbiddenError, StorageNotFoundError, StorageShareExpiredError, StorageShareRevokedError, StorageUploadIncompleteError } from "../error/errors.js";
5
+ import { collectParts, needsMultipart, planMultipart } from "../object/multipart.js";
6
+ import { StorageShare } from "../data/share.js";
7
+ import { STORAGE_OBJECTS_TABLE, STORAGE_SHARES_TABLE } from "../data/tables.js";
8
+ import { deriveObjectKey } from "../object/key.js";
9
+ import { assertWithinQuota, insertReservingQuota, updateSettlingQuota } from "../quota/quota.js";
10
+ //#region src/http/handlers.ts
11
+ /** Drop the server-only fields. The single place a row becomes something a client may see. */
12
+ function view(object) {
13
+ return {
14
+ id: object.id,
15
+ path: object.path,
16
+ ownerId: object.ownerId,
17
+ contentType: object.contentType,
18
+ size: object.size,
19
+ visibility: object.visibility,
20
+ checksum: object.checksum,
21
+ status: object.status,
22
+ createdAt: object.createdAt,
23
+ updatedAt: object.updatedAt
24
+ };
25
+ }
26
+ /** Load one row, decoded through the schema. Null when absent. */
27
+ async function findObject(deps, id) {
28
+ const row = await deps.db.selectFrom(STORAGE_OBJECTS_TABLE).selectAll().where("id", "=", id).executeTakeFirst();
29
+ return row ? StorageObject.parse(row) : null;
30
+ }
31
+ /** Load one row or throw `storage/not_found`. */
32
+ async function loadObject(deps, id) {
33
+ const object = await findObject(deps, id);
34
+ if (!object) throw new StorageNotFoundError({ detail: `no storage object ${id}` });
35
+ return object;
36
+ }
37
+ /**
38
+ * Require the caller to own the object. A private object they do not own is reported as **missing**,
39
+ * so the route cannot be used to test whether an id exists. A public object is reported as
40
+ * **forbidden**, because its existence is already public knowledge and "missing" would just be a lie.
41
+ */
42
+ function assertOwner(object, ownerId) {
43
+ if (ownerId !== null && object.ownerId === ownerId) return;
44
+ if (object.visibility === "public") throw new StorageForbiddenError({ detail: `object ${object.id} is owned by ${object.ownerId ?? "the system"}` });
45
+ throw new StorageNotFoundError({ detail: `object ${object.id} is not owned by ${ownerId ?? "an anonymous caller"}` });
46
+ }
47
+ /** Require the caller to be allowed to *read* the object: it is public, or it is theirs. */
48
+ function assertReadable(object, ownerId) {
49
+ if (object.visibility === "public") return;
50
+ if (ownerId !== null && object.ownerId === ownerId) return;
51
+ throw new StorageNotFoundError({ detail: `object ${object.id} is not readable by ${ownerId ?? "an anonymous caller"}` });
52
+ }
53
+ /** Require the object's bytes to actually be there. A `pending` row has a record but no content. */
54
+ function assertStored(object) {
55
+ if (object.status === "stored") return;
56
+ throw new StorageUploadIncompleteError({ detail: `object ${object.id} is ${object.status}, not stored` });
57
+ }
58
+ /** Write a whole row back through the codec — the round-trip rule, so no field bypasses its codec. */
59
+ async function saveObject(deps, object) {
60
+ const record = StorageObject.encode(object);
61
+ await deps.db.updateTable(STORAGE_OBJECTS_TABLE).set(record).where("id", "=", object.id).execute();
62
+ return object;
63
+ }
64
+ /**
65
+ * Start an upload: reserve the row and its quota, then mint the URL(s) the client PUTs to.
66
+ *
67
+ * **The reservation is the insert, and the insert is conditional.** A `pending` row holds its bytes
68
+ * against the owner's quota, so the row has to exist before an upload can proceed — but a check that
69
+ * ran separately from the write would let a burst of concurrent inits each read a used total none of
70
+ * them had yet contributed to. `insertReservingQuota` evaluates the sum inside the write instead, so
71
+ * the tenth concurrent init sees the other nine (`quota/quota.ts`).
72
+ *
73
+ * The pre-check above it is a courtesy: it refuses an obviously oversized upload before an R2
74
+ * multipart upload exists to clean up. When the conditional insert loses the race anyway, that
75
+ * multipart upload is aborted — a refused init leaves R2 holding nothing.
76
+ */
77
+ async function initUpload(deps, input) {
78
+ const now = deps.now();
79
+ await assertWithinQuota({
80
+ db: deps.db,
81
+ ownerId: deps.ownerId,
82
+ limitBytes: deps.config.quota.bytesPerOwner,
83
+ additionalBytes: input.size
84
+ });
85
+ const key = deriveObjectKey();
86
+ const multipart = needsMultipart(input.size, deps.config.multipartThresholdBytes);
87
+ let upload;
88
+ let uploadId = null;
89
+ if (multipart) {
90
+ const plan = planMultipart(input.size, deps.config.partSizeBytes);
91
+ uploadId = await deps.store.initMultipart(key, input.contentType);
92
+ const parts = [];
93
+ for (const part of plan.parts) parts.push({
94
+ partNumber: part.partNumber,
95
+ offset: part.offset,
96
+ length: part.length,
97
+ url: await deps.store.presignPart(key, uploadId, part.partNumber)
98
+ });
99
+ upload = {
100
+ kind: "multipart",
101
+ uploadId,
102
+ partSize: plan.partSize,
103
+ parts
104
+ };
105
+ } else upload = {
106
+ kind: "single",
107
+ url: await deps.store.presignPut(key, input.contentType, input.size)
108
+ };
109
+ const object = {
110
+ id: deps.newId(),
111
+ key,
112
+ path: input.path,
113
+ ownerId: deps.ownerId,
114
+ contentType: input.contentType,
115
+ size: input.size,
116
+ visibility: input.visibility ?? deps.config.defaultVisibility,
117
+ checksum: null,
118
+ status: "pending",
119
+ uploadId,
120
+ createdAt: now,
121
+ updatedAt: now
122
+ };
123
+ try {
124
+ await insertReservingQuota({
125
+ db: deps.db,
126
+ ownerId: deps.ownerId,
127
+ limitBytes: deps.config.quota.bytesPerOwner,
128
+ additionalBytes: input.size,
129
+ record: StorageObject.encode(object)
130
+ });
131
+ } catch (error) {
132
+ if (uploadId) await deps.store.abortMultipart(key, uploadId).catch(() => {});
133
+ throw error;
134
+ }
135
+ return {
136
+ object: view(object),
137
+ upload
138
+ };
139
+ }
140
+ /**
141
+ * Finalize an upload: assemble the parts (for a multipart), then confirm against R2 that the bytes
142
+ * are really there before the row is allowed to claim they are.
143
+ *
144
+ * The `head` is not a formality. Without it a client could complete an upload it never performed and
145
+ * leave a `stored` row pointing at nothing — a 404 from R2 at read time, long after the request that
146
+ * caused it. The size *and the content type* R2 reports win over the declared ones, so the row records
147
+ * what was stored rather than what was promised.
148
+ *
149
+ * **It is also where the quota is settled.** Part URLs carry no signed `Content-Length` — the final
150
+ * part's differs from every other, so pinning one at mint time would mean knowing the total up front
151
+ * and would still leave the last part unconstrained. The declared size therefore buys a *reservation*,
152
+ * not a limit, and an owner who declares 100 MiB can PUT far more across those URLs. Completion is the
153
+ * first and last point where the real byte count is known and the object can still be thrown away, so
154
+ * anything past the reservation is re-asserted against the quota here.
155
+ *
156
+ * **That re-assertion is the write, for the same reason the reservation was.** A check that ran ahead
157
+ * of the `UPDATE` would let two completions racing on one owner both read a total neither had yet
158
+ * contributed to, both pass, and both store — the init race, reproduced at the other end of the
159
+ * lifecycle. `updateSettlingQuota` evaluates the sum inside the update, so the second completion sees
160
+ * the first (`quota/quota.ts`).
161
+ */
162
+ async function completeUpload(deps, id, input) {
163
+ const object = await loadObject(deps, id);
164
+ assertOwner(object, deps.ownerId);
165
+ if (object.status === "stored") return view(object);
166
+ if (object.status !== "pending") throw new StorageUploadIncompleteError({ detail: `object ${id} is ${object.status} and cannot be completed` });
167
+ if (object.uploadId) {
168
+ const expected = planMultipart(object.size ?? 0, deps.config.partSizeBytes).partCount;
169
+ const parts = collectParts(input.parts, expected);
170
+ await deps.store.completeMultipart(object.key, object.uploadId, parts);
171
+ }
172
+ const metadata = await deps.store.head(object.key);
173
+ if (!metadata) throw new StorageUploadIncompleteError({
174
+ message: "No bytes were uploaded for that file.",
175
+ action: "Upload to the URL the init call returned, then complete again.",
176
+ detail: `R2 has no object at ${object.key}`
177
+ });
178
+ const settled = {
179
+ ...object,
180
+ status: "stored",
181
+ size: metadata.size,
182
+ contentType: metadata.contentType ?? object.contentType,
183
+ checksum: input.checksum ?? metadata.checksumSha256 ?? null,
184
+ uploadId: null,
185
+ updatedAt: deps.now()
186
+ };
187
+ const overshoot = metadata.size - (object.size ?? 0);
188
+ if (overshoot <= 0) return view(await saveObject(deps, settled));
189
+ try {
190
+ await updateSettlingQuota({
191
+ db: deps.db,
192
+ ownerId: object.ownerId,
193
+ limitBytes: deps.config.quota.bytesPerOwner,
194
+ additionalBytes: overshoot,
195
+ record: StorageObject.encode(settled)
196
+ });
197
+ } catch (error) {
198
+ await deps.store.delete(object.key).catch(() => {});
199
+ await saveObject(deps, {
200
+ ...object,
201
+ status: "failed",
202
+ uploadId: null,
203
+ updatedAt: deps.now()
204
+ });
205
+ throw error;
206
+ }
207
+ return view(settled);
208
+ }
209
+ /**
210
+ * Abandon an in-flight upload: tell R2 to discard the stored parts, then mark the row `failed`.
211
+ *
212
+ * The row survives rather than being deleted. `failed` rows are excluded from the quota sum, so they
213
+ * hold nothing, and keeping them means an owner can see that an upload was attempted and abandoned
214
+ * instead of the record silently evaporating.
215
+ *
216
+ * **The bytes are R2's problem after this, not the row's.** A single-PUT abort cannot revoke the
217
+ * presigned URL it handed out — nothing can, which is the whole cost of presigning — so a client may
218
+ * still PUT to it for the rest of that URL's hour, after the delete below has run. The row that
219
+ * survives therefore stops *claiming* its key the moment it goes `failed`: the orphan sweep matches
220
+ * only rows that bill for a key, so anything that lands afterwards is collected as an orphan rather
221
+ * than sheltered forever by a row that counts toward no quota (`workflows/sweep.ts`).
222
+ */
223
+ async function abortUpload(deps, id) {
224
+ const object = await loadObject(deps, id);
225
+ assertOwner(object, deps.ownerId);
226
+ if (object.status === "stored") throw new StorageUploadIncompleteError({
227
+ message: "That upload already finished.",
228
+ action: "Delete the file instead.",
229
+ detail: `object ${id} is stored`
230
+ });
231
+ if (object.uploadId) await deps.store.abortMultipart(object.key, object.uploadId);
232
+ await deps.store.delete(object.key);
233
+ return view(await saveObject(deps, {
234
+ ...object,
235
+ status: "failed",
236
+ uploadId: null,
237
+ updatedAt: deps.now()
238
+ }));
239
+ }
240
+ /**
241
+ * Resume a multipart upload: the parts R2 already holds, plus a **freshly presigned** URL for each
242
+ * one still missing.
243
+ *
244
+ * This is what makes multipart resumable at all. `initUpload` presigns every part once, and those
245
+ * URLs lapse an hour later — a 40 GiB upload is 640 of them, and a client that stalls or dies has no
246
+ * way back to the ones it never sent. Re-minting them here is the recovery path, and it is a route
247
+ * rather than a longer TTL because a presigned URL cannot be revoked: minting on demand keeps each
248
+ * one's life short and its issue authorized.
249
+ *
250
+ * Only while the row is `pending`. A `stored` row has no upload left to resume, and a `failed` one had
251
+ * its parts discarded — re-presigning against either would hand out URLs addressing nothing.
252
+ */
253
+ async function listUploadParts(deps, id) {
254
+ const object = await loadObject(deps, id);
255
+ assertOwner(object, deps.ownerId);
256
+ const uploadId = object.uploadId;
257
+ if (object.status !== "pending" || !uploadId) throw new StorageUploadIncompleteError({
258
+ message: "That upload has no parts to resume.",
259
+ action: "Only an in-flight multipart upload can be resumed. Start a new upload.",
260
+ detail: `object ${id} is ${object.status} with uploadId ${uploadId ?? "null"}`
261
+ });
262
+ const plan = planMultipart(object.size ?? 0, deps.config.partSizeBytes);
263
+ const uploaded = await deps.store.listParts(object.key, uploadId);
264
+ const stored = new Set(uploaded.map((part) => part.partNumber));
265
+ const missing = [];
266
+ for (const part of plan.parts) {
267
+ if (stored.has(part.partNumber)) continue;
268
+ missing.push({
269
+ partNumber: part.partNumber,
270
+ offset: part.offset,
271
+ length: part.length,
272
+ url: await deps.store.presignPart(object.key, uploadId, part.partNumber)
273
+ });
274
+ }
275
+ return {
276
+ uploadId,
277
+ partSize: plan.partSize,
278
+ partCount: plan.partCount,
279
+ uploaded,
280
+ missing
281
+ };
282
+ }
283
+ /**
284
+ * Encode a cursor. Keyset, not offset: an `OFFSET` page skips rows a concurrent upload shifted, so a
285
+ * client paging through their files while uploading would miss some. Base64url keeps it opaque, which
286
+ * is the point — the shape is ours to change.
287
+ */
288
+ function encodeCursor(cursor) {
289
+ const json = JSON.stringify(cursor);
290
+ const bytes = new TextEncoder().encode(json);
291
+ const binary = String.fromCharCode(...bytes);
292
+ return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
293
+ }
294
+ /** Decode a cursor, or `null` when it is not one we minted. A bad cursor starts from the beginning. */
295
+ function decodeCursor(value) {
296
+ if (!value) return null;
297
+ try {
298
+ const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
299
+ const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
300
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
301
+ if (typeof parsed !== "object" || parsed === null) return null;
302
+ const { path, id } = parsed;
303
+ return typeof path === "string" && typeof id === "string" ? {
304
+ path,
305
+ id
306
+ } : null;
307
+ } catch {
308
+ return null;
309
+ }
310
+ }
311
+ /** Default page size — generous enough for a file browser, small enough to stay one index read. */
312
+ const DEFAULT_LIST_LIMIT = 50;
313
+ /**
314
+ * One page of the caller's files, ordered by logical path. Scoped to the authenticated owner: there
315
+ * is no way to list another owner's files, and no parameter that could be made to.
316
+ */
317
+ async function listObjects(deps, query) {
318
+ const limit = query.limit ?? DEFAULT_LIST_LIMIT;
319
+ const after = decodeCursor(query.cursor);
320
+ let statement = deps.db.selectFrom(STORAGE_OBJECTS_TABLE).selectAll().where("ownerId", "=", deps.ownerId).orderBy("path", "asc").orderBy("id", "asc").limit(limit + 1);
321
+ if (query.prefix) {
322
+ const escaped = query.prefix.replace(/[\\%_]/g, (character) => `\\${character}`);
323
+ statement = statement.where("path", "like", `${escaped}%`);
324
+ }
325
+ if (after) statement = statement.where((eb) => eb.or([eb("path", ">", after.path), eb.and([eb("path", "=", after.path), eb("id", ">", after.id)])]));
326
+ const rows = await statement.execute();
327
+ const page = rows.slice(0, limit).map((row) => StorageObject.parse(row));
328
+ const objects = page.map(view);
329
+ if (rows.length <= limit) return { objects };
330
+ const last = page[page.length - 1];
331
+ return last ? {
332
+ objects,
333
+ cursor: encodeCursor({
334
+ path: last.path,
335
+ id: last.id
336
+ })
337
+ } : { objects };
338
+ }
339
+ /** Load an object for reading, enforcing public-or-owner and that its bytes exist. */
340
+ async function readableObject(deps, id) {
341
+ const object = await loadObject(deps, id);
342
+ assertReadable(object, deps.ownerId);
343
+ assertStored(object);
344
+ return object;
345
+ }
346
+ /** How long a direct-download URL stays valid. Short: it is bearer-equivalent and cannot be revoked. */
347
+ const PRESIGNED_URL_TTL_SECONDS = 300;
348
+ /**
349
+ * Mint a presigned GET — the no-Worker-in-the-byte-path escape hatch.
350
+ *
351
+ * Authorization happens **here**, once, and then the URL is on its own: it cannot be revoked, and
352
+ * anyone holding it can read the bytes until it lapses. Five minutes is short enough that a URL
353
+ * pasted into a chat is dead before it is read, and long enough to start a large download.
354
+ */
355
+ async function presignObject(deps, id) {
356
+ const object = await readableObject(deps, id);
357
+ return {
358
+ url: await deps.store.presignGet(object.key, { expiresIn: 300 }),
359
+ expiresInSeconds: 300
360
+ };
361
+ }
362
+ /** Rename a file, change who may read it, or both. The key never moves — only the row changes. */
363
+ async function updateObject(deps, id, input) {
364
+ const object = await loadObject(deps, id);
365
+ assertOwner(object, deps.ownerId);
366
+ return view(await saveObject(deps, {
367
+ ...object,
368
+ path: input.path ?? object.path,
369
+ visibility: input.visibility ?? object.visibility,
370
+ updatedAt: deps.now()
371
+ }));
372
+ }
373
+ /**
374
+ * Copy a file server-side. The bytes are copied by R2 and never enter the Worker; the copy is a new
375
+ * object with its own id, its own key, and its own share links — it is not an alias.
376
+ *
377
+ * Owner-scoped, like every other mutating route: you may copy your own files. Copying a *public* file
378
+ * you do not own is a plausible feature and deliberately not this one — it would let any reader
379
+ * duplicate bytes into their own quota on the owner's storage bill, which is a decision an adopter
380
+ * should make explicitly rather than inherit.
381
+ */
382
+ async function copyObject(deps, id, input) {
383
+ const source = await loadObject(deps, id);
384
+ assertOwner(source, deps.ownerId);
385
+ assertStored(source);
386
+ await assertWithinQuota({
387
+ db: deps.db,
388
+ ownerId: deps.ownerId,
389
+ limitBytes: deps.config.quota.bytesPerOwner,
390
+ additionalBytes: source.size ?? 0
391
+ });
392
+ const key = deriveObjectKey();
393
+ await deps.store.copy(source.key, key);
394
+ const now = deps.now();
395
+ const copy = {
396
+ ...source,
397
+ id: deps.newId(),
398
+ key,
399
+ path: input.path,
400
+ ownerId: deps.ownerId,
401
+ visibility: "private",
402
+ status: "stored",
403
+ uploadId: null,
404
+ createdAt: now,
405
+ updatedAt: now
406
+ };
407
+ try {
408
+ await insertReservingQuota({
409
+ db: deps.db,
410
+ ownerId: deps.ownerId,
411
+ limitBytes: deps.config.quota.bytesPerOwner,
412
+ additionalBytes: source.size ?? 0,
413
+ record: StorageObject.encode(copy)
414
+ });
415
+ } catch (error) {
416
+ await deps.store.delete(key).catch(() => {});
417
+ throw error;
418
+ }
419
+ return view(copy);
420
+ }
421
+ /**
422
+ * Delete a file: the object first, then the row. Every share link pointing at it goes with the row,
423
+ * through the foreign key's `ON DELETE CASCADE` — a share that outlived its object would be a live
424
+ * token for bytes that no longer exist.
425
+ *
426
+ * The object delete is best-effort. An R2 hiccup must not leave a row nobody can remove; the orphan
427
+ * sweep collects an object whose row went first.
428
+ */
429
+ async function deleteObject(deps, id) {
430
+ const object = await loadObject(deps, id);
431
+ assertOwner(object, deps.ownerId);
432
+ if (object.uploadId) await deps.store.abortMultipart(object.key, object.uploadId).catch(() => {});
433
+ await deps.store.delete(object.key).catch(() => {});
434
+ await deps.db.deleteFrom(STORAGE_OBJECTS_TABLE).where("id", "=", id).execute();
435
+ return {
436
+ id,
437
+ deleted: true
438
+ };
439
+ }
440
+ /** Mint a revocable share link for one file. */
441
+ async function createShare(deps, id, input) {
442
+ const object = await loadObject(deps, id);
443
+ assertOwner(object, deps.ownerId);
444
+ assertStored(object);
445
+ const now = deps.now();
446
+ const share = {
447
+ token: deps.newToken(),
448
+ objectId: object.id,
449
+ expiresAt: input.expiresInSeconds ? new Date(now.getTime() + input.expiresInSeconds * 1e3) : null,
450
+ revokedAt: null,
451
+ createdAt: now
452
+ };
453
+ await deps.db.insertInto(STORAGE_SHARES_TABLE).values(StorageShare.encode(share)).execute();
454
+ return {
455
+ token: share.token,
456
+ objectId: share.objectId,
457
+ expiresAt: share.expiresAt,
458
+ createdAt: share.createdAt
459
+ };
460
+ }
461
+ /**
462
+ * Withdraw a share link. A write, effective on the very next request — which is the whole reason a
463
+ * share is a row and not a presigned URL.
464
+ *
465
+ * Revoking twice is a no-op. The first revocation time is kept, because when a link stopped working
466
+ * is the fact anyone actually needs.
467
+ */
468
+ async function revokeShare(deps, token) {
469
+ const row = await deps.db.selectFrom(STORAGE_SHARES_TABLE).selectAll().where("token", "=", token).executeTakeFirst();
470
+ if (!row) throw new StorageNotFoundError({ detail: `no share token ${token}` });
471
+ const share = StorageShare.parse(row);
472
+ assertOwner(await loadObject(deps, share.objectId), deps.ownerId);
473
+ if (share.revokedAt) return {
474
+ token,
475
+ revokedAt: share.revokedAt
476
+ };
477
+ const revokedAt = deps.now();
478
+ await deps.db.updateTable(STORAGE_SHARES_TABLE).set(StorageShare.encode({
479
+ ...share,
480
+ revokedAt
481
+ })).where("token", "=", token).execute();
482
+ return {
483
+ token,
484
+ revokedAt
485
+ };
486
+ }
487
+ /**
488
+ * Resolve a share token to the object it grants read access to.
489
+ *
490
+ * Revoked and expired are **separate answers**, deliberately. Both are 410, but `storage/share_revoked`
491
+ * says the owner took the link back and `storage/share_expired` says it simply aged out — one is worth
492
+ * asking about, the other is worth re-requesting. Collapsing them into "gone" throws away the only
493
+ * information the holder can act on. Revocation is checked first: an explicit withdrawal is the more
494
+ * specific fact about a link that is both.
495
+ */
496
+ async function resolveShare(deps, token) {
497
+ const row = await deps.db.selectFrom(STORAGE_SHARES_TABLE).selectAll().where("token", "=", token).executeTakeFirst();
498
+ if (!row) throw new StorageNotFoundError({ detail: `no share token ${token}` });
499
+ const share = StorageShare.parse(row);
500
+ if (share.revokedAt) throw new StorageShareRevokedError({ detail: `share ${token} revoked at ${share.revokedAt.toISOString()}` });
501
+ if (share.expiresAt && share.expiresAt.getTime() <= deps.now().getTime()) throw new StorageShareExpiredError({ detail: `share ${token} expired at ${share.expiresAt.toISOString()}` });
502
+ const object = await loadObject(deps, share.objectId);
503
+ assertStored(object);
504
+ return object;
505
+ }
506
+ //#endregion
507
+ export { PRESIGNED_URL_TTL_SECONDS, abortUpload, completeUpload, copyObject, createShare, deleteObject, initUpload, listObjects, listUploadParts, presignObject, readableObject, resolveShare, revokeShare, updateObject };
@@ -0,0 +1,70 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
4
+ import type { Context, Hono } from "hono";
5
+ import type { StorageConfig } from "../config/config";
6
+ import { type HandlerDeps } from "./handlers";
7
+ /**
8
+ * The storage routes, their declared verification strategies, and what each accepts:
9
+ *
10
+ * POST /storage → start an upload (bearer | session)
11
+ * json: CreateUploadInput
12
+ * GET /storage → list your files (bearer | session, owner-scoped)
13
+ * query: ListObjectsQuery
14
+ * DELETE /storage/shares/:token → revoke a share (bearer | session, owner-scoped)
15
+ * param: ShareTokenParam
16
+ * POST /storage/:id/complete → finalize a multipart (bearer | session, owner-scoped)
17
+ * param: ObjectIdParam, json: CompleteUploadInput
18
+ * POST /storage/:id/abort → abandon an upload (bearer | session, owner-scoped)
19
+ * param: ObjectIdParam — no body
20
+ * GET /storage/:id/parts → resume a multipart (bearer | session, owner-scoped)
21
+ * param: ObjectIdParam
22
+ * POST /storage/:id/copy → server-side copy (bearer | session, owner-scoped)
23
+ * param: ObjectIdParam, json: CopyObjectInput
24
+ * POST /storage/:id/shares → mint a revocable share (bearer | session, owner-scoped)
25
+ * param: ObjectIdParam, json: CreateShareInput
26
+ * GET /storage/:id/url → presigned direct URL (bearer | session, owner-or-public)
27
+ * param: ObjectIdParam
28
+ * GET /storage/:id → stream the bytes (public when `visibility: 'public'`,
29
+ * otherwise bearer | session + owner)
30
+ * param: ObjectIdParam, query: ObjectReadQuery
31
+ * HEAD /storage/:id → metadata only (bearer | session, owner-scoped)
32
+ * param: ObjectIdParam
33
+ * PATCH /storage/:id → rename or change access (bearer | session, owner-scoped)
34
+ * param: ObjectIdParam, json: UpdateObjectInput
35
+ * DELETE /storage/:id → delete file and row (bearer | session, owner-scoped)
36
+ * param: ObjectIdParam
37
+ * GET /s/:token → fetch via a share link (public — the token is the credential)
38
+ * param: ShareTokenParam, query: ObjectReadQuery
39
+ *
40
+ * **Every validator sits after the guard.** An unauthenticated request with a malformed body is a
41
+ * 401, never a 400 — shape is not something a caller learns before being verified. `POST
42
+ * /storage/:id/abort` carries no json validator because it reads no body: adding one would 400 the
43
+ * bodyless POST every client sends today.
44
+ *
45
+ * `GET /storage/:id` is the one route with two strategies, because a public file must be readable by
46
+ * someone with no session at all. It is therefore **not** wrapped in {@link requireAuth}: the guard
47
+ * would deny before the handler could see that the object is public. Authorization happens inside the
48
+ * handler instead, against `c.var.auth` — which is `null` with no auth capability composed, so a
49
+ * private object is denied by default and only an explicitly public one is served.
50
+ *
51
+ * **Static segments are registered before `:param` ones.** Hono matches in registration order, so
52
+ * `/storage/shares/:token` has to come before `/storage/:id` or a DELETE to `/storage/shares/abc`
53
+ * would be read as deleting the object whose id is `shares`.
54
+ *
55
+ * **Uploads never proxy bytes through the Worker; downloads do.** That asymmetry is the design, not
56
+ * an inconsistency — `serve.ts` carries the reasoning.
57
+ */
58
+ export interface StorageRoutesOptions {
59
+ /** The resolved storage config. */
60
+ config: StorageConfig;
61
+ /** Where the object routes mount. Defaults to `/storage`. */
62
+ basePath?: string;
63
+ /** Where share fetches mount. Defaults to `/s` — short, because the whole URL gets pasted around. */
64
+ sharePath?: string;
65
+ /** Test seam: resolve handler deps from the request. Defaults to the env-based resolver. */
66
+ resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
67
+ }
68
+ /** Register the storage sub-router. Returned as the capability's `routes` hook. */
69
+ export declare function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
70
+ //# sourceMappingURL=routes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAI7E,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKtD,OAAO,EAML,KAAK,WAAW,EASjB,MAAM,YAAY,CAAC;AAqBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAClE;AAuDD,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAiJtG"}