arocapi 5.0.0-beta.1 → 5.0.0-beta.10

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 (234) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +37 -802
  3. package/dist/app.d.ts +38 -20
  4. package/dist/app.js +62 -40
  5. package/dist/app.js.map +1 -1
  6. package/dist/routes/capabilities.d.ts +7 -0
  7. package/dist/routes/capabilities.js +13 -0
  8. package/dist/routes/capabilities.js.map +1 -0
  9. package/dist/routes/entities.d.ts +5 -2
  10. package/dist/routes/entities.js +37 -57
  11. package/dist/routes/entities.js.map +1 -1
  12. package/dist/routes/entity.d.ts +7 -2
  13. package/dist/routes/entity.js +13 -29
  14. package/dist/routes/entity.js.map +1 -1
  15. package/dist/routes/file.d.ts +8 -2
  16. package/dist/routes/file.js +37 -72
  17. package/dist/routes/file.js.map +1 -1
  18. package/dist/routes/files.d.ts +5 -2
  19. package/dist/routes/files.js +24 -39
  20. package/dist/routes/files.js.map +1 -1
  21. package/dist/routes/metadata.d.ts +11 -5
  22. package/dist/routes/metadata.js +24 -68
  23. package/dist/routes/metadata.js.map +1 -1
  24. package/dist/routes/search.d.ts +8 -7
  25. package/dist/routes/search.js +90 -119
  26. package/dist/routes/search.js.map +1 -1
  27. package/dist/search/advanced.d.ts +8 -0
  28. package/dist/search/advanced.js +198 -0
  29. package/dist/search/advanced.js.map +1 -0
  30. package/dist/search/backend.d.ts +95 -0
  31. package/dist/search/backend.js +5 -0
  32. package/dist/search/backend.js.map +1 -0
  33. package/dist/search/fields.d.ts +63 -0
  34. package/dist/search/fields.js +203 -0
  35. package/dist/search/fields.js.map +1 -0
  36. package/dist/search/opensearch/advanced.d.ts +4 -0
  37. package/dist/search/opensearch/advanced.js +28 -0
  38. package/dist/search/opensearch/advanced.js.map +1 -0
  39. package/dist/search/opensearch/opensearch.d.ts +16 -0
  40. package/dist/search/opensearch/opensearch.js +187 -0
  41. package/dist/search/opensearch/opensearch.js.map +1 -0
  42. package/dist/search/opensearch/visibility.d.ts +3 -0
  43. package/dist/search/opensearch/visibility.js +27 -0
  44. package/dist/search/opensearch/visibility.js.map +1 -0
  45. package/dist/search/postgres/advanced.d.ts +7 -0
  46. package/dist/search/postgres/advanced.js +54 -0
  47. package/dist/search/postgres/advanced.js.map +1 -0
  48. package/dist/search/postgres/facets.d.ts +2 -0
  49. package/dist/search/postgres/facets.js +27 -0
  50. package/dist/search/postgres/facets.js.map +1 -0
  51. package/dist/search/postgres/geo.d.ts +6 -0
  52. package/dist/search/postgres/geo.js +42 -0
  53. package/dist/search/postgres/geo.js.map +1 -0
  54. package/dist/search/postgres/postgres.d.ts +19 -0
  55. package/dist/search/postgres/postgres.js +157 -0
  56. package/dist/search/postgres/postgres.js.map +1 -0
  57. package/dist/search/postgres/values.d.ts +8 -0
  58. package/dist/search/postgres/values.js +20 -0
  59. package/dist/search/postgres/values.js.map +1 -0
  60. package/dist/search/postgres/visibility.d.ts +4 -0
  61. package/dist/search/postgres/visibility.js +38 -0
  62. package/dist/search/postgres/visibility.js.map +1 -0
  63. package/dist/search/requestFilters.d.ts +39 -0
  64. package/dist/search/requestFilters.js +125 -0
  65. package/dist/search/requestFilters.js.map +1 -0
  66. package/dist/search/visibility.d.ts +51 -0
  67. package/dist/search/visibility.js +100 -0
  68. package/dist/search/visibility.js.map +1 -0
  69. package/dist/storage/backend.d.ts +58 -0
  70. package/dist/storage/backend.js +2 -0
  71. package/dist/storage/backend.js.map +1 -0
  72. package/dist/storage/deliver.d.ts +12 -0
  73. package/dist/storage/deliver.js +34 -0
  74. package/dist/storage/deliver.js.map +1 -0
  75. package/dist/storage/directory/directory.d.ts +6 -0
  76. package/dist/storage/directory/directory.js +24 -0
  77. package/dist/storage/directory/directory.js.map +1 -0
  78. package/dist/storage/entity-meta/entity-meta.d.ts +5 -0
  79. package/dist/storage/entity-meta/entity-meta.js +14 -0
  80. package/dist/storage/entity-meta/entity-meta.js.map +1 -0
  81. package/dist/storage/location.d.ts +19 -0
  82. package/dist/storage/location.js +36 -0
  83. package/dist/storage/location.js.map +1 -0
  84. package/dist/storage/ocfl/ocfl.d.ts +6 -0
  85. package/dist/storage/ocfl/ocfl.js +45 -0
  86. package/dist/storage/ocfl/ocfl.js.map +1 -0
  87. package/dist/storage/results.d.ts +7 -0
  88. package/dist/storage/results.js +22 -0
  89. package/dist/storage/results.js.map +1 -0
  90. package/dist/storage/s3/s3.d.ts +10 -0
  91. package/dist/storage/s3/s3.js +47 -0
  92. package/dist/storage/s3/s3.js.map +1 -0
  93. package/dist/transformers/default.d.ts +11 -22
  94. package/dist/transformers/default.js +41 -15
  95. package/dist/transformers/default.js.map +1 -1
  96. package/dist/types/access.d.ts +9 -0
  97. package/dist/types/access.js +2 -0
  98. package/dist/types/access.js.map +1 -0
  99. package/dist/types/context.d.ts +6 -0
  100. package/dist/types/context.js +2 -0
  101. package/dist/types/context.js.map +1 -0
  102. package/dist/types/transformers.d.ts +4 -10
  103. package/dist/types/visibility.d.ts +6 -0
  104. package/dist/types/visibility.js +2 -0
  105. package/dist/types/visibility.js.map +1 -0
  106. package/dist/utils/access.d.ts +17 -0
  107. package/dist/utils/access.js +41 -0
  108. package/dist/utils/access.js.map +1 -0
  109. package/dist/utils/errors.d.ts +19 -10
  110. package/dist/utils/errors.js +44 -8
  111. package/dist/utils/errors.js.map +1 -1
  112. package/dist/utils/headers.d.ts +1 -1
  113. package/dist/utils/headers.js +10 -1
  114. package/dist/utils/headers.js.map +1 -1
  115. package/dist/utils/validation.d.ts +2 -0
  116. package/dist/utils/validation.js +8 -0
  117. package/dist/utils/validation.js.map +1 -0
  118. package/dist/utils/visibility.d.ts +18 -0
  119. package/dist/utils/visibility.js +16 -0
  120. package/dist/utils/visibility.js.map +1 -0
  121. package/package.json +82 -40
  122. package/prisma/models/entity.prisma +9 -8
  123. package/prisma/models/entitySearch.prisma +21 -0
  124. package/prisma/models/file.prisma +3 -3
  125. package/src/app.ts +168 -95
  126. package/src/routes/capabilities.ts +22 -0
  127. package/src/routes/entities.ts +48 -67
  128. package/src/routes/entity.ts +21 -35
  129. package/src/routes/file.ts +53 -103
  130. package/src/routes/files.ts +31 -47
  131. package/src/routes/metadata.ts +42 -98
  132. package/src/routes/search.ts +131 -151
  133. package/src/search/advanced.ts +258 -0
  134. package/src/search/backend.ts +91 -0
  135. package/src/search/fields.ts +320 -0
  136. package/src/search/opensearch/advanced.ts +36 -0
  137. package/src/search/opensearch/opensearch.ts +290 -0
  138. package/src/search/opensearch/visibility.ts +38 -0
  139. package/src/search/postgres/advanced.ts +76 -0
  140. package/src/search/postgres/facets.ts +34 -0
  141. package/src/search/postgres/geo.ts +58 -0
  142. package/src/search/postgres/postgres.ts +232 -0
  143. package/src/search/postgres/values.ts +33 -0
  144. package/src/search/postgres/visibility.ts +54 -0
  145. package/src/search/requestFilters.ts +178 -0
  146. package/src/search/visibility.ts +193 -0
  147. package/src/storage/backend.ts +75 -0
  148. package/src/storage/deliver.ts +65 -0
  149. package/src/storage/directory/directory.ts +39 -0
  150. package/src/storage/entity-meta/entity-meta.ts +25 -0
  151. package/src/storage/location.ts +78 -0
  152. package/src/storage/ocfl/ocfl.ts +71 -0
  153. package/src/storage/results.ts +32 -0
  154. package/src/storage/s3/s3.ts +79 -0
  155. package/src/transformers/default.ts +115 -85
  156. package/src/types/access.ts +25 -0
  157. package/src/types/context.ts +15 -0
  158. package/src/types/transformers.ts +8 -34
  159. package/src/types/visibility.ts +21 -0
  160. package/src/utils/access.ts +80 -0
  161. package/src/utils/errors.ts +68 -11
  162. package/src/utils/headers.ts +22 -2
  163. package/src/utils/validation.ts +11 -0
  164. package/src/utils/visibility.ts +56 -0
  165. package/dist/app.test.d.ts +0 -1
  166. package/dist/app.test.js +0 -82
  167. package/dist/app.test.js.map +0 -1
  168. package/dist/index.dev.d.ts +0 -1
  169. package/dist/index.dev.js +0 -156
  170. package/dist/index.dev.js.map +0 -1
  171. package/dist/routes/crate.test.d.ts +0 -1
  172. package/dist/routes/crate.test.js +0 -342
  173. package/dist/routes/crate.test.js.map +0 -1
  174. package/dist/routes/entities.test.d.ts +0 -1
  175. package/dist/routes/entities.test.js +0 -273
  176. package/dist/routes/entities.test.js.map +0 -1
  177. package/dist/routes/entity.test.d.ts +0 -1
  178. package/dist/routes/entity.test.js +0 -130
  179. package/dist/routes/entity.test.js.map +0 -1
  180. package/dist/routes/file.test.d.ts +0 -1
  181. package/dist/routes/file.test.js +0 -315
  182. package/dist/routes/file.test.js.map +0 -1
  183. package/dist/routes/files.test.d.ts +0 -1
  184. package/dist/routes/files.test.js +0 -222
  185. package/dist/routes/files.test.js.map +0 -1
  186. package/dist/routes/search.test.d.ts +0 -1
  187. package/dist/routes/search.test.js +0 -780
  188. package/dist/routes/search.test.js.map +0 -1
  189. package/dist/test/helpers/fastify.d.ts +0 -9
  190. package/dist/test/helpers/fastify.js +0 -18
  191. package/dist/test/helpers/fastify.js.map +0 -1
  192. package/dist/test/integration.setup.d.ts +0 -29
  193. package/dist/test/integration.setup.js +0 -187
  194. package/dist/test/integration.setup.js.map +0 -1
  195. package/dist/test/integration.test.d.ts +0 -1
  196. package/dist/test/integration.test.js +0 -396
  197. package/dist/test/integration.test.js.map +0 -1
  198. package/dist/transformers/default.test.d.ts +0 -1
  199. package/dist/transformers/default.test.js +0 -163
  200. package/dist/transformers/default.test.js.map +0 -1
  201. package/dist/transformers/transformer.test.d.ts +0 -1
  202. package/dist/transformers/transformer.test.js +0 -187
  203. package/dist/transformers/transformer.test.js.map +0 -1
  204. package/dist/types/fileHandlers.d.ts +0 -41
  205. package/dist/types/fileHandlers.js +0 -2
  206. package/dist/types/fileHandlers.js.map +0 -1
  207. package/dist/utils/errors.test.d.ts +0 -1
  208. package/dist/utils/errors.test.js +0 -66
  209. package/dist/utils/errors.test.js.map +0 -1
  210. package/dist/utils/queryBuilder.d.ts +0 -35
  211. package/dist/utils/queryBuilder.js +0 -98
  212. package/dist/utils/queryBuilder.js.map +0 -1
  213. package/prisma.config.ts +0 -9
  214. package/src/app.test.ts +0 -112
  215. package/src/index.dev.ts +0 -200
  216. package/src/reset.d.ts +0 -1
  217. package/src/routes/__snapshots__/entities.test.ts.snap +0 -96
  218. package/src/routes/__snapshots__/entity.test.ts.snap +0 -74
  219. package/src/routes/__snapshots__/search.test.ts.snap +0 -165
  220. package/src/routes/crate.test.ts +0 -423
  221. package/src/routes/entities.test.ts +0 -320
  222. package/src/routes/entity.test.ts +0 -160
  223. package/src/routes/file.test.ts +0 -395
  224. package/src/routes/files.test.ts +0 -278
  225. package/src/routes/search.test.ts +0 -903
  226. package/src/test/__snapshots__/integration.test.ts.snap +0 -18
  227. package/src/test/helpers/fastify.ts +0 -27
  228. package/src/test/integration.setup.ts +0 -209
  229. package/src/test/integration.test.ts +0 -482
  230. package/src/transformers/default.test.ts +0 -184
  231. package/src/transformers/transformer.test.ts +0 -252
  232. package/src/types/fileHandlers.ts +0 -65
  233. package/src/utils/errors.test.ts +0 -75
  234. package/src/utils/queryBuilder.ts +0 -132
