Merge pull request #172 from kjartan221/@bsv/auth-update

sirdeggen · web-flow · commit 90e98e1b83d2 · 2026-06-10T10:27:50.000-05:00
feat(auth): bind request payloads into auth proofs
diff --git a/packages/middleware/auth/jest.config.js b/packages/middleware/auth/jest.config.js
@@ -3,6 +3,8 @@ module.exports = {
   testEnvironment: 'node',
   roots: ['<rootDir>/src'],
   testMatch: ['**/__tests__/**/*.test.ts'],
+  // Perf benchmark is opt-in via `npm run test:perf`; keep it out of the default run.
+  testPathIgnorePatterns: ['/node_modules/', String.raw`\.perf\.test\.ts$`],
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   moduleNameMapper: {
     '^(\\.{1,2}/.*)\\.js$': '$1',
diff --git a/packages/middleware/auth/jest.perf.config.js b/packages/middleware/auth/jest.perf.config.js
@@ -0,0 +1,8 @@
+const base = require('./jest.config');
+
+// Runs ONLY the perf benchmark (which the default `jest` run excludes).
+module.exports = {
+  ...base,
+  testMatch: ['**/__tests__/**/*.perf.test.ts'],
+  testPathIgnorePatterns: ['/node_modules/'],
+};
diff --git a/packages/middleware/auth/package.json b/packages/middleware/auth/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bsv/auth",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Signed, expiry-bound, single-use wallet auth proofs for BSV apps.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,6 +25,7 @@
     "lint:ci-disabled": "ts-standard src/**/*.ts",
     "lint": "ts-standard --fix src/**/*.ts",
     "test:watch": "jest --watch",
+    "test:perf": "jest --config jest.perf.config.js --runInBand",
     "test:coverage-disabled": "jest --coverage",
     "build": "tsup && tsc --emitDeclarationOnly"
   },
diff --git a/packages/middleware/auth/src/__tests__/authProof.perf.test.ts b/packages/middleware/auth/src/__tests__/authProof.perf.test.ts
@@ -0,0 +1,109 @@
+import { performance } from 'node:perf_hooks';
+import {
+  createAuthProof,
+  verifyAuthProof,
+  serializeSignablePayload,
+  normalizeBody,
+  createAuthSigData,
+} from '../core.js';
+import { ProtoWallet, PrivateKey, type WalletProtocol } from '@bsv/sdk';
+
+// Local micro-benchmark — NOT a pass/fail SLA. It logs avg/throughput and asserts
+// only very loose ceilings, to catch catastrophic regressions (e.g. an accidental
+// O(n) blow-up), never normal machine variance. Run with `npm run test:perf`; tune
+// the crypto iteration count with the PERF_ITER env var (default 50).
+const ITER = Math.max(1, Number(process.env.PERF_ITER ?? 50));
+const PURE_ITER = 20_000;
+const WARMUP = Math.min(5, ITER);
+
+// Large window so pre-minted proofs never expire mid-run, even at a high PERF_ITER.
+const OPTIONS = { protocol: [2, 'perf auth'] as WalletProtocol, windowMs: 10 * 60 * 1000 };
+const BODY = { newUsername: 'alice', bio: 'x'.repeat(256) };
+
+interface Stats { label: string; n: number; avgMs: number; minMs: number; maxMs: number; opsPerSec: number; }
+
+function summarize(label: string, samples: number[]): Stats {
+  const total = samples.reduce((a, b) => a + b, 0);
+  const avgMs = total / samples.length;
+  return { label, n: samples.length, avgMs, minMs: Math.min(...samples), maxMs: Math.max(...samples), opsPerSec: 1000 / avgMs };
+}
+
+// Slow (crypto) ops: sample each call so we get a meaningful min/max/avg.
+async function benchAsync(label: string, n: number, fn: (i: number) => Promise<unknown>): Promise<Stats> {
+  for (let i = 0; i < WARMUP; i++) await fn(i);
+  const samples: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const t0 = performance.now();
+    await fn(i);
+    samples.push(performance.now() - t0);
+  }
+  return summarize(label, samples);
+}
+
+// Fast (pure) ops: time the whole batch — per-call timer overhead would dwarf them.
+function benchSyncBatch(label: string, n: number, fn: (i: number) => unknown): Stats {
+  for (let i = 0; i < WARMUP; i++) fn(i);
+  const t0 = performance.now();
+  for (let i = 0; i < n; i++) fn(i);
+  const avgMs = (performance.now() - t0) / n;
+  return { label, n, avgMs, minMs: avgMs, maxMs: avgMs, opsPerSec: 1000 / avgMs };
+}
+
+function report(s: Stats): void {
+  const ops = Math.round(s.opsPerSec).toLocaleString();
+  // eslint-disable-next-line no-console
+  console.log(
+    `[perf] ${s.label.padEnd(32)} ${String(s.n).padStart(6)}x   ` +
+    `avg ${s.avgMs.toFixed(4)}ms   min ${s.minMs.toFixed(4)}   max ${s.maxMs.toFixed(4)}   ${ops} ops/s`,
+  );
+}
+
+describe('performance (local benchmark — `npm run test:perf`, PERF_ITER to scale)', () => {
+  let clientWallet: ProtoWallet;
+  let serverWallet: ProtoWallet;
+  let serverKey: string;
+  const consumeOk = (): boolean => true;
+
+  beforeAll(async () => {
+    clientWallet = new ProtoWallet(PrivateKey.fromRandom());
+    serverWallet = new ProtoWallet(PrivateKey.fromRandom());
+    serverKey = (await serverWallet.getPublicKey({ identityKey: true })).publicKey;
+  });
+
+  it(`createAuthProof — bodyless vs body-bound (${ITER}x)`, async () => {
+    const login = await benchAsync('createAuthProof (login)', ITER, () =>
+      createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'login', ...OPTIONS }));
+    const body = await benchAsync('createAuthProof (body)', ITER, () =>
+      createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'update', body: BODY, ...OPTIONS }));
+    report(login);
+    report(body);
+    expect(login.avgMs).toBeLessThan(500);
+    expect(body.avgMs).toBeLessThan(500);
+  }, 120_000);
+
+  it(`verifyAuthProof — bodyless vs body-bound (${ITER}x)`, async () => {
+    const loginProofs = await Promise.all(Array.from({ length: ITER }, async () =>
+      createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'login', ...OPTIONS })));
+    const bodyProofs = await Promise.all(Array.from({ length: ITER }, async () =>
+      createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'update', body: BODY, ...OPTIONS })));
+
+    const vLogin = await benchAsync('verifyAuthProof (login)', ITER, (i) =>
+      verifyAuthProof({ wallet: serverWallet, proof: loginProofs[i], action: 'login', consumeNonce: consumeOk, ...OPTIONS }));
+    const vBody = await benchAsync('verifyAuthProof (body)', ITER, (i) =>
+      verifyAuthProof({ wallet: serverWallet, proof: bodyProofs[i], action: 'update', consumeNonce: consumeOk, body: BODY, ...OPTIONS }));
+    report(vLogin);
+    report(vBody);
+    expect(vLogin.avgMs).toBeLessThan(500);
+    expect(vBody.avgMs).toBeLessThan(500);
+  }, 120_000);
+
+  it(`pure serialization, no crypto (${PURE_ITER}x) — should dwarf the crypto path`, () => {
+    const data = createAuthSigData('login', '02abc', OPTIONS);
+    const ser = benchSyncBatch('serializeSignablePayload(body)', PURE_ITER, () => serializeSignablePayload(data, BODY));
+    const norm = benchSyncBatch('normalizeBody(object)', PURE_ITER, () => normalizeBody(BODY));
+    report(ser);
+    report(norm);
+    expect(ser.avgMs).toBeLessThan(1);
+    expect(norm.avgMs).toBeLessThan(1);
+  });
+});
diff --git a/packages/middleware/auth/src/__tests__/authProof.test.ts b/packages/middleware/auth/src/__tests__/authProof.test.ts
@@ -1,7 +1,14 @@
 import { AuthProofClient, AuthProofServer } from '../auth.js';
