@algovoi/rfc9421-verifier 0.1.0 → 0.2.0

package/README.md

@@ -137,6 +137,12 @@ originating gateway — exactly the property this verifier checks.
 | [`algovoi-audit-verifier`](https://pypi.org/project/algovoi-audit-verifier/) / [`@algovoi/audit-verifier`](https://www.npmjs.com/package/@algovoi/audit-verifier) | Selective-disclosure audit bundle verifier; consumes substrate output |
 | **`algovoi-rfc9421-verifier`** / `@algovoi/rfc9421-verifier` | **This package.** RFC 9421/9530 HTTP signature verifier |
 
+## Relationship to the canonicalisation discipline
+
+This package verifies HTTP message signatures per RFC 9421 + RFC 9530 -- a different canonicalisation surface from the AlgoVoi JCS RFC 8785 receipt-body discipline at [docs.algovoi.co.uk/canonicalisation-substrate](https://docs.algovoi.co.uk/canonicalisation-substrate). HTTP signature verification (this package) and receipt-content verification (`@algovoi/audit-verifier` + the receipt-format packages) are complementary surfaces: this verifier confirms wire-level message integrity; the AlgoVoi JCS substrate confirms receipt-body canonical integrity. Both are AlgoVoi-authored under sole authorship.
+
+Parties anchoring to the AlgoVoi canonicalisation discipline are recorded in the [Substrate Adopters Registry](https://docs.algovoi.co.uk/adopters); the registry's `canon_version` pin criterion applies to receipt-body artefacts, not to HTTP signatures as such.
+
 ## Licence
 
 Apache 2.0. See [`LICENSE`](./LICENSE).

package/dist/parse.d.ts

@@ -11,6 +11,14 @@ export interface ParsedSignatureInput {
     covered_components: string[];
     parameters: Record<string, string | number>;
     raw: string;
+    /**
+     * The post-label portion of the Signature-Input header value, i.e.
+     * the Inner List + parameters block exactly as it appeared on the
+     * wire. This is the value that the @signature-params line in the
+     * RFC 9421 §2.5 signing base must carry. Empty string if the input
+     * was the unlabelled form.
+     */
+    params_block: string;
 }
 export declare function parseSignatureInput(headerValue: string): ParsedSignatureInput;
 export declare function parseSignatureValue(headerValue: string): {

package/dist/parse.js

@@ -35,6 +35,9 @@ export function parseSignatureInput(headerValue) {
     else {
         throw new SignatureInputParseError(`no label or covered-components list found at start: ${JSON.stringify(trimmed.slice(0, 40))}`);
     }
+    // Capture the post-label portion verbatim. This is what the
+    // @signature-params line of the RFC 9421 signing base must contain.
+    const paramsBlock = rest;
     const coveredMatch = COVERED_RE.exec(rest);
     if (!coveredMatch) {
         throw new SignatureInputParseError("no covered-components list found");
@@ -68,6 +71,7 @@ export function parseSignatureInput(headerValue) {
         covered_components: covered,
         parameters,
         raw: trimmed,
+        params_block: paramsBlock,
     };
 }
 export function parseSignatureValue(headerValue) {

package/dist/signing-base.d.ts

@@ -6,6 +6,7 @@
 export declare class SigningBaseError extends Error {
     constructor(message: string);
 }
+export type SigningBaseMode = "algovoi-v0" | "rfc9421";
 export interface SigningBaseInput {
     coveredComponents: string[];
     method?: string;
@@ -16,5 +17,26 @@ export interface SigningBaseInput {
     status?: number;
     headers?: Record<string, string>;
     parameters?: Record<string, string | number>;
+    /**
+     * Signing-base mode.
+     * - "algovoi-v0" (default): preserves the v0.1.0 behaviour for
+     *   backward compatibility with the AlgoVoi internal fixture and
+     *   the rfc9421_proxy_chain_v0 conformance set. @method is
+     *   lowercased and no @signature-params line is appended.
+     * - "rfc9421": full RFC 9421 §2.5 compliance. @method is preserved
+     *   as-supplied (HTTP convention is uppercase), and a final
+     *   "@signature-params" line is appended carrying
+     *   signatureParamsRaw verbatim. This is the shape required to
+     *   verify external fixtures (Envoys envoys-rfc9421, Hippo
+     *   hippo-rfc9421, RFC 9421 §B test vectors, and any other
+     *   RFC-compliant implementation).
+     */
+    mode?: SigningBaseMode;
+    /**
+     * The post-label portion of the Signature-Input header value, i.e.
+     * the Inner List + parameters block exactly as it appeared on the
+     * wire. Required when mode is "rfc9421".
+     */
+    signatureParamsRaw?: string;
 }
 export declare function buildSigningBase(input: SigningBaseInput): string;

package/dist/signing-base.js

@@ -10,6 +10,13 @@ export class SigningBaseError extends Error {
     }
 }
 export function buildSigningBase(input) {
+    const mode = input.mode ?? "algovoi-v0";
+    if (mode !== "algovoi-v0" && mode !== "rfc9421") {
+        throw new SigningBaseError(`mode must be "algovoi-v0" or "rfc9421", got ${JSON.stringify(mode)}`);
+    }
+    if (mode === "rfc9421" && input.signatureParamsRaw === undefined) {
+        throw new SigningBaseError("rfc9421 mode requires signatureParamsRaw (the post-label portion of the Signature-Input header)");
+    }
     const normHeaders = {};
     for (const [k, v] of Object.entries(input.headers ?? {})) {
         normHeaders[k.toLowerCase()] = v;
@@ -23,7 +30,7 @@ export function buildSigningBase(input) {
             case "@method":
                 if (input.method === undefined)
                     throw new SigningBaseError("@method covered but method not supplied");
-                value = input.method.toLowerCase();
+                value = mode === "rfc9421" ? input.method : input.method.toLowerCase();
                 break;
             case "@authority":
                 if (input.authority === undefined)
@@ -72,5 +79,8 @@ export function buildSigningBase(input) {
         }
         lines.push(`"${c}": ${value}`);
     }
+    if (mode === "rfc9421") {
+        lines.push(`"@signature-params": ${input.signatureParamsRaw}`);
+    }
     return lines.join("\n");
 }

package/dist/verify.d.ts

@@ -4,6 +4,7 @@
  * Mirror of the Python algovoi_rfc9421_verifier.verify module.
  * Uses @noble/ed25519 for Ed25519 verification.
  */
+import { type SigningBaseMode } from "./signing-base.js";
 export declare class VerifyError extends Error {
     constructor(message: string);
 }
@@ -27,7 +28,15 @@ export interface VerifyRequestInput {
     publicKey: PublicKey;
     scheme?: string;
     requireContentDigest?: boolean;
-    requireAlgorithm?: string;
+    requireAlgorithm?: string | null;
+    /**
+     * Signing-base mode. Default "algovoi-v0" preserves backward
+     * compatibility with the v0.1.0 internal fixture and the
+     * rfc9421_proxy_chain_v0 conformance set. Set to "rfc9421" to
+     * verify external RFC 9421-compliant fixtures (Envoys, Hippo,
+     * RFC 9421 §B test vectors).
+     */
+    mode?: SigningBaseMode;
 }
 export declare function verifySignature(signingBase: string, signatureBytes: Uint8Array, publicKey: PublicKey, algorithm?: string): Promise<boolean>;
 export declare function verifyRequest(input: VerifyRequestInput): Promise<VerifyResult>;

package/dist/verify.js

@@ -111,7 +111,10 @@ export async function verifyRequest(input) {
         return fail(result, `Signature label ${sigParsed.label} does not match Signature-Input label ${parsedSi.label}`);
     }
     const requireCd = input.requireContentDigest ?? true;
-    const requireAlg = input.requireAlgorithm ?? "sha-256";
+    // null = no algorithm requirement (accept any); undefined = default to sha-256
+    const requireAlg = input.requireAlgorithm === null
+        ? undefined
+        : (input.requireAlgorithm ?? "sha-256");
     if (requireCd) {
         const cdHeader = normHeaders["content-digest"];
         if (!cdHeader)
@@ -130,6 +133,7 @@ export async function verifyRequest(input) {
     else {
         result.content_digest_valid = true;
     }
+    const mode = input.mode ?? "algovoi-v0";
     let signingBase;
     try {
         signingBase = buildSigningBase({
@@ -140,6 +144,8 @@ export async function verifyRequest(input) {
             scheme: input.scheme ?? "https",
             headers: normHeaders,
             parameters: parsedSi.parameters,
+            mode,
+            signatureParamsRaw: mode === "rfc9421" ? parsedSi.params_block : undefined,
         });
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algovoi/rfc9421-verifier",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AlgoVoi RFC 9421 HTTP Message Signatures + RFC 9530 Content-Digest reference verifier",
   "keywords": [
     "rfc9421",

package/src/parse.ts

@@ -16,6 +16,14 @@ export interface ParsedSignatureInput {
   covered_components: string[];
   parameters: Record<string, string | number>;
   raw: string;
+  /**
+   * The post-label portion of the Signature-Input header value, i.e.
+   * the Inner List + parameters block exactly as it appeared on the
+   * wire. This is the value that the @signature-params line in the
+   * RFC 9421 §2.5 signing base must carry. Empty string if the input
+   * was the unlabelled form.
+   */
+  params_block: string;
 }
 
 const LABEL_RE = /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*=\s*/;
@@ -50,6 +58,10 @@ export function parseSignatureInput(headerValue: string): ParsedSignatureInput {
     );
   }
 
+  // Capture the post-label portion verbatim. This is what the
+  // @signature-params line of the RFC 9421 signing base must contain.
+  const paramsBlock = rest;
+
   const coveredMatch = COVERED_RE.exec(rest);
   if (!coveredMatch) {
     throw new SignatureInputParseError("no covered-components list found");
@@ -83,6 +95,7 @@ export function parseSignatureInput(headerValue: string): ParsedSignatureInput {
     covered_components: covered,
     parameters,
     raw: trimmed,
+    params_block: paramsBlock,
   };
 }
 

package/src/signing-base.ts

@@ -11,6 +11,8 @@ export class SigningBaseError extends Error {
   }
 }
 
+export type SigningBaseMode = "algovoi-v0" | "rfc9421";
+
 export interface SigningBaseInput {
   coveredComponents: string[];
   method?: string;
@@ -21,9 +23,42 @@ export interface SigningBaseInput {
   status?: number;
   headers?: Record<string, string>;
   parameters?: Record<string, string | number>;
+  /**
+   * Signing-base mode.
+   * - "algovoi-v0" (default): preserves the v0.1.0 behaviour for
+   *   backward compatibility with the AlgoVoi internal fixture and
+   *   the rfc9421_proxy_chain_v0 conformance set. @method is
+   *   lowercased and no @signature-params line is appended.
+   * - "rfc9421": full RFC 9421 §2.5 compliance. @method is preserved
+   *   as-supplied (HTTP convention is uppercase), and a final
+   *   "@signature-params" line is appended carrying
+   *   signatureParamsRaw verbatim. This is the shape required to
+   *   verify external fixtures (Envoys envoys-rfc9421, Hippo
+   *   hippo-rfc9421, RFC 9421 §B test vectors, and any other
+   *   RFC-compliant implementation).
+   */
+  mode?: SigningBaseMode;
+  /**
+   * The post-label portion of the Signature-Input header value, i.e.
+   * the Inner List + parameters block exactly as it appeared on the
+   * wire. Required when mode is "rfc9421".
+   */
+  signatureParamsRaw?: string;
 }
 
 export function buildSigningBase(input: SigningBaseInput): string {
+  const mode: SigningBaseMode = input.mode ?? "algovoi-v0";
+  if (mode !== "algovoi-v0" && mode !== "rfc9421") {
+    throw new SigningBaseError(
+      `mode must be "algovoi-v0" or "rfc9421", got ${JSON.stringify(mode)}`,
+    );
+  }
+  if (mode === "rfc9421" && input.signatureParamsRaw === undefined) {
+    throw new SigningBaseError(
+      "rfc9421 mode requires signatureParamsRaw (the post-label portion of the Signature-Input header)",
+    );
+  }
+
   const normHeaders: Record<string, string> = {};
   for (const [k, v] of Object.entries(input.headers ?? {})) {
     normHeaders[k.toLowerCase()] = v;
@@ -39,7 +74,7 @@ export function buildSigningBase(input: SigningBaseInput): string {
       case "@method":
         if (input.method === undefined)
           throw new SigningBaseError("@method covered but method not supplied");
-        value = input.method.toLowerCase();
+        value = mode === "rfc9421" ? input.method : input.method.toLowerCase();
         break;
       case "@authority":
         if (input.authority === undefined)
@@ -96,5 +131,9 @@ export function buildSigningBase(input: SigningBaseInput): string {
     lines.push(`"${c}": ${value}`);
   }
 
+  if (mode === "rfc9421") {
+    lines.push(`"@signature-params": ${input.signatureParamsRaw}`);
+  }
+
   return lines.join("\n");
 }

package/src/verify.ts

@@ -15,6 +15,7 @@ import {
 import {
   buildSigningBase,
   SigningBaseError,
+  type SigningBaseMode,
 } from "./signing-base.js";
 import {
   verifyContentDigest,
@@ -50,7 +51,15 @@ export interface VerifyRequestInput {
   publicKey: PublicKey;
   scheme?: string;
   requireContentDigest?: boolean;
-  requireAlgorithm?: string;
+  requireAlgorithm?: string | null;
+  /**
+   * Signing-base mode. Default "algovoi-v0" preserves backward
+   * compatibility with the v0.1.0 internal fixture and the
+   * rfc9421_proxy_chain_v0 conformance set. Set to "rfc9421" to
+   * verify external RFC 9421-compliant fixtures (Envoys, Hippo,
+   * RFC 9421 §B test vectors).
+   */
+  mode?: SigningBaseMode;
 }
 
 function newResult(): VerifyResult {
@@ -173,7 +182,11 @@ export async function verifyRequest(
   }
 
   const requireCd = input.requireContentDigest ?? true;
-  const requireAlg = input.requireAlgorithm ?? "sha-256";
+  // null = no algorithm requirement (accept any); undefined = default to sha-256
+  const requireAlg: string | undefined =
+    input.requireAlgorithm === null
+      ? undefined
+      : (input.requireAlgorithm ?? "sha-256");
 
   if (requireCd) {
     const cdHeader = normHeaders["content-digest"];
@@ -192,6 +205,8 @@ export async function verifyRequest(
     result.content_digest_valid = true;
   }
 
+  const mode: SigningBaseMode = input.mode ?? "algovoi-v0";
+
   let signingBase: string;
   try {
     signingBase = buildSigningBase({
@@ -202,6 +217,9 @@ export async function verifyRequest(
       scheme: input.scheme ?? "https",
       headers: normHeaders,
       parameters: parsedSi.parameters,
+      mode,
+      signatureParamsRaw:
+        mode === "rfc9421" ? parsedSi.params_block : undefined,
     });
   } catch (e) {
     if (e instanceof SigningBaseError) {