Skip to content

Latest commit

 

History

History
228 lines (163 loc) · 13 KB

0104.md

File metadata and controls

228 lines (163 loc) · 13 KB

BRC-104: HTTP Transport for BRC-103 Mutual Authentication

1. Abstract

This specification defines how to transport BRC-103 [1] mutual authentication messages via HTTP. It introduces:

  • A .well-known/auth endpoint for non-general BRC-103 messages (e.g. handshake, certificate requests).
  • A mechanism for embedding “general” messages in normal HTTP requests/responses using custom x-bsv-auth headers and an encoded request/response “payload.”
  • Clear rules for which HTTP headers are included in the signature and which are excluded, ensuring consistent signing and verification on both client and server.
  • An approach for referencing the remote peer’s identity key and session parameters in standard HTTP requests/responses.

By adopting this scheme, implementers can re-use BRC-103’s cryptographic handshake and selective certificate exchange logic in a typical browser–server or server–server HTTP environment.

2. Introduction

BRC-103 [1] defines a peer-to-peer mutual authentication flow but leaves the transport unspecified. This document describes an HTTP layering for that flow. It details:

  • Endpoints and message paths for BRC-103 handshake messages.
  • A scheme for “general” messages that carry an entire HTTP request/response inside a single BRC-103 message.
  • Custom HTTP headers that store BRC-103 parameters (nonces, signatures, identity keys, requested certificates, etc.).
  • Mechanisms to handle typical web scenarios such as 402 Payment Required or other status codes.

Where BRC-103 gives a general outline (initialRequest, initialResponse, general, certificateRequest, certificateResponse), BRC-104 explains how those messages appear as HTTP requests and HTTP responses.

3. Relationship to BRC-103

  • Mandatory Prerequisite: Implementers MUST implement or rely on BRC-103’s handshake, message types, and signature logic.
  • This specification extends BRC-103 by mapping each BRC-103 message type onto HTTP requests and responses, describing /.well-known/auth usage, specialized headers (x-bsv-auth-*), and the structured “payload” approach for general messages.

Whenever conflicts arise, BRC-103 is authoritative on handshake semantics and certificate exchange. BRC-104 only clarifies how to wrap those messages in HTTP.

4. Terminology & Definitions

  • BRC-103 Message: One of initialRequest, initialResponse, certificateRequest, certificateResponse, or general.
  • Non-General Message: A BRC-103 message of type initialRequest, initialResponse, certificateRequest, or certificateResponse.
  • General Message: A BRC-103 message of type general, used to transmit an entire HTTP request or response under the authenticated session.
  • Peer: A user agent (client) or server implementing the protocol.
  • x-bsv-auth- Headers: A family of custom HTTP headers that store BRC-103 parameters (identity key, nonce, signature, etc.).
  • x-bsv-payment Header: An optional header used for embedding BSV payment data (e.g. 402 flows).
  • .well-known/auth Endpoint: The canonical path for sending non-general messages as JSON in a POST body.

5. High-Level Overview

  1. Non-General BRC-103 messages (initialRequest, initialResponse, certificateRequest, certificateResponse) are sent as:
    • HTTP POST to /.well-known/auth, with a JSON-serialized AuthMessage in the request body.
    • The server processes it, possibly returning an AuthMessage in JSON.
  2. General BRC-103 messages are carried by a normal HTTP request to any path (e.g., /api/v1/orders), but encoded within custom headers plus a raw binary “payload.”
  3. The server intercepts that request, reconstructs the “general” BRC-103 message, verifies signatures, and eventually returns a corresponding “general” BRC-103 response.

This layering effectively merges the BRC-103 handshake and certificate logic with standard HTTP request/response cycles.

6. Detailed Specification

6.1 HTTP Endpoints

MUST define at least one endpoint:

  • POST /.well-known/auth
    • Accepts a JSON body representing a BRC-103 AuthMessage (any non-general type).
    • The server verifies the BRC-103 signature. On success, it MAY respond with another non-general BRC-103 message as JSON (e.g. initialResponse or certificateResponse).
    • If the handshake is incomplete or invalid, the server responds with an HTTP 4xx.

