mppx 0.8.15 → 0.8.18

package/dist/attestation/Client.js

@@ -0,0 +1,28 @@
+import * as SigningContext from './internal/SigningContext.js';
+/**
+ * Combines request signers using one shared context per call.
+ *
+ * The returned signer creates a fresh context unless its caller supplies one,
+ * allowing every signature on one HTTP attempt to share a nonce and timestamp.
+ */
+export function composeSigners(...signers) {
+    return {
+        protocol: 'composed',
+        async sign(request, context = SigningContext.create()) {
+            for (const signer of signers)
+                request = await signer.sign(request, context);
+            return request;
+        },
+    };
+}
+/**
+ * Wraps a fetch implementation so every outbound request is attested.
+ *
+ * Configure this wrapper as the underlying `fetch` passed to `mppx/client`
+ * `Fetch.from()`. MPPX then uses it for both the initial request and its
+ * automatic request containing an `Authorization: Payment` credential.
+ */
+export function wrapFetch(fetch, signer) {
+    return async (input, init) => fetch(await signer.sign(new Request(input, init)));
+}
+//# sourceMappingURL=Client.js.map

package/dist/attestation/Constants.d.ts

@@ -0,0 +1,15 @@
+/** RFC 9421 signature algorithms supported by request attestation. */
+export declare const Algorithms: {
+    /** EdDSA using the Ed25519 curve. */
+    readonly ed25519: 'ed25519';
+    /** RSASSA-PSS using SHA-512 and a 64-byte salt. */
+    readonly rsaPssSha512: 'rsa-pss-sha512';
+};
+/** HTTP headers defined by RFC 9421 for request-attestation signatures. */
+export declare const Headers: {
+    /** Carries the RFC 9421 signature bytes. */
+    readonly signature: 'Signature';
+    /** Carries the RFC 9421 covered components and signature parameters. */
+    readonly signatureInput: 'Signature-Input';
+};
+//# sourceMappingURL=Constants.d.ts.map

package/dist/attestation/Constants.js

@@ -0,0 +1,15 @@
+/** RFC 9421 signature algorithms supported by request attestation. */
+export const Algorithms = {
+    /** EdDSA using the Ed25519 curve. */
+    ed25519: 'ed25519',
+    /** RSASSA-PSS using SHA-512 and a 64-byte salt. */
+    rsaPssSha512: 'rsa-pss-sha512',
+};
+/** HTTP headers defined by RFC 9421 for request-attestation signatures. */
+export const Headers = {
+    /** Carries the RFC 9421 signature bytes. */
+    signature: 'Signature',
+    /** Carries the RFC 9421 covered components and signature parameters. */
+    signatureInput: 'Signature-Input',
+};
+//# sourceMappingURL=Constants.js.map

package/dist/attestation/Server.d.ts

@@ -0,0 +1,4 @@
+import type * as Types from './Types.js';
+/** Verifies every configured request-attestation protocol. */
+export declare function verify<const verifiers extends Types.VerifierMap>(request: Request, verifiers: verifiers): Promise<Types.VerificationsFrom<verifiers>>;
+//# sourceMappingURL=Server.d.ts.map

package/dist/attestation/Server.js

@@ -0,0 +1,8 @@
+/** Verifies every configured request-attestation protocol. */
+export async function verify(request, verifiers) {
+    const outcomes = {};
+    for (const [name, verifier] of Object.entries(verifiers))
+        outcomes[name] = await verifier.verify(request);
+    return outcomes;
+}
+//# sourceMappingURL=Server.js.map

package/dist/attestation/Types.d.ts

