# Tenancy Overview

StellaOps is designed for strict multi-tenancy. Tenancy is an explicit input to requests, storage, and exported evidence so decisions remain auditable and replayable (including in air-gapped deployments).

## Tenant Identity

- A **tenant** is the primary isolation boundary for data, policies, issuers/trust settings, and workflow objects (exceptions, approvals, exports).
- Requests are tenant-scoped via `X-StellaOps-Tenant: <tenantId>` and/or tenant claims in tokens (depending on deployment).

Optional sub-scoping (environment/project/workspace) is supported via ABAC claims and module-specific selectors, but does not replace the tenant boundary.

## Isolation Guarantees

StellaOps aims for defense-in-depth isolation:

- **Database isolation:** each service owns its schema; tenant scoping is enforced on every query, typically via `tenant_id` columns and Row-Level Security where appropriate.
- **Cache isolation:** cache keys and stream partitions are tenant-aware (and may use per-tenant databases in Redis/Valkey-compatible stores when configured).
- **Object storage isolation:** stored artifacts and evidence bundles are content-addressed and namespaced so tenant boundaries are preserved even when sharing infrastructure.
- **Audit boundaries:** audit trails are tenant-scoped and exported with tenant identifiers so offline reviewers can verify context.

## Enforcement Stack

- **Authority** issues tokens containing scopes and optional ABAC claims.
- **Gateway** (when deployed) routes and enforces tenant + scope checks consistently across modules.
- **Services** validate tenant context and enforce tenant constraints at the storage layer.

## Offline / Air-Gap Considerations

- Offline Kit snapshots and exported evidence bundles include tenant identifiers and deterministic manifests so verification does not rely on online services.
- Cross-tenant exports are not supported by default; when an operator needs cross-tenant reporting, it should be implemented as an explicit, audited workflow.

## References

- Scope taxonomy: `docs/security/scopes-and-roles.md`
- Gateway tenant auth contract: `docs/api/gateway/tenant-auth.md`