-import { serializeAuthSigData, createAuthSigData } from '../core.js';
+import {
+  serializeAuthSigData,
+  serializeSignablePayload,
+  normalizeBody,
+  createAuthSigData,
+  createAuthProof,
+  verifyAuthProof,
+} from '../core.js';
 import type { AuthProof, AuthSigData } from '../types.js';
-import { Utils, type WalletProtocol } from '@bsv/sdk';
+import { Utils, ProtoWallet, PrivateKey, type WalletProtocol } from '@bsv/sdk';
 
 const NOW = 1_700_000_000_000;
 const WINDOW = 2 * 60 * 1000;
@@ -78,45 +85,150 @@ describe('AuthProofServer.verifyAuthProof', () => {
 
   it('accepts a valid, fresh, unused proof and returns the identity key', async () => {
     const wallet = okWallet();
-    const result = await server.verifyAuthProof(wallet, proof(), 'login', { now: NOW, consumeNonce: consumeOk });
+    const result = await server.verifyAuthProof({ wallet, proof: proof(), action: 'login', now: NOW, consumeNonce: consumeOk });
     expect(result).toEqual({ valid: true, identityKey: IDENTITY });
     expect(wallet.verifySignature).toHaveBeenCalledTimes(1);
   });
 
   it('rejects malformed / action mismatch / expired before the signature check', async () => {
     const wallet = okWallet();
-    expect((await server.verifyAuthProof(wallet, { data: undefined, signature: [] } as unknown as AuthProof, 'login', { now: NOW, consumeNonce: consumeOk })).error).toBe('Malformed proof');
-    expect((await server.verifyAuthProof(wallet, proof(), 'delete', { now: NOW, consumeNonce: consumeOk })).error).toBe('Action mismatch');
-    expect((await server.verifyAuthProof(wallet, proof({ expiresAt: NOW - 1 }), 'login', { now: NOW, consumeNonce: consumeOk })).error).toBe('Proof expired');
+    expect((await server.verifyAuthProof({ wallet, proof: { data: undefined, signature: [] } as unknown as AuthProof, action: 'login', now: NOW, consumeNonce: consumeOk })).error).toBe('Malformed proof');
+    expect((await server.verifyAuthProof({ wallet, proof: proof(), action: 'delete', now: NOW, consumeNonce: consumeOk })).error).toBe('Action mismatch');
+    expect((await server.verifyAuthProof({ wallet, proof: proof({ expiresAt: NOW - 1 }), action: 'login', now: NOW, consumeNonce: consumeOk })).error).toBe('Proof expired');
     expect(wallet.verifySignature).not.toHaveBeenCalled();
   });
 
   it('rejects an invalid signature without consuming the nonce', async () => {
     const wallet = { verifySignature: jest.fn(async () => ({ valid: false })) };
     const consume = jest.fn(async () => true);
-    const result = await server.verifyAuthProof(wallet, proof(), 'login', { now: NOW, consumeNonce: consume });
+    const result = await server.verifyAuthProof({ wallet, proof: proof(), action: 'login', now: NOW, consumeNonce: consume });
     expect(result.error).toBe('Invalid signature');
     expect(consume).not.toHaveBeenCalled();
   });
 
   it('treats a throwing verifySignature as invalid (e.g. malformed identityKey) and does not consume', async () => {
     const wallet = { verifySignature: jest.fn(async () => { throw new Error('bad public key'); }) };
     const consume = jest.fn(async () => true);
-    const result = await server.verifyAuthProof(wallet, proof(), 'login', { now: NOW, consumeNonce: consume });
+    const result = await server.verifyAuthProof({ wallet, proof: proof(), action: 'login', now: NOW, consumeNonce: consume });
     expect(result.error).toBe('Invalid signature');
     expect(consume).not.toHaveBeenCalled();
   });
 
   it('rejects a replayed proof (nonce already consumed)', async () => {
-    const result = await server.verifyAuthProof(okWallet(), proof(), 'login', { now: NOW, consumeNonce: () => false });
+    const result = await server.verifyAuthProof({ wallet: okWallet(), proof: proof(), action: 'login', now: NOW, consumeNonce: () => false });
     expect(result.error).toBe('Proof already used');
   });
 
   it('verifies the signature against the proof identity key and nonce', async () => {
     const wallet = okWallet();
-    await server.verifyAuthProof(wallet, proof(), 'login', { now: NOW, consumeNonce: consumeOk });
+    await server.verifyAuthProof({ wallet, proof: proof(), action: 'login', now: NOW, consumeNonce: consumeOk });
     expect(wallet.verifySignature).toHaveBeenCalledWith(
       expect.objectContaining({ counterparty: IDENTITY, keyID: 'cmFuZG9tbm9uY2U=' }),
     );
   });
 });
