feat(stringify): add serializer for authrization

Author: TomokiMiyauci

README.md

@@ -78,6 +78,72 @@ assertThrows(() =>
 );
 ```
 
+## Serialization
+
+Serialize [Authorization](#authorization) into string.
+
+```ts
+import { stringifyAuthorization } from "https://deno.land/x/authorization_parser@$VERSION/stringify.ts";
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+
+assertEquals(
+  stringifyAuthorization({ authScheme: "Basic", params: "token68==" }),
+  "Basic token68",
+);
+assertEquals(
+  stringifyAuthorization({
+    authScheme: "Bearer",
+    params: { realm: `"Secure area"`, error: `"invalid_token"` },
+  }),
+  `Bearer realm="Secure area", error="invalid_token"`,
+);
+```
+
+### Error
+
+Throws an error in the following cases:
+
+- `authScheme` is invalid
+  [auth-scheme](https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1-2)
+- `params` is invalid
+  [token68](https://www.rfc-editor.org/rfc/rfc9110.html#section-11.2-2)
+- `params` key is invalid
+  [token](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.2-2)
+- `params` value is invalid
+  [token](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.2-2) or
+  [quoted-string](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.4-2)
+- There is a duplication in `params` keys(case-insensitive)
+
+```ts
+import { stringifyAuthorization } from "https://deno.land/x/authorization_parser@$VERSION/stringify.ts";
+import { assertThrows } from "https://deno.land/std/testing/asserts.ts";
+
+assertThrows(() =>
+  stringifyAuthorization({ authScheme: "<invalid:auth-scheme>" })
+);
+assertThrows(() =>
+  stringifyAuthorization({ authScheme: "<valid>", params: "<invalid:token68>" })
+);
+assertThrows(() =>
+  stringifyAuthorization({
+    authScheme: "<valid>",
+    params: { "<invalid:token>": "<valid>" },
+  })
+);
+assertThrows(() =>
+  stringifyAuthorization({
+    authScheme: "<valid>",
+    params: { "<valid>": "<invalid:token|quoted-string>" },
+  })
+);
+assertThrows(() =>
+  stringifyAuthorization({
+    authScheme: "<valid>",
+    params: { "<duplicate>": "<valid>", "<DUPLICATE>": "<valid>" },
+  })
+);
+```
+
 ## Authorization
 
 `Authorization` is following structure:

deps.ts

@@ -4,3 +4,5 @@
 export { toLowerCase } from "https://deno.land/x/[email protected]/to_lower_case.ts";
 export { trim } from "https://deno.land/x/[email protected]/trim.ts";
 export { head } from "https://deno.land/x/[email protected]/head.ts";
+export { isString } from "https://deno.land/x/[email protected]/is_string.ts";
+export { isNullable } from "https://deno.land/x/[email protected]/is_nullable.ts";

mod.ts

@@ -2,4 +2,5 @@
 // This module is browser compatible.
 
 export { parseAuthorization } from "./parse.ts";
-export type { Authorization, AuthParam, Token68 } from "./types.ts";
+export { type AuthorizationLike, stringifyAuthorization } from "./stringify.ts";
+export type { Authorization, AuthParams, Token68 } from "./types.ts";

stringify.ts

@@ -0,0 +1,113 @@
+// Copyright 2023-latest the httpland authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { isNullable, isString, toLowerCase } from "./deps.ts";
+import { duplicate } from "./utils.ts";
+import { Msg } from "./constants.ts";
+import type { Authorization, AuthParams } from "./types.ts";
+
+export interface AuthorizationLike
+  extends
+    Pick<Authorization, "authScheme">,
+    Partial<Pick<Authorization, "params">> {
+}
+
+/** Serialize {@link AuthorizationLike} into string.
+ *
+ * @example
+ * ```ts
+ * import { stringifyAuthorization } from "https://deno.land/x/authorization_parser@$VERSION/stringify.ts";
+ * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * assertEquals(
+ *   stringifyAuthorization({ authScheme: "Basic", params: "token68==" }),
+ *   "Basic token68",
+ * );
+ * assertEquals(
+ *   stringifyAuthorization({
+ *     authScheme: "Bearer",
+ *     params: { realm: `"Secure area"`, error: `"invalid_token"` },
+ *   }),
+ *   `Bearer realm="Secure area", error="invalid_token"`,
+ * );
+ * ```
+ *
+ * @throws {Error} If the input is invalid {@link AuthorizationLike}.
+ */
+export function stringifyAuthorization(input: AuthorizationLike): string {
+  assertToken(input.authScheme, `authScheme ${Msg.InvalidToken}`);
+
+  if (isNullable(input.params)) return input.authScheme;
+
+  const data = isString(input.params)
+    ? (assertToken68(input.params, `token ${Msg.InvalidToken68}`), input.params)
+    : stringifyAuthParams(input.params);
+
+  return [input.authScheme, data].filter(Boolean).join(" ");
+}
+
+const reToken = /^[\w!#$%&'*+.^`|~-]+$/;
+
+export function assertToken(
+  input: string,
+  msg?: string,
+  constructor: ErrorConstructor = Error,
+): asserts input {
+  if (!isToken(input)) throw new constructor(msg);
+}
+
+export function isToken(input: string): boolean {
+  return reToken.test(input);
+}
+
+const reToken68 = /^[A-Za-z\d+./_~-]+=*$/;
+
+export function isToken68(input: string): boolean {
+  return reToken68.test(input);
+}
+
+export function assertToken68(
+  input: string,
+  msg?: string,
+  constructor: ErrorConstructor = Error,
+): asserts input {
+  if (!isToken68(input)) throw new constructor(msg);
+}
+
+const reQuotedString =
+  /^"(?:\t| |!|[ \x23-\x5B\x5D-\x7E]|[\x80-\xFF]|\\(?:\t| |[\x21-\x7E])[\x80-\xFF])*"$/;
+
+export function isQuotedString(input: string): boolean {
+  return reQuotedString.test(input);
+}
+
+function assertAuthParam(input: AuthParams): asserts input {
+  for (const key in input) {
+    assertToken(key, `token key ${Msg.InvalidToken}`);
+
+    const value = input[key]!;
+
+    if (isToken(value) || isQuotedString(value)) continue;
+
+    throw Error(`token value should be <token> or <quoted-string> format`);
+  }
+
+  const duplicates = duplicate(Object.keys(input).map(toLowerCase));
+
+  if (duplicates.length) throw Error(Msg.DuplicatedKeys);
+}
+
+export function stringifyAuthParams(input: AuthParams): string {
+  assertAuthParam(input);
+
+  return Object
+    .entries(input)
+    .map(joinEntry)
+    .join(", ");
+}
+
+function joinEntry(
+  entry: readonly [string, string],
+): string {
+  return entry[0] + "=" + entry[1];
+}

