Merge branch 'auth' into dev/zefir

Author: zefir-git

src/AuthenticatedRequest.ts

@@ -0,0 +1,35 @@
+import {Authorisation} from "./auth/Authorisation.js";
+import {Permissible} from "./auth/Permissible.js";
+import {Permission} from "./auth/Permission.js";
+import {Request} from "./Request.js";
+
+/**
+ * A request with available {@link Authorisation}.
+ */
+export class AuthenticatedRequest<A> extends Request<A> implements Permissible {
+    /**
+     * This request’s authorisation.
+     */
+    public readonly authorisation: Authorisation<A>;
+
+    /**
+     * Create a new authenticated request.
+     * @param authorisation
+     * @param args The arguments to pass to the {@link Request} constructor.
+     */
+    public constructor(
+        authorisation: Authorisation<A>,
+        ...args: ConstructorParameters<typeof Request<A>>
+    ) {
+        super(...args);
+        this.authorisation = authorisation;
+    }
+
+    /**
+     * Check if the request has the specified permission.
+     * @param permission
+     */
+    public has(permission: Permission): boolean {
+        return this.authorisation.has(permission);
+    }
+}

src/Request.ts

@@ -2,11 +2,15 @@ import {IPAddress, IPv4, IPv6} from "@cldn/ip";
 import {Multipart} from "multipart-ts";
 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 "./AuthenticatedRequest.js";
+import {Server} from "./Server.js";
 
 /**
  * An incoming HTTP request from a connected client.
  */
