Merge branch 'main' into 20-real-client-ip-based-on-header-trusted-proxies

Author: zefir-git

src/Request.ts

@@ -4,8 +4,10 @@ import http, {OutgoingHttpHeader} from "node:http";
 import stream from "node:stream";
 import {Authenticator} from "./auth/Authenticator.js";
 import {Authorisation} from "./auth/Authorisation.js";
-import {AuthenticatedRequest} from "./auth/AuthenticatedRequest.js";
+import {Permission} from "./auth/index.js";
+import {ThrowableResponse} from "./response/index.js";
 import {Server} from "./Server.js";
+import {ServerErrorRegistry} from "./ServerErrorRegistry.js";
 
 /**
  * An incoming HTTP request from a connected client.
@@ -282,26 +284,6 @@ export class Request<A> {
         return await authenticator.authenticate(this);
     }
 
-    /**
-     * Attempt to authenticate this request with one of the {@link Server}’s {@link Authenticator}s.
-     * @returns `null` if the request lacks authorisation information.
-     */
-    public async authenticate(): Promise<AuthenticatedRequest<A> | null> {
-        const authorisation = await this.getAuthorisation();
-        if (authorisation === null) return null;
-        return new AuthenticatedRequest<A>(
-            authorisation,
-            this.method,
-            this.originalUrl,
-            this.url,
-            this.headers,
-            this.bodyStream,
-            this.originalIp,
-            this.ip,
-            this.server,
-        );
-    }
-
     /**
      * Returns a boolean value that declares whether the body has been read yet.
      */
@@ -375,6 +357,33 @@ export class Request<A> {
         return (await this.blob()).text();
     }
 
+    /**
+     * Require that authorisation can be obtained from this request.
+     * @throws {@link ThrowableResponse} of {@link ServerErrorRegistry.ErrorCodes.UNAUTHORISED} if authorisation cannot
+     * be obtained.
+     */
+    public async auth(): Promise<Authorisation<A>>;
+
+    /**
+     * Require that authorisation can be obtained from this request and that the given (requested) permission(s) are
+     * ALL within the scope of the authorisation.
+     * @param permissions The requested permissions.
+     * @throws {@link ThrowableResponse} of {@link ServerErrorRegistry.ErrorCodes.UNAUTHORISED} if authorisation cannot
+     * be obtained.
+     * @throws {@link ThrowableResponse} of {@link ServerErrorRegistry.ErrorCodes.NO_PERMISSION} if the authorisation
+     * lacks any of the requested permissions.
+     */
+    public async auth(...permissions: [Permission, ...Permission[]]): Promise<Authorisation<A>>;
+
+    public async auth(...permissions: Permission[]): Promise<Authorisation<A>> {
+        const authorisation = await this.getAuthorisation();
+        if (authorisation === null)
+            throw new ThrowableResponse(this.server.errors._get(ServerErrorRegistry.ErrorCodes.UNAUTHORISED, null));
+        if (permissions.length > 0 && !authorisation.hasAll(permissions))
+            throw new ThrowableResponse(this.server.errors._get(ServerErrorRegistry.ErrorCodes.NO_PERMISSION, null));
+        return authorisation;
+    }
+
     /**
      * Response headers that the Response to this request should include.
      * @internal

src/ServerErrorRegistry.ts

@@ -27,6 +27,9 @@ class ServerErrorRegistry<A> {
 
             [ServerErrorRegistry.ErrorCodes.NO_PERMISSION]:
                 new TextResponse("You do not have permission to perform this action.", 403),
+
+            [ServerErrorRegistry.ErrorCodes.UNAUTHORISED]:
+                new TextResponse("Authentication information was either absent or invalid.", 401),
         };
     }
 
@@ -57,6 +60,7 @@ namespace ServerErrorRegistry {
         INTERNAL,
         PRECONDITION_FAILED,
         NO_PERMISSION,
+        UNAUTHORISED,
     }
 }
 

src/auth/AuthenticatedRequest.ts

@@ -13,7 +13,7 @@ export interface Authenticator<A extends any> {
     canAuthenticate(request: Request<A>): boolean;
 
     /**
-     * Authenticate the given request. If authenticate fails, e.g. due to missing or invalid information, such as
+     * Authenticate the given request. If authentication fails, e.g. due to missing or invalid information, such as
      * credentials, the authenticator should return `null`, which can be communicated to the client by implementing
      * applications using a 401 status response.
      * @param request

src/auth/Authenticator.ts

@@ -28,6 +28,17 @@ export class PermissionGroup implements Permissible, Iterable<Permission> {
         return false;
     }
 
+    /**
+     * Check that the group has all the specified permissions.
+     * @param permissions The permissions to check.
+     */
+    public hasAll(permissions: Iterable<Permission>): boolean {
+        for (const permission of permissions)
+            if (!this.has(permission))
+                return false;
+        return true;
+    }
+
     /**
      * An iterator over the permissions in this group.
      */

src/auth/PermissionGroup.ts

@@ -1,5 +1,4 @@
 /* Auto-generated by generateIndices.sh */
-export * from "./AuthenticatedRequest.js";
 export * from "./Authenticator.js";
 export * from "./Authorisation.js";
 export * from "./Permissible.js";