@open-pencil/cloud 0.17.0-beta.1 → 0.17.0-beta.4

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 (235) hide show
  1. package/README.md +1 -1
  2. package/dist/bin/{ai-relay.mjs → services.mjs} +8 -8
  3. package/dist/bin/services.mjs.map +1 -0
  4. package/dist/client.d.ts +236 -46
  5. package/dist/client.d.ts.map +1 -1
  6. package/dist/client.js +649 -400
  7. package/dist/client.js.map +1 -1
  8. package/dist/contract.d.ts +2 -2
  9. package/dist/contract.js +2 -2
  10. package/dist/contract2.js +680 -443
  11. package/dist/contract2.js.map +1 -1
  12. package/dist/email.d.ts +9 -1
  13. package/dist/email.d.ts.map +1 -1
  14. package/dist/email.js +99 -58
  15. package/dist/email.js.map +1 -1
  16. package/dist/index.d.ts +468 -64
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/listen.mjs +575 -738
  19. package/dist/listen.mjs.map +1 -1
  20. package/dist/runtime-node.d.mts +6564 -2934
  21. package/dist/runtime-node.d.mts.map +1 -1
  22. package/dist/runtime-node.mjs +6 -5
  23. package/dist/runtime-node.mjs.map +1 -1
  24. package/dist/server.d.ts +8931 -4198
  25. package/dist/server.d.ts.map +1 -1
  26. package/dist/server.js +5260 -3859
  27. package/dist/server.js.map +1 -1
  28. package/dist/server.mjs +5686 -3736
  29. package/dist/server.mjs.map +1 -1
  30. package/dist/server2.mjs +101 -79
  31. package/dist/server2.mjs.map +1 -1
  32. package/package.json +9 -6
  33. package/src/admin/api/routes.ts +103 -33
  34. package/src/admin/audit/service.ts +25 -6
  35. package/src/admin/documents/service.ts +361 -0
  36. package/src/admin/errors.ts +9 -1
  37. package/src/admin/index.ts +6 -0
  38. package/src/admin/operations/service.ts +7 -0
  39. package/src/admin/reports/service.ts +147 -0
  40. package/src/admin/schema.ts +6 -0
  41. package/src/client/api.ts +36 -21
  42. package/src/client/auth/navigation.ts +6 -5
  43. package/src/client/index.ts +7 -7
  44. package/src/client/portal/account.ts +25 -0
  45. package/src/client/portal/administration.ts +56 -0
  46. package/src/client/{ai.ts → services.ts} +44 -27
  47. package/src/contract/account.ts +58 -2
  48. package/src/contract/admin/index.ts +67 -3
  49. package/src/contract/collaboration.ts +6 -1
  50. package/src/contract/discovery.ts +22 -4
  51. package/src/contract/documents.ts +27 -0
  52. package/src/contract/entitlements.ts +2 -2
  53. package/src/contract/index.ts +63 -37
  54. package/src/contract/relay.ts +6 -0
  55. package/src/contract/reports.ts +42 -0
  56. package/src/contract/services.ts +233 -0
  57. package/src/contract/sharing.ts +3 -9
  58. package/src/email/render.ts +26 -0
  59. package/src/email/schema.ts +11 -1
  60. package/src/email/templates/brand.ts +1 -1
  61. package/src/runtime/cloudflare/environment.ts +31 -6
  62. package/src/runtime/cloudflare/index.ts +1 -1
  63. package/src/runtime/cloudflare/logging.ts +15 -0
  64. package/src/runtime/cloudflare/maintenance.ts +31 -0
  65. package/src/runtime/cloudflare/relay/index.ts +176 -0
  66. package/src/runtime/cloudflare/relay/sockets.ts +112 -0
  67. package/src/runtime/cloudflare/worker.ts +89 -26
  68. package/src/runtime/node/application.ts +5 -3
  69. package/src/runtime/node/bootstrap.ts +20 -4
  70. package/src/runtime/node/cleanup.ts +16 -3
  71. package/src/runtime/node/entitlements/main.ts +14 -11
  72. package/src/runtime/node/index.ts +1 -1
  73. package/src/runtime/node/migrate.ts +5 -1
  74. package/src/runtime/node/relay.ts +8 -2
  75. package/src/runtime/node/request-id.ts +13 -0
  76. package/src/runtime/node/server.ts +71 -15
  77. package/src/runtime/node/{ai-relay → services}/main.ts +6 -6
  78. package/src/runtime/node/{ai-relay → services}/server.ts +18 -18
  79. package/src/runtime/postgres/database.ts +20 -1
  80. package/src/runtime/posthog/errors.ts +32 -0
  81. package/src/runtime/s3/objects.ts +50 -1
  82. package/src/runtime/site/server.ts +33 -4
  83. package/src/server/account/actions.ts +5 -0
  84. package/src/server/account/deletion.ts +302 -0
  85. package/src/server/account/routes.ts +47 -3
  86. package/src/server/account/terms.ts +42 -0
  87. package/src/server/api/router.ts +12 -7
  88. package/src/server/api/types.ts +9 -0
  89. package/src/server/app.ts +93 -15
  90. package/src/server/auth/access-control.ts +63 -0
  91. package/src/server/auth/adapter.ts +11 -0
  92. package/src/server/auth/endpoints.ts +5 -1
  93. package/src/server/auth/factory.ts +30 -3
  94. package/src/server/auth/index.ts +10 -1
  95. package/src/server/cleanup/configured.ts +12 -5
  96. package/src/server/cleanup/documents.ts +165 -71
  97. package/src/server/cleanup/objects.ts +10 -2
  98. package/src/server/cleanup/revisions.ts +24 -7
  99. package/src/server/cleanup/uploads.ts +8 -2
  100. package/src/server/cleanup/worker.ts +5 -2
  101. package/src/server/collaboration/index.ts +3 -0
  102. package/src/server/collaboration/relay/connection.ts +196 -0
  103. package/src/server/collaboration/relay/documents.ts +13 -10
  104. package/src/server/collaboration/relay/hub.ts +279 -195
  105. package/src/server/collaboration/relay/index.ts +3 -1
  106. package/src/server/collaboration/relay/log.ts +79 -0
  107. package/src/server/collaboration/relay/persistence.ts +147 -22
  108. package/src/server/collaboration/relay/resume.ts +28 -0
  109. package/src/server/collaboration/routes.ts +27 -16
  110. package/src/server/collaboration/service.ts +27 -31
  111. package/src/server/config/deployment.ts +35 -4
  112. package/src/server/config/public.ts +5 -4
  113. package/src/server/config/schema.ts +104 -16
  114. package/src/server/db/expressions.ts +15 -1
  115. package/src/server/db/migrate.ts +34 -114
  116. package/src/server/db/migrations/001_accounts.ts +79 -0
  117. package/src/server/db/migrations/002_workspaces.ts +48 -0
  118. package/src/server/db/migrations/003_storage.ts +44 -0
  119. package/src/server/db/migrations/004_documents.ts +193 -0
  120. package/src/server/db/migrations/005_sharing.ts +95 -0
  121. package/src/server/db/migrations/006_operations.ts +110 -0
  122. package/src/server/db/migrations/007_trash.ts +33 -0
  123. package/src/server/db/migrations/008_terms.ts +18 -0
  124. package/src/server/db/migrations/schema.ts +71 -0
  125. package/src/server/db/tables.ts +70 -7
  126. package/src/server/documents/access.ts +66 -55
  127. package/src/server/documents/errors.ts +7 -0
  128. package/src/server/documents/images.ts +2 -1
  129. package/src/server/documents/limits.ts +9 -9
  130. package/src/server/documents/purge.ts +75 -0
  131. package/src/server/documents/repository.ts +2 -0
  132. package/src/server/documents/routes.ts +132 -80
  133. package/src/server/documents/service.ts +18 -4
  134. package/src/server/documents/summary.ts +1 -0
  135. package/src/server/documents/trash.ts +203 -0
  136. package/src/server/documents/versions/checkpoint.ts +2 -1
  137. package/src/server/documents/versions/history.ts +11 -7
  138. package/src/server/documents/versions/routes.ts +36 -25
  139. package/src/server/documents/versions/service.ts +22 -4
  140. package/src/server/errors/index.ts +99 -0
  141. package/src/server/errors/posthog.ts +80 -0
  142. package/src/server/index.ts +56 -16
  143. package/src/server/internal/index.ts +3 -3
  144. package/src/server/internal/routes.ts +7 -15
  145. package/src/server/internal/schema.ts +1 -1
  146. package/src/server/internal/service.ts +17 -23
  147. package/src/server/invitations/budget.ts +66 -0
  148. package/src/server/invitations/index.ts +1 -0
  149. package/src/server/logging.ts +76 -0
  150. package/src/server/objects/types.ts +12 -0
  151. package/src/server/pictures/routes.ts +4 -2
  152. package/src/server/pictures/service.ts +2 -1
  153. package/src/server/policy/database.ts +39 -25
  154. package/src/server/policy/index.ts +2 -1
  155. package/src/server/policy/keys.ts +5 -2
  156. package/src/server/policy/policy.ts +1 -0
  157. package/src/server/policy/schema.ts +2 -2
  158. package/src/server/policy/service.ts +12 -9
  159. package/src/server/policy/static.ts +5 -5
  160. package/src/server/policy/workspace.ts +41 -0
  161. package/src/server/quota/reconcile.ts +2 -0
  162. package/src/server/quota/storage.ts +69 -31
  163. package/src/server/rate-limit/cleanup.ts +17 -5
  164. package/src/server/rate-limit/index.ts +4 -1
  165. package/src/server/rate-limit/middleware.ts +100 -12
  166. package/src/server/reports/index.ts +8 -0
  167. package/src/server/reports/routes.ts +37 -0
  168. package/src/server/reports/service.ts +123 -0
  169. package/src/server/services/errors.ts +7 -0
  170. package/src/server/services/index.ts +8 -0
  171. package/src/server/{ai → services}/keys.ts +11 -11
  172. package/src/server/services/routes.ts +47 -0
  173. package/src/server/{ai/service.ts → services/tokens.ts} +23 -20
  174. package/src/server/sharing/capabilities/service.ts +68 -22
  175. package/src/server/sharing/document-routes.ts +30 -22
  176. package/src/server/sharing/grants/service.ts +11 -18
  177. package/src/server/sharing/http.ts +4 -0
  178. package/src/server/sharing/invitations/service.ts +21 -11
  179. package/src/server/sharing/policy.ts +9 -14
  180. package/src/server/sharing/routes.ts +108 -85
  181. package/src/server/sharing/service.ts +1 -17
  182. package/src/server/validation.ts +59 -2
  183. package/src/server/workspaces/index.ts +1 -0
  184. package/src/server/workspaces/members.ts +89 -38
  185. package/src/server/workspaces/repository.ts +2 -1
  186. package/src/server/workspaces/routes.ts +67 -45
  187. package/src/{ai-relay → services}/app.ts +48 -44
  188. package/src/{ai-relay → services}/config.ts +25 -19
  189. package/src/services/db/index.ts +10 -0
  190. package/src/services/db/migrate.ts +37 -0
  191. package/src/{ai-relay/db/migrations/001_usage.ts → services/db/migrations/001_baseline.ts} +18 -7
  192. package/src/services/db/schema.ts +22 -0
  193. package/src/services/index.ts +18 -0
  194. package/src/{ai-relay → services}/metering.ts +2 -2
  195. package/src/{ai-relay → services}/usage.ts +43 -19
  196. package/dist/bin/ai-relay.mjs.map +0 -1
  197. package/src/ai-relay/db/index.ts +0 -10
  198. package/src/ai-relay/db/migrate.ts +0 -32
  199. package/src/ai-relay/db/schema.ts +0 -20
  200. package/src/ai-relay/index.ts +0 -18
  201. package/src/contract/ai.ts +0 -150
  202. package/src/runtime/cloudflare/relay.ts +0 -136
  203. package/src/server/ai/errors.ts +0 -7
  204. package/src/server/ai/index.ts +0 -4
  205. package/src/server/ai/routes.ts +0 -43
  206. package/src/server/auth/workspace-access.ts +0 -23
  207. package/src/server/db/migrations/001_foundation.ts +0 -164
  208. package/src/server/db/migrations/002_upload_cleanup_claims.ts +0 -34
  209. package/src/server/db/migrations/003_document_cleanup_claims.ts +0 -23
  210. package/src/server/db/migrations/004_document_sharing.ts +0 -82
  211. package/src/server/db/migrations/005_document_collaboration_epoch.ts +0 -13
  212. package/src/server/db/migrations/006_invitation_continuation.ts +0 -27
  213. package/src/server/db/migrations/007_collaboration_state.ts +0 -25
  214. package/src/server/db/migrations/008_storage_reservations.ts +0 -37
  215. package/src/server/db/migrations/009_workspace_entitlements.ts +0 -22
  216. package/src/server/db/migrations/010_upload_finalization.ts +0 -22
  217. package/src/server/db/migrations/011_upload_finalization_lease.ts +0 -12
  218. package/src/server/db/migrations/012_transactional_email.ts +0 -48
  219. package/src/server/db/migrations/013_admin_enrollment.ts +0 -54
  220. package/src/server/db/migrations/014_enrollment_email_kinds.ts +0 -30
  221. package/src/server/db/migrations/015_cloud_rate_limit.ts +0 -22
  222. package/src/server/db/migrations/016_auth_schema.ts +0 -16
  223. package/src/server/db/migrations/017_authentication_email_kinds.ts +0 -32
  224. package/src/server/db/migrations/018_authentication_mfa.ts +0 -78
  225. package/src/server/db/migrations/019_better_auth_account_issuer.ts +0 -42
  226. package/src/server/db/migrations/020_workspace_invitations.ts +0 -57
  227. package/src/server/db/migrations/021_document_versions.ts +0 -66
  228. package/src/server/db/migrations/022_entitlement_external_version.ts +0 -17
  229. package/src/server/db/migrations/023_document_images.ts +0 -61
  230. package/src/server/db/migrations/024_account_activity.ts +0 -66
  231. package/src/server/db/migrations/025_table_names.ts +0 -58
  232. package/src/server/db/migrations/026_user_picture.ts +0 -30
  233. package/src/server/db/migrations/027_document_kind.ts +0 -19
  234. package/src/server/db/migrations/helpers.ts +0 -78
  235. /package/dist/bin/{ai-relay.d.mts → services.d.mts} +0 -0