-export class Request {
+export class Request<A> {
     /**
      * The request method.
      */
@@ -32,34 +36,42 @@ export class Request {
      */
     public readonly ip: IPv4 | IPv6;
 
+    /**
+     * The {@link Server} from which this request was received.
+     */
+    public readonly server: Server<A>;
+
     /**
      * Construct a new Request.
      * @param method See {@link Request#method}.
      * @param url See {@link Request#url}.
      * @param headers See {@link Request#headers}.
      * @param bodyStream See {@link Request#bodyStream}.
      * @param ip See {@link Request#ip}.
+     * @param server See {@link Request#server}.
      */
-    protected constructor(
-        method: Request["method"],
-        url: Request["url"],
-        headers: Request["headers"],
-        bodyStream: Request["bodyStream"],
-        ip: Request["ip"],
+    public constructor(
+        method: Request<A>["method"],
+        url: Request<A>["url"],
+        headers: Request<A>["headers"],
+        bodyStream: Request<A>["bodyStream"],
+        ip: Request<A>["ip"],
+        server: Request<A>["server"]
     ) {
         this.method = method;
         this.url = url;
         this.headers = headers;
         this.bodyStream = bodyStream;
         this.ip = ip;
+        this.server = server;
     }
 
     /**
      * Create a new Request from a Node.js incoming HTTP request.
      * @throws {@link Request.BadUrlError} If the request URL is invalid.
      * @throws {@link Request.SocketClosedError} If the request socket was closed before the request could be handled.
      */
-    public static incomingMessage(incomingMessage: http.IncomingMessage) {
+    public static incomingMessage<A>(incomingMessage: http.IncomingMessage, server: Server<A>) {
         const auth =
             incomingMessage.headers.authorization
                 ?.toLowerCase()
@@ -80,7 +92,7 @@ export class Request {
         if (remoteAddress === undefined)
             throw new Request.SocketClosedError();
 
-        return new Request(incomingMessage.method as Request.Method, new URL(url), headers, incomingMessage, IPAddress.fromString(remoteAddress));
+        return new Request<A>(incomingMessage.method as Request.Method, new URL(url), headers, incomingMessage, IPAddress.fromString(remoteAddress), server);
     }
 
     /**
@@ -97,6 +109,34 @@ export class Request {
         );
     }
 
+    /**
+     * Attempt to obtain authorisation for this request with one of the {@link Server}’s {@link Authenticator}s.
+     * @returns `null` if the request lacks authorisation information.
+     */
+    public async getAuthorisation(): Promise<Authorisation<A> | null> {
+        const authenticator = this.server._authenticators.find(a => a.canAuthenticate(this));
+        if (authenticator === undefined) return null;
+        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.url,
+            this.headers,
+            this.bodyStream,
+            this.ip,
+            this.server,
+        );
+    }
+
     /**
      * Returns a boolean value that declares whether the body has been read yet.
      */

src/Server.ts

@@ -1,37 +1,41 @@
 import http from "node:http";
 import packageJson from "../package.json" with {type: "json"};
+import {Authenticator} from "./auth/Authenticator.js";
 import {Request} from "./Request.js";
 import {Response} from "./response/Response.js";
 import {RouteRegistry} from "./routing/RouteRegistry.js";
 import {ServerErrorRegistry} from "./ServerErrorRegistry.js";
 
-class Server {
+class Server<A> {
     /**
      * Headers sent with every response.
      */
     public readonly globalHeaders: Headers;
     /**
      * This server's route registry.
      */
-    public readonly routes = new RouteRegistry();
+    public readonly routes = new RouteRegistry<A>();
     private readonly server: http.Server;
     private readonly copyOrigin: boolean;
-    private readonly errors = new ServerErrorRegistry();
+    private readonly errors = new ServerErrorRegistry<A>();
+    /** @internal */
+    public readonly _authenticators: Authenticator<A>[];
 
     /**
      * Create a new HTTP server.
      * @param options Server options.
      */
-    public constructor(options: Server.Options) {
+    public constructor(options: Server.Options<A>) {
         this.server = http.createServer({
             joinDuplicateHeaders: true,
         }, this.listener.bind(this));
 
         this.globalHeaders = new Headers(options.globalHeaders);
         if (!this.globalHeaders.has("server"))
-            this.globalHeaders.set("Server", `cldn/${packageJson.version}`);
+            this.globalHeaders.set("Server", `${packageJson.name}/${packageJson.version}`);
 
         this.copyOrigin = options.copyOrigin ?? false;
+        this._authenticators = options.authenticators ?? [];
 
         this.server.listen(options.port);
     }
@@ -42,13 +46,13 @@ class Server {
     }
 
     private async listener(req: http.IncomingMessage, res: http.ServerResponse) {
-        let apiRequest: Request;
+        let apiRequest: Request<A>;
         try {
-            apiRequest = Request.incomingMessage(req);
+            apiRequest = Request.incomingMessage(req, this);
         }
         catch (e) {
             if (e instanceof Request.BadUrlError) {
-                this.errors._get(ServerErrorRegistry.ErrorCodes.BAD_URL, null)._send(res, this);
+                await this.errors._get(ServerErrorRegistry.ErrorCodes.BAD_URL, null)._send(res, this);
                 return;
             }
             if (e instanceof Request.SocketClosedError)
@@ -64,7 +68,7 @@ class Server {
             apiRequest._responseHeaders.set("vary", "origin");
         }
 
-        let response: Response;
+        let response: Response<A>;
         try {
             response = await this.routes.handle(apiRequest);
         }
@@ -76,7 +80,7 @@ class Server {
                 response = this.errors._get(ServerErrorRegistry.ErrorCodes.INTERNAL, apiRequest);
             }
         }
-        response._send(res, this, apiRequest);
+        await response._send(res, apiRequest);
     }
 
     public close(): Promise<void> {
@@ -96,7 +100,7 @@ namespace Server {
     /**
      * Server options
      */
-    export interface Options {
+    export interface Options<A> {
         /**
          * The HTTP listener port. From 1 to 65535. Ports 1–1023 require
          * privileges.
@@ -115,6 +119,11 @@ namespace Server {
          * @default false
          */
         readonly copyOrigin?: boolean;
+
+        /**
+         * Authenticators for handling request authentication.
+         */
+        readonly authenticators?: Authenticator<A>[];
     }
 }
 

src/ServerErrorRegistry.ts

@@ -5,8 +5,8 @@ import {TextResponse} from "./response/TextResponse.js";
 /**
  * A registry for server errors.
  */
-class ServerErrorRegistry {
-    private readonly responses: Record<ServerErrorRegistry.ErrorCodes, Response | ((req?: Request) => Response)>;
+class ServerErrorRegistry<A> {
+    private readonly responses: Record<ServerErrorRegistry.ErrorCodes, Response<A> | ((req?: Request<A>) => Response<A>)>;
 
     /**
      * Create a new server error registry initialised with default responses.
@@ -29,12 +29,12 @@ class ServerErrorRegistry {
      * @param code The server error code.
      * @param response The response to send.
      */
-    public register(code: ServerErrorRegistry.ErrorCodes, response: Response | ((req?: Request) => Response)) {
+    public register(code: ServerErrorRegistry.ErrorCodes, response: Response<A> | ((req?: Request<A>) => Response<A>)) {
         this.responses[code] = response;
     }
 
     /** @internal */
-    public _get(code: ServerErrorRegistry.ErrorCodes, req: Request | null): Response {
+    public _get(code: ServerErrorRegistry.ErrorCodes, req: Request<A> | null): Response<A> {
         const r = this.responses[code];
         if (typeof r === "function") return r(req ?? void 0);
         return r;

src/auth/Authenticator.ts

@@ -0,0 +1,22 @@
+import {Request} from "../Request.js";
+import {Authorisation} from "./Authorisation.js";
+
+/**
+ * Handles authentication for requests.
+ */
+export interface Authenticator<A extends any> {
+    /**
+     * Check whether this can handle authentication for the given request. The authenticator should return `false` if
+     * the request lacks the information required to begin authentication.
+     * @param request
+     */
+    canAuthenticate(request: Request<A>): boolean;
+
+    /**
+     * Authenticate the given request. If authenticate 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
+     */
+    authenticate(request: Request<A>): Promise<Authorisation<A> | null>;
+}

src/auth/Authorisation.ts

@@ -0,0 +1,22 @@
+import {Permission} from "./Permission.js";
+import {PermissionGroup} from "./PermissionGroup.js";
+
+/**
+ * A permission group with additional data.
+ */
+export class Authorisation<T> extends PermissionGroup {
+    /**
+     * Additional authentication data.
+     */
+    public readonly data: T;
+
+    /**
+     * Create a new authorisation.
+     * @param permissions The permissions of the authorisation.
+     * @param data Additional authentication data.
+     */
+    public constructor(permissions: Iterable<Permission>, data: T) {
+        super(permissions);
+        this.data = data;
+    }
+}

src/auth/Permissible.ts

@@ -0,0 +1,12 @@
+import {Permission} from "./Permission.js";
+
+/**
+ * Represents an entity that can be checked for permissions.
+ */
+export interface Permissible {
+    /**
+     * Check whether this entity has the specified permission.
+     * @param permission The permission to check.
+     */
+    has(permission: Permission): boolean;
+}

src/auth/Permission.ts

@@ -0,0 +1,31 @@
+import {Permissible} from "./Permissible.js";
+
+/**
+ * Represents a permission with a unique name.
+ */
+export class Permission implements Permissible {
+    private readonly name: string;
+
+    /**
+     * Create a new permission with the specified name.
+     * @param name The name of the permission.
+     */
+    public constructor(name: string) {
+        this.name = name;
+    }
+
+    /**
+     * Get the name of this permission.
+     */
+    public getName(): string {
+        return this.name;
+    }
+
+    /**
+     * Checks if this permission matches another.
+     * @param permission The permission to compare with.
+     */
+    public has(permission: Permission): boolean {
+        return this.name === permission.name;
+    }
+}