@friggframework/core 2.0.0--canary.690.d043f23.0 → 2.0.0--canary.691.2fd013b.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 (193) hide show
  1. package/CLAUDE.md +0 -28
  2. package/README.md +0 -105
  3. package/application/commands/integration-commands.js +10 -20
  4. package/application/commands/scheduler-commands.js +7 -11
  5. package/application/commands/user-commands.js +5 -17
  6. package/application/index.js +2 -6
  7. package/core/Worker.js +7 -31
  8. package/core/create-handler.js +0 -9
  9. package/credential/repositories/credential-repository-documentdb.js +0 -34
  10. package/credential/repositories/credential-repository-interface.js +0 -15
  11. package/credential/repositories/credential-repository-mongo.js +0 -23
  12. package/credential/repositories/credential-repository-postgres.js +0 -28
  13. package/database/config.js +24 -48
  14. package/database/documentdb-utils.js +0 -2
  15. package/database/encryption/encryption-schema-registry.js +12 -93
  16. package/database/prisma.js +2 -4
  17. package/errors/index.js +4 -0
  18. package/errors/mapping-already-exists-error.js +14 -0
  19. package/generated/prisma-mongodb/edge.js +4 -43
  20. package/generated/prisma-mongodb/index-browser.js +1 -40
  21. package/generated/prisma-mongodb/index.d.ts +111 -4739
  22. package/generated/prisma-mongodb/index.js +4 -43
  23. package/generated/prisma-mongodb/package.json +1 -1
  24. package/generated/prisma-mongodb/schema.prisma +0 -92
  25. package/generated/prisma-mongodb/wasm.js +4 -43
  26. package/generated/prisma-postgresql/edge.js +4 -43
  27. package/generated/prisma-postgresql/index-browser.js +1 -40
  28. package/generated/prisma-postgresql/index.d.ts +33 -4966
  29. package/generated/prisma-postgresql/index.js +4 -43
  30. package/generated/prisma-postgresql/package.json +1 -1
  31. package/generated/prisma-postgresql/schema.prisma +0 -87
  32. package/generated/prisma-postgresql/wasm.js +4 -43
  33. package/handlers/WEBHOOKS.md +29 -0
  34. package/handlers/app-definition-loader.js +19 -118
  35. package/handlers/app-handler-helpers.js +3 -25
  36. package/handlers/backend-utils.js +25 -31
  37. package/handlers/middleware/admin-auth.js +1 -14
  38. package/handlers/routers/auth.js +10 -46
  39. package/handlers/routers/health.js +4 -11
  40. package/handlers/routers/integration-defined-routers.js +92 -144
  41. package/handlers/routers/integration-webhook-routers.js +64 -102
  42. package/handlers/workers/integration-defined-workers.js +2 -5
  43. package/index.js +3 -63
  44. package/infrastructure/scheduler/index.js +6 -19
  45. package/infrastructure/scheduler/scheduler-service-factory.js +7 -55
  46. package/integrations/index.js +0 -1
  47. package/integrations/integration-base.js +29 -0
  48. package/integrations/integration-router.js +96 -131
  49. package/integrations/repositories/integration-mapping-repository-documentdb.js +50 -0
  50. package/integrations/repositories/integration-mapping-repository-interface.js +15 -0
  51. package/integrations/repositories/integration-mapping-repository-mongo.js +29 -0
  52. package/integrations/repositories/integration-mapping-repository-postgres.js +30 -0
  53. package/integrations/repositories/integration-mapping-repository.js +29 -0
  54. package/integrations/repositories/integration-repository-documentdb.js +3 -35
  55. package/integrations/repositories/integration-repository-interface.js +1 -17
  56. package/integrations/repositories/integration-repository-mongo.js +77 -60
  57. package/integrations/repositories/integration-repository-postgres.js +76 -62
  58. package/integrations/repositories/process-repository-mongo.js +1 -1
  59. package/integrations/tests/doubles/test-integration-repository.js +1 -12
  60. package/integrations/use-cases/create-integration.js +20 -55
  61. package/integrations/use-cases/get-integrations-for-user.js +40 -80
  62. package/integrations/use-cases/index.js +1 -5
  63. package/integrations/utils/map-integration-dto.js +14 -43
  64. package/modules/index.js +0 -14
  65. package/modules/module-factory.js +0 -12
  66. package/modules/module.js +2 -53
  67. package/modules/repositories/module-repository-documentdb.js +6 -51
  68. package/modules/repositories/module-repository-interface.js +2 -19
  69. package/modules/repositories/module-repository-mongo.js +74 -67
  70. package/modules/repositories/module-repository-postgres.js +74 -66
  71. package/modules/repositories/module-repository.js +1 -2
  72. package/modules/requester/requester.js +2 -27
  73. package/modules/use-cases/get-entities-for-user.js +13 -26
  74. package/modules/use-cases/get-entity-options-by-id.js +4 -10
  75. package/modules/use-cases/get-entity-options-by-type.js +1 -1
  76. package/modules/use-cases/get-module-instance-from-type.js +1 -1
  77. package/modules/use-cases/get-module.js +4 -10
  78. package/modules/use-cases/process-authorization-callback.js +19 -53
  79. package/modules/use-cases/refresh-entity-options.js +4 -10
  80. package/modules/use-cases/test-module-auth.js +4 -10
  81. package/package.json +5 -6
  82. package/prisma-mongodb/schema.prisma +0 -92
  83. package/prisma-postgresql/schema.prisma +0 -87
  84. package/queues/index.js +0 -25
  85. package/types/index.d.ts +0 -2
  86. package/user/repositories/user-repository-documentdb.js +2 -27
  87. package/user/repositories/user-repository-interface.js +0 -18
  88. package/user/repositories/user-repository-mongo.js +0 -24
  89. package/user/repositories/user-repository-postgres.js +0 -18
  90. package/user/tests/doubles/test-user-repository.js +1 -1
  91. package/user/use-cases/authenticate-user.js +1 -7
  92. package/user/use-cases/get-user-from-adopter-jwt.js +124 -95
  93. package/user/use-cases/get-user-from-bearer-token.js +7 -2
  94. package/user/use-cases/get-user-from-x-frigg-headers.js +80 -83
  95. package/user/user.js +1 -64
  96. package/credential/use-cases/credential-operations-for-user.js +0 -202
  97. package/credential/use-cases/reauthorize-credential-for-user.js +0 -73
  98. package/database/organization-where.js +0 -18
  99. package/database/unique-violation.js +0 -25
  100. package/extensions/bootstrap-runner.js +0 -43
  101. package/extensions/extension-loader.js +0 -167
  102. package/extensions/index.js +0 -41
  103. package/extensions/initialize-app.js +0 -123
  104. package/extensions/route-mounter.js +0 -103
  105. package/extensions/schema-composer.js +0 -188
  106. package/infrastructure/scheduler/netlify-scheduler-adapter.js +0 -216
  107. package/infrastructure/scheduler/scheduled-job-repository.js +0 -118
  108. package/integrations/repositories/integration-not-found.js +0 -14
  109. package/integrations/use-cases/integration-operations-for-user.js +0 -256
  110. package/integrations/use-cases/resolve-integration-ownership.js +0 -177
  111. package/management-api/create-management-api-router.js +0 -49
  112. package/management-api/error-response.js +0 -116
  113. package/management-api/management-api-config.js +0 -151
  114. package/management-api/meta-router.js +0 -57
  115. package/management-api/openapi/build-openapi.js +0 -144
  116. package/management-api/openapi/components.js +0 -414
  117. package/management-api/openapi/v1-operations.js +0 -83
  118. package/management-api/openapi/v2-operations.js +0 -264
  119. package/management-api/route-registry.js +0 -294
  120. package/management-api/test-support/http-client.js +0 -39
  121. package/management-api/use-cases/get-management-api-meta.js +0 -57
  122. package/management-api/v1-deprecation.js +0 -120
  123. package/management-api/v2/create-v2-router.js +0 -85
  124. package/management-api/v2/dependencies.js +0 -281
  125. package/management-api/v2/dto.js +0 -143
  126. package/management-api/v2/handlers/authorization.js +0 -94
  127. package/management-api/v2/handlers/credentials.js +0 -33
  128. package/management-api/v2/handlers/entities.js +0 -77
  129. package/management-api/v2/handlers/integrations.js +0 -128
  130. package/management-api/v2/handlers/proxy.js +0 -34
  131. package/management-api/v2/request.js +0 -85
  132. package/management-api/v2/test-support/fake-dependencies.js +0 -103
  133. package/modules/domain/authorization-session.js +0 -144
  134. package/modules/entity-scope.js +0 -15
  135. package/modules/entity-type-registry.js +0 -311
  136. package/modules/proxy/proxy-bases.js +0 -169
  137. package/modules/proxy/proxy-errors.js +0 -31
  138. package/modules/proxy/proxy-path.js +0 -183
  139. package/modules/proxy/proxy-policy.js +0 -265
  140. package/modules/repositories/authorization-session-repository-documentdb.js +0 -112
  141. package/modules/repositories/authorization-session-repository-factory.js +0 -31
  142. package/modules/repositories/authorization-session-repository-interface.js +0 -47
  143. package/modules/repositories/authorization-session-repository-prisma.js +0 -87
  144. package/modules/repositories/entity-not-found.js +0 -18
  145. package/modules/requester/proxy-request.js +0 -245
  146. package/modules/scope-config.js +0 -192
  147. package/modules/scope-policy.js +0 -112
  148. package/modules/scope-resolution.js +0 -288
  149. package/modules/scope-visibility.js +0 -247
  150. package/modules/tests/doubles/in-memory-authorization-session-repository.js +0 -45
  151. package/modules/tests/doubles/ownership-matching.js +0 -18
  152. package/modules/use-cases/authorize-entity-for-user.js +0 -61
  153. package/modules/use-cases/create-entity-from-credential.js +0 -113
  154. package/modules/use-cases/entity-operations-for-user.js +0 -162
  155. package/modules/use-cases/entity-types.js +0 -139
  156. package/modules/use-cases/execute-entity-proxy-request.js +0 -331
  157. package/modules/use-cases/get-authorization-requirements.js +0 -100
  158. package/modules/use-cases/get-entity-module-for-user.js +0 -113
  159. package/modules/use-cases/manage-access.js +0 -21
  160. package/modules/use-cases/multi-step-authorization.js +0 -329
  161. package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +0 -28
  162. package/prisma-postgresql/migrations/20261015000000_add_organization_membership/migration.sql +0 -26
  163. package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql +0 -25
  164. package/prisma-postgresql/migrations/20261017000000_add_scheduled_job/migration.sql +0 -28
  165. package/providers/index.js +0 -13
  166. package/providers/resolve-provider.js +0 -93
  167. package/queues/providers/index.js +0 -11
  168. package/queues/providers/netlify-background-provider.js +0 -150
  169. package/queues/providers/qstash-queue-provider.js +0 -199
  170. package/queues/providers/sqs-queue-provider.js +0 -70
  171. package/queues/queue-client-interface.js +0 -55
  172. package/queues/queue-message-auth.js +0 -187
  173. package/queues/queue-provider-factory.js +0 -101
  174. package/queues/queue-provider.js +0 -65
  175. package/queues/sqs-queue-client.js +0 -81
  176. package/types/modules/index.d.ts +0 -214
  177. package/types/user/index.d.ts +0 -134
  178. package/user/adopter-jwt-config.js +0 -177
  179. package/user/adopter-jwt-errors.js +0 -59
  180. package/user/adopter-token-verifier.js +0 -122
  181. package/user/app-user-helpers.js +0 -97
  182. package/user/create-user-authentication.js +0 -64
  183. package/user/membership.js +0 -51
  184. package/user/repositories/organization-membership-record.js +0 -19
  185. package/user/repositories/organization-membership-repository-documentdb.js +0 -106
  186. package/user/repositories/organization-membership-repository-factory.js +0 -42
  187. package/user/repositories/organization-membership-repository-interface.js +0 -57
  188. package/user/repositories/organization-membership-repository-mongo.js +0 -13
  189. package/user/repositories/organization-membership-repository-postgres.js +0 -29
  190. package/user/repositories/organization-membership-repository-prisma.js +0 -81
  191. package/user/tests/doubles/adopter-jwt-fixtures.js +0 -220
  192. package/user/use-cases/ensure-organization-membership.js +0 -92
  193. package/user/use-cases/find-individual-users-by-organization.js +0 -54
