feat: session storage and migration compatibility (Closes #1649)

[ruthoreaji-123]

Closes #1649

Summary

This pull request implements forward and backward compatible session schema versioning for the Remitwise authentication system. Sessions now carry a schemaVersion field, and a transparent migration layer ensures old (V1) sessions continue to work while new sessions are stamped with the current version.

Motivation

The current authentication system stores session data in encrypted cookies using iron-session. However, the SessionData interface has no schema versioning mechanism. This means:

• Any breaking change to the session format (adding required fields, changing field types, restructuring) would silently break all existing sessions upon deployment
• There is no way to detect or handle legacy sessions that don't match the current schema
• Rollbacks after schema changes leave users with unreadable sessions, forcing re-authentication
• There is no observability into how many sessions are migrated on each request

Without this work, deployments losing data or making old records unreadable could survive review or deployment.

What Changed

New: Session Migration Module (lib/auth/session-migration.ts)

A dedicated module providing:

• SESSION_CURRENT_VERSION = 2 — the current session schema version constant
• SESSION_MIN_SUPPORTED_VERSION = 1 — the oldest version the deserializer supports
• detectVersion(raw) — detects the schema version of a raw session object (returns 0 for V1 legacy sessions without schemaVersion)
• isValidSessionShape(raw) — type guard validating address (string), createdAt (number), and expiresAt (number) fields
• migrateSession(raw) — idempotent migration: V1 → V2 (adds schemaVersion). Never throws; returns original data on error.
• recordMigrationAttempt(fromVersion, toVersion, success) — observability tracking migration success/failure/skip counts
• getMigrationStats() — returns current migration statistics for monitoring
• resetMigrationStats() — resets stats (used in tests)

Updated: Session Management (lib/session.ts)

• SessionData interface now includes optional schemaVersion?: number for backward compatibility
• getSession() — decrypts → validates → applies migrateSession() → returns V2 session
• getSessionWithRefresh() — same flow with token refresh logic
• requireAuth() — same flow with 401 response on failure
• createSession() — stamps schemaVersion: SESSION_CURRENT_VERSION on new sessions

Design Invariants

1. Idempotency: migrateSession() called twice on the same data produces the same result. Calling it on already-migrated V2 data returns migrated: false.
2. No partial state: failed or invalid sessions return migrated: false with original data unmodified.
3. Forward compatibility: unknown extra fields in V1 sessions are preserved through migration via JSON spread.
4. Backward compatibility: V2 sessions (with schemaVersion) are readable by any code that understands V2.
5. No silent data loss: invalid shapes are returned as-is; never silently discarded.

Failure Behavior

Scenario	Result
Valid V1 session (no schemaVersion)	Migrated to V2, migrated: true
Valid V2 session (with schemaVersion)	No-op, migrated: false
Invalid shape (missing required fields)	Original data returned, migrated: false
Empty object	Original data returned, migrated: false
V1 with extra unknown fields	Migrated, all fields preserved
Migration function error	Original data returned, migrated: false (never throws)

Backward & Forward Compatibility

• Upgrade: Deploy the new code. V1 sessions are transparently upgraded on first read. No database migration or cookie rotation needed.
• Rollback: If rolled back, V2 sessions with schemaVersion field are still readable — the field is simply ignored by older code since address, createdAt, and expiresAt remain present.
• Re-run: Migration is idempotent — re-running is safe.
• No breaking changes: The schemaVersion field is optional in the TypeScript interface, so existing code that doesn't know about it continues to work.

Migration / Rollback Considerations

• No cookie rotation or forced logout required
• No database migration needed — sessions are stored encrypted in cookies
• Old sessions are transparently migrated on read
• Future schema changes can add new migration steps in migrateSession() following the established pattern

Validation Evidence

Test Results

✓ tests/unit/session-migration.test.ts (35 tests) 16ms

Test Files  1 passed (1)
     Tests  35 passed (35)

Test Coverage

The 35 tests cover:

Category	Tests	Description
detectVersion	5	V1, V2, invalid types, empty object
isValidSessionShape	8	Valid/invalid shapes, wrong types, null values
Upgrade (V1→V2)	3	Adds schemaVersion, preserves fields, preserves extras
Already current	1	V2 session is a no-op
Rollback compatibility	2	V2 readable, unknown fields preserved
Idempotency (rerun)	2	V1 twice = same result, V2 twice = no-op
Invalid data	3	Invalid shape, empty object, missing fields
Partial progress	2	Partial V1, complete V1
Legacy data fixtures	3	Realistic V1, zero timestamps, very large timestamps
Migration stats	4	Tracks success, skip, failed, reset
Version constants	2	current >= min, min = 1

Additional Validation

• Formatter: npx prettier --write applied — all files formatted
• TypeScript check: npx tsc --noEmit — no new errors (pre-existing errors in unrelated files)
• Existing tests: All 26 node-based tests pass, all existing vitest tests unaffected
• No artifacts or secrets: No generated files, no secrets, no disabled checks
• No unrelated refactors: Only in-scope changes

Security / Correctness Note

This change adds a schemaVersion field to session cookies, enabling future schema evolution without breaking existing sessions. The migration is purely additive (adds a field) and is idempotent. No new attack surface is introduced — the migration layer operates on already-decrypted data and only adds metadata. Invalid or corrupted sessions are rejected at the validation layer before migration runs.

Upstream

Target: Remitwise-Org/Remitwise-Frontend main

Closes #1649