# Security and Tenancy

This document describes planned security and tenant-isolation expectations. It is planning-only and does not implement controls.

## Status labels

- **Approved foundation** — already established by the repository documentation.
- **Recommended direction** — the preferred approach, subject to product-owner approval.
- **Deferred decision** — intentionally decided later.
- **Open question** — requires product-owner input.

## Authentication security

- **Recommended direction** — Support email-and-password registration, email verification, secure one-way password hashing, password resets, Google OAuth/OpenID Connect login, and safe Google identity linking.
- **Recommended direction** — Password signup creates an unverified global user account or secure pending-registration record before email verification. Organization creation, owner membership creation, and trial activation occur only after verification and must be idempotent.
- **Recommended direction** — A verified email claim from an appropriately validated Google OAuth/OpenID Connect provider may satisfy email verification. External identities must be linked only after verifying ownership and preventing account-linking conflicts; accounts must not be merged solely from an untrusted or unverified email value.
- **Recommended direction** — Passwords must never be reversibly encrypted.
- **Recommended direction** — Login rate limiting, account lockout and recovery considerations, logout from all devices, and MFA-ready architecture are required for owners, editors, and platform administrators.
- **Recommended direction** — Password-reset and email-verification tokens should be time-limited, single-use, stored only as hashes, and redacted from logs.

## Authorization and tenant isolation

- **Approved foundation** — Organizations are the tenant boundary.
- **Approved foundation** — Users are global accounts and may belong to multiple organizations through membership records, with an organization-specific role in each organization.
- **Recommended direction** — Use a shared application and shared MySQL database with strict organization-level tenant isolation.
- **Recommended direction** — Organization-owned records contain an organization scope, and all reads, writes, lists, searches, exports, downloads, background jobs, caches, sessions, files, and audit logs enforce that scope.
- **Recommended direction** — The application must derive trusted server-side active-organization context from authenticated membership and verified domain/session state, not from untrusted client-provided organization identifiers alone.
- **Recommended direction** — Authorization must verify both user permission and organization membership for the active organization.
- **Recommended direction** — Users must not access another tenant by changing organization identifiers in URLs, forms, JSON bodies, headers, cookies, or API requests.
- **Recommended direction** — Automated tests must prove Organization A cannot read, modify, list, search, export, download, or infer Organization B's information.

## Sensitive-data handling

| Information | Handling |
| --- | --- |
| Password hashes | **Recommended direction** — Store in the database using a secure one-way password hashing algorithm; never log or encrypt reversibly. |
| Password-reset tokens | **Recommended direction** — Store only hashes in the database; redact from logs. |
| Email-verification tokens | **Recommended direction** — Store only hashes in the database; redact from logs. |
| Google access and refresh tokens | **Recommended direction** — Encrypt at rest if stored; redact from logs; request minimal scopes. |
| Stripe identifiers | **Recommended direction** — Store non-secret customer, subscription, price, and event identifiers in the database as needed. |
| Stripe webhook secrets | **Recommended direction** — Store in environment configuration only; never store in the database or logs. |
| Application encryption keys | **Recommended direction** — Store in environment configuration or a secrets manager; never store in the same database records as encrypted values they protect. |
| Database credentials | **Recommended direction** — Store in environment configuration or a secrets manager; redact from logs. |
| Email credentials | **Recommended direction** — Store in environment configuration or a secrets manager; redact from logs. |
| Session cookies | **Recommended direction** — Secure, HTTP-only, SameSite-aware, environment-specific cookies scoped only to the appropriate hostname; do not log values. |
| Backup credentials | **Recommended direction** — Store outside the database in environment configuration or a secrets manager; restrict access and redact from logs. |
| Customer files | **Recommended direction** — Store with tenant-aware paths or object keys, access controls, malware/type checks where appropriate, and encryption at rest when supported. |
| Audit logs | **Recommended direction** — Store security-relevant metadata without passwords, hashes, reset tokens, OAuth tokens, Stripe secrets, payment-card information, or full sensitive request bodies. |

## Web security controls

- **Recommended direction** — CSRF protection must protect state-changing browser requests.
- **Recommended direction** — XSS protection should combine server-side escaping, safe Blade defaults, validation, content security controls where practical, and careful handling of user-generated content.
- **Recommended direction** — SQL-injection prevention should rely on parameterized queries, ORM/query-builder safeguards, validation, and review of raw SQL if ever required.
- **Recommended direction** — Rate limiting should apply to login, password reset, email verification resend, invitation, checkout creation, domain verification, export creation, and other abuse-prone actions.

## Secure file handling

- **Recommended direction** — File records and storage paths/object keys must be tenant-aware.
- **Recommended direction** — Downloads must verify organization membership, permission, file ownership, lifecycle state, and safe storage references.
- **Recommended direction** — Exports must be generated and downloaded only within the authorized organization context.

## Audit logging

- **Recommended direction** — Audit signup, successful and failed login, logout, password reset, Google account linking, organization creation, invitations, invitation acceptance, role changes, user removal, branding changes, custom-domain changes, subscription changes, data exports, account suspension, reactivation, account deletion, platform-administrator support access, and security-sensitive configuration changes.
- **Recommended direction** — Audit logs should include actor, organization context where applicable, target, event type, timestamp, result, and safe metadata.
- **Recommended direction** — Audit logs must not include passwords, password hashes, reset tokens, OAuth tokens, Stripe secrets, payment-card information, or full sensitive request bodies.

## Platform-administrator access

- **Recommended direction** — Platform administrators are separate from organization administrators.
- **Recommended direction** — Support access should be explicit, least-privilege, time-bounded where possible, audited, and subject to product-owner rules.

## Customer-owned domain authentication handoff

- **Deferred decision** — Browser session cookies cannot be shared across unrelated customer-owned domains such as `staff.customer.com` and a central Cloutal login domain. A future reviewed architecture decision must choose between central authentication followed by a short-lived signed handoff or separate authenticated sessions established independently on each customer domain.
- **Recommended direction** — Reusable session credentials must never be placed in query strings.
- **Recommended direction** — Any handoff token must be short-lived, single-use, audience-bound to the intended hostname, and protected against replay.
- **Recommended direction** — The destination hostname must already be verified and mapped to the correct organization before a handoff is issued or accepted.
- **Recommended direction** — Customer-domain session cookies must be Secure, HTTP-only, SameSite-aware, and scoped only to the appropriate hostname.
- **Recommended direction** — OAuth callbacks should remain centralized where practical to avoid per-customer callback sprawl.

## Backup protection

- **Recommended direction** — MySQL backups should be encrypted, stored off-server, monitored for success, retained according to policy, and periodically restore-tested.
- **Recommended direction** — Backup locations, credentials, and encryption keys must be separate between UAT and production.

## Security testing and incident readiness

- **Recommended direction** — Security tests should cover tenant boundaries, authorization denials, token handling, webhook signatures, idempotency, rate limits, file access, audit-log redaction, and replay-resistant customer-domain authentication handoffs if introduced.
- **Recommended direction** — Incident-response readiness should include alerting, escalation paths, evidence preservation, customer communication criteria, and recovery playbooks.

## Open questions

- **Open question** — Is MFA mandatory for any roles at launch?
- **Open question** — What support-access approval workflow is required for platform administrators?
- **Open question** — What audit-log retention period is required?