# IssuerLink Flows

IssuerLink enables issuer operators to authenticate with a desktop console by pairing a mobile wallet (Ed25519 signer) to a web session. The Lambdas in `issuerlink/` orchestrate QR code distribution, signature verification, and session authorization.

## Happy-path flow
1. **Request QR** (`issuerlink/getLoginQR`)
   - **Route**: `POST /issuerlink/login`
   - Generates a 7200-second session nonce tied to the caller's source IP and stores it in the `issuerSessions` table. Returns a deep link string (`bt.issuer://link?s=...&ip=...`) that the mobile app encodes into a QR.
2. **Sign and submit** (`issuerlink/verifyUser`)
   - **Route**: `POST /issuerlink/verify`
   - Mobile app posts `{ token, sig, PK }` where `token` encodes the session ID and desktop IP. The handler:
     - Validates the Ed25519 signature with the claimed Stellar public key.
     - Confirms the PK exists in the `PII` table and is not restricted.
     - Confirms the session exists, matches the desktop IP, and records the user profile under the session record.
     - Gathers issuer accounts the PK signs for by enumerating Horizon signer relationships and annotating weight-based authority levels.
     - Returns `{ isAuthorized: true, context: { self, issuers } }` or rejects with `isAuthorized: false`.
3. **Authorize subsequent requests** (`issuerlink/sessionLambdaAuthorizerHOT`)
   - **Route**: Lambda authorizer attached to protected routes.
   - Reads the session token from the `Authorization` header, loads the session from `issuerSessions`, verifies both the stored `valid` flag and the caller IP, then injects the previously stored `user` and `issuers` context into API Gateway.

## Tables & schema
- `issuerSessions` primary key: `PK` (session ID). Attributes include `IP`, `TTL`, `verified`, `valid`, and any user context captured during verification.
- Session TTL is 7200 seconds from QR creation; clients should refresh before the record expires.

## Error handling
- Any signature mismatch or session/IP mismatch raises `PermissionError`, producing `isAuthorized: false` without leaking details.
- DynamoDB or Horizon failures bubble up as JSON error strings so operational logs capture the cause. Harden the API Gateway responses to avoid exposing internals in production.

## Roadmap callouts
- Session validation still uses bespoke JSON in the `Authorization` header; future work should migrate to WalletConnect or a signed JWT with CSRF protection.
- `verifyUser` contains TODOs for encoding a secure cookie and persisting issuer context atomically—plan to wire those before broad rollout.