arocapi 5.0.0-beta.2 → 5.0.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 (117) hide show
  1. package/README.md +37 -824
  2. package/dist/app.d.ts +20 -7
  3. package/dist/app.js +42 -28
  4. package/dist/app.js.map +1 -1
  5. package/dist/app.test.js +41 -56
  6. package/dist/app.test.js.map +1 -1
  7. package/dist/errorHandling.test.d.ts +1 -0
  8. package/dist/errorHandling.test.js +222 -0
  9. package/dist/errorHandling.test.js.map +1 -0
  10. package/dist/index.dev.js +4 -3
  11. package/dist/index.dev.js.map +1 -1
  12. package/dist/routes/capabilities.test.js +8 -8
  13. package/dist/routes/capabilities.test.js.map +1 -1
  14. package/dist/routes/crate.test.js +67 -19
  15. package/dist/routes/crate.test.js.map +1 -1
  16. package/dist/routes/entities.d.ts +5 -2
  17. package/dist/routes/entities.js +31 -49
  18. package/dist/routes/entities.js.map +1 -1
  19. package/dist/routes/entities.test.js +16 -12
  20. package/dist/routes/entities.test.js.map +1 -1
  21. package/dist/routes/entity.d.ts +7 -2
  22. package/dist/routes/entity.js +14 -29
  23. package/dist/routes/entity.js.map +1 -1
  24. package/dist/routes/entity.test.js +19 -13
  25. package/dist/routes/entity.test.js.map +1 -1
  26. package/dist/routes/file.d.ts +6 -0
  27. package/dist/routes/file.js +67 -59
  28. package/dist/routes/file.js.map +1 -1
  29. package/dist/routes/file.test.js +135 -25
  30. package/dist/routes/file.test.js.map +1 -1
  31. package/dist/routes/files.d.ts +5 -2
  32. package/dist/routes/files.js +24 -39
  33. package/dist/routes/files.js.map +1 -1
  34. package/dist/routes/files.test.js +44 -21
  35. package/dist/routes/files.test.js.map +1 -1
  36. package/dist/routes/metadata.d.ts +6 -0
  37. package/dist/routes/metadata.js +49 -54
  38. package/dist/routes/metadata.js.map +1 -1
  39. package/dist/routes/search.d.ts +6 -2
  40. package/dist/routes/search.js +95 -99
  41. package/dist/routes/search.js.map +1 -1
  42. package/dist/routes/search.test.js +85 -39
  43. package/dist/routes/search.test.js.map +1 -1
  44. package/dist/test/helpers/fastify.js +2 -3
  45. package/dist/test/helpers/fastify.js.map +1 -1
  46. package/dist/test/integration.setup.d.ts +18 -0
  47. package/dist/test/integration.setup.js +15 -7
  48. package/dist/test/integration.setup.js.map +1 -1
  49. package/dist/test/integration.test.js +368 -2
  50. package/dist/test/integration.test.js.map +1 -1
  51. package/dist/transformers/default.d.ts +10 -18
  52. package/dist/transformers/default.js +41 -15
  53. package/dist/transformers/default.js.map +1 -1
  54. package/dist/transformers/default.test.js +109 -47
  55. package/dist/transformers/default.test.js.map +1 -1
  56. package/dist/transformers/transformer.test.js +12 -34
  57. package/dist/transformers/transformer.test.js.map +1 -1
  58. package/dist/types/access.d.ts +9 -0
  59. package/dist/types/access.js +2 -0
  60. package/dist/types/access.js.map +1 -0
  61. package/dist/types/context.d.ts +6 -0
  62. package/dist/types/context.js +2 -0
  63. package/dist/types/context.js.map +1 -0
  64. package/dist/types/fileHandlers.d.ts +5 -9
  65. package/dist/types/transformers.d.ts +4 -10
  66. package/dist/types/visibility.d.ts +5 -0
  67. package/dist/types/visibility.js +2 -0
  68. package/dist/types/visibility.js.map +1 -0
  69. package/dist/utils/access.d.ts +17 -0
  70. package/dist/utils/access.js +41 -0
  71. package/dist/utils/access.js.map +1 -0
  72. package/dist/utils/errors.d.ts +13 -4
  73. package/dist/utils/errors.js +44 -8
  74. package/dist/utils/errors.js.map +1 -1
  75. package/dist/utils/errors.test.js +14 -1
  76. package/dist/utils/errors.test.js.map +1 -1
  77. package/dist/utils/validation.d.ts +2 -0
  78. package/dist/utils/validation.js +8 -0
  79. package/dist/utils/validation.js.map +1 -0
  80. package/dist/utils/visibility.d.ts +18 -0
  81. package/dist/utils/visibility.js +16 -0
  82. package/dist/utils/visibility.js.map +1 -0
  83. package/package.json +6 -4
  84. package/src/app.test.ts +45 -66
  85. package/src/app.ts +85 -54
  86. package/src/errorHandling.test.ts +288 -0
  87. package/src/index.dev.ts +6 -4
  88. package/src/routes/__snapshots__/search.test.ts.snap +2 -2
  89. package/src/routes/capabilities.test.ts +8 -8
  90. package/src/routes/crate.test.ts +80 -19
  91. package/src/routes/entities.test.ts +16 -12
  92. package/src/routes/entities.ts +40 -59
  93. package/src/routes/entity.test.ts +19 -13
  94. package/src/routes/entity.ts +22 -35
  95. package/src/routes/file.test.ts +156 -25
  96. package/src/routes/file.ts +84 -62
  97. package/src/routes/files.test.ts +52 -26
  98. package/src/routes/files.ts +31 -47
  99. package/src/routes/metadata.ts +64 -58
  100. package/src/routes/search.test.ts +88 -39
  101. package/src/routes/search.ts +123 -119
  102. package/src/test/helpers/fastify.ts +2 -3
  103. package/src/test/integration.setup.ts +18 -7
  104. package/src/test/integration.test.ts +472 -1
  105. package/src/transformers/default.test.ts +139 -47
  106. package/src/transformers/default.ts +103 -83
  107. package/src/transformers/transformer.test.ts +18 -44
  108. package/src/types/access.ts +20 -0
  109. package/src/types/context.ts +15 -0
  110. package/src/types/fileHandlers.ts +5 -13
  111. package/src/types/transformers.ts +4 -32
  112. package/src/types/visibility.ts +18 -0
  113. package/src/utils/access.ts +80 -0
  114. package/src/utils/errors.test.ts +16 -1
  115. package/src/utils/errors.ts +67 -10
  116. package/src/utils/validation.ts +11 -0
  117. package/src/utils/visibility.ts +56 -0
