feat(audit): Audit Log ledger and STAC Service Account

[KinshukSS2]

PR 2 — Audit Log & Service Account

Branch: feat/audit-log-stac → base: feat/auth-foundation-phase0

📎 Stacked on: PR 1 — Auth Foundation (feat/auth-foundation-phase0)

---

What This PR Does

Adds the append-only audit trail infrastructure required by the STAC/ODRL access governance layer.

---

Files Changed

File	Lines	Description
database/migrations/003_audit_log.sql	+106 (new file)	Creates sensorthings."AuditLog" table with UUID PK, role FK, action CHECK constraint, JSONB payload, 2 btree indexes, and append-only REVOKE/GRANT
api/app/db/audit_crud.py	+112 (new file)	Async helper log_audit_event() that accepts a caller-provided connection for transactional composability

Total: 2 files, 218 insertions

---

Schema — sensorthings."AuditLog"

id             UUID        PRIMARY KEY DEFAULT gen_random_uuid()
actor_id       BIGINT      FK → "User"(id) ON DELETE SET NULL  -- NULL = anonymous
action_type    VARCHAR(50) NOT NULL CHECK IN (
                   'PUBLIC_READ', 'RESTRICTED_REQUEST', 'ADMIN_APPROVAL')
dataset_id     TEXT        -- STAC dataset identifier
odrl_policy_id TEXT        -- ODRL policy reference
payload        JSONB       DEFAULT NULL
created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()

Append-only: UPDATE and DELETE are revoked from all roles (administrator, user, sensor, guest, qc). Only INSERT is granted to user and sensor.

---

Key Design Decisions

Decision	Rationale
UUID PK	Avoids sequential ID leakage; safe to expose in external APIs
actor_id nullable	Supports anonymous PUBLIC_READ events without a User row
ON DELETE SET NULL	Deleting a user never silently removes their audit history
REVOKE after RESET ROLE	Follows istsos_auth.sql lines 398–444 pattern; runs as session superuser
conn passed in by caller	Lets callers include the INSERT in the same transaction as the logged action
json.dumps() + ::jsonb cast	Required by asyncpg strict typing; follows oidc_user_crud.py line 104 pattern

---

Service Account Script

Run this manually in psql — do not commit it. Replace the password hash before running in any real environment.

-- ============================================================
-- STAC Connector Service Account — run manually, do NOT commit
-- ============================================================

-- To regenerate the bcrypt hash for a real password, run:
--   python3 -c "from passlib.context import CryptContext; \
--               print(CryptContext(schemes=['bcrypt']).hash('YOUR_REAL_PASSWORD'))"

BEGIN;

INSERT INTO sensorthings."User" (username, role, password, status)
VALUES (
    'stac_connector_bot',
    'administrator',
    -- bcrypt hash of 'changeme' — REPLACE before deploying
    '$2b$12$8sbp6m56Nw7ZnsWl1jctnu85uZlTFxddZmF.CjFDXtQokGoBsf9Ya',
    'active'
)
RETURNING id;

-- Set the uri using the id returned above (replace <id> with actual value)
-- or run as a single statement with a CTE:

WITH inserted AS (
    UPDATE sensorthings."User"
    SET uri = '/Users(' || id || ')'
    WHERE username = 'stac_connector_bot'
    RETURNING id, username, uri
)
SELECT * FROM inserted;

COMMIT;

---

Checklist

• Migration uses ADD … IF NOT EXISTS / CREATE TABLE IF NOT EXISTS — idempotent
• gen_random_uuid() — pgcrypto already loaded in istsos_schema.sql
• REVOKE/GRANT after RESET ROLE — matches istsos_auth.sql pattern
• json.dumps + ::jsonb cast — asyncpg type safety
• conn parameter — composable inside caller transactions
• Service account script is not in a migration file
• Branch stacked on feat/auth-foundation-phase0 (8f8c359)
• No existing tables, endpoints, or tests modified