+
+describe('normalizeBody', () => {
+  it('UTF-8 encodes strings', () => {
+    expect(normalizeBody('hi')).toEqual(Utils.toArray('hi', 'utf8'));
+  });
+
+  it('reads ArrayBuffer and typed arrays as raw bytes', () => {
+    const u8 = new Uint8Array([9, 8, 7]);
+    expect(normalizeBody(u8)).toEqual([9, 8, 7]);
+    expect(normalizeBody(u8.buffer)).toEqual([9, 8, 7]);
+  });
+
+  it('respects a typed-array view offset and length', () => {
+    const view = new Uint8Array(new Uint8Array([1, 2, 3, 4, 5]).buffer, 1, 3);
+    expect(normalizeBody(view)).toEqual([2, 3, 4]);
+  });
+
+  it('JSON-encodes plain objects', () => {
+    expect(normalizeBody({ a: 1 })).toEqual(Utils.toArray('{"a":1}', 'utf8'));
+  });
+
+  it('JSON-encodes arrays (params, objects, numbers) rather than treating them as bytes', () => {
+    expect(normalizeBody(['a=1', 'b=2'])).toEqual(Utils.toArray('["a=1","b=2"]', 'utf8'));
+    expect(normalizeBody([{ id: 1 }])).toEqual(Utils.toArray('[{"id":1}]', 'utf8'));
+    expect(normalizeBody([1, 2, 3])).toEqual(Utils.toArray('[1,2,3]', 'utf8'));
+  });
+});
+
+describe('serializeSignablePayload (body binding)', () => {
+  it('with no body equals serializeAuthSigData, so login proofs are unchanged', () => {
+    expect(serializeSignablePayload(sigData())).toEqual(serializeAuthSigData(sigData()));
+  });
+
+  it('binding a body changes the signed bytes and is body-sensitive', () => {
+    const base = JSON.stringify(serializeSignablePayload(sigData(), { user: 'alice' }));
+    expect(base).not.toBe(JSON.stringify(serializeAuthSigData(sigData())));
+    expect(JSON.stringify(serializeSignablePayload(sigData(), { user: 'alice' }))).toBe(base);
+    expect(JSON.stringify(serializeSignablePayload(sigData(), { user: 'bob' }))).not.toBe(base);
+  });
+
+  it('distinguishes an empty body from no body', () => {
+    expect(serializeSignablePayload(sigData(), '')).not.toEqual(serializeSignablePayload(sigData()));
+  });
+
+  it('treats a JSON string and the equivalent object identically', () => {
+    expect(serializeSignablePayload(sigData(), '{"user":"a"}'))
+      .toEqual(serializeSignablePayload(sigData(), { user: 'a' }));
+  });
+});
+
+describe('round-trip with real wallets (createAuthProof → verifyAuthProof)', () => {
+  const OPTS = OPTIONS;
+  const consumeOk = () => true;
+  let clientWallet: ProtoWallet;
+  let serverWallet: ProtoWallet;
+  let serverKey: string;
+  let clientKey: string;
+
+  beforeAll(async () => {
+    clientWallet = new ProtoWallet(PrivateKey.fromRandom());
+    serverWallet = new ProtoWallet(PrivateKey.fromRandom());
+    serverKey = (await serverWallet.getPublicKey({ identityKey: true })).publicKey;
+    clientKey = (await clientWallet.getPublicKey({ identityKey: true })).publicKey;
+  });
+
+  it('verifies a bodyless (login) proof', async () => {
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'login', ...OPTS });
+    const r = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'login', consumeNonce: consumeOk, ...OPTS });
+    expect(r).toEqual({ valid: true, identityKey: clientKey });
+  });
+
+  it('verifies a body-bound request when given the same body', async () => {
+    const body = { newUsername: 'alice' };
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'changeUsername', body, ...OPTS });
+    const r = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'changeUsername', consumeNonce: consumeOk, body, ...OPTS });
+    expect(r).toEqual({ valid: true, identityKey: clientKey });
+  });
+
+  it('rejects a tampered body', async () => {
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'changeUsername', body: { newUsername: 'alice' }, ...OPTS });
+    const r = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'changeUsername', consumeNonce: consumeOk, body: { newUsername: 'bob' }, ...OPTS });
+    expect(r.valid).toBe(false);
+    expect(r.error).toBe('Invalid signature');
+  });
+
+  it('rejects a body-bound proof verified without the body', async () => {
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'changeUsername', body: { newUsername: 'alice' }, ...OPTS });
+    const r = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'changeUsername', consumeNonce: consumeOk, ...OPTS });
+    expect(r.valid).toBe(false);
+  });
+
+  it('rejects a bodyless proof verified with an injected body', async () => {
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'login', ...OPTS });
+    const r = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'login', consumeNonce: consumeOk, body: { x: 1 }, ...OPTS });
+    expect(r.valid).toBe(false);
+  });
+
+  it('binds a binary body (typed array) without corruption', async () => {
+    const p = await createAuthProof({ wallet: clientWallet, counterparty: serverKey, action: 'upload', body: new Uint8Array([0, 255, 10, 13, 200, 1]), ...OPTS });
+    const ok = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'upload', consumeNonce: consumeOk, body: new Uint8Array([0, 255, 10, 13, 200, 1]), ...OPTS });
+    expect(ok.valid).toBe(true);
+    const bad = await verifyAuthProof({ wallet: serverWallet, proof: p, action: 'upload', consumeNonce: consumeOk, body: new Uint8Array([0, 255, 10, 13, 200, 2]), ...OPTS });
+    expect(bad.valid).toBe(false);
+  });
+});
diff --git a/packages/middleware/auth/src/auth.ts b/packages/middleware/auth/src/auth.ts
@@ -12,6 +12,7 @@ import type {
   ConsumeNonce,
   ProofSignerWallet,
   ProofVerifierWallet,
+  RequestBody,
   VerifyAuthProofResult,
 } from './types.js';
 
