From 0a9fa8e2912911cf3be93f2e030eb0957c469ffd Mon Sep 17 00:00:00 2001
From: John Ferlito <johnf@inodes.org>
Date: Fri, 27 Mar 2026 15:39:07 +1100
Subject: [PATCH] docs: add auth/authorisation section and rewrite range
 request docs

Clarify that HTTP range support is delegated to the file handler
implementation rather than being automatic. Add a new Authentication
and Authorisation section with examples. Fix prisma directory name.
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 54 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 7391128..bf446fa 100644
--- a/README.md
+++ b/README.md
@@ -638,12 +638,60 @@ The `/file/:id` endpoint supports these query parameters:
 
 ### HTTP Range Support
 
-The endpoint automatically handles HTTP range requests for partial content,
-useful for media streaming:
+Range request support for media streaming can be implemented in your file
+handler by parsing the `Range` header from the request context and returning
+a partial stream:
 
-- Returns **206 Partial Content** for valid range requests
-- Returns **416 Range Not Satisfiable** for invalid ranges
-- Sets appropriate `Content-Range` and `Accept-Ranges` headers
+```typescript
+fileHandler: {
+  get: async (file, { request }) => {
+    const range = request.headers.range;
+    // Parse range header and return partial content stream
+    // Your storage backend (S3, filesystem, etc.) likely supports range reads natively
+  },
+}
+```
+
+### Authentication and Authorisation
+
+The library delegates authentication and authorisation to your transformers.
+The access transformer receives the full Fastify request context, so you can
+verify credentials and set access flags accordingly:
+
+```typescript
+accessTransformer: async (entity, { request }) => {
+  const token = request.headers.authorization;
+  const user = await verifyToken(token);
+
+  if (!user) {
+    // Unauthenticated — metadata visible but content restricted
+    return {
+      ...entity,
+      access: {
+        metadata: true,
+        content: false,
+        contentAuthorizationUrl: 'https://auth.example.com/login',
+      },
+    };
+  }
+
+  const canAccess = await checkUserLicense(user, entity.contentLicenseId);
+
+  return {
+    ...entity,
+    access: {
+      metadata: true,
+      content: canAccess,
+      contentAuthorizationUrl: canAccess
+        ? undefined
+        : 'https://rems.example.com/request-access',
+    },
+  };
+}
+```
+
+The same pattern applies to `fileAccessTransformer` for controlling file
+content downloads.
 
 ### Entity Meta Field
 
@@ -739,7 +787,7 @@ your-project/
 ├── prisma/
 │   ├── schema.prisma         # Prisma schema
 │   ├── models/              # Your custom models
-│   └── upstream/            # Symlink to arocapi models
+│   └── arocapi/             # Symlink to arocapi models
 ├── prisma.config.ts         # Prisma configuration
 ├── .env                     # Environment variables
 └── package.json