@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.680.daae24e.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 (117) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/CLAUDE.md +0 -40
  3. package/application/commands/entity-commands.js +60 -18
  4. package/application/commands/integration-commands.js +18 -71
  5. package/application/index.js +6 -2
  6. package/credential/repositories/credential-repository-documentdb.js +34 -0
  7. package/credential/repositories/credential-repository-interface.js +15 -0
  8. package/credential/repositories/credential-repository-mongo.js +23 -0
  9. package/credential/repositories/credential-repository-postgres.js +28 -0
  10. package/credential/use-cases/credential-operations-for-user.js +117 -0
  11. package/credential/use-cases/reauthorize-credential-for-user.js +66 -0
  12. package/database/documentdb-encryption-service.js +9 -22
  13. package/database/documentdb-utils.js +1 -4
  14. package/database/encryption/README.md +78 -14
  15. package/database/encryption/documentdb-encryption-service.md +78 -1
  16. package/database/encryption/encryption-config.js +240 -0
  17. package/database/encryption/encryption-schema-registry.js +41 -12
  18. package/database/encryption/field-encryption-service.js +69 -5
  19. package/database/encryption/integration-mapping-encryption.js +1 -1
  20. package/database/encryption/test-support/fake-ciphertext.js +15 -0
  21. package/database/prisma.js +11 -36
  22. package/database/use-cases/check-encryption-health-use-case.js +43 -52
  23. package/errors/index.js +0 -4
  24. package/generated/prisma-mongodb/edge.js +20 -4
  25. package/generated/prisma-mongodb/index-browser.js +17 -1
  26. package/generated/prisma-mongodb/index.d.ts +1543 -95
  27. package/generated/prisma-mongodb/index.js +20 -4
  28. package/generated/prisma-mongodb/package.json +1 -1
  29. package/generated/prisma-mongodb/schema.prisma +27 -0
  30. package/generated/prisma-mongodb/wasm.js +20 -4
  31. package/generated/prisma-postgresql/edge.js +20 -4
  32. package/generated/prisma-postgresql/index-browser.js +17 -1
  33. package/generated/prisma-postgresql/index.d.ts +1570 -89
  34. package/generated/prisma-postgresql/index.js +20 -4
  35. package/generated/prisma-postgresql/package.json +1 -1
  36. package/generated/prisma-postgresql/schema.prisma +26 -0
  37. package/generated/prisma-postgresql/wasm.js +20 -4
  38. package/handlers/WEBHOOKS.md +0 -29
  39. package/handlers/app-definition-loader.js +19 -8
  40. package/handlers/app-handler-helpers.js +25 -3
  41. package/handlers/backend-utils.js +31 -25
  42. package/handlers/middleware/admin-auth.js +14 -1
  43. package/handlers/routers/auth.js +11 -3
  44. package/handlers/routers/health.js +11 -4
  45. package/handlers/workers/integration-defined-workers.js +5 -2
  46. package/index.js +4 -4
  47. package/integrations/index.js +0 -4
  48. package/integrations/integration-base.js +0 -29
  49. package/integrations/integration-router.js +16 -23
  50. package/integrations/repositories/integration-mapping-repository-documentdb.js +0 -50
  51. package/integrations/repositories/integration-mapping-repository-interface.js +0 -15
  52. package/integrations/repositories/integration-mapping-repository-mongo.js +0 -29
  53. package/integrations/repositories/integration-mapping-repository-postgres.js +0 -30
  54. package/integrations/repositories/integration-mapping-repository.js +0 -29
  55. package/integrations/repositories/integration-repository-documentdb.js +0 -32
  56. package/integrations/repositories/integration-repository-interface.js +0 -30
  57. package/integrations/repositories/integration-repository-mongo.js +1 -53
  58. package/integrations/repositories/integration-repository-postgres.js +0 -58
  59. package/integrations/repositories/process-repository-mongo.js +1 -1
  60. package/integrations/use-cases/create-integration.js +19 -57
  61. package/integrations/use-cases/integration-operations-for-user.js +225 -0
  62. package/integrations/utils/map-integration-dto.js +1 -15
  63. package/management-api/create-management-api-router.js +49 -0
  64. package/management-api/error-response.js +116 -0
  65. package/management-api/management-api-config.js +82 -0
  66. package/management-api/meta-router.js +57 -0
  67. package/management-api/openapi/build-openapi.js +144 -0
  68. package/management-api/openapi/components.js +368 -0
  69. package/management-api/openapi/v1-operations.js +83 -0
  70. package/management-api/openapi/v2-operations.js +252 -0
  71. package/management-api/route-registry.js +294 -0
  72. package/management-api/test-support/http-client.js +39 -0
  73. package/management-api/use-cases/get-management-api-meta.js +57 -0
  74. package/management-api/v1-deprecation.js +120 -0
  75. package/management-api/v2/create-v2-router.js +85 -0
  76. package/management-api/v2/dependencies.js +256 -0
  77. package/management-api/v2/dto.js +123 -0
  78. package/management-api/v2/handlers/authorization.js +93 -0
  79. package/management-api/v2/handlers/credentials.js +29 -0
  80. package/management-api/v2/handlers/entities.js +74 -0
  81. package/management-api/v2/handlers/integrations.js +125 -0
  82. package/management-api/v2/handlers/proxy.js +34 -0
  83. package/management-api/v2/request.js +54 -0
  84. package/management-api/v2/test-support/fake-dependencies.js +103 -0
  85. package/modules/domain/authorization-session.js +144 -0
  86. package/modules/entity-type-registry.js +311 -0
  87. package/modules/index.js +6 -0
  88. package/modules/proxy/proxy-errors.js +20 -0
  89. package/modules/proxy/proxy-path.js +179 -0
  90. package/modules/proxy/proxy-policy.js +248 -0
  91. package/modules/repositories/authorization-session-repository-documentdb.js +112 -0
  92. package/modules/repositories/authorization-session-repository-factory.js +31 -0
  93. package/modules/repositories/authorization-session-repository-interface.js +47 -0
  94. package/modules/repositories/authorization-session-repository-prisma.js +87 -0
  95. package/modules/requester/proxy-request.js +244 -0
  96. package/modules/requester/requester.js +27 -2
  97. package/modules/tests/doubles/in-memory-authorization-session-repository.js +45 -0
  98. package/modules/use-cases/entity-operations-for-user.js +125 -0
  99. package/modules/use-cases/entity-types.js +115 -0
  100. package/modules/use-cases/execute-entity-proxy-request.js +239 -0
  101. package/modules/use-cases/get-authorization-requirements.js +100 -0
  102. package/modules/use-cases/get-entity-module-for-user.js +86 -0
  103. package/modules/use-cases/multi-step-authorization.js +302 -0
  104. package/modules/utils/map-module-dto.js +3 -5
  105. package/package.json +5 -5
  106. package/prisma-mongodb/schema.prisma +27 -0
  107. package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +28 -0
  108. package/prisma-postgresql/schema.prisma +26 -0
  109. package/types/index.d.ts +1 -0
  110. package/types/modules/index.d.ts +58 -0
  111. package/user/tests/doubles/test-user-repository.js +1 -1
  112. package/user/use-cases/get-user-from-bearer-token.js +2 -7
  113. package/errors/mapping-already-exists-error.js +0 -14
  114. package/integrations/use-cases/add-entities-to-integration.js +0 -92
  115. package/integrations/use-cases/remove-entities-from-integration.js +0 -70
  116. package/integrations/utils/assert-entity-ids-input.js +0 -42
  117. package/modules/utils/to-credential-id.js +0 -14
