Merge pull request #137 from ty-everett/codex/async-auth-session-managers

Add async auth session managers

Author: sirdeggen

docs/architecture/identity.md

@@ -51,9 +51,9 @@ Server response:
 
 Both parties emerge from the handshake having verified each other's identity keys. Subsequent requests in the same session use a session token derived from the initial handshake.
 
-`@bsv/auth-express-middleware` installs BRC-31 as Express middleware. Any route wrapped by it requires a valid BRC-31 handshake from the client.
+`@bsv/auth-express-middleware` installs BRC-103/BRC-104 as Express middleware. Any route wrapped by it requires a valid BRC-103 handshake from the client over the BRC-104 HTTP binding.
 
-The machine-readable spec is at `specs/auth/brc31-handshake.yaml` (AsyncAPI 3.0).
+The machine-readable spec is at `specs/auth/brc103-mutual-auth.yaml` (AsyncAPI 3.0).
 
 ## Identity Keys
 

docs/packages/middleware/auth-express-middleware.md

@@ -57,7 +57,7 @@ app.listen(3000)
 - **AuthRequest** — Extended Request with `.auth` object containing `identityKey`
 - **BRC-103 mutual authentication** — Nonce-based challenge-response with signatures
 - **BRC-104 HTTP transport** — Custom headers (`x-bsv-auth-*`) for non-general messages
-- **Session management** — Tracks nonces per identity; SessionManager interface extensible
+- **Session management** — Tracks nonces per identity; AsyncSessionManager interface extensible to synchronous or asynchronous stores
 - **Certificate exchange** — Optional verifiable certificates during handshake
 - **Response wrapping** — Middleware intercepts response methods to sign responses before sending
 - **Optional authentication** — `allowUnauthenticated` flag for mixed public/private endpoints
@@ -104,6 +104,19 @@ app.use(express.json())
 app.use(authMiddleware)
 ```
 
+### Shared sessions for scaled servers
+
+The default `SessionManager` stores BRC-103 nonce/session state in one process. For load-balanced Express servers, pass a `AsyncSessionManager` backed by shared storage so every instance can resolve the same handshake state instead of relying on sticky routing.
+
+```typescript
+import { AsyncSessionManager } from '@bsv/sdk'
+
+const authMiddleware = createAuthMiddleware({
+  wallet,
+  sessionManager: sharedSessionManager satisfies AsyncSessionManager
+})
+```
+
 ### Per-route protection
 
 ```typescript