@@ -1,6 +1,18 @@
1
1
  import type { Entity, File, PrismaClient } from '../generated/prisma/client.js';
2
+ import type { AccessFunction, AccessInfo } from '../types/access.js';
3
+ import type { RequestContext } from '../types/context.js';
2
4
 
3
- type EntityWithFile = Entity & { file?: { id: string } | null };
5
+ /**
6
+ * An entity's stored database row: its Record fields, `meta`, `createdAt` and `updatedAt`
7
+ * Never sent as-is; `meta` can be large
8
+ */
9
+ export type EntityRow = Entity;
10
+
11
+ /**
12
+ * A file's stored database row with its file entity's row
13
+ * Never sent as-is; `meta` can be large
14
+ */
15
+ export type FileRow = File & { entity: EntityRow };
4
16
 
5
17
  /**
6
18
  * Entity reference - used for memberOf and rootCollection
@@ -11,8 +23,8 @@ type EntityReference = {
11
23
  };
12
24
 
13
25
  /**
14
- * Base entity shape - output of base transformation with unresolved references
15
- * Used internally before reference resolution
26
+ * Base entity shape - an entity's Record fields with memberOf and rootCollection as ids
27
+ * The access function receives this shape, so deciding access never looks up parent entities
16
28
  */
17
29
  export type BaseEntity = {
18
30
  id: string;
@@ -41,31 +53,13 @@ export type StandardEntity = {
41
53
  };
42
54
 
43
55
  /**
44
- * Access information for an entity
45
- */
46
- type AccessInfo = {
47
- metadata: boolean;
48
- content: boolean;
49
- metadataAuthorizationUrl?: string;
50
- contentAuthorizationUrl?: string;
51
- };
52
-
53
- /**
54
- * Authorised entity - includes access information
55
- * This is the output of the access transformer
56
+ * Authorised entity - a standard entity with the access function's result attached
56
57
  */
57
58
  export type AuthorisedEntity = StandardEntity & {
58
59
  access: AccessInfo;
59
60
  };
60
61
 
61
- /**
62
- * Access information for a file
63
- * Files only control content access - metadata is always accessible
64
- */
65
- type FileAccessInfo = {
66
- content: boolean;
67
- contentAuthorizationUrl?: string;
68
- };
62
+ type FileAccessInfo = Pick<AccessInfo, 'content' | 'contentAuthorizationUrl'>;
69
63
 
70
64
  /**
71
65
  * Standard file shape - output of base file transformation
@@ -79,9 +73,7 @@ export type StandardFile = {
79
73
  };
80
74
 
81
75
  /**
82
- * Authorised file - includes access information
83
- * This is the output of the file access transformer
84
- * File metadata is always accessible - only content access is controlled
76
+ * Authorised file - a standard file with its file entity's Content access attached
85
77
  */
86
78
  export type AuthorisedFile = StandardFile & {
87
79
  access: FileAccessInfo;
@@ -90,9 +82,8 @@ export type AuthorisedFile = StandardFile & {
90
82
  /**
91
83
  * Base entity transformer - always applied first
92
84
  * Transforms raw database entity to base entity shape with unresolved references
93
- * Accepts Entity with optional file relation included
94
85
  */
95
- export const baseEntityTransformer = (entity: EntityWithFile): BaseEntity => {
86
+ export const baseEntityTransformer = (entity: EntityRow): BaseEntity => {
96
87
  const base: BaseEntity = {
97
88
  id: entity.id,
98
89
  name: entity.name,
@@ -107,72 +98,17 @@ export const baseEntityTransformer = (entity: EntityWithFile): BaseEntity => {
107
98
  return base;
108
99
  };
109
100
 
110
- /**
111
- * All Public Access Transformer - grants full access to metadata and content
112
- *
113
- * WARNING: This transformer makes ALL content publicly accessible without restrictions.
114
- * Only use this for fully public datasets where no access control is needed.
115
- *
116
- * For repositories with restricted content, implement a custom accessTransformer
117
- * that checks user permissions and licenses.
118
- *
119
- * @example
120
- * ```typescript
121
- * await server.register(arocapi, {
122
- * prisma,
123
- * opensearch,
124
- * accessTransformer: AllPublicAccessTransformer, // Explicit choice for public data
125
- * });
126
- * ```
127
- */
128
- export const AllPublicAccessTransformer = (entity: StandardEntity): AuthorisedEntity => ({
129
- ...entity,
130
- access: {
131
- metadata: true,
132
- content: true,
133
- },
134
- });
135
-
136
101
  /**
137
102
  * Base file transformer - always applied first
138
103
  * Transforms raw database file to standard file shape (without access)
139
104
  */
140
- export const baseFileTransformer = (file: File): StandardFile => ({
105
+ const baseFileTransformer = (file: File): StandardFile => ({
141
106
  id: file.id,
142
107
  filename: file.filename,
143
108
  mediaType: file.mediaType,
144
109
  size: Number(file.size),
145
110
  });
146
111
 
147
- /**
148
- * All Public File Access Transformer - grants full access to file content
149
- *
150
- * WARNING: This transformer makes ALL file content publicly accessible without restrictions.
151
- * Only use this for fully public datasets where no access control is needed.
152
- *
153
- * For repositories with restricted content, implement a custom fileAccessTransformer
154
- * that checks user permissions and licenses.
155
- *
156
- * Note: File metadata (filename, size, mediaType, etc.) is always accessible.
157
- * This transformer only controls content access.
158
- *
159
- * @example
160
- * ```typescript
161
- * await server.register(arocapi, {
162
- * prisma,
163
- * opensearch,
164
- * accessTransformer: AllPublicAccessTransformer,
165
- * fileAccessTransformer: AllPublicFileAccessTransformer, // Explicit choice for public data
166
- * });
167
- * ```
168
- */
169
- export const AllPublicFileAccessTransformer = (file: StandardFile): AuthorisedFile => ({
170
- ...file,
171
- access: {
172
- content: true,
173
- },
174
- });
175
-
176
112
  /**
177
113
  * Resolve entity references (memberOf/rootCollection) to objects with id and name
178
114
  * Batch-fetches all referenced entities in a single query for performance
@@ -181,7 +117,7 @@ export const AllPublicFileAccessTransformer = (file: StandardFile): AuthorisedFi
181
117
  * @param prisma - Prisma client instance
182
118
  * @returns Map of entity ID to EntityReference object
183
119
  */
184
- export const resolveEntityReferences = async (
120
+ const resolveEntityReferences = async (
185
121
  entities: Array<{ memberOf: string | null; rootCollection: string | null }>,
186
122
  prisma: PrismaClient,
187
123
  ): Promise<Map<string, EntityReference>> => {
@@ -208,3 +144,97 @@ export const resolveEntityReferences = async (
208
144
 
209
145
  return new Map(refs.map((r) => [r.id, { id: r.id, name: r.name }]));
210
146
  };
147
+
148
+ /**
149
+ * Transform database entities to standard entities, resolving their references in one query
150
+ */
151
+ const toStandardEntities = async (entities: EntityRow[], prisma: PrismaClient): Promise<StandardEntity[]> => {
152
+ const refMap = await resolveEntityReferences(entities, prisma);
153
+
154
+ return entities.map((entity) => {
155
+ const base = baseEntityTransformer(entity);
156
+
157
+ return {
158
+ ...base,
159
+ memberOf: base.memberOf ? (refMap.get(base.memberOf) ?? null) : null,
160
+ rootCollection: base.rootCollection ? (refMap.get(base.rootCollection) ?? null) : null,
161
+ };
162
+ });
163
+ };
164
+
165
+ const pickAccess = ({
166
+ metadata,
167
+ content,
168
+ metadataAuthorizationUrl,
169
+ contentAuthorizationUrl,
170
+ }: AccessInfo): AccessInfo => ({
171
+ metadata,
172
+ content,
173
+ ...(metadataAuthorizationUrl && { metadataAuthorizationUrl }),
174
+ ...(contentAuthorizationUrl && { contentAuthorizationUrl }),
175
+ });
176
+
177
+ /**
178
+ * Decide access to database entities with the access function
179
+ */
180
+ export const decideAccess = async (
181
+ entities: EntityRow[],
182
+ access: AccessFunction,
183
+ context: RequestContext,
184
+ ): Promise<AccessInfo[]> =>
185
+ Promise.all(entities.map(async (entity) => pickAccess(await access(baseEntityTransformer(entity), context, entity))));
186
+
187
+ /**
188
+ * Transform database entities to standard entities with the access function's result attached, in input order
189
+ */
190
+ export const authoriseEntities = async (
191
+ entities: EntityRow[],
192
+ prisma: PrismaClient,
193
+ access: AccessFunction,
194
+ context: RequestContext,
195
+ ): Promise<AuthorisedEntity[]> => {
196
+ const [standardEntities, entityAccess] = await Promise.all([
197
+ toStandardEntities(entities, prisma),
198
+ decideAccess(entities, access, context),
199
+ ]);
200
+
201
+ return standardEntities.map((entity, i) => ({ ...entity, access: entityAccess[i] }));
202
+ };
203
+
204
+ /**
205
+ * Transform database files to standard files with their file entity's Content access attached, in input order
206
+ */
207
+ export const authoriseFiles = async (
208
+ files: FileRow[],
209
+ access: AccessFunction,
210
+ context: RequestContext,
211
+ ): Promise<AuthorisedFile[]> => {
212
+ const fileEntityAccess = await decideAccess(
213
+ files.map((file) => file.entity),
214
+ access,
215
+ context,
216
+ );
217
+
218
+ return files.map((file, i) => {
219
+ const { metadata: _metadata, metadataAuthorizationUrl: _metadataUrl, ...fileAccess } = fileEntityAccess[i];
220
+
221
+ return { ...baseFileTransformer(file), access: fileAccess };
222
+ });
223
+ };
224
+
225
+ /**
226
+ * Apply consumer transformers in order, each receiving the previous one's output
227
+ */
228
+ export const applyTransformers = async <T, R>(
229
+ item: T,
230
+ transformers: Array<(item: T, context: RequestContext, row: R) => Promise<T> | T>,
231
+ context: RequestContext,
232
+ row: R,
233
+ ): Promise<T> => {
234
+ let result = item;
235
+ for (const transformer of transformers) {
236
+ result = await transformer(result, context, row);
237
+ }
238
+
239
+ return result;
240
+ };
@@ -0,0 +1,25 @@
1
+ import type { BaseEntity, EntityRow } from '../transformers/default.js';
2
+ import type { RequestContext } from './context.js';
3
+
4
+ /**
5
+ * What a request may read of a visible entity: its Metadata and, for files, its Content
6
+ * Authorisation URLs point to where access can be requested and are only meaningful when the flag is false
7
+ */
8
+ export type AccessInfo = {
9
+ metadata: boolean;
10
+ content: boolean;
11
+ metadataAuthorizationUrl?: string;
12
+ contentAuthorizationUrl?: string;
13
+ };
14
+
15
+ /**
16
+ * Access function - required
17
+ * Decides access to an entity for this request from its Record fields and its stored row (e.g. a value the indexer kept in `meta`).
18
+ * A file's access is its file entity's access, decided with the file entity's row.
19
+ * The library attaches the result to responses and enforces it on the Metadata and Content routes.
20
+ */
21
+ export type AccessFunction = (
22
+ entity: BaseEntity,
23
+ context: RequestContext,
24
+ row: EntityRow,
25
+ ) => Promise<AccessInfo> | AccessInfo;
@@ -0,0 +1,15 @@
1
+ import type { FastifyInstance, FastifyRequest } from 'fastify';
2
+
3
+ /**
4
+ * Context passed to every consumer hook: visibility filters, the access function, transformers and handlers
5
+ */
6
+ export type RequestContext = {
7
+ request: FastifyRequest;
8
+ fastify: FastifyInstance;
9
+ };
10
+
11
+ /**
12
+ * Whether the request carries valid credentials
13
+ * Refusals are 401 for anonymous requests, so the client can prompt a login, and 403 otherwise
14
+ */
15
+ export type IsAuthenticated = (context: RequestContext) => Promise<boolean> | boolean;
@@ -1,52 +1,26 @@
1
- import type { FastifyInstance, FastifyRequest } from 'fastify';
2
- import type { AuthorisedEntity, AuthorisedFile, StandardEntity, StandardFile } from '../transformers/default.js';
3
-
4
- /**
5
- * Context provided to entity transformers
6
- */
7
- export type TransformerContext = {
8
- request: FastifyRequest;
9
- fastify: FastifyInstance;
10
- };
11
-
12
- /**
13
- * Access transformer function - required
14
- * Transforms StandardEntity to AuthorisedEntity by adding access information
15
- */
16
- export type AccessTransformer = (
17
- entity: StandardEntity,
18
- context: TransformerContext,
19
- ) => Promise<AuthorisedEntity> | AuthorisedEntity;
1
+ import type { AuthorisedEntity, AuthorisedFile, EntityRow, FileRow } from '../transformers/default.js';
2
+ import type { RequestContext } from './context.js';
20
3
 
21
4
  /**
22
5
  * Entity transformer function
23
6
  * Receives AuthorisedEntity and transforms it further
24
7
  * Transformers are applied as a pipeline, with each transformer receiving
25
- * the output of the previous one
8
+ * the output of the previous one, and every transformer receiving the entity's row
26
9
  */
27
10
  export type EntityTransformer<TInput = AuthorisedEntity, TOutput = TInput> = (
28
11
  entity: TInput,
29
- context: TransformerContext,
12
+ context: RequestContext,
13
+ row: EntityRow,
30
14
  ) => Promise<TOutput> | TOutput;
31
15
 
32
- /**
33
- * File access transformer function - required
34
- * Transforms StandardFile to AuthorisedFile by adding access information
35
- * File metadata (filename, size, mediaType, etc.) is always accessible
36
- * Only content access is controlled (access.content)
37
- */
38
- export type FileAccessTransformer = (
39
- file: StandardFile,
40
- context: TransformerContext,
41
- ) => Promise<AuthorisedFile> | AuthorisedFile;
42
-
43
16
  /**
44
17
  * File transformer function
45
18
  * Receives AuthorisedFile and transforms it further
46
19
  * Transformers are applied as a pipeline, with each transformer receiving
47
- * the output of the previous one
20
+ * the output of the previous one, and every transformer receiving the file's row
48
21
  */
49
22
  export type FileTransformer<TInput = AuthorisedFile, TOutput = TInput> = (
50
23
  file: TInput,
51
- context: TransformerContext,
24
+ context: RequestContext,
25
+ row: FileRow,
52
26
  ) => Promise<TOutput> | TOutput;
@@ -0,0 +1,21 @@
1
+ import type { Prisma } from '../generated/prisma/client.js';
2
+ import type { FieldDeclarations } from '../search/fields.js';
3
+ import type { SearchVisibilityWhere } from '../search/visibility.js';
4
+ import type { RequestContext } from './context.js';
5
+
6
+ /**
7
+ * Entity visibility filter - required
8
+ * Returns a Prisma condition matching the entities visible to this request
9
+ */
10
+ export type EntityVisibilityFilter = (
11
+ context: RequestContext,
12
+ ) => Promise<Prisma.EntityWhereInput> | Prisma.EntityWhereInput;
13
+
14
+ /**
15
+ * Search visibility filter - required
16
+ * Returns a condition over `id` and the search backend's declared fields matching the entities visible to this request
17
+ * Must agree with the entity visibility filter
18
+ */
19
+ export type SearchVisibilityFilter<Fields extends FieldDeclarations = FieldDeclarations> = (
20
+ context: RequestContext,
21
+ ) => Promise<SearchVisibilityWhere<Fields>> | SearchVisibilityWhere<Fields>;
@@ -0,0 +1,80 @@
1
+ import type { FastifyReply, FastifyRequest } from 'fastify';
2
+ import { decideAccess, type EntityRow } from '../transformers/default.js';
3
+ import type { AccessFunction } from '../types/access.js';
4
+ import type { IsAuthenticated, RequestContext } from '../types/context.js';
5
+ import { sendRefusal } from './errors.js';
6
+ import { isAnonymous } from './visibility.js';
7
+
8
+ /**
9
+ * All Public Access - every request may read every visible entity's Metadata and Content
10
+ *
11
+ * WARNING: Only use this for fully public repositories with no access control.
12
+ */
13
+ export const AllPublicAccess: AccessFunction = () => ({ metadata: true, content: true });
14
+
15
+ export type LicenceAccessOptions = {
16
+ hasLicence: (licenceId: string, context: RequestContext) => Promise<boolean> | boolean;
17
+ authorisationUrl?: (licenceId: string) => string;
18
+ };
19
+
20
+ /**
21
+ * Licence Access - Metadata access needs the entity's metadata licence, Content access its content licence
22
+ *
23
+ * Each licence is checked at most once per request, so a listing sharing a few licences costs a few checks.
24
+ */
25
+ export const LicenceAccess = ({ hasLicence, authorisationUrl }: LicenceAccessOptions): AccessFunction => {
26
+ const checksByRequest = new WeakMap<FastifyRequest, Map<string, Promise<boolean>>>();
27
+
28
+ const check = (licenceId: string, context: RequestContext) => {
29
+ let checks = checksByRequest.get(context.request);
30
+ if (!checks) {
31
+ checks = new Map();
32
+ checksByRequest.set(context.request, checks);
33
+ }
34
+
35
+ let held = checks.get(licenceId);
36
+ if (!held) {
37
+ held = Promise.resolve(hasLicence(licenceId, context));
38
+ checks.set(licenceId, held);
39
+ }
40
+
41
+ return held;
42
+ };
43
+
44
+ return async ({ metadataLicenseId, contentLicenseId }, context) => {
45
+ const [metadata, content] = await Promise.all([
46
+ check(metadataLicenseId, context),
47
+ check(contentLicenseId, context),
48
+ ]);
49
+
50
+ return {
51
+ metadata,
52
+ content,
53
+ ...(!metadata && authorisationUrl && { metadataAuthorizationUrl: authorisationUrl(metadataLicenseId) }),
54
+ ...(!content && authorisationUrl && { contentAuthorizationUrl: authorisationUrl(contentLicenseId) }),
55
+ };
56
+ };
57
+ };
58
+
59
+ type AccessGuardOptions = {
60
+ access: AccessFunction;
61
+ isAuthenticated?: IsAuthenticated;
62
+ level: 'metadata' | 'content';
63
+ };
64
+
65
+ /**
66
+ * Build a check that refuses a request when a visible entity's Metadata or Content isn't accessible to it
67
+ * Returns whether the request was denied (not the reply: replies are thenable, so awaiting one loses it)
68
+ */
69
+ export const createAccessGuard =
70
+ ({ access, isAuthenticated, level }: AccessGuardOptions) =>
71
+ async (reply: FastifyReply, entity: EntityRow, context: RequestContext) => {
72
+ const [entityAccess] = await decideAccess([entity], access, context);
73
+ if (entityAccess[level]) {
74
+ return false;
75
+ }
76
+
77
+ sendRefusal(reply, await isAnonymous(isAuthenticated, context), entity.id);
78
+
79
+ return true;
80
+ };
@@ -1,13 +1,19 @@
1
- const ERROR_CODES = {
1
+ import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify';
2
+ import { hasZodFastifySchemaValidationErrors } from 'fastify-type-provider-zod';
3
+
4
+ export const ERROR_CODES = {
2
5
  VALIDATION_ERROR: 'VALIDATION_ERROR',
3
6
  NOT_FOUND: 'NOT_FOUND',
7
+ UNAUTHORIZED: 'UNAUTHORIZED',
8
+ FORBIDDEN: 'FORBIDDEN',
9
+ CONFLICT: 'CONFLICT',
10
+ RANGE_NOT_SATISFIABLE: 'RANGE_NOT_SATISFIABLE',
4
11
  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
5
12
  INTERNAL_ERROR: 'INTERNAL_ERROR',
6
- INVALID_REQUEST: 'INVALID_REQUEST',
7
13
  INVALID_ENTITY_TYPE: 'INVALID_ENTITY_TYPE',
8
14
  } as const;
9
15
 
10
- type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
16
+ export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
11
17
 
12
18
  type ErrorDetails = {
13
19
  [key: string]: unknown;
@@ -21,7 +27,7 @@ export type StandardErrorResponse = {
21
27
  };
22
28
  };
23
29
 
24
- const createErrorResponse = (code: ErrorCode, message: string, details?: ErrorDetails): StandardErrorResponse => ({
30
+ export const createError = (code: ErrorCode, message: string, details?: ErrorDetails): StandardErrorResponse => ({
25
31
  error: {
26
32
  code,
27
33
  message,
@@ -31,19 +37,70 @@ const createErrorResponse = (code: ErrorCode, message: string, details?: ErrorDe
31
37
 
32
38
  type ValidationViolation = {
33
39
  field: string;
34
- message: string;
40
+ message?: string;
35
41
  value?: unknown;
36
42
  };
37
43
 
38
44
  export const createValidationError = (message: string, violations: ValidationViolation[]): StandardErrorResponse =>
39
- createErrorResponse(ERROR_CODES.VALIDATION_ERROR, message, { violations });
45
+ createError(ERROR_CODES.VALIDATION_ERROR, message, { violations });
40
46
 
41
47
  export const createNotFoundError = (message: string, entityId?: string): StandardErrorResponse =>
42
- createErrorResponse(ERROR_CODES.NOT_FOUND, message, entityId ? { entityId } : undefined);
48
+ createError(ERROR_CODES.NOT_FOUND, message, entityId ? { entityId } : undefined);
49
+
50
+ export const createAuthenticationRequiredError = (message: string, entityId: string): StandardErrorResponse =>
51
+ createError(ERROR_CODES.UNAUTHORIZED, message, { entityId });
52
+
53
+ export const createForbiddenError = (message: string, entityId: string): StandardErrorResponse =>
54
+ createError(ERROR_CODES.FORBIDDEN, message, { entityId });
55
+
56
+ export const createInternalError = (message = 'Internal server error'): StandardErrorResponse =>
57
+ createError(ERROR_CODES.INTERNAL_ERROR, message);
58
+
59
+ /**
60
+ * Refuse a request for a resource: 401 if it is anonymous, so the client can prompt a login, otherwise 403
61
+ */
62
+ export const sendRefusal = (reply: FastifyReply, anonymous: boolean, id: string) =>
63
+ anonymous
64
+ ? reply.code(401).send(createAuthenticationRequiredError('Authentication is required to access this resource', id))
65
+ : reply.code(403).send(createForbiddenError('You do not have permission to access this resource', id));
66
+
67
+ const ERROR_CODE_BY_STATUS: Record<number, ErrorCode> = {
68
+ 401: ERROR_CODES.UNAUTHORIZED,
69
+ 403: ERROR_CODES.FORBIDDEN,
70
+ 404: ERROR_CODES.NOT_FOUND,
71
+ 409: ERROR_CODES.CONFLICT,
72
+ 416: ERROR_CODES.RANGE_NOT_SATISFIABLE,
73
+ 429: ERROR_CODES.RATE_LIMIT_EXCEEDED,
74
+ };
75
+
76
+ export const errorHandler = (error: unknown, request: FastifyRequest, reply: FastifyReply) => {
77
+ if (hasZodFastifySchemaValidationErrors(error)) {
78
+ const violations = error.validation.map((v) => ({
79
+ field: v.instancePath,
80
+ message: v.message,
81
+ }));
82
+
83
+ return reply.code(400).send(createValidationError('The request parameters are invalid', violations));
84
+ }
43
85
 
44
- export const createInvalidRequestError = (message: string): StandardErrorResponse =>
45
- createErrorResponse(ERROR_CODES.INVALID_REQUEST, message);
86
+ const { statusCode, status, message, headers, expose, code } = (error ?? {}) as Partial<
87
+ FastifyError & { status: number; headers: Record<string, string>; expose: boolean }
88
+ >;
89
+ const httpStatus = statusCode ?? status;
90
+ const trusted = expose === true || (typeof code === 'string' && code.startsWith('FST_'));
91
+ if (trusted && httpStatus && httpStatus >= 400 && httpStatus < 500) {
92
+ const errorCode = ERROR_CODE_BY_STATUS[httpStatus] ?? ERROR_CODES.VALIDATION_ERROR;
46
93
 
47
- export const createInternalError = (message = 'Internal server error'): StandardErrorResponse => {
48
- return createErrorResponse(ERROR_CODES.INTERNAL_ERROR, message);
94
+ return reply
95
+ .code(httpStatus)
96
+ .headers(headers ?? {})
97
+ .send(createError(errorCode, message ?? ''));
98
+ }
99
+
100
+ request.log.error({ err: error });
101
+
102
+ return reply.code(500).send(createInternalError());
49
103
  };
104
+
105
+ export const notFoundHandler = (_request: FastifyRequest, reply: FastifyReply) =>
106
+ reply.code(404).send(createNotFoundError('The requested resource was not found'));
@@ -1,16 +1,36 @@
1
1
  import type { FastifyReply } from 'fastify';
2
2
 
3
- export const setFileHeaders = (
3
+ /** Sandboxes deposited bytes; see docs/adr/0005-library-sandboxes-delivered-bytes.md */
4
+ const contentSecurityPolicy = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
5
+
6
+ const token = "[!#$%&'*+\\-.^_`|~0-9a-z]+";
7
+ const quotedString = '"(?:[^"\\\\]|\\\\.)*"';
8
+ const mediaType = new RegExp(
9
+ `^(?:audio|video)/${token}(?:[ \\t]*;[ \\t]*${token}=(?:${token}|${quotedString}))*[ \\t]*$`,
10
+ 'i',
11
+ );
12
+
13
+ // Chrome won't play media opened directly under this CSP, and a media document can't run script.
14
+ // RFC 9110 grammar, so no comma outside quotes: browsers split the header as a list, respecting
15
+ // quotes, and take the last type, so `audio/mpeg, text/html` is HTML
16
+ const isMedia = (contentType: string) => mediaType.test(contentType);
17
+
18
+ export const setDeliveryHeaders = (
4
19
  reply: FastifyReply,
5
20
  metadata: { contentType: string; contentLength: number; etag?: string; lastModified?: Date },
6
21
  ) => {
7
22
  reply.header('Content-Type', metadata.contentType);
8
23
  reply.header('Content-Length', metadata.contentLength.toString());
9
-
10
24
  if (metadata.etag) {
11
25
  reply.header('ETag', metadata.etag);
12
26
  }
13
27
  if (metadata.lastModified) {
14
28
  reply.header('Last-Modified', metadata.lastModified.toUTCString());
15
29
  }
30
+
31
+ // Last, so a throw above can't leave them on the 500
32
+ reply.header('X-Content-Type-Options', 'nosniff');
33
+ if (!isMedia(metadata.contentType)) {
34
+ reply.header('Content-Security-Policy', contentSecurityPolicy);
35
+ }
16
36
  };
@@ -0,0 +1,11 @@
1
+ import type { FastifyInstance } from 'fastify';
2
+ import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
3
+
4
+ import { errorHandler } from './errors.js';
5
+
6
+ export const setupValidation = (fastify: FastifyInstance) => {
7
+ fastify.setValidatorCompiler(validatorCompiler);
8
+ fastify.setSerializerCompiler(serializerCompiler);
9
+
10
+ fastify.setErrorHandler(errorHandler);
11
+ };