@terreno/api 57.9.0 → 57.11.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.
@@ -9,6 +9,25 @@ const plugins_1 = require("../plugins");
9
9
  const statements_1 = require("./statements");
10
10
  var statements_2 = require("./statements");
11
11
  Object.defineProperty(exports, "READ_ONLY_ROLE_PERMISSIONS", { enumerable: true, get: function () { return statements_2.READ_ONLY_ROLE_PERMISSIONS; } });
12
+ const observabilityAdminPermissionSpec = () => ({
13
+ aiDataset: [...statements_1.terrenoStatements.aiDataset],
14
+ aiEvaluator: [...statements_1.terrenoStatements.aiEvaluator],
15
+ aiExperiment: [...statements_1.terrenoStatements.aiExperiment],
16
+ aiPrompt: [...statements_1.terrenoStatements.aiPrompt],
17
+ aiReview: [...statements_1.terrenoStatements.aiReview],
18
+ aiTrace: [...statements_1.terrenoStatements.aiTrace],
19
+ });
20
+ const observabilityReadOnlyPermissionSpec = (statements) => {
21
+ const expanded = (0, exports.expandRolePermissions)(statements_1.READ_ONLY_ROLE_PERMISSIONS, statements);
22
+ const defaults = {};
23
+ for (const resource of statements_1.OBSERVABILITY_RBAC_RESOURCES) {
24
+ const actions = expanded[resource];
25
+ if (actions && actions.length > 0) {
26
+ defaults[resource] = [...actions];
27
+ }
28
+ }
29
+ return defaults;
30
+ };
12
31
  /**
13
32
  * Insert missing default roles. Existing unsealed roles are left unchanged so admin
14
33
  * customizations survive process restarts. Sealed roles are refreshed from code.
@@ -18,6 +37,14 @@ const upsertSeededRole = async (model, role, statements) => {
18
37
  const existing = await model.findOneOrNone({ name: role.name });
19
38
  if (existing) {
20
39
  if (!existing.isSealed) {
40
+ if (role.name === "admin") {
41
+ existing.permissions = (0, statements_1.mergeMissingResourcePermissions)(existing.permissions, permissions, statements_1.OBSERVABILITY_RBAC_RESOURCES);
42
+ await existing.save();
43
+ }
44
+ else if (role.name === "auditor") {
45
+ existing.permissions = (0, statements_1.mergeMissingResourcePermissions)(existing.permissions, observabilityReadOnlyPermissionSpec(statements), statements_1.OBSERVABILITY_RBAC_RESOURCES);
46
+ await existing.save();
47
+ }
21
48
  return;
22
49
  }
23
50
  existing.description = role.description;
@@ -72,6 +99,7 @@ exports.terrenoDefaultRoles = [
72
99
  adminAnnouncementImpression: ["read"],
73
100
  configuration: ["read", "update"],
74
101
  user: ["create", "list", "read", "update"],
102
+ ...observabilityAdminPermissionSpec(),
75
103
  },
76
104
  },
77
105
  {
@@ -1,4 +1,10 @@
1
1
  export declare const ADMIN_MODEL_ACCESS: readonly ["read", "write", "writeOwned"];
2
+ export declare const AI_PROMPT_ACTIONS: readonly ["list", "read", "create", "update", "promote", "playground"];
3
+ export declare const AI_TRACE_ACTIONS: readonly ["list", "read"];
4
+ export declare const AI_REVIEW_ACTIONS: readonly ["list", "read", "score", "assign"];
5
+ export declare const AI_EXPERIMENT_ACTIONS: readonly ["list", "read", "create", "promote"];
6
+ export declare const OBSERVABILITY_RBAC_RESOURCES: readonly ["aiPrompt", "aiTrace", "aiReview", "aiDataset", "aiExperiment", "aiEvaluator"];
7
+ export type ObservabilityRbacResource = (typeof OBSERVABILITY_RBAC_RESOURCES)[number];
2
8
  /** Resource/action that opens the admin panel. Other admin permissions do not grant entry. */
