@pithy-sh/storage 0.3.0 → 0.5.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.d.ts +4 -3
- package/dist/error/errors.d.ts.map +1 -1
- package/dist/error/errors.js +2 -2
- package/dist/http/handlers.d.ts +45 -14
- package/dist/http/handlers.d.ts.map +1 -1
- package/dist/http/handlers.js +169 -66
- package/dist/http/responses.d.ts +6 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +2 -1
- package/dist/http/routes.d.ts +13 -2
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +37 -9
- package/dist/http/schemas.d.ts +6 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +6 -5
- 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 +2 -1
- package/dist/object/cloudflare.d.ts.map +1 -1
- package/dist/object/cloudflare.js +2 -2
- 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.js +1 -1
- package/package.json +5 -5
- 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 +6 -5
- package/src/http/handlers.ts +212 -79
- package/src/http/responses.ts +13 -1
- package/src/http/routes.ts +64 -10
- package/src/http/schemas.ts +10 -4
- 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 +2 -2
- 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
package/src/capability.ts
CHANGED
|
@@ -1,17 +1,24 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import type { PermissionHook } from "@pithy-sh/core/src/access/access";
|
|
5
|
+
import { recordsOutsidePolicy } from "@pithy-sh/core/src/access/policyCheck";
|
|
4
6
|
import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
|
|
5
7
|
import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
8
|
+
import { allSettings } from "@pithy-sh/core/src/capability/settings";
|
|
6
9
|
import type { DatabaseSpecMap } from "@pithy-sh/core/src/data/databases";
|
|
7
10
|
import type { KvNamespaceSpecMap } from "@pithy-sh/core/src/kv/namespaces";
|
|
8
11
|
import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
|
|
9
12
|
import type { Migration } from "kysely/migration";
|
|
10
|
-
import { StorageConfig, type StorageConfigInput } from "./config/config";
|
|
13
|
+
import { refuseRenamedStorageOptions, StorageConfig, type StorageConfigInput } from "./config/config";
|
|
11
14
|
import { storageTables } from "./data/tables";
|
|
15
|
+
import { STORAGE_MANAGE_POWER } from "./http/handlers";
|
|
12
16
|
import { registerStorageRoutes } from "./http/routes";
|
|
17
|
+
import { storageAdminRoutes } from "./http/scopes";
|
|
13
18
|
import { storage_0001_objects } from "./migrations/0001_objects";
|
|
14
|
-
import {
|
|
19
|
+
import { storage_0002_ownership } from "./migrations/0002_ownership";
|
|
20
|
+
import { bundleTokenCheck } from "./secret/bundleToken";
|
|
21
|
+
import { STORAGE_BUCKET_BINDING, STORAGE_R2_SECRET, storageSecretsRegistry } from "./secret/registry";
|
|
15
22
|
import { storageExampleSeed } from "./seeds/example";
|
|
16
23
|
import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated";
|
|
17
24
|
import { storageWorkflows } from "./workflows/specs";
|
|
@@ -25,6 +32,12 @@ export const STORAGE_MIGRATION_ORDER = 800;
|
|
|
25
32
|
export type StorageOptions = StorageConfigInput & {
|
|
26
33
|
/** Mount the object routes somewhere other than `/storage`. */
|
|
27
34
|
basePath?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Asked on every read and write of a stored file: `allow`, `deny`, or `default` for the rules. Sharing a
|
|
37
|
+
* file with one person is an allow; a legal hold is a deny. No hook is the rules, unchanged. Share
|
|
38
|
+
* links are unchanged by it, and usage rollups keep their non-disclosure rule whatever it answers.
|
|
39
|
+
*/
|
|
40
|
+
permission?: PermissionHook;
|
|
28
41
|
/** Mount share fetches somewhere other than `/s`. Short by default — the whole URL gets pasted around. */
|
|
29
42
|
sharePath?: string;
|
|
30
43
|
};
|
|
@@ -51,17 +64,25 @@ export interface StorageCapability
|
|
|
51
64
|
*
|
|
52
65
|
* `dependsOn: ["secrets"]` is real: the R2 credential bundle is read through the aggregated registry
|
|
53
66
|
* at startup, so a project composing storage without `@pithy-sh/secrets` must fail at assembly, not at
|
|
54
|
-
* the first presign. Auth is *not* listed — it is a seam. Ownership
|
|
55
|
-
*
|
|
56
|
-
*
|
|
67
|
+
* the first presign. Auth is *not* listed — it is a seam. Ownership reads `c.var.auth.userId`, so without
|
|
68
|
+
* `@pithy-sh/auth` every write denies rather than opens, which is the right failure and needs no
|
|
69
|
+
* dependency edge. Tenancy is a seam too: the organization a file belongs to comes from core's
|
|
70
|
+
* acting-organization resolver, so `@pithy-sh/organization` is optional, never imported, and declared on
|
|
71
|
+
* `powers` only through `storage:manage`. Both belong in the manifest's `optionalCapabilities`.
|
|
57
72
|
*/
|
|
58
73
|
export function storage(options: StorageOptions = {}): StorageCapability {
|
|
59
|
-
const { basePath, sharePath, ...configInput } = options;
|
|
74
|
+
const { basePath, sharePath, permission, ...configInput } = options;
|
|
75
|
+
// A renamed option is refused by name before anything parses, so it cannot quietly mean the default.
|
|
76
|
+
refuseRenamedStorageOptions(configInput as Record<string, unknown>);
|
|
60
77
|
// Parse at assembly — an out-of-range part size or a threshold below it fails on deploy, not on the
|
|
61
78
|
// first large upload.
|
|
62
79
|
const resolved = StorageConfig.parse(configInput);
|
|
80
|
+
const mountPath = basePath ?? "/storage";
|
|
63
81
|
|
|
64
|
-
const migrations: Record<string, Migration> = {
|
|
82
|
+
const migrations: Record<string, Migration> = {
|
|
83
|
+
"0001_objects": storage_0001_objects,
|
|
84
|
+
"0002_ownership": storage_0002_ownership,
|
|
85
|
+
};
|
|
65
86
|
const requiredBindings: BindingSpecInput[] = [
|
|
66
87
|
// The app database — the objects and shares tables live here.
|
|
67
88
|
{ type: "d1", name: "DB" },
|
|
@@ -87,6 +108,9 @@ export function storage(options: StorageOptions = {}): StorageCapability {
|
|
|
87
108
|
workflows: storageWorkflows,
|
|
88
109
|
requiredBindings,
|
|
89
110
|
config: StorageConfig,
|
|
111
|
+
// The power a role holds to edit, delete and re-scope any file in its own organization. Declared so
|
|
112
|
+
// tenancy can refuse a role catalog that places it nowhere — but only in a Worker that composes storage.
|
|
113
|
+
powers: [STORAGE_MANAGE_POWER],
|
|
90
114
|
databases: {
|
|
91
115
|
app: {
|
|
92
116
|
binding: "DB",
|
|
@@ -95,7 +119,27 @@ export function storage(options: StorageOptions = {}): StorageCapability {
|
|
|
95
119
|
migrations,
|
|
96
120
|
},
|
|
97
121
|
},
|
|
98
|
-
|
|
122
|
+
// Built from the resolved mount path, never the default, so the manifest names this Worker's paths.
|
|
123
|
+
adminRoutes: storageAdminRoutes(mountPath),
|
|
124
|
+
// `pithy doctor` names every file a narrowed `visibility.allowed` no longer admits. Nothing rewrites
|
|
125
|
+
// them: making a public file private breaks every link already published. And it names an R2 bundle
|
|
126
|
+
// still holding the Cloudflare API token provisioning once stored beside the key pair (#728).
|
|
127
|
+
settings: allSettings(
|
|
128
|
+
recordsOutsidePolicy({
|
|
129
|
+
capability: "storage",
|
|
130
|
+
noun: "file",
|
|
131
|
+
table: "pithy_storage_objects",
|
|
132
|
+
policy: resolved.visibility,
|
|
133
|
+
remedy: `Move each with PATCH ${mountPath}/:id`,
|
|
134
|
+
}),
|
|
135
|
+
bundleTokenCheck({ secret: STORAGE_R2_SECRET, provision: "storage provision" }),
|
|
136
|
+
),
|
|
137
|
+
routes: registerStorageRoutes({
|
|
138
|
+
config: resolved,
|
|
139
|
+
basePath: mountPath,
|
|
140
|
+
sharePath,
|
|
141
|
+
...(permission ? { permission } : {}),
|
|
142
|
+
}),
|
|
99
143
|
seeds: [storageExampleSeed],
|
|
100
144
|
});
|
|
101
145
|
|
package/src/config/config.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { VisibilityPolicy } from "@pithy-sh/core/src/access/visibility";
|
|
5
|
+
import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
4
6
|
import { z } from "zod";
|
|
5
|
-
import { StorageVisibility } from "../data/storageObject";
|
|
6
7
|
import {
|
|
7
8
|
DEFAULT_MULTIPART_THRESHOLD_BYTES,
|
|
8
9
|
DEFAULT_PART_SIZE_BYTES,
|
|
@@ -25,8 +26,9 @@ import {
|
|
|
25
26
|
* fixes the practical object ceiling: 10,000 × 64 MiB ≈ 625 GiB. Raise `partSizeBytes` to raise the
|
|
26
27
|
* ceiling (R2's own object cap is 4.995 TiB); the cost is that every retry re-sends a larger part.
|
|
27
28
|
*
|
|
28
|
-
* **Default visibility is private
|
|
29
|
-
* cannot leak a file.
|
|
29
|
+
* **Default visibility is private, and the project decides which levels exist.** The safe default is the
|
|
30
|
+
* one where forgetting to set a field cannot leak a file, and `visibility.allowed` — all three levels
|
|
31
|
+
* unless narrowed — is how a project promises that a file can never be published at all.
|
|
30
32
|
*/
|
|
31
33
|
|
|
32
34
|
/** The largest single-part upload R2 accepts — 5 GiB, less 5 MiB. Above it, multipart is not optional. */
|
|
@@ -68,8 +70,8 @@ export const StorageConfig = z
|
|
|
68
70
|
.describe(
|
|
69
71
|
"Bytes per multipart part, for every part but the last. R2 allows at most 10,000 parts, so this fixes the largest object you can store: 64 MiB gives ~625 GiB. The floor is S3's 5 MiB rule for non-final parts.",
|
|
70
72
|
),
|
|
71
|
-
|
|
72
|
-
"
|
|
73
|
+
visibility: VisibilityPolicy.prefault({}).describe(
|
|
74
|
+
"Which visibility levels a file may carry, and the one an upload gets when it names none. Private by default; every level allowed unless narrowed.",
|
|
73
75
|
),
|
|
74
76
|
pendingTtlSeconds: z
|
|
75
77
|
.number()
|
|
@@ -80,7 +82,7 @@ export const StorageConfig = z
|
|
|
80
82
|
"How long a `pending` row holds its quota reservation before the orphan sweep reclaims it. Long enough for a slow multipart upload to finish; short enough that an abandoned one does not hold a quota forever.",
|
|
81
83
|
),
|
|
82
84
|
})
|
|
83
|
-
.describe("Configuration for the storage capability — quotas, multipart sizing, and
|
|
85
|
+
.describe("Configuration for the storage capability — quotas, multipart sizing, and the visibility policy.")
|
|
84
86
|
.check((ctx) => {
|
|
85
87
|
// A ceiling below the part size would mean the first "multipart" upload is a single short part,
|
|
86
88
|
// which R2 accepts but which makes the threshold meaningless. Say so rather than silently allowing it.
|
|
@@ -103,3 +105,19 @@ export type StorageConfigInput = z.input<typeof StorageConfig>;
|
|
|
103
105
|
export function maxObjectBytes(config: StorageConfig): number {
|
|
104
106
|
return config.partSizeBytes * MAX_UPLOAD_PARTS;
|
|
105
107
|
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Refuse a config that still names an option a release renamed, naming the new one.
|
|
111
|
+
*
|
|
112
|
+
* `defaultVisibility` became `visibility.default`, beside `visibility.allowed`. Zod would strip the old key
|
|
113
|
+
* and parse the rest, so a project upgrading without the edit would quietly get the default it may have
|
|
114
|
+
* meant to change — refused here instead, before the config is parsed.
|
|
115
|
+
*/
|
|
116
|
+
export function refuseRenamedStorageOptions(input: Record<string, unknown>): void {
|
|
117
|
+
if (!("defaultVisibility" in input)) return;
|
|
118
|
+
throw new ValidationError({
|
|
119
|
+
message: "`defaultVisibility` was renamed `visibility.default`.",
|
|
120
|
+
action: `Replace \`defaultVisibility: ${JSON.stringify(input.defaultVisibility)}\` with \`visibility: { default: ${JSON.stringify(input.defaultVisibility)} }\` in storage({ … }) in this Worker's pithy.config.ts.`,
|
|
121
|
+
detail: "storage({ defaultVisibility }) names an option this release renamed",
|
|
122
|
+
});
|
|
123
|
+
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { RecordVisibility } from "@pithy-sh/core/src/access/visibility";
|
|
4
5
|
import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
|
|
5
6
|
import { z } from "zod";
|
|
6
7
|
|
|
@@ -20,13 +21,20 @@ import { z } from "zod";
|
|
|
20
21
|
* `size` is declared by the client at init and *confirmed* against R2 at completion. It is nullable
|
|
21
22
|
* because a caller may not know it up front; a null size reserves no quota, which is why the handler
|
|
22
23
|
* requires it whenever a quota is configured.
|
|
24
|
+
*
|
|
25
|
+
* **Whose it is.** `ownerId` is the authenticated user and `organizationId` the organization they were
|
|
26
|
+
* acting for when the file was written — the same two columns, in the same terms, as a media record, so
|
|
27
|
+
* one name answers *what is this account holding* across both. The organization is the fact at the time
|
|
28
|
+
* of the write, never a join through current membership.
|
|
23
29
|
*/
|
|
24
30
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
31
|
+
/**
|
|
32
|
+
* Who may read an object without a share link — core's three levels, the same ones media uses. Visibility
|
|
33
|
+
* is authorization, not a bucket setting: the bucket itself stays private.
|
|
34
|
+
*/
|
|
35
|
+
export const StorageVisibility = RecordVisibility.describe(
|
|
36
|
+
"Who may read an object without a share link: `private` is its owner, acting for its organization; `organization` is any member acting for it; `public` is anyone with the id. Visibility is authorization, not a bucket setting — the bucket itself stays private.",
|
|
37
|
+
);
|
|
30
38
|
export type StorageVisibility = z.infer<typeof StorageVisibility>;
|
|
31
39
|
|
|
32
40
|
export const StorageObjectStatus = z
|
|
@@ -51,6 +59,12 @@ export const StorageObject = z
|
|
|
51
59
|
.string()
|
|
52
60
|
.nullable()
|
|
53
61
|
.describe("The authenticated user who owns the file, from AuthContext. Null for system-owned objects."),
|
|
62
|
+
organizationId: z
|
|
63
|
+
.string()
|
|
64
|
+
.nullable()
|
|
65
|
+
.describe(
|
|
66
|
+
"The organization the owner was acting for when the file was written, from the acting-organization seam. Null when none was in force, and for system-owned objects.",
|
|
67
|
+
),
|
|
54
68
|
contentType: z
|
|
55
69
|
.string()
|
|
56
70
|
.min(1)
|
|
@@ -63,7 +77,9 @@ export const StorageObject = z
|
|
|
63
77
|
.nonnegative()
|
|
64
78
|
.nullable()
|
|
65
79
|
.describe("Byte count. Declared at init so the pending row reserves quota; confirmed against R2 at completion."),
|
|
66
|
-
visibility: StorageVisibility.describe(
|
|
80
|
+
visibility: StorageVisibility.describe(
|
|
81
|
+
"Who may read this object: its owner, its organization's members, or anyone with the id.",
|
|
82
|
+
),
|
|
67
83
|
checksum: z
|
|
68
84
|
.string()
|
|
69
85
|
.nullable()
|
package/src/error/errors.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import { PithyError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
5
|
import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
|
|
6
|
+
import type { UnmarkedString } from "@pithy-sh/core/src/privacy/types";
|
|
6
7
|
|
|
7
8
|
/**
|
|
8
9
|
* `@pithy-sh/storage` throw sugar. The `storage/*` codes live in core's closed `KitErrorPayload` union
|
|
@@ -15,9 +16,9 @@ import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
|
|
|
15
16
|
*/
|
|
16
17
|
|
|
17
18
|
interface StorageErrorArgs {
|
|
18
|
-
message?:
|
|
19
|
-
action?:
|
|
20
|
-
detail?:
|
|
19
|
+
message?: UnmarkedString;
|
|
20
|
+
action?: UnmarkedString;
|
|
21
|
+
detail?: UnmarkedString;
|
|
21
22
|
/**
|
|
22
23
|
* Values a translating client interpolates into its own wording for this code. Client-facing, so —
|
|
23
24
|
* unlike `action` and `detail` — these cross the boundary with `message`.
|
|
@@ -47,8 +48,8 @@ export class StorageForbiddenError extends PithyError {
|
|
|
47
48
|
{
|
|
48
49
|
code: "storage/forbidden",
|
|
49
50
|
status: 403,
|
|
50
|
-
message: args.message ?? "
|
|
51
|
-
action: args.action ?? "Sign in as the owner, or ask
|
|
51
|
+
message: args.message ?? "You can see that file, but it is not yours to change.",
|
|
52
|
+
action: args.action ?? "Sign in as the owner, or ask a role holding storage:manage in its organization.",
|
|
52
53
|
detail: args.detail,
|
|
53
54
|
params: args.params,
|
|
54
55
|
},
|