Shade/packages/shade-transport-bridge/src/auth.ts

/**
 * Bridge auth primitive.
 *
 * SSE/EventSource cannot carry custom headers in browsers, so the bridge
 * protocol uses signed query parameters for every endpoint kind. The
 * signature is over the canonical `{address, kind, since, signedAt}` payload
 * using the recipient's Ed25519 signing key. The server looks up the owner
 * key for `address` (registered via `/v1/inbox/register`) and verifies the
 * signature with the same `verifyPayload` path used by the inbox.
 */

import type { CryptoProvider } from '@shade/core';
import { signPayload } from '@shade/server';

export type BridgeKind = 'stream' | 'poll' | 'ws';

export interface BridgeAuthInput {
  crypto: CryptoProvider;
  signingPrivateKey: Uint8Array;
  address: string;
  kind: BridgeKind;
  since: number;
}

/**
 * Returns the URLSearchParams that must be appended to the bridge URL
 * (`/v1/bridge/stream`, `/v1/bridge/poll`, `/v1/bridge/ws`). The same shape
 * is consumed by `verifyBridgeAuth` on the server side.
 */
export async function signBridgeQuery(input: BridgeAuthInput): Promise<URLSearchParams> {
  const signed = await signPayload(input.crypto, input.signingPrivateKey, {
    address: input.address,
    kind: input.kind,
    since: input.since,
  });
  const qs = new URLSearchParams();
  qs.set('address', input.address);
  qs.set('kind', input.kind);
  qs.set('since', String(input.since));
  qs.set('signedAt', String(signed.signedAt));
  qs.set('signature', signed.signature);
  return qs;
}

export function bridgeQueryToCanonical(qs: URLSearchParams): {
  address: string;
  kind: BridgeKind;
  since: number;
  signedAt: number;
  signature: string;
} | null {
  const address = qs.get('address');
  const kind = qs.get('kind') as BridgeKind | null;
  const sinceStr = qs.get('since');
  const signedAtStr = qs.get('signedAt');
  const signature = qs.get('signature');
  if (!address || !kind || sinceStr === null || !signedAtStr || !signature) return null;
  if (kind !== 'stream' && kind !== 'poll' && kind !== 'ws') return null;
  const since = Number(sinceStr);
  const signedAt = Number(signedAtStr);
  if (!Number.isFinite(since) || since < 0) return null;
  if (!Number.isFinite(signedAt)) return null;
  return { address, kind, since, signedAt, signature };
}

// ─── V4.7 — presence subscription auth ────────────────────────────

export interface PresenceAuthInput {
  crypto: CryptoProvider;
  signingPrivateKey: Uint8Array;
  /** The watcher's own address (signer of the request). */
  address: string;
  /** Addresses to subscribe presence updates for. May be empty. */
  watched: readonly string[];
}

/**
 * Build the signed query string for `GET /v1/bridge/presence`. The
 * `kind: 'presence'` field is bound into the canonical payload to
 * prevent cross-endpoint replay against `/v1/bridge/{stream,poll,ws}`.
 *
 * The `watched` array is sorted to give the signed bytes a canonical
 * order; the wire form encodes it as a single comma-separated
 * `watched=` parameter (address syntax disallows `,`).
 */
export async function signPresenceQuery(input: PresenceAuthInput): Promise<URLSearchParams> {
  const watched = [...input.watched].sort();
  const signed = await signPayload(input.crypto, input.signingPrivateKey, {
    address: input.address,
    kind: 'presence',
    watched,
  });
  const qs = new URLSearchParams();
  qs.set('address', input.address);
  qs.set('kind', 'presence');
  qs.set('watched', watched.join(','));
  qs.set('signedAt', String(signed.signedAt));
  qs.set('signature', signed.signature);
  return qs;
}