@@ -0,0 +1,76 @@
+import type { MaybePromise } from '../internal/types.js';
+import type { Algorithms } from './Constants.js';
+/** RFC 9421 algorithms implemented by the request-attestation signer and verifier. */
+export type SignatureAlgorithm = (typeof Algorithms)[keyof typeof Algorithms];
+/** Resolves a trusted public key for a parsed request signature. */
+export type KeyResolver = (parameters: {
+    /** RFC 9421 algorithm declared by the signature. */
+    algorithm: SignatureAlgorithm;
+    /** Key identifier declared by the signature. */
+    keyId: string;
+    /** Request carrying the signature. */
+    request: Request;
+}) => MaybePromise<CryptoKey | undefined>;
+/**
+ * The complete outcome of attempting one protocol verifier.
+ *
+ * `absent` means the protocol did not appear on the request. `invalid` means
+ * it appeared but failed validation and must reject the request. `unverified`
+ * means key material or another required verification dependency was unavailable.
+ * `verified` carries protocol-specific data that is safe for callers to inspect.
+ */
+export type Verification<value = unknown> = {
+    status: 'absent';
+} | {
+    status: 'invalid';
+    reason: string;
+} | {
+    status: 'unverified';
+    reason: string;
+} | {
+    status: 'verified';
+    value: value;
+};
+/**
+ * Verifies one request-attestation protocol carried by an HTTP request.
+ *
+ * Verifiers are registered in a {@link VerifierMap}; each map key names the
+ * result returned to the caller.
+ */
+export type Verifier<value = unknown> = {
+    /** Validates the request and returns a complete protocol verification outcome. */
+    verify: (request: Request) => MaybePromise<Verification<value>>;
+};
+/** Maps each recognized protocol name to its verifier. */
+export type VerifierMap = Readonly<Record<string, Verifier>>;
+/** Preserves each configured protocol's complete verification outcome. */
+export type VerificationsFrom<verifiers extends VerifierMap> = {
+    readonly [protocol in keyof verifiers]: Awaited<ReturnType<verifiers[protocol]['verify']>>;
+};
+/**
+ * Values shared by every signer contributing to one HTTP request attempt.
+ *
+ * A caller may reuse this context across independent signature protocols so
+ * they describe the same attempt. A later network retry must use a new context.
+ */
+export type SigningContext = {
+    /** Unix timestamp, in seconds, at which the request attempt was created. */
+    readonly created: number;
+    /** Base64url-encoded random value identifying this request attempt. */
+    readonly nonce: string;
+};
+/**
+ * Signs each outbound HTTP request, including MPP payment retries.
+ *
+ * The protocol type preserves which adapter produced the signer for diagnostics
+ * and composition, without asserting that the signer alone authorizes payment.
+ */
+export type Signer<protocol extends string = string> = {
+    /** Protocol identifier used for diagnostics. */
+    protocol: protocol;
+    /** Returns a new request containing the protocol's signature material. */
+    sign: (request: Request, context?: SigningContext | undefined) => MaybePromise<Request>;
+};
+/** Maps application-defined names to request-attestation signers. */
+export type SignerMap = Readonly<Record<string, Signer>>;
+//# sourceMappingURL=Types.d.ts.map

package/dist/attestation/Types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Types.js.map

package/dist/attestation/index.d.ts

@@ -0,0 +1,6 @@
+export * as Client from './Client.js';
+export * as Server from './Server.js';
+export * as Store from '../Store.js';
+export * from './Constants.js';
+export * from './Types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/attestation/index.js

@@ -0,0 +1,6 @@
+export * as Client from './Client.js';
+export * as Server from './Server.js';
+export * as Store from '../Store.js';
+export * from './Constants.js';
+export * from './Types.js';
+//# sourceMappingURL=index.js.map

package/dist/attestation/internal/HttpMessageSignature.d.ts

