@terreno/admin-backend 57.12.0 → 57.14.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/README.md CHANGED
@@ -49,7 +49,7 @@ This creates `GET /admin/config` plus full CRUD at `/admin/users` and `/admin/to
49
49
  ## What's included
50
50
 
51
51
  - `AdminApp` — registers admin routes and the config metadata endpoint
52
- - `DocumentStorageApp` — optional GCS document browser routes for admins
52
+ - `DocumentStorageApp` — optional GCS document browser routes for admins, or for every signed-in user in a private folder (`access: "authenticated"`), with optional upload rate limit
53
53
  - `runScriptCli` — CLI helper for admin script execution
54
54
  - Auto-generated CRUD via `modelRouter` with `IsAdmin` on every route
55
55
  - `GET /admin/config` — field metadata extracted from Mongoose schemas and OpenAPI
@@ -1,4 +1,4 @@
1
- import { type AdminContribution, type TerrenoPlugin } from "@terreno/api";
1
+ import { type AdminContribution, type RouteRateLimitOptions, type TerrenoPlugin } from "@terreno/api";
2
2
  import type express from "express";
3
3
  import { type FileUploadsEnabled } from "./fileUploadsGate";
4
4
  export interface DocumentStorageOptions {
@@ -8,6 +8,14 @@ export interface DocumentStorageOptions {
8
8
  allowedMimeTypes?: string[];
9
9
  maxFileSize?: number;
10
10
  signedUrlExpiration?: number;
11
+ /**
12
+ * Who may use the routes. `admin` (default) gives admins the whole bucket. `authenticated`
13
+ * also lets signed-in non-admins in, confined to their own `users/<userId>/` folder
14
+ * under `folderPrefix`. A prefix without a trailing slash gets one.
15
+ */
16
+ access?: "admin" | "authenticated";
17
+ /** Per-key limit on uploads (`POST basePath/`). Keys by client IP unless `keyBy` is set. */
18
+ uploadRateLimit?: Omit<RouteRateLimitOptions, "name">;
11
19
  /**
12
20
  * When `false` or the function returns `false`, `POST` uploads are rejected.
13
21
  * Listing, download, and delete stay available. Omit or pass `true` to leave uploads enabled.
@@ -33,7 +41,7 @@ export declare class DocumentStorageApp implements TerrenoPlugin {
33
41
  constructor(options: DocumentStorageOptions);
34
42
  adminContribution(): AdminContribution;
35
43
  private get bucket();
36
- private get prefix();
44
+ private prefixFor;
37
45
  private get allowedMimeTypes();
38
46
  register(app: express.Application): void;
39
47
  }
@@ -43,6 +43,30 @@ const isAdmin = (req) => {
43
43
  const user = req.user;
44
44
  return user?.admin === true;
45
45
  };
46
+ const userIdOf = (req) => {
47
+ const user = req.user;
48
+ return user?.id ?? (user?._id != null ? String(user._id) : undefined);
49
+ };
50
+ // GCS prefixes are directories. A value without a trailing slash would glue the next
51
+ // segment on (`pr-5users/` instead of `pr-5/users/`).
52
+ // GCS answers a missing bucket with 404 notFound. That is an empty demo, not a broken list.
53
+ const isMissingBucket = (error) => {
54
+ if (typeof error !== "object" || error === null) {
55
+ return false;
56
+ }
57
+ const gcsError = error;
58
+ if (gcsError.code !== 404) {
59
+ return false;
60
+ }
61
+ return gcsError.errors?.some((item) => item.reason === "notFound") === true;
62
+ };
63
+ const withTrailingSlash = (folderPrefix) => {
64
+ const base = folderPrefix ?? "";
65
+ if (base.length === 0 || base.endsWith("/")) {
66
+ return base;
67
+ }
68
+ return `${base}/`;
69
+ };
46
70
  class DocumentStorageApp {
47
71
  options;
48
72
  storage;
@@ -67,8 +91,17 @@ class DocumentStorageApp {
67
91
  }
68
92
  return this.storage.bucket(bucketName);
69
93
  }
70
- get prefix() {
71
- return this.options.folderPrefix ?? "";
94
+ // Admins see the whole configured prefix; other users only their own folder.
95
+ prefixFor(req) {
96
+ const base = withTrailingSlash(this.options.folderPrefix);
97
+ if (isAdmin(req)) {
98
+ return base;
99
+ }
100
+ const userId = userIdOf(req);
101
+ if (!userId) {
102
+ throw new api_1.APIError({ status: 401, title: "Authentication required" });
103
+ }
104
+ return `${base}users/${userId}/`;
72
105
  }
73
106
  get allowedMimeTypes() {
74
107
  if (this.options.allowedMimeTypes) {
@@ -97,36 +130,59 @@ class DocumentStorageApp {
97
130
  limits: { fileSize: maxFileSize },
98
131
  storage: multer_1.default.memoryStorage(),
99
132
  });
100
- const adminGuard = [
133
+ const isOpenToUsers = this.options.access === "authenticated";
134
+ const accessGuard = [
101
135
  (0, api_1.authenticateMiddleware)(),
102
136
  (req, _res, next) => {
103
- if (!isAdmin(req)) {
137
+ if (!isOpenToUsers && !isAdmin(req)) {
104
138
  throw new api_1.APIError({ status: 403, title: "Admin access required" });
105
139
  }
106
140
  next();
107
141
  },
108
142
  ];
143
+ const uploadRateLimit = this.options.uploadRateLimit
144
+ ? [
145
+ (0, api_1.createRouteRateLimitMiddleware)({
146
+ ...this.options.uploadRateLimit,
147
+ name: `documents-upload:${basePath}`,
148
+ }),
149
+ ]
150
+ : [];
109
151
  // GET basePath/ — List files and folders
110
- app.get(`${basePath}/`, ...adminGuard, (0, api_1.asyncHandler)(async (req, res) => {
152
+ app.get(`${basePath}/`, ...accessGuard, (0, api_1.asyncHandler)(async (req, res) => {
111
153
  const queryPrefix = req.query.prefix ?? "";
112
- const fullPrefix = `${this.prefix}${queryPrefix}`;
113
- const [files, , apiResponse] = await this.bucket.getFiles({
114
- delimiter: "/",
115
- prefix: fullPrefix,
116
- });
154
+ const rootPrefix = this.prefixFor(req);
155
+ const fullPrefix = `${rootPrefix}${queryPrefix}`;
156
+ let files;
157
+ let prefixes = [];
158
+ try {
159
+ const listed = await this.bucket.getFiles({
160
+ delimiter: "/",
161
+ prefix: fullPrefix,
162
+ });
163
+ files = listed[0];
164
+ prefixes = listed[2]?.prefixes ?? [];
165
+ }
166
+ catch (error) {
167
+ if (!isMissingBucket(error)) {
168
+ throw error;
169
+ }
170
+ api_1.logger.warn("Document storage bucket does not exist; returning an empty list");
171
+ const empty = { files: [], folders: [], prefix: queryPrefix };
172
+ return res.json(empty);
173
+ }
117
174
  const documentFiles = files
118
175
  .filter((file) => file.name !== fullPrefix)
119
176
  .map((file) => ({
120
177
  contentType: file.metadata.contentType,
121
- fullPath: file.name.slice(this.prefix.length),
178
+ fullPath: file.name.slice(rootPrefix.length),
122
179
  isFolder: false,
123
180
  name: file.name.split("/").filter(Boolean).pop() ?? file.name,
124
181
  size: Number(file.metadata.size ?? 0),
125
182
  updated: file.metadata.updated,
126
183
  }));
127
- const prefixes = apiResponse?.prefixes ?? [];
128
184
  const folders = prefixes.map((p) => {
129
- const relative = p.slice(this.prefix.length);
185
+ const relative = p.slice(rootPrefix.length);
130
186
  return relative;
131
187
  });
132
188
  const response = {
@@ -137,7 +193,7 @@ class DocumentStorageApp {
137
193
  return res.json(response);
138
194
  }));
139
195
  // POST basePath/ — Upload a file
140
- app.post(`${basePath}/`, ...adminGuard, upload.single("file"), (0, api_1.asyncHandler)(async (req, res) => {
196
+ app.post(`${basePath}/`, ...accessGuard, ...uploadRateLimit, upload.single("file"), (0, api_1.asyncHandler)(async (req, res) => {
141
197
  await (0, fileUploadsGate_1.assertFileUploadsEnabled)(req, this.options.fileUploadsEnabled);
142
198
  const file = req.file;
143
199
  if (!file) {
@@ -145,7 +201,7 @@ class DocumentStorageApp {
145
201
  }
146
202
  const targetPrefix = req.body.prefix ?? "";
147
203
  const sanitizedFilename = file.originalname.replace(/[^a-zA-Z0-9._-]/g, "_");
148
- const gcsPath = `${this.prefix}${targetPrefix}${sanitizedFilename}`;
204
+ const gcsPath = `${this.prefixFor(req)}${targetPrefix}${sanitizedFilename}`;
149
205
  const gcsFile = this.bucket.file(gcsPath);
150
206
  await gcsFile.save(file.buffer, {
151
207
  contentType: file.mimetype,
@@ -161,12 +217,12 @@ class DocumentStorageApp {
161
217
  return res.json(documentFile);
162
218
  }));
163
219
  // GET basePath/download/* — Stream file download
164
- app.get(`${basePath}/download/*filepath`, ...adminGuard, (0, api_1.asyncHandler)(async (req, res) => {
220
+ app.get(`${basePath}/download/*filepath`, ...accessGuard, (0, api_1.asyncHandler)(async (req, res) => {
165
221
  const filePath = normalizePathParam(req.params.filepath);
166
222
  if (!filePath) {
167
223
  throw new api_1.APIError({ status: 400, title: "File path is required" });
168
224
  }
169
- const gcsPath = `${this.prefix}${filePath}`;
225
+ const gcsPath = `${this.prefixFor(req)}${filePath}`;
170
226
  const gcsFile = this.bucket.file(gcsPath);
171
227
  let metadata;
172
228
  try {
@@ -214,36 +270,36 @@ class DocumentStorageApp {
214
270
  }
215
271
  }));
216
272
  // POST basePath/folder — Create a folder
217
- app.post(`${basePath}/folder`, ...adminGuard, (0, api_1.asyncHandler)(async (req, res) => {
273
+ app.post(`${basePath}/folder`, ...accessGuard, (0, api_1.asyncHandler)(async (req, res) => {
218
274
  const { folderName, prefix } = req.body;
219
275
  if (!folderName) {
220
276
  throw new api_1.APIError({ status: 400, title: "Folder name is required" });
221
277
  }
222
278
  const sanitizedName = folderName.replace(/[^a-zA-Z0-9._-]/g, "_");
223
279
  const targetPrefix = prefix ?? "";
224
- const gcsPath = `${this.prefix}${targetPrefix}${sanitizedName}/`;
280
+ const gcsPath = `${this.prefixFor(req)}${targetPrefix}${sanitizedName}/`;
225
281
  const gcsFile = this.bucket.file(gcsPath);
226
282
  await gcsFile.save(Buffer.alloc(0), { contentType: "application/x-directory" });
227
283
  return res.json({ folder: `${targetPrefix}${sanitizedName}/` });
228
284
  }));
229
285
  // DELETE basePath/folder/* — Delete a folder and all its contents
230
- app.delete(`${basePath}/folder/*folderpath`, ...adminGuard, (0, api_1.asyncHandler)(async (req, res) => {
286
+ app.delete(`${basePath}/folder/*folderpath`, ...accessGuard, (0, api_1.asyncHandler)(async (req, res) => {
231
287
  const folderPath = normalizePathParam(req.params.folderpath);
232
288
  if (!folderPath) {
233
289
  throw new api_1.APIError({ status: 400, title: "Folder path is required" });
234
290
  }
235
- const gcsPrefix = `${this.prefix}${folderPath}`;
291
+ const gcsPrefix = `${this.prefixFor(req)}${folderPath}`;
236
292
  const [files] = await this.bucket.getFiles({ prefix: gcsPrefix });
237
293
  await Promise.all(files.map((f) => f.delete({ ignoreNotFound: true })));
238
294
  return res.json({ success: true });
239
295
  }));
240
296
  // DELETE basePath/* — Delete a file
241
- app.delete(`${basePath}/*filepath`, ...adminGuard, (0, api_1.asyncHandler)(async (req, res) => {
297
+ app.delete(`${basePath}/*filepath`, ...accessGuard, (0, api_1.asyncHandler)(async (req, res) => {
242
298
  const filePath = normalizePathParam(req.params.filepath);
243
299
  if (!filePath) {
244
300
  throw new api_1.APIError({ status: 400, title: "File path is required" });
245
301
  }
246
- const gcsPath = `${this.prefix}${filePath}`;
302
+ const gcsPath = `${this.prefixFor(req)}${filePath}`;
247
303
  const gcsFile = this.bucket.file(gcsPath);
248
304
  await gcsFile.delete({ ignoreNotFound: true });
249
305
  return res.json({ success: true });
package/package.json CHANGED
@@ -5,8 +5,8 @@
5
5
  },
6
6
  "dependencies": {
7
7
  "@google-cloud/storage": "^7.15.0",
8
- "@terreno/api": "57.12.0",
9
- "@terreno/jobs": "57.12.0",
8
+ "@terreno/api": "57.14.0",
9
+ "@terreno/jobs": "57.14.0",
10
10
  "express": "^5.2.1",
11
11
  "luxon": "^3.7.2",
12
12
  "multer": "2.2.0"
@@ -14,7 +14,7 @@
14
14
  "description": "Admin panel backend plugin for @terreno/api — part of Terreno, the batteries-included TypeScript framework for universal apps.",
15
15
  "devDependencies": {
16
16
  "@biomejs/biome": "^2.3.6",
17
- "@terreno/test": "57.12.0",
17
+ "@terreno/test": "57.14.0",
18
18
  "@types/bun": "^1.4.0",
19
19
  "@types/express": "^5.0.6",
20
20
  "@types/luxon": "^3.7.1",
@@ -55,5 +55,5 @@
55
55
  "test:coverage": "bun run ../scripts/check-coverage.ts"
56
56
  },
57
57
  "types": "dist/index.d.ts",
58
- "version": "57.12.0"
58
+ "version": "57.14.0"
59
59
  }
@@ -488,7 +488,120 @@ describe("DocumentStorageApp", () => {
488
488
  });
489
489
  });
490
490
 
491
+ describe("access: authenticated", () => {
492
+ const recordingFileFactory = (saved: string[]) => (path: string) =>
493
+ ({
494
+ createReadStream: mock(() => new PassThrough()),
495
+ delete: mock(async () => {
496
+ saved.push(`delete:${path}`);
497
+ return [{}];
498
+ }),
499
+ getMetadata: mock(async () => [{}]),
500
+ metadata: {},
501
+ name: path,
502
+ save: mock(async () => {
503
+ saved.push(`save:${path}`);
504
+ }),
505
+ }) as unknown as MockedFile;
506
+
507
+ it("confines non-admins to their own users/<id>/ folder", async () => {
508
+ app = buildApp({access: "authenticated", bucketName: "b", folderPrefix: "tenant/"});
509
+ const agent = await authAsUser(app, "notAdmin");
510
+ const user = await UserModel.findOne({email: "notAdmin@example.com"});
511
+ const userId = String(user?._id);
512
+ const userPrefix = `tenant/users/${userId}/`;
513
+
514
+ bucketBehavior.getFiles = mock(async (opts: {prefix: string}) => {
515
+ expect(opts.prefix).toBe(`${userPrefix}sub/`);
516
+ return [
517
+ [{metadata: {size: 1}, name: `${userPrefix}sub/a.txt`}],
518
+ null,
519
+ {prefixes: [`${userPrefix}sub/inner/`]},
520
+ ];
521
+ });
522
+ const list = await agent.get("/documents/").query({prefix: "sub/"}).expect(200);
523
+ expect(list.body.files[0].fullPath).toBe("sub/a.txt");
524
+ expect(list.body.folders).toEqual(["sub/inner/"]);
525
+
526
+ const saved: string[] = [];
527
+ bucketBehavior.fileFactory = recordingFileFactory(saved);
528
+ await agent
529
+ .post("/documents/")
530
+ .attach("file", Buffer.from("x"), {contentType: "text/plain", filename: "x.txt"})
531
+ .expect(200);
532
+ await agent.delete("/documents/x.txt").expect(200);
533
+ expect(saved).toEqual([`save:${userPrefix}x.txt`, `delete:${userPrefix}x.txt`]);
534
+ });
535
+
536
+ it("inserts a slash when folderPrefix has none", async () => {
537
+ app = buildApp({access: "authenticated", bucketName: "b", folderPrefix: "pr-5"});
538
+ const userAgent = await authAsUser(app, "notAdmin");
539
+ const user = await UserModel.findOne({email: "notAdmin@example.com"});
540
+ const userId = String(user?._id);
541
+ bucketBehavior.getFiles = mock(async (opts: {prefix: string}) => {
542
+ expect(opts.prefix).toBe(`pr-5/users/${userId}/`);
543
+ return [[], null, {prefixes: []}];
544
+ });
545
+ await userAgent.get("/documents/").expect(200);
546
+
547
+ const adminAgent = await authAsUser(app, "admin");
548
+ bucketBehavior.getFiles = mock(async (opts: {prefix: string}) => {
549
+ expect(opts.prefix).toBe("pr-5/");
550
+ return [[], null, {prefixes: []}];
551
+ });
552
+ await adminAgent.get("/documents/").expect(200);
553
+ });
554
+
555
+ it("keeps whole-bucket access for admins", async () => {
556
+ app = buildApp({access: "authenticated", bucketName: "b", folderPrefix: "tenant/"});
557
+ const agent = await authAsUser(app, "admin");
558
+ bucketBehavior.getFiles = mock(async (opts: {prefix: string}) => {
559
+ expect(opts.prefix).toBe("tenant/");
560
+ return [[], null, {prefixes: []}];
561
+ });
562
+ await agent.get("/documents/").expect(200);
563
+ });
564
+
565
+ it("still requires authentication", async () => {
566
+ app = buildApp({access: "authenticated", bucketName: "b"});
567
+ await supertest(app).get("/documents/").expect(401);
568
+ });
569
+ });
570
+
571
+ describe("uploadRateLimit", () => {
572
+ it("allows one upload per IP per window, then returns 429", async () => {
573
+ app = buildApp({bucketName: "b", uploadRateLimit: {max: 1, windowMs: 60_000}});
574
+ const agent = await authAsUser(app, "admin");
575
+ const upload = () =>
576
+ agent
577
+ .post("/documents/")
578
+ .attach("file", Buffer.from("x"), {contentType: "text/plain", filename: "x.txt"});
579
+
580
+ await upload().expect(200);
581
+ const limited = await upload().expect(429);
582
+ expect(limited.headers["retry-after"]).toBeDefined();
583
+ // Listing is not rate limited.
584
+ await agent.get("/documents/").expect(200);
585
+ });
586
+ });
587
+
491
588
  describe("configuration edge cases", () => {
589
+ it("returns an empty list when the bucket does not exist", async () => {
590
+ app = buildApp({bucketName: "missing-bucket"});
591
+ const agent = await authAsUser(app, "admin");
592
+ bucketBehavior.getFiles = mock(async () => {
593
+ const error = new Error("The specified bucket does not exist.") as Error & {
594
+ code?: number;
595
+ errors?: {reason?: string}[];
596
+ };
597
+ error.code = 404;
598
+ error.errors = [{reason: "notFound"}];
599
+ throw error;
600
+ });
601
+ const res = await agent.get("/documents/").expect(200);
602
+ expect(res.body).toEqual({files: [], folders: [], prefix: ""});
603
+ });
604
+
492
605
  it("throws a 503 when no bucketName is configured", async () => {
493
606
  const originalBucket = process.env.GCS_BUCKET;
494
607
  process.env.GCS_BUCKET = "";
@@ -5,7 +5,9 @@ import {
5
5
  APIError,
6
6
  asyncHandler,
7
7
  authenticateMiddleware,
8
+ createRouteRateLimitMiddleware,
8
9
  logger,
10
+ type RouteRateLimitOptions,
9
11
  type TerrenoPlugin,
10
12
  } from "@terreno/api";
11
13
  import type express from "express";
@@ -21,6 +23,14 @@ export interface DocumentStorageOptions {
21
23
  allowedMimeTypes?: string[];
22
24
  maxFileSize?: number;
23
25
  signedUrlExpiration?: number;
26
+ /**
27
+ * Who may use the routes. `admin` (default) gives admins the whole bucket. `authenticated`
28
+ * also lets signed-in non-admins in, confined to their own `users/<userId>/` folder
29
+ * under `folderPrefix`. A prefix without a trailing slash gets one.
30
+ */
31
+ access?: "admin" | "authenticated";
32
+ /** Per-key limit on uploads (`POST basePath/`). Keys by client IP unless `keyBy` is set. */
33
+ uploadRateLimit?: Omit<RouteRateLimitOptions, "name">;
24
34
  /**
25
35
  * When `false` or the function returns `false`, `POST` uploads are rejected.
26
36
  * Listing, download, and delete stay available. Omit or pass `true` to leave uploads enabled.
@@ -37,6 +47,11 @@ export interface DocumentFile {
37
47
  isFolder: boolean;
38
48
  }
39
49
 
50
+ interface ListedStorageFile {
51
+ metadata: {contentType?: unknown; size?: unknown; updated?: unknown};
52
+ name: string;
53
+ }
54
+
40
55
  export interface DocumentListResponse {
41
56
  files: DocumentFile[];
42
57
  folders: string[];
@@ -80,6 +95,33 @@ const isAdmin = (req: express.Request): boolean => {
80
95
  return user?.admin === true;
81
96
  };
82
97
 
98
+ const userIdOf = (req: express.Request): string | undefined => {
99
+ const user = req.user as {_id?: unknown; id?: string} | undefined;
100
+ return user?.id ?? (user?._id != null ? String(user._id) : undefined);
101
+ };
102
+
103
+ // GCS prefixes are directories. A value without a trailing slash would glue the next
104
+ // segment on (`pr-5users/` instead of `pr-5/users/`).
105
+ // GCS answers a missing bucket with 404 notFound. That is an empty demo, not a broken list.
106
+ const isMissingBucket = (error: unknown): boolean => {
107
+ if (typeof error !== "object" || error === null) {
108
+ return false;
109
+ }
110
+ const gcsError = error as {code?: number; errors?: {reason?: string}[]};
111
+ if (gcsError.code !== 404) {
112
+ return false;
113
+ }
114
+ return gcsError.errors?.some((item) => item.reason === "notFound") === true;
115
+ };
116
+
117
+ const withTrailingSlash = (folderPrefix: string | undefined): string => {
118
+ const base = folderPrefix ?? "";
119
+ if (base.length === 0 || base.endsWith("/")) {
120
+ return base;
121
+ }
122
+ return `${base}/`;
123
+ };
124
+
83
125
  export class DocumentStorageApp implements TerrenoPlugin {
84
126
  private options: DocumentStorageOptions;
85
127
  private storage: Storage;
@@ -108,8 +150,17 @@ export class DocumentStorageApp implements TerrenoPlugin {
108
150
  return this.storage.bucket(bucketName);
109
151
  }
110
152
 
111
- private get prefix() {
112
- return this.options.folderPrefix ?? "";
153
+ // Admins see the whole configured prefix; other users only their own folder.
154
+ private prefixFor(req: express.Request): string {
155
+ const base = withTrailingSlash(this.options.folderPrefix);
156
+ if (isAdmin(req)) {
157
+ return base;
158
+ }
159
+ const userId = userIdOf(req);
160
+ if (!userId) {
161
+ throw new APIError({status: 401, title: "Authentication required"});
162
+ }
163
+ return `${base}users/${userId}/`;
113
164
  }
114
165
 
115
166
  private get allowedMimeTypes(): Set<string> {
@@ -144,44 +195,65 @@ export class DocumentStorageApp implements TerrenoPlugin {
144
195
  storage: multer.memoryStorage(),
145
196
  });
146
197
 
147
- const adminGuard = [
198
+ const isOpenToUsers = this.options.access === "authenticated";
199
+ const accessGuard = [
148
200
  authenticateMiddleware(),
149
201
  (req: express.Request, _res: express.Response, next: express.NextFunction) => {
150
- if (!isAdmin(req)) {
202
+ if (!isOpenToUsers && !isAdmin(req)) {
151
203
  throw new APIError({status: 403, title: "Admin access required"});
152
204
  }
153
205
  next();
154
206
  },
155
207
  ];
208
+ const uploadRateLimit: express.RequestHandler[] = this.options.uploadRateLimit
209
+ ? [
210
+ createRouteRateLimitMiddleware({
211
+ ...this.options.uploadRateLimit,
212
+ name: `documents-upload:${basePath}`,
213
+ }) as express.RequestHandler,
214
+ ]
215
+ : [];
156
216
 
157
217
  // GET basePath/ — List files and folders
158
218
  app.get(
159
219
  `${basePath}/`,
160
- ...adminGuard,
220
+ ...accessGuard,
161
221
  asyncHandler(async (req: express.Request, res: express.Response) => {
162
222
  const queryPrefix = (req.query.prefix as string) ?? "";
163
- const fullPrefix = `${this.prefix}${queryPrefix}`;
223
+ const rootPrefix = this.prefixFor(req);
224
+ const fullPrefix = `${rootPrefix}${queryPrefix}`;
164
225
 
165
- const [files, , apiResponse] = await this.bucket.getFiles({
166
- delimiter: "/",
167
- prefix: fullPrefix,
168
- });
226
+ let files: ListedStorageFile[];
227
+ let prefixes: string[] = [];
228
+ try {
229
+ const listed = await this.bucket.getFiles({
230
+ delimiter: "/",
231
+ prefix: fullPrefix,
232
+ });
233
+ files = listed[0];
234
+ prefixes = (listed[2] as {prefixes?: string[]} | undefined)?.prefixes ?? [];
235
+ } catch (error) {
236
+ if (!isMissingBucket(error)) {
237
+ throw error;
238
+ }
239
+ logger.warn("Document storage bucket does not exist; returning an empty list");
240
+ const empty: DocumentListResponse = {files: [], folders: [], prefix: queryPrefix};
241
+ return res.json(empty);
242
+ }
169
243
 
170
244
  const documentFiles: DocumentFile[] = files
171
245
  .filter((file) => file.name !== fullPrefix)
172
246
  .map((file) => ({
173
247
  contentType: file.metadata.contentType as string | undefined,
174
- fullPath: file.name.slice(this.prefix.length),
248
+ fullPath: file.name.slice(rootPrefix.length),
175
249
  isFolder: false,
176
250
  name: file.name.split("/").filter(Boolean).pop() ?? file.name,
177
251
  size: Number(file.metadata.size ?? 0),
178
252
  updated: file.metadata.updated as string,
179
253
  }));
180
254
 
181
- const prefixes =
182
- ((apiResponse as {prefixes?: string[]})?.prefixes as string[] | undefined) ?? [];
183
255
  const folders = prefixes.map((p) => {
184
- const relative = p.slice(this.prefix.length);
256
+ const relative = p.slice(rootPrefix.length);
185
257
  return relative;
186
258
  });
187
259
 
@@ -198,7 +270,8 @@ export class DocumentStorageApp implements TerrenoPlugin {
198
270
  // POST basePath/ — Upload a file
199
271
  app.post(
200
272
  `${basePath}/`,
201
- ...adminGuard,
273
+ ...accessGuard,
274
+ ...uploadRateLimit,
202
275
  upload.single("file") as unknown as express.RequestHandler,
203
276
  asyncHandler(async (req: express.Request, res: express.Response) => {
204
277
  await assertFileUploadsEnabled(req, this.options.fileUploadsEnabled);
@@ -209,7 +282,7 @@ export class DocumentStorageApp implements TerrenoPlugin {
209
282
 
210
283
  const targetPrefix = (req.body.prefix as string) ?? "";
211
284
  const sanitizedFilename = file.originalname.replace(/[^a-zA-Z0-9._-]/g, "_");
212
- const gcsPath = `${this.prefix}${targetPrefix}${sanitizedFilename}`;
285
+ const gcsPath = `${this.prefixFor(req)}${targetPrefix}${sanitizedFilename}`;
213
286
 
214
287
  const gcsFile = this.bucket.file(gcsPath);
215
288
  await gcsFile.save(file.buffer, {
@@ -232,14 +305,14 @@ export class DocumentStorageApp implements TerrenoPlugin {
232
305
  // GET basePath/download/* — Stream file download
233
306
  app.get(
234
307
  `${basePath}/download/*filepath`,
235
- ...adminGuard,
308
+ ...accessGuard,
236
309
  asyncHandler(async (req: express.Request, res: express.Response) => {
237
310
  const filePath = normalizePathParam(req.params.filepath);
238
311
  if (!filePath) {
239
312
  throw new APIError({status: 400, title: "File path is required"});
240
313
  }
241
314
 
242
- const gcsPath = `${this.prefix}${filePath}`;
315
+ const gcsPath = `${this.prefixFor(req)}${filePath}`;
243
316
  const gcsFile = this.bucket.file(gcsPath);
244
317
 
245
318
  let metadata: Record<string, unknown>;
@@ -297,7 +370,7 @@ export class DocumentStorageApp implements TerrenoPlugin {
297
370
  // POST basePath/folder — Create a folder
298
371
  app.post(
299
372
  `${basePath}/folder`,
300
- ...adminGuard,
373
+ ...accessGuard,
301
374
  asyncHandler(async (req: express.Request, res: express.Response) => {
302
375
  const {folderName, prefix} = req.body as {folderName?: string; prefix?: string};
303
376
  if (!folderName) {
@@ -306,7 +379,7 @@ export class DocumentStorageApp implements TerrenoPlugin {
306
379
 
307
380
  const sanitizedName = folderName.replace(/[^a-zA-Z0-9._-]/g, "_");
308
381
  const targetPrefix = prefix ?? "";
309
- const gcsPath = `${this.prefix}${targetPrefix}${sanitizedName}/`;
382
+ const gcsPath = `${this.prefixFor(req)}${targetPrefix}${sanitizedName}/`;
310
383
 
311
384
  const gcsFile = this.bucket.file(gcsPath);
312
385
  await gcsFile.save(Buffer.alloc(0), {contentType: "application/x-directory"});
@@ -318,14 +391,14 @@ export class DocumentStorageApp implements TerrenoPlugin {
318
391
  // DELETE basePath/folder/* — Delete a folder and all its contents
319
392
  app.delete(
320
393
  `${basePath}/folder/*folderpath`,
321
- ...adminGuard,
394
+ ...accessGuard,
322
395
  asyncHandler(async (req: express.Request, res: express.Response) => {
323
396
  const folderPath = normalizePathParam(req.params.folderpath);
324
397
  if (!folderPath) {
325
398
  throw new APIError({status: 400, title: "Folder path is required"});
326
399
  }
327
400
 
328
- const gcsPrefix = `${this.prefix}${folderPath}`;
401
+ const gcsPrefix = `${this.prefixFor(req)}${folderPath}`;
329
402
  const [files] = await this.bucket.getFiles({prefix: gcsPrefix});
330
403
  await Promise.all(files.map((f) => f.delete({ignoreNotFound: true})));
331
404
 
@@ -336,14 +409,14 @@ export class DocumentStorageApp implements TerrenoPlugin {
336
409
  // DELETE basePath/* — Delete a file
337
410
  app.delete(
338
411
  `${basePath}/*filepath`,
339
- ...adminGuard,
412
+ ...accessGuard,
340
413
  asyncHandler(async (req: express.Request, res: express.Response) => {
341
414
  const filePath = normalizePathParam(req.params.filepath);
342
415
  if (!filePath) {
343
416
  throw new APIError({status: 400, title: "File path is required"});
344
417
  }
345
418
 
346
- const gcsPath = `${this.prefix}${filePath}`;
419
+ const gcsPath = `${this.prefixFor(req)}${filePath}`;
347
420
  const gcsFile = this.bucket.file(gcsPath);
348
421
 
349
422
  await gcsFile.delete({ignoreNotFound: true});