@httpland/http-auth v1.0.0-beta.1

http-auth

HTTP authentication middleware framework for standard Request and Response.

Compliant with RFC 9110, 11 HTTP Authentication.

Middleware

For a definition of Universal HTTP middleware, see the http-middleware project.

What

Handles Authorization and WWW-Authenticate HTTP headers. Called before the handler, it acts as a filter/guard for the handler.

You can focus solely on authenticate the integrity of the token.

More specifically:

• Secure parsing of the Authorization header
• Manage the HTTP Authentication header
• Control the handler

Usage

You specify the Authenticate scheme and provide the authentication function for token.

import auth from "https://deno.land/x/http_auth@$VERSION/mod.ts";
import {
  assertSpyCall,
  assertSpyCalls,
  spy,
} from "https://deno.land/std@0.177.0/testing/mock.ts";
import { assertEquals } from "https://deno.land/std@0.177.0/testing/asserts.ts";

const handler = spy(() => new Response());
const authenticate = spy(() => false);
const middleware = auth({ scheme: "<auth-scheme>", authenticate });
const response = await middleware(
  new Request("http://localhost", {
    headers: { authorization: "<auth-scheme> <token>" },
  }),
  handler,
);

assertSpyCalls(handler, 0);
assertSpyCall(authenticate, 0, { args: ["<token>"] });
assertEquals(response.status, 401);
assertEquals(response.headers.get("www-authenticate"), "<auth-scheme>");

Authentication headers

It is helpful to know about HTTP authentication headers.

Authorization: <auth-scheme> <token>
WWW-Authenticate: <auth-scheme> [*<auth-param>]

• auth-scheme - Authentication scheme. e.g. Basic
• token - Authentication token

Authentication

Authentication is an object that defines an authentication type and authentication method. It has the following structure:

interface Authentication {
  readonly scheme: string;
  readonly authenticate: Authenticate;
}

interface Authenticate {
  (token: string): boolean | Promise<boolean>;
}

The scheme represent <auth-scheme>.

The authenticate receives <token> from the Authorization header. It interprets the token is valid or not.

Basic

Provides ready-to-use Authorization for Basic Authentication.

import auth from "https://deno.land/x/http_auth@$VERSION/mod.ts";
import Basic from "https://deno.land/x/http_auth@$VERSION/basic.ts";
import { assertEquals } from "https://deno.land/std@0.177.0/testing/asserts.ts";

const middleware = auth(
  new Basic({ "<user-id>": "<password>", admin: "123456" }),
);
const response = await middleware(
  new Request("http://localhost"),
  () => new Response(),
);

assertEquals(
  response.headers.get("www-authenticate"),
  `Basic realm="Secure area"`,
);

License

Copyright © 2023-present httpland.

Released under the MIT license