@pithy-sh/storage 0.3.0 → 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.
Files changed (82) hide show
  1. package/dist/capability.d.ts +12 -3
  2. package/dist/capability.d.ts.map +1 -1
  3. package/dist/capability.js +35 -9
  4. package/dist/config/config.d.ts +20 -4
  5. package/dist/config/config.d.ts.map +1 -1
  6. package/dist/config/config.js +23 -6
  7. package/dist/data/storageObject.d.ts +12 -0
  8. package/dist/data/storageObject.d.ts.map +1 -1
  9. package/dist/data/storageObject.js +13 -2
  10. package/dist/data/tables.js +1 -1
  11. package/dist/error/errors.js +2 -2
  12. package/dist/http/handlers.d.ts +45 -14
  13. package/dist/http/handlers.d.ts.map +1 -1
  14. package/dist/http/handlers.js +169 -66
  15. package/dist/http/responses.d.ts +6 -0
  16. package/dist/http/responses.d.ts.map +1 -1
  17. package/dist/http/responses.js +2 -1
  18. package/dist/http/routes.d.ts +13 -2
  19. package/dist/http/routes.d.ts.map +1 -1
  20. package/dist/http/routes.js +37 -9
  21. package/dist/http/schemas.d.ts +6 -0
  22. package/dist/http/schemas.d.ts.map +1 -1
  23. package/dist/http/schemas.js +6 -5
  24. package/dist/http/scopes.d.ts +25 -0
  25. package/dist/http/scopes.d.ts.map +1 -0
  26. package/dist/http/scopes.js +32 -0
  27. package/dist/http/serve.d.ts +5 -2
  28. package/dist/http/serve.d.ts.map +1 -1
  29. package/dist/index.d.ts +2 -0
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +5 -3
  32. package/dist/migrations/0002_ownership.d.ts +5 -0
  33. package/dist/migrations/0002_ownership.d.ts.map +1 -0
  34. package/dist/migrations/0002_ownership.js +114 -0
  35. package/dist/object/cloudflare.d.ts +2 -1
  36. package/dist/object/cloudflare.d.ts.map +1 -1
  37. package/dist/object/cloudflare.js +2 -2
  38. package/dist/provision/provisionStorage.d.ts +14 -2
  39. package/dist/provision/provisionStorage.d.ts.map +1 -1
  40. package/dist/provision/provisionStorage.js +19 -4
  41. package/dist/provision/resolveStorageConfig.js +1 -1
  42. package/dist/quota/ceiling.d.ts +36 -0
  43. package/dist/quota/ceiling.d.ts.map +1 -0
  44. package/dist/quota/ceiling.js +31 -0
  45. package/dist/quota/quota.d.ts +24 -7
  46. package/dist/quota/quota.d.ts.map +1 -1
  47. package/dist/quota/quota.js +40 -12
  48. package/dist/secret/bundleToken.d.ts +24 -0
  49. package/dist/secret/bundleToken.d.ts.map +1 -0
  50. package/dist/secret/bundleToken.js +74 -0
  51. package/dist/secret/registry.d.ts +5 -1
  52. package/dist/secret/registry.d.ts.map +1 -1
  53. package/dist/secret/registry.js +7 -3
  54. package/dist/seeds/example.d.ts.map +1 -1
  55. package/dist/seeds/example.js +3 -0
  56. package/dist/test-utils/liveStorage.d.ts.map +1 -1
  57. package/dist/test-utils/liveStorage.js +5 -2
  58. package/dist/version.generated.d.ts +1 -1
  59. package/dist/version.generated.js +1 -1
  60. package/package.json +5 -5
  61. package/pithy.manifest.json +20 -10
  62. package/src/capability.ts +52 -8
  63. package/src/config/config.ts +24 -6
  64. package/src/data/storageObject.ts +22 -6
  65. package/src/error/errors.ts +2 -2
  66. package/src/http/handlers.ts +212 -79
  67. package/src/http/responses.ts +13 -1
  68. package/src/http/routes.ts +64 -10
  69. package/src/http/schemas.ts +10 -4
  70. package/src/http/scopes.ts +39 -0
  71. package/src/http/serve.ts +5 -2
  72. package/src/index.ts +2 -0
  73. package/src/migrations/0002_ownership.ts +176 -0
  74. package/src/object/cloudflare.ts +2 -2
  75. package/src/provision/provisionStorage.ts +22 -3
  76. package/src/quota/ceiling.ts +44 -0
  77. package/src/quota/quota.ts +63 -20
  78. package/src/secret/bundleToken.ts +81 -0
  79. package/src/secret/registry.ts +6 -8
  80. package/src/seeds/example.ts +3 -0
  81. package/src/test-utils/liveStorage.ts +3 -6
  82. 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 { STORAGE_BUCKET_BINDING, storageSecretsRegistry } from "./secret/registry";
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 scoping reads `c.var.auth.userId`,
55
- * so without `@pithy-sh/auth` every owner-scoped route denies rather than opens, which is the right
56
- * failure and needs no dependency edge. It belongs in the manifest's `optionalCapabilities`.
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> = { "0001_objects": storage_0001_objects };
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
- routes: registerStorageRoutes({ config: resolved, basePath, sharePath }),
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
 
@@ -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.** The safe default is the one where forgetting to set a field
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
- defaultVisibility: StorageVisibility.default("private").describe(
72
- "Visibility for an upload that does not name one. Private, so a forgotten field can never publish a file.",
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 default visibility.")
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
- export const StorageVisibility = z
26
- .enum(["private", "public"])
27
- .describe(
28
- "Who may read an object without a share link: `private` is the owner alone, `public` is anyone with the id. Visibility is authorization, not a bucket setting — the bucket itself stays private.",
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("Whether anyone with the id may read this object, or only its owner."),
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()
@@ -47,8 +47,8 @@ export class StorageForbiddenError extends PithyError {
47
47
  {
48
48
  code: "storage/forbidden",
49
49
  status: 403,
50
- message: args.message ?? "That file is not yours.",
51
- action: args.action ?? "Sign in as the owner, or ask them for a share link.",
50
+ message: args.message ?? "You can see that file, but it is not yours to change.",
51
+ action: args.action ?? "Sign in as the owner, or ask a role holding storage:manage in its organization.",
52
52
  detail: args.detail,
53
53
  params: args.params,
54
54
  },