Update migration files and refactor tests for audit population (#49)

Author: laraibg786

.codacy.yml

@@ -1,6 +1,5 @@
-include_paths:
-  - "backend/**"
-  - "migrations/**"
+include_paths: ["backend/**"]
 exclude_paths:
   - ".github/**"
-  - "backend/tests/**"
+  - "**/tests/**"
+  - "migrations/**"

.github/workflows/code_test.yml

@@ -76,10 +76,6 @@ jobs:
   test_migrations:
     runs-on: ubuntu-latest
 
-    permissions:
-      id-token: write
-      contents: read
-
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v6
@@ -88,12 +84,4 @@ jobs:
 
       - name: Migration tests
         run: |
-          uv run --with coverage,pytest-cov \
-            python -m pytest migrations/test_migrations.py -n auto --cov --cov-report=xml
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          fail_ci_if_error: true
-          use_oidc: true
-          verbose: true
+          uv run migrations/run_tests.py -n auto

.github/workflows/sonarcloud.yml

@@ -4,10 +4,9 @@ permissions:
   contents: read
 on:
   push:
-    branches:
-      - main
+    branches: [ main ]
   pull_request:
-    types: [opened, synchronize, reopened]
+    branches: [ main ]
 
 jobs:
   sonarqube:

backend/__init__.py

@@ -49,14 +49,24 @@
 --   (e.g. license_status_code = 'ACTIVE' is readable without a
 --   join). New enum values are added by INSERT only — no UPDATE
 --   or DELETE of existing rows is ever permitted.
+--
+-- ACTION CODE DESIGN
+--   Action codes in reference."actions" are intentionally
+--   resource-agnostic. The resource type and ID are captured
+--   in audit junction tables (audit_log_licenses,
+--   audit_log_sessions, audit_log_vendor_actors). A REVOKED
+--   entry joined to audit_log_licenses means a license was
+--   revoked; joined to audit_log_sessions means a session was
+--   revoked. This allows new resource types to be added in
+--   future without introducing new action codes for common verbs.
 -- ============================================================
 
 BEGIN;
 
 -- Switch to the schema owner so that default privileges defined
 -- in 01_roles.sql for reference_owner apply to all objects
 -- created in this transaction.
-SET LOCAL ROLE reference_owner;
+SET LOCAL ROLE "reference_owner";
 
 -- ============================================================
 -- reference."license_statuses"
@@ -68,7 +78,7 @@ SET LOCAL ROLE reference_owner;
 -- ============================================================
 
 DO $$ BEGIN
-    CREATE TABLE reference."license_statuses" (
+    CREATE TABLE "reference"."license_statuses" (
         "code"        TEXT PRIMARY KEY,
         "description" TEXT NOT NULL
     );
@@ -77,11 +87,11 @@ EXCEPTION WHEN duplicate_table THEN
 END $$;
 
 -- COMMENT ON is idempotent and intentionally outside the DO block.
-COMMENT ON TABLE  reference."license_statuses"               IS 'Lookup table for license lifecycle states. EXPIRED is intentionally omitted: expiry is a derived state computed at query time from app."licenses"."expires_at". Storing it redundantly would risk inconsistency.';
-COMMENT ON COLUMN reference."license_statuses"."code"        IS 'Machine-readable status code (PK). Self-documents FK references in app."licenses". Examples: ACTIVE, REVOKED.';
-COMMENT ON COLUMN reference."license_statuses"."description" IS 'Human-readable explanation of this license state for developers and operators.';
+COMMENT ON TABLE  "reference"."license_statuses"               IS 'Lookup table for license lifecycle states. EXPIRED is intentionally omitted: expiry is a derived state computed at query time from "app"."licenses"."expires_at". Storing it redundantly would risk inconsistency.';
+COMMENT ON COLUMN "reference"."license_statuses"."code"        IS 'Machine-readable status code (PK). Self-documents FK references in "app"."licenses". Examples: ACTIVE, REVOKED.';
+COMMENT ON COLUMN "reference"."license_statuses"."description" IS 'Human-readable explanation of this license state for developers and operators.';
 
-INSERT INTO reference."license_statuses" ("code", "description")
+INSERT INTO "reference"."license_statuses" ("code", "description")
 VALUES
     ('ACTIVE',  'License is valid and can be activated by a customer device.'),
     ('REVOKED', 'License was manually revoked by the vendor; no further activations or heartbeats are permitted.')
@@ -96,19 +106,19 @@ ON CONFLICT ("code") DO NOTHING;
 -- ============================================================
 
 DO $$ BEGIN
-    CREATE TABLE reference."session_statuses" (
+    CREATE TABLE "reference"."session_statuses" (
         "code"        TEXT PRIMARY KEY,
         "description" TEXT NOT NULL
     );
 EXCEPTION WHEN duplicate_table THEN
     RAISE NOTICE 'table reference."session_statuses" already exists, skipping';
 END $$;
 
-COMMENT ON TABLE  reference."session_statuses"               IS 'Lookup table for session lifecycle states. Derived states (grace period exceeded, license expired) are computed at query time, not stored.';
-COMMENT ON COLUMN reference."session_statuses"."code"        IS 'Machine-readable status code (PK). Values: ACTIVE, REVOKED, ZOMBIE, CLEANUP.';
-COMMENT ON COLUMN reference."session_statuses"."description" IS 'Human-readable explanation of this session state for developers and operators.';
+COMMENT ON TABLE  "reference"."session_statuses"               IS 'Lookup table for session lifecycle states. Derived states (grace period exceeded, license expired) are computed at query time, not stored.';
+COMMENT ON COLUMN "reference"."session_statuses"."code"        IS 'Machine-readable status code (PK). Values: ACTIVE, REVOKED, ZOMBIE, CLEANUP.';
+COMMENT ON COLUMN "reference"."session_statuses"."description" IS 'Human-readable explanation of this session state for developers and operators.';
 
-INSERT INTO reference."session_statuses" ("code", "description")
+INSERT INTO "reference"."session_statuses" ("code", "description")
 VALUES
     ('ACTIVE',  'Session is running and receiving heartbeats normally.'),
     ('REVOKED', 'Session was explicitly terminated by a vendor action or an automated system process.'),
@@ -124,19 +134,19 @@ ON CONFLICT ("code") DO NOTHING;
 -- ============================================================
 
 DO $$ BEGIN
-    CREATE TABLE reference."heartbeat_resp_statuses" (
+    CREATE TABLE "reference"."heartbeat_resp_statuses" (
         "code"        TEXT PRIMARY KEY,
         "description" TEXT NOT NULL
     );
 EXCEPTION WHEN duplicate_table THEN
     RAISE NOTICE 'table reference."heartbeat_resp_statuses" already exists, skipping';
 END $$;
 
-COMMENT ON TABLE  reference."heartbeat_resp_statuses"               IS 'Lookup table for heartbeat response codes returned by the server to the SDK. The server selects a code based on current license and session state; the SDK takes a mandatory action based on the code received.';
-COMMENT ON COLUMN reference."heartbeat_resp_statuses"."code"        IS 'Machine-readable response code (PK). Values: CONTINUE, REFRESH, REVOKED, EXPIRED, ERROR.';
-COMMENT ON COLUMN reference."heartbeat_resp_statuses"."description" IS 'Human-readable description of the response code and the SDK action it mandates.';
+COMMENT ON TABLE  "reference"."heartbeat_resp_statuses"               IS 'Lookup table for heartbeat response codes returned by the server to the SDK. The server selects a code based on current license and session state; the SDK takes a mandatory action based on the code received.';
+COMMENT ON COLUMN "reference"."heartbeat_resp_statuses"."code"        IS 'Machine-readable response code (PK). Values: CONTINUE, REFRESH, REVOKED, EXPIRED, ERROR.';
+COMMENT ON COLUMN "reference"."heartbeat_resp_statuses"."description" IS 'Human-readable description of the response code and the SDK action it mandates.';
 
-INSERT INTO reference."heartbeat_resp_statuses" ("code", "description")
+INSERT INTO "reference"."heartbeat_resp_statuses" ("code", "description")
 VALUES
     ('CONTINUE', 'License is valid and the session is healthy. SDK should continue normal protected operation with no state change.'),
     ('REFRESH',  'The vendor has modified the license configuration since the last heartbeat (e.g. expiry extended, max_grace_secs changed, metadata updated). SDK must re-fetch the current license state and apply it before continuing.'),
@@ -154,19 +164,19 @@ ON CONFLICT ("code") DO NOTHING;
 -- ============================================================
 
 DO $$ BEGIN
-    CREATE TABLE reference."error_codes" (
+    CREATE TABLE "reference"."error_codes" (
         "code"        TEXT PRIMARY KEY,
         "description" TEXT NOT NULL
     );
 EXCEPTION WHEN duplicate_table THEN
     RAISE NOTICE 'table reference."error_codes" already exists, skipping';
 END $$;
 
-COMMENT ON TABLE  reference."error_codes"               IS 'Canonical lookup table for business error codes used in API responses and SDK error handling. HTTP status code mapping is handled exclusively in application code and is decoupled from this table.';
-COMMENT ON COLUMN reference."error_codes"."code"        IS 'Machine-readable error code constant (PK). Referenced by API responses, SDK error handlers, and log entries.';
-COMMENT ON COLUMN reference."error_codes"."description" IS 'Human-readable explanation of the error condition for developers and operators.';
+COMMENT ON TABLE  "reference"."error_codes"               IS 'Canonical lookup table for business error codes used in API responses and SDK error handling. HTTP status code mapping is handled exclusively in application code and is decoupled from this table.';
+COMMENT ON COLUMN "reference"."error_codes"."code"        IS 'Machine-readable error code constant (PK). Referenced by API responses, SDK error handlers, and log entries.';
+COMMENT ON COLUMN "reference"."error_codes"."description" IS 'Human-readable explanation of the error condition for developers and operators.';
 
-INSERT INTO reference."error_codes" ("code", "description")
+INSERT INTO "reference"."error_codes" ("code", "description")
 VALUES
     ('INVALID_CREDENTIALS',   'Authentication failed due to incorrect email or password.'),
     ('INVALID_TOKEN',         'JWT access token is missing, malformed, or has expired.'),
@@ -185,41 +195,52 @@ ON CONFLICT ("code") DO NOTHING;
 -- ============================================================
 -- reference."actions"
 -- ============================================================
--- Auditable action verbs recorded in audit."auditLogs".
+-- Auditable action verbs recorded in audit."audit_logs".
 -- Codes are broadly resource-agnostic; the affected resource
 -- is captured in audit junction tables. This allows new
--- resource types to be added without modifying audit."auditLogs".
--- Exception: HEARTBEAT_ERROR is heartbeat-specific by nature
--- and is an intentional exception to the resource-agnostic
--- principle — documented here to prevent future confusion.
+-- resource types to be added without modifying audit."audit_logs".
+-- Exceptions to the resource-agnostic principle (documented
+-- here to prevent future confusion):
+--   HEARTBEAT_ERROR   — heartbeat-specific by nature
+--   PASSWORD_CHANGED  — vendor-specific by nature
+--   TOKEN_ROTATED     — session-specific by nature
+--   TOKEN_REFRESHED   — vendor auth flow specific
+--   ACTIVATED         — session creation via license activation
+--   LOGIN_SUCCESS     — vendor auth flow specific
+--   LOGIN_FAILED      — vendor auth flow specific
+--   CLEANED           — session CLEANUP transition, system-driven
 -- ============================================================
 
 DO $$ BEGIN
-    CREATE TABLE reference."actions" (
+    CREATE TABLE "reference"."actions" (
         "code"        TEXT PRIMARY KEY,
         "description" TEXT NOT NULL
     );
 EXCEPTION WHEN duplicate_table THEN
     RAISE NOTICE 'table reference."actions" already exists, skipping';
 END $$;
 
-COMMENT ON TABLE  reference."actions"               IS 'Lookup table for auditable action verbs recorded in audit."auditLogs". Codes are broadly resource-agnostic; the affected resource is captured in audit junction tables (audit."auditLogLicenses", audit."auditLogSessions", etc.). HEARTBEAT_ERROR is an intentional exception: it is heartbeat-specific by nature.';
-COMMENT ON COLUMN reference."actions"."code"        IS 'Machine-readable action verb (PK). Examples: CREATED, MODIFIED, REVOKED, DELETED.';
-COMMENT ON COLUMN reference."actions"."description" IS 'Human-readable description of what this action represents in the system.';
+COMMENT ON TABLE  "reference"."actions"               IS 'Lookup table for auditable action verbs recorded in "audit"."audit_logs". Codes are broadly resource-agnostic; the affected resource is captured in audit junction tables ("audit"."audit_log_licenses", "audit"."audit_log_sessions", etc.). Exceptions (HEARTBEAT_ERROR, PASSWORD_CHANGED, TOKEN_ROTATED, etc.) are heartbeat- or auth-flow-specific by nature and are documented in the migration file header.';
+COMMENT ON COLUMN "reference"."actions"."code"        IS 'Machine-readable action verb (PK). Examples: CREATED, MODIFIED, REVOKED, DELETED.';
+COMMENT ON COLUMN "reference"."actions"."description" IS 'Human-readable description of what this action represents in the system.';
 
-INSERT INTO reference."actions" ("code", "description")
+INSERT INTO "reference"."actions" ("code", "description")
 VALUES
-    ('SIGNUP',          'A new actor account was registered on the platform.'),
-    ('LOGIN_SUCCESS',   'An actor successfully authenticated and received an access token.'),
-    ('LOGIN_FAILED',    'An actor authentication attempt failed due to invalid credentials.'),
-    ('TOKEN_REFRESHED', 'An actor obtained a new access token using a valid refresh token.'),
-    ('CREATED',         'A new resource was created.'),
-    ('MODIFIED',        'An existing resource was modified.'),
-    ('REVOKED',         'A resource was revoked by an authorised actor.'),
-    ('EXPIRED',         'A resource was transitioned to an expired state by the system.'),
-    ('ACTIVATED',       'A new session was created via a successful license key activation.'),
-    ('HEARTBEAT_ERROR', 'A heartbeat was received but produced a non-CONTINUE response; the event is recorded in app."heartbeats" for audit continuity.'),
-    ('DELETED',         'A resource was soft-deleted.')
+    ('SIGNUP',           'A new vendor account was registered on the platform.'),
+    ('LOGIN_SUCCESS',    'A vendor successfully authenticated and received an access token.'),
+    ('LOGIN_FAILED',     'A vendor authentication attempt failed due to invalid credentials.'),
+    ('TOKEN_REFRESHED',  'A vendor obtained a new access token using a valid refresh token.'),
+    ('CREATED',          'A new resource was created.'),
+    ('MODIFIED',         'An existing resource had one or more fields modified.'),
+    ('CONFIG_UPDATED',   'Structural policy configuration of a resource was changed (e.g. expires_at, max_grace_secs, max_sessions).'),
+    ('REVOKED',          'A resource was revoked by an authorised actor.'),
+    ('EXPIRED',          'A resource was transitioned to an expired state by the system.'),
+    ('ACTIVATED',        'A new session was created via a successful license key activation.'),
+    ('TOKEN_ROTATED',    'A session bearer token was rotated. Hash values are never recorded.'),
+    ('HEARTBEAT_ERROR',  'A heartbeat was received but produced a non-CONTINUE response; the event is recorded in app."heartbeats" for audit continuity.'),
+    ('DELETED',          'A resource was soft-deleted.'),
+    ('PASSWORD_CHANGED', 'A vendor account password was changed. Hash values are never recorded.'),
+    ('CLEANED',          'A session was transitioned to CLEANUP status by the system cleanup job.')
 ON CONFLICT ("code") DO NOTHING;
 
 COMMIT;