@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,92 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { StorageObjectStatus, StorageVisibility } from "../data/storageObject.js";
|
|
4
|
+
import { UploadedPart } from "../object/uploadedPart.js";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
//#region src/http/responses.ts
|
|
7
|
+
/**
|
|
8
|
+
* What the storage routes return as JSON, as Zod objects a client can validate against and the OpenAPI
|
|
9
|
+
* contract can describe. The byte-serving routes (`GET` and `HEAD /storage/:id`, `GET /s/:token`) answer
|
|
10
|
+
* with the object itself rather than JSON, and `routes.ts` describes those inline.
|
|
11
|
+
*
|
|
12
|
+
* `schemas.ts` bounds what a caller may send; this file states what it gets back. These describe JSON on
|
|
13
|
+
* the wire, so a date is the ISO-8601 string `c.json` writes, and nothing here carries a codec or a
|
|
14
|
+
* transform: parsing a response hands back exactly what went in, which is what lets
|
|
15
|
+
* `routes.workers.test.ts` parse a real answer and compare it with the original.
|
|
16
|
+
*
|
|
17
|
+
* **A field added here later is `.optional()` as well as `.nullable()`.** A client generated from the
|
|
18
|
+
* contract reads Workers on older releases too, and a required key they cannot send fails it outright.
|
|
19
|
+
*/
|
|
20
|
+
/** A stored file as a client sees it. The object key and the R2 upload id never appear. */
|
|
21
|
+
const StorageObjectResponse = z.object({
|
|
22
|
+
id: z.string().describe("The file's id. What every other route takes as `:id`."),
|
|
23
|
+
path: z.string().describe("The file's logical path, as the owner named it. Never an R2 key."),
|
|
24
|
+
ownerId: z.string().nullable().describe("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."),
|
|
25
|
+
organizationId: z.string().nullable().optional().describe("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."),
|
|
26
|
+
contentType: z.string().describe("The file's MIME type: as declared at upload, replaced at completion by the type R2 stored."),
|
|
27
|
+
size: z.number().int().nullable().describe("The file's size in bytes: as declared at upload, replaced at completion by what R2 stored."),
|
|
28
|
+
visibility: StorageVisibility,
|
|
29
|
+
checksum: z.string().nullable().describe("Lowercase hex SHA-256 the client reported at completion, or R2's own when it reported none. Null until stored."),
|
|
30
|
+
status: StorageObjectStatus,
|
|
31
|
+
createdAt: z.iso.datetime().describe("When the upload was started, ISO-8601."),
|
|
32
|
+
updatedAt: z.iso.datetime().describe("When the record last changed, ISO-8601.")
|
|
33
|
+
}).describe("One stored file, without its object key or upload id.");
|
|
34
|
+
/** One part of a multipart upload, with the URL its bytes go to. */
|
|
35
|
+
const UploadPartTargetResponse = z.object({
|
|
36
|
+
partNumber: z.number().int().describe("The part's 1-based index within the upload."),
|
|
37
|
+
offset: z.number().int().describe("Where the part starts in the file, in bytes from 0."),
|
|
38
|
+
length: z.number().int().describe("How many bytes the part carries."),
|
|
39
|
+
url: z.string().describe("The presigned URL to PUT exactly these bytes to. Valid for an hour.")
|
|
40
|
+
}).describe("One part of a multipart upload and where to send it.");
|
|
41
|
+
/** Where the bytes go: one URL, or one per part. */
|
|
42
|
+
const UploadTargetResponse = z.discriminatedUnion("kind", [z.object({
|
|
43
|
+
kind: z.literal("single").describe("One PUT carries the whole file."),
|
|
44
|
+
url: z.string().describe("The presigned URL to PUT the whole file to. It signs the declared size.")
|
|
45
|
+
}).describe("A single-PUT upload."), z.object({
|
|
46
|
+
kind: z.literal("multipart").describe("The file goes up in parts, each to its own URL."),
|
|
47
|
+
uploadId: z.string().describe("R2's id for the multipart upload."),
|
|
48
|
+
partSize: z.number().int().describe("The size of every part but the last, in bytes."),
|
|
49
|
+
parts: z.array(UploadPartTargetResponse).describe("Every part, in order, each with its own URL.")
|
|
50
|
+
}).describe("A multipart upload, used once the file is past the configured threshold.")]).describe("Where to send the file's bytes.");
|
|
51
|
+
/** What starting an upload returns. */
|
|
52
|
+
const UploadInitResponse = z.object({
|
|
53
|
+
object: StorageObjectResponse,
|
|
54
|
+
upload: UploadTargetResponse
|
|
55
|
+
}).describe("The upload was started: the pending file's record, and where its bytes go.");
|
|
56
|
+
/** One page of the caller's files. */
|
|
57
|
+
const ObjectListResponse = z.object({
|
|
58
|
+
objects: z.array(StorageObjectResponse).describe("The caller's files on this page, ordered by logical path."),
|
|
59
|
+
cursor: z.string().optional().describe("Pass this back as `cursor` to read the next page. Absent on the last page.")
|
|
60
|
+
}).describe("One page of the caller's files.");
|
|
61
|
+
/** Where a resuming client stands. */
|
|
62
|
+
const UploadPartsResponse = z.object({
|
|
63
|
+
uploadId: z.string().describe("R2's id for the multipart upload."),
|
|
64
|
+
partSize: z.number().int().describe("The size of every part but the last, in bytes."),
|
|
65
|
+
partCount: z.number().int().describe("How many parts the upload has in all."),
|
|
66
|
+
uploaded: z.array(UploadedPart).describe("The parts R2 already holds. Do not send these again."),
|
|
67
|
+
missing: z.array(UploadPartTargetResponse).describe("The parts still to send, each with a freshly presigned URL.")
|
|
68
|
+
}).describe("A multipart upload's progress: what R2 holds, and a live URL for every part it does not.");
|
|
69
|
+
/** A presigned direct-download URL. */
|
|
70
|
+
const PresignedUrlResponse = z.object({
|
|
71
|
+
url: z.string().describe("A presigned GET for the file's bytes. Anyone holding it can read them until it lapses."),
|
|
72
|
+
expiresInSeconds: z.number().int().describe("How long the URL works, in seconds from now.")
|
|
73
|
+
}).describe("A short-lived direct-download URL that bypasses the Worker.");
|
|
74
|
+
/** What deleting a file returns. */
|
|
75
|
+
const ObjectDeletedResponse = z.object({
|
|
76
|
+
id: z.string().describe("The id of the file that was deleted."),
|
|
77
|
+
deleted: z.literal(true).describe("Always true: the file, its record and its share links are gone.")
|
|
78
|
+
}).describe("The file was deleted.");
|
|
79
|
+
/** A minted share link. */
|
|
80
|
+
const ShareResponse = z.object({
|
|
81
|
+
token: z.string().describe("The share token. The link is the share path followed by this, and it is the credential."),
|
|
82
|
+
objectId: z.string().describe("The id of the file the link reads."),
|
|
83
|
+
expiresAt: z.iso.datetime().nullable().describe("When the link stops working, ISO-8601, or null when it never expires."),
|
|
84
|
+
createdAt: z.iso.datetime().describe("When the link was minted, ISO-8601.")
|
|
85
|
+
}).describe("A revocable share link for one file.");
|
|
86
|
+
/** What revoking a share link returns. */
|
|
87
|
+
const ShareRevokedResponse = z.object({
|
|
88
|
+
token: z.string().describe("The share token that was revoked."),
|
|
89
|
+
revokedAt: z.iso.datetime().describe("When the link was first revoked, ISO-8601. Revoking again keeps this time.")
|
|
90
|
+
}).describe("The share link was revoked.");
|
|
91
|
+
//#endregion
|
|
92
|
+
export { ObjectDeletedResponse, ObjectListResponse, PresignedUrlResponse, ShareResponse, ShareRevokedResponse, StorageObjectResponse, UploadInitResponse, UploadPartTargetResponse, UploadPartsResponse, UploadTargetResponse };
|
package/dist/http/routes.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { type PermissionHook } from "@pithy-sh/core/src/access/access";
|
|
3
4
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
4
5
|
import type { Context, Hono } from "hono";
|
|
5
6
|
import type { StorageConfig } from "../config/config";
|
|
@@ -9,8 +10,10 @@ import { type HandlerDeps } from "./handlers";
|
|
|
9
10
|
*
|
|
10
11
|
* POST /storage → start an upload (bearer | session)
|
|
11
12
|
* json: CreateUploadInput
|
|
12
|
-
* GET /storage → list
|
|
13
|
+
* GET /storage → list the files you may see (bearer | session)
|
|
13
14
|
* query: ListObjectsQuery
|
|
15
|
+
* GET /storage/admin/usage → files and bytes held (control-plane, storage:usage:read)
|
|
16
|
+
* query: UsageQuery
|
|
14
17
|
* DELETE /storage/shares/:token → revoke a share (bearer | session, owner-scoped)
|
|
15
18
|
* param: ShareTokenParam
|
|
16
19
|
* POST /storage/:id/complete → finalize a multipart (bearer | session, owner-scoped)
|
|
@@ -26,7 +29,7 @@ import { type HandlerDeps } from "./handlers";
|
|
|
26
29
|
* GET /storage/:id/url → presigned direct URL (bearer | session, owner-or-public)
|
|
27
30
|
* param: ObjectIdParam
|
|
28
31
|
* GET /storage/:id → stream the bytes (public when `visibility: 'public'`,
|
|
29
|
-
* otherwise bearer | session +
|
|
32
|
+
* otherwise bearer | session + readable)
|
|
30
33
|
* param: ObjectIdParam, query: ObjectReadQuery
|
|
31
34
|
* HEAD /storage/:id → metadata only (bearer | session, owner-scoped)
|
|
32
35
|
* param: ObjectIdParam
|
|
@@ -42,6 +45,12 @@ import { type HandlerDeps } from "./handlers";
|
|
|
42
45
|
* /storage/:id/abort` carries no json validator because it reads no body: adding one would 400 the
|
|
43
46
|
* bodyless POST every client sends today.
|
|
44
47
|
*
|
|
48
|
+
* **"Owner-scoped" above means the access rules, not the owner alone.** Every route reads a file only if its
|
|
49
|
+
* visibility admits the caller — its owner acting for its organization, any member for `organization`,
|
|
50
|
+
* anyone for `public` — and changes one only for its owner or a role holding `storage:manage` in its
|
|
51
|
+
* organization, with the adopter's permission hook asked about both. A file the caller may not read is
|
|
52
|
+
* not found, never forbidden (`handlers.ts`).
|
|
53
|
+
*
|
|
45
54
|
* `GET /storage/:id` is the one route with two strategies, because a public file must be readable by
|
|
46
55
|
* someone with no session at all. It is therefore **not** wrapped in {@link requireAuth}: the guard
|
|
47
56
|
* would deny before the handler could see that the object is public. Authorization happens inside the
|
|
@@ -62,6 +71,8 @@ export interface StorageRoutesOptions {
|
|
|
62
71
|
basePath?: string;
|
|
63
72
|
/** Where share fetches mount. Defaults to `/s` — short, because the whole URL gets pasted around. */
|
|
64
73
|
sharePath?: string;
|
|
74
|
+
/** The adopter's permission hook: allow, deny, or the default rules, asked on every file read and write. */
|
|
75
|
+
permission?: PermissionHook;
|
|
65
76
|
/** Test seam: resolve handler deps from the request. Defaults to the env-based resolver. */
|
|
66
77
|
resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
|
|
67
78
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAErF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAO7E,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAMtD,OAAO,EAML,KAAK,WAAW,EASjB,MAAM,YAAY,CAAC;AAgCpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4GAA4G;IAC5G,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,4FAA4F;IAC5F,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAClE;AAuFD,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA6RtG"}
|
package/dist/http/routes.js
CHANGED
|
@@ -1,15 +1,21 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { storageDatabase } from "../data/tables.js";
|
|
3
|
+
import { STORAGE_OBJECTS_TABLE, storageDatabase } from "../data/tables.js";
|
|
4
|
+
import { abortUpload, completeUpload, copyObject, createShare, deleteObject, initUpload, listObjects, listUploadParts, presignObject, readableObject, resolveShare, revokeShare, updateObject } from "./handlers.js";
|
|
4
5
|
import { STORAGE_R2_SECRET } from "../secret/registry.js";
|
|
5
6
|
import { objectStore } from "../object/store.js";
|
|
7
|
+
import { storageCeiling } from "../quota/ceiling.js";
|
|
6
8
|
import { requireAuth } from "./guard.js";
|
|
7
|
-
import {
|
|
9
|
+
import { ObjectDeletedResponse, ObjectListResponse, PresignedUrlResponse, ShareResponse, ShareRevokedResponse, StorageObjectResponse, UploadInitResponse, UploadPartsResponse } from "./responses.js";
|
|
8
10
|
import { CompleteUploadInput, CopyObjectInput, CreateShareInput, CreateUploadInput, ListObjectsQuery, ObjectIdParam, ObjectReadQuery, ShareTokenParam, UpdateObjectInput } from "./schemas.js";
|
|
11
|
+
import { STORAGE_USAGE_READ_SCOPE } from "./scopes.js";
|
|
9
12
|
import { parseConditions, parseRangeHeader, rangeNotSatisfiable, serveMetadata, serveObject, toObjectRange } from "./serve.js";
|
|
10
13
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
11
|
-
import {
|
|
12
|
-
import {
|
|
14
|
+
import { accessCaller } from "@pithy-sh/core/src/access/access";
|
|
15
|
+
import { UsageQuery, UsageResponse, usageRollup } from "@pithy-sh/core/src/access/usage";
|
|
16
|
+
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
17
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
18
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
13
19
|
//#region src/http/routes.ts
|
|
14
20
|
/**
|
|
15
21
|
* Read one binding, or fail with a message naming the binding and how to add it. A `?.` here would
|
|
@@ -25,7 +31,7 @@ function requireBinding(env, name, kind) {
|
|
|
25
31
|
return value;
|
|
26
32
|
}
|
|
27
33
|
/** Build the default per-request dependency resolver from the resolved config. */
|
|
28
|
-
function defaultResolveDeps(config) {
|
|
34
|
+
function defaultResolveDeps(config, permission) {
|
|
29
35
|
return async (c) => {
|
|
30
36
|
const env = c.env;
|
|
31
37
|
const bucket = requireBinding(env, "STORAGE_BUCKET", "an R2 bucket");
|
|
@@ -38,24 +44,49 @@ function defaultResolveDeps(config) {
|
|
|
38
44
|
secretName: STORAGE_R2_SECRET
|
|
39
45
|
}),
|
|
40
46
|
config,
|
|
41
|
-
|
|
47
|
+
caller: await accessCaller(c.var),
|
|
48
|
+
...permission ? { permission } : {},
|
|
49
|
+
env: c.env,
|
|
42
50
|
newId: () => crypto.randomUUID(),
|
|
43
51
|
newToken: () => shareToken(),
|
|
44
|
-
now: () => /* @__PURE__ */ new Date()
|
|
52
|
+
now: () => /* @__PURE__ */ new Date(),
|
|
53
|
+
quotaLimit: memoized(() => storageCeiling(c, config))
|
|
45
54
|
};
|
|
46
55
|
};
|
|
47
56
|
}
|
|
57
|
+
/** One computation per request, however many writes ask for it. */
|
|
58
|
+
function memoized(compute) {
|
|
59
|
+
let pending;
|
|
60
|
+
return () => {
|
|
61
|
+
pending ??= compute();
|
|
62
|
+
return pending;
|
|
63
|
+
};
|
|
64
|
+
}
|
|
48
65
|
/** A 256-bit share token, base64url-encoded and unpadded so it is safe in a path segment. */
|
|
49
66
|
function shareToken() {
|
|
50
67
|
const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32));
|
|
51
68
|
const binary = String.fromCharCode(...bytes);
|
|
52
69
|
return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
|
53
70
|
}
|
|
71
|
+
/** `requireAuth()` lets either a bearer token or a session through. */
|
|
72
|
+
const AUTHENTICATED = ["bearer", "session"];
|
|
73
|
+
/** What a byte read can answer: the whole file, the range asked for, or nothing new since the caller's copy. */
|
|
74
|
+
const BYTE_RESPONSES = {
|
|
75
|
+
200: {
|
|
76
|
+
description: "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.",
|
|
77
|
+
contentType: "application/octet-stream"
|
|
78
|
+
},
|
|
79
|
+
206: {
|
|
80
|
+
description: "The byte range the `Range` header asked for.",
|
|
81
|
+
contentType: "application/octet-stream"
|
|
82
|
+
},
|
|
83
|
+
304: { description: "The caller's copy matches `If-None-Match`. No body." }
|
|
84
|
+
};
|
|
54
85
|
/** Register the storage sub-router. Returned as the capability's `routes` hook. */
|
|
55
86
|
function registerStorageRoutes(options) {
|
|
56
87
|
const base = options.basePath ?? "/storage";
|
|
57
88
|
const share = options.sharePath ?? "/s";
|
|
58
|
-
const resolve = options.resolveDeps ?? defaultResolveDeps(options.config);
|
|
89
|
+
const resolve = options.resolveDeps ?? defaultResolveDeps(options.config, options.permission);
|
|
59
90
|
/** Stream one object, honoring `Range` and `If-None-Match`. Shared by the id route and the share route. */
|
|
60
91
|
const stream = async (c, deps, object, download) => {
|
|
61
92
|
const requested = parseRangeHeader(c.req.header("range"), object.size);
|
|
@@ -75,39 +106,106 @@ function registerStorageRoutes(options) {
|
|
|
75
106
|
});
|
|
76
107
|
};
|
|
77
108
|
return (app) => {
|
|
78
|
-
app.post(base,
|
|
109
|
+
app.post(base, describeRoute({
|
|
110
|
+
summary: "Start an upload.",
|
|
111
|
+
description: "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.",
|
|
112
|
+
verification: AUTHENTICATED,
|
|
113
|
+
responses: { 201: UploadInitResponse }
|
|
114
|
+
}), requireAuth(), validate("json", CreateUploadInput), async (c) => {
|
|
79
115
|
return c.json(await initUpload(await resolve(c), c.req.valid("json")), 201);
|
|
80
116
|
});
|
|
81
|
-
app.get(base,
|
|
117
|
+
app.get(base, describeRoute({
|
|
118
|
+
summary: "List the files the caller may see.",
|
|
119
|
+
description: "The caller's own files and their organization's, by path. `includePublic=true` adds every public file.",
|
|
120
|
+
verification: AUTHENTICATED,
|
|
121
|
+
responses: { 200: ObjectListResponse }
|
|
122
|
+
}), requireAuth(), validate("query", ListObjectsQuery), async (c) => {
|
|
82
123
|
return c.json(await listObjects(await resolve(c), c.req.valid("query")));
|
|
83
124
|
});
|
|
84
|
-
app.
|
|
125
|
+
app.get(`${base}/admin/usage`, describeRoute({
|
|
126
|
+
summary: "Count files held, per organization or per owner.",
|
|
127
|
+
description: "Stored files and their bytes. A per-owner read names its organization, so no figure ever spans two.",
|
|
128
|
+
verification: "control-plane",
|
|
129
|
+
scopes: [STORAGE_USAGE_READ_SCOPE],
|
|
130
|
+
responses: { 200: UsageResponse }
|
|
131
|
+
}), requireControlPlane(STORAGE_USAGE_READ_SCOPE), validate("query", UsageQuery), async (c) => {
|
|
132
|
+
const d1 = requireBinding(c.env, "DB", "a D1 database");
|
|
133
|
+
const db = storageDatabase(d1);
|
|
134
|
+
return c.json(await usageRollup(db, STORAGE_OBJECTS_TABLE, c.req.valid("query")));
|
|
135
|
+
});
|
|
136
|
+
app.delete(`${base}/shares/:token`, describeRoute({
|
|
137
|
+
summary: "Revoke a share link.",
|
|
138
|
+
description: "Takes effect on the next fetch. Revoking twice is a no-op that keeps the first time.",
|
|
139
|
+
verification: AUTHENTICATED,
|
|
140
|
+
responses: { 200: ShareRevokedResponse }
|
|
141
|
+
}), requireAuth(), validate("param", ShareTokenParam), async (c) => {
|
|
85
142
|
return c.json(await revokeShare(await resolve(c), c.req.valid("param").token));
|
|
86
143
|
});
|
|
87
|
-
app.post(`${base}/:id/complete`,
|
|
144
|
+
app.post(`${base}/:id/complete`, describeRoute({
|
|
145
|
+
summary: "Finish an upload.",
|
|
146
|
+
description: "Assembles a multipart upload, then confirms the bytes against R2. Completing a stored file again answers with it unchanged.",
|
|
147
|
+
verification: AUTHENTICATED,
|
|
148
|
+
responses: { 200: StorageObjectResponse }
|
|
149
|
+
}), requireAuth(), validate("param", ObjectIdParam), validate("json", CompleteUploadInput), async (c) => {
|
|
88
150
|
return c.json(await completeUpload(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
|
|
89
151
|
});
|
|
90
|
-
app.post(`${base}/:id/abort`,
|
|
152
|
+
app.post(`${base}/:id/abort`, describeRoute({
|
|
153
|
+
summary: "Abandon an upload.",
|
|
154
|
+
description: "Discards whatever R2 holds for the upload. The record stays, marked failed.",
|
|
155
|
+
verification: AUTHENTICATED,
|
|
156
|
+
responses: { 200: StorageObjectResponse }
|
|
157
|
+
}), requireAuth(), validate("param", ObjectIdParam), async (c) => {
|
|
91
158
|
return c.json(await abortUpload(await resolve(c), c.req.valid("param").id));
|
|
92
159
|
});
|
|
93
|
-
app.get(`${base}/:id/parts`,
|
|
160
|
+
app.get(`${base}/:id/parts`, describeRoute({
|
|
161
|
+
summary: "Resume a multipart upload.",
|
|
162
|
+
verification: AUTHENTICATED,
|
|
163
|
+
responses: { 200: UploadPartsResponse }
|
|
164
|
+
}), requireAuth(), validate("param", ObjectIdParam), async (c) => {
|
|
94
165
|
return c.json(await listUploadParts(await resolve(c), c.req.valid("param").id));
|
|
95
166
|
});
|
|
96
|
-
app.post(`${base}/:id/copy`,
|
|
167
|
+
app.post(`${base}/:id/copy`, describeRoute({
|
|
168
|
+
summary: "Copy a file.",
|
|
169
|
+
description: "R2 copies the bytes. The copy is a new private file with its own id.",
|
|
170
|
+
verification: AUTHENTICATED,
|
|
171
|
+
responses: { 201: StorageObjectResponse }
|
|
172
|
+
}), requireAuth(), validate("param", ObjectIdParam), validate("json", CopyObjectInput), async (c) => {
|
|
97
173
|
return c.json(await copyObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
|
|
98
174
|
});
|
|
99
|
-
app.post(`${base}/:id/shares`,
|
|
175
|
+
app.post(`${base}/:id/shares`, describeRoute({
|
|
176
|
+
summary: "Mint a share link.",
|
|
177
|
+
verification: AUTHENTICATED,
|
|
178
|
+
responses: { 201: ShareResponse }
|
|
179
|
+
}), requireAuth(), validate("param", ObjectIdParam), validate("json", CreateShareInput), async (c) => {
|
|
100
180
|
return c.json(await createShare(await resolve(c), c.req.valid("param").id, c.req.valid("json")), 201);
|
|
101
181
|
});
|
|
102
|
-
app.get(`${base}/:id/url`,
|
|
182
|
+
app.get(`${base}/:id/url`, describeRoute({
|
|
183
|
+
summary: "Mint a direct download URL.",
|
|
184
|
+
description: "For a file the caller may read. The URL cannot be revoked, so it lapses in five minutes.",
|
|
185
|
+
verification: AUTHENTICATED,
|
|
186
|
+
responses: { 200: PresignedUrlResponse }
|
|
187
|
+
}), requireAuth(), validate("param", ObjectIdParam), async (c) => {
|
|
103
188
|
return c.json(await presignObject(await resolve(c), c.req.valid("param").id));
|
|
104
189
|
});
|
|
105
|
-
app.get(`${base}/:id`,
|
|
190
|
+
app.get(`${base}/:id`, describeRoute({
|
|
191
|
+
summary: "Read a file's bytes.",
|
|
192
|
+
description: "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`.",
|
|
193
|
+
verification: [
|
|
194
|
+
"public",
|
|
195
|
+
"bearer",
|
|
196
|
+
"session"
|
|
197
|
+
],
|
|
198
|
+
responses: BYTE_RESPONSES
|
|
199
|
+
}), validate("param", ObjectIdParam), validate("query", ObjectReadQuery), async (c) => {
|
|
106
200
|
const deps = await resolve(c);
|
|
107
201
|
const object = await readableObject(deps, c.req.valid("param").id);
|
|
108
202
|
return stream(c, deps, object, c.req.valid("query").download === "1");
|
|
109
203
|
});
|
|
110
|
-
app.on("HEAD", `${base}/:id`,
|
|
204
|
+
app.on("HEAD", `${base}/:id`, describeRoute({
|
|
205
|
+
summary: "Read a file's headers without its bytes.",
|
|
206
|
+
verification: AUTHENTICATED,
|
|
207
|
+
responses: { 200: { description: "The headers a GET would carry, with no body." } }
|
|
208
|
+
}), requireAuth(), validate("param", ObjectIdParam), async (c) => {
|
|
111
209
|
const deps = await resolve(c);
|
|
112
210
|
const object = await readableObject(deps, c.req.valid("param").id);
|
|
113
211
|
const metadata = await deps.store.head(object.key);
|
|
@@ -118,13 +216,27 @@ function registerStorageRoutes(options) {
|
|
|
118
216
|
visibility: object.visibility
|
|
119
217
|
});
|
|
120
218
|
});
|
|
121
|
-
app.patch(`${base}/:id`,
|
|
219
|
+
app.patch(`${base}/:id`, describeRoute({
|
|
220
|
+
summary: "Rename a file or change who may read it.",
|
|
221
|
+
verification: AUTHENTICATED,
|
|
222
|
+
responses: { 200: StorageObjectResponse }
|
|
223
|
+
}), requireAuth(), validate("param", ObjectIdParam), validate("json", UpdateObjectInput), async (c) => {
|
|
122
224
|
return c.json(await updateObject(await resolve(c), c.req.valid("param").id, c.req.valid("json")));
|
|
123
225
|
});
|
|
124
|
-
app.delete(`${base}/:id`,
|
|
226
|
+
app.delete(`${base}/:id`, describeRoute({
|
|
227
|
+
summary: "Delete a file.",
|
|
228
|
+
description: "Its share links go with it.",
|
|
229
|
+
verification: AUTHENTICATED,
|
|
230
|
+
responses: { 200: ObjectDeletedResponse }
|
|
231
|
+
}), requireAuth(), validate("param", ObjectIdParam), async (c) => {
|
|
125
232
|
return c.json(await deleteObject(await resolve(c), c.req.valid("param").id));
|
|
126
233
|
});
|
|
127
|
-
app.get(`${share}/:token`,
|
|
234
|
+
app.get(`${share}/:token`, describeRoute({
|
|
235
|
+
summary: "Read a file through a share link.",
|
|
236
|
+
description: "The token is the credential. A revoked or expired link answers 410. Honors `Range` and `If-None-Match`.",
|
|
237
|
+
verification: "public",
|
|
238
|
+
responses: BYTE_RESPONSES
|
|
239
|
+
}), validate("param", ShareTokenParam), validate("query", ObjectReadQuery), async (c) => {
|
|
128
240
|
const deps = await resolve(c);
|
|
129
241
|
const object = await resolveShare(deps, c.req.valid("param").token);
|
|
130
242
|
return stream(c, deps, object, c.req.valid("query").download === "1");
|
package/dist/http/schemas.d.ts
CHANGED
|
@@ -36,6 +36,7 @@ export declare const CreateUploadInput: z.ZodObject<{
|
|
|
36
36
|
contentType: z.ZodString;
|
|
37
37
|
size: z.ZodNumber;
|
|
38
38
|
visibility: z.ZodOptional<z.ZodEnum<{
|
|
39
|
+
organization: "organization";
|
|
39
40
|
private: "private";
|
|
40
41
|
public: "public";
|
|
41
42
|
}>>;
|
|
@@ -52,6 +53,7 @@ export type CompleteUploadInput = z.output<typeof CompleteUploadInput>;
|
|
|
52
53
|
export declare const UpdateObjectInput: z.ZodObject<{
|
|
53
54
|
path: z.ZodOptional<z.ZodString>;
|
|
54
55
|
visibility: z.ZodOptional<z.ZodEnum<{
|
|
56
|
+
organization: "organization";
|
|
55
57
|
private: "private";
|
|
56
58
|
public: "public";
|
|
57
59
|
}>>;
|
|
@@ -67,6 +69,10 @@ export declare const CreateShareInput: z.ZodObject<{
|
|
|
67
69
|
export type CreateShareInput = z.output<typeof CreateShareInput>;
|
|
68
70
|
export declare const ListObjectsQuery: z.ZodObject<{
|
|
69
71
|
prefix: z.ZodOptional<z.ZodString>;
|
|
72
|
+
includePublic: z.ZodOptional<z.ZodEnum<{
|
|
73
|
+
false: "false";
|
|
74
|
+
true: "true";
|
|
75
|
+
}>>;
|
|
70
76
|
cursor: z.ZodOptional<z.ZodString>;
|
|
71
77
|
limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
|
|
72
78
|
}, z.core.$strip>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkDxB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;iBAQsC,CAAC;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,eAAe;;iBAQiC,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;iBAQiE,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,eAAO,MAAM,iBAAiB
|
|
1
|
+
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkDxB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;iBAQsC,CAAC;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,eAAe;;iBAQiC,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;iBAQiE,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,eAAO,MAAM,iBAAiB;;;;;;;;;iBAqBuE,CAAC;AACtG,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,eAAO,MAAM,mBAAmB;;;;;;iBAgBqE,CAAC;AACtG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,eAAO,MAAM,iBAAiB;;;;;;;iBAmB1B,CAAC;AACL,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,eAAO,MAAM,eAAe;;iBAE8D,CAAC;AAC3F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAK/D,eAAO,MAAM,gBAAgB;;iBAYwC,CAAC;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,eAAO,MAAM,gBAAgB;;;;;;;;iBA0ByF,CAAC;AACvH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
|
package/dist/http/schemas.js
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { StorageVisibility } from "../data/storageObject.js";
|
|
4
3
|
import { ReportedPart } from "../object/multipart.js";
|
|
4
|
+
import { StorageVisibility } from "../data/storageObject.js";
|
|
5
5
|
import { MAX_OBJECT_KEY_BYTES } from "../object/key.js";
|
|
6
6
|
import { z } from "zod";
|
|
7
7
|
//#region src/http/schemas.ts
|
|
8
8
|
/**
|
|
9
9
|
* The request schemas for the storage routes. Every path parameter, query string and body is parsed
|
|
10
10
|
* here before a handler sees it (CLAUDE.md §Zod: validate at every boundary), declared on the route
|
|
11
|
-
* line with `
|
|
11
|
+
* line with `validate(target, Schema)` — so reading `routes.ts` tells you what a
|
|
12
12
|
* route accepts without opening a handler. A failure maps to `validation/invalid_input` through
|
|
13
13
|
* `fromZodError`.
|
|
14
14
|
*
|
|
@@ -65,7 +65,7 @@ const CreateUploadInput = z.object({
|
|
|
65
65
|
path: logicalPath,
|
|
66
66
|
contentType: z.string().min(1).max(255).describe("The file's MIME type, as you intend it. A declaration, not a constraint: a presigned PUT cannot sign a content type, so completion replaces this with the type R2 actually stored."),
|
|
67
67
|
size: z.number().int().nonnegative().describe("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."),
|
|
68
|
-
visibility: StorageVisibility.optional().describe("Who may read the file once stored. Omitted takes the configured default
|
|
68
|
+
visibility: StorageVisibility.optional().describe("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.")
|
|
69
69
|
}).describe("A request to start an upload — what the file is called, what it is, and how big it is.");
|
|
70
70
|
const CompleteUploadInput = z.object({
|
|
71
71
|
parts: z.array(ReportedPart).default([]).describe("Every part's number and the ETag R2 answered its PUT with. Empty for a single-PUT upload, which has no parts to assemble."),
|
|
@@ -73,7 +73,7 @@ const CompleteUploadInput = z.object({
|
|
|
73
73
|
}).describe("A request to finalize an upload — the parts to assemble, and optionally what was sent.");
|
|
74
74
|
const UpdateObjectInput = z.object({
|
|
75
75
|
path: logicalPath.optional(),
|
|
76
|
-
visibility: StorageVisibility.optional().describe("Change who may read the file. Takes effect on the next request.")
|
|
76
|
+
visibility: StorageVisibility.optional().describe("Change who may read the file. Takes effect on the next request. A level outside `visibility.allowed` is refused.")
|
|
77
77
|
}).describe("A rename, a visibility change, or both. At least one field must be present.").check((ctx) => {
|
|
78
78
|
if (ctx.value.path === void 0 && ctx.value.visibility === void 0) ctx.issues.push({
|
|
79
79
|
code: "custom",
|
|
@@ -85,9 +85,10 @@ const UpdateObjectInput = z.object({
|
|
|
85
85
|
const CopyObjectInput = z.object({ path: logicalPath }).describe("A server-side copy — the new file's logical path. The bytes never leave R2.");
|
|
86
86
|
const CreateShareInput = z.object({ expiresInSeconds: z.number().int().positive().max(31536e3).optional().describe("How long the link works, in seconds. Omitted never expires — revocation is then the only way to end it, which is a deliberate choice rather than a default.") }).describe("A request to mint a revocable share link for one file.");
|
|
87
87
|
const ListObjectsQuery = z.object({
|
|
88
|
-
prefix: z.string().max(MAX_OBJECT_KEY_BYTES).optional().describe("Only files whose logical path starts with this. Omitted lists everything you
|
|
88
|
+
prefix: z.string().max(MAX_OBJECT_KEY_BYTES).optional().describe("Only files whose logical path starts with this. Omitted lists everything you may see."),
|
|
89
|
+
includePublic: z.enum(["true", "false"]).optional().describe("`true` adds every public file to your own and your organization's. Off by default, so nobody receives what they did not ask for."),
|
|
89
90
|
cursor: z.string().min(1).optional().describe("The `cursor` a previous page returned. Opaque — pass it back unchanged to advance."),
|
|
90
91
|
limit: z.coerce.number().int().min(1).max(100).optional().describe("Files per page. Defaults to 50, capped at 100 so one request cannot scan an entire owner's files.")
|
|
91
|
-
}).describe("Query parameters for the
|
|
92
|
+
}).describe("Query parameters for the file listing: your own files, your organization's, and public ones on request.");
|
|
92
93
|
//#endregion
|
|
93
94
|
export { CompleteUploadInput, CopyObjectInput, CreateShareInput, CreateUploadInput, ListObjectsQuery, ObjectIdParam, ObjectReadQuery, ShareTokenParam, UpdateObjectInput };
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
|
|
4
|
+
import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
|
|
5
|
+
/**
|
|
6
|
+
* Storage's control-plane scope, and the admin surface a manifest advertises.
|
|
7
|
+
*
|
|
8
|
+
* **This module imports types and nothing else**, because a management client in a browser reads the scope
|
|
9
|
+
* names to render what a connection may do, and `tooling/browser-scopes` compiles every scope the kit
|
|
10
|
+
* declares against the DOM lib alone.
|
|
11
|
+
*
|
|
12
|
+
* **One scope, a read, and it is numbers.** Files and bytes held, per owner and per organization — never a
|
|
13
|
+
* path, a key or a link. A per-owner figure is always one organization's, so a tool holding this scope
|
|
14
|
+
* still cannot learn that a person holds an account in two of them.
|
|
15
|
+
*/
|
|
16
|
+
/** Files and bytes held, per organization and per owner within one. */
|
|
17
|
+
export declare const STORAGE_USAGE_READ_SCOPE: ControlPlaneScope;
|
|
18
|
+
/** Every control-plane scope this capability defines. */
|
|
19
|
+
export declare const STORAGE_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
|
|
20
|
+
/**
|
|
21
|
+
* The admin routes this capability advertises on `GET /control-plane/manifest`, built from the **resolved**
|
|
22
|
+
* mount path, never the default.
|
|
23
|
+
*/
|
|
24
|
+
export declare function storageAdminRoutes(basePath: string): AdminRoute[];
|
|
25
|
+
//# sourceMappingURL=scopes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/http/scopes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF,yDAAyD;AACzD,eAAO,MAAM,4BAA4B,EAAE,SAAS,iBAAiB,EAA+B,CAAC;AAErG;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAUjE"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
//#region src/http/scopes.ts
|
|
4
|
+
/**
|
|
5
|
+
* Storage's control-plane scope, and the admin surface a manifest advertises.
|
|
6
|
+
*
|
|
7
|
+
* **This module imports types and nothing else**, because a management client in a browser reads the scope
|
|
8
|
+
* names to render what a connection may do, and `tooling/browser-scopes` compiles every scope the kit
|
|
9
|
+
* declares against the DOM lib alone.
|
|
10
|
+
*
|
|
11
|
+
* **One scope, a read, and it is numbers.** Files and bytes held, per owner and per organization — never a
|
|
12
|
+
* path, a key or a link. A per-owner figure is always one organization's, so a tool holding this scope
|
|
13
|
+
* still cannot learn that a person holds an account in two of them.
|
|
14
|
+
*/
|
|
15
|
+
/** Files and bytes held, per organization and per owner within one. */
|
|
16
|
+
const STORAGE_USAGE_READ_SCOPE = "storage:usage:read";
|
|
17
|
+
/** Every control-plane scope this capability defines. */
|
|
18
|
+
const STORAGE_CONTROL_PLANE_SCOPES = [STORAGE_USAGE_READ_SCOPE];
|
|
19
|
+
/**
|
|
20
|
+
* The admin routes this capability advertises on `GET /control-plane/manifest`, built from the **resolved**
|
|
21
|
+
* mount path, never the default.
|
|
22
|
+
*/
|
|
23
|
+
function storageAdminRoutes(basePath) {
|
|
24
|
+
return [{
|
|
25
|
+
method: "GET",
|
|
26
|
+
path: `${basePath}/admin/usage`,
|
|
27
|
+
scope: STORAGE_USAGE_READ_SCOPE,
|
|
28
|
+
summary: "Files and bytes held, per organization or per owner within one organization. Never across organizations."
|
|
29
|
+
}];
|
|
30
|
+
}
|
|
31
|
+
//#endregion
|
|
32
|
+
export { STORAGE_CONTROL_PLANE_SCOPES, STORAGE_USAGE_READ_SCOPE, storageAdminRoutes };
|
package/dist/http/serve.d.ts
CHANGED
|
@@ -86,8 +86,11 @@ export interface ServeOptions {
|
|
|
86
86
|
metadata: ObjectMetadata;
|
|
87
87
|
/** The logical path — its last segment becomes the download filename. */
|
|
88
88
|
path: string;
|
|
89
|
-
/**
|
|
90
|
-
|
|
89
|
+
/**
|
|
90
|
+
* Who may read the object, which decides whether a shared cache may hold it: only a public object may
|
|
91
|
+
* be cached publicly, so an organization's file is as uncacheable as a private one.
|
|
92
|
+
*/
|
|
93
|
+
visibility: "private" | "organization" | "public";
|
|
91
94
|
/** Serve as a download (`attachment`) rather than inline. */
|
|
92
95
|
download?: boolean;
|
|
93
96
|
}
|
package/dist/http/serve.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/http/serve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,iEAAiE;AACjE,MAAM,MAAM,YAAY;AACtB,qDAAqD;AACnD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,mDAAmD;GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACnD,kEAAkE;GAChE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAK9B;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAwBrG;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAQpG;AAQD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,EAAE,cAAc,CAAC;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb
|
|
1
|
+
{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/http/serve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,iEAAiE;AACjE,MAAM,MAAM,YAAY;AACtB,qDAAqD;AACnD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,mDAAmD;GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACnD,kEAAkE;GAChE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAK9B;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAwBrG;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAQpG;AAQD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,EAAE,cAAc,CAAC;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,UAAU,EAAE,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC;IAClD,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,wDAAwD;IACxD,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAClD;AAmGD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,CAsBvE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAI7D;AAED,0GAA0G;AAC1G,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE1D"}
|
package/dist/index.d.ts
CHANGED
|
@@ -14,6 +14,8 @@ export { maxObjectBytes, StorageConfig, type StorageConfigInput, StorageQuota }
|
|
|
14
14
|
export { StorageShare } from "./data/share";
|
|
15
15
|
export { StorageObject, StorageObjectStatus, StorageVisibility } from "./data/storageObject";
|
|
16
16
|
export { STORAGE_OBJECTS_TABLE, STORAGE_SHARES_TABLE, type StorageDatabase, storageDatabase } from "./data/tables";
|
|
17
|
+
export { STORAGE_MANAGE_POWER } from "./http/handlers";
|
|
18
|
+
export { STORAGE_USAGE_READ_SCOPE } from "./http/scopes";
|
|
17
19
|
export { deriveObjectKey, isDerivedObjectKey, OBJECT_KEY_PREFIX } from "./object/key";
|
|
18
20
|
export { collectParts, MultipartPlan, needsMultipart, PartPlan, planMultipart, ReportedPart } from "./object/multipart";
|
|
19
21
|
export { ObjectListing, ObjectMetadata, type ObjectStore, type ObjectStoreOptions, objectStore, type PresignedObjects, } from "./object/store";
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxH,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxH,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { StorageObject, StorageObjectStatus, StorageVisibility } from "./data/storageObject.js";
|
|
4
3
|
import { MultipartPlan, PartPlan, ReportedPart, collectParts, needsMultipart, planMultipart } from "./object/multipart.js";
|
|
5
4
|
import { StorageConfig, StorageQuota, maxObjectBytes } from "./config/config.js";
|
|
6
5
|
import { StorageShare } from "./data/share.js";
|
|
6
|
+
import { StorageObject, StorageObjectStatus, StorageVisibility } from "./data/storageObject.js";
|
|
7
7
|
import { STORAGE_OBJECTS_TABLE, STORAGE_SHARES_TABLE, storageDatabase } from "./data/tables.js";
|
|
8
|
+
import { OBJECT_KEY_PREFIX, deriveObjectKey, isDerivedObjectKey } from "./object/key.js";
|
|
9
|
+
import { STORAGE_MANAGE_POWER } from "./http/handlers.js";
|
|
8
10
|
import { R2StorageCredentials, STORAGE_R2_SECRET, r2CredentialsRegistry, storageSecretsRegistry } from "./secret/registry.js";
|
|
9
11
|
import { ObjectListing, ObjectMetadata, objectStore } from "./object/store.js";
|
|
10
|
-
import {
|
|
12
|
+
import { STORAGE_USAGE_READ_SCOPE } from "./http/scopes.js";
|
|
11
13
|
import { STORAGE_CAPABILITY, StorageSweepParams, storageWorkflows } from "./workflows/specs.js";
|
|
12
14
|
import { STORAGE_MIGRATION_ORDER, isStorageCapability, storage } from "./capability.js";
|
|
13
15
|
import { sweepStorage } from "./workflows/sweep.js";
|
|
14
|
-
export { MultipartPlan, OBJECT_KEY_PREFIX, ObjectListing, ObjectMetadata, PartPlan, R2StorageCredentials, ReportedPart, STORAGE_CAPABILITY, STORAGE_MIGRATION_ORDER, STORAGE_OBJECTS_TABLE, STORAGE_R2_SECRET, STORAGE_SHARES_TABLE, StorageConfig, StorageObject, StorageObjectStatus, StorageQuota, StorageShare, StorageSweepParams, StorageVisibility, collectParts, deriveObjectKey, isDerivedObjectKey, isStorageCapability, maxObjectBytes, needsMultipart, objectStore, planMultipart, r2CredentialsRegistry, storage, storageDatabase, storageSecretsRegistry, storageWorkflows, sweepStorage };
|
|
16
|
+
export { MultipartPlan, OBJECT_KEY_PREFIX, ObjectListing, ObjectMetadata, PartPlan, R2StorageCredentials, ReportedPart, STORAGE_CAPABILITY, STORAGE_MANAGE_POWER, STORAGE_MIGRATION_ORDER, STORAGE_OBJECTS_TABLE, STORAGE_R2_SECRET, STORAGE_SHARES_TABLE, STORAGE_USAGE_READ_SCOPE, StorageConfig, StorageObject, StorageObjectStatus, StorageQuota, StorageShare, StorageSweepParams, StorageVisibility, collectParts, deriveObjectKey, isDerivedObjectKey, isStorageCapability, maxObjectBytes, needsMultipart, objectStore, planMultipart, r2CredentialsRegistry, storage, storageDatabase, storageSecretsRegistry, storageWorkflows, sweepStorage };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"0002_ownership.d.ts","sourceRoot":"","sources":["../../src/migrations/0002_ownership.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAgKlD,eAAO,MAAM,sBAAsB,EAAE,SAWpC,CAAC"}
|