@@ -31,6 +31,16 @@ const websocketURLSchema = v.pipe(
31
31
 
32
32
  const optionalTextSchema = v.optional(v.pipe(v.string(), v.trim(), v.minLength(1)))
33
33
 
34
+ /**
35
+ * A prefix deleted files move under: one lowercase path segment and a slash, which no object key
36
+ * the server makes starts with (they start with `documents/`).
37
+ */
38
+ const deletedPrefixSchema = v.pipe(
39
+ v.string(),
40
+ v.regex(/^[a-z0-9][a-z0-9-]*\/$/),
41
+ v.check((prefix) => prefix !== 'documents/', 'deleted_prefix cannot be documents/')
42
+ )
43
+
34
44
  const rawCloudServerConfigSchema = v.object({
35
45
  deployment: v.picklist(['official', 'self-hosted']),
36
46
  publicURL: httpURLSchema,
@@ -111,6 +121,8 @@ const rawCloudServerConfigSchema = v.object({
111
121
  s3ChecksumVerification: v.optional(v.picklist(['native', 'metadata']), 'native'),
112
122
  s3ServerSideEncryption: v.optional(v.picklist(['AES256', 'aws:kms'])),
113
123
  s3KmsKeyId: optionalTextSchema,
124
+ /** Where a deleted file is kept until the bucket's lifecycle rule expires it; see `deleted_prefix`. */
125
+ s3DeletedPrefix: v.optional(deletedPrefixSchema),
114
126
  smtpHost: optionalTextSchema,
115
127
  smtpPort: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(65_535))),
116
128
  smtpSecure: v.optional(v.boolean()),
@@ -136,17 +148,48 @@ const rawCloudServerConfigSchema = v.object({
136
148
  v.pipe(v.number(), v.integer(), v.minValue(0)),
137
149
  30 * 24 * 60 * 60_000
138
150
  ),
139
- /** The AI service editors reach with tokens this server signs; see `src/contract/ai.ts`. */
140
- aiEndpoint: v.optional(httpURLSchema),
141
- /** The PKCS #8 PEM of the P-256 key that signs AI service tokens. */
142
- aiSigningKey: optionalTextSchema,
143
- aiTokenLifetimeSeconds: v.optional(
151
+ /**
152
+ * How long a document deleted forever keeps its files and rows, out of everyone's sight, so a
153
+ * server administrator can still bring it back; 0 destroys it at once.
154
+ */
155
+ documentPurgeGraceMs: v.optional(
156
+ v.pipe(v.number(), v.integer(), v.minValue(0)),
157
+ 7 * 24 * 60 * 60_000
158
+ ),
159
+ /** The OpenPencil services editors reach with tokens this server signs; see `src/contract/services.ts`. */
160
+ servicesEndpoint: v.optional(httpURLSchema),
161
+ /** The PKCS #8 PEM of the P-256 key that signs service tokens. */
162
+ servicesSigningKey: optionalTextSchema,
163
+ servicesTokenLifetimeSeconds: v.optional(
144
164
  v.pipe(v.number(), v.integer(), v.minValue(60), v.maxValue(60 * 60)),
145
165
  10 * 60
146
166
  ),
147
167
  billingPortalURL: v.optional(httpURLSchema),
148
168
  /** The bearer token services such as billing present to the internal API. */
149
- internalServiceToken: v.optional(v.pipe(v.string(), v.minLength(32)))
169
+ internalServiceToken: v.optional(v.pipe(v.string(), v.minLength(32))),
170
+ /**
171
+ * The operator's own terms, privacy policy, abuse contact, and minimum age; without it the
172
+ * server shows none. With `requireAcceptance`, an account uses the server only once it accepted
173
+ * `termsVersion`.
174
+ */
175
+ legal: v.optional(
176
+ v.object({
177
+ termsURL: v.optional(httpURLSchema),
178
+ privacyURL: v.optional(httpURLSchema),
179
+ termsVersion: optionalTextSchema,
180
+ requireAcceptance: v.boolean(),
181
+ abuseEmail: v.optional(v.pipe(v.string(), v.email())),
182
+ minimumAge: v.optional(v.pipe(v.number(), v.integer(), v.minValue(13), v.maxValue(21)))
183
+ })
184
+ ),
185
+ /** Where server errors are reported; without it the server reports nothing. */
186
+ errorTracking: v.optional(
187
+ v.object({
188
+ provider: v.literal('posthog'),
189
+ host: httpURLSchema,
190
+ projectAPIKey: v.pipe(v.string(), v.trim(), v.minLength(1))
191
+ })
192
+ )
150
193
  })
151
194
 
152
195
  export type CloudServerConfig = v.InferOutput<typeof rawCloudServerConfigSchema>
@@ -181,6 +224,9 @@ function validateAuthenticationConfig(config: CloudServerConfig): void {
181
224
  if (config.deploymentAdminMFARequired && !config.totpEnabled && !config.passkeysEnabled) {
182
225
  throw new CloudConfigError('Deployment administrator MFA requires TOTP or passkeys')
183
226
  }
227
+ if (config.deployment === 'official' && !config.deploymentAdminMFARequired) {
228
+ throw new CloudConfigError('An official deployment requires MFA for deployment administrators')
229
+ }
184
230
  if (config.recoveryCodesEnabled && !config.totpEnabled) {
185
231
  throw new CloudConfigError('MFA recovery codes require TOTP')
186
232
  }
@@ -222,7 +268,7 @@ function validateEmailConfig(config: CloudServerConfig): void {
222
268
  }
223
269
 
224
270
  function validateServiceConfig(config: CloudServerConfig): void {
225
- requireTogether(config, 'AI service', ['aiEndpoint', 'aiSigningKey'])
271
+ requireTogether(config, 'Services', ['servicesEndpoint', 'servicesSigningKey'])
226
272
  if (config.internalServiceToken && config.staticEntitlements) {
227
273
  throw new CloudConfigError(
228
274
  'The internal API writes database entitlements, which static entitlements would hide'
@@ -230,10 +276,17 @@ function validateServiceConfig(config: CloudServerConfig): void {
230
276
  }
231
277
  if (
232
278
  config.deployment === 'official' &&
233
- config.aiEndpoint &&
234
- new URL(config.aiEndpoint).protocol !== 'https:'
279
+ config.servicesEndpoint &&
280
+ new URL(config.servicesEndpoint).protocol !== 'https:'
235
281
  ) {
236
- throw new CloudConfigError('Official AI service endpoint must use HTTPS')
282
+ throw new CloudConfigError('Official services endpoint must use HTTPS')
283
+ }
284
+ }
285
+
286
+ function validateLegalConfig(config: CloudServerConfig): void {
287
+ const legal = config.legal
288
+ if (legal?.requireAcceptance && !(legal.termsURL && legal.termsVersion)) {
289
+ throw new CloudConfigError('[legal] require_acceptance needs terms_url and terms_version')
237
290
  }
238
291
  }
239
292
 
@@ -260,9 +313,13 @@ export function parseCloudServerConfig(input: unknown): CloudServerConfig {
260
313
  validateEmailConfig(config)
261
314
  validateServiceConfig(config)
262
315
  validateObjectStorageConfig(config)
316
+ validateLegalConfig(config)
263
317
  return config
264
318
  }
265
319
 
320
+ /** PostHog's EU Cloud ingestion host, where OpenPencil's own project is. */
321
+ const POSTHOG_DEFAULT_HOST = 'https://eu.i.posthog.com'
322
+
266
323
  const DEFAULT_SECRET_NAMES = {
267
324
  databaseURL: 'DATABASE_URL',
268
325
  authSecret: 'BETTER_AUTH_SECRET',
@@ -275,8 +332,9 @@ const DEFAULT_SECRET_NAMES = {
275
332
  smtpUser: 'OPENPENCIL_CLOUD_SMTP_USER',
276
333
  smtpPassword: 'OPENPENCIL_CLOUD_SMTP_PASSWORD',
277
334
  turnstileSecretKey: 'TURNSTILE_SECRET_KEY',
278
- aiSigningKey: 'OPENPENCIL_CLOUD_AI_SIGNING_KEY',
279
- internalServiceToken: 'OPENPENCIL_CLOUD_SERVICE_TOKEN'
335
+ servicesSigningKey: 'OPENPENCIL_CLOUD_SERVICES_SIGNING_KEY',
336
+ internalServiceToken: 'OPENPENCIL_CLOUD_SERVICE_TOKEN',
337
+ posthogProjectAPIKey: 'POSTHOG_PROJECT_API_KEY'
280
338
  } as const
281
339
 
282
340
  const urlSchema = v.pipe(v.string(), v.url())
@@ -445,6 +503,11 @@ export const cloudDeploymentConfigSchema = v.strictObject({
445
503
  checksum_verification: v.optional(v.picklist(['native', 'metadata']), 'native'),
446
504
  server_side_encryption: v.optional(v.picklist(['AES256', 'aws:kms'])),
447
505
  kms_key_id: v.optional(textSchema),
506
+ /**
507
+ * Keeps each file cleanup deletes under this prefix, such as `deleted/`, so a database restored
508
+ * to an earlier time still finds it; a lifecycle rule on the prefix expires them.
509
+ */
510
+ deleted_prefix: v.optional(deletedPrefixSchema),
448
511
  maximum_upload_bytes: v.optional(positiveIntegerSchema)
449
512
  }),
450
513
  collaboration: v.optional(
@@ -457,9 +520,10 @@ export const cloudDeploymentConfigSchema = v.strictObject({
457
520
  ),
458
521
  documents: v.optional(
459
522
  v.strictObject({
460
- retention_days: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0)), 30)
523
+ retention_days: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0)), 30),
524
+ purge_grace_days: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0)), 7)
461
525
  }),
462
- { retention_days: 30 }
526
+ { retention_days: 30, purge_grace_days: 7 }
463
527
  ),
