@did-btcr2/method 0.28.0 → 0.32.0

package/src/core/aggregation/transport/http/nonce-cache.ts

@@ -0,0 +1,43 @@
+export interface NonceCacheConfig {
+  /** Max distinct entries to retain before FIFO eviction. Default 10,000. */
+  maxEntries?: number;
+}
+
+/**
+ * Bounded anti-replay cache for `(did, nonce)` pairs.
+ *
+ * Replay windowing is the caller's responsibility — this cache only detects
+ * duplicates. Callers are expected to reject envelopes/headers whose timestamp
+ * is outside the clock-skew window *before* consulting the cache, so entries
+ * here are always within the protocol's acceptable window.
+ *
+ * Eviction is strict-FIFO (Map insertion order) once `maxEntries` is reached.
+ */
+export class NonceCache {
+  readonly #maxEntries: number;
+  readonly #entries = new Map<string, number>();
+
+  constructor(config: NonceCacheConfig = {}) {
+    this.#maxEntries = config.maxEntries ?? 10_000;
+  }
+
+  /**
+   * Record a nonce. Returns `true` if it was novel (caller should accept the
+   * request) or `false` if it was a replay (caller should reject).
+   */
+  store(did: string, nonce: string, timestampSec: number): boolean {
+    const key = `${did}:${nonce}`;
+    if(this.#entries.has(key)) return false;
+    this.#entries.set(key, timestampSec);
+    if(this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next();
+      if(!oldest.done) this.#entries.delete(oldest.value);
+    }
+    return true;
+  }
+
+  /** Current cache size. Exposed for observability and tests. */
+  size(): number {
+    return this.#entries.size;
+  }
+}

package/src/core/aggregation/transport/http/protocol.ts

@@ -0,0 +1,57 @@
+/**
+ * On-the-wire version of the HTTP transport envelope. Separate from
+ * {@link AGGREGATION_WIRE_VERSION} (which versions the aggregation protocol
+ * payloads) so transport-layer changes don't force a protocol bump.
+ */
+export const HTTP_ENVELOPE_VERSION = 1;
+
+/**
+ * HTTP routes served by {@link HttpServerTransport}. The `{did}` placeholder
+ * in {@link HTTP_ROUTE.ACTOR_INBOX} is substituted with a URL-safe DID at
+ * request time.
+ */
+export const HTTP_ROUTE = {
+  ADVERTS     : '/v1/adverts',
+  MESSAGES    : '/v1/messages',
+  ACTOR_INBOX : '/v1/actors/{did}/inbox',
+  WELL_KNOWN  : '/v1/.well-known/aggregation',
+} as const;
+
+/** Server-Sent Events event names used by the broadcast + inbox streams. */
+export const SSE_EVENT = {
+  ADVERT    : 'advert',
+  MESSAGE   : 'message',
+  HEARTBEAT : 'heartbeat',
+} as const;
+
+/** Default clock-skew tolerance for envelope timestamps (seconds). */
+export const DEFAULT_CLOCK_SKEW_SEC = 60;
+
+/** Default length of the per-envelope anti-replay nonce (bytes). */
+export const DEFAULT_NONCE_LEN_BYTES = 16;
+
+/**
+ * Tamper-evident wrapper around an aggregation {@link BaseMessage}. Every
+ * authenticated HTTP request and inbox SSE event carries one of these.
+ *
+ * The signature is BIP340 Schnorr over the SHA-256 of the JCS-canonicalized
+ * envelope **excluding** the `sig` field. Receivers reconstruct the same
+ * canonical form, verify the signature against the sender's registered
+ * communication public key, and reject outside-skew timestamps.
+ */
+export interface SignedEnvelope {
+  /** Envelope format version; must equal {@link HTTP_ENVELOPE_VERSION}. */
+  v: number;
+  /** Sender DID. */
+  from: string;
+  /** Recipient DID. Omitted for broadcasts (e.g. COHORT_ADVERT). */
+  to?: string;
+  /** Unix seconds at which the envelope was produced. */
+  timestamp: number;
+  /** Hex-encoded random nonce, {@link DEFAULT_NONCE_LEN_BYTES} bytes. */
+  nonce: string;
+  /** Aggregation message payload (plain-JSON form, `toJSON`-normalized). */
+  message: Record<string, unknown>;
+  /** Hex-encoded 64-byte BIP340 Schnorr signature. */
+  sig: string;
+}

package/src/core/aggregation/transport/http/rate-limiter.ts

@@ -0,0 +1,75 @@
+export interface BucketState {
+  tokens: number;
+  lastRefillMs: number;
+}
+
+/**
+ * Pluggable storage backend for rate-limit state. The default
+ * {@link InMemoryRateLimitStore} is a plain Map; swap in Redis-backed or
+ * SQLite-backed implementations for multi-instance deployments.
+ */
+export interface RateLimitStore {
+  get(key: string): BucketState | undefined;
+  set(key: string, state: BucketState): void;
+}
+
+export class InMemoryRateLimitStore implements RateLimitStore {
+  readonly #buckets = new Map<string, BucketState>();
+
+  get(key: string): BucketState | undefined {
+    return this.#buckets.get(key);
+  }
+
+  set(key: string, state: BucketState): void {
+    this.#buckets.set(key, state);
+  }
+}
+
+export interface RateLimiterConfig {
+  /** Steady-state request rate per key (requests per second). Default 10. */
+  rps?: number;
+  /** Peak burst allowance (bucket capacity). Default 30. */
+  burst?: number;
+  /** Optional pluggable store. Defaults to an in-memory Map. */
+  store?: RateLimitStore;
+}
+
+/**
+ * Token-bucket rate limiter keyed by an opaque string (typically a verified
+ * sender DID). Tokens refill linearly at `rps` up to `burst`. Each `consume`
+ * call atomically debits one token or returns `false` to reject.
+ *
+ * The limiter is synchronous and deterministic given `nowMs` — tests can
+ * drive it with a fixed clock to exercise exact boundaries.
+ */
+export class RateLimiter {
+  readonly #rps: number;
+  readonly #burst: number;
+  readonly #store: RateLimitStore;
+
+  constructor(config: RateLimiterConfig = {}) {
+    this.#rps   = config.rps   ?? 10;
+    this.#burst = config.burst ?? 30;
+    this.#store = config.store ?? new InMemoryRateLimitStore();
+  }
+
+  /** Consume one token for `key`. Returns `true` if accepted, `false` if throttled. */
+  consume(key: string, nowMs: number): boolean {
+    const existing = this.#store.get(key);
+    const state: BucketState = existing ?? { tokens: this.#burst, lastRefillMs: nowMs };
+
+    if(existing) {
+      const elapsedSec = Math.max(0, (nowMs - existing.lastRefillMs) / 1000);
+      state.tokens       = Math.min(this.#burst, existing.tokens + elapsedSec * this.#rps);
+      state.lastRefillMs = nowMs;
+    }
+
+    if(state.tokens < 1) {
+      this.#store.set(key, state);
+      return false;
+    }
+    state.tokens -= 1;
+    this.#store.set(key, state);
+    return true;
+  }
+}

package/src/core/aggregation/transport/http/request-auth.ts

@@ -0,0 +1,164 @@
+import { canonicalHashBytes } from '@did-btcr2/common';
+import type { CompressedSecp256k1PublicKey, SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
+
+import { HttpTransportError } from './errors.js';
+import { DEFAULT_CLOCK_SKEW_SEC, DEFAULT_NONCE_LEN_BYTES, HTTP_ENVELOPE_VERSION } from './protocol.js';
+
+/**
+ * `Authorization`-header scheme used to authenticate SSE subscription
+ * requests. The header value takes the form
+ * `BTCR2-Sig v=<n>,did=<did>,ts=<unix>,nonce=<hex>,sig=<hex>`.
+ *
+ * Used only for GET endpoints (SSE inbox subscribe). POST endpoints carry a
+ * full {@link SignedEnvelope} in the request body instead.
+ */
+export const REQUEST_AUTH_SCHEME = 'BTCR2-Sig';
+
+export interface ParsedRequestAuth {
+  /** Transport envelope format version. */
+  v: number;
+  /** Subscriber DID. */
+  did: string;
+  /** Unix-seconds timestamp. */
+  ts: number;
+  /** Hex-encoded anti-replay nonce. */
+  nonce: string;
+  /** Hex-encoded 64-byte BIP340 signature. */
+  sig: string;
+}
+
+export interface BuildRequestAuthOptions {
+  nonce?: string;
+  timestamp?: number;
+}
+
+/**
+ * Build an `Authorization` header value proving the caller controls the
+ * private key for `did`. Covers a specific request path so the signature
+ * can't be replayed against a different endpoint.
+ */
+export function buildRequestAuth(
+  did:  string,
+  keys: SchnorrKeyPair,
+  path: string,
+  opts: BuildRequestAuthOptions = {},
+): string {
+  const ts    = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  const nonce = opts.nonce ?? bytesToHex(randomBytes(DEFAULT_NONCE_LEN_BYTES));
+
+  const digest = canonicalHashBytes({
+    v : HTTP_ENVELOPE_VERSION,
+    did,
+    ts,
+    nonce,
+    path,
+  });
+  const sig = keys.secretKey.sign(digest, { scheme: 'schnorr' });
+
+  return `${REQUEST_AUTH_SCHEME} v=${HTTP_ENVELOPE_VERSION},did=${did},ts=${ts},nonce=${nonce},sig=${bytesToHex(sig)}`;
+}
+
+/**
+ * Parse a `BTCR2-Sig` auth header value into its structured fields. Does NOT
+ * verify the signature — call {@link verifyRequestAuth} for that.
+ */
+export function parseRequestAuth(headerValue: string): ParsedRequestAuth {
+  const prefix = `${REQUEST_AUTH_SCHEME} `;
+  if(!headerValue.startsWith(prefix)) {
+    throw new HttpTransportError(
+      `Unexpected auth scheme (want ${REQUEST_AUTH_SCHEME})`,
+      'REQUEST_AUTH_SCHEME',
+    );
+  }
+
+  const params: Record<string, string> = {};
+  for(const piece of headerValue.slice(prefix.length).split(',')) {
+    const eq = piece.indexOf('=');
+    if(eq === -1) continue;
+    const key = piece.slice(0, eq).trim();
+    const val = piece.slice(eq + 1).trim();
+    if(key.length > 0) params[key] = val;
+  }
+
+  const v  = Number(params.v);
+  const ts = Number(params.ts);
+  if(!Number.isInteger(v) || !Number.isInteger(ts) || !params.did || !params.nonce || !params.sig) {
+    throw new HttpTransportError(
+      'Malformed auth header (missing or invalid field)',
+      'REQUEST_AUTH_MALFORMED',
+      { received: Object.keys(params) },
+    );
+  }
+  return { v, did: params.did, ts, nonce: params.nonce, sig: params.sig };
+}
+
+export interface VerifyRequestAuthOptions {
+  clockSkewSec?: number;
+  now?: () => number;
+}
+
+/**
+ * Parse + verify an auth header. Throws {@link HttpTransportError} on any
+ * failure; returns the parsed fields on success.
+ *
+ * `expectedPath` must match the path the signature commits to. `senderPk`
+ * must correspond to the DID the signer claims.
+ */
+export function verifyRequestAuth(
+  headerValue:  string,
+  expectedPath: string,
+  senderPk:     CompressedSecp256k1PublicKey,
+  opts:         VerifyRequestAuthOptions = {},
+): ParsedRequestAuth {
+  const parsed = parseRequestAuth(headerValue);
+
+  if(parsed.v !== HTTP_ENVELOPE_VERSION) {
+    throw new HttpTransportError(
+      `Unsupported auth version: ${parsed.v}`,
+      'REQUEST_AUTH_VERSION_MISMATCH',
+      { version: parsed.v, expected: HTTP_ENVELOPE_VERSION },
+    );
+  }
+
+  const skewSec = opts.clockSkewSec ?? DEFAULT_CLOCK_SKEW_SEC;
+  const nowMs   = opts.now ? opts.now() : Date.now();
+  const nowSec  = Math.floor(nowMs / 1000);
+  const diff    = Math.abs(nowSec - parsed.ts);
+  if(diff > skewSec) {
+    throw new HttpTransportError(
+      `Auth timestamp out of skew: ${diff}s > ${skewSec}s`,
+      'REQUEST_AUTH_TIMESTAMP_SKEW',
+      { diff, skewSec },
+    );
+  }
+
+  let sigBytes: Uint8Array;
+  try {
+    sigBytes = hexToBytes(parsed.sig);
+  } catch {
+    throw new HttpTransportError('Auth signature is not valid hex', 'REQUEST_AUTH_SIG_HEX');
+  }
+  if(sigBytes.length !== 64) {
+    throw new HttpTransportError(
+      `Invalid auth signature length: ${sigBytes.length}`,
+      'REQUEST_AUTH_SIG_LENGTH',
+      { length: sigBytes.length },
+    );
+  }
+
+  const digest = canonicalHashBytes({
+    v     : parsed.v,
+    did   : parsed.did,
+    ts    : parsed.ts,
+    nonce : parsed.nonce,
+    path  : expectedPath,
+  });
+
+  const ok = senderPk.verify(sigBytes, digest, { scheme: 'schnorr' });
+  if(!ok) {
+    throw new HttpTransportError('Auth signature verification failed', 'REQUEST_AUTH_SIG_INVALID');
+  }
+
+  return parsed;
+}