@@ -1,264 +0,0 @@
1
- const { ref } = require('./components');
2
-
3
- /**
4
- * Per-operation documentation for Management API v2, keyed by the route
5
- * registry's operationId. Paths and methods come from the registry, never
6
- * from here, so the document cannot list a route the router does not serve.
7
- */
8
-
9
- const json = (schema) => ({ content: { 'application/json': { schema } } });
10
- const ok = (description, schema) => ({ description, ...(schema && json(schema)) });
11
- const body = (schema, required = true) => ({ required, ...json(schema) });
12
- const errors = (...names) =>
13
- Object.fromEntries(
14
- names.map((name) => {
15
- const status = {
16
- BadRequest: '400',
17
- Unauthorized: '401',
18
- Forbidden: '403',
19
- NotFound: '404',
20
- Conflict: '409',
21
- BadGateway: '502',
22
- }[name];
23
- return [status, { $ref: `#/components/responses/${name}` }];
24
- })
25
- );
26
- const query = (name, description, schema = { type: 'string' }, required = false) => ({
27
- name,
28
- in: 'query',
29
- required,
30
- description,
31
- schema,
32
- });
33
- const stepQuery = [
34
- query('step', 'Step number, 1-based (default 1)', { type: 'integer', minimum: 1 }),
35
- query('sessionId', 'Session from step 1; required for later steps'),
36
- ];
37
- // ADR-056 §3.4: the same two filters on every list that mixes ownership.
38
- const listFilters = [
39
- query('scope', 'Only records of this scope', { type: 'string', enum: ['individual', 'organization'] }),
40
- query('owner', 'Only the caller\'s own (`me`) or the active organization\'s (`org`)', { type: 'string', enum: ['me', 'org'] }),
41
- ];
42
- const anyJson = { description: 'Defined by the integration or module' };
43
-
44
- const V2_OPERATIONS = {
45
- // Integrations
46
- listIntegrations: {
47
- summary: "List the caller's integrations",
48
- description:
49
- 'Returns only `{ integrations }`: the caller\'s and the active organization\'s, created in that organization (ADR-056 §3.6). Each carries `scope`, `owner`, `organizationId` and `access`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
50
- parameters: listFilters,
51
- responses: { 200: ok('Integrations', ref('ListIntegrationsResponse')), ...errors('Unauthorized') },
52
- },
53
- listIntegrationOptions: {
54
- summary: 'List the integration types this app offers',
55
- responses: { 200: ok('Integration types', ref('ListIntegrationOptionsResponse')), ...errors('Unauthorized') },
56
- },
57
- createIntegration: {
58
- summary: 'Create an integration between entities the caller owns',
59
- description: 'An identical existing integration (same user, type and entities) is reused.',
60
- requestBody: body(ref('CreateIntegrationRequest')),
61
- responses: {
62
- 201: ok('Created (or reused) integration', ref('Integration')),
63
- ...errors('BadRequest', 'Unauthorized', 'NotFound'),
64
- },
65
- },
66
- getIntegration: {
67
- summary: 'Get an integration',
68
- responses: { 200: ok('Integration', ref('Integration')), ...errors('Unauthorized', 'NotFound') },
69
- },
70
- updateIntegration: {
71
- summary: "Replace an integration's config",
72
- requestBody: body(ref('UpdateIntegrationRequest')),
73
- responses: { 200: ok('Updated integration', ref('Integration')), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
74
- },
75
- deleteIntegration: {
76
- summary: 'Delete an integration',
77
- responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound') },
78
- },
79
- getIntegrationConfigOptions: {
80
- summary: 'Get config options (form schema) for an integration',
81
- responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
82
- },
83
- refreshIntegrationConfigOptions: {
84
- summary: 'Refresh config options with the current form values',
85
- requestBody: body({ type: 'object', additionalProperties: true }, false),
86
- responses: { 200: ok('Options', anyJson), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
87
- },
88
- listIntegrationActions: {
89
- summary: 'List user actions an integration offers',
90
- parameters: [query('actionType', 'Only actions of this userActionType')],
91
- responses: { 200: ok('User actions', anyJson), ...errors('Unauthorized', 'NotFound') },
92
- },
93
- getIntegrationActionOptions: {
94
- summary: 'Get the options form for a user action',
95
- requestBody: body({ type: 'object', additionalProperties: true }, false),
96
- responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
97
- },
98
- refreshIntegrationActionOptions: {
99
- summary: 'Refresh a user action options form',
100
- requestBody: body({ type: 'object', additionalProperties: true }, false),
101
- responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
102
- },
103
- runIntegrationAction: {
104
- summary: 'Run a user action',
105
- description: 'Only actions the integration lists as user actions can run; anything else is 404 ACTION_NOT_FOUND.',
106
- requestBody: body({ type: 'object', additionalProperties: true }, false),
107
- responses: { 200: ok('Action result', anyJson), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
108
- },
109
- testIntegrationAuth: {
110
- summary: "Test an integration's connections",
111
- responses: { 200: ok('Result', ref('AuthTestResult')), ...errors('Unauthorized', 'NotFound') },
112
- },
113
-
114
- // Entities
115
- listEntities: {
116
- summary: "List the caller's connected entities",
117
- description:
118
- "The active organization's entities and the caller's individual ones (ADR-056 §3.6): an individual entity belongs to the organization it was connected in, unless `ownership.individualAcross` is `all`. Each carries `scope`, `owner`, `organizationId` and `access`.",
119
- parameters: listFilters,
120
- responses: { 200: ok('Entities', ref('ListEntitiesResponse')), ...errors('Unauthorized') },
121
- },
122
- listEntityTypes: {
123
- summary: 'List the entity types (API modules) this app can connect',
124
- description:
125
- 'Every type registered in appDefinition.entities plus every module a declared integration binds. `usedBy` lists the integrations that bind each type; it is empty for a type registered without any integration.',
126
- responses: { 200: ok('Entity types', ref('ListEntityTypesResponse')), ...errors('Unauthorized') },
127
- },
128
- getEntityType: {
129
- summary: 'Describe an entity type',
130
- description:
131
- 'Includes `usedBy`, the integrations that bind the type (empty for a registry-only type).',
132
- responses: { 200: ok('Entity type', ref('EntityType')), ...errors('Unauthorized', 'NotFound') },
133
- },
134
- getEntityTypeRequirements: {
135
- summary: 'Describe one authorization step of an entity type',
136
- description: 'Read-only: does not start a session. Use GET /api/v2/authorize to start a flow.',
137
- parameters: [stepQuery[0]],
138
- responses: {
139
- 200: ok('Requirements', ref('AuthorizationRequirements')),
140
- ...errors('BadRequest', 'Unauthorized', 'NotFound'),
141
- },
142
- },
143
- getEntity: {
144
- summary: 'Get an entity',
145
- responses: { 200: ok('Entity', ref('Entity')), ...errors('Unauthorized', 'NotFound') },
146
- },
147
- deleteEntity: {
148
- summary: 'Delete an entity',
149
- description: 'Refused with 409 ENTITY_IN_USE while integrations use it. The credential stays.',
150
- responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound', 'Conflict') },
151
- },
152
- testEntityAuth: {
153
- summary: "Test an entity's stored credential",
154
- responses: { 200: ok('Result', ref('AuthTestResult')), ...errors('Unauthorized', 'NotFound') },
155
- },
156
- getEntityOptions: {
157
- summary: "Get an entity's options",
158
- responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
159
- },
160
- refreshEntityOptions: {
161
- summary: "Refresh an entity's options",
162
- requestBody: body({ type: 'object', additionalProperties: true }, false),
163
- responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
164
- },
165
- proxyEntityRequest: {
166
- summary: "Call the entity's API through Frigg (beta)",
167
- description:
168
- "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; `base` optionally names one of the module's several base URLs (default `default`; a name, never a URL), and allow-list rules match per base. Deny by default, only operations in the module's (or the app's) allow-list. ADR-056 §3.5: the caller needs use access to the entity in the active organization (an entity they cannot see there is 404), and the entity's scope must be in managementApi.proxy.scopes (default individual only; 403 PROXY_NOT_ALLOWED with details.reason 'scope', or 'access' for view-only access). The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
169
- requestBody: body(ref('ProxyRequest')),
170
- responses: {
171
- 200: ok('Upstream answer (the status mirrors the upstream status)', ref('ProxyResponse')),
172
- 400: ok('INVALID_PROXY_REQUEST, or PROXY_UNKNOWN_BASE (`base` is not one of the module\'s base names; the message lists them)', ref('ProxyError')),
173
- 401: ok('INVALID_CREDENTIALS or unauthenticated', ref('ProxyError')),
174
- 403: ok("PROXY_NOT_ALLOWED: not in the allow-list, or details.reason 'scope' / 'access'", ref('ProxyError')),
175
- 404: ok('Entity not found, or not visible in the active organization', ref('Error')),
176
- 413: ok('PAYLOAD_TOO_LARGE', ref('ProxyError')),
177
- 415: ok('UNSUPPORTED_MEDIA_TYPE', ref('ProxyError')),
178
- 429: ok('RATE_LIMITED (Retry-After passed through)', ref('ProxyError')),
179
- 502: ok('UPSTREAM_ERROR, NETWORK_ERROR or RESPONSE_TOO_LARGE', ref('ProxyError')),
180
- 504: ok('TIMEOUT', ref('ProxyError')),
181
- },
182
- },
183
-
184
- // Credentials
185
- listCredentials: {
186
- summary: "List the caller's credentials (masked)",
187
- description:
188
- 'A credential is listed through the entities that use it that the caller may see, so each organization lists only its own connections; one no entity uses is listed to its owner. Each carries `scope`, `owner`, `organizationId` and `access`, taken from who owns the credential.',
189
- parameters: listFilters,
190
- responses: { 200: ok('Credentials', ref('ListCredentialsResponse')), ...errors('Unauthorized') },
191
- },
192
- getCredential: {
193
- summary: 'Get a credential (masked)',
194
- responses: { 200: ok('Credential', ref('Credential')), ...errors('Unauthorized', 'NotFound') },
195
- },
196
- deleteCredential: {
197
- summary: 'Delete a credential',
198
- description: 'Entities that used it stay, with no credential, until re-authorized.',
199
- responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound') },
200
- },
201
- getCredentialReauthorizeRequirements: {
202
- summary: 'Start or continue re-authorizing a credential',
203
- parameters: stepQuery,
204
- responses: {
205
- 200: ok('Requirements', ref('AuthorizationRequirements')),
206
- ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict'),
207
- },
208
- },
209
- reauthorizeCredential: {
210
- summary: 'Submit a re-authorization step',
211
- requestBody: body(ref('ReauthorizeRequest')),
212
- responses: {
213
- 200: ok('Complete or pending', ref('AuthorizeResponse')),
214
- ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict', 'BadGateway'),
215
- },
216
- },
217
-
218
- // Authorization
219
- getAuthorizationRequirements: {
220
- summary: 'Start or continue an authorization',
221
- description:
222
- 'Single-step modules return their requirements. Multi-step modules start a session on step 1 (returned as sessionId); later steps need it and must be the current step.',
223
- parameters: [
224
- query('entityType', 'Module name', { type: 'string' }, true),
225
- ...stepQuery,
226
- query('state', 'OAuth state forwarded to the provider'),
227
- ],
228
- responses: {
229
- 200: ok('Requirements', ref('AuthorizationRequirements')),
230
- ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict'),
231
- },
232
- },
233
- authorize: {
234
- summary: 'Submit an authorization step',
235
- description:
236
- 'Answers { status: "complete", entity, credential } or { status: "pending", step, totalSteps, sessionId, requirements }.',
237
- requestBody: body(ref('AuthorizeRequest')),
238
- responses: {
239
- 200: ok('Complete or pending', ref('AuthorizeResponse')),
240
- ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict', 'BadGateway'),
241
- },
242
- },
243
- };
244
-
245
- const META_OPERATIONS = {
246
- getApiMeta: {
247
- summary: 'Supported API versions and capabilities',
248
- description: 'No authentication, no database. The core version is added for admin callers only.',
249
- security: [],
250
- responses: { 200: ok('Discovery document', ref('ApiMeta')) },
251
- },
252
- getOpenApiV1: {
253
- summary: 'OpenAPI document for Management API v1 (deprecated)',
254
- security: [],
255
- responses: { 200: ok('OpenAPI 3 document', { type: 'object' }) },
256
- },
257
- getOpenApiV2: {
258
- summary: 'OpenAPI document for Management API v2',
259
- security: [],
260
- responses: { 200: ok('OpenAPI 3 document', { type: 'object' }) },
261
- },
262
- };
263
-
264
- module.exports = { V2_OPERATIONS, META_OPERATIONS };
@@ -1,294 +0,0 @@
1
- /**
2
- * Management API route registry (ADR-053).
3
- *
4
- * The single source of truth for the Management API surface. Three consumers
5
- * read it, so they cannot drift apart:
6
- *
7
- * - the Express routers (v2 mounts its handlers by `operationId`; v1 gets its
8
- * deprecation headers from the v1 list),
9
- * - the OpenAPI documents served at /api/meta/openapi/v{n}.json,
10
- * - the API Gateway HTTP API routes that devtools generates
11
- * (`getGatewayRoutes`, used by base-definition-factory).
12
- *
13
- * Rules (ADR-053):
14
- * - v2 lives under `/api/v2/<resource>`. Gateway routes are declared per
15
- * resource, never `ANY /api/v2/{proxy+}`: `/api/v2/reports` (ADR-010) is
16
- * served by the admin-scripts Lambda and must not be shadowed.
17
- * - v1 is the frozen unprefixed surface. Its handlers live in
18
- * integrations/integration-router.js and do not change; this list mirrors
19
- * them (a contract test keeps the two equal).
20
- * - `/api/meta` is version-neutral and served by the DB-free `health` Lambda.
21
- *
22
- * This module must stay free of database, AWS and app-definition imports:
23
- * devtools loads it at build time.
24
- */
25
-
26
- /**
27
- * Supported Management API majors. `deprecatedAt` feeds the RFC 9745
28
- * `Deprecation` header; `sunset` (RFC 8594) stays null until a removal release
29
- * is scheduled.
30
- */
31
- const MANAGEMENT_API_VERSIONS = Object.freeze({
32
- 1: Object.freeze({
33
- status: 'deprecated',
34
- deprecatedAt: '2026-11-01',
35
- sunset: null,
36
- }),
37
- 2: Object.freeze({ status: 'stable' }),
38
- });
39
-
40
- const PREFERRED_API_VERSION = '2';
41
-
42
- /**
43
- * `/api/v2/<segment>` values no v2 route may take. `reports` belongs to the
44
- * admin-scripts Lambda (ADR-010); where it lives long term is open (ADR-053
45
- * §7), so it is reserved, kept out of the v2 OpenAPI document and out of the
46
- * /api/meta capabilities.
47
- */
48
- const RESERVED_V2_SEGMENTS = Object.freeze(['reports']);
49
-
50
- const V1_MIGRATION_DOCS_URL =
51
- 'https://docs.friggframework.org/api/migrate-v1-v2';
52
-
53
- /** Lambda functions (devtools names) that serve Management API routes. */
54
- const FUNCTIONS = Object.freeze({ AUTH: 'auth', HEALTH: 'health' });
55
-
56
- const route = (version, fn) => (definition) =>
57
- Object.freeze({ version, function: fn, ...definition });
58
-
59
- /**
60
- * The v1 routes registered by createIntegrationRouter(). `ANY` marks routes
61
- * registered with `router.all()`. Frozen: no behaviour change except the
62
- * deprecation headers.
63
- */
64
- const V1_ROUTES = Object.freeze(
65
- [
66
- { method: 'GET', path: '/api/integrations' },
67
- { method: 'POST', path: '/api/integrations' },
68
- { method: 'PATCH', path: '/api/integrations/:integrationId' },
69
- { method: 'DELETE', path: '/api/integrations/:integrationId' },
70
- {
71
- method: 'GET',
72
- path: '/api/integrations/:integrationId/config/options',
73
- },
74
- {
75
- method: 'POST',
76
- path: '/api/integrations/:integrationId/config/options/refresh',
77
- },
78
- { method: 'ANY', path: '/api/integrations/:integrationId/actions' },
79
- {
80
- method: 'ANY',
81
- path: '/api/integrations/:integrationId/actions/:actionId/options',
82
- },
83
- {
84
- method: 'POST',
85
- path: '/api/integrations/:integrationId/actions/:actionId/options/refresh',
86
- },
87
- {
88
- method: 'POST',
89
- path: '/api/integrations/:integrationId/actions/:actionId',
90
- },
91
- { method: 'GET', path: '/api/integrations/:integrationId' },
92
- { method: 'GET', path: '/api/integrations/:integrationId/test-auth' },
93
- { method: 'GET', path: '/api/authorize' },
94
- { method: 'POST', path: '/api/authorize' },
95
- { method: 'POST', path: '/api/entity' },
96
- { method: 'GET', path: '/api/entity/options/:credentialId' },
97
- { method: 'GET', path: '/api/entities/:entityId/test-auth' },
98
- { method: 'GET', path: '/api/entities/:entityId' },
99
- { method: 'POST', path: '/api/entities/:entityId/options' },
100
- { method: 'POST', path: '/api/entities/:entityId/options/refresh' },
101
- ].map(route('1', FUNCTIONS.AUTH))
102
- );
103
-
104
- /**
105
- * The v2 routes. Order matters: Express matches in this order, so literal
106
- * segments (`/options`, `/types`) come before `/:id` siblings.
107
- *
108
- * - `operationId` keys the handler in management-api/v2 and the OpenAPI
109
- * operation.
110
- * - `stability: 'beta'` marks routes that may still change in a core minor
111
- * (ADR-053 §2); it is published as `x-frigg-stability`.
112
- * - `capability` names the /api/meta capability a route belongs to.
113
- */
114
- const V2_ROUTES = Object.freeze(
115
- [
116
- // Integrations
117
- { operationId: 'listIntegrations', method: 'GET', path: '/api/v2/integrations', tag: 'Integrations' },
118
- { operationId: 'listIntegrationOptions', method: 'GET', path: '/api/v2/integrations/options', tag: 'Integrations' },
119
- { operationId: 'createIntegration', method: 'POST', path: '/api/v2/integrations', tag: 'Integrations' },
120
- { operationId: 'getIntegration', method: 'GET', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
121
- { operationId: 'updateIntegration', method: 'PATCH', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
122
- { operationId: 'deleteIntegration', method: 'DELETE', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
123
- { operationId: 'getIntegrationConfigOptions', method: 'GET', path: '/api/v2/integrations/:integrationId/config/options', tag: 'Integrations' },
124
- { operationId: 'refreshIntegrationConfigOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/config/options/refresh', tag: 'Integrations' },
125
- { operationId: 'listIntegrationActions', method: 'GET', path: '/api/v2/integrations/:integrationId/actions', tag: 'Integrations' },
126
- { operationId: 'getIntegrationActionOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId/options', tag: 'Integrations' },
127
- { operationId: 'refreshIntegrationActionOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId/options/refresh', tag: 'Integrations' },
128
- { operationId: 'runIntegrationAction', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId', tag: 'Integrations' },
129
- { operationId: 'testIntegrationAuth', method: 'GET', path: '/api/v2/integrations/:integrationId/test-auth', tag: 'Integrations' },
130
-
131
- // Entities
132
- { operationId: 'listEntities', method: 'GET', path: '/api/v2/entities', tag: 'Entities' },
133
- { operationId: 'listEntityTypes', method: 'GET', path: '/api/v2/entities/types', tag: 'Entities' },
134
- { operationId: 'getEntityType', method: 'GET', path: '/api/v2/entities/types/:entityType', tag: 'Entities' },
135
- { operationId: 'getEntityTypeRequirements', method: 'GET', path: '/api/v2/entities/types/:entityType/requirements', tag: 'Entities' },
136
- { operationId: 'getEntity', method: 'GET', path: '/api/v2/entities/:entityId', tag: 'Entities' },
137
- { operationId: 'deleteEntity', method: 'DELETE', path: '/api/v2/entities/:entityId', tag: 'Entities' },
138
- { operationId: 'testEntityAuth', method: 'GET', path: '/api/v2/entities/:entityId/test-auth', tag: 'Entities' },
139
- { operationId: 'getEntityOptions', method: 'GET', path: '/api/v2/entities/:entityId/options', tag: 'Entities' },
140
- { operationId: 'refreshEntityOptions', method: 'POST', path: '/api/v2/entities/:entityId/options/refresh', tag: 'Entities' },
141
- { operationId: 'proxyEntityRequest', method: 'POST', path: '/api/v2/entities/:entityId/proxy', tag: 'Entities', stability: 'beta', capability: 'entityProxy' },
142
-
143
- // Credentials
144
- { operationId: 'listCredentials', method: 'GET', path: '/api/v2/credentials', tag: 'Credentials', capability: 'credentials' },
145
- { operationId: 'getCredential', method: 'GET', path: '/api/v2/credentials/:credentialId', tag: 'Credentials', capability: 'credentials' },
146
- { operationId: 'deleteCredential', method: 'DELETE', path: '/api/v2/credentials/:credentialId', tag: 'Credentials', capability: 'credentials' },
147
- { operationId: 'getCredentialReauthorizeRequirements', method: 'GET', path: '/api/v2/credentials/:credentialId/reauthorize', tag: 'Credentials', capability: 'credentials' },
148
- { operationId: 'reauthorizeCredential', method: 'POST', path: '/api/v2/credentials/:credentialId/reauthorize', tag: 'Credentials', capability: 'credentials' },
149
-
150
- // Authorization (multi-step)
151
- { operationId: 'getAuthorizationRequirements', method: 'GET', path: '/api/v2/authorize', tag: 'Authorization', capability: 'multiStepAuthorize' },
152
- { operationId: 'authorize', method: 'POST', path: '/api/v2/authorize', tag: 'Authorization', capability: 'multiStepAuthorize' },
153
- ].map(route('2', FUNCTIONS.AUTH))
154
- );
155
-
156
- /** Version-neutral discovery routes, served without auth or database. */
157
- const META_ROUTES = Object.freeze(
158
- [
159
- { operationId: 'getApiMeta', method: 'GET', path: '/api/meta' },
160
- ...Object.keys(MANAGEMENT_API_VERSIONS).map((major) => ({
161
- operationId: `getOpenApiV${major}`,
162
- method: 'GET',
163
- path: `/api/meta/openapi/v${major}.json`,
164
- })),
165
- ].map(route(null, FUNCTIONS.HEALTH))
166
- );
167
-
168
- /**
169
- * Unversioned routes the auth Lambda serves next to the Management API
170
- * (core/handlers/routers/auth.js). The OAuth redirect is the provider's
171
- * callback target, so it is neither deprecated nor disabled with v1.
172
- */
173
- const AUTH_EXTRA_ROUTES = Object.freeze(
174
- [
175
- {
176
- operationId: 'oauthRedirect',
177
- method: 'GET',
178
- path: '/api/integrations/redirect/:appId',
179
- },
180
- ].map(route(null, FUNCTIONS.AUTH))
181
- );
182
-
183
- /**
184
- * The v2 routes an app serves. Routes tied to an opt-in capability (the entity
185
- * proxy, ADR-052) are left out unless the app enables it.
186
- *
187
- * @param {Object} [options]
188
- * @param {boolean} [options.proxy=false] - `managementApi.proxy.enable`
189
- */
190
- function listV2Routes({ proxy = false } = {}) {
191
- return V2_ROUTES.filter(
192
- (record) => proxy || record.capability !== 'entityProxy'
193
- );
194
- }
195
-
196
- /**
197
- * @param {Object} [options]
198
- * @param {boolean} [options.v1=true] - false drops the v1 routes
199
- * (`managementApi.v1: false` in the app definition).
200
- * @param {boolean} [options.proxy=false] - true keeps the entity proxy route.
201
- * @returns {Array<Object>} Every registered route record.
202
- */
203
- function listRoutes({ v1 = true, proxy = false } = {}) {
204
- return [
205
- ...(v1 ? V1_ROUTES : []),
206
- ...listV2Routes({ proxy }),
207
- ...META_ROUTES,
208
- ...AUTH_EXTRA_ROUTES,
209
- ];
210
- }
211
-
212
- /** `/api/v2/entities/:entityId` -> `/api/v2/entities/{entityId}` */
213
- function toGatewayPath(expressPath) {
214
- return expressPath.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
215
- }
216
-
217
- /**
218
- * The resource root a route is grouped under for API Gateway:
219
- * `/api/v2/<resource>` for v2, `/api/<resource>` for v1, `/api/meta` for meta.
220
- */
221
- function resourceRoot(record) {
222
- const segments = record.path.split('/').filter(Boolean);
223
- const depth = record.version === '2' ? 3 : 2;
224
- return `/${segments.slice(0, depth).join('/')}`;
225
- }
226
-
227
- /**
228
- * API Gateway HTTP API routes for the Management API, derived from the
229
- * registry. Each resource root gets an exact route when the root itself is
230
- * registered and a greedy `{proxy+}` route when deeper paths are. The auth
231
- * function uses `ANY` (as it always has, so CORS preflights reach Express);
232
- * the health function only serves GET.
233
- *
234
- * @param {Object} [options]
235
- * @param {boolean} [options.v1=true]
236
- * @param {boolean} [options.proxy=false]
237
- * @returns {Array<{function: string, method: string, path: string}>}
238
- */
239
- function getGatewayRoutes({ v1 = true, proxy = false } = {}) {
240
- const out = [];
241
- const seen = new Set();
242
- const add = (fn, method, path) => {
243
- const key = `${fn} ${method} ${path}`;
244
- if (seen.has(key)) return;
245
- seen.add(key);
246
- out.push({ function: fn, method, path });
247
- };
248
-
249
- const grouped = [
250
- ...(v1 ? V1_ROUTES : []),
251
- ...listV2Routes({ proxy }),
252
- ...META_ROUTES,
253
- ];
254
- const greedyRoots = new Set();
255
- for (const record of grouped) {
256
- const root = resourceRoot(record);
257
- const method = record.function === FUNCTIONS.AUTH ? 'ANY' : 'GET';
258
- if (record.path === root) {
259
- add(record.function, method, root);
260
- } else {
261
- add(record.function, method, `${root}/{proxy+}`);
262
- greedyRoots.add(`${record.function} ${root}`);
263
- }
264
- }
265
-
266
- // Extra routes get an exact route unless a greedy route on the same
267
- // function already covers them.
268
- for (const record of AUTH_EXTRA_ROUTES) {
269
- const covered = greedyRoots.has(
270
- `${record.function} ${resourceRoot(record)}`
271
- );
272
- if (!covered) {
273
- add(record.function, record.method, toGatewayPath(record.path));
274
- }
275
- }
276
-
277
- return out;
278
- }
279
-
280
- module.exports = {
281
- MANAGEMENT_API_VERSIONS,
282
- PREFERRED_API_VERSION,
283
- RESERVED_V2_SEGMENTS,
284
- V1_MIGRATION_DOCS_URL,
285
- FUNCTIONS,
286
- V1_ROUTES,
287
- V2_ROUTES,
288
- META_ROUTES,
289
- AUTH_EXTRA_ROUTES,
290
- listRoutes,
291
- listV2Routes,
292
- getGatewayRoutes,
293
- toGatewayPath,
294
- };
@@ -1,39 +0,0 @@
1
- /**
2
- * Test helper: send one real HTTP request to an Express app on an ephemeral
3
- * port and return { status, headers, body }. Real HTTP (not a mocked req/res)
4
- * so body parsing, the error boundary and headers behave as in Lambda.
5
- */
6
- async function request(app, { method = 'GET', path, headers = {}, body, rawBody } = {}) {
7
- const server = await new Promise((resolve) => {
8
- const s = app.listen(0, '127.0.0.1', () => resolve(s));
9
- });
10
- try {
11
- const init = { method, headers: { ...headers } };
12
- if (rawBody !== undefined) {
13
- init.body = rawBody;
14
- } else if (body !== undefined) {
15
- init.body = JSON.stringify(body);
16
- init.headers['content-type'] = 'application/json';
17
- }
18
- const res = await fetch(
19
- `http://127.0.0.1:${server.address().port}${path}`,
20
- init
21
- );
22
- const text = await res.text();
23
- let parsed = text;
24
- try {
25
- parsed = text ? JSON.parse(text) : undefined;
26
- } catch {
27
- // not JSON; keep the text
28
- }
29
- return {
30
- status: res.status,
31
- headers: Object.fromEntries(res.headers.entries()),
32
- body: parsed,
33
- };
34
- } finally {
35
- await new Promise((resolve) => server.close(resolve));
36
- }
37
- }
38
-
39
- module.exports = { request };
@@ -1,57 +0,0 @@
1
- const {
2
- MANAGEMENT_API_VERSIONS,
3
- PREFERRED_API_VERSION,
4
- listV2Routes,
5
- } = require('../route-registry');
6
-
7
- /**
8
- * Builds the GET /api/meta document (ADR-053 §4): the API majors this
9
- * deployment serves, their status and OpenAPI links, and the capability flags
10
- * clients feature-detect with. Reads configuration only: no database, no
11
- * network.
12
- */
13
- class GetManagementApiMeta {
14
- /**
15
- * @param {Object} params
16
- * @param {ReturnType<import('../management-api-config').resolveManagementApiConfig>} params.config
17
- * @param {string} params.coreVersion - @friggframework/core version, admin-only.
18
- */
19
- constructor({ config, coreVersion }) {
20
- this.config = config;
21
- this.coreVersion = coreVersion;
22
- }
23
-
24
- /**
25
- * @param {Object} [options]
26
- * @param {boolean} [options.isAdmin=false] - caller presented the admin key.
27
- */
28
- execute({ isAdmin = false } = {}) {
29
- const versions = {};
30
- for (const [major, info] of Object.entries(MANAGEMENT_API_VERSIONS)) {
31
- const disabled = major === '1' && !this.config.v1;
32
- versions[major] = {
33
- ...info,
34
- ...(disabled && { status: 'disabled' }),
35
- openapi: `/api/meta/openapi/v${major}.json`,
36
- };
37
- }
38
-
39
- // Capabilities come from the routes the app actually serves, so a flag
40
- // can never advertise a route that is not mounted.
41
- const capabilities = [
42
- ...new Set(
43
- listV2Routes({ proxy: this.config.proxy.enable })
44
- .map((r) => r.capability)
45
- .filter(Boolean)
46
- ),
47
- ].sort();
48
-
49
- return {
50
- api: { versions, preferred: PREFERRED_API_VERSION },
51
- capabilities,
52
- ...(isAdmin && { frigg: { coreVersion: this.coreVersion } }),
53
- };
54
- }
55
- }
56
-
57
- module.exports = { GetManagementApiMeta };