Skip to content

Tenant-Project Ownership Baseline (MVP)

Purpose

Define the canonical ownership model for GPUaaS before further feature coding. This baseline is mandatory for all new implementation work.

Scope

  • Tenant/project hierarchy and ownership semantics.
  • Auth context and access control boundaries.
  • Billing ownership model.
  • Contract and schema impact for MVP reset-baseline.
  • Minimal IAM shape to avoid future query rewrites.

Canonical Hierarchy

Tenant (org)
  -> Project
    -> Resources (allocations, usage records, ledger entries, payment sessions, storage objects, scheduler resources)

Identity hierarchy remains separate:

User (human actor) / Service identity
  -> Membership-based role assignment (tenant/project)
  -> Request context includes active project

Membership Model (MVP-Compatible, Future-Proof)

Introduce membership tables now and enforce single-tenant behavior by constraint: 1. tenant_memberships(tenant_id, user_id, role, ...) with UNIQUE(user_id) in MVP. 2. project_memberships(project_id, user_id, role, ...) with UNIQUE(project_id, user_id). 3. All authz/resource-access queries must resolve through memberships (not users.org_id direct ownership checks). 4. When multi-tenant users are needed later, drop UNIQUE(user_id) on tenant_memberships without rewriting authz query shape.

Mandatory Ownership Rules

  1. Tenant is the legal/billing ownership root.
  2. Project is the operational resource-ownership scope.
  3. User is an actor and attribution identity, not owner-of-record.
  4. Every allocation must belong to exactly one tenant and one project.
  5. Access checks for resources must be tenant/project scoped; requested_by_user_id is audit only.

Signup / Bootstrap Model

MVP uses one automatic path for every new user: 1. Create personal tenant (organizations.type = personal). 2. Create default project under that tenant (slug = default). 3. Bind user to that tenant context. 4. Create membership rows: - tenant: owner - project: owner 5. Issue auth context with tenant claim; project is selected per request context.

No floating users without tenant/project context are allowed.

Auth Context Model

  1. JWT/session must include tenant context (org_id claim in current schema).
  2. Active project is request-scoped (header/body/path), validated server-side.
  3. Tenant context from JWT and request context must both pass membership validation.
  4. Header-only tenant context (X-Tenant-ID without token tenant claim) is deferred to a future IAM phase.
  5. User-level policy overrides are out of MVP scope.
  6. Missing project context on project-scoped endpoints is rejected (400 invalid_request); there is no implicit server-side default project fallback.

Role Model (Two-Tier, Explicit)

  1. Platform role (users.role) is global control-plane authority:
  2. admin: platform superadmin
  3. user: non-platform-admin
  4. Tenant/project roles live in membership tables and are tenant-scoped authorization roles:
  5. tenant: owner, admin, member, billing_viewer
  6. project: owner, admin, member, viewer
  7. Tenant/project access checks must not rely on users.role except for explicit platform-admin override paths.

Billing Model

  1. Billing balance and Stripe customer identity belong to tenant.
  2. Ledger entries are tenant-owned financial records.
  3. User fields in billing/payment tables are actor attribution (initiated_by_user_id, requested_by_user_id).
  4. Personal tenants behave like single-user billing without special-case code paths.
  5. Project-level billing customer override is a deferred option (projects.stripe_customer_id nullable, fallback to tenant customer).

MVP IAM Scope (Intentionally Simple)

  1. Keep role model small for MVP (owner, admin, member, billing_viewer).
  2. Keep single-tenant-per-user behavior via UNIQUE(user_id) in tenant_memberships.
  3. Defer tenant-level groups and project-level groups to post-MVP IAM phase.

Reset-Baseline Implementation Policy

This repo is pre-production and can reset state. 1. No data migration/backfill strategy is required for this change. 2. Recreate schema and seed data to enforce ownership constraints from day one. 3. Remove transitional nullable ownership behavior in code.

Required Schema Constraints (MVP Baseline)

At minimum, enforce: 1. allocations.org_id NOT NULL. 2. allocations.project_id NOT NULL. 3. allocations.project_id references projects.id where projects.org_id = allocations.org_id (mandatory database-level composite constraint). 4. Membership tables exist and are used in authorization paths: - tenant_memberships with UNIQUE(user_id) (MVP constraint) - project_memberships with UNIQUE(project_id, user_id) 5. Any new tenant-scoped mutable resource must carry non-null tenant/project ownership or explicitly document why project scope is not applicable. 6. nodes.org_id nullable semantics must be explicit: - null means shared/unassigned pool node not dedicated to a single tenant. - non-null means tenant-dedicated node.