464
528
  email: emailSchema,
465
529
  workers: v.optional(
@@ -490,10 +554,10 @@ export const cloudDeploymentConfigSchema = v.strictObject({
490
554
  v.strictObject({ source: v.literal('database') })
491
555
  ])
492
556
  ),
493
- ai: v.optional(
557
+ services: v.optional(
494
558
  v.strictObject({
495
559
  endpoint: urlSchema,
496
- signing_key: defaultReference(DEFAULT_SECRET_NAMES.aiSigningKey),
560
+ signing_key: defaultReference(DEFAULT_SECRET_NAMES.servicesSigningKey),
497
561
  token_lifetime_minutes: v.optional(
498
562
  v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(60)),
499
563
  10
@@ -503,6 +567,30 @@ export const cloudDeploymentConfigSchema = v.strictObject({
503
567
  billing: v.optional(v.strictObject({ portal_url: urlSchema })),
504
568
  internal_api: v.optional(
505
569
  v.strictObject({ service_token: defaultReference(DEFAULT_SECRET_NAMES.internalServiceToken) })
570
+ ),
571
+ /**
572
+ * Optional: the operator's terms and privacy policy, linked at sign-up and in the portal, and
573
+ * with `require_acceptance`, accepted once per `terms_version` before an account uses the server.
574
+ */
575
+ legal: v.optional(
576
+ v.strictObject({
577
+ terms_url: v.optional(urlSchema),
578
+ privacy_url: v.optional(urlSchema),
579
+ terms_version: v.optional(textSchema),
580
+ require_acceptance: v.optional(v.boolean(), false),
581
+ abuse_email: v.optional(v.pipe(v.string(), v.email())),
582
+ minimum_age: v.optional(v.pipe(v.number(), v.integer(), v.minValue(13), v.maxValue(21)))
583
+ })
584
+ ),
585
+ /** Optional: reports server errors to PostHog error tracking. Leave it out to send nothing. */
586
+ error_tracking: v.optional(
587
+ v.strictObject({
588
+ provider: v.literal('posthog'),
589
+ host: v.optional(urlSchema, POSTHOG_DEFAULT_HOST),
590
+ project_api_key: v.optional(configurableTextSchema, {
591
+ from_env: DEFAULT_SECRET_NAMES.posthogProjectAPIKey
592
+ })
593
+ })
506
594
  )
507
595
  })
508
596
 
@@ -1,4 +1,6 @@
1
- import { sql, type Expression } from 'kysely'
1
+ import { sql, type Expression, type Transaction } from 'kysely'
2
+
3
+ import type { CloudDatabase } from './tables'
2
4
 
3
5
  export const CURRENT_TIMESTAMP = sql<Date>`current_timestamp`
4
6
  export const EMPTY_JSON_OBJECT = sql`'{}'::jsonb`
@@ -11,3 +13,15 @@ export function checkColumnIn(column: string, values: readonly string[]): Expres
11
13
  }
12
14
  return sql<boolean>`${sql.ref(column)} in (${sql.join(values.map((value) => sql.lit(value)))})`
13
15
  }
16
+
17
+ /**
18
+ * Holds a lock named `key` until the transaction ends, for a check and a write that must not
19
+ * interleave with another transaction's, such as reserving storage from an account's allowance,
20
+ * which spans rows no single one of which could be locked for it.
21
+ */
22
+ export async function lockForTransaction(
23
+ transaction: Transaction<CloudDatabase>,
24
+ key: string
25
+ ): Promise<void> {
26
+ await sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(transaction)
27
+ }
@@ -1,67 +1,38 @@
1
1
  import type { Kysely } from 'kysely'
2
2
  import { Migrator, type Migration, type MigrationProvider } from 'kysely/migration'
3
3
 
4
- import * as foundation from './migrations/001_foundation'
5
- import * as cleanupClaims from './migrations/002_upload_cleanup_claims'
6
- import * as documentCleanupClaims from './migrations/003_document_cleanup_claims'
7
- import * as documentSharing from './migrations/004_document_sharing'
8
- import * as documentCollaborationEpoch from './migrations/005_document_collaboration_epoch'
9
- import * as invitationContinuation from './migrations/006_invitation_continuation'
10
- import * as collaborationState from './migrations/007_collaboration_state'
11
- import * as storageReservations from './migrations/008_storage_reservations'
12
- import * as workspaceEntitlements from './migrations/009_workspace_entitlements'
13
- import * as uploadFinalization from './migrations/010_upload_finalization'
14
- import * as uploadFinalizationLease from './migrations/011_upload_finalization_lease'
15
- import * as transactionalEmail from './migrations/012_transactional_email'
16
- import * as adminEnrollment from './migrations/013_admin_enrollment'
17
- import * as enrollmentEmailKinds from './migrations/014_enrollment_email_kinds'
18
- import * as cloudRateLimit from './migrations/015_cloud_rate_limit'
19
- import * as authSchema from './migrations/016_auth_schema'
20
- import * as authenticationEmailKinds from './migrations/017_authentication_email_kinds'
21
- import * as authenticationMFA from './migrations/018_authentication_mfa'
22
- import * as betterAuthAccountIssuer from './migrations/019_better_auth_account_issuer'
23
- import * as workspaceInvitations from './migrations/020_workspace_invitations'
24
- import * as documentVersions from './migrations/021_document_versions'
25
- import * as entitlementExternalVersion from './migrations/022_entitlement_external_version'
26
- import * as documentImages from './migrations/023_document_images'
27
- import * as accountActivity from './migrations/024_account_activity'
28
- import * as tableNames from './migrations/025_table_names'
29
- import * as userPicture from './migrations/026_user_picture'
30
- import * as documentKind from './migrations/027_document_kind'
4
+ import * as accounts from './migrations/001_accounts'
5
+ import * as workspaces from './migrations/002_workspaces'
6
+ import * as storage from './migrations/003_storage'
7
+ import * as documents from './migrations/004_documents'
8
+ import * as sharing from './migrations/005_sharing'
9
+ import * as operations from './migrations/006_operations'
10
+ import * as trash from './migrations/007_trash'
11
+ import * as terms from './migrations/008_terms'
31
12
  import type { CloudDatabase } from './tables'
32
13
 
33
- const migrations: Record<string, Migration> = {
34
- '001_foundation': foundation,
35
- '002_upload_cleanup_claims': cleanupClaims,
36
- '003_document_cleanup_claims': documentCleanupClaims,
37
- '004_document_sharing': documentSharing,
38
- '005_document_collaboration_epoch': documentCollaborationEpoch,
39
- '006_invitation_continuation': invitationContinuation,
40
- '007_collaboration_state': collaborationState,
41
- '008_storage_reservations': storageReservations,
42
- '009_workspace_entitlements': workspaceEntitlements,
43
- '010_upload_finalization': uploadFinalization,
44
- '011_upload_finalization_lease': uploadFinalizationLease,
45
- '012_transactional_email': transactionalEmail,
46
- '013_admin_enrollment': adminEnrollment,
47
- '014_enrollment_email_kinds': enrollmentEmailKinds,
48
- '015_cloud_rate_limit': cloudRateLimit,
49
- '016_auth_schema': authSchema,
50
- '017_authentication_email_kinds': authenticationEmailKinds,
51
- '018_authentication_mfa': authenticationMFA,
52
- '019_better_auth_account_issuer': betterAuthAccountIssuer,
53
- '020_workspace_invitations': workspaceInvitations,
54
- '021_document_versions': documentVersions,
55
- '022_entitlement_external_version': entitlementExternalVersion,
56
- '023_document_images': documentImages,
57
- '024_account_activity': accountActivity,
58
- '025_table_names': tableNames,
59
- '026_user_picture': userPicture,
60
- '027_document_kind': documentKind
14
+ /**
15
+ * A migration runs before the code it ships with, while the previous release still serves, so it
16
+ * only adds (expand): no table or column dropped, renamed, retyped, or newly required. One that
17
+ * must (contract) names each table or `table.column` it changes in `contracts`, and ships a
18
+ * release after the last code that used them (`tests/integration/server/db/expand.test.ts`).
19
+ */
20
+ export type CloudMigration = Migration & { contracts?: readonly string[] }
21
+
22
+ const migrations: Record<string, CloudMigration> = {
23
+ '001_accounts': accounts,
24
+ '002_workspaces': workspaces,
25
+ '003_storage': storage,
26
+ '004_documents': documents,
27
+ '005_sharing': sharing,
28
+ '006_operations': operations,
29
+ '007_trash': trash,
30
+ '008_terms': terms
61
31
  }
62
32
 
63
- class CloudMigrationProvider implements MigrationProvider {
64
- async getMigrations(): Promise<Record<string, Migration>> {
33
+ /** Cloud's migrations, in order. */
34
+ export class CloudMigrationProvider implements MigrationProvider {
35
+ async getMigrations(): Promise<Record<string, CloudMigration>> {
65
36
  return migrations
66
37
  }
67
38
  }
@@ -71,46 +42,11 @@ export type CloudAuthMigration = {
71
42
  schemaVersion: string
72
43
  }
73
44
 
74
- const REQUIRED_AUTH_SCHEMA: Record<string, string[]> = {
75
- user: [
76
- 'id',
77
- 'name',
78
- 'email',
79
- 'email_verified',
80
- 'created_at',
81
- 'updated_at',
82
- 'role',
83
- 'banned',
84
- 'two_factor_enabled'
85
- ],
86
- session: ['id', 'expires_at', 'token', 'user_id', 'impersonated_by'],
87
- account: ['id', 'account_id', 'provider_id', 'user_id'],
88
- verification: ['id', 'identifier', 'value', 'expires_at'],
89
- device_code: ['id', 'device_code', 'user_code', 'status', 'client_id'],
90
- rate_limit: ['id', 'key', 'count', 'last_request'],
91
- two_factor: [
92
- 'id',
93
- 'secret',
94
- 'backup_codes',
95
- 'user_id',
96
- 'verified',
97
- 'failed_verification_count',
98
- 'locked_until'
99
- ],
100
- passkey: ['id', 'public_key', 'user_id', 'credential_id', 'counter', 'device_type', 'backed_up']
101
- }
102
-
103
- async function existingAuthSchema(
104
- database: Kysely<CloudDatabase>
105
- ): Promise<Map<string, Set<string>>> {
106
- const tables = await database.introspection.getTables()
107
- return new Map(
108
- tables
109
- .filter((table) => Object.hasOwn(REQUIRED_AUTH_SCHEMA, table.name))
110
- .map((table) => [table.name, new Set(table.columns.map((column) => column.name))])
111
- )
112
- }
113
-
45
+ /**
46
+ * Better Auth's tables come from its own migration API, once, after Cloud's: the version they
47
+ * were built for is recorded, and a different one stops startup until someone migrates it
48
+ * deliberately, since Better Auth cannot say what an upgrade between its versions changes.
49
+ */
114
50
  async function migrateAuthSchema(
115
51
  database: Kysely<CloudDatabase>,
116
52
  migration: CloudAuthMigration
@@ -128,23 +64,7 @@ async function migrateAuthSchema(
128
64
  }
129
65
  return
130
66
  }
131
-
132
- const existing = await existingAuthSchema(database)
133
- if (existing.size === 0) {
134
- await migration.run()
135
- } else {
136
- const missing = Object.entries(REQUIRED_AUTH_SCHEMA).flatMap(([table, requiredColumns]) => {
137
- const columns = existing.get(table)
138
- if (!columns) return [table]
139
- return requiredColumns
140
- .filter((column) => !columns.has(column))
141
- .map((column) => `${table}.${column}`)
142
- })
143
- if (missing.length > 0) {
144
- throw new Error(`Existing Better Auth schema is incomplete: ${missing.join(', ')}`)
145
- }
146
- }
147
-
67
+ await migration.run()
148
68
  await database
149
69
  .insertInto('authSchemaVersion')
150
70
  .values({ id: 'better-auth', version: migration.schemaVersion, updatedAt: new Date() })
@@ -0,0 +1,79 @@
1
+ import type { Kysely } from 'kysely'
2
+
3
+ import { addChecks, addIndexes, dropTables, now, required } from './schema'
4
+
5
+ /** What Cloud keeps about an account beside Better Auth's tables: its plan, sign-ins, and picture. */
6
+ const TABLES = [
7
+ 'auth_schema_version',
8
+ 'account_entitlement',
9
+ 'mfa_assurance',
10
+ 'sign_in',
11
+ 'user_picture',
12
+ 'api_rate_limit'
13
+ ]
14
+
15
+ export async function up(database: Kysely<unknown>): Promise<void> {
16
+ // The Better Auth schema version this database was built for.
17
+ await database.schema
18
+ .createTable('auth_schema_version')
19
+ .addColumn('id', 'text', (column) => column.primaryKey())
20
+ .addColumn('version', 'text', required)
21
+ .addColumn('updated_at', 'timestamptz', now)
22
+ .execute()
23
+ // An account's plan, as billing or an operator set it; its workspaces share it.
24
+ await database.schema
25
+ .createTable('account_entitlement')
26
+ .addColumn('user_id', 'text', (column) => column.primaryKey())
27
+ .addColumn('values', 'jsonb', required)
28
+ .addColumn('source', 'text', required)
29
+ .addColumn('revision', 'integer', (column) => column.notNull().defaultTo(1))
30
+ .addColumn('external_version', 'bigint')
31
+ .addColumn('updated_at', 'timestamptz', now)
32
+ .execute()
33
+ await database.schema
34
+ .createTable('mfa_assurance')
35
+ .addColumn('session_id', 'uuid', (column) => column.primaryKey())
36
+ .addColumn('user_id', 'uuid', required)
37
+ .addColumn('method', 'text', required)
38
+ .addColumn('verified_at', 'timestamptz', required)
39
+ .execute()
40
+ await database.schema
41
+ .createTable('sign_in')
42
+ .addColumn('id', 'uuid', (column) => column.primaryKey())
43
+ .addColumn('user_id', 'uuid', required)
44
+ .addColumn('session_id', 'uuid')
45
+ .addColumn('method', 'text', required)
46
+ .addColumn('ip_address', 'text')
47
+ .addColumn('user_agent', 'text')
48
+ .addColumn('created_at', 'timestamptz', now)
49
+ .execute()
50
+ await database.schema
51
+ .createTable('user_picture')
52
+ .addColumn('user_id', 'uuid', (column) => column.primaryKey())
53
+ .addColumn('bytes', 'bytea', required)
54
+ .addColumn('format', 'text', required)
55
+ .addColumn('checksum', 'text', required)
56
+ .addColumn('source', 'text', required)
57
+ .addColumn('created_at', 'timestamptz', now)
58
+ .execute()
59
+ // OpenPencil's own rate limits; Better Auth keeps its own in `rate_limit`.
60
+ await database.schema
61
+ .createTable('api_rate_limit')
62
+ .addColumn('key_hash', 'text', (column) => column.primaryKey())
63
+ .addColumn('window_started_at', 'timestamptz', required)
64
+ .addColumn('request_count', 'integer', (column) => column.notNull().defaultTo(1))
65
+ .addColumn('updated_at', 'timestamptz', now)
66
+ .execute()
67
+ await addChecks(database, [
68
+ ['user_picture', 'format', ['png', 'jpeg']],
69
+ ['user_picture', 'source', ['upload', 'provider']]
70
+ ])
71
+ await addIndexes(database, [
72
+ ['sign_in', ['user_id', 'created_at']],
73
+ ['sign_in', ['session_id']]
74
+ ])
75
+ }
76
+
77
+ export async function down(database: Kysely<unknown>): Promise<void> {
78
+ await dropTables(database, TABLES)
79
+ }
@@ -0,0 +1,48 @@
1
+ import type { Kysely } from 'kysely'
2
+
3
+ import { addChecks, addIndexes, dropTables, now, required, ROLES, withInvitation } from './schema'
4
+
5
+ /** Workspaces, their members, and the people invited to join. */
6
+ const TABLES = ['workspace', 'workspace_member', 'workspace_invitation']
7
+
8
+ export async function up(database: Kysely<unknown>): Promise<void> {
9
+ // A workspace takes its limits from its owner's plan.
10
+ await database.schema
11
+ .createTable('workspace')
12
+ .addColumn('id', 'uuid', (column) => column.primaryKey())
13
+ .addColumn('name', 'text', required)
14
+ .addColumn('slug', 'text', (column) => column.notNull().unique())
15
+ .addColumn('created_by', 'text', required)
16
+ .addColumn('owner_id', 'text', required)
17
+ .addColumn('created_at', 'timestamptz', now)
18
+ .addColumn('updated_at', 'timestamptz', now)
19
+ .execute()
20
+ await database.schema
21
+ .createTable('workspace_member')
22
+ .addColumn('workspace_id', 'uuid', (column) =>
23
+ column.notNull().references('workspace.id').onDelete('cascade')
24
+ )
25
+ .addColumn('user_id', 'text', required)
26
+ .addColumn('role', 'text', required)
27
+ .addColumn('created_at', 'timestamptz', now)
28
+ .addPrimaryKeyConstraint('workspace_member_pkey', ['workspace_id', 'user_id'])
29
+ .execute()
30
+ await withInvitation(database.schema.createTable('workspace_invitation'), 'role')
31
+ .addColumn('workspace_id', 'uuid', (column) =>
32
+ column.notNull().references('workspace.id').onDelete('cascade')
33
+ )
34
+ .execute()
35
+ await addChecks(database, [
36
+ ['workspace_member', 'role', ROLES],
37
+ ['workspace_invitation', 'role', ROLES]
38
+ ])
39
+ await addIndexes(database, [
40
+ ['workspace', ['owner_id']],
41
+ ['workspace_member', ['user_id']],
42
+ ['workspace_invitation', ['workspace_id', 'revoked_at']]
43
+ ])
44
+ }
45
+
46
+ export async function down(database: Kysely<unknown>): Promise<void> {
47
+ await dropTables(database, TABLES)
48
+ }
@@ -0,0 +1,44 @@
1
+ import type { Kysely } from 'kysely'
2
+
3
+ import { dropTables, now, required } from './schema'
4
+
5
+ /** Files in the object store, a workspace's images among them, and how much each workspace uses. */
6
+ const TABLES = ['storage_object', 'workspace_storage_usage', 'workspace_image']
7
+
8
+ export async function up(database: Kysely<unknown>): Promise<void> {
9
+ // A stored file, by content; revisions, snapshots, and images refer to one.
10
+ await database.schema
11
+ .createTable('storage_object')
12
+ .addColumn('id', 'uuid', (column) => column.primaryKey())
13
+ .addColumn('object_key', 'text', (column) => column.notNull().unique())
14
+ .addColumn('checksum', 'text', required)
15
+ .addColumn('byte_size', 'bigint', required)
16
+ .addColumn('content_type', 'text', required)
17
+ .addColumn('created_at', 'timestamptz', now)
18
+ .execute()
19
+ await database.schema
20
+ .createTable('workspace_storage_usage')
21
+ .addColumn('workspace_id', 'uuid', (column) =>
22
+ column.primaryKey().references('workspace.id').onDelete('cascade')
23
+ )
24
+ .addColumn('committed_bytes', 'bigint', (column) => column.notNull().defaultTo(0))
25
+ .addColumn('updated_at', 'timestamptz', now)
26
+ .execute()
27
+ // A workspace's images, each stored once; revisions name the ones they use.
28
+ await database.schema
29
+ .createTable('workspace_image')
30
+ .addColumn('workspace_id', 'uuid', (column) =>
31
+ column.notNull().references('workspace.id').onDelete('cascade')
32
+ )
33
+ .addColumn('checksum', 'text', required)
34
+ .addColumn('storage_object_id', 'uuid', (column) =>
35
+ column.notNull().unique().references('storage_object.id')
36
+ )
37
+ .addColumn('touched_at', 'timestamptz', now)
38
+ .addPrimaryKeyConstraint('workspace_image_pkey', ['workspace_id', 'checksum'])
39
+ .execute()
40
+ }
41
+
42
+ export async function down(database: Kysely<unknown>): Promise<void> {
43
+ await dropTables(database, TABLES)
44
+ }