Low-Level Design (LLD)
Detailed flow diagrams and implementation details
Login & Authentication Flow
Flow: Login & Authentication
Document: LLD-001
Version: 1.0
Date: 2026-02-21
Author: Frontend Architect (AI Agent)
Status: Draft
Scope: End-to-end login flow for web and mobile, including BankID OIDC, session management, demo mode, and error handling
1. Overview
Drop uses BankID OIDC as the sole production authentication method. Email/password login exists only in demo/dev mode. Authentication produces a JWT stored as an httpOnly cookie (web) or Bearer token (mobile). The login flow includes BankID redirect, loading states, token receipt, session persistence, and comprehensive error handling.
Key facts:
BankID is mandatory for production (PSD2/SCA compliance)
Demo mode provides email/password fallback for development
JWT lifetime: 7d (all clients)
Session tracking via SHA-256 token hash in sessions table
Age verification (>= 18) enforced during BankID callback
2. Web Login Flow (BankID OIDC)
2.1 Sequence Diagram — Web BankID Login
sequenceDiagram
actor User
participant Browser as Browser
Email entry
Password input
Password entry
Login button
Trigger api.login()
Register link
router.push("/register")
Navigate to registration
8. Accessibility Considerations (WCAG 2.1 AA)
Requirement
Implementation
Form labels
All inputs have associated elements
Error announcements
Error messages use role="alert" for screen readers
Focus management
After error, focus returns to the first invalid field
Color contrast
Error red (#EF4444) on white background meets 4.5:1 ratio
Keyboard navigation
Tab order follows visual order: email → password → submit → social buttons
Password visibility
Toggle button has aria-label "Vis passord" / "Skjul passord"
Loading state
Submit button shows loading spinner and is disabled during request
9. Cross-References
BankID OIDC integration details: See Authentication
API endpoints: GET /v1/auth/bankid/initiate , POST /v1/auth/bankid/callback , POST /v1/auth/demo-login , POST /v1/auth/refresh , GET /api/auth/me — See API Reference
Session database schema: sessions table — See Database Schema
Component overview: See component-overview.md
Figma login screen: mockups/figma-make-export/src/app/screens/Login.tsx
Web login page: src/drop-app/src/app/login/page.tsx — See PAGES.md
Registration flow: See flow-registration-onboarding.md
Login & Authentication (Backend)
Login & Authentication — Backend Architecture
Backend-specific authentication details for the Drop fintech platform. Covers JWT token structure, token refresh mechanism, session revocation, rate limiting on auth endpoints, audit logging, demo mode implementation, and cookie security settings.
JWT Token Structure
Token Generation
Source: src/drop-api/src/lib/auth.ts:42-48
Library: jose (HS256 default, RS256 opt-in)
new jose.SignJWT({ userId, email, role })
.setProtectedHeader({ alg: "HS256" })
.setIssuedAt()
.setIssuer("drop-api")
.setAudience("drop")
.setExpirationTime("7d")
.sign(key);
JWT Claims
Claim
Type
Value
Source
userId
string
usr_<16 hex chars> (e.g., usr_a1b2c3d4e5f6g7h8 )
auth.ts:44 — from user record
email
string
usr_xxx@bankid.drop.local (BankID placeholder) or real email
auth.ts:44 — from user record
role
string
user or merchant
auth.ts:44 — from users.role column
iat
number
Unix timestamp of issuance
auth.ts:45 — setIssuedAt()
exp
number
iat + 7 days (604800 seconds)
auth.ts:45 — setExpirationTime("7d")
iss
string
drop-api
auth.ts:45 — setIssuer()
aud
string
drop
auth.ts:45 — setAudience()
Algorithm Selection
Algorithm
Condition
Key Source
Use Case
HS256 (default)
JWT_RS256_PRIVATE_KEY not set
JWT_SECRET env var → TextEncoder.encode()
Standard deployment
RS256 (opt-in)
Both JWT_RS256_PRIVATE_KEY and JWT_RS256_PUBLIC_KEY set
PEM-encoded RSA key pair
Multi-service verification (API gateway, microservices)
Source: auth.ts:12-34 — getAlgorithm() auto-detects based on available keys.
Token Verification
Source: auth.ts:50-66
Determine algorithm (HS256 or RS256)
Call jose.jwtVerify(token, key, { issuer: "drop-api", audience: "drop" })
Extract userId , email , role from payload
Type-check: both userId and email must be strings
Default role to "user" if not present
JWT Refresh Flow
sequenceDiagram
participant Client as Client (Web/Mobile)
participant API as drop-api
participant DB as Database
Client->>API: POST /v1/auth/refresh
API->>API: Extract token from Bearer header or cookie
API->>API: Verify JWT signature (jose)
API->>DB: SELECT session WHERE token_hash = SHA256(token);" }
Refresh Behavior
Source: routes/auth.ts:201-210
Auth middleware validates current token
All existing sessions revoked ( revokeAllSessions(user.id) )
New JWT signed with fresh iat and exp (7 days from now)
New session record created in sessions table
Cookie set for web clients ( Set-Cookie header)
Token returned in JSON body for mobile clients
Key design decision: Token refresh performs a full session rotation — old sessions are invalidated immediately. This limits the window for token theft: a stolen token becomes invalid as soon as the legitimate user refreshes.
Session Revocation
Session Revocation Flow
sequenceDiagram
participant Client as Client
participant API as drop-api
participant DB as Database
alt Logout (user-initiated)
Client->>API: POST /v1/auth/logout
API->>API: Verify token (authMiddleware)
API->>DB: UPDATE sessions SET revoked = 1" }
end
Session Verification on Every Request
Source: auth.ts:108-117
Every authenticated request performs these checks:
Token signature verification — JWT must be valid and not expired
Session lookup — SELECT id FROM sessions WHERE token_hash = SHA256(token) AND revoked = 0 AND expires_at > NOW()
Session count check — If user has any sessions in DB but none match the current token, reject (prevents use of tokens from before session tracking was enabled)
User existence check — SELECT * FROM users WHERE id = ? AND deleted_at IS NULL (soft-deleted users are blocked)
Session Table Schema
Column
Type
Description
id
TEXT PK
Format: ses_<16 hex chars>
user_id
TEXT FK
References users.id
token_hash
TEXT
SHA-256 hash of the JWT string
created_at
TEXT
ISO timestamp of session creation
expires_at
TEXT
ISO timestamp, 7 days from creation
revoked
INTEGER
0 = active, 1 = revoked
Indexes: idx_sessions_user (user_id), idx_sessions_token (token_hash)
Rate Limiting on Auth Endpoints
Rate Limit Configuration
Endpoint
Limit
Window
Source
GET /v1/auth/bankid/initiate
10 requests
60 seconds
routes/auth.ts:19
POST /v1/auth/bankid/callback
10 requests
60 seconds
routes/auth.ts:43
POST /v1/auth/demo-login
Inherits from service mode check
N/A
Only available in demo mode
GET /v1/auth/me
No additional rate limit
N/A
Auth required (implicit protection)
POST /v1/auth/logout
No additional rate limit
N/A
Auth required
POST /v1/auth/refresh
No additional rate limit
N/A
Auth required
Rate Limiting Implementation
Source: middleware/rate-limit.ts:7-23
Storage: rate_limits table (persistent across restarts)
Key: Client IP address
Algorithm: Fixed window counter
Cleanup: Every 100 requests, expired entries are deleted
Atomic: Uses runUpsert for race-condition-safe counter updates
The rate limiter uses the rate_limits database table:
Column
Type
Description
key
TEXT PK
Client IP address
count
INTEGER
Request count in current window
reset_at
INTEGER
Unix timestamp when window resets
Client IP Extraction
Source: middleware/rate-limit.ts:25-27
Priority order:
x-real-ip header (nginx/Cloudflare)
First IP in x-forwarded-for chain (proxy chain)
Fallback: 127.0.0.1
Audit Logging for Auth Events
Audit Actions
Source: src/drop-api/src/lib/audit.ts
Action
Trigger
Data Recorded
REGISTER
New user created via BankID
userId , method: bankid , isNewUser: true , IP, user agent
LOGIN
Existing user authenticated via BankID
userId , method: bankid , isNewUser: false , IP, user agent
LOGOUT
User calls /v1/auth/logout
userId , resourceType: session
REFRESH
Token refresh
userId , resourceType: session
Audit Log Schema
Table: audit_log
Column
Type
Auth-Specific Usage
id
TEXT PK
Format: aud_<16 hex chars>
timestamp
TEXT
ISO timestamp of event
user_id
TEXT FK
Authenticated user ID
action
TEXT
One of REGISTER , LOGIN , LOGOUT , REFRESH
resource_type
TEXT
auth or session
resource_id
TEXT
Session ID (for session events)
details
TEXT
JSON: { method, isNewUser, platform }
ip_address
TEXT
Client IP from middleware
user_agent
TEXT
User-Agent header value
request_id
TEXT
Correlation ID from x-request-id header
Audit Log Example
{
"id": "aud_a1b2c3d4e5f6g7h8",
"timestamp": "2026-02-21T12:00:00.000Z",
"user_id": "usr_f1e2d3c4b5a69788",
"action": "LOGIN",
"resource_type": "auth",
"details": "{\"method\":\"bankid\",\"isNewUser\":false}",
"ip_address": "203.0.113.42",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
Demo Mode Implementation
Overview
Source: routes/auth.ts:131-159
Demo mode provides authentication without BankID for development and testing. API-side demo mode is controlled by DROP_MODE env var (checked via isDemoMode() in services/mode.ts ). NEXT_PUBLIC_SERVICE_MODE is the client-side equivalent (set to demo in docker-compose.yml).
Demo Login Endpoint
Endpoint: POST /v1/auth/demo-login
Aspect
Behavior
Availability
Only when isDemoMode() returns true
Authentication
None required
User
Fixed demo user: usr_demo1 (seeded in db.ts )
Response
JWT token + user data (same format as BankID callback)
Feature flag
Returns 404 when demo mode is disabled
Demo User Profile
Field
Value
Source
ID
usr_demo1
db.ts seed data
Email
demo@example.test
db.ts seed data
Name
Demo User
db.ts seed data
Phone
+4700000000
db.ts seed data
Role
merchant
Upgraded in initDb()
KYC Status
approved
Set on seed
Bank accounts
DNB (45,000 NOK), Nordea (12,350 NOK)
db.ts seed data
BankID Mock Mode
Source: bankid.ts:126-128
When BANKID_MOCK=true , the BankID OIDC flow is mocked:
exchangeAndVerify() skips token exchange and JWKS verification
Returns a mock user based on the auth code value:
Code starting with underage : returns user born 2010 (fails age check)
Default: returns Test Bankersen , born 1990 (passes age check)
Deprecated Endpoints
Source: routes/auth.ts:109-128
Endpoint
Status Code
Message
POST /v1/auth/login
410 Gone
"Email/password login is no longer supported. Please use BankID."
POST /v1/auth/register
410 Gone
"Email/password registration is no longer supported. Please use BankID."
POST /v1/auth/verify-otp
410 Gone
"OTP verification is no longer supported. Authentication is handled via BankID."
Cookie Security Settings
Cookie Configuration
Source: routes/auth.ts:195, 206
Property
Value
Purpose
Source
HttpOnly
true
Prevents JavaScript access — mitigates XSS token theft
auth.ts , cookie string
Secure
true (production)
Cookie only sent over HTTPS
Implied by deployment (Cloudflare enforces HTTPS)
SameSite
Lax
Prevents CSRF — cookie not sent on cross-origin POST requests
routes/auth.ts:206
Path
/
Cookie available to all routes
routes/auth.ts:206
Max-Age
604800 (7 days)
Session lifetime matching JWT expiry
routes/auth.ts:206
Domain
Not set (defaults to current domain)
Scoped to getdrop.no in production
Default browser behavior
Cookie Lifecycle
Event
Cookie Action
Source
BankID callback (web)
Set drop_token= with full security attributes
BFF redirect handler
Token refresh
Set new drop_token= , same attributes
routes/auth.ts:206
Logout
Clear cookie: drop_token=; Max-Age=0
routes/auth.ts:195
SameSite=Lax Behavior
Request Type
Cookie Sent?
Reason
Same-origin GET
Yes
Normal navigation
Same-origin POST
Yes
Form submissions
Cross-origin GET (top-level navigation)
Yes
Allows BankID redirect back
Cross-origin POST
No
CSRF protection
Cross-origin AJAX/fetch
No
CSRF protection
Subdomain requests
Depends on Domain setting
No Domain set = strict origin match
Web vs Mobile Token Strategy
Aspect
Web (Next.js)
Mobile (Expo)
Token delivery
httpOnly cookie ( drop_token )
JSON body ( { token } )
Token storage
Browser cookie jar (managed by browser)
AsyncStorage (React Native encrypted storage)
Token transmission
Automatic via Cookie header
Manual via Authorization: Bearer header
CSRF protection
SameSite=Lax + CORS origin validation
Not needed (no cookies, Bearer token)
Token extraction
auth.ts:96-99 — parse from cookie header
auth.ts:93-94 — extract from Authorization header
Cross-References
BankID OIDC flow: AUTHENTICATION.md — Full BankID authentication sequence
Auth source: src/drop-api/src/lib/auth.ts — JWT signing, verification, session management
Auth routes: src/drop-api/src/routes/auth.ts — Endpoint handlers
Auth middleware: src/drop-api/src/middleware/auth.ts — Request authentication
Rate limiter: src/drop-api/src/middleware/rate-limit.ts — IP-based rate limiting
BankID library: src/drop-api/src/lib/bankid.ts — OIDC flow, pid parsing, user creation
Security architecture: SECURITY-ARCHITECTURE.md — Cookie settings, JWT configuration
API reference: API-REFERENCE.md — Full endpoint documentation
Database schema: DATABASE-SCHEMA.md — sessions , users , audit_log tables
Registration & Onboarding Flow
Registration & Onboarding Flow -- Low-Level Design
Document: LLD-REGISTRATION
Status: Approved
Last updated: 2026-02-21
Author: Standards Architect
Applies to: Drop v1.0 (PSD2 pass-through model)
User requirements: Minimum age 18, Norwegian residency, valid BankID (from vilkar.html)
Overview
Drop's registration is simplified by using BankID as the sole authentication provider. There is no separate registration form -- user accounts are created automatically on first BankID login. The onboarding flow then guides the user through consent collection, KYC verification, and first bank account linking.
Key principle: Progressive disclosure. Users see only what they need at each step. Heavy verification happens in the background while the user explores the app.
Complete Registration Flow
sequenceDiagram
participant User
participant App as Drop App
participant BFF as Next.js BFF / Hono API
participant BankID as BankID OIDC
participant Sumsub
participant Bank as Nordic Bank (Open Banking)
participant DB as PostgreSQL
Note over User,DB: Step 1 -- BankID Authentication + Auto-Registration
User->>App: Tap "Logg inn med BankID"
App->>BFF: GET /api/auth/bankid (or /v1/auth/bankid/initiate)
BFF->>BFF: Generate state + nonce
BFF->>BFF: Rate limit check (10/min per IP)
BFF->>App: { redirectUrl }
App->>BankID: Open BankID authorize URL
User->>BankID: Authenticate (BankID app/code device)
Note over User,BankID: SCA: possession (device) + knowledge (PIN)
BankID->>App: Redirect with ?code=&state=
App->>BFF: GET /callback?code=&state= (or POST /callback)
BFF->>BFF: Verify state vs cookie/session
BFF->>BankID: POST /token (exchange code)
BankID->>BFF: { id_token, access_token }
BFF->>BFF: Verify ID token signature (JWKS)
BFF->>BFF: Extract pid (fodselsnummer, 11 digits)
BFF->>BFF: Parse DOB from pid
BFF->>BFF: Verify age >= 18
alt Age < 18
BFF->>App: Error: "Du ma vaere minst 18 ar"
App->>User: Show age restriction message
else Age >= 18
BFF->>BFF: SHA-256 hash pid -> national_id_hash
BFF->>DB: SELECT user WHERE national_id_hash = ?
alt Existing user
BFF->>DB: Create session + JWT
BFF->>App: Set cookie / return Bearer token
App->>User: Redirect to /dashboard
else New user (first login)
BFF->>DB: INSERT user (kyc_status='approved', kyc_method='bankid', auth_provider='bankid', password_hash='EIDONLY')
BFF->>DB: Create session + JWT
BFF->>App: Set cookie / return Bearer token
App->>User: Redirect to /onboarding
end
end
Note over User,DB: Step 2 -- Consent Collection (Onboarding Screen 1)
App->>User: Show consent checkboxes
User->>App: Accept terms + privacy + data processing
App->>BFF: POST /api/consents (type: 'terms', granted: true)
BFF->>DB: INSERT consents (terms, ip_address, granted_at)
App->>BFF: POST /api/consents (type: 'privacy', granted: true)
BFF->>DB: INSERT consents (privacy, ip_address, granted_at)
App->>User: Optional: marketing consent checkbox
Note over User,App: Marketing consent is OPTIONAL per GDPR
Note over User,DB: Step 3 -- KYC Trigger (Background)
BFF->>Sumsub: Create applicant (name, DOB from BankID)
Sumsub->>BFF: applicant_id
BFF->>DB: Store applicant_id
Sumsub->>Sumsub: PEP + sanctions screening
Sumsub->>BFF: Webhook: screening results
BFF->>DB: INSERT screening_results
Note over User,DB: Step 4 -- Bank Account Linking (Onboarding Screen 2)
App->>User: "Koble til bankkonto"
User->>App: Select bank (DNB, SpareBank1, Nordea...)
App->>BFF: POST /api/bank-accounts/link
BFF->>Bank: Open Banking: AISP consent request
Bank->>User: Authorize AISP access (SCA)
User->>Bank: Approve
Bank->>BFF: AISP access token + account list
BFF->>DB: INSERT bank_accounts (from AISP response)
BFF->>Bank: GET /accounts/{id}/balances
Bank->>BFF: { balance, currency }
BFF->>DB: UPDATE bank_accounts SET balance = ?, is_primary = 1
BFF->>App: { bankAccounts: [...] }
App->>User: Show linked account with balance
Note over User,DB: Step 5 -- Onboarding Complete
App->>User: "Velkommen til Drop!"
App->>User: Redirect to /dashboard
Onboarding States
stateDiagram-v2
[*] --> bankid_redirect : User taps "Logg inn med BankID"
bankid_redirect --> bankid_auth : BankID authorize page
bankid_auth --> age_check : BankID callback received
age_check --> rejected_underage : Age < 18
age_check --> user_lookup : Age >= 18
rejected_underage --> [*]
user_lookup --> existing_user : national_id_hash found
user_lookup --> new_user : national_id_hash not found
existing_user --> dashboard : Session created, redirect
new_user --> user_created : Auto-register from BankID data
user_created --> consent_collection : Redirect to /onboarding
consent_collection --> consents_granted : Terms + privacy accepted
consents_granted --> kyc_background : Sumsub screening starts
kyc_background --> bank_linking : Screening runs in background
bank_linking --> bank_consent : User selects bank
bank_consent --> bank_authorized : AISP consent granted
bank_authorized --> account_linked : Balance fetched
account_linked --> onboarding_complete : First bank account linked
onboarding_complete --> dashboard : Redirect to /dashboard
state kyc_background {
[*] --> sumsub_pending
sumsub_pending --> screening
screening --> kyc_approved : All clear
screening --> kyc_review : Match found
kyc_review --> kyc_approved : Cleared by compliance
kyc_review --> kyc_rejected : Confirmed risk
}
dashboard --> [*]
Age Verification (18+)
Norwegian fodselsnummer (11-digit personal identification number) encodes the date of birth:
Digits
Meaning
Example
1-2
Day of birth (DD)
15
3-4
Month of birth (MM)
03
5-6
Year of birth (YY)
95
7-9
Individual number
123
10-11
Check digits
45
Century determination (from individual number, digits 7-9):
000-499: born 1900-1999
500-749: born 1854-1899 (historical) or 2000-2039
750-899: born 1854-1899 (historical)
900-999: born 1940-1999
Verification logic:
1. Extract DD, MM, YY from pid[0..5]
2. Determine century from pid[6..8]
3. Construct full birthdate
4. Calculate age = today - birthdate
5. If age < 18: reject with "Du ma vaere minst 18 ar for a bruke Drop"
Source: vilkar.html section 3 -- "Du ma vaere minst 18 ar og bosatt i Norge for a bruke Drop."
Norwegian Residency Check
BankID issuance inherently confirms Norwegian residency:
BankID is issued only by Norwegian banks to their customers
Norwegian bank accounts require Norwegian national ID (fodselsnummer or D-number)
D-numbers are issued to foreign nationals with legitimate ties to Norway
Additional signals:
Phone number prefix: +47 (Norwegian)
BankID issuer: Norwegian bank (from ID token amr claim)
Signal
Check
Enforcement
BankID ownership
Implicit -- only Norwegian residents have BankID
At authentication
Phone number
+47 prefix
Optional validation at profile update
Postal address
Norwegian postal code
At bank account linking (from AISP data)
Consent Collection
Required Consents
Per GDPR Article 6(1)(a) and Article 7, explicit consent must be collected before processing personal data. The following consents are collected during onboarding:
Consent Type
Required
Legal Basis
Description
Withdrawable
terms
Yes (mandatory)
Contract (Art. 6(1)(b))
Terms of service acceptance
Account deletion required
privacy
Yes (mandatory)
Consent (Art. 6(1)(a))
Privacy policy acknowledgment
Account deletion required
data_processing
Yes (mandatory)
Consent (Art. 6(1)(a))
PSD2 AISP/PISP data processing consent
Revokes bank access
marketing
No (optional)
Consent (Art. 6(1)(a))
Marketing communications
Yes, at any time
cookies_analytics
No (optional)
Consent (Art. 6(1)(a))
Analytics cookies
Yes, at any time
cookies_marketing
No (optional)
Consent (Art. 6(1)(a))
Marketing/tracking cookies
Yes, at any time
Consent Checklist
#
Consent
Checkbox Text (Norwegian)
Default
Validation
1
Terms of service
"Jeg godtar Drop sine brukervilkar"
Unchecked
Must be checked to proceed
2
Privacy policy
"Jeg har lest og godtar personvernerklaringen"
Unchecked
Must be checked to proceed
3
PSD2 data access
"Jeg godtar at Drop leser kontoinformasjon og initierer betalinger via Open Banking"
Unchecked
Must be checked to proceed
4
Marketing
"Jeg onsker a motta nyheter og tilbud fra Drop"
Unchecked
Optional
Consent Storage
Each consent is stored in the consents table:
Column
Value
Purpose
id
con_
Unique consent record ID
user_id
usr_
References the user
consent_type
terms , privacy , marketing , etc.
Type of consent
granted
1 (true) or 0 (false)
Current consent state
granted_at
ISO timestamp
When consent was granted
withdrawn_at
ISO timestamp or NULL
When consent was withdrawn
ip_address
Client IP
Proof of consent action (GDPR Art. 7(1))
Consent API
Endpoint
Method
Purpose
GET /api/consents
GET
List all user consents
POST /api/consents
POST
Grant or withdraw consent
Consent withdrawal flow:
User navigates to Settings > Privacy
Toggles marketing consent off
POST /api/consents with { consentType: "marketing", granted: false }
Record updated: granted = 0 , withdrawn_at = now()
User can re-grant at any time
First Bank Account Linking
After consent collection, the user links their first bank account via AISP:
sequenceDiagram
participant User
participant App as Drop App
participant BFF as Drop API
participant Bank as Nordic Bank
User->>App: Select bank from list (DNB, SpareBank1, etc.)
App->>BFF: POST /api/bank-accounts/link { bankId: "dnb" }
BFF->>Bank: Open Banking: GET /authorize (AISP scope)
Bank->>User: Show consent screen (SCA required)
Note over User,Bank: "Drop vil lese kontosaldo og
Generated by randomId("ba")
user_id
Current user ID
From JWT
bank_name
"DNB"
From bank selection
account_number
Domestic format (masked in API)
From ASPSP account details
iban
Full IBAN
From ASPSP
balance
Balance in oere (e.g., 4523000 = 45,230 NOK)
From ASPSP balance endpoint
balance_synced_at
Current timestamp
Set on each refresh
currency
"NOK"
From ASPSP
is_primary
1 for first account, 0 for others
Auto-set
connected_at
Current timestamp
Set on linking
5. Balance Refresh Strategy
Trigger
Frequency
ASPSP Call
UI Behavior
User opens Dashboard
On demand
GET /v1/accounts/{id}/balances
Show spinner, then updated balance
User pulls to refresh
On demand
GET /v1/accounts/{id}/balances
Pull-to-refresh animation
Background sync
Every 6 hours
GET /v1/accounts/{id}/balances
Silent update
Pre-payment check
Before PISP
GET /v1/accounts/{id}/balances
Inline balance verification
User views /accounts
On demand
GET /v1/accounts/{id}/balances
Show spinner per account
PSD2 constraint: TPP-initiated requests (background sync) are limited to 4 per day per account (RTS Art. 36(6)). User-initiated requests (opening app, pull-to-refresh) are unlimited .
6. Error Handling
6.1 Error Table
Error
Stage
HTTP Status
User Message (Norwegian)
Recovery
Bank not supported
Bank selection
400
"Denne banken stottes ikke ennaa."
Show supported banks
ASPSP API unreachable
Consent creation
502
"Kunne ikke koble til banken. Prv igjen senere."
Retry after 30s
SCA timeout
SCA at bank
408
"BankID-sesjonen utlp. Prv igjen."
Restart linking flow
SCA cancelled
SCA at bank
400
"Du avbrt tilkoblingen."
Offer retry button
SCA rejected
SCA at bank
403
"Banken avviste tilgangen."
Contact bank support
Consent invalid
Callback
403
"Tilgangsforesprselen var ugyldig."
Restart flow
State mismatch
Callback
403
"Sikkerhetssjekk feilet. Prv igjen."
Restart flow
No accounts found
Account retrieval
404
"Fant ingen kontoer hos denne banken."
Verify correct bank selected
Balance read failed
Balance fetch
502
"Kunne ikke hente saldo. Viser sist kjente."
Show cached balance with timestamp
Consent expired
Any balance read
403
"Tilgangen til banken din er utlpt. Koble til paa nytt."
Re-link flow
Rate limit exceeded
Balance read
429
"For mange foresprsler. Viser sist kjente saldo."
Show cached balance
6.2 Fallback Behavior
When a balance read fails, Drop shows the last cached balance with the balance_synced_at timestamp:
DNB Brukskonto
45 230,00 kr
Sist oppdatert: 2 timer siden
If the consent is expired or revoked, the balance is zeroed and the user sees:
DNB Brukskonto
-- kr
Tilgangen er utlopt. Koble til paa nytt.
[Koble til] button
7. Consent Renewal
AISP consents have a maximum validity of 90 days (PSD2 RTS Art. 10). Drop proactively prompts renewal:
Timeline
Action
Day 0
Consent created, validUntil = Day 90
Day 60
Push notification: "Din banktilgang utlper snart. Forny tilgangen."
Day 80
In-app banner on Dashboard: "Tilgangen til DNB utlper om 10 dager."
Day 85
Push notification: "Tilgangen utlper om 5 dager. Forny naa."
Day 90
Consent expires. Balance zeroed. User must re-link.
Renewal flow: Same as initial linking — new consent + BankID SCA at bank. The old consent is deleted after the new one is active.
8. Account Unlinking
When the user taps "Fjern konto" (Remove account):
DELETE /v1/consents/{consentId} at the ASPSP (revoke consent)
DELETE FROM bank_accounts WHERE id = ? in Drop DB
UPDATE consents SET withdrawn_at = now WHERE aspsp_consent_id = ?
If the removed account was primary, promote another linked account to primary
If no accounts remain, Dashboard shows "Koble til bank" prompt
9. Multi-Bank Support
Users can link accounts from multiple banks. Each linked account has its own AISP consent with its own lifecycle.
Dashboard display:
Dine bankkontoer (Your bank accounts)
DNB Brukskonto 45 230,00 kr (primary)
DNB Sparekonto 12 800,00 kr
Nordea Brukskonto 8 450,00 kr
Totalt 66 480,00 kr
[Koble til ny bank]
Drop API: GET /api/auth/me returns totalBalance (sum of all linked account balances) and bankAccounts[] array.
10. Database Impact
10.1 Tables Affected
Table
Operation
When
bank_accounts
INSERT
Account linked
bank_accounts
UPDATE (balance, balance_synced_at)
Balance refresh
bank_accounts
DELETE
Account unlinked
consents
INSERT (consent_type: 'psd2_aisp')
Consent created
consents
UPDATE (granted, granted_at)
SCA completed
consents
UPDATE (withdrawn_at)
Consent revoked
audit_log
INSERT
Every linking/unlinking action
notifications
INSERT
Consent expiry reminders
10.2 Index Usage
Index
Used By
idx_bank_accounts_user on user_id
All account queries (scoped to user)
idx_consents_user on user_id
Consent lookups for renewal checks
11. Cross-References
Open Banking AISP/PISP: ../integration/open-banking-aisp-pisp.md — Berlin Group API details, consent properties
BankID OIDC: ../integration/bankid-oidc-integration.md — Drop authentication (separate from bank SCA)
Security Architecture: ../hld/security-architecture.md — Trust boundaries, data classification
Remittance Flow: flow-remittance.md — Uses linked bank account for PISP
Database Schema: ../../backend/DATABASE-SCHEMA.md — bank_accounts , consents tables
API Reference: ../../backend/API-REFERENCE.md — GET /api/auth/me returns bank accounts
QR Payment Flow
Flow: QR Payment
Document: LLD-002
Version: 1.0
Date: 2026-02-21
Author: Frontend Architect (AI Agent)
Status: Draft
Scope: End-to-end QR payment flow covering camera handling, merchant resolution, payment confirmation, SCA, and error states for both web and mobile
1. Overview
QR payments allow Drop users to pay in-store by scanning a merchant's QR code. The payment is initiated via PISP (Payment Initiation Service Provider) directly from the user's bank account under the PSD2 pass-through model. Drop never holds customer funds.
QR Code Format: drop://pay/{merchantId}
Payment Fee: 1% of transaction amount (fee is deducted from user's balance: totalOre = amountOre + feeOre . Settlement to merchant is separate.)
Note: Database stores amounts in ore (minor units). API accepts NOK and converts internally using nokToOre() . Example: 129 NOK = 12900 ore in DB.
Flow summary: Camera permission → QR scan → decode merchant ID → fetch merchant details → amount entry → SCA trigger → payment confirmation → receipt display
2. QR Payment Sequence Diagram
sequenceDiagram
actor User
participant App as Drop App>
+query(sql, params): T[]
+getOne(sql, params): T
+run(sql, params): RunResult
+transaction(fn): void
}
class PISPClient {
<>
+initiatePayment(paymentRequest): PaymentResponse
+getPaymentStatus(paymentId): PaymentStatus
}
TransactionsRoute --> RemittanceDto
TransactionsRoute --> QRPaymentDto
TransactionsRoute --> Transaction
TransactionsRoute --> Database
TransactionsRoute --> PISPClient
3. Database Schema
3.1 Tables
transactions
Purpose: Records all financial operations. Append-only — status updates are the only writes after creation.
Column
Type
Nullable
Default
Constraints
Description
id
TEXT
NO
—
PK, format: tx_
Transaction identifier
user_id
TEXT
NO
—
FK → users(id)
Initiating user
type
TEXT
NO
—
CHECK('remittance','qr_payment')
Transaction type
status
TEXT
NO
'processing'
CHECK('processing','completed','failed')
Payment status
amount
REAL
NO
—
NOT NULL
Send amount in NOK (stored in øre equivalent)
currency
TEXT
YES
'NOK'
—
Source currency (always NOK at MVP)
fee
REAL
YES
0
—
Fee in NOK (0.5% remittance, merchant rate for QR)
recipient_id
TEXT
YES
NULL
FK → recipients(id)
For remittances; NULL for QR
merchant_id
TEXT
YES
NULL
FK → merchants(id)
For QR payments; NULL for remittance
send_amount
REAL
YES
NULL
—
Amount sent in source currency
receive_amount
REAL
YES
NULL
—
Amount received in destination currency
receive_currency
TEXT
YES
NULL
—
Destination currency (e.g., RSD, EUR)
exchange_rate
REAL
YES
NULL
—
Exchange rate at time of transaction
description
TEXT
YES
NULL
—
Optional user-provided description
idempotency_key
TEXT
YES
NULL
UNIQUE
Prevents duplicate payments on retry
created_at
TEXT
NO
datetime('now')
—
Transaction timestamp
Indexes:
Index Name
Columns
Type
Rationale
transactions_pkey
id
B-tree (PK)
Primary key lookup
idx_transactions_user
user_id
B-tree
Filter all transactions per user (high frequency)
idx_tx_idempotency
idempotency_key
Unique B-tree
Prevent duplicate payment on API retry
idx_transactions_recipient
recipient_id
B-tree
Lookup by recipient
idx_transactions_merchant
merchant_id
B-tree
Lookup by merchant
exchange_rates
Purpose: Stores current NOK-to-foreign currency exchange rates for the 6 supported remittance corridors.
Column
Type
Nullable
Default
Constraints
Description
id
INTEGER
NO
auto
PK
Surrogate key
from_currency
TEXT
NO
—
NOT NULL
Always 'NOK' at MVP
to_currency
TEXT
NO
—
NOT NULL
Target currency (RSD, BAM, PLN, PKR, TRY, EUR)
rate
REAL
NO
—
NOT NULL
Exchange rate: 1 NOK = N target currency units
updated_at
TEXT
YES
—
—
Last rate update timestamp
Indexes:
Index Name
Columns
Type
Rationale
idx_rates_currency
from_currency, to_currency
Composite B-tree
Fast rate lookup by currency pair
3.2 Enums (CHECK constraints in SQLite, native ENUMs in PostgreSQL migration)
-- transaction type
CHECK(type IN ('remittance', 'qr_payment'))
-- transaction status
CHECK(status IN ('processing', 'completed', 'failed'))
3.3 Migration Notes
Migration: Included in db.ts initializeDatabase() — runs on startup (SQLite) or via separate migration script (PostgreSQL)
Zero-downtime: YES — only INSERT and UPDATE status needed; CREATE INDEX CONCURRENTLY for PostgreSQL
Backfill required: NO — new tables
Estimated migration time: < 1 second (SQLite), < 5 seconds (PostgreSQL)
4. API Contract
Base Path: /v1/transactions
POST /v1/transactions/remittance
Summary: Initiate international money transfer (PISP) from user's bank account to a saved recipient
Authentication: Bearer JWT required ( authMiddleware )
Rate Limit: 10 req/60s per IP + 3 req/60s per user
Request Body:
{
"recipientId": "rec_abc123def456gh78",
"amount": 2000,
"bankAccountId": "ba_abc123def456gh78",
"currency": "NOK"
}
Success Response — 201 Created :
{
"data": {
"id": "tx_rem_abc123def456gh78",
"type": "remittance",
"status": "processing",
"amount": 2000,
"fee": 10,
"receiveAmount": 20340,
"receiveCurrency": "RSD",
"exchangeRate": 10.17,
"estimatedDelivery": "2-4 business days",
"scaRedirect": "https://dnb.no/sca/pay/abc123",
"createdAt": "2026-02-23T10:00:00.000Z"
}
}
Error Responses:
Status
Code
Description
400
validation_error
Missing or invalid fields (amount, recipientId)
401
unauthorized
Missing or expired JWT
403
kyc_required
User kyc_status is not approved
403
insufficient_balance
Cached AISP balance < amount + fee
404
recipient_not_found
recipientId does not belong to this user
409
duplicate_transaction
Idempotency key collision — returns existing transaction
422
amount_out_of_range
Amount < 100 NOK or > 50,000 NOK
429
rate_limited
Exceeded 10 req/60s per IP or 3 req/60s per user
502
pisp_unavailable
Open Banking PISP API unreachable
500
internal_error
Unexpected server error
POST /v1/transactions/qr-payment
Summary: Initiate QR merchant payment (PISP) from user's bank account
Authentication: Bearer JWT required
Request Body:
{
"merchantId": "mer_abc123def456gh78",
"amount": 450
}
Success Response — 201 Created :
{
"data": {
"id": "tx_qr_abc123def456gh78",
"type": "qr_payment",
"status": "completed",
"amount": 450,
"fee": 4.5,
"merchantName": "Café Oslo AS",
"createdAt": "2026-02-23T10:00:00.000Z"
}
}
Error Responses:
Status
Code
Description
400
validation_error
Missing or invalid fields
401
unauthorized
Missing or expired JWT
403
kyc_required
User kyc_status not approved
404
merchant_not_found
merchantId not found or inactive
500
internal_error
Unexpected error
POST /v1/transactions/disclosure
Summary: Pre-payment disclosure — returns fee, exchange rate, receive amount (PSD2 Art. 45/46 compliance)
Authentication: Bearer JWT required
Request Body:
{
"type": "remittance",
"amount": 2000,
"recipientId": "rec_abc123def456gh78"
}
Success Response — 200 OK :
{
"data": {
"sendAmount": 2000,
"sendCurrency": "NOK",
"fee": 10,
"feePercentage": 0.5,
"exchangeRate": 10.17,
"receiveAmount": 20340,
"receiveCurrency": "RSD",
"totalCost": 2010,
"estimatedDelivery": "2-4 business days"
}
}
GET /v1/transactions
Summary: List authenticated user's transactions with pagination
Query Parameters:
Parameter
Type
Default
Description
page
integer
1
Page number (1-based)
limit
integer
20
Items per page (max 50)
type
string
—
Filter: remittance or qr_payment
status
string
—
Filter: processing , completed , failed
Success Response — 200 OK :
{
"data": {
"transactions": [
{
"id": "tx_rem_abc123",
"type": "remittance",
"status": "completed",
"amount": 2000,
"fee": 10,
"receiveAmount": 20340,
"receiveCurrency": "RSD",
"recipientName": "Marko Petrovic",
"createdAt": "2026-02-23T10:00:00.000Z"
}
],
"total": 15,
"page": 1,
"limit": 20
}
}
5. Algorithm Specifications
5.1 Fee Calculation — Remittance
Purpose: Calculate 0.5% fee on remittance, rounded to 2 decimal places
Complexity: Time O(1) | Space O(1)
function calculateRemittanceFee(sendAmountNOK: number): number
FEE_RATE = 0.005 // 0.5%
fee = sendAmountNOK * FEE_RATE
return Math.round(fee * 100) / 100 // Round to 2 decimal places
function calculateReceiveAmount(sendAmountNOK: number, exchangeRate: number): number
netSend = sendAmountNOK // Fee taken from send amount, not receive
receive = netSend * exchangeRate
return Math.round(receive) // Round to whole units of target currency
Edge Cases:
Minimum amount: 100 NOK → fee = 0.50 NOK
Maximum amount: 50,000 NOK → fee = 250 NOK
Rate not found: Return 404 — do not proceed to transaction
5.2 Idempotency Key Generation
Purpose: Prevent double-charging on network retry or duplicate form submission
Format: {userId}:{amount}:{recipientId}:{minuteTimestamp}
function generateIdempotencyKey(userId, amount, recipientId): string
minuteTimestamp = Math.floor(Date.now() / 60000) // Changes every 60s
key = `${userId}:${amount}:${recipientId}:${minuteTimestamp}`
return key
// Unique index on transactions.idempotency_key prevents duplicate
// If INSERT fails with UNIQUE constraint → return existing transaction
6. Sequence Diagrams
6.1 Remittance Initiation Flow
sequenceDiagram
autonumber
actor Client as Client (Web/Mobile)
participant RL as Rate Limiter
participant Auth as Auth Middleware
participant Route as Transactions Route
participant DB as Database
participant PISP as Open Banking PISP
Client->>RL: POST /v1/transactions/remittance
RL->>RL: Check rate_limits (10/IP, 3/user per 60s)
alt Rate limit exceeded
RL-->>Client: 429 Too Many Requests
end
RL->>Auth: Forward request
Auth->>Auth: Extract JWT from Bearer header / cookie
Auth->>DB: SELECT session WHERE token_hash = ? AND revoked = 0
Auth->>DB: SELECT user WHERE id = ? AND deleted_at IS NULL
Auth-->>Route: user context {userId, role, kycStatus}
Route->>Route: Validate body: recipientId, amount (100-50000), bankAccountId
alt Validation fails
Route-->>Client: 400 validation_error
end
alt kyc_status != 'approved'
Route-->>Client: 403 kyc_required
end
Route->>DB: SELECT * FROM recipients WHERE id = ? AND user_id = ?
alt Recipient not found
Route-->>Client: 404 recipient_not_found
end
Route->>DB: SELECT rate FROM exchange_rates WHERE to_currency = ?
Route->>DB: SELECT * FROM bank_accounts WHERE id = ? AND user_id = ? AND is_primary = 1
Route->>Route: Calculate fee (0.5%), total cost, receive amount
alt balance < totalCost
Route-->>Client: 403 insufficient_balance
end
Route->>DB: BEGIN TRANSACTION
Route->>DB: UPDATE bank_accounts SET balance = balance - totalCostInOere WHERE balance >= ?
Route->>DB: INSERT INTO transactions (status='processing', idempotency_key=?)
Route->>DB: INSERT INTO audit_log (action='transaction.create')
Route->>DB: INSERT INTO notifications (title='Overføring startet')
Route->>DB: COMMIT
Route->>PISP: POST /v1/payments/cross-border-credit-transfers
PISP-->>Route: {paymentId, transactionStatus: "RCVD", scaRedirect}
Route-->>Client: 201 {transactionId, status: "processing", scaRedirect}
6.2 QR Payment Flow
sequenceDiagram
autonumber
actor Client as Client (Mobile)
participant Route as Transactions Route
participant DB as Database
Client->>Route: POST /v1/transactions/qr-payment {merchantId, amount}
Route->>DB: Verify JWT session
Route->>DB: SELECT * FROM merchants WHERE id = ? AND status = 'active'
alt Merchant not found
Route-->>Client: 404 merchant_not_found
end
Route->>DB: SELECT * FROM bank_accounts WHERE user_id = ? AND is_primary = 1
Route->>Route: Calculate fee = amount * merchant.fee_rate
Route->>Route: Calculate total = amount + fee
Route->>DB: BEGIN TRANSACTION
Route->>DB: UPDATE bank_accounts SET balance = balance - total
Route->>DB: INSERT INTO transactions (type='qr_payment', status='completed')
Route->>DB: INSERT INTO audit_log (action='qr_payment.create')
Route->>DB: INSERT INTO notifications (title='Betaling registrert')
Route->>DB: COMMIT
Route-->>Client: 201 {transactionId, status: "completed", merchantName}
7. State Diagrams
stateDiagram-v2
[*] --> processing: POST /v1/transactions/remittance (PISP initiated)
processing --> completed: PISP webhook — payment confirmed by bank
processing --> failed: PISP webhook — payment rejected (insufficient funds, SCA timeout, SCA cancelled)
processing --> failed: 5-minute SCA timeout — no callback received
completed --> [*]
failed --> [*]
Note: QR payments go directly from creation to completed (synchronous in MVP — no PISP webhook for domestic transfers in mock mode).
State Transition Rules:
From
To
Trigger
Guard Condition
Side Effect
(none)
processing
POST /v1/transactions/remittance
KYC approved, balance sufficient
Deduct cached balance, create audit log, send notification
processing
completed
PISP webhook or QR sync completion
paymentId matches transaction
Update status, send completion notification
processing
failed
PISP webhook rejection or 5-min timeout
paymentId matches, status RJCT
Restore cached balance (re-sync AISP), send failure notification
8. Error Handling Strategy
8.1 Error Classification
Error Type
HTTP Status
Retry?
Log Level
Alert?
ValidationError
400
No
INFO
No
UnauthorizedError
401
No
WARN
No
KYCRequired
403
No
INFO
No
InsufficientBalance
403
No
INFO
No
RecipientNotFound
404
No
INFO
No
DuplicateTransaction
409
No
INFO
No
AmountOutOfRange
422
No
INFO
No
RateLimited
429
After Retry-After
WARN
No
PISPUnavailable
502
Yes (3x backoff)
ERROR
Yes (if sustained > 5 min)
DatabaseError
500
Yes (1x)
ERROR
Yes
UnexpectedError
500
No
ERROR
Yes
8.2 Error Response Format
{
"error": "kyc_required",
"message": "Du må fullføre identitetsverifisering før du kan sende penger.",
"details": []
}
8.3 Retry & Fallback Strategy
PISP API call failure:
→ Retry with exponential backoff: [1s, 2s, 4s]
→ Max retries: 3
→ Circuit breaker: Open after 3 failures in 60s window → 60s cooldown
→ Fallback: Return 502 to client — payment cannot proceed without PISP
→ Alert: Sentry alert if circuit remains open > 5 minutes
→ Idempotency: PISP call uses X-Request-ID = idempotency_key to prevent double-payment on retry
9. Concurrency & Thread Safety
Concern
Scenario
Mitigation
Double payment
Client retries POST /v1/transactions/remittance after network timeout
Unique index on idempotency_key — second INSERT fails with UNIQUE constraint → return existing transaction
Balance race condition
Two simultaneous payments from same account
DB transaction with UPDATE bank_accounts SET balance = balance - X WHERE balance >= X — atomic check-and-deduct
Exchange rate staleness
Rate changes between disclosure and payment
Rate locked at payment initiation time; user sees pre-payment disclosure; rate used is from DB at payment time
10. Performance Considerations
Operation
Target (p99)
Current Baseline
Optimization
POST /v1/transactions/remittance
< 500ms (local) + PISP latency
~50ms DB operations
DB transaction atomic; PISP call is async from user perspective
GET /v1/transactions
< 100ms
~20ms
Index idx_transactions_user on user_id ; pagination limits result set
POST /v1/transactions/disclosure
< 50ms
~10ms
Two DB reads (recipient + exchange rate); no external API call
POST /v1/transactions/qr-payment
< 200ms
~40ms
Synchronous completion in mock mode; PISP async in production
Known bottlenecks:
PISP API latency: 200-2000ms external call — mitigated by async SCA redirect pattern
Exchange rate reads: High frequency but 6 rows only — fully cached in PostgreSQL buffer pool
11. Dependencies
Internal Dependencies
Dependency
Type
Purpose
Fallback if unavailable
middleware/auth.ts
Synchronous
JWT validation + user context
None — request rejected with 401
middleware/rate-limit.ts
Synchronous
IP + user rate limiting
None — request rejected with 429
lib/db.ts
Required
All data access (query, run, transaction)
None — module unavailable
External Dependencies
Dependency
Version
Purpose
Fallback if unavailable
PostgreSQL
16
Primary data store
SQLite (dev only)
Open Banking PISP (Neonomics/ASPSP)
Berlin Group v1.3.12+
Payment initiation
None — return 502, payment cannot proceed
Open Banking AISP
Berlin Group v1.3.12+
Pre-payment balance verification
Use cached bank_accounts.balance with staleness warning
12. Configuration Parameters
Variable
Type
Default
Required
Description
DATABASE_URL
string
—
No (SQLite default)
PostgreSQL connection string
NEXT_PUBLIC_SERVICE_MODE
string
mock
No
mock = simulate PISP; production = real PISP calls
OPEN_BANKING_API_URL
string
—
Yes (prod)
Neonomics or ASPSP base URL
OPEN_BANKING_CLIENT_ID
string
—
Yes (prod)
eIDAS client identifier
OPEN_BANKING_CLIENT_SECRET
string
—
Yes (prod)
eIDAS client secret
13. Testing Approach
Test Type
Tool
Coverage Target
Location
Unit tests
Vitest
> 80% business logic
src/drop-api/src/__tests__/unit/transactions/
Integration tests
Supertest
Key payment flows
src/drop-api/src/__tests__/integration/transactions/
Key test scenarios:
Remittance — success path (mock PISP)
Remittance — KYC not approved → 403
Remittance — amount < 100 NOK → 422
Remittance — amount > 50,000 NOK → 422
Remittance — recipient not found → 404
Remittance — duplicate request (idempotency key) → 409 with existing transaction
QR payment — success path
QR payment — merchant inactive → 404
Disclosure — calculates fee, exchange rate, receive amount correctly
PISP circuit breaker — 3 failures → open → 502 (integration test, Phase 2)
Concurrent payment — balance race condition handled correctly (Phase 2)
Approval
Role
Name
Date
Signature
Author
Petter Graff
2026-02-23
Module Owner
John (AI Director)
Security Review
Tech Lead
John (AI Director)
LLD: Withdrawal Flow
Withdrawal Request Flow (Angrerett)
Purpose
Implements the user's right of withdrawal (angrerett) as required by Norwegian consumer protection law (angrerettloven). Users can submit a withdrawal request to cancel their account or service agreement within the statutory cooling-off period.
Sequence Diagram
sequenceDiagram
participant U as User (App)
participant API as Drop API
participant Auth as Auth Middleware
participant DB as PostgreSQL
participant Audit as Audit Log
U->>API: POST /withdrawal { reason, comment }
API->>Auth: Validate JWT token
Auth-->>API: user context
alt Invalid JSON body
API-->>U: 400 bad_request
end
API->>API: Sanitize reason (max 100 chars)
API->>API: Sanitize comment (max 1000 chars)
API->>API: Validate reason against VALID_REASONS
alt Invalid reason
API-->>U: 400 validation_error
end
API->>DB: INSERT INTO withdrawal_requests (id, user_id, reason, comment)
DB-->>API: OK
API->>Audit: Log WITHDRAWAL_REQUEST action
Audit->>DB: INSERT INTO audit_log
API-->>U: 201 { success: true, id }
Database Schema
withdrawal_requests table
Column
Type
Constraints
id
TEXT
PRIMARY KEY (prefix: wr_ )
user_id
TEXT
NOT NULL, REFERENCES users(id)
reason
TEXT
Nullable
comment
TEXT
Nullable
status
TEXT
DEFAULT 'pending', CHECK IN ('pending','processing','completed','rejected')
created_at
TIMESTAMPTZ
DEFAULT NOW()
Index: idx_withdrawal_requests_user on user_id .
Valid Withdrawal Reasons
Value
Description
not_needed
User no longer needs the service
alternative
User found an alternative service
not_satisfied
User is not satisfied with the service
other
Other reason (details in comment field)
"" (empty)
No reason provided
Request Processing
Authentication -- request must include a valid JWT token (authMiddleware).
Input validation -- reason is checked against the allowlist; both reason and comment are sanitized via sanitizeText with length limits.
Record creation -- a new withdrawal_requests row is inserted with status pending .
Audit logging -- an audit log entry is created with action WITHDRAWAL_REQUEST , including the reason and the requester's IP address.
Status Lifecycle
pending --> processing --> completed
\-> rejected
pending -- initial state after user submits request.
processing -- staff/admin has begun reviewing the request.
completed -- withdrawal has been executed, account closed or service cancelled.
rejected -- request was denied (e.g., outside cooling-off period, regulatory hold).
Error States
Scenario
HTTP Status
Error Code
Missing/invalid JWT
401
unauthorized
Malformed JSON body
400
bad_request
Invalid reason value
400
validation_error
Database write failure
500
internal_error
Edge Cases
Duplicate requests -- no uniqueness constraint on user_id; a user can submit multiple withdrawal requests. Business logic should handle deduplication at the review stage.
Already deleted user -- the foreign key on user_id ensures the user must exist. If the user record has deleted_at set, the auth middleware should reject the request before it reaches this route.
AML retention -- even after withdrawal is completed, transaction records and AML-related data must be retained for 5 years per hvitvaskingsloven. The data retention cron ( /cron/retention ) handles anonymization after the retention period expires.
Cross-References
Angrerettloven -- Norwegian Act on the Right of Withdrawal (consumer protection).
Data retention -- See src/drop-api/src/routes/cron.ts retention endpoint and docs/architecture/lld/flow-kyc-aml.md for AML retention requirements.
Audit logging -- See src/drop-api/src/lib/audit.ts for audit log implementation.
LLD: Middleware Lifecycle Flow
Middleware Lifecycle — Low-Level Design
Document: LLD-MIDDLEWARE
Status: Approved
Last updated: 2026-02-21
Author: Standards Architect
Applies to: Drop API (Hono) — src/drop-api/src/app.ts
Overview
The Drop API uses Hono as its HTTP framework. Middleware is organized into two layers: global middleware applied to every request via app.use("*") , and per-route middleware applied within individual route handlers. This document describes the complete execution order.
Source of truth: src/drop-api/src/app.ts
Middleware Execution Order
flowchart TD
A["Incoming HTTP Request"] --> B["1. CORS Middleware\n(global)"]
B --> C["2. Request ID Middleware\n(global)"]
C --> D["3. Client IP Middleware\n(global)"]
D --> E["4. Route Matching\n(/v1/* or /api/*)"]
E --> F{Route found?}
F -->|No| G["404 Not Found"]
F -->|Yes| H["5. Per-Route Middleware\n(auth / rateLimit / featureGate)"]
H --> I["6. Route Handler"]
I --> J["Response"]
I -.->|Error thrown| K["Global Error Handler\n(app.onError)"]
K --> J
style A fill:#f5f5f5,stroke:#333
style B fill:#ffd93d,stroke:#333
style C fill:#ffd93d,stroke:#333
style D fill:#ffd93d,stroke:#333
style H fill:#6bcb77,stroke:#333
style I fill:#4d96ff,stroke:#333,color:#fff
style K fill:#ff6b6b,stroke:#333,color:#fff
Global Middleware (Applied to Every Request)
These are registered in app.ts with app.use("*") and execute in registration order, top-to-bottom.
1. CORS ( hono/cors )
Source: app.ts:23-30
Configures Cross-Origin Resource Sharing headers for browser-based clients.
Setting
Value
Allowed origins
http://localhost:3000 , http://localhost:3001 , process.env.APP_URL
Credentials
true (cookies sent cross-origin)
The credentials: true setting is required because the web app sends JWT tokens in httpOnly cookies. Empty strings from unset env vars are filtered out.
2. Request ID
Source: app.ts:33-38
Generates or propagates a unique request identifier for distributed tracing.
Behavior
Detail
Header checked
x-request-id
Fallback
crypto.randomUUID()
Context variable
c.get("requestId")
Response header
x-request-id (echoed back)
Downstream middleware and route handlers access the request ID via c.get("requestId") for structured logging and audit trails.
3. Client IP
Source: app.ts:41-47
Extracts the originating client IP address from proxy headers.
Priority
Header
Processing
1st
x-real-ip
Trimmed
2nd
x-forwarded-for
First entry, trimmed
Fallback
—
127.0.0.1
The extracted IP is stored as c.get("clientIp") and used by rate limiting and audit logging.
Note: The rate-limit.ts module also exports a getClientIp(c) helper that performs the same extraction. Some route handlers use getClientIp(c) directly instead of c.get("clientIp") .
4. Global Error Handler
Source: app.ts:50 , middleware/error-handler.ts:16-23
Registered via app.onError(globalErrorHandler) . This is not middleware in the traditional sense — it is an error boundary that catches any unhandled exceptions thrown during request processing.
Error Type
Response
HTTPException (Hono)
Returns the exception's status and message
All other errors
Logs via logger.error , reports to Sentry via captureError , returns 500 Internal Server Error with generic message
The error handler never leaks stack traces or internal details to the client.
Route Mounting
Source: app.ts:53-72
All API routes are mounted under a versioned prefix:
Mount Point
Purpose
/v1/*
Primary API path (mobile + new clients)
/api/*
Backward compatibility during migration
Both mount points serve the identical route handlers — /api is an alias for /v1 .
Mounted Route Groups
Path
Route Module
Primary Middleware
/v1/auth
authRoutes
Rate limiting (inline)
/v1/health
healthRoutes
None (public)
/v1/transactions
transactionRoutes
authMiddleware + rate limiting
/v1/recipients
recipientRoutes
authMiddleware
/v1/rates
rateRoutes
None (public)
/v1/cards
cardRoutes
authMiddleware + feature gate
/v1/merchants
merchantRoutes
merchantMiddleware
/v1/settings
settingsRoutes
authMiddleware
/v1/notifications
notificationRoutes
authMiddleware
/v1/user
userRoutes
authMiddleware
/v1/admin
adminRoutes
adminMiddleware + rate limiting
/v1/consents
consentRoutes
authMiddleware
/v1/complaints
complaintRoutes
authMiddleware
/v1/cron
cronRoutes
Varies
/v1/withdrawal
withdrawalRoutes
authMiddleware
Per-Route Middleware
Per-route middleware is applied within individual route files, not globally. It executes after the global middleware chain.
Authentication Middleware ( middleware/auth.ts )
Three variants, all following the same pattern: extract JWT, verify token + session, set c.set("user", ...) .
Middleware
Role Check
Used By
authMiddleware
Any authenticated user
Most routes (transactions, recipients, settings, etc.)
merchantMiddleware
role === 'merchant'
Merchant routes
adminMiddleware
role === 'admin'
Admin routes (audit, screening, STR)
Flow:
Extract bearer token from Authorization header or cookie
Verify JWT signature (HS256) and check session in sessions table
If invalid or expired: return 401 Unauthorized
If role mismatch (merchant/admin variants): return 403 Forbidden
Set c.set("user", authUser) for downstream handlers
Rate Limiting ( middleware/rate-limit.ts )
Rate limiting is not a Hono middleware function — it is a utility called inline within route handlers.
// Example from transactions.ts
if (!(await rateLimit(ip, 10))) {
return c.json({ error: "rate_limited", message: "Too many requests" }, 429);
}
Parameter
Description
ip
Rate limit key (usually client IP, sometimes user:{id} )
limit
Maximum requests per window
windowMs
Window duration in ms (default: 60000 = 1 minute)
Rate limit state is persisted in the rate_limits database table (SQLite/PostgreSQL). Expired entries are cleaned up every 100 checks.
Per-endpoint limits:
Endpoint
Key
Limit
Window
POST /transactions/remittance
IP
10/min
60s
POST /transactions/remittance
user:{id}
3/min
60s
POST /transactions/qr-payment
IP
10/min
60s
POST /transactions/qr-payment
user:{id}
3/min
60s
GET /admin/audit
IP
30/min
60s
GET /admin/screening
IP
30/min
60s
POST /admin/screening
IP
10/min
60s
GET /admin/str
IP
30/min
60s
POST /admin/str
IP
10/min
60s
PATCH /admin/str
IP
10/min
60s
Feature Gates ( lib/feature-flags.ts )
Feature gates control access to unreleased functionality. Like rate limiting, they are called inline within route handlers, not as Hono middleware.
// Example from cards.ts
if (!isEnabled("virtualCards")) {
return c.json({ error: "not_found", message: "Feature not available" }, 404);
}
Flag
Default
Controls
virtualCards
false
Card creation, listing, detail, cancellation
physicalCards
false
Physical card ordering
cardDetails
false
Card detail endpoint
cardFreeze
false
Card freeze/unfreeze
cardPin
false
Card PIN management
spendingLimits
false
Spending limit management
notifications
true
Notification endpoints
merchantDashboard
true
Merchant dashboard
Flags are read from environment variables ( FF_VIRTUAL_CARDS=true ) with fallback to compiled defaults. The featureGate() helper throws an HTTPException(404) for disabled features, which the global error handler catches.
Complete Request Lifecycle (Sequence Diagram)
sequenceDiagram
participant Client
participant CORS as CORS Middleware
participant ReqID as Request ID Middleware
participant IP as Client IP Middleware
participant Router as Hono Router
participant Auth as Auth Middleware
participant RL as Rate Limiter
participant FG as Feature Gate
participant Handler as Route Handler
participant DB as Database
participant ErrH as Error Handler
Client->>CORS: HTTP Request
CORS->>CORS: Check origin, set CORS headers
CORS->>ReqID: next()
ReqID->>ReqID: Extract/generate x-request-id
ReqID->>IP: next()
IP->>IP: Extract client IP from headers
IP->>Router: next()
Router->>Router: Match route (/v1/* or /api/*)
alt Public route (health, rates)
Router->>Handler: Direct execution
else Authenticated route
Router->>Auth: authMiddleware / adminMiddleware / merchantMiddleware
Auth->>DB: Verify JWT + session
alt Token invalid
Auth-->>Client: 401 Unauthorized
else Token valid
Auth->>Auth: Set c.user
Auth->>RL: Check rate limit (inline)
alt Rate exceeded
RL-->>Client: 429 Too Many Requests
else Within limit
RL->>FG: Check feature flag (if applicable)
alt Feature disabled
FG-->>Client: 404 Feature not available
else Feature enabled
FG->>Handler: Execute route logic
Handler->>DB: Query/mutation
Handler-->>Client: JSON response
end
end
end
end
Note over Handler,ErrH: If any error is thrown
Handler-->>ErrH: Unhandled error
ErrH->>ErrH: Log + Sentry report
ErrH-->>Client: 500 Internal Server Error
Input Validation
Input validation is not middleware — it is a collection of utility functions in middleware/validation.ts called directly by route handlers.
Function
Purpose
Used By
sanitizeText(text, maxLength)
Strip HTML tags, control characters, truncate
All text input fields
validatePhone(phone)
International phone format ( + prefix, 8-15 digits)
User profile
validateAmount(amount)
Positive number, max 2 decimal places
Transactions
validateIBAN(iban)
ISO 13616 IBAN checksum validation
Bank accounts
validatePIN(pin)
Exactly 4 digits
Card PIN
validateEmail(email)
Basic email format
Registration
validateCurrency(currency)
Whitelist: EUR, USD, GBP, BAM, CHF, PLN, NOK, RSD, TRY, PKR
Transactions
validateName(name)
Non-empty, contains letters, no script injection
Recipients
validateLanguage(lang)
Whitelist: nb, en, bs, sq
Settings
auditLog(...)
Insert audit trail record
All significant actions
Cross-References
Security Architecture — Trust boundaries, STRIDE, application security controls
Authentication — JWT, session management, BankID OIDC
API Reference — Endpoint specifications and security requirements
Login Authentication Flow — BankID OIDC authentication detail