@@ -0,0 +1,73 @@
+import type { BareItem } from 'structured-headers';
+import type { MaybePromise } from '../../internal/types.js';
+import * as Store from '../../Store.js';
+import type { KeyResolver, SignatureAlgorithm, SigningContext } from '../Types.js';
+/** RFC 9421 constants used by request-attestation signature profiles. */
+export declare const Constants: {
+    /** Derived request components supported by this narrow request profile. */
+    readonly components: {
+        /** The target host and non-default port. */
+        readonly authority: '@authority';
+        /** The request URL path without its query string. */
+        readonly path: '@path';
+        /** The lowercased `Signature-Agent` request header. */
+        readonly signatureAgent: 'signature-agent';
+        /** The signature's canonicalized covered-components and parameters. */
+        readonly signatureParams: '@signature-params';
+    };
+};
+/** A covered HTTP message component and its RFC 9421 component parameters. */
+export type Component = {
+    /** Derived component identifier or lowercased HTTP field name. */
+    id: string;
+    /** Parameters that qualify the component, such as `;key="agent"`. */
+    parameters?: ReadonlyMap<string, BareItem> | undefined;
+};
+/** Input accepted by signers; bare strings denote unparameterized components. */
+export type ComponentInput = string | Component;
+export type SignatureInput = {
+    algorithm: SignatureAlgorithm;
+    components: readonly Component[];
+    created: number;
+    expires: number;
+    keyId: string;
+    label: string;
+    nonce: string;
+    parameters: ReadonlyMap<string, BareItem>;
+    tag: string;
+};
+/** Result of validating one supported RFC 9421 signature. */
+export type VerificationResult = {
+    status: 'absent';
+} | {
+    status: 'invalid';
+    reason: string;
+} | {
+    status: 'unverified';
+    reason: string;
+} | {
+    status: 'verified';
+    input: SignatureInput;
+};
+/** Signs a request using the configured RFC 9421-derived component list. */
+export declare function sign(request: Request, options: {
+    components: readonly ComponentInput[];
+    expiresIn?: number | undefined;
+    keyId: string;
+    key: CryptoKey;
+    label: string;
+    context?: SigningContext | undefined;
+    tag: string;
+}): Promise<Request>;
+/** Verifies a request signature, its lifetime, and optionally its nonce. */
+export declare function verify(request: Request, options: {
+    keyResolver: KeyResolver;
+    maxAge: number;
+    nonceNamespace: string;
+    nonceStore: Store.AtomicStore;
+    requiredComponents: readonly string[];
+    tag: string | readonly string[];
+    validate?: ((input: SignatureInput, request: Request) => string | undefined) | undefined;
+    validateKey?: ((key: CryptoKey, input: SignatureInput, request: Request) => MaybePromise<string | undefined>) | undefined;
+}): Promise<VerificationResult>;
+//# sourceMappingURL=HttpMessageSignature.d.ts.map

package/dist/attestation/internal/HttpMessageSignature.js

