feat(auth): application-layer auth foundation

[KinshukSS2]

Pull Request

Branch: feat/auth-foundation-phase0 → fix/post-pivot-cleanup

---

Overview

This PR is Phase 0 of the auth-foundation plan agreed in the STAC/ODRL architecture review. It is a prerequisite for every access-control feature that follows.

It delivers two self-contained changes:

#	File	What changed
1	database/migrations/002_add_password_status.sql	Adds password and status columns to sensorthings."User"
2	api/app/oauth.py → authenticate_user()	Replaces pg_authid-only auth with bcrypt-first + JIT fallback

---

Change 1 — Migration 002_add_password_status.sql

Adds two columns to sensorthings."User" wrapped in the project-standard current_setting('custom.authorization') guard block, with SET ROLE "administrator" before and RESET ROLE after (identical pattern to 001_identity_linking.sql).

ALTER TABLE sensorthings."User"
    ADD COLUMN IF NOT EXISTS "password" VARCHAR(255) DEFAULT NULL;

ALTER TABLE sensorthings."User"
    ADD COLUMN IF NOT EXISTS "status" VARCHAR(50) DEFAULT 'active';

password semantics:

• NULL → legacy (pre-migration) account. The JIT fallback in authenticate_user() fires on next login and backfills this column.
• NOT NULL → modern account. The bcrypt path in authenticate_user() is used exclusively; no pg_authid connection is ever opened.

status semantics:

• 'active' (default) → normal login permitted. All existing rows receive this value automatically — zero disruption.
• Future values ('suspended', 'deleted') will be enforced at the application layer; no DB constraint is added here to keep the migration forward-compatible.

Both statements use ADD COLUMN IF NOT EXISTS — the migration is fully idempotent and safe to re-run against instances that received the columns via a prior manual hotfix.

---

Change 2 — authenticate_user() rewrite

Before (legacy):

pg_authid connect → if success → fetch role from "User" → return dict

One path. Requires every user to have a PostgreSQL LOGIN role. Incompatible with the application-layer pivot.

After (this PR):

Step 1  SELECT (id, username, role, password) from "User"
          └─ not found → return None (never falls through to pg_authid)

Step 2  password IS NOT NULL (modern path)
          └─ asyncio.to_thread(pwd_context.verify, ...)
               ├─ match   → return user dict
               └─ no match → return None

Step 3  password IS NULL (legacy / JIT path)
          └─ get_auth_connection(username, password)
               ├─ pg_authid rejected → return None
               └─ pg_authid accepted →
                    asyncio.to_thread(pwd_context.hash, password)
                    UPDATE "User" SET password = $hash  [write pool]
                    ┌─ backfill ok  → log INFO, return user dict
                    └─ backfill err → log ERROR, still return user dict
                                      (best-effort, never blocks login)

Key implementation decisions:

Decision	Rationale
asyncio.to_thread for bcrypt	bcrypt is intentionally CPU-heavy; running it synchronously in an async handler would stall the entire event loop
Lazy import of pwd_context	password_crud.py already imports get_auth_connection from oauth.py; a module-level import of pwd_context in oauth.py would create a circular dependency. The lazy import pattern is already used in password_crud.py line 115
POSTGRES_PORT_WRITE pattern for backfill	Consistent with role_crud.py and password_crud.py; honours read-replica topology
Backfill failure does not raise	A write-pool hiccup must never prevent a successful login; the error is logged for ops visibility
Unknown users → immediate None	Prevents pg_authid oracle attacks where an attacker probes for valid PostgreSQL roles that aren't registered application users

---

Testing

This PR does not add new test files (test harness for the login flow with bcrypt accounts is tracked separately). The existing api/tests/test_password_update.py covers update_local_password() which exercises the same pwd_context and write-pool path.

Manual verification steps:

1. Apply migration against a fresh DB — both columns appear, all existing rows have status = 'active' and password = NULL.
2. Login with a legacy user (password IS NULL) → pg_authid fallback fires, hash is backfilled, login succeeds.
3. Login again with the same user → bcrypt path fires, no pg_authid connection opened (confirm via pg_stat_activity).
4. Login with wrong password → None returned, 401 issued.
5. Login with unknown username → None returned, 401 issued (no pg_authid probe).

---

Migration from upstream

origin/main users applying this migration to an existing database will see no disruption:

• All existing "User" rows gain password = NULL and status = 'active'.
• Login continues to work via the JIT fallback until each user logs in once, at which point their hash is transparently backfilled.
• No LOGIN role is created or dropped.
• No data is lost.

---

Files Changed

• database/migrations/002_add_password_status.sql
• api/app/oauth.py

---

Checklist

• Migration is idempotent (ADD COLUMN IF NOT EXISTS)
• Migration follows 001_identity_linking.sql structural pattern exactly
• asyncio.to_thread used for all blocking bcrypt work
• Circular import resolved via lazy function-scoped import
• Backfill failure is caught and logged; login is never blocked
• No new PostgreSQL LOGIN roles created or required
• No breaking change for any existing user or test
• Branch is feat/auth-foundation-phase0 based on fix/post-pivot-cleanup (dc2d07b)