@friggframework/core 2.0.0--canary.704.6a606c3.0 → 2.0.0--canary.707.2702ff3.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 (213) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/CLAUDE.md +28 -40
  3. package/README.md +105 -0
  4. package/application/commands/entity-commands.js +60 -18
  5. package/application/commands/integration-commands.js +20 -73
  6. package/application/commands/scheduler-commands.js +11 -7
  7. package/application/commands/user-commands.js +17 -5
  8. package/application/index.js +6 -2
  9. package/core/Worker.js +31 -7
  10. package/core/create-handler.js +9 -0
  11. package/credential/repositories/credential-repository-documentdb.js +34 -0
  12. package/credential/repositories/credential-repository-interface.js +15 -0
  13. package/credential/repositories/credential-repository-mongo.js +23 -0
  14. package/credential/repositories/credential-repository-postgres.js +28 -0
  15. package/credential/use-cases/credential-operations-for-user.js +202 -0
  16. package/credential/use-cases/reauthorize-credential-for-user.js +73 -0
  17. package/database/config.js +48 -24
  18. package/database/documentdb-encryption-service.js +9 -22
  19. package/database/documentdb-utils.js +2 -0
  20. package/database/encryption/README.md +78 -14
  21. package/database/encryption/documentdb-encryption-service.md +78 -1
  22. package/database/encryption/encryption-config.js +219 -0
  23. package/database/encryption/encryption-schema-registry.js +121 -24
  24. package/database/encryption/field-encryption-service.js +69 -5
  25. package/database/encryption/integration-mapping-encryption.js +1 -1
  26. package/database/encryption/test-support/fake-ciphertext.js +15 -0
  27. package/database/organization-where.js +18 -0
  28. package/database/prisma.js +15 -38
  29. package/database/unique-violation.js +25 -0
  30. package/database/use-cases/check-encryption-health-use-case.js +43 -52
  31. package/errors/index.js +0 -4
  32. package/extensions/bootstrap-runner.js +43 -0
  33. package/extensions/extension-loader.js +230 -0
  34. package/extensions/index.js +44 -0
  35. package/extensions/initialize-app.js +123 -0
  36. package/extensions/prisma-composer.js +264 -0
  37. package/extensions/route-mounter.js +103 -0
  38. package/extensions/schema-composer.js +188 -0
  39. package/generated/prisma-mongodb/edge.js +43 -4
  40. package/generated/prisma-mongodb/index-browser.js +40 -1
  41. package/generated/prisma-mongodb/index.d.ts +4761 -133
  42. package/generated/prisma-mongodb/index.js +43 -4
  43. package/generated/prisma-mongodb/package.json +1 -1
  44. package/generated/prisma-mongodb/schema.prisma +92 -0
  45. package/generated/prisma-mongodb/wasm.js +43 -4
  46. package/generated/prisma-postgresql/edge.js +43 -4
  47. package/generated/prisma-postgresql/index-browser.js +40 -1
  48. package/generated/prisma-postgresql/index.d.ts +4961 -28
  49. package/generated/prisma-postgresql/index.js +43 -4
  50. package/generated/prisma-postgresql/package.json +1 -1
  51. package/generated/prisma-postgresql/schema.prisma +87 -0
  52. package/generated/prisma-postgresql/wasm.js +43 -4
  53. package/handlers/WEBHOOKS.md +0 -29
  54. package/handlers/app-definition-loader.js +128 -19
  55. package/handlers/app-handler-helpers.js +25 -3
  56. package/handlers/backend-utils.js +31 -25
  57. package/handlers/middleware/admin-auth.js +14 -1
  58. package/handlers/routers/auth.js +46 -10
  59. package/handlers/routers/health.js +13 -4
  60. package/handlers/routers/integration-defined-routers.js +144 -92
  61. package/handlers/routers/integration-webhook-routers.js +102 -64
  62. package/handlers/workers/integration-defined-workers.js +5 -2
  63. package/index.js +66 -3
  64. package/infrastructure/scheduler/eventbridge-scheduler-adapter.js +13 -67
  65. package/infrastructure/scheduler/index.js +19 -6
  66. package/infrastructure/scheduler/netlify-scheduler-adapter.js +216 -0
  67. package/infrastructure/scheduler/scheduled-job-repository.js +118 -0
  68. package/infrastructure/scheduler/scheduler-service-factory.js +55 -7
  69. package/integrations/index.js +1 -0
  70. package/integrations/integration-base.js +0 -29
  71. package/integrations/integration-router.js +131 -96
  72. package/integrations/repositories/integration-mapping-repository-documentdb.js +0 -50
  73. package/integrations/repositories/integration-mapping-repository-interface.js +0 -15
  74. package/integrations/repositories/integration-mapping-repository-mongo.js +0 -29
  75. package/integrations/repositories/integration-mapping-repository-postgres.js +0 -30
  76. package/integrations/repositories/integration-mapping-repository.js +0 -29
  77. package/integrations/repositories/integration-not-found.js +14 -0
  78. package/integrations/repositories/integration-repository-documentdb.js +35 -35
  79. package/integrations/repositories/integration-repository-interface.js +17 -31
  80. package/integrations/repositories/integration-repository-mongo.js +60 -129
  81. package/integrations/repositories/integration-repository-postgres.js +62 -134
  82. package/integrations/repositories/process-repository-mongo.js +1 -1
  83. package/integrations/schedule-config.js +80 -0
  84. package/integrations/tests/doubles/test-integration-repository.js +12 -1
  85. package/integrations/use-cases/create-integration.js +72 -75
  86. package/integrations/use-cases/dispatch-ongoing-syncs.js +100 -0
  87. package/integrations/use-cases/get-integrations-for-user.js +80 -40
  88. package/integrations/use-cases/index.js +7 -1
  89. package/integrations/use-cases/integration-operations-for-user.js +256 -0
  90. package/integrations/use-cases/resolve-integration-ownership.js +177 -0
  91. package/integrations/utils/map-integration-dto.js +43 -14
  92. package/management-api/create-management-api-router.js +49 -0
  93. package/management-api/error-response.js +116 -0
  94. package/management-api/management-api-config.js +151 -0
  95. package/management-api/meta-router.js +76 -0
  96. package/management-api/openapi/build-openapi.js +144 -0
  97. package/management-api/openapi/components.js +415 -0
  98. package/management-api/openapi/v1-operations.js +83 -0
  99. package/management-api/openapi/v2-operations.js +264 -0
  100. package/management-api/route-registry.js +411 -0
  101. package/management-api/test-support/http-client.js +39 -0
  102. package/management-api/use-cases/get-management-api-meta.js +57 -0
  103. package/management-api/v1-deprecation.js +120 -0
  104. package/management-api/v2/create-v2-router.js +85 -0
  105. package/management-api/v2/dependencies.js +281 -0
  106. package/management-api/v2/dto.js +143 -0
  107. package/management-api/v2/handlers/authorization.js +94 -0
  108. package/management-api/v2/handlers/credentials.js +33 -0
  109. package/management-api/v2/handlers/entities.js +77 -0
  110. package/management-api/v2/handlers/integrations.js +128 -0
  111. package/management-api/v2/handlers/proxy.js +34 -0
  112. package/management-api/v2/request.js +85 -0
  113. package/management-api/v2/test-support/fake-dependencies.js +103 -0
  114. package/modules/domain/authorization-session.js +144 -0
  115. package/modules/entity-scope.js +15 -0
  116. package/modules/entity-type-registry.js +311 -0
  117. package/modules/index.js +14 -0
  118. package/modules/module-factory.js +12 -0
  119. package/modules/module.js +53 -2
  120. package/modules/proxy/proxy-bases.js +169 -0
  121. package/modules/proxy/proxy-errors.js +31 -0
  122. package/modules/proxy/proxy-path.js +183 -0
  123. package/modules/proxy/proxy-policy.js +277 -0
  124. package/modules/repositories/authorization-session-repository-documentdb.js +112 -0
  125. package/modules/repositories/authorization-session-repository-factory.js +31 -0
  126. package/modules/repositories/authorization-session-repository-interface.js +47 -0
  127. package/modules/repositories/authorization-session-repository-prisma.js +87 -0
  128. package/modules/repositories/entity-not-found.js +18 -0
  129. package/modules/repositories/module-repository-documentdb.js +51 -6
  130. package/modules/repositories/module-repository-interface.js +19 -2
  131. package/modules/repositories/module-repository-mongo.js +67 -74
  132. package/modules/repositories/module-repository-postgres.js +66 -74
  133. package/modules/repositories/module-repository.js +2 -1
  134. package/modules/requester/proxy-request.js +245 -0
  135. package/modules/requester/requester.js +35 -5
  136. package/modules/scope-config.js +192 -0
  137. package/modules/scope-policy.js +112 -0
  138. package/modules/scope-resolution.js +288 -0
  139. package/modules/scope-visibility.js +247 -0
  140. package/modules/tests/doubles/in-memory-authorization-session-repository.js +45 -0
  141. package/modules/tests/doubles/ownership-matching.js +18 -0
  142. package/modules/use-cases/authorize-entity-for-user.js +61 -0
  143. package/modules/use-cases/create-entity-from-credential.js +113 -0
  144. package/modules/use-cases/entity-operations-for-user.js +162 -0
  145. package/modules/use-cases/entity-types.js +139 -0
  146. package/modules/use-cases/execute-entity-proxy-request.js +331 -0
  147. package/modules/use-cases/get-authorization-requirements.js +100 -0
  148. package/modules/use-cases/get-entities-for-user.js +26 -13
  149. package/modules/use-cases/get-entity-module-for-user.js +113 -0
  150. package/modules/use-cases/get-entity-options-by-id.js +10 -4
  151. package/modules/use-cases/get-entity-options-by-type.js +1 -1
  152. package/modules/use-cases/get-module-instance-from-type.js +1 -1
  153. package/modules/use-cases/get-module.js +10 -4
  154. package/modules/use-cases/manage-access.js +21 -0
  155. package/modules/use-cases/multi-step-authorization.js +329 -0
  156. package/modules/use-cases/process-authorization-callback.js +53 -19
  157. package/modules/use-cases/refresh-entity-options.js +10 -4
  158. package/modules/use-cases/test-module-auth.js +10 -4
  159. package/modules/utils/map-module-dto.js +3 -5
  160. package/package.json +6 -6
  161. package/prisma-mongodb/schema.prisma +92 -0
  162. package/prisma-postgresql/migrations/20261003000000_add_authorization_session/migration.sql +28 -0
  163. package/prisma-postgresql/migrations/20261015000000_add_organization_membership/migration.sql +26 -0
  164. package/prisma-postgresql/migrations/20261016000000_add_entity_integration_organization/migration.sql +25 -0
  165. package/prisma-postgresql/migrations/20261017000000_add_scheduled_job/migration.sql +28 -0
  166. package/prisma-postgresql/schema.prisma +87 -0
  167. package/providers/index.js +23 -0
  168. package/providers/resolve-provider.js +93 -0
  169. package/providers/runtime-detection.js +124 -0
  170. package/queues/index.js +25 -0
  171. package/queues/providers/index.js +11 -0
  172. package/queues/providers/netlify-background-provider.js +150 -0
  173. package/queues/providers/qstash-queue-provider.js +219 -0
  174. package/queues/providers/sqs-queue-provider.js +70 -0
  175. package/queues/queue-client-interface.js +55 -0
  176. package/queues/queue-message-auth.js +193 -0
  177. package/queues/queue-provider-factory.js +101 -0
  178. package/queues/queue-provider.js +65 -0
  179. package/queues/sqs-queue-client.js +81 -0
  180. package/types/index.d.ts +2 -0
  181. package/types/modules/index.d.ts +214 -0
  182. package/types/user/index.d.ts +134 -0
  183. package/user/adopter-jwt-config.js +177 -0
  184. package/user/adopter-jwt-errors.js +59 -0
  185. package/user/adopter-token-verifier.js +122 -0
  186. package/user/app-user-helpers.js +97 -0
  187. package/user/create-user-authentication.js +64 -0
  188. package/user/membership.js +51 -0
  189. package/user/repositories/organization-membership-record.js +19 -0
  190. package/user/repositories/organization-membership-repository-documentdb.js +106 -0
  191. package/user/repositories/organization-membership-repository-factory.js +42 -0
  192. package/user/repositories/organization-membership-repository-interface.js +57 -0
  193. package/user/repositories/organization-membership-repository-mongo.js +13 -0
  194. package/user/repositories/organization-membership-repository-postgres.js +29 -0
  195. package/user/repositories/organization-membership-repository-prisma.js +81 -0
  196. package/user/repositories/user-repository-documentdb.js +27 -2
  197. package/user/repositories/user-repository-interface.js +18 -0
  198. package/user/repositories/user-repository-mongo.js +24 -0
  199. package/user/repositories/user-repository-postgres.js +18 -0
  200. package/user/tests/doubles/adopter-jwt-fixtures.js +220 -0
  201. package/user/tests/doubles/test-user-repository.js +1 -1
  202. package/user/use-cases/authenticate-user.js +7 -1
  203. package/user/use-cases/ensure-organization-membership.js +92 -0
  204. package/user/use-cases/find-individual-users-by-organization.js +54 -0
  205. package/user/use-cases/get-user-from-adopter-jwt.js +95 -124
  206. package/user/use-cases/get-user-from-bearer-token.js +2 -7
  207. package/user/use-cases/get-user-from-x-frigg-headers.js +83 -80
  208. package/user/user.js +64 -1
  209. package/errors/mapping-already-exists-error.js +0 -14
  210. package/integrations/use-cases/add-entities-to-integration.js +0 -92
  211. package/integrations/use-cases/remove-entities-from-integration.js +0 -70
  212. package/integrations/utils/assert-entity-ids-input.js +0 -42
  213. package/modules/utils/to-credential-id.js +0 -14
