git.stella-ops.org/docs/implplan/EPIC_14.md

No file to print Fine. Identity and tenancy: the part everyone underestimates until they trip over it in prod. Here’s the clean, doc‑ready version.

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

Epic 14: Authority‑Backed Scopes & Tenancy

Short name: Authority‑Backed Scopes & Tenancy Primary components: Authority (authN/Z), Web Services API, Policy Engine, Orchestrator, Task Runner, Console, CLI Surfaces: /auth/*, request middleware, DB schema (RLS), object storage layout, message bus topics, audit logs, CLI login/impersonation flows Touches: Conseiller (Feedser), Excitator (Vexer), Findings Ledger, Export Center, Notifications Studio, Advisory AI Assistant

AOC ground rule reminder: Conseiller and Excitator aggregate and link advisories/VEX. They never merge or mutate source records. Enforcement of aggregation‑only behavior is tenant‑agnostic and must hold across all scopes.

---

1) What it is

A uniform model for identity, authorization, and isolation that is enforced end‑to‑end:

• Authority‑backed tokens: JWT/OIDC tokens issued by a configured Authority. Tokens carry scopes, roles, and tenant memberships as claims. Services verify and authorize locally; no out‑of‑band ACL calls during the hot path.
• Tenancy: First‑class multi‑tenant isolation with optional projects within a tenant. Strong separation at the database layer via row‑level security (RLS) and in object storage via tenant‑prefixed paths (and optionally per‑tenant KMS keys).
• Scopes & roles: Minimal set of composable scopes (stella:{resource}:{verb}) that map to roles (viewer, editor, operator, admin, owner) and can be constrained to {tenant}/{project}.
• Context propagation: Every API request, job, message, and artifact is stamped with {tenant_id, project_id, actor} and validated at ingress and again at persistence.
• Service accounts & delegation: Robot identities with scoped, expiring credentials for CI, Task Packs, and webhooks. Human-to-robot delegation is explicit and auditable.
• Audit: Immutable decision logs for authN/Z events with resource, scope, and policy evaluation outcomes.

Tenancy model:

Organization (optional, for billing) 
└── Tenant (isolation boundary)
    ├── Projects (isolation + grouping)
    │   ├── Sources (registries, repos)
    │   ├── Jobs & Runs
    │   ├── SBOMs & Artifacts
    │   ├── Findings / Evaluations
    │   └── Policies (bound or inherited)
    └── Shared tenant services (notifications, exports, secrets)

Knowledge planes:

• Global knowledge plane: Advisories, CVE metadata, CPE, KEV, etc. No tenant data.
• Tenant plane: SBOMs, VEX attachments, policy results, exposures, notifications, exports, audits.

Conseiller/Excitator live across both planes: they collect into the global plane and link to tenant plane without merging sources.

---

2) Why (brief)

Security that depends on “being careful” is not security. We need hard boundaries the platform cannot cross by accident:

• Run many teams/customers safely on one deployment.
• Minimize blast radius for credentials and mistakes.
• Make CI and automation safe with least‑privileged scopes.
• Keep latency low by verifying locally with signed tokens.

---

3) How it should work (maximum detail)

3.1 Tokens, claims, and scopes

Token type: JWT, signed by the Authority. Services cache JWKS and verify locally.

Required claims:

• iss, sub, aud, iat, exp
• scope: space‑separated scopes (stella:sbom:read, stella:job:run)
• tenants: array of tenant IDs the subject may access
• tenant (active): the currently selected tenant for the request
• roles: object map { "<tenant>": ["viewer", "editor", ...] }
• projects (optional): array of project IDs or { "<tenant>": ["projA", "projB"] }
• mfa (optional): boolean or level for step‑up enforcement
• act (optional): actor chain for delegation/impersonation

Scope grammar:

stella:{resource}:{verb}[#{constraint}]
  resource ∈ {tenant, project, source, job, sbom, vex, advisory, policy, finding, export, notify, secret, pack, ledger, console}
  verb ∈ {read, list, write, delete, run, execute, approve, admin}
  constraint := tenant/{tenantId}[/project/{projectId}]

Examples:

• stella:sbom:read#tenant/t-123/project/p-abc
• stella:job:run#tenant/t-123
• stella:tenant:admin#tenant/t-123 (Tenant Owner)

Role mapping (default):

• viewer → read/list on most resources
• editor → viewer + write on sbom/policy
• operator → editor + job:run, export:run, notify:manage
• admin → operator + user/role management inside tenant
• owner → admin + billing/tenant lifecycle

3.2 Selecting the active tenant

• API: X‑Stella‑Tenant: <tenant_id> header or ?tenant=<id> query. If omitted and the token has exactly one tenant, that tenant is active; else 400.
• Console: Tenant switcher in the top bar. Console includes header on all calls.
• CLI: stella login --tenant <id> sets the default; override per command --tenant.

All services must reject requests where the active tenant is not in tenants[] and scopes do not include that tenant constraint.

3.3 Request pipeline

1. Authentication middleware: verify JWT signature and expiry.
2. Tenant activation: pick active tenant per header; set per‑request context {tenant_id, actor}.
3. Scope check: compare required scope for the route with token scopes. If route accepts project limiters, check constraints align.
4. Policy overlay (optional): ABAC evaluation for fine controls (e.g., “deny job:run outside business hours”).
5. Persistence guard: set DB session GUC stella.tenant_id and verify any writes include matching tenant_id. Enforce Postgres RLS.
6. Audit: write decision to audit bus (async) with permit|deny, reasons, and matched rule.

3.4 Database isolation

Approach: shared schema with Row Level Security. Every tenant‑scoped table includes tenant_id and optional project_id.

RLS policy template (Postgres):

ALTER TABLE sboms ENABLE ROW LEVEL SECURITY;

CREATE POLICY sboms_isolate ON sboms
USING (tenant_id = current_setting('stella.tenant_id', true));

-- For INSERT/UPDATE guard:
CREATE POLICY sboms_write_guard ON sboms
AS PERMISSIVE FOR ALL
TO PUBLIC
WITH CHECK (tenant_id = current_setting('stella.tenant_id', true));

Set stella.tenant_id at connection checkout:

SELECT set_config('stella.tenant_id', $1, true); -- $1 = active tenant

Migrations:

• Add tenant_id to all tenant‑scoped tables.
• Backfill existing rows with the default tenant in Quickstart.
• Enable RLS and policies in a reversible migration.

3.5 Object storage and artifacts

• Layout: s3://<bucket>/tenants/<tenant_id>/projects/<project_id>/<resource>/<uuid>...
• KMS keys: optional per‑tenant key alias. Map via kms_alias = "stella-<tenant_id>".
• Ensure Task Runner and Export Center only operate within the prefixed path of the active tenant.

3.6 Message bus topics

• Topic naming: stella.<tenant_id>.<domain>.<event> for tenant‑scoped events.
• Global knowledge events remain stella.global.kb.*.
• Subscriptions always include a tenant filter unless consuming global knowledge.

3.7 Background workers

• Orchestrator & Task Runner: each job carries {tenant_id, project_id}. Workers set stella.tenant_id before any DB or object store access. Reject jobs that miss the context.
• Conseiller/Excitator: ingest to global plane; linking jobs (matching advisories to tenant SBOMs) run per tenant and respect RLS.

3.8 Policy overlay (optional but recommended)

Integrate Policy Engine with condition keys:

• tenant, project, resource.type, resource.id, actor.role, actor.mfa, time, ip. Examples:
• Deny job:run from IPs outside CIDR.
• Require mfa=true to approve notifications templates.
• Quotas: “max exports per hour per tenant.”

3.9 Service accounts & delegation

• Robot principals: sa:{tenant}:{name} with scopes constrained to tenant/project. Default TTL 1h; max TTL policy‑controlled.
• Token minting: Tenant admins can generate tokens via API/Console; all tokens auditable; optional bound to CIDR or workload identity.
• Delegation: stella token delegate --to sa:... --scopes ... --ttl 15m produces a token with act chain, recorded in audit log.

3.10 Auditing

Every decision logs:

• ts, tenant, actor, route, resource, action, effect, reason, scopes_used, policy_rule_id
• Persist in tenant‑scoped audit table and stream to stella.<tenant>.audit.decisions.
• Expose search/filter in Console → Admin → Audit.

3.11 CLI and Console UX

• CLI: stella login, stella whoami, stella tenants list, --tenant flag everywhere. Clear error if token lacks tenant or scope.
• Console: Tenant switcher, role badges, “why denied?” modal showing scope and policy reasons without leaking internals.
• Impersonation (admin only): sudo as <user> for debugging with visible banner; issues delegated token with act chain.

3.12 Compatibility modes

• Quickstart single‑tenant: hidden tenant local. Header optional. RLS enabled with constant.
• Multi‑tenant: full model active; migrations buttoned up; Console exposes tenant admin.

---

4) Architecture

4.1 New/updated modules

• auth/authority: JWKS fetching, token validation, scope parser, cache.
• auth/middleware: HTTP/gRPC interceptors for authN/Z, tenant activation, audit emit.
• auth/roles: role → scope mapping + tenant/project constraints.
• auth/policy-bridge: optional ABAC evaluation using Policy Engine.
• storage/tenantctx: helpers to set stella.tenant_id in DB session and object‑store prefixes.
• audit/decisions: structured logging and bus producer.
• cli/auth: login, token store, tenant switcher, whoami.

4.2 Data model changes

• Add tenant_id (and project_id where appropriate) to: sources, jobs, runs, sboms, components, findings, policies, exports, notifications, secrets, packs, ledger, audits.

• Create tables:

  • tenants(id, name, status, created_at, owner_user_id)
  • projects(id, tenant_id, name, meta, created_at)
  • memberships(user_id, tenant_id, roles[])
  • service_accounts(id, tenant_id, name, scopes[], created_at, disabled)
  • audit_decisions(...) (tenant‑scoped)

---

5) APIs and contracts

5.1 Standard headers

• Authorization: Bearer <jwt>
• X‑Stella‑Tenant: <tenant_id>
• X‑Request‑ID (propagated for audit correlation)

5.2 Auth endpoints

• POST /auth/login (OIDC code flow start for Console)
• GET /auth/jwks.json (proxy/cached from Authority if needed)
• GET /auth/whoami → { sub, tenants[], activeTenant, roles, scopes, mfa }
• POST /auth/tokens/service (tenant admin) → mint robot token with constrained scopes/ttl
• POST /auth/tokens/delegate → mint delegated token with act chain

5.3 Tenant admin endpoints

• POST /tenants (owner only)
• GET /tenants, GET /tenants/:id
• POST /tenants/:id/projects, GET /tenants/:id/projects
• POST /tenants/:id/members (assign role), DELETE /tenants/:id/members/:user
• GET /tenants/:id/audit (search)

5.4 Route protection conventions

Each route declares:

• resource, verb
• Whether it requires project constraint
• Optional policy gates (e.g., require_mfa)

Example (OpenAPI extension):

x-stella-auth:
  resource: sbom
  verb: read
  requireTenant: true
  allowProjectScoped: true
  requireMFA: false

---

6) Documentation changes

Create/update:

1. /docs/security/tenancy-overview.md Concepts, knowledge planes, tenant/project model, isolation layers.

2. /docs/security/scopes-and-roles.md Scope grammar, default roles, examples, custom role mapping.

3. /docs/security/authority-config.md How to connect to an OIDC provider, JWKS caching, audience, issuers, time skew, MFA signal.

4. /docs/operations/multi-tenancy.md Running multi‑tenant deployments: quotas, KMS per tenant, object store layout, message topics, backup/restore per tenant.

5. /docs/operations/rls-and-data-isolation.md Postgres RLS policy reference, migrations, troubleshooting leaks.

6. /docs/console/admin-tenants.md Tenant switcher, managing members, roles, audit viewer.

7. /docs/cli/authentication.md login, whoami, tenants list, --tenant, service tokens, delegation.

8. /docs/api/authentication.md Headers, error codes, sample requests, OpenAPI x-stella-auth annotations.

9. /docs/policy/examples/abac-overlays.md Optional policy snippets: MFA requirements, time windows, IP restrictions, quotas.

10. /docs/install/configuration-reference.md New STELLA_AUTH_*, STELLA_TENANCY_*, and per‑service flags.

Add at the top of each page:

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

---

7) Implementation plan

Middleware & libraries

• Implement auth/middleware with:

  • JWKS cache and signature verification (kid pinning, 10 min refresh).
  • Scope parser and matcher with constraint evaluation.
  • Tenant activator reading header/query and verifying membership.
  • Policy hook for ABAC (feature flag).
  • Decision audit emitter (non‑blocking).

Services

• API: wrap all handlers with middleware; declare route protection via decorators/annotations; enforce project constraints.
• DB access layer: on connection checkout set stella.tenant_id; forbid raw SQL that bypasses the session GUC.
• Orchestrator/Task Runner: include {tenant_id, project_id} in job spec; enforce before any IO.
• Export/Notify/AI: stamp tenant in outbound payloads and logs; include it in idempotency keys.
• Conseiller/Excitator: keep global ingestion; ensure linking jobs run with tenant context only.

Console

• Add tenant switcher and “whoami” panel.
• Show role badges; display “why denied?” with scope/policy explanation from 403 payload.
• Tenant Admin screens: members, roles, service tokens, audit.

CLI

• stella login (device/code or local browser) and tenant selection.
• Persist tokens per profile; --tenant override; whoami.
• Commands fail with clear errors on scope violation.

Storage

• Prefix object store paths by tenant/project.
• Optional per‑tenant KMS key integration.

Migrations

• Add tenant_id and backfill.
• Enable RLS with policies and tests.
• Seed default tenant for Quickstart.

---

8) Engineering tasks

Auth & middleware

• Implement JWKS retrieval and caching with rotation tests.
• Implement scope parser and matcher with constraint support.
• Build HTTP/gRPC interceptors and integrate across services.
• Add ABAC policy hook and sample policies.
• Emit structured decision audits.

Data & storage

• Add tenant_id columns and indices; backfill in migration.
• Enable Postgres RLS policies for all tenant‑scoped tables.
• Update ORM/queries to rely on RLS; remove any “WHERE tenant_id = ...” duplication.
• Tenant‑prefixed object store paths; optional per‑tenant KMS keys.

Services

• Annotate all routes with x-stella-auth or equivalent decorator.
• Propagate tenant context through orchestrator and workers.
• Update Conseiller/Excitator linkers to require tenant context.

Console

• Implement tenant switcher, role display, and “whoami.”
• Add Tenant Admin screens (members, projects, service accounts).
• Implement “Why denied?” modal reading 403 details.

CLI

• login, whoami, tenants list, tenant flag and persistence.
• Service token minting for tenant admins.
• Delegate token creation for robot use.

Audit

• Create audit_decisions table and producer.
• Add search API and Console viewer.

Docs

• Author the ten docs listed in §6 with examples and diagrams.
• Add troubleshooting: common 401/403 causes and fixes.
• Add migration guide from single‑tenant to multi‑tenant.

Tests

• Unit tests for scope matching and token validation.
• RLS tests verifying cross‑tenant reads/writes fail.
• E2E tests: multi‑tenant users, robot tokens, ABAC overlays, orchestrator runs.
• Fuzz tests on header handling to prevent tenant confusion bugs.

---

9) Feature changes required

• All services: must expose 403 payloads with machine‑and human‑readable denial reasons and the missing scope string.
• Export Center: requires tenant in all manifests; deny cross‑tenant exports by default; allow explicit cross‑tenant mirror via signed bundle.
• Notifications: destinations and templates are tenant‑scoped; sending pipeline stamps tenant.
• Advisory AI Assistant: restricts training context to a tenant’s data; global knowledge plane may be referenced but never log tenant data into global.
• Findings Ledger: partition by tenant; queries must be tenant‑filtered or rely solely on RLS.
• Policy Engine: support condition keys for tenant and actor; ship example policies.

---

10) Acceptance criteria

• Requests lacking X‑Stella‑Tenant in multi‑tenant mode are rejected unless single‑tenant Quickstart.
• RLS prevents cross‑tenant leakage proven by tests that attempt blind selects/inserts.
• CLI can log in, list tenants, select tenant, and perform a job limited to that tenant.
• Console shows tenant switcher; admin can invite a member and assign roles.
• Service token can be minted with narrow scopes and expires as configured.
• Every 403 returns a clear “missing required scope …” with the exact scope string.
• Conseiller/Excitator continue aggregation‑only behavior; linking jobs run strictly under tenant context.
• Audit stream captures all permit/deny decisions with correlation IDs.

---

11) Risks & mitigations

• RLS misconfiguration. Write tests that run with and without RLS; block migrations unless policies are present. Provide a canary query per service on boot to verify isolation.
• Scope explosion. Keep a minimal, stable scope set; use constraints for specificity; document patterns.
• JWKS outages. Cache keys with TTL, support multiple kids, and tolerate short network failures.
• Privilege creep in robots. Short TTLs by default, clear UI to rotate/revoke, and audit for usage anomalies.
• Tenant confusion bugs. Require tenant header, validate against token memberships, and pin tenant context into DB session and job payloads, never thread‑locals only.

---

12) Philosophy

• Isolation by default. Tenancy isn’t a UI filter; it’s enforced where the data lives.
• Least privilege wins. Humans and robots get only what they need for as long as they need it.
• Explain denials. If the platform can’t explain “why no,” it’s broken.
• Global vs tenant plane. Public knowledge is shared; customer data is not, ever.

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.