Other resource endpoints (e.g. /myapp/orders) MAY handle general messages. The request body is an ordinary HTTP request body, while key BRC-103 fields (signature, identityKey, etc.) are placed in custom headers and an encoded “payload.”

6.2 Header Conventions

BRC-104 introduces the following headers:

  1. x-bsv-auth-version: The BRC-103 version string (e.g. "1.0").
  2. x-bsv-auth-identity-key: The sender’s public identity key (33-byte compressed secp256k1 pubkey, typically hex).
  3. x-bsv-auth-nonce & x-bsv-auth-your-nonce: 32-byte ephemeral nonces used in BRC-103’s handshake.
  4. x-bsv-auth-signature: ECDSA signature in hex, verifying the message.
  5. x-bsv-auth-request-id: A client-generated 32-byte random ID (base64) to correlate request/response pairs in “general” messages.
  6. x-bsv-auth-message-type: (Optional) The BRC-103 message type if returning a certificateRequest or certificateResponse via HTTP.
  7. x-bsv-auth-requested-certificates: (Optional) JSON-encoded RequestedCertificateSet for certificate requests.

x-bsv-auth- headers MUST be excluded from the set of user-signed headers. They are ephemeral parameters or are used for BRC-103 signature itself.

6.3 Signed Fields & Excluded Fields

When building a “general” message, the BRC-103 specification requires a signature across certain fields. In BRC-104:

  • Included in signature:

    • Request method (GET, POST, etc.).
    • Request path and query string.
    • “Whitelisted” headers only:
      • authorization (client and server)
      • content-type (client-only)
      • Any header with prefix x-bsv- except x-bsv-auth-...
    • Request body bytes.

  • Excluded:

    • Non-whitelisted headers (like x-bsv-auth-*, accept)
    • Cookies, user-agent, etc.

Servers do not sign content-type because certain server middleware tends to modify the content-type header. For example, express appends charset=utf-8 to the content-type resulting in ambiguity over the pre-image being signed.

Clients however do not generally modify the content-type header in requests which allows it to be included in the pre-image being signed.

The order of included headers will be lexicographical to ensure matching preimages on both sides.

6.4 Request/Response Flow for “General” Messages

Client perspective:

  1. Construct an HTTP request as usual, but store the entire method, path, query, selected headers, and body inside a “payload” field in the BRC-103 general message.
  2. The BRC-103 identity key, version, nonce, etc., go into x-bsv-auth-* headers.
  3. Send the request over standard HTTP.
  4. The server verifies authenticity, processes the request, and returns a BRC-103 “general” message in the response:
    • The server includes x-bsv-auth-version, x-bsv-auth-signature, x-bsv-auth-identity-key, etc.
    • The actual response status code, headers, and body are re-encoded as a “payload.”

Server perspective:

  1. On receiving the request, parse the x-bsv-auth-* headers (nonce, signature, identityKey, etc.).
  2. Construct the “general” BRC-103 message from the payload.
  3. If signature checks pass, handle the HTTP request in memory (similar to a normal route).
  4. Instead of sending the result directly to the wire, embed your final status code, headers, and body in a new “general” BRC-103 message.
  5. Write it back in x-bsv-auth-* headers + the binary payload within the same HTTP response.

6.5 Request/Response Flow for “Non-General” Messages

Non-general BRC-103 messages—like initialRequest, initialResponse, certificateRequest, certificateResponse—MUST be exchanged via:

  1. POST /.well-known/auth, with a JSON body: 
    {
  "version": "1.0",
  "messageType": "initialRequest",
  "identityKey": "...",
  "initialNonce": "...",
  "signature": "...",
  ...
}
  2. The server decodes the AuthMessage, verifies it, and possibly replies with another AuthMessage in JSON form: 
    {
  "version": "1.0",
  "messageType": "initialResponse",
  "identityKey": "...",
  "nonce": "...",
  "yourNonce": "...",
  "signature": "...",
  ...
}
  3. On success, the client merges that result into the BRC-103 session state.