@@ -1,6 +1,17 @@
1
- import { describe, expect, it } from 'vitest';
1
+ import type { FastifyInstance, FastifyRequest } from 'fastify';
2
+ import { beforeEach, describe, expect, it, vi } from 'vitest';
3
+ import { mockReset } from 'vitest-mock-extended';
2
4
  import type { Entity } from '../generated/prisma/client.js';
3
- import { AllPublicAccessTransformer, baseEntityTransformer } from './default.js';
5
+ import { prisma } from '../test/helpers/fastify.js';
6
+ import type { AccessFunction } from '../types/access.js';
7
+ import type { RequestContext } from '../types/context.js';
8
+ import { AllPublicAccess } from '../utils/access.js';
9
+ import { applyTransformers, authoriseEntities, authoriseFiles, baseEntityTransformer } from './default.js';
10
+
11
+ const context: RequestContext = {
12
+ request: {} as FastifyRequest,
13
+ fastify: {} as FastifyInstance,
14
+ };
4
15
 
5
16
  describe('baseEntityTransformer', () => {
6
17
  it('should transform entity to standard entity shape', () => {
@@ -117,68 +128,149 @@ describe('baseEntityTransformer', () => {
117
128
  });
118
129
  });
119
130
 
120
- describe('AllPublicAccessTransformer', () => {
121
- it('should grant full access to metadata and content', () => {
122
- const standardEntity = {
131
+ describe('AllPublicAccess', () => {
132
+ it('should grant access to metadata and content without authorisation URLs', () => {
133
+ const baseEntity = {
123
134
  id: 'http://example.com/entity/123',
124
135
  name: 'Test Entity',
125
136
  description: 'A test entity',
126
137
  entityType: 'http://schema.org/MediaObject',
127
- memberOf: { id: 'http://example.com/parent', name: 'Parent Entity' },
128
- rootCollection: { id: 'http://example.com/root', name: 'Root Collection' },
138
+ memberOf: 'http://example.com/parent',
139
+ rootCollection: 'http://example.com/root',
129
140
  metadataLicenseId: 'https://creativecommons.org/licenses/by/4.0/',
130
141
  contentLicenseId: 'https://creativecommons.org/licenses/by/4.0/',
131
142
  };
132
143
 
133
- const result = AllPublicAccessTransformer(standardEntity);
144
+ expect(AllPublicAccess(baseEntity, context)).toEqual({ metadata: true, content: true });
145
+ });
146
+ });
147
+
148
+ const dbEntity = (id: string, overrides: Partial<Entity> = {}): Entity => ({
149
+ id,
150
+ name: `Name of ${id}`,
151
+ description: '',
152
+ entityType: 'http://schema.org/MediaObject',
153
+ memberOf: null,
154
+ rootCollection: null,
155
+ metadataLicenseId: 'https://example.com/licence/metadata',
156
+ contentLicenseId: 'https://example.com/licence/content',
157
+ createdAt: new Date(),
158
+ updatedAt: new Date(),
159
+ meta: null,
160
+ ...overrides,
161
+ });
134
162
 
135
- expect(result).toEqual({
136
- ...standardEntity,
137
- access: {
138
- metadata: true,
139
- content: true,
140
- },
163
+ describe('authoriseEntities', () => {
164
+ beforeEach(() => {
165
+ mockReset(prisma);
166
+ });
167
+
168
+ it('should pass the access function parent ids but return the Record with parent names', async () => {
169
+ prisma.entity.findMany.mockResolvedValue([dbEntity('http://example.com/collection')]);
170
+ const access = vi.fn<AccessFunction>(AllPublicAccess);
171
+
172
+ const [entity] = await authoriseEntities(
173
+ [dbEntity('http://example.com/item', { memberOf: 'http://example.com/collection' })],
174
+ prisma,
175
+ access,
176
+ context,
177
+ );
178
+
179
+ expect(access).toHaveBeenCalledWith(
180
+ expect.objectContaining({ memberOf: 'http://example.com/collection' }),
181
+ context,
182
+ );
183
+ expect(entity.memberOf).toEqual({
184
+ id: 'http://example.com/collection',
185
+ name: 'Name of http://example.com/collection',
141
186
  });
187
+ expect(entity.access).toEqual({ metadata: true, content: true });
142
188
  });
143
189
 
144
- it('should preserve all standard entity fields', () => {
145
- const standardEntity = {
146
- id: 'http://example.com/entity/789',
147
- name: 'Another Entity',
148
- description: 'Another description',
149
- entityType: 'http://schema.org/Person',
150
- memberOf: null,
151
- rootCollection: null,
152
- metadataLicenseId: 'https://creativecommons.org/publicdomain/zero/1.0/',
153
- contentLicenseId: 'https://creativecommons.org/publicdomain/zero/1.0/',
154
- };
190
+ it('should keep only the access keys the library defines', async () => {
191
+ const access = vi.fn(async () => ({
192
+ metadata: false,
193
+ content: false,
194
+ metadataAuthorizationUrl: 'https://example.com/request-metadata',
195
+ contentAuthorizationUrl: 'https://example.com/request-content',
196
+ licence: 'secret',
197
+ }));
198
+
199
+ const [entity] = await authoriseEntities([dbEntity('http://example.com/item')], prisma, access, context);
200
+
201
+ expect(entity.access).toEqual({
202
+ metadata: false,
203
+ content: false,
204
+ metadataAuthorizationUrl: 'https://example.com/request-metadata',
205
+ contentAuthorizationUrl: 'https://example.com/request-content',
206
+ });
207
+ });
208
+ });
155
209
 
156
- const result = AllPublicAccessTransformer(standardEntity);
210
+ describe('authoriseFiles', () => {
211
+ beforeEach(() => {
212
+ mockReset(prisma);
213
+ });
157
214
 
158
- expect(result.id).toBe(standardEntity.id);
159
- expect(result.name).toBe(standardEntity.name);
160
- expect(result.description).toBe(standardEntity.description);
161
- expect(result.entityType).toBe(standardEntity.entityType);
162
- expect(result.memberOf).toBe(standardEntity.memberOf);
163
- expect(result.rootCollection).toBe(standardEntity.rootCollection);
164
- expect(result.metadataLicenseId).toBe(standardEntity.metadataLicenseId);
165
- expect(result.contentLicenseId).toBe(standardEntity.contentLicenseId);
215
+ const dbFile = (id: string) => ({
216
+ id,
217
+ filename: 'audio.wav',
218
+ mediaType: 'audio/wav',
219
+ size: BigInt(2048),
220
+ meta: null,
221
+ createdAt: new Date(),
222
+ updatedAt: new Date(),
223
+ entity: dbEntity(id),
166
224
  });
167
225
 
168
- it('should not add contentAuthorizationUrl for public access', () => {
169
- const standardEntity = {
170
- id: 'http://example.com/entity/public',
171
- name: 'Public Entity',
172
- description: 'Fully public',
173
- entityType: 'http://pcdm.org/models#Collection',
174
- memberOf: null,
175
- rootCollection: null,
176
- metadataLicenseId: 'https://creativecommons.org/licenses/by/4.0/',
177
- contentLicenseId: 'https://creativecommons.org/licenses/by/4.0/',
178
- };
226
+ it("should attach only the Content access of each file's entity", async () => {
227
+ const access: AccessFunction = (entity) =>
228
+ entity.id === 'http://example.com/restricted.wav'
229
+ ? {
230
+ metadata: false,
231
+ content: false,
232
+ metadataAuthorizationUrl: 'https://example.com/request-metadata',
233
+ contentAuthorizationUrl: 'https://example.com/request-content',
234
+ }
235
+ : { metadata: false, content: true };
179
236
 
180
- const result = AllPublicAccessTransformer(standardEntity);
237
+ const files = await authoriseFiles(
238
+ [dbFile('http://example.com/restricted.wav'), dbFile('http://example.com/open.wav')],
239
+ access,
240
+ context,
241
+ );
242
+
243
+ expect(files).toEqual([
244
+ {
245
+ id: 'http://example.com/restricted.wav',
246
+ filename: 'audio.wav',
247
+ mediaType: 'audio/wav',
248
+ size: 2048,
249
+ access: { content: false, contentAuthorizationUrl: 'https://example.com/request-content' },
250
+ },
251
+ {
252
+ id: 'http://example.com/open.wav',
253
+ filename: 'audio.wav',
254
+ mediaType: 'audio/wav',
255
+ size: 2048,
256
+ access: { content: true },
257
+ },
258
+ ]);
259
+ });
260
+ });
261
+
262
+ describe('applyTransformers', () => {
263
+ it('should chain transformers in order', async () => {
264
+ const result = await applyTransformers(
265
+ 'a',
266
+ [(item) => `${item}b`, async (item, { request }) => `${item}c${request.url}`],
267
+ { ...context, request: { url: '/d' } as FastifyRequest },
268
+ );
269
+
270
+ expect(result).toBe('abc/d');
271
+ });
181
272
 
182
- expect(result.access.contentAuthorizationUrl).toBeUndefined();
273
+ it('should return the item unchanged without transformers', async () => {
274
+ expect(await applyTransformers('a', [], context)).toBe('a');
183
275
  });
184
276
  });
@@ -1,6 +1,8 @@
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
+ export type EntityWithFile = Omit<Entity, 'meta'> & { file?: { id: string } | null };
4
6
 
5
7
  /**
6
8
  * Entity reference - used for memberOf and rootCollection
@@ -11,8 +13,8 @@ type EntityReference = {
11
13
  };
12
14
 
13
15
  /**
14
- * Base entity shape - output of base transformation with unresolved references
15
- * Used internally before reference resolution
16
+ * Base entity shape - an entity's Record fields with memberOf and rootCollection as ids
17
+ * The access function receives this shape, so deciding access never looks up parent entities
16
18
  */
17
19
  export type BaseEntity = {
18
20
  id: string;
@@ -41,31 +43,13 @@ export type StandardEntity = {
41
43
  };
42
44
 
43
45
  /**
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
46
+ * Authorised entity - a standard entity with the access function's result attached
56
47
  */
57
48
  export type AuthorisedEntity = StandardEntity & {
58
49
  access: AccessInfo;
59
50
  };
60
51
 
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
- };
52
+ type FileAccessInfo = Pick<AccessInfo, 'content' | 'contentAuthorizationUrl'>;
69
53
 
70
54
  /**
71
55
  * Standard file shape - output of base file transformation
@@ -79,9 +63,7 @@ export type StandardFile = {
79
63
  };
80
64
 
81
65
  /**
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
66
+ * Authorised file - a standard file with its file entity's Content access attached
85
67
  */
86
68
  export type AuthorisedFile = StandardFile & {
87
69
  access: FileAccessInfo;
@@ -107,72 +89,17 @@ export const baseEntityTransformer = (entity: EntityWithFile): BaseEntity => {
107
89
  return base;
108
90
  };
109
91
 
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
92
  /**
137
93
  * Base file transformer - always applied first
138
94
  * Transforms raw database file to standard file shape (without access)
139
95
  */
140
- export const baseFileTransformer = (file: File): StandardFile => ({
96
+ const baseFileTransformer = (file: File): StandardFile => ({
141
97
  id: file.id,
142
98
  filename: file.filename,
143
99
  mediaType: file.mediaType,
144
100
  size: Number(file.size),
145
101
  });
146
102
 
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
103
  /**
177
104
  * Resolve entity references (memberOf/rootCollection) to objects with id and name
178
105
  * Batch-fetches all referenced entities in a single query for performance
@@ -181,7 +108,7 @@ export const AllPublicFileAccessTransformer = (file: StandardFile): AuthorisedFi
181
108
  * @param prisma - Prisma client instance
182
109
  * @returns Map of entity ID to EntityReference object
183
110
  */
184
- export const resolveEntityReferences = async (
111
+ const resolveEntityReferences = async (
185
112
  entities: Array<{ memberOf: string | null; rootCollection: string | null }>,
186
113
  prisma: PrismaClient,
187
114
  ): Promise<Map<string, EntityReference>> => {
@@ -208,3 +135,96 @@ export const resolveEntityReferences = async (
208
135
 
209
136
  return new Map(refs.map((r) => [r.id, { id: r.id, name: r.name }]));
210
137
  };
138
+
139
+ /**
140
+ * Transform database entities to standard entities, resolving their references in one query
141
+ */
142
+ const toStandardEntities = async (entities: EntityWithFile[], prisma: PrismaClient): Promise<StandardEntity[]> => {
143
+ const refMap = await resolveEntityReferences(entities, prisma);
144
+
145
+ return entities.map((entity) => {
146
+ const base = baseEntityTransformer(entity);
147
+
148
+ return {
149
+ ...base,
150
+ memberOf: base.memberOf ? (refMap.get(base.memberOf) ?? null) : null,
151
+ rootCollection: base.rootCollection ? (refMap.get(base.rootCollection) ?? null) : null,
152
+ };
153
+ });
154
+ };
155
+
156
+ const pickAccess = ({
157
+ metadata,
158
+ content,
159
+ metadataAuthorizationUrl,
160
+ contentAuthorizationUrl,
161
+ }: AccessInfo): AccessInfo => ({
162
+ metadata,
163
+ content,
164
+ ...(metadataAuthorizationUrl && { metadataAuthorizationUrl }),
165
+ ...(contentAuthorizationUrl && { contentAuthorizationUrl }),
166
+ });
167
+
168
+ /**
169
+ * Decide access to database entities with the access function
170
+ */
171
+ export const decideAccess = async (
172
+ entities: EntityWithFile[],
173
+ access: AccessFunction,
174
+ context: RequestContext,
175
+ ): Promise<AccessInfo[]> =>
176
+ Promise.all(entities.map(async (entity) => pickAccess(await access(baseEntityTransformer(entity), context))));
177
+
178
+ /**
179
+ * Transform database entities to standard entities with the access function's result attached
180
+ */
181
+ export const authoriseEntities = async (
182
+ entities: EntityWithFile[],
183
+ prisma: PrismaClient,
184
+ access: AccessFunction,
185
+ context: RequestContext,
186
+ ): Promise<AuthorisedEntity[]> => {
187
+ const [standardEntities, entityAccess] = await Promise.all([
188
+ toStandardEntities(entities, prisma),
189
+ decideAccess(entities, access, context),
190
+ ]);
191
+
192
+ return standardEntities.map((entity, i) => ({ ...entity, access: entityAccess[i] }));
193
+ };
194
+
195
+ /**
196
+ * Transform database files to standard files with their file entity's Content access attached
197
+ */
198
+ export const authoriseFiles = async (
199
+ files: Array<File & { entity: EntityWithFile }>,
200
+ access: AccessFunction,
201
+ context: RequestContext,
202
+ ): Promise<AuthorisedFile[]> => {
203
+ const fileEntityAccess = await decideAccess(
204
+ files.map((file) => file.entity),
205
+ access,
206
+ context,
207
+ );
208
+
209
+ return files.map((file, i) => {
210
+ const { metadata: _metadata, metadataAuthorizationUrl: _metadataUrl, ...fileAccess } = fileEntityAccess[i];
211
+
212
+ return { ...baseFileTransformer(file), access: fileAccess };
213
+ });
214
+ };
215
+
216
+ /**
217
+ * Apply consumer transformers in order, each receiving the previous one's output
218
+ */
219
+ export const applyTransformers = async <T>(
220
+ item: T,
221
+ transformers: Array<(item: T, context: RequestContext) => Promise<T> | T>,
222
+ context: RequestContext,
223
+ ): Promise<T> => {
224
+ let result = item;
225
+ for (const transformer of transformers) {
226
+ result = await transformer(result, context);
227
+ }
228
+
229
+ return result;
230
+ };
@@ -1,16 +1,20 @@
1
1
  import type { FastifyInstance, FastifyRequest } from 'fastify';
2
2
  import { describe, expect, it } from 'vitest';
3
- import type { AccessTransformer, EntityTransformer, TransformerContext } from '../types/transformers.js';
3
+ import { prisma } from '../test/helpers/fastify.js';
4
+ import type { AccessFunction } from '../types/access.js';
5
+ import type { RequestContext } from '../types/context.js';
6
+ import type { EntityTransformer } from '../types/transformers.js';
4
7
  import {
5
- AllPublicAccessTransformer,
6
8
  type AuthorisedEntity,
9
+ applyTransformers,
10
+ authoriseEntities,
7
11
  type BaseEntity,
8
12
  baseEntityTransformer,
9
13
  type StandardEntity,
10
14
  } from './default.js';
11
15
 
12
16
  describe('Entity Transformers', () => {
13
- const mockContext: TransformerContext = {
17
+ const mockContext: RequestContext = {
14
18
  request: {} as FastifyRequest,
15
19
  fastify: {} as FastifyInstance,
16
20
  };
@@ -69,28 +73,6 @@ describe('Entity Transformers', () => {
69
73
  });
70
74
  });
71
75
 
72
- describe('AllPublicAccessTransformer', () => {
73
- it('should add full access to standard entity', () => {
74
- const result = AllPublicAccessTransformer(mockStandardEntity);
75
-
76
- expect(result).toEqual({
77
- ...mockStandardEntity,
78
- access: {
79
- metadata: true,
80
- content: true,
81
- },
82
- });
83
- });
84
-
85
- it('should grant metadata and content access', () => {
86
- const result = AllPublicAccessTransformer(mockStandardEntity);
87
-
88
- expect(result.access.metadata).toBe(true);
89
- expect(result.access.content).toBe(true);
90
- expect(result.access.contentAuthorizationUrl).toBeUndefined();
91
- });
92
- });
93
-
94
76
  describe('Custom transformers', () => {
95
77
  it('should allow custom transformer to add computed fields', () => {
96
78
  const customTransformer: EntityTransformer<AuthorisedEntity, { id: string; displayName: string; uri: string }> = (
@@ -148,7 +130,7 @@ describe('Entity Transformers', () => {
148
130
  requestUrl: context.request.url || 'unknown',
149
131
  });
150
132
 
151
- const contextWithUrl: TransformerContext = {
133
+ const contextWithUrl: RequestContext = {
152
134
  request: { url: '/test-url' } as FastifyRequest,
153
135
  fastify: {} as FastifyInstance,
154
136
  };
@@ -208,13 +190,10 @@ describe('Entity Transformers', () => {
208
190
  updatedAt: new Date(),
209
191
  };
210
192
 
211
- const customAccessTransformer: AccessTransformer = (entity) => ({
212
- ...entity,
213
- access: {
214
- metadata: true,
215
- content: false,
216
- contentAuthorizationUrl: 'https://example.com/auth',
217
- },
193
+ const access: AccessFunction = () => ({
194
+ metadata: true,
195
+ content: false,
196
+ contentAuthorizationUrl: 'https://example.com/auth',
218
197
  });
219
198
 
220
199
  const addMetadata: EntityTransformer<AuthorisedEntity, AuthorisedEntity & { processed: boolean }> = (entity) => ({
@@ -222,18 +201,13 @@ describe('Entity Transformers', () => {
222
201
  processed: true,
223
202
  });
224
203
 
225
- // Full pipeline: base -> resolve references -> access -> custom
226
- const base = baseEntityTransformer(rawEntity);
227
-
228
- // Simulate reference resolution (in real code, this uses resolveEntityReferences)
229
- const standard: StandardEntity = {
230
- ...base,
231
- memberOf: base.memberOf ? { id: base.memberOf, name: 'Parent Collection' } : null,
232
- rootCollection: base.rootCollection ? { id: base.rootCollection, name: 'Root Collection' } : null,
233
- };
204
+ prisma.entity.findMany.mockResolvedValue([
205
+ { ...rawEntity, id: 'http://example.com/collection', name: 'Parent Collection' },
206
+ { ...rawEntity, id: 'http://example.com/root', name: 'Root Collection' },
207
+ ]);
234
208
 
235
- const authorised = await customAccessTransformer(standard, mockContext);
236
- const final = await addMetadata(authorised, mockContext);
209
+ const [authorised] = await authoriseEntities([rawEntity], prisma, access, mockContext);
210
+ const final = await applyTransformers(authorised, [addMetadata], mockContext);
237
211
 
238
212
  expect(final).toMatchObject({
239
213
  id: 'http://example.com/entity/123',
@@ -0,0 +1,20 @@
1
+ import type { BaseEntity } 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. A file's access is its file entity's access.
18
+ * The library attaches the result to responses and enforces it on the Metadata and Content routes.
19
+ */
20
+ export type AccessFunction = (entity: BaseEntity, context: RequestContext) => 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,11 +1,6 @@
1
1
  import type { Readable } from 'node:stream';
2
- import type { FastifyInstance, FastifyRequest } from 'fastify';
3
2
  import type { Entity, File } from '../generated/prisma/client.js';
4
-
5
- export type FileHandlerContext = {
6
- request: FastifyRequest;
7
- fastify: FastifyInstance;
8
- };
3
+ import type { RequestContext } from './context.js';
9
4
 
10
5
  export type FileMetadata = {
11
6
  contentType: string;
@@ -34,14 +29,11 @@ export type FilePathResult = {
34
29
 
35
30
  export type FileResult = FileRedirectResult | FileStreamResult | FilePathResult;
36
31
 
37
- export type GetFileHandler = (
38
- file: File,
39
- context: FileHandlerContext,
40
- ) => Promise<FileResult | false> | FileResult | false;
32
+ export type GetFileHandler = (file: File, context: RequestContext) => Promise<FileResult | false> | FileResult | false;
41
33
 
42
34
  export type HeadFileHandler = (
43
35
  file: File,
44
- context: FileHandlerContext,
36
+ context: RequestContext,
45
37
  ) => Promise<FileMetadata | false> | FileMetadata | false;
46
38
 
47
39
  export type FileHandler = {
@@ -51,12 +43,12 @@ export type FileHandler = {
51
43
 
52
44
  export type GetRoCrateHandler = (
53
45
  entity: Entity,
54
- context: FileHandlerContext,
46
+ context: RequestContext,
55
47
  ) => Promise<FileResult | false> | FileResult | false;
56
48
 
57
49
  export type HeadRoCrateHandler = (
58
50
  entity: Entity,
59
- context: FileHandlerContext,
51
+ context: RequestContext,
60
52
  ) => Promise<FileMetadata | false> | FileMetadata | false;
61
53
 
62
54
  export type RoCrateHandler = {