@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,203 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { R2Bucket, ReadableStream } from "@cloudflare/workers-types";
4
+ import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
5
+ import { z } from "zod";
6
+ import { type R2StorageCredentials } from "../secret/registry";
7
+ import type { ReportedPart } from "./multipart";
8
+ /**
9
+ * `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
10
+ *
11
+ * **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
12
+ * constructed over an injected bucket binding and a *named* credential secret, which is exactly what
13
+ * lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
14
+ * inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
15
+ * must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
16
+ * imports is what guarantees it.
17
+ *
18
+ * It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
19
+ * in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
20
+ * the other's scheme.
21
+ *
22
+ * **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
23
+ * delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
24
+ * Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
25
+ * bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
26
+ * hides which is which; only `object/cloudflare.ts` touches the manager.
27
+ *
28
+ * Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
29
+ * boundary rather than surfacing as `undefined` three layers up.
30
+ */
31
+ /** An object's metadata, as either a HEAD or a GET reports it. */
32
+ export declare const ObjectMetadata: z.ZodObject<{
33
+ key: z.ZodString;
34
+ size: z.ZodNumber;
35
+ etag: z.ZodString;
36
+ contentType: z.ZodOptional<z.ZodString>;
37
+ contentDisposition: z.ZodOptional<z.ZodString>;
38
+ uploaded: z.ZodDate;
39
+ checksumSha256: z.ZodOptional<z.ZodString>;
40
+ }, z.core.$strip>;
41
+ export type ObjectMetadata = z.output<typeof ObjectMetadata>;
42
+ /** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
43
+ export declare const ObjectRange: z.ZodObject<{
44
+ offset: z.ZodOptional<z.ZodNumber>;
45
+ length: z.ZodOptional<z.ZodNumber>;
46
+ suffix: z.ZodOptional<z.ZodNumber>;
47
+ }, z.core.$strip>;
48
+ export type ObjectRange = z.output<typeof ObjectRange>;
49
+ /** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
50
+ export declare const ObjectConditions: z.ZodObject<{
51
+ etagMatches: z.ZodOptional<z.ZodString>;
52
+ etagDoesNotMatch: z.ZodOptional<z.ZodString>;
53
+ uploadedBefore: z.ZodOptional<z.ZodDate>;
54
+ uploadedAfter: z.ZodOptional<z.ZodDate>;
55
+ }, z.core.$strip>;
56
+ export type ObjectConditions = z.output<typeof ObjectConditions>;
57
+ /** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
58
+ export declare const ObjectListing: z.ZodObject<{
59
+ objects: z.ZodArray<z.ZodObject<{
60
+ key: z.ZodString;
61
+ size: z.ZodNumber;
62
+ etag: z.ZodString;
63
+ contentType: z.ZodOptional<z.ZodString>;
64
+ contentDisposition: z.ZodOptional<z.ZodString>;
65
+ uploaded: z.ZodDate;
66
+ checksumSha256: z.ZodOptional<z.ZodString>;
67
+ }, z.core.$strip>>;
68
+ cursor: z.ZodOptional<z.ZodString>;
69
+ }, z.core.$strip>;
70
+ export type ObjectListing = z.output<typeof ObjectListing>;
71
+ /** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
72
+ export declare const UploadedPart: z.ZodObject<{
73
+ partNumber: z.ZodNumber;
74
+ etag: z.ZodString;
75
+ size: z.ZodNumber;
76
+ }, z.core.$strip>;
77
+ export type UploadedPart = z.output<typeof UploadedPart>;
78
+ /** How long a presigned URL stays valid. */
79
+ export interface PresignOptions {
80
+ /** Lifetime in seconds. Defaults to one hour — long enough for a large part, short enough to leak little. */
81
+ expiresIn?: number;
82
+ }
83
+ /** Presign options for one part, which may additionally pin its exact byte count. */
84
+ export interface PresignPartOptions extends PresignOptions {
85
+ /** Exact byte count the client must send. Omitted by default; see `presignPart`. */
86
+ contentLength?: number;
87
+ }
88
+ /** What to read, and under what preconditions. */
89
+ export interface GetOptions {
90
+ /** Serve only this byte range (206). */
91
+ range?: ObjectRange;
92
+ /** Serve only if these preconditions hold; otherwise the result carries metadata and no body (304). */
93
+ onlyIf?: ObjectConditions;
94
+ }
95
+ /** Which slice of the bucket to list. */
96
+ export interface ListOptions {
97
+ /** Only keys starting with this prefix. Omitted lists the whole bucket. */
98
+ prefix?: string;
99
+ /** Continuation cursor from a previous page. */
100
+ cursor?: string;
101
+ /** Page size. R2 caps this at 1,000. */
102
+ limit?: number;
103
+ }
104
+ /** An object read: its metadata, its bytes, and the range R2 actually served. */
105
+ export interface ObjectBody {
106
+ /** The whole object's metadata — `size` is the object's, not the range's. */
107
+ metadata: ObjectMetadata;
108
+ /** The bytes, streamed. `null` when a precondition failed, which is the 304 signal. */
109
+ body: ReadableStream | null;
110
+ /** The byte range R2 served, when a range was asked for. `null` means the whole object. */
111
+ range: {
112
+ offset: number;
113
+ length: number;
114
+ } | null;
115
+ }
116
+ /**
117
+ * The S3-protocol half of the seam: everything the R2 binding cannot do without pulling bytes through
118
+ * the Worker. Declared here as a structural port so `store.ts` never imports `@pithy-sh/cloudflare`,
119
+ * and so a test can drive the store with no SDK and no network.
120
+ */
121
+ export interface PresignedObjects {
122
+ /**
123
+ * Presign a PUT for one whole object. The length is signed, so the client must send exactly that many
124
+ * bytes. The type is **not** — S3 presigning marks `content-type` unsignable — so it is a hint the
125
+ * completion reconciles against what R2 actually stored.
126
+ */
127
+ presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
128
+ /** Presign a GET for one object. */
129
+ presignGet(key: string, options?: PresignOptions): Promise<string>;
130
+ /** Open a multipart upload; returns the `uploadId` every later step is addressed by. */
131
+ createMultipartUpload(key: string, contentType: string): Promise<string>;
132
+ /** Presign a PUT for one part — the only multipart step a client ever touches. */
133
+ presignUploadPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
134
+ /** Assemble the uploaded parts into one object. */
135
+ completeMultipartUpload(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
136
+ /** Discard an in-flight upload and its stored parts. Idempotent. */
137
+ abortMultipartUpload(key: string, uploadId: string): Promise<void>;
138
+ /** List the parts already stored against an in-flight upload, ascending. */
139
+ listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
140
+ /** Copy an object within the bucket, server-side — the bytes never leave R2. */
141
+ copyObject(sourceKey: string, destinationKey: string): Promise<void>;
142
+ }
143
+ /** The object plane: presigned transfer, the multipart lifecycle, and binding-backed reads. */
144
+ export interface ObjectStore {
145
+ /** Presign a PUT the client uploads a whole object to. Bytes never proxy through the Worker. */
146
+ presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
147
+ /** Presign a GET — the escape hatch for serving without a Worker in the byte path. */
148
+ presignGet(key: string, options?: PresignOptions): Promise<string>;
149
+ /** Open a multipart upload. Persist the returned `uploadId`: it is the handle a resume needs. */
150
+ initMultipart(key: string, contentType: string): Promise<string>;
151
+ /**
152
+ * Presign a PUT for one part. `contentLength` is **not** signed by default: the final part's length
153
+ * differs from every other, so signing it would mean knowing the total size at mint time. R2 enforces
154
+ * the 5 MiB floor and 5 GiB ceiling itself, and the object's real size is confirmed at completion.
155
+ */
156
+ presignPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
157
+ /** Assemble the reported parts into one object. Order and completeness are checked before R2 sees them. */
158
+ completeMultipart(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
159
+ /** Abort an in-flight upload. Idempotent, so a sweep or a retried teardown can re-run. */
160
+ abortMultipart(key: string, uploadId: string): Promise<void>;
161
+ /** The parts already stored against an in-flight upload — what a resuming client asks for. */
162
+ listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
163
+ /** Read an object through the binding, honoring a range and conditional preconditions. `null` when absent. */
164
+ get(key: string, options?: GetOptions): Promise<ObjectBody | null>;
165
+ /** Read an object's metadata without its body. `null` when absent — a missing object is an answer. */
166
+ head(key: string): Promise<ObjectMetadata | null>;
167
+ /** One page of bucket keys. The orphan sweep's view; an owner's file list comes from D1. */
168
+ list(options?: ListOptions): Promise<ObjectListing>;
169
+ /** Server-side copy within the bucket. */
170
+ copy(sourceKey: string, destinationKey: string): Promise<void>;
171
+ /** Delete one object. Idempotent by protocol. */
172
+ delete(key: string): Promise<void>;
173
+ }
174
+ /** How to build an object store. */
175
+ export interface ObjectStoreOptions {
176
+ /** The R2 bucket binding — `STORAGE_BUCKET` for storage, `MEDIA_BUCKET` for media. */
177
+ bucket: R2Bucket;
178
+ /**
179
+ * The env the credential secret resolves against. Only ever handed to `sharedSecretsStore`; no
180
+ * binding on it is read directly (CLAUDE.md §Secrets).
181
+ */
182
+ env: SecretsStoreEnv;
183
+ /**
184
+ * The registry name the R2 credential bundle is stored under. Whatever name is passed, the *same*
185
+ * capability must have declared it with `r2CredentialsRegistry(name)` — a name no capability
186
+ * declared is absent from the aggregated registry and throws on first use.
187
+ */
188
+ secretName?: string;
189
+ /**
190
+ * Test seam: build the S3 port from resolved credentials. Defaults to the real R2 adapter. Overriding
191
+ * it is how a test drives the store with no SDK, no credentials, and no network.
192
+ */
193
+ presigned?: (credentials: R2StorageCredentials) => PresignedObjects;
194
+ }
195
+ /**
196
+ * Build an object store over a bucket binding and a named credential secret.
197
+ *
198
+ * Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
199
+ * secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
200
+ * two concurrent presigns share one resolution rather than racing two.
201
+ */
202
+ export declare function objectStore(options: ObjectStoreOptions): ObjectStore;
203
+ //# sourceMappingURL=store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/object/store.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,178 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { r2CredentialsRegistry } from "../secret/registry.js";
4
+ import { r2Presigned } from "./cloudflare.js";
5
+ import { z } from "zod";
6
+ import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
7
+ //#region src/object/store.ts
8
+ /**
9
+ * `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
10
+ *
11
+ * **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
12
+ * constructed over an injected bucket binding and a *named* credential secret, which is exactly what
13
+ * lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
14
+ * inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
15
+ * must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
16
+ * imports is what guarantees it.
17
+ *
18
+ * It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
19
+ * in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
20
+ * the other's scheme.
21
+ *
22
+ * **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
23
+ * delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
24
+ * Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
25
+ * bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
26
+ * hides which is which; only `object/cloudflare.ts` touches the manager.
27
+ *
28
+ * Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
29
+ * boundary rather than surfacing as `undefined` three layers up.
30
+ */
31
+ /** An object's metadata, as either a HEAD or a GET reports it. */
32
+ const ObjectMetadata = z.object({
33
+ key: z.string().min(1).describe("The R2 object key. Opaque to the caller — policy lives in `key.ts`."),
34
+ size: z.number().int().nonnegative().describe("The whole object's size in bytes, not the served range's."),
35
+ etag: z.string().min(1).describe("R2's entity tag for this object version, unquoted. Quote it before it becomes an `ETag` header."),
36
+ contentType: z.string().min(1).optional().describe("The stored `Content-Type`. Absent when the object was written without one."),
37
+ contentDisposition: z.string().min(1).optional().describe("The stored `Content-Disposition`, when one was written. Recorded, not honored — the serve path derives its own, because this string is whatever the uploader sent."),
38
+ uploaded: z.date().describe("When R2 wrote this object version."),
39
+ checksumSha256: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("Lowercase hex SHA-256, when R2 holds one. Absent unless the upload supplied or requested it.")
40
+ }).describe("One object's metadata — everything a serve path needs without transferring the body.");
41
+ /** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
42
+ const ObjectRange = z.object({
43
+ offset: z.number().int().nonnegative().optional().describe("First byte to read, from the start of the object."),
44
+ length: z.number().int().positive().optional().describe("How many bytes to read from `offset`."),
45
+ suffix: z.number().int().positive().optional().describe("Read this many bytes from the *end* — `bytes=-N`.")
46
+ }).describe("A byte range to read, as an HTTP `Range` header maps onto R2.");
47
+ /** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
48
+ const ObjectConditions = z.object({
49
+ etagMatches: z.string().min(1).optional().describe("Read only if the object's etag equals this (`If-Match`)."),
50
+ etagDoesNotMatch: z.string().min(1).optional().describe("Read only if the object's etag differs (`If-None-Match`) — the 304 path."),
51
+ uploadedBefore: z.date().optional().describe("Read only if the object was written before this (`If-Unmodified-Since`)."),
52
+ uploadedAfter: z.date().optional().describe("Read only if the object was written after this (`If-Modified-Since`).")
53
+ }).describe("Conditional-read preconditions. R2 returns metadata with no body when one fails.");
54
+ /** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
55
+ const ObjectListing = z.object({
56
+ objects: z.array(ObjectMetadata).describe("This page's objects, in R2's lexicographic key order."),
57
+ cursor: z.string().min(1).optional().describe("Continuation cursor for the next page. Absent means this page was the last.")
58
+ }).describe("One page of a bucket listing. Pagination is caller-driven — pass `cursor` back to advance.");
59
+ /** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
60
+ const UploadedPart = z.object({
61
+ partNumber: z.number().int().min(1).describe("The part's 1-based index within the upload."),
62
+ etag: z.string().min(1).describe("The part's entity tag, verbatim. Pass it back unchanged to complete."),
63
+ size: z.number().int().nonnegative().describe("The part's size in bytes, as R2 stored it.")
64
+ }).describe("One uploaded part — the unit a resumed upload skips re-sending.");
65
+ /** Map our range shape onto R2's — the binding's union admits exactly one of these three forms. */
66
+ function toR2Range(range) {
67
+ if (!range) return void 0;
68
+ if (range.suffix !== void 0) return { suffix: range.suffix };
69
+ if (range.offset !== void 0 && range.length !== void 0) return {
70
+ offset: range.offset,
71
+ length: range.length
72
+ };
73
+ if (range.offset !== void 0) return { offset: range.offset };
74
+ if (range.length !== void 0) return { length: range.length };
75
+ }
76
+ /** Lowercase hex for a checksum R2 hands back as raw bytes. */
77
+ function toHex(buffer) {
78
+ return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
79
+ }
80
+ /** Validate an `R2Object` into {@link ObjectMetadata} — the one place binding shapes cross the seam. */
81
+ function toMetadata(object) {
82
+ return ObjectMetadata.parse({
83
+ key: object.key,
84
+ size: object.size,
85
+ etag: object.etag,
86
+ contentType: object.httpMetadata?.contentType,
87
+ contentDisposition: object.httpMetadata?.contentDisposition,
88
+ uploaded: object.uploaded,
89
+ checksumSha256: object.checksums?.sha256 ? toHex(object.checksums.sha256) : void 0
90
+ });
91
+ }
92
+ /**
93
+ * Build an object store over a bucket binding and a named credential secret.
94
+ *
95
+ * Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
96
+ * secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
97
+ * two concurrent presigns share one resolution rather than racing two.
98
+ */
99
+ function objectStore(options) {
100
+ const secretName = options.secretName ?? "storage-r2-credentials";
101
+ const build = options.presigned ?? r2Presigned;
102
+ const bucket = options.bucket;
103
+ let presignedPromise = null;
104
+ function presigned() {
105
+ if (!presignedPromise) presignedPromise = (async () => {
106
+ const registry = r2CredentialsRegistry(secretName);
107
+ const store = await sharedSecretsStore(options.env, registry);
108
+ return build(store.get(secretName));
109
+ })();
110
+ return presignedPromise;
111
+ }
112
+ return {
113
+ async presignPut(key, contentType, contentLength, presignOptions) {
114
+ return (await presigned()).presignPut(key, contentType, contentLength, presignOptions);
115
+ },
116
+ async presignGet(key, presignOptions) {
117
+ return (await presigned()).presignGet(key, presignOptions);
118
+ },
119
+ async initMultipart(key, contentType) {
120
+ return (await presigned()).createMultipartUpload(key, contentType);
121
+ },
122
+ async presignPart(key, uploadId, partNumber, presignOptions) {
123
+ return (await presigned()).presignUploadPart(key, uploadId, partNumber, presignOptions);
124
+ },
125
+ async completeMultipart(key, uploadId, parts) {
126
+ await (await presigned()).completeMultipartUpload(key, uploadId, parts);
127
+ },
128
+ async abortMultipart(key, uploadId) {
129
+ await (await presigned()).abortMultipartUpload(key, uploadId);
130
+ },
131
+ async listParts(key, uploadId) {
132
+ return (await presigned()).listParts(key, uploadId);
133
+ },
134
+ async get(key, getOptions) {
135
+ const conditions = getOptions?.onlyIf;
136
+ const object = await bucket.get(key, {
137
+ range: toR2Range(getOptions?.range),
138
+ onlyIf: conditions ? conditions : void 0
139
+ });
140
+ if (!object) return null;
141
+ const body = "body" in object ? object.body : null;
142
+ const served = getOptions?.range && object.range ? object.range : void 0;
143
+ const offset = served && "offset" in served ? served.offset ?? 0 : 0;
144
+ const length = served && "length" in served ? served.length ?? 0 : 0;
145
+ return {
146
+ metadata: toMetadata(object),
147
+ body,
148
+ range: served ? {
149
+ offset,
150
+ length
151
+ } : null
152
+ };
153
+ },
154
+ async head(key) {
155
+ const object = await bucket.head(key);
156
+ return object ? toMetadata(object) : null;
157
+ },
158
+ async list(listOptions) {
159
+ const page = await bucket.list({
160
+ prefix: listOptions?.prefix,
161
+ cursor: listOptions?.cursor,
162
+ limit: listOptions?.limit
163
+ });
164
+ return ObjectListing.parse({
165
+ objects: page.objects.map(toMetadata),
166
+ cursor: page.truncated ? page.cursor : void 0
167
+ });
168
+ },
169
+ async copy(sourceKey, destinationKey) {
170
+ await (await presigned()).copyObject(sourceKey, destinationKey);
171
+ },
172
+ async delete(key) {
173
+ await bucket.delete(key);
174
+ }
175
+ };
176
+ }
177
+ //#endregion
178
+ export { ObjectConditions, ObjectListing, ObjectMetadata, ObjectRange, UploadedPart, objectStore };
@@ -0,0 +1,139 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
4
+ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
5
+ /**
6
+ * The provisioning orchestration for the storage capability — the live counterpart to
7
+ * `pithy add storage`'s config wiring.
8
+ *
9
+ * The split is deliberate and worth stating, because the two commands look like one. `pithy add`
10
+ * writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
11
+ * `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
12
+ * nothing — an `add` that reached out to an account would make adding a capability an operation you
13
+ * could not do offline, or in CI, or without credentials. This command stands up what those bindings
14
+ * point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
15
+ *
16
+ * The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
17
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
18
+ * per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
19
+ * CLI writes the complete entry here, once the host worker exists.
20
+ *
21
+ * The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
22
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
23
+ * records its call order, and no account. **Every step is idempotent**: find-then-create for the
24
+ * bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
25
+ *
26
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
27
+ * here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
28
+ * and written into the secret as given. That is a real limitation, and the manifest says so rather
29
+ * than promising a mint that does not happen.
30
+ */
31
+ /**
32
+ * The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
33
+ * `acme-prod-storage`.
34
+ *
35
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
36
+ * teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
37
+ * buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
38
+ * `@pithy-sh/email`'s deliberately project-shared suppression database.
39
+ *
40
+ * The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
41
+ * account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
42
+ * same account and silently adopted — two apps writing objects into one bucket, and either teardown
43
+ * deleting both. The name is the only partition R2 offers, so the name carries the owner.
44
+ *
45
+ * Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
46
+ * genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
47
+ * writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
48
+ * keeps it on purpose.
49
+ */
50
+ export declare function storageBucketName(project: string, env: ManagedEnvironment): string;
51
+ /**
52
+ * The deployed sweep-worker name for a project's environment — also its resolved config's basename.
53
+ *
54
+ * A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
55
+ * cannot be renamed once a deploy or a `service` binding points at it.
56
+ */
57
+ export declare function storageWorkerName(project: string, env: ManagedEnvironment): string;
58
+ /** The provisioned resources an environment's worker and secret are wired to. */
59
+ export interface StorageResources {
60
+ /** The R2 bucket objects live in. */
61
+ bucketName: string;
62
+ }
63
+ /** The live Cloudflare/wrangler seam. Each step must be idempotent. */
64
+ export interface StorageProvisioner {
65
+ /**
66
+ * Verify account prerequisites before any resource is created — most importantly a registered
67
+ * `workers.dev` subdomain, which Cloudflare requires to deploy a Workflow-hosting worker. Failing
68
+ * here means failing before a bucket exists, rather than half way through a fan-out.
69
+ */
70
+ preflight(): Promise<void>;
71
+ /** Create (or reuse) this environment's R2 bucket; returns its name. Idempotent. */
72
+ ensureBucket(env: ManagedEnvironment): Promise<{
73
+ bucketName: string;
74
+ }>;
75
+ /**
76
+ * Write this environment's `storage-r2-credentials` secret — the account id, S3 key pair, scoped
77
+ * token, and bucket name the object store presigns with. Idempotent (create, else update). Runs
78
+ * before the worker is deployed: a worker that boots without its credentials fails on its first
79
+ * multipart abort.
80
+ */
81
+ writeCredentials(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
82
+ /** Deploy the prebuilt sweep worker for this environment, wired to the provisioned bucket. */
83
+ deployWorker(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
84
+ }
85
+ /** What provisioning produced, per environment. */
86
+ export interface StorageProvisionResult {
87
+ /** Each environment provisioned, with the resources its worker and secret were wired to. */
88
+ environments: Array<{
89
+ env: ManagedEnvironment;
90
+ } & StorageResources>;
91
+ }
92
+ /**
93
+ * Provision the storage infrastructure: check the account, create every environment's bucket, write
94
+ * every environment's credentials, then deploy every environment's sweep worker.
95
+ *
96
+ * The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
97
+ * must not boot before the secret it reads. Fanning each phase across all environments — rather than
98
+ * completing one environment end to end before starting the next — means a failure creating prod's
99
+ * bucket stops the run before staging's worker is deployed against a half-provisioned account.
100
+ *
101
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
102
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
103
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
104
+ */
105
+ export declare function provisionStorage(provisioner: StorageProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<StorageProvisionResult>;
106
+ /** The teardown seam — the inverse of {@link StorageProvisioner}. Every step idempotent. */
107
+ export interface StorageDeprovisioner {
108
+ /** Delete this environment's sweep worker. Idempotent (a missing worker is a no-op). */
109
+ deleteWorker(env: ManagedEnvironment): Promise<void>;
110
+ /**
111
+ * Delete this environment's R2 bucket **and every file in it**. **Destructive** — nothing here is
112
+ * recoverable. Idempotent (a missing bucket is a no-op).
113
+ *
114
+ * Emptying the bucket is part of the contract, not a nicety: R2 refuses to delete a bucket that still
115
+ * holds an object, or the parts of a multipart upload that was never completed. An implementation that
116
+ * only called the control-plane delete would work on an untouched bucket and fail on every bucket
117
+ * anyone had used.
118
+ */
119
+ deleteBucket(env: ManagedEnvironment): Promise<void>;
120
+ }
121
+ /** Teardown options. By default the stored files are **kept** — only the sweep workers come down. */
122
+ export interface StorageDeprovisionOptions {
123
+ /**
124
+ * Also delete the R2 buckets, with every file in them. Off by default, because those files are the
125
+ * adopter's data and no deploy can restore them — the flag is the confirmation.
126
+ */
127
+ deleteStorage?: boolean;
128
+ }
129
+ /**
130
+ * Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
131
+ * sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
132
+ * everything in them. Idempotent end to end.
133
+ *
134
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
135
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
136
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
137
+ */
138
+ export declare function deprovisionStorage(deprovisioner: StorageDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: StorageDeprovisionOptions): Promise<void>;
139
+ //# sourceMappingURL=provisionStorage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provisionStorage.d.ts","sourceRoot":"","sources":["../../src/provision/provisionStorage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,6BAA6B,CAAC;AAG3F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAElF;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oFAAoF;IACpF,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,8FAA8F;IAC9F,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,4FAA4F;IAC5F,YAAY,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,kBAAkB,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;CACrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,sBAAsB,CAAC,CAiBjC;AASD,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,qGAAqG;AACrG,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,oBAAoB,EACnC,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EACtD,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CASf"}
@@ -0,0 +1,112 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { STORAGE_CAPABILITY } from "../workflows/specs.js";
4
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
5
+ import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
6
+ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
7
+ //#region src/provision/provisionStorage.ts
8
+ /**
9
+ * The provisioning orchestration for the storage capability — the live counterpart to
10
+ * `pithy add storage`'s config wiring.
11
+ *
12
+ * The split is deliberate and worth stating, because the two commands look like one. `pithy add`
13
+ * writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
14
+ * `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
15
+ * nothing — an `add` that reached out to an account would make adding a capability an operation you
16
+ * could not do offline, or in CI, or without credentials. This command stands up what those bindings
17
+ * point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
18
+ *
19
+ * The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
20
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
21
+ * per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
22
+ * CLI writes the complete entry here, once the host worker exists.
23
+ *
24
+ * The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
25
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
26
+ * records its call order, and no account. **Every step is idempotent**: find-then-create for the
27
+ * bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
28
+ *
29
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
30
+ * here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
31
+ * and written into the secret as given. That is a real limitation, and the manifest says so rather
32
+ * than promising a mint that does not happen.
33
+ */
34
+ /**
35
+ * The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
36
+ * `acme-prod-storage`.
37
+ *
38
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
39
+ * teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
40
+ * buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
41
+ * `@pithy-sh/email`'s deliberately project-shared suppression database.
42
+ *
43
+ * The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
44
+ * account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
45
+ * same account and silently adopted — two apps writing objects into one bucket, and either teardown
46
+ * deleting both. The name is the only partition R2 offers, so the name carries the owner.
47
+ *
48
+ * Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
49
+ * genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
50
+ * writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
51
+ * keeps it on purpose.
52
+ */
53
+ function storageBucketName(project, env) {
54
+ return resourceNames(project).env(env).r2(STORAGE_CAPABILITY);
55
+ }
56
+ /**
57
+ * The deployed sweep-worker name for a project's environment — also its resolved config's basename.
58
+ *
59
+ * A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
60
+ * cannot be renamed once a deploy or a `service` binding points at it.
61
+ */
62
+ function storageWorkerName(project, env) {
63
+ return resourceNames(project).env(env).worker(STORAGE_CAPABILITY);
64
+ }
65
+ /**
66
+ * Provision the storage infrastructure: check the account, create every environment's bucket, write
67
+ * every environment's credentials, then deploy every environment's sweep worker.
68
+ *
69
+ * The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
70
+ * must not boot before the secret it reads. Fanning each phase across all environments — rather than
71
+ * completing one environment end to end before starting the next — means a failure creating prod's
72
+ * bucket stops the run before staging's worker is deployed against a half-provisioned account.
73
+ *
74
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
75
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
76
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
77
+ */
78
+ async function provisionStorage(provisioner, environments) {
79
+ await provisioner.preflight();
80
+ const resources = /* @__PURE__ */ new Map();
81
+ for (const env of managedEnvironments(environments)) {
82
+ const { bucketName } = await provisioner.ensureBucket(env);
83
+ resources.set(env, { bucketName });
84
+ }
85
+ for (const env of managedEnvironments(environments)) await provisioner.writeCredentials(env, resourcesFor(resources, env));
86
+ for (const env of managedEnvironments(environments)) await provisioner.deployWorker(env, resourcesFor(resources, env));
87
+ return { environments: managedEnvironments(environments).map((env) => ({
88
+ env,
89
+ ...resourcesFor(resources, env)
90
+ })) };
91
+ }
92
+ /** Read back an environment's resources. Absent is impossible by construction, so the throw is a bug check. */
93
+ function resourcesFor(resources, env) {
94
+ const found = resources.get(env);
95
+ if (!found) throw new InternalError({ message: `No provisioned resources for the ${env} environment.` });
96
+ return found;
97
+ }
98
+ /**
99
+ * Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
100
+ * sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
101
+ * everything in them. Idempotent end to end.
102
+ *
103
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
104
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
105
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
106
+ */
107
+ async function deprovisionStorage(deprovisioner, environments, options = {}) {
108
+ for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
109
+ if (options.deleteStorage) for (const env of managedEnvironments(environments)) await deprovisioner.deleteBucket(env);
110
+ }
111
+ //#endregion
112
+ export { deprovisionStorage, provisionStorage, storageBucketName, storageWorkerName };