6.6 Authentication Failure Handling

  • If the handshake or signature fails, the server MUST return 401 Unauthorized (or another 4xx suitable code) with a JSON body describing the error.
  • If the user sets invalid data, the server MAY respond with 400 Bad Request.

6.7 Body Encoding Rules

When sending a “general” message:

  • The body is included raw in the BRC-103 payload, but only after a length prefix.
  • If content-type is application/json, you typically convert your JSON object to UTF-8 bytes.
  • If it is binary data (e.g. images), you pass the binary as bytes.
  • If no body, specify a -1 length in the payload.

The same approach is used for the server’s return body in the “general” response message.

6.8 Signature Preimage Calculation for HTTP Request Messages

The code references BRC-103’s standard approach: concatenating these fields in a stable order:

  1. x-bsv-auth-request-id (32 bytes, base64-decoded).
  2. Request method length + UTF-8 bytes.
  3. Path length + UTF-8 bytes (or -1 if empty).
  4. Query string length + UTF-8 bytes (or -1 if none).
  5. Included headers count, given in order of transmittal over the wire. For each header:
    • VarInt of key length, key bytes
    • VarInt of value length, value bytes
  6. Body length + body bytes (or -1 if none).

Then sign with the identity key. The server reconstructs that same preimage from the request data, verifying the signature in x-bsv-auth-signature.

6.9 Signature Preimage Calculation for HTTP Response Messages

In response to client request the server creates a BRC-103 payload as follows:

  1. x-bsv-auth-request-id (echoing back the client's requestId as seen on line 174).
  2. Response status (varInt)
  3. Included headers count, given in order of transmittal over the wire. For each header:
    • VarInt of key length, key bytes
    • VarInt of value length, value bytes
  4. Body length + body bytes (or -1 if none).

7. Implementation Notes & Examples

7.1 Client-Side Example

A reference “client” does the following:

  • When sending a non-general message (e.g. handshake, certificate request), it:
    1. Performs POST /.well-known/auth with Content-Type: application/json.
    2. Embeds the entire AuthMessage (BRC-103 structure) in JSON.
  • When sending a general message:
    1. Serializes method, path, query, whitelisted headers, and body into a BRC-103 payload.
    2. Supplies x-bsv-auth-version, x-bsv-auth-identity-key, x-bsv-auth-nonce, x-bsv-auth-your-nonce (if applicable), x-bsv-auth-signature, and x-bsv-auth-request-id in the request headers.
    3. On receiving the server’s HTTP response, decodes those same fields from the response headers, building a BRC-103 message that includes the returned status code, headers, and body as a “payload.”

7.2 Server-Side Example

  1. Intercept POST /.well-known/auth requests, parse them as JSON, treat them as BRC-103 “non-general.”
  2. For other paths, it checks for x-bsv-auth-request-id to see if it’s a “general” message.
  3. It re-routes the normal Express request logic so that instead of returning data directly, the server packs the data into a BRC-103 “general” message and responds accordingly.

This approach ensures a typical server can remain mostly unmodified, while the middleware handles the signature verification and re-encoding of the final response.

8. Security Considerations

  • Replay Attacks: The nonce fields in BRC-103 ensure freshness. Servers MUST reject repeated nonces.
  • Header Injection: Only a fixed set of headers is signed. If malicious headers are injected, they are outside the signature scope. Implementers should sanitize or ignore unknown headers.
  • Transport Encryption: BRC-104 does not replace TLS. Implementers SHOULD still use HTTPS to hide private or sensitive information from eavesdroppers.
  • Certificate Revocation: If identity certificates are used, the logic for checking revocationOutpoints remains as in BRC-103.

References

  • BRC-103: Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol (provides handshake and message definitions).