stringify_test.ts

@@ -0,0 +1,61 @@
+import { AuthorizationLike, stringifyAuthorization } from "./stringify.ts";
+import {
+  assertEquals,
+  assertThrows,
+  Authorization,
+  describe,
+  it,
+} from "./_dev_deps.ts";
+
+import authorization from "./authorization.json" assert { type: "json" };
+
+describe("stringifyAuthorization", () => {
+  it("should return string if the input is valid", () => {
+    const table: [AuthorizationLike, string][] = [
+      [{ authScheme: "a" }, "a"],
+      [{ authScheme: "basic" }, "basic"],
+      [{ authScheme: "basic", params: "abcde" }, "basic abcde"],
+      [{ authScheme: "basic", params: "abcde==" }, "basic abcde=="],
+      [{ authScheme: "basic", params: {} }, "basic"],
+      [{ authScheme: "basic", params: { a: "a" } }, "basic a=a"],
+      [
+        { authScheme: "basic", params: { a: "a", b: `"test"` } },
+        `basic a=a, b="test"`,
+      ],
+    ];
+
+    table.forEach(([input, expected]) => {
+      assertEquals(stringifyAuthorization(input), expected);
+    });
+  });
+
+  it("should throw error if the input is invalid", () => {
+    const table: AuthorizationLike[] = [
+      { authScheme: "" },
+      { authScheme: "<invalid>" },
+      { authScheme: "a", params: "" },
+      { authScheme: "a", params: "<invalid>" },
+      { authScheme: "a", params: { "": "" } },
+      { authScheme: "a", params: { "<invalid>": "" } },
+      { authScheme: "a", params: { a: "" } },
+      { authScheme: "a", params: { a: "<invalid>" } },
+      { authScheme: "a", params: { a: `"\x00"` } },
+      { authScheme: "a", params: { a: "test", A: "test" } },
+    ];
+
+    table.forEach((input) => {
+      assertThrows(() => stringifyAuthorization(input));
+    });
+  });
+
+  authorization.forEach((suite) => {
+    it(suite.name, () => {
+      if (!suite.must_fail) {
+        assertEquals(
+          stringifyAuthorization(suite.expected as Authorization),
+          suite.header,
+        );
+      }
+    });
+  });
+});