@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,45 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
4
+ import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
5
+ import type { StorageConfig } from "../config/config";
6
+ import type { StorageResources } from "./provisionStorage";
7
+ /**
8
+ * Resolve the sweep worker's committed `wrangler.jsonc` template into one environment's standalone
9
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
10
+ * bindings' names — stays as the template committed it.
11
+ *
12
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics (clone, fill by binding name,
13
+ * stamp `ENVIRONMENT`). What this file adds is one thing the generic resolver deliberately does not
14
+ * do: it **rewrites `workflows` and `triggers.crons` from the capability's specs** rather than from
15
+ * the template's own block. The template carries both so it reads as a complete, deployable config,
16
+ * but `workflows/specs.ts` is the single source of the binding name, the class name, and the
17
+ * schedule — so changing the sweep's cron is a one-line spec edit, not a spec edit plus a JSONC edit
18
+ * that nothing checks agree.
19
+ *
20
+ * Pure: the caller parses the template and writes the result.
21
+ */
22
+ /** The resolved ids and per-env values for one environment's sweep-worker deploy. */
23
+ export interface StorageConfigParams {
24
+ /**
25
+ * The project name — the `<project>` segment the deployed worker and Workflow names lead with. The
26
+ * root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed: a Worker script
27
+ * name is account-scoped, so a wrong value here overwrites another project's running host.
28
+ */
29
+ project: string;
30
+ /** The target environment. */
31
+ env: ManagedEnvironment;
32
+ /** The app database id for this environment — where the `pithy_storage_*` tables live. */
33
+ appDatabaseId: string;
34
+ /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the R2 credentials. */
35
+ secretsDatabaseId: string;
36
+ /** The CF Secrets Store id holding the per-env master key. */
37
+ storeId: string;
38
+ /** The provisioned bucket the worker binds. */
39
+ resources: StorageResources;
40
+ /** The app's resolved storage config — serialized into the worker's `STORAGE_CONFIG` var. */
41
+ storageConfig: StorageConfig;
42
+ }
43
+ /** Fill the template for one environment. */
44
+ export declare function resolveStorageConfig(template: WorkflowHostTemplate, params: StorageConfigParams): WorkflowHostTemplate;
45
+ //# sourceMappingURL=resolveStorageConfig.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveStorageConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveStorageConfig.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyC,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAEpH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AAEH,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,GAAG,EAAE,kBAAkB,CAAC;IACxB,0FAA0F;IAC1F,aAAa,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,EAAE,gBAAgB,CAAC;IAC5B,6FAA6F;IAC7F,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,oBAAoB,CA2BtB"}
@@ -0,0 +1,33 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { STORAGE_CAPABILITY, storageWorkflowRegistry } from "../workflows/specs.js";
4
+ import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
5
+ import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
6
+ //#region src/provision/resolveStorageConfig.ts
7
+ /** Fill the template for one environment. */
8
+ function resolveStorageConfig(template, params) {
9
+ const { project, env, appDatabaseId, secretsDatabaseId, storeId, resources, storageConfig } = params;
10
+ const derived = hostWorkflowsFor(storageWorkflowRegistry, {
11
+ project,
12
+ capability: STORAGE_CAPABILITY,
13
+ env
14
+ });
15
+ const resolved = resolveWorkflowHost(template, {
16
+ project,
17
+ capability: STORAGE_CAPABILITY,
18
+ env,
19
+ databaseIds: {
20
+ DB: appDatabaseId,
21
+ SECRETS: secretsDatabaseId
22
+ },
23
+ r2BucketNames: { STORAGE_BUCKET: resources.bucketName },
24
+ secretsStoreId: storeId,
25
+ masterKeySecretName: masterKeySecretName(project, env),
26
+ vars: { STORAGE_CONFIG: JSON.stringify(storageConfig) },
27
+ workflows: derived.workflows
28
+ });
29
+ resolved.triggers = derived.crons.length > 0 ? { crons: derived.crons } : void 0;
30
+ return resolved;
31
+ }
32
+ //#endregion
33
+ export { resolveStorageConfig };
@@ -0,0 +1,127 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { StorageObjectRow, StorageObjectStatus } from "../data/storageObject";
4
+ import { type StorageDatabase } from "../data/tables";
5
+ /**
6
+ * Per-owner byte quotas.
7
+ *
8
+ * **Quota is checked when an upload *starts*, and the sum counts `pending` rows alongside `stored`
9
+ * ones.** That is the whole design, and it is not an optimization.
10
+ *
11
+ * Counting only completed uploads would make the check meaningless under concurrency: ten clients
12
+ * that each declare 1 GiB against a 1 GiB quota all read a used total of zero, all pass, and all
13
+ * upload. Nothing in that sequence is a bug in any single request — the check is simply measuring the
14
+ * wrong thing. Making the client declare its size up front, and having the `pending` row *reserve*
15
+ * those bytes the moment it is written, turns the quota into something a concurrent burst cannot
16
+ * walk past: the second init reads the first's reservation.
17
+ *
18
+ * **The reservation only holds if the sum and the insert are one statement.** A `SELECT sum(size)`
19
+ * followed by a separate `INSERT` reproduces the very race it was meant to close, one round trip
20
+ * later: ten concurrent inits all read a used total that none of them has yet contributed to, all
21
+ * pass, and all insert. D1 has no interactive transactions, so a `BEGIN`/`COMMIT` wrapper is not
22
+ * available — {@link insertReservingQuota} is the mechanism instead. It writes the pending row with a
23
+ * conditional `INSERT … SELECT … WHERE`, so the sum is evaluated *inside* the write, and a row that
24
+ * would breach the limit simply does not appear.
25
+ *
26
+ * {@link assertWithinQuota} survives as the cheap pre-check a handler runs before it creates anything
27
+ * that would need cleaning up. It is a courtesy, not the enforcement.
28
+ *
29
+ * **Completion settles the same way it reserved.** A part URL carries no signed `Content-Length`, so
30
+ * an owner may PUT more than they declared, and the overshoot has to be re-asserted when the row turns
31
+ * `stored`. That re-assertion is {@link updateSettlingQuota} — a conditional `UPDATE`, the same shape
32
+ * as the conditional `INSERT` — because two completions racing on a plain check both read a total
33
+ * neither has yet contributed and both pass. The rule is one rule: every write that changes what an
34
+ * owner holds evaluates the sum inside itself.
35
+ *
36
+ * The reservation is not free — an abandoned upload holds bytes it never stored. That is what
37
+ * `pendingTtlSeconds` and the orphan sweep are for: a `pending` row past its TTL is aborted and
38
+ * dropped, returning its reservation. Over-counting briefly and reclaiming is the right way round;
39
+ * under-counting has no recovery.
40
+ *
41
+ * A `null` limit is unlimited and skips the query entirely. A `null` owner (a system object) has no
42
+ * quota — there is no principal to bill it to.
43
+ */
44
+ /** What a quota check needs. */
45
+ export interface QuotaCheck {
46
+ /** The storage database. */
47
+ db: StorageDatabase;
48
+ /** The owner the bytes are billed to. Null is a system object, which no quota applies to. */
49
+ ownerId: string | null;
50
+ /** The configured per-owner ceiling in bytes. Null is unlimited. */
51
+ limitBytes: number | null;
52
+ /** The bytes this upload declares — what the pending row is about to reserve. */
53
+ additionalBytes: number;
54
+ }
55
+ /** A quota check plus the row whose insertion *is* the reservation. */
56
+ export interface QuotaReservation extends QuotaCheck {
57
+ /** The row to write, already through `StorageObject.encode` — the SQLite shape, never the app one. */
58
+ record: StorageObjectRow;
59
+ }
60
+ /** A quota check plus the row whose update *is* the settlement. */
61
+ export interface QuotaSettlement extends QuotaCheck {
62
+ /**
63
+ * The whole row to write, already through `StorageObject.encode`. Its `id` is what the update
64
+ * targets — the settlement rewrites one known row rather than a set.
65
+ */
66
+ record: StorageObjectRow;
67
+ }
68
+ /**
69
+ * The statuses that bill an owner: a `pending` row reserves its declared bytes and a `stored` one
70
+ * holds real ones. `failed` bills nothing.
71
+ *
72
+ * Exported because the orphan sweep asks the same question of the same rows — a key is *claimed* if
73
+ * and only if a row bills for it — and the two predicates drifting apart is what let a `failed` row
74
+ * shield its R2 object from collection while counting toward nobody's quota
75
+ * (`workflows/sweep.ts`).
76
+ */
77
+ export declare const QUOTA_COUNTED_STATUSES: readonly StorageObjectStatus[];
78
+ /**
79
+ * Bytes an owner currently holds: every `pending` reservation plus every `stored` object. `failed`
80
+ * rows are excluded — they hold no bytes and reserve nothing.
81
+ */
82
+ export declare function usedBytes(db: StorageDatabase, ownerId: string): Promise<number>;
83
+ /**
84
+ * Throw `storage/quota_exceeded` when this upload would put the owner over their limit. The
85
+ * comparison is `used + additional > limit`, so an upload landing exactly on the limit is allowed —
86
+ * a quota is a ceiling you may reach, not one you must stay under.
87
+ *
88
+ * **This is a pre-check, not the reservation.** It reads a total nothing holds still, so between it
89
+ * and any later write a concurrent init can have taken the room. Use it to refuse an obviously
90
+ * oversized upload *before* opening an R2 multipart upload there would then be nothing to clean up
91
+ * for, and let {@link insertReservingQuota} be the boundary that actually decides.
92
+ */
93
+ export declare function assertWithinQuota(check: QuotaCheck): Promise<void>;
94
+ /**
95
+ * Insert a storage row **only if** it fits inside the owner's quota, and throw
96
+ * `storage/quota_exceeded` when it does not.
97
+ *
98
+ * The sum and the write are one statement — `INSERT … SELECT <values> WHERE (SELECT sum(size) …) <=
99
+ * limit - additional` — because two statements cannot be made to hold a reservation without a
100
+ * transaction, and D1 has none to offer. SQLite evaluates the sub-select while it holds the write
101
+ * lock, so a burst of concurrent inits is serialized by the database itself: each one sees every
102
+ * reservation that landed before it, and the first that would breach the limit inserts nothing.
103
+ *
104
+ * `RETURNING id` is how "inserted nothing" is read back. Zero rows is not an error to SQLite — the
105
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
106
+ */
107
+ export declare function insertReservingQuota(reservation: QuotaReservation): Promise<void>;
108
+ /**
109
+ * Rewrite one row **only if** the bytes it newly claims still fit inside the owner's quota, and throw
110
+ * `storage/quota_exceeded` when they do not.
111
+ *
112
+ * This is {@link insertReservingQuota}'s other half, and it exists for the identical reason. A
113
+ * completion measures what R2 actually holds against what the pending row reserved, and the difference
114
+ * is bytes the owner has not been granted yet. Settling that difference with a separate
115
+ * {@link assertWithinQuota} would put the enforcement back where it never worked: two completions
116
+ * racing both read a total neither has yet contributed to, both pass, and the owner ends over the
117
+ * limit — the same defect the conditional insert was written to close, one lifecycle stage later.
118
+ *
119
+ * `additionalBytes` is the **overshoot**, not the object's size. The row being updated is still
120
+ * `pending`, so the sub-select in the `WHERE` already counts its reservation: SQLite evaluates the
121
+ * condition against the pre-update table. Passing the full size would bill the reservation twice.
122
+ *
123
+ * `RETURNING id` reads back whether the row moved. Zero rows updated is not an error to SQLite — the
124
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
125
+ */
126
+ export declare function updateSettlingQuota(settlement: QuotaSettlement): Promise<void>;
127
+ //# sourceMappingURL=quota.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/quota/quota.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,EAAE,EAAE,eAAe,CAAC;IACpB,6FAA6F;IAC7F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,sGAAsG;IACtG,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD;;;OAGG;IACH,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAA0B,CAAC;AAE5F;;;GAGG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUrF;AAYD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpF"}
@@ -0,0 +1,102 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { StorageQuotaExceededError } from "../error/errors.js";
4
+ import { STORAGE_OBJECTS_TABLE } from "../data/tables.js";
5
+ import { sql } from "kysely";
6
+ //#region src/quota/quota.ts
7
+ /**
8
+ * The statuses that bill an owner: a `pending` row reserves its declared bytes and a `stored` one
9
+ * holds real ones. `failed` bills nothing.
10
+ *
11
+ * Exported because the orphan sweep asks the same question of the same rows — a key is *claimed* if
12
+ * and only if a row bills for it — and the two predicates drifting apart is what let a `failed` row
13
+ * shield its R2 object from collection while counting toward nobody's quota
14
+ * (`workflows/sweep.ts`).
15
+ */
16
+ const QUOTA_COUNTED_STATUSES = ["pending", "stored"];
17
+ /**
18
+ * Bytes an owner currently holds: every `pending` reservation plus every `stored` object. `failed`
19
+ * rows are excluded — they hold no bytes and reserve nothing.
20
+ */
21
+ async function usedBytes(db, ownerId) {
22
+ const row = await db.selectFrom(STORAGE_OBJECTS_TABLE).select(sql`coalesce(sum(size), 0)`.as("used")).where("ownerId", "=", ownerId).where("status", "in", [...QUOTA_COUNTED_STATUSES]).executeTakeFirst();
23
+ return Number(row?.used ?? 0);
24
+ }
25
+ /** A size a caller declared has to be a real byte count. Zero is fine; negative is a client bug. */
26
+ function assertDeclaredSize(additionalBytes) {
27
+ if (additionalBytes >= 0) return;
28
+ throw new StorageQuotaExceededError({
29
+ message: "An upload needs a size.",
30
+ action: "Declare the file's byte count when you start the upload.",
31
+ detail: `negative declared size ${additionalBytes}`
32
+ });
33
+ }
34
+ /**
35
+ * Throw `storage/quota_exceeded` when this upload would put the owner over their limit. The
36
+ * comparison is `used + additional > limit`, so an upload landing exactly on the limit is allowed —
37
+ * a quota is a ceiling you may reach, not one you must stay under.
38
+ *
39
+ * **This is a pre-check, not the reservation.** It reads a total nothing holds still, so between it
40
+ * and any later write a concurrent init can have taken the room. Use it to refuse an obviously
41
+ * oversized upload *before* opening an R2 multipart upload there would then be nothing to clean up
42
+ * for, and let {@link insertReservingQuota} be the boundary that actually decides.
43
+ */
44
+ async function assertWithinQuota(check) {
45
+ if (check.limitBytes === null || check.ownerId === null) return;
46
+ assertDeclaredSize(check.additionalBytes);
47
+ const used = await usedBytes(check.db, check.ownerId);
48
+ if (used + check.additionalBytes > check.limitBytes) throw new StorageQuotaExceededError({ detail: `owner would hold ${used + check.additionalBytes} bytes against a limit of ${check.limitBytes}` });
49
+ }
50
+ /**
51
+ * Insert a storage row **only if** it fits inside the owner's quota, and throw
52
+ * `storage/quota_exceeded` when it does not.
53
+ *
54
+ * The sum and the write are one statement — `INSERT … SELECT <values> WHERE (SELECT sum(size) …) <=
55
+ * limit - additional` — because two statements cannot be made to hold a reservation without a
56
+ * transaction, and D1 has none to offer. SQLite evaluates the sub-select while it holds the write
57
+ * lock, so a burst of concurrent inits is serialized by the database itself: each one sees every
58
+ * reservation that landed before it, and the first that would breach the limit inserts nothing.
59
+ *
60
+ * `RETURNING id` is how "inserted nothing" is read back. Zero rows is not an error to SQLite — the
61
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
62
+ */
63
+ async function insertReservingQuota(reservation) {
64
+ const { db, ownerId, limitBytes, additionalBytes, record } = reservation;
65
+ if (limitBytes === null || ownerId === null) {
66
+ await db.insertInto(STORAGE_OBJECTS_TABLE).values(record).execute();
67
+ return;
68
+ }
69
+ assertDeclaredSize(additionalBytes);
70
+ const columns = Object.keys(record);
71
+ const values = db.selectNoFrom((eb) => columns.map((column) => eb.val(record[column]).as(column))).where((eb) => eb(eb.selectFrom(STORAGE_OBJECTS_TABLE).select(sql`coalesce(sum(size), 0)`.as("used")).where("ownerId", "=", ownerId).where("status", "in", [...QUOTA_COUNTED_STATUSES]), "<=", limitBytes - additionalBytes));
72
+ if (!await db.insertInto("pithyStorageObjects").columns(columns).expression(values).returning("id").executeTakeFirst()) throw new StorageQuotaExceededError({ detail: `reservation of ${additionalBytes} bytes lost against a limit of ${limitBytes}` });
73
+ }
74
+ /**
75
+ * Rewrite one row **only if** the bytes it newly claims still fit inside the owner's quota, and throw
76
+ * `storage/quota_exceeded` when they do not.
77
+ *
78
+ * This is {@link insertReservingQuota}'s other half, and it exists for the identical reason. A
79
+ * completion measures what R2 actually holds against what the pending row reserved, and the difference
80
+ * is bytes the owner has not been granted yet. Settling that difference with a separate
81
+ * {@link assertWithinQuota} would put the enforcement back where it never worked: two completions
82
+ * racing both read a total neither has yet contributed to, both pass, and the owner ends over the
83
+ * limit — the same defect the conditional insert was written to close, one lifecycle stage later.
84
+ *
85
+ * `additionalBytes` is the **overshoot**, not the object's size. The row being updated is still
86
+ * `pending`, so the sub-select in the `WHERE` already counts its reservation: SQLite evaluates the
87
+ * condition against the pre-update table. Passing the full size would bill the reservation twice.
88
+ *
89
+ * `RETURNING id` reads back whether the row moved. Zero rows updated is not an error to SQLite — the
90
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
91
+ */
92
+ async function updateSettlingQuota(settlement) {
93
+ const { db, ownerId, limitBytes, additionalBytes, record } = settlement;
94
+ if (limitBytes === null || ownerId === null) {
95
+ await db.updateTable(STORAGE_OBJECTS_TABLE).set(record).where("id", "=", record.id).execute();
96
+ return;
97
+ }
98
+ assertDeclaredSize(additionalBytes);
99
+ if (!await db.updateTable("pithyStorageObjects").set(record).where("id", "=", record.id).where((eb) => eb(eb.selectFrom("pithyStorageObjects").select(sql`coalesce(sum(size), 0)`.as("used")).where("ownerId", "=", ownerId).where("status", "in", [...QUOTA_COUNTED_STATUSES]), "<=", limitBytes - additionalBytes)).returning("id").executeTakeFirst()) throw new StorageQuotaExceededError({ detail: `settlement of ${additionalBytes} further bytes lost against a limit of ${limitBytes}` });
100
+ }
101
+ //#endregion
102
+ export { QUOTA_COUNTED_STATUSES, assertWithinQuota, insertReservingQuota, updateSettlingQuota, usedBytes };
@@ -0,0 +1,72 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { SecretOrigin, SecretRotation } from "@pithy-sh/core/src/capability/secretOrigin";
4
+ import { z } from "zod";
5
+ /**
6
+ * The R2 credential bundle the {@link ObjectStore} seam reads, and the **factory** that declares it
7
+ * under any name (CLAUDE.md §Secrets).
8
+ *
9
+ * Why a factory and not a bare name. `sharedSecretsStore(env, registry)` throws for any name absent
10
+ * from the *aggregated* registry, and that registry is built only from the composed capabilities'
11
+ * `secretRegistry` slices. So `objectStore({ bucket, secretName })` cannot resolve a string on its
12
+ * own — something must have declared that name, with a schema, on a capability. The factory is that
13
+ * something: storage declares `storage-r2-credentials` for `STORAGE_BUCKET`, `@pithy-sh/media`
14
+ * declares `media-r2-credentials` for `MEDIA_BUCKET`, and both point the same seam at their own
15
+ * bucket without either package knowing the other's name.
16
+ *
17
+ * One factory is also what makes the join key safe. `aggregateSecretRegistries` allows a name to be
18
+ * declared twice only when every axis agrees (`backend`, `scope`, `valueType`, `rotatable`); two
19
+ * hand-written declarations drift, one factory cannot.
20
+ */
21
+ /**
22
+ * The credentials one R2 bucket is addressed and presigned with. Composed from
23
+ * {@link R2Credentials} rather than redeclaring the key pair — that shape is `@pithy-sh/cloudflare`'s
24
+ * to define, and `CloudflareR2Manager` validates its config against it.
25
+ */
26
+ export declare const R2StorageCredentials: z.ZodObject<{
27
+ accessKeyId: z.ZodString;
28
+ secretAccessKey: z.ZodString;
29
+ accountId: z.ZodString;
30
+ bucket: z.ZodString;
31
+ apiToken: z.ZodString;
32
+ }, z.core.$strip>;
33
+ export type R2StorageCredentials = z.output<typeof R2StorageCredentials>;
34
+ /**
35
+ * One R2-credentials registry entry. Spelled out as a type so the factory can return
36
+ * `Record<N, R2CredentialsEntry>` — a computed key alone widens to a string index signature, which
37
+ * would lose the literal name `SecretsAccessor.get` narrows on.
38
+ */
39
+ export interface R2CredentialsEntry {
40
+ /**
41
+ * An encrypted row in the per-environment secrets D1 — where these values actually live.
42
+ *
43
+ * No `wrangler.jsonc` binds an R2 credential bundle from the Cloudflare Secrets Store; `pithy storage
44
+ * provision` and `pithy media provision` write it through `dispatchSecretWrite` → the manager
45
+ * Workflow → `SystemSecretsStore`, which is the D1 path. The registry's `backend` is the *single*
46
+ * place a secret's storage location is decided and is what the read seam routes on, so declaring
47
+ * `cf-secrets-store` here would send every deployed read to a binding that does not exist.
48
+ */
49
+ backend: "d1";
50
+ /** Each environment addresses its own bucket with its own key pair. */
51
+ scope: "environment";
52
+ /** R2 S3 key pairs are minted and replaced whole, not rotated with overlap windows. */
53
+ rotatable: false;
54
+ /** A JSON bundle, validated against {@link R2StorageCredentials} before it is exposed. */
55
+ valueType: "json";
56
+ /** The bundle's shape. */
57
+ schema: typeof R2StorageCredentials;
58
+ /** Where the pair comes from. `obtained`, always — see {@link R2_CREDENTIALS_PAGE}. */
59
+ origin: SecretOrigin;
60
+ /** How the pair is replaced. `manual`, always — the same page, by the same human. */
61
+ rotation: SecretRotation;
62
+ }
63
+ /**
64
+ * A one-entry secret-registry slice declaring `name` as an R2 credential bundle. Hang it on the
65
+ * declaring capability's `secretRegistry`, then pass the same `name` to `objectStore`.
66
+ */
67
+ export declare function r2CredentialsRegistry<const N extends string>(name: N): Record<N, R2CredentialsEntry>;
68
+ /** The name storage's own bucket credentials are stored and resolved under. */
69
+ export declare const STORAGE_R2_SECRET = "storage-r2-credentials";
70
+ /** The storage capability's secret-registry slice — aggregated into the shared accessor at startup. */
71
+ export declare const storageSecretsRegistry: Record<"storage-r2-credentials", R2CredentialsEntry>;
72
+ //# sourceMappingURL=registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAE/F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;iBASmF,CAAC;AACrH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,OAAO,EAAE,IAAI,CAAC;IACd,uEAAuE;IACvE,KAAK,EAAE,aAAa,CAAC;IACrB,uFAAuF;IACvF,SAAS,EAAE,KAAK,CAAC;IACjB,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,uFAAuF;IACvF,MAAM,EAAE,YAAY,CAAC;IACrB,qFAAqF;IACrF,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAmCD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAEpG;AAED,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,sDAA2C,CAAC"}
@@ -0,0 +1,84 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ import { R2Credentials } from "@pithy-sh/cloudflare/src/r2/r2Credentials";
5
+ import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
6
+ //#region src/secret/registry.ts
7
+ /**
8
+ * The R2 credential bundle the {@link ObjectStore} seam reads, and the **factory** that declares it
9
+ * under any name (CLAUDE.md §Secrets).
10
+ *
11
+ * Why a factory and not a bare name. `sharedSecretsStore(env, registry)` throws for any name absent
12
+ * from the *aggregated* registry, and that registry is built only from the composed capabilities'
13
+ * `secretRegistry` slices. So `objectStore({ bucket, secretName })` cannot resolve a string on its
14
+ * own — something must have declared that name, with a schema, on a capability. The factory is that
15
+ * something: storage declares `storage-r2-credentials` for `STORAGE_BUCKET`, `@pithy-sh/media`
16
+ * declares `media-r2-credentials` for `MEDIA_BUCKET`, and both point the same seam at their own
17
+ * bucket without either package knowing the other's name.
18
+ *
19
+ * One factory is also what makes the join key safe. `aggregateSecretRegistries` allows a name to be
20
+ * declared twice only when every axis agrees (`backend`, `scope`, `valueType`, `rotatable`); two
21
+ * hand-written declarations drift, one factory cannot.
22
+ */
23
+ /**
24
+ * The credentials one R2 bucket is addressed and presigned with. Composed from
25
+ * {@link R2Credentials} rather than redeclaring the key pair — that shape is `@pithy-sh/cloudflare`'s
26
+ * to define, and `CloudflareR2Manager` validates its config against it.
27
+ */
28
+ const R2StorageCredentials = R2Credentials.extend({
29
+ accountId: z.string().min(1).describe("The Cloudflare account id the bucket lives in — the S3 endpoint host."),
30
+ bucket: z.string().min(1).describe("The R2 bucket name every presigned URL and server-side object call targets."),
31
+ apiToken: z.string().min(1).describe("The R2-scoped Cloudflare API token the key pair was derived from. Carried alongside because an R2 S3 access key IS a CF API token — the id is the key id, the SHA-256 of the value is the secret — so whatever provisions the pair already holds it, and `CloudflareR2Manager` needs it to prove bucket access.")
32
+ }).describe("The account, key pair, scoped token, and bucket name the object store presigns and addresses R2 with.");
33
+ /**
34
+ * Where a human makes an R2 S3 access-key pair, and where the same human makes the next one.
35
+ *
36
+ * **Nothing here will ever mint one, and that is the fact the declaration carries.** Cloudflare has no
37
+ * API that returns an S3 access-key pair, so `pithy storage provision` and `pithy media provision` both
38
+ * take one as a flag and write it as given — a generated value would open no bucket and would replace a
39
+ * loud gap with a quiet one. Naming the page is the whole of the help the kit can offer, which is exactly
40
+ * what `obtained` is for.
41
+ *
42
+ * Origin and rotation name the same page because it is the same page: replacement is making another pair
43
+ * and deleting the old one. That is also why {@link R2CredentialsEntry.rotatable} is false — there is no
44
+ * overlap window to hold two live versions through.
45
+ */
46
+ const R2_CREDENTIALS_PAGE = "https://developers.cloudflare.com/r2/api/tokens/";
47
+ /**
48
+ * The one entry shape every name shares — declared once so no two declarations can disagree.
49
+ *
50
+ * The two declaration axes live here rather than at each name for the reason the rest of the entry does:
51
+ * `storage-r2-credentials` and `media-r2-credentials` are the same kind of credential from the same
52
+ * issuer, and `aggregateSecretRegistries` refuses a name two capabilities describe differently. One
53
+ * factory is how they cannot.
54
+ */
55
+ const R2_CREDENTIALS_ENTRY = {
56
+ backend: "d1",
57
+ scope: "environment",
58
+ rotatable: false,
59
+ valueType: "json",
60
+ schema: R2StorageCredentials,
61
+ origin: {
62
+ kind: "obtained",
63
+ issuer: "cloudflare",
64
+ documentation: R2_CREDENTIALS_PAGE
65
+ },
66
+ rotation: {
67
+ kind: "manual",
68
+ issuer: "cloudflare",
69
+ documentation: R2_CREDENTIALS_PAGE
70
+ }
71
+ };
72
+ /**
73
+ * A one-entry secret-registry slice declaring `name` as an R2 credential bundle. Hang it on the
74
+ * declaring capability's `secretRegistry`, then pass the same `name` to `objectStore`.
75
+ */
76
+ function r2CredentialsRegistry(name) {
77
+ return defineSecretRegistry({ [name]: R2_CREDENTIALS_ENTRY });
78
+ }
79
+ /** The name storage's own bucket credentials are stored and resolved under. */
80
+ const STORAGE_R2_SECRET = "storage-r2-credentials";
81
+ /** The storage capability's secret-registry slice — aggregated into the shared accessor at startup. */
82
+ const storageSecretsRegistry = r2CredentialsRegistry(STORAGE_R2_SECRET);
83
+ //#endregion
84
+ export { R2StorageCredentials, STORAGE_R2_SECRET, r2CredentialsRegistry, storageSecretsRegistry };
@@ -0,0 +1,5 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { type SeedSet } from "@pithy-sh/core/src/seed/seed";
4
+ export declare const storageExampleSeed: SeedSet;
5
+ //# sourceMappingURL=example.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/seeds/example.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4C,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AA+DtG,eAAO,MAAM,kBAAkB,EAAE,OAoD/B,CAAC"}
@@ -0,0 +1,111 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { StorageObject } from "../data/storageObject.js";
4
+ import { STORAGE_OBJECTS_TABLE } from "../data/tables.js";
5
+ import { OBJECT_KEY_PREFIX } from "../object/key.js";
6
+ import { EXAMPLE_ADA, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
7
+ import { d1SeedGroup, defineSeed } from "@pithy-sh/core/src/seed/seed";
8
+ //#region src/seeds/example.ts
9
+ /**
10
+ * Where the example set sorts among the whole project's seed registry. It runs after `auth` (100),
11
+ * whose example seeds the users these files belong to, so the owning identities exist first — the
12
+ * order encodes that dependency, exactly like the migration registry. It need not line up with
13
+ * {@link STORAGE_MIGRATION_ORDER}: a different registry, composed separately by `pithy seed`.
14
+ */
15
+ const STORAGE_EXAMPLE_SEED_ORDER = 230;
16
+ /**
17
+ * A handful of demo files for the canonical example cast ({@link EXAMPLE_ADA} et al.).
18
+ *
19
+ * **Both halves are seeded — the rows and the bytes.** A storage row with no object in the bucket is
20
+ * precisely the divergence the orphan sweep exists to reconcile, so a fixture that seeded only D1
21
+ * would ship a demo where every download 404s and the sweep has work to do on a fresh install. The
22
+ * `r2` items below write the same keys the rows name, so `GET /storage/:id` returns real content on
23
+ * a freshly seeded environment.
24
+ *
25
+ * The ids and keys are **fixed**, not generated, which is what makes the set idempotent: re-seeding
26
+ * writes the same rows over the same keys rather than accumulating a new copy of Ada's notes on every
27
+ * run. One file is `public` on purpose, so the unauthenticated read path is exercised by the demo
28
+ * data rather than only by the tests.
29
+ *
30
+ * Composed in only when the project turns on `seed.includeExamples` (`pithy.config.ts`), and only for
31
+ * `dev` and `staging` — an example fixture never targets `prod`, regardless of that setting.
32
+ */
33
+ /** Fixed ids, so the fixture is idempotent and the D1 rows and R2 objects cannot drift apart. */
34
+ const NOTES_ID = "6f1c8f36-30a5-4d5f-9f4d-6a5a52b9f0a1";
35
+ const PLAN_ID = "8c2d9a47-41b6-4e60-a05e-7b6b63c0e1b2";
36
+ const README_ID = "9d3ea058-52c7-4f71-b16f-8c7c74d1f2c3";
37
+ const CREATED_AT = /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z");
38
+ /** The demo bodies. Declared once so a row's `size` is the byte count actually written to R2. */
39
+ const BODIES = {
40
+ [NOTES_ID]: "Lovelace, notes on the Analytical Engine.\n",
41
+ [PLAN_ID]: "Hopper, plan for the next compiler.\n",
42
+ [README_ID]: "A public file. Anyone with the id may read this one.\n"
43
+ };
44
+ /** Bytes of a demo body — `size` must be the encoded length, not the character count. */
45
+ function byteLength(id) {
46
+ return new TextEncoder().encode(BODIES[id]).length;
47
+ }
48
+ /** The R2 object key a demo file lives under — the same opaque `obj/<uuid>` shape the handlers derive. */
49
+ function demoKey(id) {
50
+ return `${OBJECT_KEY_PREFIX}${id}`;
51
+ }
52
+ /** The bucket objects the rows point at, so a seeded environment can actually serve the bytes. */
53
+ const objects = Object.keys(BODIES).map((id) => ({
54
+ binding: "STORAGE_BUCKET",
55
+ key: demoKey(id),
56
+ body: BODIES[id],
57
+ contentType: "text/plain"
58
+ }));
59
+ const storageExampleSeed = defineSeed({
60
+ name: "example",
61
+ order: STORAGE_EXAMPLE_SEED_ORDER,
62
+ environments: ["dev", "staging"],
63
+ example: true,
64
+ d1: [d1SeedGroup("app", STORAGE_OBJECTS_TABLE, StorageObject, [
65
+ {
66
+ id: NOTES_ID,
67
+ key: demoKey(NOTES_ID),
68
+ path: "notes/analytical-engine.txt",
69
+ ownerId: EXAMPLE_ADA.id,
70
+ contentType: "text/plain",
71
+ size: byteLength(NOTES_ID),
72
+ visibility: "private",
73
+ checksum: null,
74
+ status: "stored",
75
+ uploadId: null,
76
+ createdAt: CREATED_AT,
77
+ updatedAt: CREATED_AT
78
+ },
79
+ {
80
+ id: PLAN_ID,
81
+ key: demoKey(PLAN_ID),
82
+ path: "plans/compiler.txt",
83
+ ownerId: EXAMPLE_GRACE.id,
84
+ contentType: "text/plain",
85
+ size: byteLength(PLAN_ID),
86
+ visibility: "private",
87
+ checksum: null,
88
+ status: "stored",
89
+ uploadId: null,
90
+ createdAt: CREATED_AT,
91
+ updatedAt: CREATED_AT
92
+ },
93
+ {
94
+ id: README_ID,
95
+ key: demoKey(README_ID),
96
+ path: "public/readme.txt",
97
+ ownerId: EXAMPLE_ADA.id,
98
+ contentType: "text/plain",
99
+ size: byteLength(README_ID),
100
+ visibility: "public",
101
+ checksum: null,
102
+ status: "stored",
103
+ uploadId: null,
104
+ createdAt: CREATED_AT,
105
+ updatedAt: CREATED_AT
106
+ }
107
+ ])],
108
+ r2: objects
109
+ });
110
+ //#endregion
111
+ export { storageExampleSeed };