@@ -22,8 +23,10 @@ import type {
 export class AuthProofClient {
   constructor(private readonly options: AuthProofOptions = {}) {}
 
-  createAuthProof(wallet: ProofSignerWallet, counterparty: string, action: string): Promise<AuthProof> {
-    return createAuthProof(wallet, counterparty, action, this.options);
+  createAuthProof(
+    args: { wallet: ProofSignerWallet; counterparty: string; action: string; body?: RequestBody },
+  ): Promise<AuthProof> {
+    return createAuthProof({ ...args, ...this.options });
   }
 
   createAuthSigData(action: string, identityKey: string, now?: number): AuthSigData {
@@ -44,12 +47,16 @@ export class AuthProofServer {
   constructor(private readonly options: AuthProofOptions = {}) {}
 
   verifyAuthProof(
-    wallet: ProofVerifierWallet,
-    proof: AuthProof | undefined | null,
-    expectedAction: string,
-    deps: { consumeNonce: ConsumeNonce; now?: number },
+    args: {
+      wallet: ProofVerifierWallet;
+      proof: AuthProof | undefined | null;
+      action: string;
+      consumeNonce: ConsumeNonce;
+      now?: number;
+      body?: RequestBody;
+    },
   ): Promise<VerifyAuthProofResult> {
-    return verifyAuthProof(wallet, proof, expectedAction, deps, this.options);
+    return verifyAuthProof({ ...args, ...this.options });
   }
 
   checkAuthSigData(
diff --git a/packages/middleware/auth/src/core.ts b/packages/middleware/auth/src/core.ts
diff --git a/packages/middleware/auth/src/index.ts b/packages/middleware/auth/src/index.ts
diff --git a/packages/middleware/auth/src/types.ts b/packages/middleware/auth/src/types.ts
