feat: add workspace RBAC audit foundations

docs/reference/api.md

@@ -94,6 +94,33 @@ DELETE /api-tokens/{token_id}
 Deactivates a token immediately. Revoked tokens can no longer access public API
 endpoints.
 
+### Workspace Audit
+
+#### List Workspace Roles
+
+```text
+GET /audit/roles
+```
+
+Returns the supported workspace RBAC roles and their permission strings.
+
+#### List Workspace Audit Logs
+
+```text
+GET /audit/logs
+```
+
+Returns recent sanitized audit events for the default workspace. Optional
+filters:
+
+| Query parameter | Purpose |
+| --- | --- |
+| `limit` | Number of rows to return, from 1 to 200 |
+| `action` | Restrict to one action key |
+| `entity_type` | Restrict to one entity category |
+
+Audit details redact secret-like fields before they are stored.
+
 ### Domains
 
 #### List Domains

docs/reference/database.md

@@ -28,6 +28,40 @@ workspace during migration.
 | created_at | TIMESTAMP | When the workspace was created |
 | updated_at | TIMESTAMP | When the workspace was last updated |
 
+### Workspace_Memberships
+
+The `workspace_memberships` table stores user role assignments for workspace
+RBAC.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | INTEGER | Primary key |
+| workspace_id | INTEGER | Foreign key to workspaces.id |
+| user_id | INTEGER | Foreign key to users.id |
+| role | VARCHAR(50) | Workspace role such as workspace_owner or analyst |
+| active | BOOLEAN | Whether the membership can be used |
+| created_at | TIMESTAMP | When the membership was created |
+| updated_at | TIMESTAMP | When the membership was last updated |
+
+### Workspace_Audit_Logs
+
+The `workspace_audit_logs` table records sanitized sensitive actions per
+workspace so operators can answer who changed what and when.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | INTEGER | Primary key |
+| workspace_id | INTEGER | Foreign key to workspaces.id |
+| actor_type | VARCHAR(50) | Authentication type, such as session or api_key |
+| actor_id | VARCHAR(120) | User, token, or auth actor identifier |
+| action | VARCHAR(100) | Stable action key, such as mail_source.updated |
+| entity_type | VARCHAR(80) | Entity category affected |
+| entity_id | VARCHAR(120) | Affected entity identifier |
+| entity_name | VARCHAR(255) | Optional display name for the entity |
+| details | TEXT | Sanitized JSON details with secret fields redacted |
+| ip_address | VARCHAR(64) | Client IP when available |
+| created_at | TIMESTAMP | When the action happened |
+
 ### Domains
 
 The `domains` table stores information about the domains being monitored.

docs/reference/workspaces.md

@@ -29,6 +29,40 @@ Domain, mail-source, and user query helpers scope reads to a workspace by
 default. This prevents cross-tenant reads in new M15 surfaces and gives later
 RBAC work a single ownership field to enforce.
 
+## Roles And Permissions
+
+DMARQ defines these workspace roles as the RBAC vocabulary for MSP mode:
+
+| Role | Intended operator |
+|------|-------------------|
+| `workspace_owner` | Full workspace administrator |
+| `domain_admin` | Domain and mail-source administrator |
+| `operator` | Day-to-day operations and notification management |
+| `analyst` | Reporting and posture reader |
+| `auditor` | Audit and report reader |
+
+The role catalog is available from `GET /api/v1/audit/roles`. Current admin
+sessions and admin API keys map to `workspace_owner` until membership management
+screens are added.
+
+## Audit Logs
+
+The `workspace_audit_logs` table stores sanitized records for sensitive
+workspace actions. `GET /api/v1/audit/logs` returns recent audit events for the
+default workspace and can filter by `action` or `entity_type`.
+
+Current audit coverage includes:
+
+- API token creation and revocation
+- mail-source creation, update, deletion, enable/disable toggles, and OAuth
+  connect/disconnect actions
+- notification and forensic setting changes
+- webhook creation, update, disable, and test actions
+- manual DKIM selector add/remove actions
+
+Audit details redact secret-like fields such as passwords, OAuth tokens, API
+keys, and webhook signing secrets.
+
 ## Migration Story
 
 The migration creates the `workspaces` table, inserts the default workspace, and
@@ -37,6 +71,9 @@ mail-source tables. Nullable columns keep upgrades safe for older databases and
 for import paths that may be backfilled in stages; runtime helpers attach
 legacy rows to the default workspace when needed.
 
+The RBAC/audit migration adds `workspace_memberships` for role assignments and
+`workspace_audit_logs` for workspace-scoped change history.
+
 The current implementation keeps domain names globally unique. That matches the
 existing single-domain ownership model and avoids ambiguous ownership while MSP
 RBAC and onboarding controls are built out.