Workspace Foundations

DMARQ uses a workspace as the tenant boundary for multi-organization and MSP deployments. Milestone 15 starts with a default single-tenant workspace so existing deployments have a clear migration path before workspace RBAC and MSP views are added.

Default Workspace

Existing installs are migrated into:

slug: default
name: Default Workspace

The migration attaches legacy domains, users, and mail sources to this default workspace. New domain rows created by the API also default to this workspace.

Ownership Boundaries

The initial workspace model relates these core records to a workspace:

monitored domains
mail sources
users

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
AI summary generation, action proposal generation/confirmation, and MCP read-only tool calls

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 adds nullable workspace_id ownership columns to existing domain, user, and 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.

Onboarding Templates

Workspace onboarding templates give MSP operators a repeatable way to create a new client workspace with minimal manual configuration. The template API can:

preview a rendered onboarding plan before anything is saved
create or reuse a workspace
seed monitored domains and manual DKIM selectors
seed disabled mail-source shells for IMAP, Gmail, or Microsoft 365
seed safe notification defaults without storing notification target secrets
return an operator checklist for DNS validation, mailbox connection, initial import, and notification testing

Available templates are exposed from GET /api/v1/onboarding/templates. Operators render a plan with POST /api/v1/onboarding/preview and apply it with POST /api/v1/onboarding/apply.

The onboarding response and audit records redact secret-like fields, including passwords, OAuth secrets, tokens, and API keys. Existing domains and mail sources are treated idempotently; duplicate domains owned by another workspace are rejected to keep ownership unambiguous.

Notification defaults currently seed the existing notification settings table. They intentionally avoid Apprise target URLs, so operators still add and test delivery targets explicitly after onboarding.

MSP Operator Views

MSP operator endpoints provide cross-workspace summaries without returning raw DMARC report rows across tenant boundaries. GET /api/v1/operator/workspaces returns one summary per active workspace:

workspace identity and active state
health status derived from domains, enabled mail sources, active alerts, recent failed imports, and missing import history
domain counts and names
mail-source counts and the most recent import status
aggregate report counts
current retention controls
recent workspace audit events as drift indicators

GET /api/v1/operator/workspaces/{workspace_id} returns the same summary for one workspace.

Workspace retention controls are stored on the workspace row:

Field	Purpose	Default
`report_retention_days`	Aggregate DMARC report retention target	400
`forensic_retention_days`	Forensic report retention target	90
`tls_report_retention_days`	SMTP TLS report retention target	400

Operators can update these controls with PUT /api/v1/operator/workspaces/{workspace_id}/retention. Updates are written to the workspace audit log as workspace.retention_updated.

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.

5.3 KiB Raw Blame History