3
9
  export declare const ADMIN_PAGE_RESOURCE: "admin";
4
10
  export declare const ADMIN_PAGE_ACTION: "access";
@@ -15,6 +21,12 @@ export declare const terrenoStatements: {
15
21
  readonly adminConsentForm: readonly ["read", "write", "writeOwned"];
16
22
  readonly adminConsentResponse: readonly ["read", "write", "writeOwned"];
17
23
  readonly adminFeatureFlag: readonly ["read", "write", "writeOwned"];
24
+ readonly aiDataset: readonly ["create", "list", "read", "update", "delete"];
25
+ readonly aiEvaluator: readonly ["create", "list", "read", "update", "delete"];
26
+ readonly aiExperiment: readonly ["list", "read", "create", "promote"];
27
+ readonly aiPrompt: readonly ["list", "read", "create", "update", "promote", "playground"];
28
+ readonly aiReview: readonly ["list", "read", "score", "assign"];
29
+ readonly aiTrace: readonly ["list", "read"];
18
30
  readonly announcement: readonly ["create", "list", "read", "update", "delete"];
19
31
  readonly announcementAcknowledgement: readonly ["list", "read"];
20
32
  readonly announcementImpression: readonly ["list", "read"];
@@ -36,4 +48,7 @@ export declare const READ_ONLY_ROLE_PERMISSIONS: {
36
48
  };
37
49
  export type RolePermissionSpec = PermissionSet | "*" | typeof READ_ONLY_ROLE_PERMISSIONS;
38
50
  export declare const mergeStatements: <S extends Statements>(appStatements: S) => Statements & S;
51
+ export declare const terrenoStatementDescriptions: Record<string, Record<string, string>>;
52
+ /** Add missing actions for selected resources without removing consumer-defined grants. */
53
+ export declare const mergeMissingResourcePermissions: (existing: PermissionSet, defaults: PermissionSet, resources: readonly string[]) => PermissionSet;
39
54
  export declare const expandRolePermissions: (spec: RolePermissionSpec, statements: Statements, readActions: readonly string[]) => PermissionSet;
@@ -1,8 +1,27 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.expandRolePermissions = exports.mergeStatements = exports.READ_ONLY_ROLE_PERMISSIONS = exports.READ_ACTIONS = exports.terrenoStatements = exports.ORGANIZATION_ACTIONS = exports.ADMIN_PAGE_PERMISSION = exports.ADMIN_PAGE_ACTION = exports.ADMIN_PAGE_RESOURCE = exports.ADMIN_MODEL_ACCESS = void 0;
3
+ exports.expandRolePermissions = exports.mergeMissingResourcePermissions = exports.terrenoStatementDescriptions = exports.mergeStatements = exports.READ_ONLY_ROLE_PERMISSIONS = exports.READ_ACTIONS = exports.terrenoStatements = exports.ORGANIZATION_ACTIONS = exports.ADMIN_PAGE_PERMISSION = exports.ADMIN_PAGE_ACTION = exports.ADMIN_PAGE_RESOURCE = exports.OBSERVABILITY_RBAC_RESOURCES = exports.AI_EXPERIMENT_ACTIONS = exports.AI_REVIEW_ACTIONS = exports.AI_TRACE_ACTIONS = exports.AI_PROMPT_ACTIONS = exports.ADMIN_MODEL_ACCESS = void 0;
4
4
  const MODEL_CRUD = ["create", "list", "read", "update", "delete"];
5
5
  exports.ADMIN_MODEL_ACCESS = ["read", "write", "writeOwned"];
6
+ exports.AI_PROMPT_ACTIONS = [
7
+ "list",
8
+ "read",
9
+ "create",
10
+ "update",
11
+ "promote",
12
+ "playground",
13
+ ];
14
+ exports.AI_TRACE_ACTIONS = ["list", "read"];
15
+ exports.AI_REVIEW_ACTIONS = ["list", "read", "score", "assign"];
16
+ exports.AI_EXPERIMENT_ACTIONS = ["list", "read", "create", "promote"];
17
+ exports.OBSERVABILITY_RBAC_RESOURCES = [
18
+ "aiPrompt",
19
+ "aiTrace",
20
+ "aiReview",
21
+ "aiDataset",
22
+ "aiExperiment",
23
+ "aiEvaluator",
24
+ ];
6
25
  /** Resource/action that opens the admin panel. Other admin permissions do not grant entry. */
7
26
  exports.ADMIN_PAGE_RESOURCE = "admin";
8
27
  exports.ADMIN_PAGE_ACTION = "access";
@@ -27,6 +46,12 @@ exports.terrenoStatements = {
27
46
  adminConsentForm: exports.ADMIN_MODEL_ACCESS,
28
47
  adminConsentResponse: exports.ADMIN_MODEL_ACCESS,
29
48
  adminFeatureFlag: exports.ADMIN_MODEL_ACCESS,
49
+ aiDataset: MODEL_CRUD,
50
+ aiEvaluator: MODEL_CRUD,
51
+ aiExperiment: exports.AI_EXPERIMENT_ACTIONS,
52
+ aiPrompt: exports.AI_PROMPT_ACTIONS,
53
+ aiReview: exports.AI_REVIEW_ACTIONS,
54
+ aiTrace: exports.AI_TRACE_ACTIONS,
30
55
  announcement: MODEL_CRUD,
31
56
  announcementAcknowledgement: ["list", "read"],
32
57
  announcementImpression: ["list", "read"],
@@ -52,6 +77,63 @@ const mergeStatements = (appStatements) => {
52
77
  };
53
78
  };
54
79
  exports.mergeStatements = mergeStatements;
80
+ exports.terrenoStatementDescriptions = {
81
+ aiDataset: {
82
+ create: "Create datasets",
83
+ delete: "Delete datasets",
84
+ list: "List datasets",
85
+ read: "View dataset detail and items",
86
+ update: "Update datasets and items",
87
+ },
88
+ aiEvaluator: {
89
+ create: "Create evaluators",
90
+ delete: "Delete evaluators",
91
+ list: "List evaluators and templates",
92
+ read: "View evaluator detail",
93
+ update: "Update evaluators",
94
+ },
95
+ aiExperiment: {
96
+ create: "Start experiments and run estimates",
97
+ list: "List experiments",
98
+ promote: "Promote a passing prompt version to production",
99
+ read: "View experiment results",
100
+ },
101
+ aiPrompt: {
102
+ create: "Create prompts",
103
+ list: "List prompts",
104
+ playground: "Run the prompt playground",
105
+ promote: "Move production or staging labels",
106
+ read: "View prompt detail and versions",
107
+ update: "Create new prompt versions",
108
+ },
109
+ aiReview: {
110
+ assign: "Assign review items and enqueue traces for review",
111
+ list: "List the review queue",
112
+ read: "Open review items",
113
+ score: "Submit or skip review scores",
114
+ },
115
+ aiTrace: {
116
+ list: "List traces and observability status",
117
+ read: "View trace detail and run trace test helpers",
118
+ },
119
+ };
120
+ /** Add missing actions for selected resources without removing consumer-defined grants. */
121
+ const mergeMissingResourcePermissions = (existing, defaults, resources) => {
122
+ const merged = { ...existing };
123
+ for (const resource of resources) {
124
+ const defaultActions = defaults[resource];
125
+ if (!defaultActions || defaultActions.length === 0) {
126
+ continue;
127
+ }
128
+ const current = new Set(merged[resource] ?? []);
129
+ for (const action of defaultActions) {
130
+ current.add(action);
131
+ }
132
+ merged[resource] = [...current];
133
+ }
134
+ return merged;
135
+ };
136
+ exports.mergeMissingResourcePermissions = mergeMissingResourcePermissions;
55
137
  const expandRolePermissions = (spec, statements, readActions) => {
56
138
  if (spec === "*") {
57
139
  const expanded = {};
package/package.json CHANGED
@@ -11,7 +11,7 @@
11
11
  "@modelcontextprotocol/node": "^2.0.0",
12
12
  "@modelcontextprotocol/server": "^2.0.0",
13
13
  "@sentry/bun": "^10.39.0",
14
- "@terreno/test": "57.9.0",
14
+ "@terreno/test": "57.11.0",
15
15
  "@thream/socketio-jwt": "^3.1.4",
16
16
  "@types/qs": "^6.14.0",
17
17
  "ajv": "8.20.0",
@@ -48,7 +48,7 @@
48
48
  "devDependencies": {
49
49
  "@biomejs/biome": "^2.3.6",
50
50
  "@modelcontextprotocol/client": "^2.0.0",
51
- "@terreno/syncdb": "57.9.0",
51
+ "@terreno/syncdb": "57.11.0",
52
52
  "@types/bun": "^1.4.0",
53
53
  "@types/cors": "^2.8.17",
54
54
  "@types/express": "^5.0.6",
@@ -132,5 +132,5 @@
132
132
  "updateSnapshot": "bun test --update-snapshots"
133
133
  },
134
134
  "types": "dist/index.d.ts",
135
- "version": "57.9.0"
135
+ "version": "57.11.0"
136
136
  }
@@ -581,6 +581,44 @@ describe("array operation errors", () => {
581
581
  expect(res.body.detail).toContain("Access to PATCH");
582
582
  });
583
583
 
584
+ it("lets a later route handle non-ObjectId paths under the same prefix", async () => {
585
+ app.use(
586
+ "/ai",
587
+ modelRouter(FoodModel, {
588
+ allowAnonymous: true,
589
+ permissions: {
590
+ create: [],
591
+ delete: [],
592
+ list: [],
593
+ read: [],
594
+ update: [],
595
+ },
596
+ })
597
+ );
598
+ app.post("/ai/observability/evaluators", (_req, res) => {
599
+ res.status(201).json({data: {created: true}});
600
+ });
601
+ app.post("/ai/observability/experiments", (_req, res) => {
602
+ res.status(201).json({data: {started: true}});
603
+ });
604
+ _server = supertest(app);
605
+
606
+ const created = await _server
607
+ .post("/ai/observability/evaluators")
608
+ .send({name: "toxicity", target: "full trace"})
609
+ .expect(201);
610
+ expect(created.body.data.created).toBe(true);
611
+
612
+ const started = await _server
613
+ .post("/ai/observability/experiments")
614
+ .send({name: "Example Experiment"})
615
+ .expect(201);
616
+ expect(started.body.data.started).toBe(true);
617
+
618
+ const denied = await _server.post(`/ai/${apple._id}/tags`).send({tags: "organic"}).expect(405);
619
+ expect(denied.body.code).toBe("array-update-not-allowed");
620
+ });
621
+
584
622
  it("array operation on non-existent document returns 404", async () => {
585
623
  app.use(
586
624
  "/food",
@@ -284,7 +284,18 @@ describe("query and list methods", () => {
284
284
  it("list query params not in list", async () => {
285
285
  const res = await agent.get(`/food?ownerId=${admin._id}`).expect(400);
286
286
  expect(res.body.title).toBe("Query parameter not allowed");
287
- expect(res.body.detail).toBe("ownerId is not allowed as a query param.");
287
+ expect(res.body.detail).toContain("ownerId is not allowed as a query param.");
288
+ });
289
+
290
+ it("names the model and allowed queryFields when a filter field is missing", async () => {
291
+ const res = await agent.get(`/food?ownerId=${admin._id}`).expect(400);
292
+ expect(res.body.code).toBe("query-param-not-allowed");
293
+ expect(res.body.source).toEqual({parameter: "ownerId"});
294
+ expect(res.body.detail).toContain('Add "ownerId" to queryFields on the Food modelRouter');
295
+ expect(res.body.meta.queryParam).toBe("ownerId");
296
+ expect(res.body.meta.model).toBe("Food");
297
+ expect(Array.isArray(res.body.meta.allowedQueryFields)).toBe(true);
298
+ expect(res.body.meta.allowedQueryFields).not.toContain("ownerId");
288
299
  });
289
300
 
290
301
  it("list query by nested param", async () => {
@@ -487,18 +498,18 @@ describe("query and list methods", () => {
487
498
  .get(`/food?${qs.stringify({$and: [{ownerId: "healthy"}, {tags: "cheap"}]})}`)
488
499
  .expect(400);
489
500
  expect(res.body.title).toBe("Query parameter not allowed");
490
- expect(res.body.detail).toBe("ownerId is not allowed as a query param.");
501
+ expect(res.body.detail).toContain("ownerId is not allowed as a query param.");
491
502
  res = await agent
492
503
  .get(`/food?${qs.stringify({$and: [{tags: "cheap"}, {ownerId: "healthy"}]})}`)
493
504
  .expect(400);
494
505
  expect(res.body.title).toBe("Query parameter not allowed");
495
- expect(res.body.detail).toBe("ownerId is not allowed as a query param.");
506
+ expect(res.body.detail).toContain("ownerId is not allowed as a query param.");
496
507
 
497
508
  res = await agent
498
509
  .get(`/food?${qs.stringify({$or: [{tags: "cheap"}, {ownerId: "healthy"}]})}`)
499
510
  .expect(400);
500
511
  expect(res.body.title).toBe("Query parameter not allowed");
501
- expect(res.body.detail).toBe("ownerId is not allowed as a query param.");
512
+ expect(res.body.detail).toContain("ownerId is not allowed as a query param.");
502
513
  });
503
514
 
504
515
  it("query with a number", async () => {
package/src/api.ts CHANGED
@@ -496,10 +496,13 @@ const mergeDateRangeQueryParams = <T>(
496
496
  };
497
497
 
498
498
  // Ensures query params are allowed. Also checks nested query params when using $and/$or.
499
+ // The error names the field, the model, and the allowed list so a missing `queryFields`
500
+ // entry is obvious from the client (syncdb raises it as QueryFieldNotAllowedError).
499
501
  const checkQueryParamAllowed = (
500
502
  queryParam: string,
501
503
  queryParamValue: unknown,
502
- queryFields: string[] = []
504
+ queryFields: string[] = [],
505
+ modelName = "this model"
503
506
  ) => {
504
507
  // Cast for iteration through complex query values
505
508
  const complexValue = queryParamValue as Array<Record<string, unknown>>;
@@ -509,15 +512,20 @@ const checkQueryParamAllowed = (
509
512
  // Complex query of the form `$and: [{key1: value1}, {key2: value2}]`
510
513
  for (const subQuery of complexValue) {
511
514
  for (const subKey of Object.keys(subQuery)) {
512
- checkQueryParamAllowed(subKey, subQuery[subKey], queryFields);
515
+ checkQueryParamAllowed(subKey, subQuery[subKey], queryFields, modelName);
513
516
  }
514
517
  }
515
518
  return;
516
519
  }
517
520
  if (!queryFields.includes(queryParam)) {
521
+ const allowed = queryFields.length > 0 ? queryFields.join(", ") : "(none)";
518
522
  throw new BadRequestError({
519
523
  code: "query-param-not-allowed",
520
- detail: `${queryParam} is not allowed as a query param.`,
524
+ detail:
525
+ `${queryParam} is not allowed as a query param. ` +
526
+ `Add "${queryParam}" to queryFields on the ${modelName} modelRouter to filter on it. ` +
527
+ `Allowed: ${allowed}.`,
528
+ meta: {allowedQueryFields: [...queryFields], model: modelName, queryParam},
521
529
  source: {parameter: queryParam},
522
530
  title: "Query parameter not allowed",
523
531
  });
@@ -829,6 +837,22 @@ const _buildModelRouter = <T>(
829
837
  authenticateMiddleware(options.allowAnonymous),
830
838
  permissionMiddleware(model, options),
831
839
  listOpenApiMiddleware(model, options, routePath),
840
+ // Runs before query validation so a field missing from queryFields is always
841
+ // reported with this error, whatever the validator's settings.
842
+ (req: Request, _res: Response, next: NextFunction): void => {
843
+ for (const queryParam of Object.keys(req.query)) {
844
+ if (PAGINATION_QUERY_PARAMS.includes(queryParam)) {
845
+ continue;
846
+ }
847
+ checkQueryParamAllowed(
848
+ queryParam,
849
+ req.query[queryParam],
850
+ options.queryFields,
851
+ model.modelName
852
+ );
853
+ }
854
+ next();
855
+ },
832
856
  queryValidation,
833
857
  ],
834
858
  asyncHandler(async (req: Request, res: Response) => {
@@ -841,7 +865,12 @@ const _buildModelRouter = <T>(
841
865
  if (PAGINATION_QUERY_PARAMS.includes(queryParam)) {
842
866
  continue;
843
867
  }
844
- checkQueryParamAllowed(queryParam, req.query[queryParam], options.queryFields);
868
+ checkQueryParamAllowed(
869
+ queryParam,
870
+ req.query[queryParam],
871
+ options.queryFields,
872
+ model.modelName
873
+ );
845
874
 
846
875
  // Not sure if this is necessary or if mongoose does the right thing.
847
876
  if (req.query[queryParam] === "true") {
@@ -1375,15 +1404,36 @@ const _buildModelRouter = <T>(
1375
1404
  });
1376
1405
  };
1377
1406
 
1378
- const arrayPost = async (req: Request, res: Response) => {
1407
+ // Array routes are `/:id/:field`. A non-ObjectId id is another resource under the
1408
+ // same prefix (for example POST /ai/observability/evaluators), so leave the router
1409
+ // and let a later registration handle it.
1410
+ const continueUnlessDocumentId = (req: Request, next: NextFunction): boolean => {
1411
+ const id = req.params.id;
1412
+ if (typeof id === "string" && isValidObjectId(id)) {
1413
+ return false;
1414
+ }
1415
+ next("router");
1416
+ return true;
1417
+ };
1418
+
1419
+ const arrayPost = async (req: Request, res: Response, next: NextFunction) => {
1420
+ if (continueUnlessDocumentId(req, next)) {
1421
+ return;
1422
+ }
1379
1423
  return arrayOperation(req, res, "POST");
1380
1424
  };
1381
1425
 
1382
- const arrayPatch = async (req: Request, res: Response) => {
1426
+ const arrayPatch = async (req: Request, res: Response, next: NextFunction) => {
1427
+ if (continueUnlessDocumentId(req, next)) {
1428
+ return;
1429
+ }
1383
1430
  return arrayOperation(req, res, "PATCH");
1384
1431
  };
1385
1432
 
1386
- const arrayDelete = async (req: Request, res: Response) => {
1433
+ const arrayDelete = async (req: Request, res: Response, next: NextFunction) => {
1434
+ if (continueUnlessDocumentId(req, next)) {
1435
+ return;
1436
+ }
1387
1437
  return arrayOperation(req, res, "DELETE");
1388
1438
  };
1389
1439
  // Set up routes for managing array fields. Check if there any array fields to add this for.
package/src/index.ts CHANGED
@@ -118,6 +118,7 @@ export {
118
118
  } from "./notifications/notificationsBeforeSend";
119
119
  export * from "./notifiers/googleChatNotifier";
120
120
  export * from "./notifiers/slackNotifier";
121
+ export * from "./notifiers/slackWebApi";
121
122
  export * from "./notifiers/zoomNotifier";
122
123
  export * from "./openApiBuilder";
123
124
  export * from "./openApiCompat";