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