@@ -4,8 +4,41 @@
4
4
  * Infrastructure layer service that orchestrates field-level encryption/decryption.
5
5
  * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
6
6
  */
7
+ const { logger } = require('./logger');
8
+ const { isDeployedRuntime } = require('./encryption-config');
9
+
10
+ /**
11
+ * Thrown when a value that looks like ciphertext cannot be decrypted in a
12
+ * deployed runtime (a wrong, rotated or missing key). Returning the stored
13
+ * ciphertext would hand it to API modules as if it were a token.
14
+ */
15
+ class FieldDecryptionError extends Error {
16
+ constructor(message, options) {
17
+ super(message, options);
18
+ this.name = 'FieldDecryptionError';
19
+ }
20
+ }
21
+
22
+ // Cryptor.encrypt() returns `${keyId}:${iv}:${ciphertext}:${encryptedKey}`:
23
+ // keyId and encryptedKey are base64, iv is 16 bytes of hex, ciphertext is hex.
24
+ // Plaintext with three colons (`https://user:pw@host:443`, `a:b:c:d`) must not
25
+ // be mistaken for it.
26
+ const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
27
+ const IV_PART = /^[0-9a-f]{32}$/i;
28
+ const CIPHERTEXT_PART = /^(?:[0-9a-f]{2})+$/i;
29
+
7
30
  class FieldEncryptionService {
8
- constructor({ cryptor, schema }) {
31
+ /**
32
+ * @param {Object} params
33
+ * @param {Object} params.cryptor
34
+ * @param {Object} params.schema
35
+ * @param {() => boolean} [params.failClosedOnDecryptError] - whether a
36
+ * ciphertext-shaped value that fails to decrypt throws. Defaults to
37
+ * "running deployed" (encryption-config's isDeployedRuntime), read on
38
+ * each failure. Locally such a value is returned as stored, with a
39
+ * warning.
40
+ */
41
+ constructor({ cryptor, schema, failClosedOnDecryptError }) {
9
42
  if (!cryptor) {
10
43
  throw new Error('Cryptor instance required');
11
44
  }
@@ -15,6 +48,10 @@ class FieldEncryptionService {
15
48
 
16
49
  this.cryptor = cryptor;
17
50
  this.schema = schema;
51
+ this.failClosedOnDecryptError =
52
+ typeof failClosedOnDecryptError === 'function'
53
+ ? failClosedOnDecryptError
54
+ : () => isDeployedRuntime();
18
55
  }
19
56
 
20
57
  /**
@@ -97,12 +134,33 @@ class FieldEncryptionService {
97
134
  const decryptionPromises = fields.map(async (fieldPath) => {
98
135
  const value = this._getNestedValue(decrypted, fieldPath);
99
136
 
100
- if (this._isEncrypted(value)) {
137
+ if (!this._isEncrypted(value)) {
138
+ return null;
139
+ }
140
+ try {
101
141
  const decryptedValue = await this.cryptor.decrypt(value);
102
142
  const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
103
143
  return { fieldPath, decryptedValue: deserializedValue };
144
+ } catch (error) {
145
+ // Deployed: a ciphertext-shaped value under a wrong, rotated or
146
+ // missing key fails the read rather than reaching an API
147
+ // module as a token. Legacy plaintext never gets here: it does
148
+ // not look like ciphertext (_isEncrypted).
149
+ if (this.failClosedOnDecryptError()) {
150
+ throw new FieldDecryptionError(
151
+ `Could not decrypt ${modelName}.${fieldPath}`,
152
+ { cause: error }
153
+ );
154
+ }
155
+ // Local: a value that looks like ciphertext but is not is read
156
+ // as it is stored. One such field must not fail the whole
157
+ // read, findMany included.
158
+ logger.warn(
159
+ `Could not decrypt ${modelName}.${fieldPath}; returning the stored value`,
160
+ { errorName: error?.name }
161
+ );
162
+ return null;
104
163
  }
105
- return null;
106
164
  });
107
165
 
108
166
  const results = await Promise.all(decryptionPromises);
@@ -152,7 +210,13 @@ class FieldEncryptionService {
152
210
  }
153
211
 
154
212
  const parts = value.split(':');
155
- return parts.length >= 4;
213
+ return (
214
+ parts.length === 4 &&
215
+ BASE64_PART.test(parts[0]) &&
216
+ IV_PART.test(parts[1]) &&
217
+ CIPHERTEXT_PART.test(parts[2]) &&
218
+ BASE64_PART.test(parts[3])
219
+ );
156
220
  }
157
221
 
158
222
  _getNestedValue(obj, path) {
@@ -251,4 +315,4 @@ class FieldEncryptionService {
251
315
  }
252
316
  }
253
317
 
254
- module.exports = { FieldEncryptionService };
318
+ module.exports = { FieldEncryptionService, FieldDecryptionError };
@@ -1,4 +1,4 @@
1
- const { getEncryptionConfig } = require('../prisma');
1
+ const { getEncryptionConfig } = require('./encryption-config');
2
2
  const { Cryptor } = require('../../encrypt/Cryptor');
3
3
  const {
4
4
  getFieldsToDecryptOnRead,
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Test double for Cryptor output. Same shape as the real thing
3
+ * (`keyId:iv:ciphertext:encryptedKey`: base64, 16-byte hex, hex, base64) so
4
+ * FieldEncryptionService._isEncrypted accepts it, with the plaintext
5
+ * recoverable for the fake decrypt.
6
+ */
7
+ const fakeCiphertext = (plain) =>
8
+ `a2V5SWQ=:${'0'.repeat(32)}:${Buffer.from(String(plain)).toString(
9
+ 'hex'
10
+ )}:ZW5jS2V5`;
11
+
12
+ const fakePlaintext = (ciphertext) =>
13
+ Buffer.from(String(ciphertext).split(':')[2], 'hex').toString();
14
+
15
+ module.exports = { fakeCiphertext, fakePlaintext };
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The Prisma `where` fragment for an `organizationId` on MongoDB (ADR-056
3
+ * §3.6), shared by the entity and integration adapters.
4
+ *
5
+ * Prisma on MongoDB: `null` matches only an explicit null and `isSet: false`
6
+ * only a missing field. A row written before the column existed is the common
7
+ * "no organization" case, so `null` here means both.
8
+ */
9
+ function organizationWhere(organizationId) {
10
+ if (organizationId === null) {
11
+ return {
12
+ OR: [{ organizationId: null }, { organizationId: { isSet: false } }],
13
+ };
14
+ }
15
+ return { organizationId };
16
+ }
17
+
18
+ module.exports = { organizationWhere };
@@ -4,6 +4,7 @@ const {
4
4
  const { loadCustomEncryptionSchema } = require('./encryption/encryption-schema-registry');
5
5
  const { logger } = require('./encryption/logger');
6
6
  const { Cryptor } = require('../encrypt/Cryptor');
7
+ const { getEncryptionConfig } = require('./encryption/encryption-config');
7
8
  const config = require('./config');
8
9
 
9
10
  /**
@@ -32,33 +33,6 @@ function ensureMongoDbUrl() {
32
33
  );
33
34
  }
34
35
 
35
- function getEncryptionConfig() {
36
- const STAGE = process.env.STAGE || process.env.NODE_ENV || 'development';
37
- const shouldBypassEncryption = ['dev', 'test', 'local'].includes(STAGE);
38
-
39
- if (shouldBypassEncryption) {
40
- return { enabled: false };
41
- }
42
-
43
- const hasKMS =
44
- process.env.KMS_KEY_ARN && process.env.KMS_KEY_ARN.trim() !== '';
45
- const hasAES =
46
- process.env.AES_KEY_ID && process.env.AES_KEY_ID.trim() !== '';
47
-
48
- if (!hasKMS && !hasAES) {
49
- logger.warn(
50
- 'No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID). ' +
51
- 'Field-level encryption disabled. Set STAGE=production and configure keys to enable.'
52
- );
53
- return { enabled: false };
54
- }
55
-
56
- return {
57
- enabled: true,
58
- method: hasKMS ? 'kms' : 'aes',
59
- };
60
- }
61
-
62
36
  const prismaClientSingleton = () => {
63
37
  let PrismaClient;
64
38
 
@@ -67,13 +41,15 @@ const prismaClientSingleton = () => {
67
41
  const paths = [
68
42
  // Lambda layer location (when using Prisma Lambda layer)
69
43
  `/opt/nodejs/node_modules/generated/prisma-${dbType}`,
44
+ // __dirname-based absolute path (Netlify functions and bundlers)
45
+ require('node:path').resolve(__dirname, `../generated/prisma-${dbType}`),
70
46
  // Local development location (relative to core package)
71
47
  `../generated/prisma-${dbType}`,
72
48
  ];
73
49
 
74
- for (const path of paths) {
50
+ for (const candidate of paths) {
75
51
  try {
76
- return require(path).PrismaClient;
52
+ return require(candidate).PrismaClient;
77
53
  } catch (err) {
78
54
  // Continue to next path
79
55
  }
@@ -103,9 +79,13 @@ const prismaClientSingleton = () => {
103
79
  errorFormat: 'pretty',
104
80
  });
105
81
 
82
+ // Throws when a deployed runtime has no encryption key: the app must not
83
+ // start and write sensitive fields in plaintext.
106
84
  const encryptionConfig = getEncryptionConfig();
107
85
 
108
86
  if (encryptionConfig.enabled) {
87
+ // Fail closed: if the extension cannot be installed, do not hand out
88
+ // a client that would write plaintext.
109
89
  try {
110
90
  // Load custom encryption schema from appDefinition before creating extension
111
91
  loadCustomEncryptionSchema();
@@ -120,17 +100,14 @@ const prismaClientSingleton = () => {
120
100
  enabled: true,
121
101
  })
122
102
  );
123
-
124
- logger.info(
125
- `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
126
- );
127
103
  } catch (error) {
128
- logger.error(
129
- 'Failed to initialize encryption extension:',
130
- error
131
- );
132
- logger.warn('Continuing without encryption...');
104
+ logger.error('Failed to initialize encryption extension:', error);
105
+ throw error;
133
106
  }
107
+
108
+ logger.info(
109
+ `Field-level encryption enabled using ${encryptionConfig.method.toUpperCase()}`
110
+ );
134
111
  } else {
135
112
  logger.info('Field-level encryption disabled');
136
113
  }
@@ -0,0 +1,25 @@
1
+ /** Mongo/DocumentDB duplicate-key error code. */
2
+ const DUPLICATE_KEY_CODE = 11000;
3
+ /** Prisma's unique-constraint error code (PostgreSQL and MongoDB). */
4
+ const PRISMA_UNIQUE_CODE = 'P2002';
5
+
6
+ /**
7
+ * Whether `error` is a unique-constraint violation, however the database
8
+ * layer raised it: a Prisma `P2002`, or a duplicate-key `11000`
9
+ * (`documentdb-utils` `insertOne` sets `code` on the error it throws).
10
+ * Matches on the code only, never on message text.
11
+ *
12
+ * @param {unknown} error
13
+ * @returns {boolean}
14
+ */
15
+ function isUniqueViolation(error) {
16
+ return (
17
+ error?.code === PRISMA_UNIQUE_CODE || error?.code === DUPLICATE_KEY_CODE
18
+ );
19
+ }
20
+
21
+ module.exports = {
22
+ isUniqueViolation,
23
+ DUPLICATE_KEY_CODE,
24
+ PRISMA_UNIQUE_CODE,
25
+ };
@@ -1,3 +1,12 @@
1
+ const {
2
+ resolveEncryptionConfig,
3
+ OPT_OUT_VAR,
4
+ } = require('../encryption/encryption-config');
5
+
6
+ /**
7
+ * Reports whether field-level encryption is on and working, using the same
8
+ * rule the Prisma client applies at startup (encryption/encryption-config.js).
9
+ */
1
10
  class CheckEncryptionHealthUseCase {
2
11
  constructor({ testEncryptionUseCase }) {
3
12
  this.testEncryptionUseCase = testEncryptionUseCase;
@@ -5,78 +14,60 @@ class CheckEncryptionHealthUseCase {
5
14
 
6
15
  async execute() {
7
16
  const config = this._getEncryptionConfiguration();
17
+ const summary = {
18
+ mode: config.mode,
19
+ bypassed: config.bypassed,
20
+ optedOut: config.optedOut,
21
+ runtime: config.runtime,
22
+ stage: config.stage,
23
+ debug: {
24
+ hasKMS: config.hasKMS,
25
+ hasAES: config.hasAES,
26
+ },
27
+ };
8
28
 
9
- if (config.isBypassed || config.mode === 'none') {
10
- const testResult = config.isBypassed
11
- ? 'Encryption bypassed for this stage'
12
- : 'No encryption keys configured';
29
+ if (config.error) {
30
+ return {
31
+ status: 'unhealthy',
32
+ ...summary,
33
+ testResult: config.error,
34
+ encryptionWorks: false,
35
+ };
36
+ }
13
37
 
38
+ if (!config.enabled) {
14
39
  return {
15
40
  status: 'disabled',
16
- mode: config.mode,
17
- bypassed: config.isBypassed,
18
- stage: config.stage,
19
- testResult,
41
+ ...summary,
42
+ testResult: this._disabledReason(config),
20
43
  encryptionWorks: false,
21
- debug: {
22
- hasKMS: config.hasKMS,
23
- hasAES: config.hasAES,
24
- },
25
44
  };
26
45
  }
27
46
 
28
47
  try {
29
48
  const testResults = await this.testEncryptionUseCase.execute();
30
-
31
- return {
32
- ...testResults,
33
- mode: config.mode,
34
- bypassed: config.isBypassed,
35
- stage: config.stage,
36
- debug: {
37
- hasKMS: config.hasKMS,
38
- hasAES: config.hasAES,
39
- },
40
- };
49
+ return { ...testResults, ...summary };
41
50
  } catch (error) {
42
51
  return {
43
52
  status: 'unhealthy',
44
- mode: config.mode,
45
- bypassed: config.isBypassed,
46
- stage: config.stage,
53
+ ...summary,
47
54
  testResult: `Encryption test failed: ${error.message}`,
48
55
  encryptionWorks: false,
49
- debug: {
50
- hasKMS: config.hasKMS,
51
- hasAES: config.hasAES,
52
- },
53
56
  };
54
57
  }
55
58
  }
56
59
 
57
- _getEncryptionConfiguration() {
58
- const { STAGE, BYPASS_ENCRYPTION_STAGE, KMS_KEY_ARN, AES_KEY_ID } =
59
- process.env;
60
-
61
- const defaultBypassStages = ['dev', 'test', 'local'];
62
- const useEnv = BYPASS_ENCRYPTION_STAGE !== undefined;
63
- const bypassStages = useEnv
64
- ? BYPASS_ENCRYPTION_STAGE.split(',').map((s) => s.trim())
65
- : defaultBypassStages;
66
-
67
- const isBypassed = bypassStages.includes(STAGE);
68
- const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
69
- const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '';
70
- // Prefer KMS over AES when both are configured (KMS is more secure)
71
- const mode = hasKMS ? 'kms' : hasAES ? 'aes' : 'none';
60
+ _disabledReason(config) {
61
+ if (config.bypassed) return 'Encryption bypassed for this stage';
62
+ if (config.optedOut) {
63
+ return `Encryption explicitly disabled (${OPT_OUT_VAR}=true); sensitive fields are stored in plaintext`;
64
+ }
65
+ return 'No encryption keys configured';
66
+ }
72
67
 
73
- return {
74
- stage: STAGE || null,
75
- isBypassed,
76
- hasAES,
77
- hasKMS,
78
- mode,
79
- };
68
+ _getEncryptionConfiguration() {
69
+ const config = resolveEncryptionConfig(process.env);
70
+ return { ...config, stage: process.env.STAGE || null };
80
71
  }
81
72
  }
82
73
 
package/errors/index.js CHANGED
@@ -6,9 +6,6 @@ const {
6
6
  ParameterTypeError,
7
7
  } = require('./validation-errors');
8
8
  const { ClientSafeError } = require('./client-safe-error');
9
- const {
10
- MappingAlreadyExistsError,
11
- } = require('./mapping-already-exists-error');
12
9
 
13
10
  module.exports = {
14
11
  BaseError,
@@ -17,5 +14,4 @@ module.exports = {
17
14
  RequiredPropertyError,
18
15
  ParameterTypeError,
19
16
  ClientSafeError,
20
- MappingAlreadyExistsError,
21
17
  };
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Bootstrap Runner
3
+ *
4
+ * Runs extension bootstrap functions in sequence.
5
+ * Bootstrap hooks execute AFTER database connection but BEFORE integration
6
+ * router creation. This is the right place for extensions to:
7
+ *
8
+ * - Load credentials from database into integration definitions
9
+ * - Register additional middleware or services
10
+ * - Perform one-time initialization
11
+ *
12
+ * @example
13
+ * await runExtensionBootstraps(extensions, { prisma, appDefinition });
14
+ */
15
+
16
+ /**
17
+ * Runs all extension bootstrap functions in sequence.
18
+ *
19
+ * @param {Array<Object>} extensions - Normalized extensions (from extension-loader)
20
+ * @param {Object} context
21
+ * @param {Object} context.prisma - Prisma client instance
22
+ * @param {Object} context.appDefinition - Full app definition
23
+ * @throws {Error} If any bootstrap function fails (fails fast)
24
+ */
25
+ async function runExtensionBootstraps(extensions, context = {}) {
26
+ if (!extensions || extensions.length === 0) return;
27
+
28
+ const { prisma, appDefinition } = context;
29
+
30
+ for (const ext of extensions) {
31
+ if (!ext.bootstrap) continue;
32
+
33
+ try {
34
+ await ext.bootstrap(prisma, appDefinition);
35
+ } catch (error) {
36
+ throw new Error(
37
+ `Extension "${ext.name}" bootstrap failed: ${error.message}`
38
+ );
39
+ }
40
+ }
41
+ }
42
+
43
+ module.exports = { runExtensionBootstraps };
@@ -0,0 +1,230 @@
1
+ /**
2
+ * Extension Loader
3
+ *
4
+ * Validates and normalizes the core extensions of the app definition
5
+ * (`appDefinition.coreExtensions`, an array). Core extensions add custom
6
+ * Prisma models, encryption schemas, admin routes and bootstrap logic to a
7
+ * Frigg app. The key is `coreExtensions`, not `extensions`: ADR-017 keeps
8
+ * `appDefinition.extensions` for its keyed object form.
9
+ *
10
+ * @example
11
+ * const extensions = loadExtensions(appDefinition);
12
+ * // extensions is a normalized array, safe to iterate
13
+ */
14
+
15
+ const path = require('path');
16
+ const {
17
+ coreExtensionRoutePathError,
18
+ } = require('../management-api/route-registry');
19
+
20
+ const SCHEMA_DB_TYPES = ['postgresql', 'mongodb'];
21
+
22
+ function schemaErrors(schema, label) {
23
+ if (typeof schema === 'string') {
24
+ return schema.endsWith('.prisma') ? [] : [`${label}: must end with .prisma`];
25
+ }
26
+ if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
27
+ return [`${label}: must be a string (path to .prisma file) or { postgresql, mongodb } paths`];
28
+ }
29
+ const errors = [];
30
+ const keys = Object.keys(schema);
31
+ if (keys.length === 0) errors.push(`${label}: names no database type`);
32
+ for (const key of keys) {
33
+ if (!SCHEMA_DB_TYPES.includes(key)) {
34
+ errors.push(`${label}.${key}: unknown database type (expected ${SCHEMA_DB_TYPES.join(' or ')})`);
35
+ } else if (typeof schema[key] !== 'string' || !schema[key].endsWith('.prisma')) {
36
+ errors.push(`${label}.${key}: must be a path ending in .prisma`);
37
+ }
38
+ }
39
+ return errors;
40
+ }
41
+
42
+ /**
43
+ * Validates a single extension definition.
44
+ * @param {Object} ext - Raw extension config from app definition
45
+ * @param {number} index - Position in the coreExtensions array (for error messages)
46
+ * @returns {{valid: boolean, errors: string[]}}
47
+ */
48
+ function validateExtension(ext, index) {
49
+ const prefix = `coreExtensions[${index}]`;
50
+ const errors = [];
51
+
52
+ if (!ext || typeof ext !== 'object') {
53
+ errors.push(`${prefix}: must be an object`);
54
+ return { valid: false, errors };
55
+ }
56
+
57
+ if (!ext.name || typeof ext.name !== 'string') {
58
+ errors.push(`${prefix}.name: required string`);
59
+ }
60
+
61
+ // schema is optional: a .prisma file for every database, or one per
62
+ // database type ({ postgresql, mongodb }), since a model written for one
63
+ // (an autoincrement Int id, a String[] column) does not compile for the other.
64
+ if (ext.schema !== undefined) {
65
+ errors.push(...schemaErrors(ext.schema, `${prefix}.schema`));
66
+ }
67
+
68
+ // migrations is optional: a directory of Prisma migration folders
69
+ // (<timestamp>_<name>/migration.sql) for the extension's PostgreSQL models.
70
+ // They are applied with the core migrations. MongoDB has no migrations.
71
+ if (ext.migrations !== undefined && (typeof ext.migrations !== 'string' || ext.migrations === '')) {
72
+ errors.push(`${prefix}.migrations: must be a string (path to a migrations directory)`);
73
+ }
74
+
75
+ // encryption is optional — object with model names → { fields: [...] }
76
+ if (ext.encryption !== undefined) {
77
+ if (!ext.encryption || typeof ext.encryption !== 'object') {
78
+ errors.push(`${prefix}.encryption: must be an object`);
79
+ } else {
80
+ for (const [model, config] of Object.entries(ext.encryption)) {
81
+ if (!config || !Array.isArray(config.fields)) {
82
+ errors.push(
83
+ `${prefix}.encryption.${model}: must have a "fields" array`
84
+ );
85
+ }
86
+ }
87
+ }
88
+ }
89
+
90
+ // routes is optional — { path, handler }
91
+ if (ext.routes !== undefined) {
92
+ if (!ext.routes || typeof ext.routes !== 'object') {
93
+ errors.push(`${prefix}.routes: must be an object with { path, handler }`);
94
+ } else {
95
+ if (!ext.routes.path || typeof ext.routes.path !== 'string') {
96
+ errors.push(`${prefix}.routes.path: required string`);
97
+ } else {
98
+ const pathError = coreExtensionRoutePathError(ext.routes.path);
99
+ if (pathError) {
100
+ errors.push(`${prefix}.routes.path: ${pathError}`);
101
+ }
102
+ }
103
+ if (!ext.routes.handler) {
104
+ errors.push(`${prefix}.routes.handler: required (function or module path)`);
105
+ }
106
+ }
107
+ }
108
+
109
+ // bootstrap is optional — function or module path
110
+ if (ext.bootstrap !== undefined) {
111
+ if (typeof ext.bootstrap !== 'function' && typeof ext.bootstrap !== 'string') {
112
+ errors.push(
113
+ `${prefix}.bootstrap: must be a function or a string (module path)`
114
+ );
115
+ }
116
+ }
117
+
118
+ return { valid: errors.length === 0, errors };
119
+ }
120
+
121
+ /**
122
+ * Loads and validates extensions from the app definition.
123
+ *
124
+ * @param {Object} appDefinition - The full app definition
125
+ * @returns {Array<Object>} Normalized extensions array (empty if none)
126
+ * @throws {Error} If any extension fails validation
127
+ */
128
+ function loadExtensions(appDefinition) {
129
+ if (!appDefinition) return [];
130
+
131
+ // The array this loader reads used to be `appDefinition.extensions`;
132
+ // that key now belongs to ADR-017's keyed object. An array there is the
133
+ // old spelling: stop at load rather than silently dropping the extensions.
134
+ if (Array.isArray(appDefinition.extensions)) {
135
+ throw new Error(
136
+ 'appDefinition.extensions (array) was renamed to appDefinition.coreExtensions; ' +
137
+ 'move the array to coreExtensions'
138
+ );
139
+ }
140
+
141
+ const raw = appDefinition.coreExtensions;
142
+ if (!raw) return [];
143
+
144
+ if (!Array.isArray(raw)) {
145
+ throw new Error('appDefinition.coreExtensions must be an array');
146
+ }
147
+
148
+ if (raw.length === 0) return [];
149
+
150
+ const allErrors = [];
151
+
152
+ const normalized = raw.map((ext, index) => {
153
+ const { valid, errors } = validateExtension(ext, index);
154
+ if (!valid) {
155
+ allErrors.push(...errors);
156
+ return null;
157
+ }
158
+
159
+ // Normalize bootstrap — resolve string paths to functions
160
+ let bootstrapFn = null;
161
+ if (typeof ext.bootstrap === 'function') {
162
+ bootstrapFn = ext.bootstrap;
163
+ } else if (typeof ext.bootstrap === 'string') {
164
+ bootstrapFn = require(ext.bootstrap);
165
+ }
166
+
167
+ // Normalize route handler — resolve string paths to functions
168
+ let routeHandler = null;
169
+ if (ext.routes) {
170
+ if (typeof ext.routes.handler === 'function') {
171
+ routeHandler = ext.routes.handler;
172
+ } else if (typeof ext.routes.handler === 'string') {
173
+ routeHandler = require(ext.routes.handler);
174
+ } else {
175
+ routeHandler = ext.routes.handler;
176
+ }
177
+ }
178
+
179
+ return {
180
+ name: ext.name,
181
+ schema: ext.schema || null,
182
+ migrations: ext.migrations || null,
183
+ encryption: ext.encryption || null,
184
+ routes: ext.routes
185
+ ? { path: ext.routes.path, handler: routeHandler }
186
+ : null,
187
+ bootstrap: bootstrapFn,
188
+ };
189
+ });
190
+
191
+ if (allErrors.length > 0) {
192
+ throw new Error(
193
+ `Invalid extension configuration:\n- ${allErrors.join('\n- ')}`
194
+ );
195
+ }
196
+
197
+ return normalized.filter(Boolean);
198
+ }
199
+
200
+ /**
201
+ * The .prisma file an extension adds for one database type.
202
+ * @param {Object} ext - Normalized extension
203
+ * @param {'postgresql'|'mongodb'} [dbType] - Omitted: a string schema only
204
+ * @returns {string|null}
205
+ */
206
+ function extensionSchemaPath(ext, dbType) {
207
+ if (!ext?.schema) return null;
208
+ if (typeof ext.schema === 'string') return ext.schema;
209
+ return dbType ? ext.schema[dbType] || null : null;
210
+ }
211
+
212
+ /**
213
+ * Get extension schema file paths from loaded extensions.
214
+ * @param {Array<Object>} extensions - Normalized extensions
215
+ * @param {'postgresql'|'mongodb'} [dbType] - Database the paths are for. A
216
+ * per-database schema ({ postgresql, mongodb }) only answers when given one.
217
+ * @returns {string[]} Array of absolute paths to .prisma schema files
218
+ */
219
+ function getExtensionSchemaPaths(extensions, dbType) {
220
+ return extensions
221
+ .map((ext) => extensionSchemaPath(ext, dbType))
222
+ .filter(Boolean);
223
+ }
224
+
225
+ module.exports = {
226
+ loadExtensions,
227
+ validateExtension,
228
+ getExtensionSchemaPaths,
229
+ extensionSchemaPath,
230
+ };