@@ -0,0 +1,320 @@
+import { isInnerList, parseDictionary, serializeItem, serializeDictionary, serializeInnerList, serializeParameters, } from 'structured-headers';
+import * as Store from '../../Store.js';
+import { Algorithms, Headers as AttestationHeaders } from '../Constants.js';
+import * as SigningContextInternal from './SigningContext.js';
+/** RFC 9421 constants used by request-attestation signature profiles. */
+export const Constants = {
+    /** Derived request components supported by this narrow request profile. */
+    components: {
+        /** The target host and non-default port. */
+        authority: '@authority',
+        /** The request URL path without its query string. */
+        path: '@path',
+        /** The lowercased `Signature-Agent` request header. */
+        signatureAgent: 'signature-agent',
+        /** The signature's canonicalized covered-components and parameters. */
+        signatureParams: '@signature-params',
+    },
+};
+const algorithmDescriptors = {
+    [Algorithms.ed25519]: {
+        hash: undefined,
+        keyAlgorithm: 'Ed25519',
+        webCryptoAlgorithm: 'Ed25519',
+    },
+    [Algorithms.rsaPssSha512]: {
+        hash: 'SHA-512',
+        keyAlgorithm: 'RSA-PSS',
+        webCryptoAlgorithm: { name: 'RSA-PSS', saltLength: 64 },
+    },
+};
+/** Signs a request using the configured RFC 9421-derived component list. */
+export async function sign(request, options) {
+    const context = options.context ?? SigningContextInternal.create();
+    const created = context.created;
+    const expires = created + (options.expiresIn ?? 60);
+    const algorithm = algorithmFromKey(options.key);
+    const parameters = new Map([
+        ['created', created],
+        ['expires', expires],
+        ['keyid', options.keyId],
+        ['alg', algorithm],
+        ['nonce', context.nonce],
+        ['tag', options.tag],
+    ]);
+    const input = {
+        algorithm,
+        components: options.components.map(toComponent),
+        created,
+        expires,
+        keyId: options.keyId,
+        label: options.label,
+        nonce: context.nonce,
+        parameters,
+        tag: options.tag,
+    };
+    const signature = await crypto.subtle.sign(webCryptoAlgorithm(algorithm), options.key, toArrayBuffer(encode(signatureBase(request, input))));
+    const headers = new Headers(request.headers);
+    const inputs = parseHeaderDictionary(headers, AttestationHeaders.signatureInput);
+    const signatures = parseHeaderDictionary(headers, AttestationHeaders.signature);
+    if (!haveSameKeys(inputs, signatures))
+        throw new Error('Signature-Input and Signature must contain the same labels.');
+    if (inputs.has(input.label) || signatures.has(input.label))
+        throw new Error(`HTTP message signature label "${input.label}" already exists.`);
+    inputs.set(input.label, toInnerList(input));
+    signatures.set(input.label, [signature, new Map()]);
+    headers.set(AttestationHeaders.signatureInput, serializeDictionary(inputs));
+    headers.set(AttestationHeaders.signature, serializeDictionary(signatures));
+    return new Request(request, { headers });
+}
+/** Verifies a request signature, its lifetime, and optionally its nonce. */
+export async function verify(request, options) {
+    const parsed = parse(request, options.tag);
+    if (!parsed)
+        return { status: 'absent' };
+    if (parsed.reason)
+        return { status: 'invalid', reason: parsed.reason };
+    if (!parsed.input || !parsed.signature)
+        return { status: 'invalid', reason: 'The HTTP message signature is malformed.' };
+    const { input, signature } = parsed;
+    if (!options.requiredComponents.every((component) => hasComponent(input.components, component)))
+        return {
+            status: 'invalid',
+            reason: 'The signature does not cover the required request components.',
+        };
+    const now = Math.floor(Date.now() / 1000);
+    if (input.created > now || input.expires <= now || input.expires - input.created > options.maxAge)
+        return { status: 'invalid', reason: 'The signature is expired or has an invalid lifetime.' };
+    if (options.validate) {
+        const reason = options.validate(input, request);
+        if (reason)
+            return { status: 'invalid', reason };
+    }
+    let key;
+    try {
+        key = await options.keyResolver({
+            algorithm: input.algorithm,
+            keyId: input.keyId,
+            request,
+        });
+    }
+    catch {
+        return { status: 'unverified', reason: 'The public key could not be resolved.' };
+    }
+    if (!key)
+        return {
+            status: 'unverified',
+            reason: 'No public key is available for the signature key ID.',
+        };
+    if (!keySupportsAlgorithm(key, input.algorithm))
+        return {
+            status: 'invalid',
+            reason: 'The public key does not support the signature algorithm.',
+        };
+    if (options.validateKey) {
+        const reason = await options.validateKey(key, input, request);
+        if (reason)
+            return { status: 'invalid', reason };
+    }
+    let valid;
+    try {
+        valid = await crypto.subtle.verify(webCryptoAlgorithm(input.algorithm), key, toArrayBuffer(signature), toArrayBuffer(encode(signatureBase(request, input))));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { status: 'invalid', reason: 'The HTTP message signature is invalid.' };
+    try {
+        if (!(await Store.tryClaim(options.nonceStore, `${options.nonceNamespace}:${input.keyId}:${input.nonce}`, input.expires * 1000)))
+            return { status: 'invalid', reason: 'The signature nonce has already been used.' };
+    }
+    catch {
+        return { status: 'unverified', reason: 'Replay protection is unavailable.' };
+    }
+    return { status: 'verified', input };
+}
+function parse(request, expectedTag) {
+    const inputHeader = request.headers.get(AttestationHeaders.signatureInput);
+    const signatureHeader = request.headers.get(AttestationHeaders.signature);
+    if (!inputHeader && !signatureHeader)
+        return undefined;
+    if (!inputHeader || !signatureHeader)
+        return { reason: 'Signature-Input and Signature must both be provided.' };
+    let inputs;
+    let signatures;
+    try {
+        inputs = parseDictionary(inputHeader);
+        signatures = parseDictionary(signatureHeader);
+    }
+    catch {
+        return { reason: 'The HTTP message signature is malformed.' };
+    }
+    if (!haveSameKeys(inputs, signatures))
+        return { reason: 'Signature-Input and Signature do not contain the same labels.' };
+    const tags = new Set(typeof expectedTag === 'string' ? [expectedTag] : expectedTag);
+    for (const [label, entry] of inputs) {
+        if (!hasExpectedTag(entry, tags))
+            continue;
+        const input = toSignatureInput(label, entry);
+        if (!input)
+            return { reason: 'The HTTP message signature is malformed.' };
+        const signature = signatures.get(label);
+        if (!signature || isInnerList(signature) || !(signature[0] instanceof ArrayBuffer))
+            return { reason: 'No matching HTTP message signature was provided.' };
+        return { input, signature: new Uint8Array(signature[0]) };
+    }
+    return undefined;
+}
+function serializeInput(input) {
+    return serializeInnerList(toInnerList(input));
+}
+function toInnerList(input) {
+    const components = input.components.map((component) => [
+        component.id,
+        new Map(component.parameters),
+    ]);
+    return [components, new Map(input.parameters)];
+}
+function toSignatureInput(label, entry) {
+    const innerList = entry;
+    if (!isInnerList(innerList))
+        return undefined;
+    const [componentEntries, parameters] = innerList;
+    if (!componentEntries.length ||
+        !componentEntries.every(([component]) => typeof component === 'string'))
+        return undefined;
+    const components = componentEntries.map(([id, parameters]) => ({
+        id: id,
+        parameters,
+    }));
+    const created = parameters.get('created');
+    const expires = parameters.get('expires');
+    const algorithm = parameters.get('alg');
+    const keyId = parameters.get('keyid');
+    const nonce = parameters.get('nonce');
+    const tag = parameters.get('tag');
+    if (!isInteger(created) ||
+        !isInteger(expires) ||
+        !isSignatureAlgorithm(algorithm) ||
+        typeof keyId !== 'string' ||
+        typeof nonce !== 'string' ||
+        typeof tag !== 'string')
+        return undefined;
+    return {
+        algorithm,
+        components,
+        created,
+        expires,
+        keyId,
+        label,
+        nonce,
+        parameters,
+        tag,
+    };
+}
+function algorithmFromKey(key) {
+    for (const algorithm of Object.values(Algorithms))
+        if (keySupportsAlgorithm(key, algorithm))
+            return algorithm;
+    throw new TypeError('Request attestation requires an Ed25519 or RSA-PSS SHA-512 signing key.');
+}
+function isInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value);
+}
+function isSignatureAlgorithm(value) {
+    return typeof value === 'string' && Object.hasOwn(algorithmDescriptors, value);
+}
+function keySupportsAlgorithm(key, algorithm) {
+    const { hash, keyAlgorithm } = algorithmDescriptors[algorithm];
+    return (key.algorithm.name === keyAlgorithm &&
+        (!hash || key.algorithm.hash.name === hash));
+}
+function webCryptoAlgorithm(algorithm) {
+    return algorithmDescriptors[algorithm].webCryptoAlgorithm;
+}
+function signatureBase(request, input) {
+    const lines = input.components.map((component) => `${serializeComponent(component)}: ${componentValue(request, component)}`);
+    lines.push(`"${Constants.components.signatureParams}": ${serializeInput(input)}`);
+    return lines.join('\n');
+}
+function componentValue(request, component) {
+    const url = new URL(request.url);
+    if (component.id === Constants.components.authority) {
+        if (component.parameters?.size)
+            throw new Error('Unsupported parameters for "@authority".');
+        return url.host;
+    }
+    if (component.id === Constants.components.path) {
+        if (component.parameters?.size)
+            throw new Error('Unsupported parameters for "@path".');
+        return url.pathname;
+    }
+    if (component.parameters?.size)
+        return componentDictionaryValue(request, component.id, component.parameters);
+    const value = request.headers.get(component.id);
+    if (value === null)
+        throw new Error(`Missing signed HTTP header "${component.id}".`);
+    // RFC 9421 signs the serialized field value, not a Unicode-normalized string.
+    if (!/^[\x20-\x7e]*$/.test(value))
+        throw new Error(`Signed HTTP header "${component.id}" is not ASCII.`);
+    return value;
+}
+function componentDictionaryValue(request, component, parameters) {
+    const key = parameters.get('key');
+    if (typeof key !== 'string' || parameters.size !== 1)
+        throw new Error(`Unsupported parameters for signed HTTP header "${component}".`);
+    const value = request.headers.get(component);
+    if (value === null)
+        throw new Error(`Missing signed HTTP header "${component}".`);
+    let dictionary;
+    try {
+        dictionary = parseDictionary(value);
+    }
+    catch {
+        throw new Error(`Signed HTTP header "${component}" is not a structured dictionary.`);
+    }
+    const member = dictionary.get(key);
+    if (!member || isInnerList(member))
+        throw new Error(`Signed HTTP header "${component}" has no member "${key}".`);
+    return serializeItem(member);
+}
+function hasComponent(components, expected) {
+    return components.some((component) => component.id === expected);
+}
+function haveSameKeys(left, right) {
+    return left.size === right.size && [...left.keys()].every((key) => right.has(key));
+}
+function hasExpectedTag(entry, tags) {
+    const value = entry;
+    if (!isInnerList(value))
+        return false;
+    const tag = value[1].get('tag');
+    return typeof tag === 'string' && tags.has(tag);
+}
+function serializeComponent(component) {
+    return `"${component.id}"${component.parameters?.size ? serializeParameters(new Map(component.parameters)) : ''}`;
+}
+function toComponent(component) {
+    return typeof component === 'string'
+        ? { id: component }
+        : { id: component.id, parameters: component.parameters && new Map(component.parameters) };
+}
+function parseHeaderDictionary(headers, name) {
+    const value = headers.get(name);
+    if (!value)
+        return new Map();
+    try {
+        return parseDictionary(value);
+    }
+    catch {
+        throw new Error(`HTTP header "${name}" is not a structured dictionary.`);
+    }
+}
+function encode(value) {
+    return new TextEncoder().encode(value);
+}
+function toArrayBuffer(value) {
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+}
+//# sourceMappingURL=HttpMessageSignature.js.map

package/dist/attestation/internal/SigningContext.d.ts

@@ -0,0 +1,4 @@
+import type * as Types from '../Types.js';
+/** Creates the signing context for one outbound HTTP request attempt. */
+export declare function create(): Types.SigningContext;
+//# sourceMappingURL=SigningContext.d.ts.map

package/dist/attestation/internal/SigningContext.js

@@ -0,0 +1,11 @@
+import { Base64 } from 'ox';
+/** Creates the signing context for one outbound HTTP request attempt. */
+export function create() {
+    const bytes = new Uint8Array(64);
+    crypto.getRandomValues(bytes);
+    return Object.freeze({
+        created: Math.floor(Date.now() / 1_000),
+        nonce: Base64.fromBytes(bytes, { pad: false, url: true }),
+    });
+}
+//# sourceMappingURL=SigningContext.js.map

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import cli from './cli/cli.js';
-await cli.serve();
-//# sourceMappingURL=bin.js.map
+import cli from './cli/cli.js'
+
+await cli.serve()