@irvinebroque/http-rfc-utils 0.1.0

package/dist/http-signatures.d.ts

@@ -0,0 +1,202 @@
+/**
+ * HTTP Message Signatures per RFC 9421.
+ * RFC 9421 §2-3.
+ * @see https://www.rfc-editor.org/rfc/rfc9421.html
+ *
+ * This module provides primitives for creating signature bases and parsing/formatting
+ * Signature-Input and Signature fields. Actual cryptographic signing/verification
+ * is out of scope - this provides the HTTP-layer primitives.
+ */
+import type { SignatureComponent, SignatureParams, SignatureInput, Signature, SignatureMessageContext, SignatureBaseResult, DerivedComponentName } from './types.js';
+/**
+ * Derived component names per RFC 9421 §2.2.
+ * These are special component identifiers that start with '@'.
+ */
+export declare const DERIVED_COMPONENTS: readonly DerivedComponentName[];
+/**
+ * Check if a component name is a derived component.
+ * RFC 9421 §2.2.
+ */
+export declare function isDerivedComponent(name: string): name is DerivedComponentName;
+/**
+ * Parse a Signature-Input field value.
+ * RFC 9421 §4.1.
+ *
+ * The Signature-Input field is a Dictionary Structured Field containing the
+ * metadata for one or more message signatures.
+ *
+ * @param value - The Signature-Input header field value
+ * @returns Array of parsed SignatureInput objects, or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * const inputs = parseSignatureInput(
+ *     'sig1=("@method" "@authority" "content-type");created=1618884473;keyid="test-key"'
+ * );
+ * // Returns: [{ label: 'sig1', components: [...], params: { created: 1618884473, keyid: 'test-key' } }]
+ * ```
+ */
+export declare function parseSignatureInput(value: string): SignatureInput[] | null;
+/**
+ * Format SignatureInput objects to a Signature-Input field value.
+ * RFC 9421 §4.1.
+ *
+ * @param inputs - Array of SignatureInput objects to format
+ * @returns The formatted Signature-Input header field value
+ *
+ * @example
+ * ```ts
+ * const value = formatSignatureInput([{
+ *     label: 'sig1',
+ *     components: [{ name: '@method' }, { name: 'content-type' }],
+ *     params: { created: 1618884473, keyid: 'test-key' }
+ * }]);
+ * // Returns: 'sig1=("@method" "content-type");created=1618884473;keyid="test-key"'
+ * ```
+ */
+export declare function formatSignatureInput(inputs: SignatureInput[]): string;
+/**
+ * Parse a Signature field value.
+ * RFC 9421 §4.2.
+ *
+ * The Signature field is a Dictionary Structured Field containing signature
+ * values as byte sequences.
+ *
+ * @param value - The Signature header field value
+ * @returns Array of parsed Signature objects, or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * const sigs = parseSignature('sig1=:YmFzZTY0ZW5jb2RlZHNpZw==:');
+ * // Returns: [{ label: 'sig1', value: Uint8Array([...]) }]
+ * ```
+ */
+export declare function parseSignature(value: string): Signature[] | null;
+/**
+ * Format Signature objects to a Signature field value.
+ * RFC 9421 §4.2.
+ *
+ * @param signatures - Array of Signature objects to format
+ * @returns The formatted Signature header field value
+ *
+ * @example
+ * ```ts
+ * const value = formatSignature([{
+ *     label: 'sig1',
+ *     value: new Uint8Array([98, 97, 115, 101, 54, 52])
+ * }]);
+ * // Returns: 'sig1=:YmFzZTY0:' (base64 encoded)
+ * ```
+ */
+export declare function formatSignature(signatures: Signature[]): string;
+/**
+ * Parse a component identifier string.
+ * RFC 9421 §2.
+ *
+ * Component identifiers are strings that identify HTTP message components
+ * to be included in the signature base.
+ *
+ * @param value - The component identifier string (e.g., '"content-type"' or '"cache-control";sf')
+ * @returns Parsed SignatureComponent, or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * const component = parseComponentIdentifier('"content-type"');
+ * // Returns: { name: 'content-type' }
+ *
+ * const componentWithParams = parseComponentIdentifier('"example-dict";key="member"');
+ * // Returns: { name: 'example-dict', params: { key: 'member' } }
+ * ```
+ */
+export declare function parseComponentIdentifier(value: string): SignatureComponent | null;
+/**
+ * Format a component identifier to string.
+ * RFC 9421 §2.
+ *
+ * @param component - The SignatureComponent to format
+ * @returns The formatted component identifier string
+ *
+ * @example
+ * ```ts
+ * formatComponentIdentifier({ name: 'content-type' });
+ * // Returns: '"content-type"'
+ *
+ * formatComponentIdentifier({ name: 'example-dict', params: { key: 'member' } });
+ * // Returns: '"example-dict";key="member"'
+ * ```
+ */
+export declare function formatComponentIdentifier(component: SignatureComponent): string;
+/**
+ * Canonicalize field values per RFC 9421 §2.1.
+ *
+ * Multiple field values are combined with ", " (comma + space).
+ * Leading/trailing whitespace is trimmed from each value.
+ * Obsolete line folding is replaced with a single space.
+ *
+ * @param values - Array of field values
+ * @returns The canonicalized field value
+ *
+ * @example
+ * ```ts
+ * canonicalizeFieldValue(['  value1  ', '  value2  ']);
+ * // Returns: 'value1, value2'
+ * ```
+ */
+export declare function canonicalizeFieldValue(values: string[]): string;
+/**
+ * Binary-wrap field values per RFC 9421 §2.1.4.
+ *
+ * Each field value is base64-encoded individually, and the results are
+ * combined with ", " (comma + space) and then re-encoded as a byte sequence.
+ *
+ * @param values - Array of field values
+ * @returns The binary-wrapped field value as a byte sequence
+ *
+ * @example
+ * ```ts
+ * binaryWrapFieldValues(['value1', 'value2']);
+ * // Returns base64 of each value concatenated
+ * ```
+ */
+export declare function binaryWrapFieldValues(values: string[]): Uint8Array;
+/**
+ * Derive a component value from a message context.
+ * RFC 9421 §2.
+ *
+ * @param message - The message context
+ * @param component - The component to derive
+ * @returns The derived value, or null if the component cannot be derived
+ */
+export declare function deriveComponentValue(message: SignatureMessageContext, component: SignatureComponent): string | null;
+/**
+ * Create the signature base string.
+ * RFC 9421 §2.5.
+ *
+ * The signature base is the string that will be signed. It contains one line
+ * per covered component, plus the signature parameters line at the end.
+ *
+ * @param message - The message context
+ * @param components - The components to include in the signature
+ * @param params - The signature parameters
+ * @returns The signature base and formatted signature-params, or null if creation fails
+ *
+ * @example
+ * ```ts
+ * const result = createSignatureBase(
+ *     {
+ *         method: 'POST',
+ *         authority: 'example.com',
+ *         headers: new Map([['content-type', ['application/json']]])
+ *     },
+ *     [{ name: '@method' }, { name: '@authority' }, { name: 'content-type' }],
+ *     { created: 1618884473, keyid: 'test-key' }
+ * );
+ * // Returns:
+ * // {
+ * //     base: '"@method": POST\n"@authority": example.com\n"content-type": application/json\n"@signature-params": ("@method" "@authority" "content-type");created=1618884473;keyid="test-key"',
+ * //     signatureParams: '("@method" "@authority" "content-type");created=1618884473;keyid="test-key"'
+ * // }
+ * ```
+ */
+export declare function createSignatureBase(message: SignatureMessageContext, components: SignatureComponent[], params?: SignatureParams): SignatureBaseResult | null;
+//# sourceMappingURL=http-signatures.d.ts.map

package/dist/http-signatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-signatures.d.ts","sourceRoot":"","sources":["../src/http-signatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACR,kBAAkB,EAElB,eAAe,EACf,cAAc,EACd,SAAS,EACT,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EAIvB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,oBAAoB,EAUpD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,oBAAoB,CAE7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,GAAG,IAAI,CAsC1E;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CA6DrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,IAAI,CAuBhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAQ/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAwIjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAyB/E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAS/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAYlE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,uBAAuB,EAChC,SAAS,EAAE,kBAAkB,GAC9B,MAAM,GAAG,IAAI,CAWf;AA+HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,kBAAkB,EAAE,EAChC,MAAM,CAAC,EAAE,eAAe,GACzB,mBAAmB,GAAG,IAAI,CAoC5B"}