Christian Krakau-Louis
138 lines
5.3 KiB
Markdown
138 lines
5.3 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|