@@ -118,7 +131,7 @@ app.post('/secure-endpoint', createAuthMiddleware({ wallet }), (req, res) => {
 - **BRC-104 HTTP transport** — Uses custom headers and `/.well-known/auth` endpoint
 - **General vs non-general messages** — Non-general for handshake, general for authenticated app requests
 - **Nonce binding** — Each request/response pair bound to server-generated nonce; prevents replay attacks
-- **Session management** — Tracks nonces per identity; SessionManager interface extensible
+- **Session management** — Tracks nonces per identity; AsyncSessionManager interface extensible to synchronous or asynchronous stores
 - **Certificate exchange** — Optional verifiable certificates during handshake
 - **Response wrapping** — Middleware intercepts response methods to sign responses before sending
 

docs/reference/brc-index.md

@@ -78,13 +78,13 @@ Implementations: `@bsv/paymail`, `@bsv/message-box-client`, `@bsv/402-pay`
 
 Conformance vectors: `conformance/vectors/wallet/brc29/`
 
-### BRC-31: HTTP Mutual Authentication Handshake
+### BRC-103 / BRC-104: Mutual Authentication Handshake + HTTP Transport
 
-Specifies the `x-bsv-auth-*` HTTP headers that implement mutual-auth challenge-response over standard HTTP. Built on the BRC-103 Peer framework.
+BRC-103 specifies the peer-to-peer mutual authentication protocol (AuthMessage envelope, nonces, certificates, sessions). BRC-104 binds it to HTTP via the `/.well-known/auth` endpoint and `x-bsv-auth-*` headers. Replaces the legacy BRC-31 identifier.
 
-Implementations: `@bsv/auth-express-middleware`, `@bsv/authsocket`
+Implementations: `@bsv/auth-express-middleware`, `@bsv/authsocket`, `@bsv/sdk` (`Peer`, `Transport`)
 
-Spec: `specs/auth/brc31-handshake.yaml`
+Spec: `specs/auth/brc103-mutual-auth.yaml`
 
 ### BRC-42: Key Derivation Scheme (BKDS)
 

docs/specs/brc-31-auth.md

@@ -186,4 +186,4 @@ BRC-31-related portable coverage currently lives in `conformance/vectors/messagi
 
 ## Spec artifact
 
-[brc31-handshake.yaml](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/auth/brc31-handshake.yaml)
+[brc103-mutual-auth.yaml](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/auth/brc103-mutual-auth.yaml)

packages/middleware/auth-express-middleware/API.md

@@ -9,7 +9,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export interface AuthMiddlewareOptions {
     wallet: WalletInterface;
-    sessionManager?: SessionManager;
+    sessionManager?: SessionManager | AsyncSessionManager;
     allowUnauthenticated?: boolean;
     certificatesToRequest?: RequestedCertificateSet;
     onCertificatesReceived?: (senderPublicKey: string, certs: VerifiableCertificate[], req: Request, res: Response, next: NextFunction) => void;

packages/middleware/auth-express-middleware/README.md

@@ -53,7 +53,7 @@ By layering **BRC-103** on top of Express, you can:
   Supports BRC-103’s concept of revealing only certain fields in a certificate, helping to preserve privacy for you and your users while verifying necessary information.
 
 - **Extendable**  
-  Provide a custom `SessionManager` or plug in advanced logic for verifying user attributes.
+  Provide a custom `AsyncSessionManager`, including asynchronous shared stores, or plug in advanced logic for verifying user attributes.
 
 ---
 
@@ -123,7 +123,7 @@ Use the factory function:
 createAuthMiddleware({
   wallet: myWallet, 
   allowUnauthenticated?: boolean,
-  sessionManager?: SessionManager,
+  sessionManager?: AsyncSessionManager,
   certificatesToRequest?: RequestedCertificateSet,
   onCertificatesReceived?: (senderPublicKey, certs, req, res, next) => void
 })
@@ -133,10 +133,49 @@ createAuthMiddleware({
 
 - **`wallet`** *(required)*: A wallet instance that implements signing and key management, typically from `@bsv/sdk` or your own custom build.  
 - **`allowUnauthenticated`** *(default: `false`)*: If `true`, requests without valid BRC-103 authentication will **not** be rejected. Instead, `req.auth.identityKey` is set to `"unknown"`.  
-- **`sessionManager`** *(optional)*: Customize session management (nonce tracking, etc.). By default, an internal `SessionManager` is used.  
+- **`sessionManager`** *(optional)*: Customize session management (nonce tracking, etc.). By default, an internal `SessionManager` is used. For horizontally scaled servers, pass a `AsyncSessionManager` backed by shared storage so every instance can resolve the same nonce/session state.
 - **`certificatesToRequest`** *(optional)*: A specification of which certificates (by type, fields, issuer) to request automatically from the peer.  
 - **`onCertificatesReceived`** *(optional)*: Callback invoked when the peer responds with **Verifiable Certificates**.
 
+### Horizontal Scaling
+
+The default `SessionManager` stores handshake state in memory. That is appropriate for one process, but a load-balanced deployment can route the initial nonce exchange, certificate request, and general message to different server instances. In that topology, provide a `AsyncSessionManager` backed by shared storage so nonce lookups are available to every instance:
+
+```ts
+import { PeerSession, AsyncSessionManager } from '@bsv/sdk'
+
+async function getSharedSession(identifier: string): Promise<PeerSession | undefined> {
+  const session = await store.get(`auth:nonce:${identifier}`)
+  if (session != null) return session
+
+  const nonce = await store.get(`auth:identity:${identifier}`)
+  return nonce == null ? undefined : await store.get(`auth:nonce:${nonce}`)
+}
+
+const sessionManager: AsyncSessionManager = {
+  async addSession(session: PeerSession) {
+    await store.set(`auth:nonce:${session.sessionNonce}`, session)
+    await store.set(`auth:identity:${session.peerIdentityKey}`, session.sessionNonce)
+  },
+  async updateSession(session: PeerSession) {
+    await store.set(`auth:nonce:${session.sessionNonce}`, session)
+    await store.set(`auth:identity:${session.peerIdentityKey}`, session.sessionNonce)
+  },
+  async getSession(identifier: string) {
+    return await getSharedSession(identifier)
+  },
+  async removeSession(session: PeerSession) {
+    await store.delete(`auth:nonce:${session.sessionNonce}`)
+    await store.delete(`auth:identity:${session.peerIdentityKey}`)
+  },
+  async hasSession(identifier: string) {
+    return await getSharedSession(identifier) != null
+  }
+}
+
+app.use(createAuthMiddleware({ wallet: myWallet, sessionManager }))
+```
+
 ### Injecting the Middleware into Express
 
 Simply call:
@@ -200,7 +239,7 @@ If `allowUnauthenticated` is **false**, any request without a valid handshake or
 Returns an Express middleware function. **Options**:
 
 - **`wallet`**: (required) A BRC-100 object implementing your signing and verification logic.  
-- **`sessionManager`**: (optional) Manage nonces & state across requests.  
+- **`sessionManager`**: (optional) Manage nonces & state across requests. Supports synchronous or asynchronous `AsyncSessionManager` implementations.
 - **`allowUnauthenticated`**: (optional) If true, non-authenticated requests are allowed but marked as `identityKey: 'unknown'`.  
 - **`certificatesToRequest`**: (optional) Automatic certificate request data structure.  
 - **`onCertificatesReceived`**: (optional) A callback triggered when certs arrive from the client.
@@ -290,4 +329,4 @@ app.listen(3000, () => console.log('Server up!'))
 
 ---
 
-**Happy hacking!** If you have questions, suggestions, or want to contribute improvements, feel free to open an issue or PR in our repository. 
+**Happy hacking!** If you have questions, suggestions, or want to contribute improvements, feel free to open an issue or PR in our repository.

packages/middleware/auth-express-middleware/src/index.ts

@@ -9,6 +9,7 @@ import {
   RequestedCertificateSet,
   Transport,
   SessionManager,
+  AsyncSessionManager,
   WalletInterface,
   PubKeyHex
 } from '@bsv/sdk'
@@ -37,7 +38,10 @@ export interface AuthRequest extends Request {
 // Developers may optionally provide a handler for incoming certificates.
 export interface AuthMiddlewareOptions {
   wallet: WalletInterface
-  sessionManager?: SessionManager // Optional if dev wants custom SessionManager
+  // Optional session store. Default is in-process synchronous `SessionManager`.
+  // Pass an `AsyncSessionManager` (Redis/SQL-backed, etc.) to share state
+  // across load-balanced instances; Peer awaits internally so both work.
+  sessionManager?: SessionManager | AsyncSessionManager
   allowUnauthenticated?: boolean
   certificatesToRequest?: RequestedCertificateSet
   onCertificatesReceived?: (
@@ -378,7 +382,7 @@ export class ExpressTransport implements Transport {
    * @param {NextFunction} next - The Express `next` middleware function.
    * @param {Function} [onCertificatesReceived] - Optional callback invoked when certificates are received.
    */
-  public handleIncomingRequest (
+  public async handleIncomingRequest (
     req: AuthRequest,
     res: Response,
     next: NextFunction,
@@ -389,7 +393,7 @@ export class ExpressTransport implements Transport {
       res: Response,
       next: NextFunction
     ) => void
-  ): void {
+  ): Promise<void> {
     this.log('debug', 'Handling incoming request', {
       path: req.path,
       headers: req.headers,
@@ -402,7 +406,7 @@ export class ExpressTransport implements Transport {
         throw new Error('You must set a Peer before you can handle incoming requests!')
       }
       if (req.path === '/.well-known/auth') {
-        this.handleWellKnownAuth(req, res, next, onCertificatesReceived)
+        await this.handleWellKnownAuth(req, res, next, onCertificatesReceived)
       } else if (req.headers['x-bsv-auth-request-id']) {
         this.handleGeneralMessage(req, res, next)
       } else {
@@ -417,7 +421,7 @@ export class ExpressTransport implements Transport {
   /**
    * Handles a request to /.well-known/auth (non-general / handshake messages).
    */
-  private handleWellKnownAuth (
+  private async handleWellKnownAuth (
     req: AuthRequest,
     res: Response,
     next: NextFunction,
@@ -428,7 +432,7 @@ export class ExpressTransport implements Transport {
       res: Response,
       next: NextFunction
     ) => void
-  ): void {
+  ): Promise<void> {
     const message = req.body as AuthMessage
     this.log('debug', 'Received non-general message at /.well-known/auth', { message })
 
@@ -443,7 +447,7 @@ export class ExpressTransport implements Transport {
       this.openNonGeneralHandles[requestId] = [{ res, next }]
     }
 
-    if (!this.peer!.sessionManager.hasSession(message.identityKey)) {
+    if (!await this.peer!.sessionManager.hasSession(message.identityKey)) {
       this.registerCertificateListener(req, res, next, requestId, message, onCertificatesReceived)
     }
 
@@ -650,7 +654,7 @@ export class ExpressTransport implements Transport {
     }
 
     this.hijackResponse(res, next, wrapper, buildAndSendResponse)
-    this.scheduleNextOrCertificateWait(next, senderPublicKey, wrapper, buildAndSendResponse)
+    void this.scheduleNextOrCertificateWait(next, senderPublicKey, wrapper, buildAndSendResponse).catch(next)
   }
 
   /**
@@ -728,13 +732,13 @@ export class ExpressTransport implements Transport {
   /**
    * Either calls next() immediately or stores it pending certificate arrival.
    */
-  private scheduleNextOrCertificateWait (
+  private async scheduleNextOrCertificateWait (
     next: NextFunction,
     senderPublicKey: string,
     wrapper: ResponseWriterWrapper,
     buildAndSendResponse: () => Promise<void>
-  ): void {
-    const hasSession = this.peer?.sessionManager.hasSession(senderPublicKey) ?? false
+  ): Promise<void> {
+    const hasSession = await (this.peer?.sessionManager.hasSession(senderPublicKey) ?? false)
     const needsCertificates = this.peer?.certificatesToRequest?.certifiers?.length
     this.log('debug', 'Checking if we need to wait for certificates', {
       senderPublicKey,
@@ -991,6 +995,6 @@ export function createAuthMiddleware (options: AuthMiddlewareOptions): (req: Aut
         method: req.method
       })
     }
-    transport.handleIncomingRequest(req, res, next, onCertificatesReceived)
+    void transport.handleIncomingRequest(req, res, next, onCertificatesReceived).catch(next)
   }
 }