Contract Impact (Planned)

  1. Public API endpoints that mutate project-owned resources require explicit project context.
  2. Resource list/read endpoints must filter by tenant + project authorization context.
  3. Billing/payment endpoints must expose tenant-owned balance semantics.
  4. Canonical resource_name should be emitted on tenant/project-scoped resources using the Resource Identifier Spec.
  5. Error semantics remain unchanged (ownership_required, insufficient_permissions, etc.) but checks move to tenant/project boundaries.

Policy Scope Impact (Planned)

  1. Current per-user concurrency policy should be replaced with tenant/project scope keys.
  2. Policy resolution chain for MVP remains:
  3. global defaults
  4. tenant override
  5. project override
  6. Concurrency policy should support both project cap and tenant cap keys.
  7. Conflict handling is deterministic: most-specific scope wins (project overrides tenant; tenant overrides global).
  8. policy_values.scope_type='plan' is retained for Phase-2 pricing/subscription layering and is out of MVP evaluation chain.
  9. policy_values.scope_type='user' may remain in schema for forward compatibility but is out of MVP evaluation chain.
  10. Planned Phase-2 chain: global -> plan -> tenant -> project (most-specific wins).

Idempotency TTL Baseline

  1. idempotency_keys.expires_at uses a 24h baseline TTL in MVP.
  2. A policy key idempotency.key_ttl_seconds is planned for explicit runtime configurability.

OPA-Ready Design Constraint (No Rewrite Later)

  1. Authorization decisions should be funneled through a single decision interface in API/service code.
  2. MVP may continue in-code evaluation, but decision input/output shape must be policy-engine friendly:
  3. input: actor, tenant, project, action, resource, attributes
  4. output: allow/deny, reason, policy source
  5. Full OPA/OPAL rollout is deferred; embedded OPA pilot is allowed later without changing endpoint contracts.

Authorization Performance SLO (MVP)

  1. Membership-resolution SLO target (API-side authorization checks):
  2. p95 <= 20 ms
  3. p99 <= 50 ms
  4. Scope:
  5. tenant + project membership resolution path used by project-scoped endpoints.
  6. Enforcement posture:
  7. query/index optimization first, no async permission cache by default.
  8. cache design is triggered only if sustained p95/p99 breaches remain after query/index tuning.
  9. Required evidence in acceptance:
  10. explain-plan proof that membership resolution uses indexed paths.
  11. integration test coverage for active-membership-only semantics (deleted_at is null).

Implementation Risks & Triggers

  1. Membership resolution latency risk:
  2. Risk: high-frequency authorization checks can regress if membership/policy lookups become join-heavy.
  3. MVP posture: optimize query/index paths first; do not add asynchronous authorization cache by default.
  4. Trigger for cache design: sustained p95 authz-check latency or API p95 breach under representative load after index/query tuning.
  5. Role-rigidity risk:
  6. Risk: hardcoded role-name checks (if role == ...) make ABAC/OPA migration expensive.
  7. Required implementation shape: map actions to permissions and evaluate by permission set, not literal role branching in handlers.
  8. Multi-tenant user expansion risk:
  9. Risk: forgetting that MVP single-tenant behavior is enforced by UNIQUE(user_id) in tenant_memberships.
  10. Constraint contract: authz query shape must remain membership-based so multi-tenant enablement is a constraint change, not a query rewrite.
  11. Audit continuity risk:
  12. Risk: hard-deleting memberships erases operational evidence for historical authorization attribution.
  13. MVP posture: memberships are soft-deleted; authz queries only consider active rows (deleted_at is null).

Non-Goals (MVP)

  1. Multi-tenant user context switching UX.
  2. Project-level role matrix.
  3. IAM group management UI.
  4. Full service-account runtime implementation (model/spec is required pre-work).

Acceptance Gate Before Coding

Ownership baseline is considered ready when: - ADR accepted and linked in roadmap. - ERD and db schema updated to non-null ownership semantics. - OpenAPI contract reflects project context requirements. - Test standards include tenant/project authorization checks for resource endpoints.

References

  • doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md
  • doc/architecture/ERD.md
  • doc/architecture/db_schema_v1.sql
  • doc/architecture/Schema_Migration_Plan.md
  • doc/Implementation_Roadmap.md
  • doc/architecture/Resource_Identifier_Spec.md