@@ -62,7 +62,7 @@ class CreateIntegration {
62
62
 
63
63
  // A concurrent request may have created a matching row between the
64
64
  // lookup above and this insert; re-check before any side effects run.
65
- const survivor = await this._findSurvivor(
65
+ const survivor = await this._findDuplicate(
66
66
  userId,
67
67
  config?.type,
68
68
  entities
@@ -135,68 +135,30 @@ class CreateIntegration {
135
135
  return mapIntegrationClassToIntegrationDTO(integrationInstance);
136
136
  }
137
137
 
138
- async _findMatches(userId, type, entityIds) {
138
+ async _findDuplicate(userId, type, entityIds) {
139
139
  const candidates =
140
140
  await this.integrationRepository.findIntegrationsByUserId(userId);
141
- const target = new Set((entityIds ?? []).map(String));
142
-
143
- const live = candidates.filter(
144
- (integration) =>
145
- // An IN_DELETION row is either mid-teardown or a zombie left
146
- // behind by a failed deleteIntegrationById call — never a live
147
- // integration. Treating it as a duplicate would hand a
148
- // reinstall attempt a row nothing will ever move out of
149
- // IN_DELETION, silently discarded by the queue worker forever.
150
- // Let a fresh create proceed instead; the zombie is cleaned up
151
- // out-of-band, matching how teardown failures are already
152
- // handled here.
153
- integration.status !== 'IN_DELETION' &&
154
- integration.config?.type === type
155
- );
156
- const entitySet = (integration) =>
157
- new Set((integration.entitiesIds ?? []).map(String));
158
-
159
- const exact = live.filter((integration) => {
160
- const current = entitySet(integration);
141
+ const target = [...(entityIds ?? [])].map(String).sort();
142
+
143
+ const matches = candidates.filter((integration) => {
144
+ // An IN_DELETION row is either mid-teardown or a zombie left
145
+ // behind by a failed deleteIntegrationById call — never a live
146
+ // integration. Treating it as a duplicate would hand a reinstall
147
+ // attempt a row nothing will ever move out of IN_DELETION,
148
+ // silently discarded by the queue worker forever. Let a fresh
149
+ // create proceed instead; the zombie is cleaned up out-of-band,
150
+ // matching how teardown failures are already handled here.
151
+ if (integration.status === 'IN_DELETION') return false;
152
+ if (integration.config?.type !== type) return false;
153
+ const current = [...(integration.entitiesIds ?? [])]
154
+ .map(String)
155
+ .sort();
161
156
  return (
162
- current.size === target.size &&
163
- [...target].every((id) => current.has(id))
157
+ current.length === target.length &&
158
+ current.every((id, index) => id === target[index])
164
159
  );
165
160
  });
166
161
 
167
- // Entities may have been attached after create (addEntitiesToIntegration),
168
- // so a reconnect that sends the original entities must still find the
169
- // integration that now holds them, instead of creating a second one
170
- // that would share those entities.
171
- const supersets = live.filter((integration) => {
172
- const current = entitySet(integration);
173
- return [...target].every((id) => current.has(id));
174
- });
175
- return { exact, supersets: target.size ? supersets : [] };
176
- }
177
-
178
- async _findDuplicate(userId, type, entityIds) {
179
- const { exact, supersets } = await this._findMatches(
180
- userId,
181
- type,
182
- entityIds
183
- );
184
- if (exact.length) return this._pickOldest(exact);
185
- return supersets.length ? this._pickOldest(supersets) : null;
186
- }
187
-
188
- // After an insert the new row is itself an exact match, so the survivor
189
- // is the oldest of every exact or superset match (the new row included):
190
- // an older integration that already holds these entities always wins.
191
- async _findSurvivor(userId, type, entityIds) {
192
- const { exact, supersets } = await this._findMatches(
193
- userId,
194
- type,
195
- entityIds
196
- );
197
- // supersets includes the exact matches; it is empty only for an
198
- // empty entity set, where exact matching alone applies.
199
- const matches = supersets.length ? supersets : exact;
200
162
  return matches.length ? this._pickOldest(matches) : null;
201
163
  }
202
164
 
@@ -0,0 +1,225 @@
1
+ const Boom = require('@hapi/boom');
2
+ const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
3
+
4
+ /**
5
+ * Management API v2 integration operations. They put an ownership check
6
+ * (missing or foreign integration = 404) in front of the existing
7
+ * integration use cases, and pass the record's owner id on, so the
8
+ * organisation user model works the same as for entities.
9
+ */
10
+
11
+ const notFound = (integrationId) =>
12
+ Boom.notFound(`Integration ${integrationId} not found`, {
13
+ code: 'INTEGRATION_NOT_FOUND',
14
+ });
15
+
16
+ /** The integration record, or 404 when it is missing or not the caller's. */
17
+ class GetOwnedIntegrationRecord {
18
+ constructor({ integrationRepository }) {
19
+ this.integrationRepository = integrationRepository;
20
+ }
21
+
22
+ async execute(integrationId, user) {
23
+ let record = null;
24
+ try {
25
+ record = await this.integrationRepository.findIntegrationById(
26
+ integrationId
27
+ );
28
+ } catch (error) {
29
+ if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
30
+ throw notFound(integrationId);
31
+ }
32
+ throw error;
33
+ }
34
+ if (!record || !userOwns(user, record.userId)) {
35
+ throw notFound(integrationId);
36
+ }
37
+ return record;
38
+ }
39
+ }
40
+
41
+ /**
42
+ * Creates (or reuses) an integration between entities the caller owns.
43
+ * Unlike v1, the entities' ownership and the integration type are checked
44
+ * before anything is written.
45
+ */
46
+ class CreateIntegrationForUser {
47
+ constructor({ createIntegration, getEntityModuleForUser, integrationClasses }) {
48
+ this.createIntegration = createIntegration;
49
+ this.getEntityModuleForUser = getEntityModuleForUser;
50
+ this.integrationClasses = integrationClasses || [];
51
+ }
52
+
53
+ async execute({ entities, config }, user) {
54
+ if (!config || typeof config !== 'object' || typeof config.type !== 'string') {
55
+ throw Boom.badRequest('config.type is required', {
56
+ code: 'VALIDATION_ERROR',
57
+ details: { field: 'config.type' },
58
+ });
59
+ }
60
+ const known = this.integrationClasses.some(
61
+ (IntegrationClass) => IntegrationClass.Definition?.name === config.type
62
+ );
63
+ if (!known) {
64
+ throw Boom.badRequest(`Unknown integration type '${config.type}'`, {
65
+ code: 'UNKNOWN_INTEGRATION_TYPE',
66
+ });
67
+ }
68
+ if (
69
+ !Array.isArray(entities) ||
70
+ entities.some((id) => typeof id !== 'string' && typeof id !== 'number')
71
+ ) {
72
+ throw Boom.badRequest('entities must be an array of entity ids', {
73
+ code: 'VALIDATION_ERROR',
74
+ details: { field: 'entities' },
75
+ });
76
+ }
77
+ for (const entityId of entities) {
78
+ await this.getEntityModuleForUser.loadOwnedEntity(String(entityId), user);
79
+ }
80
+ return this.createIntegration.execute(
81
+ entities.map(String),
82
+ user.getId(),
83
+ config
84
+ );
85
+ }
86
+ }
87
+
88
+ /** The hydrated integration instance (modules loaded) for an owned integration. */
89
+ class GetIntegrationInstanceForUser {
90
+ constructor({ getOwnedIntegrationRecord, getIntegrationInstance }) {
91
+ this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
92
+ this.getIntegrationInstance = getIntegrationInstance;
93
+ }
94
+
95
+ async execute(integrationId, user) {
96
+ const record = await this.getOwnedIntegrationRecord.execute(
97
+ integrationId,
98
+ user
99
+ );
100
+ return this.getIntegrationInstance.execute(record.id, record.userId);
101
+ }
102
+ }
103
+
104
+ /** Replaces an owned integration's config. */
105
+ class UpdateIntegrationForUser {
106
+ constructor({ getOwnedIntegrationRecord, updateIntegration }) {
107
+ this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
108
+ this.updateIntegration = updateIntegration;
109
+ }
110
+
111
+ async execute(integrationId, user, config) {
112
+ if (!config || typeof config !== 'object' || Array.isArray(config)) {
113
+ throw Boom.badRequest('config must be an object', {
114
+ code: 'VALIDATION_ERROR',
115
+ details: { field: 'config' },
116
+ });
117
+ }
118
+ const record = await this.getOwnedIntegrationRecord.execute(
119
+ integrationId,
120
+ user
121
+ );
122
+ return this.updateIntegration.execute(record.id, record.userId, config);
123
+ }
124
+ }
125
+
126
+ /** Deletes an owned integration (runs its onDelete hooks). */
127
+ class RemoveIntegrationForUser {
128
+ constructor({ getOwnedIntegrationRecord, deleteIntegrationForUser }) {
129
+ this.getOwnedIntegrationRecord = getOwnedIntegrationRecord;
130
+ this.deleteIntegrationForUser = deleteIntegrationForUser;
131
+ }
132
+
133
+ async execute(integrationId, user) {
134
+ const record = await this.getOwnedIntegrationRecord.execute(
135
+ integrationId,
136
+ user
137
+ );
138
+ await this.deleteIntegrationForUser.execute(record.id, record.userId);
139
+ }
140
+ }
141
+
142
+ /**
143
+ * Sends one of the framework's user-facing events (GET_CONFIG_OPTIONS,
144
+ * GET_USER_ACTIONS, ...) to an owned integration. Handlers pass fixed event
145
+ * names only; caller-chosen action ids go through RunIntegrationActionForUser.
146
+ */
147
+ class SendIntegrationEventForUser {
148
+ constructor({ getIntegrationInstanceForUser }) {
149
+ this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
150
+ }
151
+
152
+ async execute(integrationId, user, event, payload) {
153
+ const instance = await this.getIntegrationInstanceForUser.execute(
154
+ integrationId,
155
+ user
156
+ );
157
+ return instance.send(event, payload);
158
+ }
159
+ }
160
+
161
+ /**
162
+ * Runs a user action on an owned integration. Unlike v1, the action id must
163
+ * be one the integration lists as a user action (static USER_ACTION events
164
+ * or its dynamic user actions), so a caller cannot fire internal events such
165
+ * as lifecycle hooks.
166
+ */
167
+ class RunIntegrationActionForUser {
168
+ constructor({ getIntegrationInstanceForUser }) {
169
+ this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
170
+ }
171
+
172
+ async execute(integrationId, user, actionId, payload) {
173
+ const instance = await this.getIntegrationInstanceForUser.execute(
174
+ integrationId,
175
+ user
176
+ );
177
+ const actions =
178
+ typeof instance.loadUserActions === 'function'
179
+ ? await instance.loadUserActions()
180
+ : {};
181
+ if (!actions || !Object.prototype.hasOwnProperty.call(actions, actionId)) {
182
+ throw Boom.notFound(
183
+ `Integration ${integrationId} has no user action '${actionId}'`,
184
+ { code: 'ACTION_NOT_FOUND' }
185
+ );
186
+ }
187
+ return instance.send(actionId, payload);
188
+ }
189
+ }
190
+
191
+ /**
192
+ * Runs the integration's auth test and reconciles its status. Returns the
193
+ * errors recorded during the test.
194
+ */
195
+ class TestIntegrationAuthForUser {
196
+ constructor({ getIntegrationInstanceForUser }) {
197
+ this.getIntegrationInstanceForUser = getIntegrationInstanceForUser;
198
+ }
199
+
200
+ /** @returns {Promise<{ ok: boolean, errors: Array<Object> }>} */
201
+ async execute(integrationId, user) {
202
+ const instance = await this.getIntegrationInstanceForUser.execute(
203
+ integrationId,
204
+ user
205
+ );
206
+ const start = Date.now();
207
+ const authPassed = await instance.testAuth();
208
+ await instance.reconcileAuthStatus(authPassed);
209
+ const errors = (instance.record?.messages?.errors || []).filter(
210
+ ({ timestamp }) => timestamp >= start
211
+ );
212
+ return { ok: Boolean(authPassed) && errors.length === 0, errors };
213
+ }
214
+ }
215
+
216
+ module.exports = {
217
+ GetOwnedIntegrationRecord,
218
+ CreateIntegrationForUser,
219
+ GetIntegrationInstanceForUser,
220
+ UpdateIntegrationForUser,
221
+ RemoveIntegrationForUser,
222
+ SendIntegrationEventForUser,
223
+ RunIntegrationActionForUser,
224
+ TestIntegrationAuthForUser,
225
+ };
@@ -20,18 +20,4 @@ function mapIntegrationClassToIntegrationDTO(integration) {
20
20
  }
21
21
 
22
22
 
23
- const getModulesDefinitionFromIntegrationClasses = (integrationClasses) => {
24
- return [
25
- ...new Set(
26
- integrationClasses
27
- .map((integration) =>
28
- Object.values(integration.Definition.modules).map(
29
- (module) => module.definition
30
- )
31
- )
32
- .flat()
33
- ),
34
- ];
35
- };
36
-
37
- module.exports = { mapIntegrationClassToIntegrationDTO, getModulesDefinitionFromIntegrationClasses };
23
+ module.exports = { mapIntegrationClassToIntegrationDTO };
@@ -0,0 +1,49 @@
1
+ const express = require('express');
2
+ const { resolveManagementApiConfig } = require('./management-api-config');
3
+ const {
4
+ createV1DeprecationRouter,
5
+ createV1DisabledRouter,
6
+ } = require('./v1-deprecation');
7
+
8
+ /**
9
+ * The Management API served by the auth Lambda (ADR-053): v2 under /api/v2
10
+ * and the frozen, deprecated v1 at the unprefixed paths. With
11
+ * `managementApi.v1: false` the v1 handlers are never built and the v1 paths
12
+ * answer 410.
13
+ *
14
+ * @param {Object} [params]
15
+ * @param {Object} [params.appDefinition] - defaults to loadAppDefinition().
16
+ * @param {Function} [params.createV1Router] - defaults to createIntegrationRouter.
17
+ * @param {Function} [params.createV2Router] - defaults to createManagementApiV2Router.
18
+ */
19
+ function createManagementApiRouter({
20
+ appDefinition,
21
+ createV1Router,
22
+ createV2Router,
23
+ } = {}) {
24
+ const definition =
25
+ appDefinition ||
26
+ require('../handlers/app-definition-loader').loadAppDefinition();
27
+ const config = resolveManagementApiConfig(definition.managementApi);
28
+
29
+ const buildV1 =
30
+ createV1Router ||
31
+ require('../integrations/integration-router').createIntegrationRouter;
32
+ const buildV2 =
33
+ createV2Router ||
34
+ require('./v2/create-v2-router').createManagementApiV2Router;
35
+
36
+ const router = express.Router();
37
+ router.use(buildV2({ appDefinition: definition, config }));
38
+
39
+ if (config.v1) {
40
+ router.use(createV1DeprecationRouter());
41
+ router.use(buildV1());
42
+ } else {
43
+ router.use(createV1DisabledRouter());
44
+ }
45
+
46
+ return router;
47
+ }
48
+
49
+ module.exports = { createManagementApiRouter };
@@ -0,0 +1,116 @@
1
+ const Boom = require('@hapi/boom');
2
+
3
+ /**
4
+ * Error responses for the HTTP boundary (handlers/app-handler-helpers.js).
5
+ *
6
+ * - v1 and other unversioned routes keep their historical body:
7
+ * `{ error: message }` for 4xx, `{ error: 'Internal Server Error' }` for 5xx.
8
+ * - Management API v2 and /api/meta answer `{ error: { code, message, details? } }`
9
+ * and carry `Frigg-API-Version: 2` even when the error happened before any
10
+ * v2 router ran (for example a body-parser failure).
11
+ */
12
+
13
+ const API_VERSION_HEADER = 'Frigg-API-Version';
14
+
15
+ const CODE_BY_STATUS = {
16
+ 400: 'BAD_REQUEST',
17
+ 401: 'UNAUTHORIZED',
18
+ 403: 'FORBIDDEN',
19
+ 404: 'NOT_FOUND',
20
+ 405: 'METHOD_NOT_ALLOWED',
21
+ 409: 'CONFLICT',
22
+ 410: 'GONE',
23
+ 413: 'PAYLOAD_TOO_LARGE',
24
+ 415: 'UNSUPPORTED_MEDIA_TYPE',
25
+ 422: 'UNPROCESSABLE_ENTITY',
26
+ 429: 'RATE_LIMITED',
27
+ 500: 'INTERNAL_ERROR',
28
+ 501: 'NOT_IMPLEMENTED',
29
+ 502: 'BAD_GATEWAY',
30
+ 503: 'SERVICE_UNAVAILABLE',
31
+ 504: 'GATEWAY_TIMEOUT',
32
+ };
33
+
34
+ // body-parser (via http-errors) tags its failures with `type`.
35
+ const CODE_BY_BODY_PARSER_TYPE = {
36
+ 'entity.parse.failed': 'INVALID_JSON',
37
+ 'entity.too.large': 'PAYLOAD_TOO_LARGE',
38
+ 'encoding.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
39
+ 'charset.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
40
+ 'request.aborted': 'BAD_REQUEST',
41
+ };
42
+
43
+ /** True for paths that use the v2 error contract. */
44
+ function isVersionedManagementApiPath(path = '') {
45
+ return (
46
+ path === '/api/v2' ||
47
+ path.startsWith('/api/v2/') ||
48
+ path === '/api/meta' ||
49
+ path.startsWith('/api/meta/')
50
+ );
51
+ }
52
+
53
+ /**
54
+ * The HTTP status for an error. Boom errors carry theirs. Other errors are
55
+ * trusted only when they declare a client error as safe to expose, as
56
+ * http-errors (and so body-parser) does; anything else is a 500, so an
57
+ * upstream FetchError's `statusCode` is never mistaken for ours.
58
+ */
59
+ function resolveStatusCode(err) {
60
+ if (err?.isBoom) return err.output.statusCode;
61
+ const status = err?.status ?? err?.statusCode;
62
+ if (
63
+ err?.expose === true &&
64
+ Number.isInteger(status) &&
65
+ status >= 400 &&
66
+ status < 500
67
+ ) {
68
+ return status;
69
+ }
70
+ return 500;
71
+ }
72
+
73
+ /** Normalises any thrown value into a Boom error with the right status. */
74
+ function toBoom(err) {
75
+ if (err?.isBoom) return err;
76
+ const error = err instanceof Error ? err : new Error(String(err));
77
+ return Boom.boomify(error, { statusCode: resolveStatusCode(err) });
78
+ }
79
+
80
+ /** The v2 error body for a Boom error. */
81
+ function toV2ErrorBody(boomError) {
82
+ const statusCode = boomError.output.statusCode;
83
+ const data =
84
+ boomError.data && typeof boomError.data === 'object'
85
+ ? boomError.data
86
+ : {};
87
+ const exposeServerError = statusCode >= 500 && data.expose === true;
88
+
89
+ const code =
90
+ (typeof data.code === 'string' && data.code) ||
91
+ CODE_BY_BODY_PARSER_TYPE[boomError.type] ||
92
+ CODE_BY_STATUS[statusCode] ||
93
+ (statusCode >= 500 ? 'INTERNAL_ERROR' : 'BAD_REQUEST');
94
+
95
+ const message =
96
+ statusCode < 500 || exposeServerError
97
+ ? boomError.message
98
+ : 'Internal Server Error';
99
+
100
+ const body = { code, message };
101
+ if (
102
+ data.details !== undefined &&
103
+ (statusCode < 500 || exposeServerError)
104
+ ) {
105
+ body.details = data.details;
106
+ }
107
+ return { error: body };
108
+ }
109
+
110
+ module.exports = {
111
+ API_VERSION_HEADER,
112
+ isVersionedManagementApiPath,
113
+ resolveStatusCode,
114
+ toBoom,
115
+ toV2ErrorBody,
116
+ };
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Resolves `appDefinition.managementApi` (ADR-052, ADR-053).
3
+ *
4
+ * ```js
5
+ * managementApi: {
6
+ * v1: false, // drop the deprecated v1 routes (default true)
7
+ * proxy: {
8
+ * enable: true, // entity proxy, off by default (ADR-052)
9
+ * timeoutMs: 25000, // whole upstream call, lower only
10
+ * maxRequestBytes: 1048576,
11
+ * maxResponseBytes: 5242880, // lower only
12
+ * modules: { // per-module allow-list override
13
+ * hubspot: { allow: 'module' },
14
+ * erp: { allow: [{ method: 'GET', path: '/v1/customers/**' }] },
15
+ * },
16
+ * },
17
+ * }
18
+ * ```
19
+ */
20
+
21
+ // ADR-052 §7. API Gateway HTTP APIs time out at 30s and Lambda responses cap
22
+ // at 6MB, so the timeout and response defaults are also ceilings: an app may
23
+ // lower them, not raise them.
24
+ const DEFAULT_PROXY_LIMITS = Object.freeze({
25
+ timeoutMs: 25_000,
26
+ maxRequestBytes: 1024 * 1024,
27
+ maxResponseBytes: 5 * 1024 * 1024,
28
+ });
29
+
30
+ // The request-body limit has no platform ceiling below API Gateway's 10MB, so
31
+ // an app may raise it up to that.
32
+ const MAX_REQUEST_BYTES_CEILING = 10 * 1024 * 1024;
33
+
34
+ const isPositiveNumber = (value) =>
35
+ typeof value === 'number' && Number.isFinite(value) && value > 0;
36
+
37
+ /** The value, capped at `ceiling`; the ceiling when the value is unusable. */
38
+ function positiveCapped(value, ceiling) {
39
+ return isPositiveNumber(value) ? Math.min(value, ceiling) : ceiling;
40
+ }
41
+
42
+ /** The value, capped at `ceiling`; `fallback` when the value is unusable. */
43
+ function positiveOr(value, fallback, ceiling) {
44
+ return isPositiveNumber(value) ? Math.min(value, ceiling) : fallback;
45
+ }
46
+
47
+ /**
48
+ * @param {Object} [managementApi] - `appDefinition.managementApi`
49
+ * @returns {{ v1: boolean, proxy: { enable: boolean, timeoutMs: number, maxRequestBytes: number, maxResponseBytes: number, modules: Object } }}
50
+ */
51
+ function resolveManagementApiConfig(managementApi) {
52
+ const config =
53
+ managementApi && typeof managementApi === 'object' ? managementApi : {};
54
+ const proxy =
55
+ config.proxy && typeof config.proxy === 'object' ? config.proxy : {};
56
+
57
+ return {
58
+ v1: config.v1 !== false,
59
+ proxy: {
60
+ enable: proxy.enable === true,
61
+ timeoutMs: positiveCapped(
62
+ proxy.timeoutMs,
63
+ DEFAULT_PROXY_LIMITS.timeoutMs
64
+ ),
65
+ maxRequestBytes: positiveOr(
66
+ proxy.maxRequestBytes,
67
+ DEFAULT_PROXY_LIMITS.maxRequestBytes,
68
+ MAX_REQUEST_BYTES_CEILING
69
+ ),
70
+ maxResponseBytes: positiveCapped(
71
+ proxy.maxResponseBytes,
72
+ DEFAULT_PROXY_LIMITS.maxResponseBytes
73
+ ),
74
+ modules:
75
+ proxy.modules && typeof proxy.modules === 'object'
76
+ ? proxy.modules
77
+ : {},
78
+ },
79
+ };
80
+ }
81
+
82
+ module.exports = { resolveManagementApiConfig, DEFAULT_PROXY_LIMITS };
@@ -0,0 +1,57 @@
1
+ const { Router } = require('express');
2
+ const Boom = require('@hapi/boom');
3
+ const { resolveManagementApiConfig } = require('./management-api-config');
4
+ const {
5
+ GetManagementApiMeta,
6
+ } = require('./use-cases/get-management-api-meta');
7
+ const { isValidAdminApiKey } = require('../handlers/middleware/admin-auth');
8
+ const { version: coreVersion } = require('../package.json');
9
+ const { MANAGEMENT_API_VERSIONS } = require('./route-registry');
10
+ const { buildOpenApiDocument } = require('./openapi/build-openapi');
11
+
12
+ /**
13
+ * Version-neutral discovery routes (ADR-053 §4, §5), mounted on the DB-free
14
+ * health Lambda. No authentication: the admin API key only adds the core
15
+ * version to the response.
16
+ *
17
+ * @param {Object} params
18
+ * @param {Object} params.appDefinition - the loaded app definition
19
+ * (`managementApi` is read).
20
+ */
21
+ function createManagementApiMetaRouter({ appDefinition = {} } = {}) {
22
+ const config = resolveManagementApiConfig(appDefinition.managementApi);
23
+ const getMeta = new GetManagementApiMeta({ config, coreVersion });
24
+
25
+ const router = Router();
26
+
27
+ router.get('/api/meta', (req, res) => {
28
+ const isAdmin = isValidAdminApiKey(req.get('x-frigg-admin-api-key'));
29
+ res.set('Cache-Control', 'no-store');
30
+ res.json(getMeta.execute({ isAdmin }));
31
+ });
32
+
33
+ // One OpenAPI document per major (ADR-053 §5). Static per deployment, so
34
+ // built once; the entity proxy appears only when the app enables it.
35
+ const documents = new Map();
36
+ for (const major of Object.keys(MANAGEMENT_API_VERSIONS)) {
37
+ router.get(`/api/meta/openapi/v${major}.json`, (_req, res) => {
38
+ if (!documents.has(major)) {
39
+ documents.set(
40
+ major,
41
+ buildOpenApiDocument(major, { proxy: config.proxy.enable })
42
+ );
43
+ }
44
+ res.set('Cache-Control', 'public, max-age=300');
45
+ res.json(documents.get(major));
46
+ });
47
+ }
48
+
49
+ // Anything else under /api/meta is a v2-shaped 404, not Express's page.
50
+ router.use('/api/meta', (req, _res, next) => {
51
+ next(Boom.notFound(`No Management API meta route for ${req.method} ${req.originalUrl.split('?')[0]}`));
52
+ });
53
+
54
+ return router;
55
+ }
56
+
57
+ module.exports = { createManagementApiMetaRouter };