Identity and Access Domain Model Review and Architectural Refactor - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Bite 30 — Identity and Access Domain Model Review and Architectural Refactor

Bite 30A — Authoritative Identity and Access Domain Model Decision

Status: Architectural decision record — agreed model
Baseline: development SHA 82b0e5db114b4db9707c576bd8ca1a401d083c6e
Scope of Bite 30A: Audit and decision only. No schema migrations or behavioral refactoring.
Relationship to Bite 28E: Bite 28E — Tenant/User/Auth E2E Coverage is deferred and will be absorbed into the final Bite 30 hardening and verification work.

1. Purpose

Bite 30 exists because the identity, authentication, tenant, Person, Collaborator, and authorization structures implemented through Bites 27 and 28 contain architectural assumptions that are no longer consistent with the intended ERS domain model.

Bite 30A establishes one authoritative model before any implementation changes are made.

The model covers:

  • Authentication Account
  • Actor
  • Tenant
  • Person
  • Person–Tenant Membership
  • Collaborator / Collaborator Journey
  • Role and Role Grant
  • self-service authorization
  • delegated authorization
  • Session
  • tenant selection
  • account / Actor / Person / Membership / Collaborator lifecycle
  • Application Administrator / global authority
  • Tenant Support Access Lease
  • audit identity
  • Earnings and Expenses ownership and tenant provenance

For every entity or authorization concept, this document defines:

  • Purpose
  • Ownership
  • Cardinality
  • Tenant scope
  • Lifecycle
  • Activation/deactivation semantics
  • Authorization consequences
  • Database invariants

2. Foundational Principles

2.1 One human, one Authentication Account

A human shall have one, and only one, ERS Authentication Account, regardless of how many tenants the human participates in.

The Authentication Account represents authentication identity only.

It does not itself represent:

  • a Tenant;
  • a Person–Tenant Membership;
  • a Collaborator;
  • a tenant authorization role.

An Authentication Account may control multiple tenant Actors.

A very small number of Application Administrators may have an Authentication Account without a Person record and without any tenant Actor.

2.2 One global Person

A human represented in the ERS business domain shall have one global Person record.

A Person is not owned by a Tenant.

If Maria participates in Tenant A and Tenant B, ERS stores one Maria Person record and two separate Person–Tenant Memberships.

Global Person information is shared across the Person's memberships. A permitted update to Maria's global information therefore changes the authoritative Maria record for all memberships.

Tenant-specific information must not be stored as global Person information.

2.3 Person–Tenant Membership is first-class

A Person–Tenant Membership represents the fact that a global Person participates in a particular Tenant.

The membership is separate from authentication, authorization, and collaboration.

Only a Tenant Administrator may create a Person–Tenant Membership for that Tenant.

A Tenant may know a Person only through that Tenant's membership with the Person.

Tenant A must be unable to determine that the same global Person participates in Tenant B.

The existence, status, Actors, Collaborator Journeys, financial records, roles, and other relationships of the Person in other tenants are confidential from Tenant A.

2.4 Tenant Actors are tenant-specific authorization identities

When a Person participates in multiple tenants, the Person uses a different Actor for each Tenant.

All of those tenant Actors may be controlled by the same Authentication Account.

A tenant Actor represents:

this authenticated human acting as this Person within this specific Tenant.

Switching tenants therefore changes the selected Actor and authorization context. It does not change:

  • the Authentication Account;
  • the global Person;
  • the underlying human.

2.5 Self-service authorization is intrinsic

A Person's self-service rights do not come from a Role Grant.

An active tenant Actor linked through a Person–Tenant Membership intrinsically identifies the Person whose self-service resources may be accessed.

The Person's self-service authorization includes the rights agreed for the Person domain, including access to the Person's own information and the Person's own historical Earnings and Expenses for the selected Tenant.

A Tenant Administrator does not grant or revoke those intrinsic rights through delegated Roles.

Tenant access is controlled by the tenant Actor's activation state.

2.6 Collaborator status augments Person capabilities

Becoming a Collaborator does not create a new login identity.

A Collaborator Journey is a tenant-specific business relationship involving an existing Person–Tenant Membership.

Creating a Collaborator Journey requires an existing Person–Tenant Membership; the existence of a Person alone is insufficient.

While the Person is an active Collaborator, the Person receives the additional intrinsic capabilities associated with active collaboration, including the agreed access to current Work Assignments and current Earnings and Expenses.

Ending a Collaborator Journey does not delete or replace:

  • the Person;
  • the Person–Tenant Membership;
  • the Authentication Account;
  • the tenant Actor;
  • historical Earnings or Expenses.

2.7 Delegated authorization is separate from self-service

Roles and Role Grants represent delegated authority such as:

  • Tenant Administrator;
  • Earnings Operator;
  • Expenses Operator.

They do not represent the Person's intrinsic right to act on their own information.

The existing PERSON role/grant concept is therefore not part of the target authorization model.

2.8 Application Administrators are global and are never tenant Persons

Application Administrators are a very small set of application-global identities.

An Application Administrator:

  • has a global Actor;
  • has no Person record while serving as an Application Administrator;
  • has no Person–Tenant Membership;
  • has no tenant Actor;
  • has no Collaborator Journey;
  • must never acquire ordinary tenant privileges;
  • must never receive implicit access to tenant business data.

Application-global authority is a control-plane authority, not a wildcard tenant authority.

The target model shall not use tenant_id = '*' to mean that an Application Administrator is an administrator inside every tenant.

2.9 Global administration does not imply tenant-data access

ERS shall distinguish:

  1. Normal tenant access — through a tenant Actor, intrinsic self-service authorization, and delegated tenant Role Grants.
  2. Global administration — through a global Actor and application control-plane permissions.
  3. Exceptional support access — through an explicitly approved Tenant Support Access Lease.

A Global Actor shall never implicitly possess tenant business-data authorization.

2.10 Tenant Support Access Lease is exceptional authorization

When application support genuinely requires access to tenant information, the access must not create an ordinary tenant identity for the Application Administrator.

A Tenant Support Access Lease:

  • is associated with the actual global Application Administrator Actor;
  • applies to exactly one Tenant;
  • records a reason/support case;
  • contains explicitly permitted operations or resource classes;
  • has a fixed expiration;
  • can be terminated by a Tenant Administrator at any moment;
  • must cease authorizing requests immediately after termination;
  • is not a Role Grant;
  • is not a Person–Tenant Membership;
  • is not a tenant Actor;
  • does not make the Application Administrator a Person or Collaborator in the Tenant;
  • is comprehensively audited;
  • must be visible to the affected Tenant's administrators.

A future break-glass mechanism, if ERS requires one, must be designed separately and shall not be inferred from the ordinary support-lease model.

2.11 Earnings and Expenses belong to the Person and reference the Tenant

A Person's Earnings and Expenses remain attached to the global Person.

Every Earnings/Expense financial record must also carry an explicit Tenant reference.

This allows:

  • Maria to access her own Tenant-A records when operating through her Tenant-A Actor;
  • Maria to access her own Tenant-B records when operating through her Tenant-B Actor;
  • an authorized Tenant-A operator to access only Tenant-A records;
  • ERS to preserve historical financial ownership even after a Collaborator Journey ends.

A financial record may retain a Collaborator Journey reference as provenance when the transaction arose from that journey, but the journey is not the enduring owner of the Person's financial history.

3. Target Relationship Model

                                  HUMAN
                                    |
                                    | 1 : 1
                                    v
                         +------------------------+
                         | Authentication Account |
                         +-----------+------------+
                                     |
                         controls 0..N Actors
                                     |
             +-----------------------+-----------------------+
             |                                               |
             v                                               v
    +------------------+                            +------------------+
    |   Global Actor   |                            |   Tenant Actor   |
    |  scope = GLOBAL  |                            | scope = TENANT   |
    +--------+---------+                            +--------+---------+
             |                                               |
      Application Admin                                      |
      control plane only                                     |
             |                                               v
             |                                  +---------------------------+
             |                                  | Person–Tenant Membership  |
             |                                  +-------------+-------------+
             |                                                |
             |                                                v
             |                                         +-------------+
             |                                         |   Person    |
             |                                         |   GLOBAL    |
             |                                         +-------------+
             |
             +-- optional Tenant Support Access Lease --> one Tenant only

For an ordinary multi-tenant Person:

Authentication Account
        |
        +---- Tenant Actor A ---- Membership A ----+
        |                                          |
        +---- Tenant Actor B ---- Membership B ----+---- Global Person

Tenant A cannot enumerate or infer Membership B.

4. Entity Decisions

4.1 Authentication Account

Purpose
Authenticate one human to ERS.

Ownership
Application-global.

Cardinality

  • Human → Authentication Account: exactly 1:1.
  • Authentication Account → tenant Actors: 0..N.
  • Authentication Account → global Actor: normally 0; exactly 1 for an Application Administrator.
  • Authentication Account → Person: 0..1.
  • Person → Authentication Account: 0..1 during migration/onboarding; at most one active authentication identity.

Tenant scope
None.

Lifecycle

  • Created independently of Tenant membership.
  • Never hard-deleted when security/audit history must be retained.
  • Password/reset/session lifecycle belongs to the Account.

Activation/deactivation semantics

  • Account deactivation disables authentication to ERS globally.
  • All active Sessions for the Account must be revoked immediately.
  • Account reactivation does not automatically reactivate tenant Actors.

Authorization consequences

  • An authenticated Account has no tenant authorization until a specific active Actor/context is selected or resolved.
  • Account activation alone grants no business permission.

Database invariants

  • Login identity is globally unique and normalized.
  • One human must not have multiple Authentication Accounts.
  • Account deactivation must invalidate Sessions.
  • The current one-to-one immutable auth_user_accounts.actor_id relationship is not part of the target model.
  • An Application Administrator Account must not own tenant Actors or be linked to a Person.

4.2 Actor

Purpose
Represent the authorization principal currently acting in ERS.

Ownership

  • Global Actor: application-owned.
  • Tenant Actor: bound to exactly one Person–Tenant Membership and controlled by exactly one Authentication Account.

Cardinality

  • Authentication Account → Actor: 0..N.
  • Person–Tenant Membership → tenant Actor: 0..1, with at most one current tenant Actor for that membership/account identity.
  • Application Administrator Account → Global Actor: exactly 1.

Tenant scope

  • Tenant Actor: exactly one Tenant, derived from/bound to its Membership.
  • Global Actor: no Tenant.

Lifecycle

  • Tenant Actor may be created once the Person has both an Authentication Account and a Person–Tenant Membership.
  • Actor history is retained.
  • Actor should be deactivated/reactivated, not silently repointed to another Person/Tenant.

Activation/deactivation semantics

  • Deactivating a tenant Actor removes that human's access to that Tenant only.
  • It does not deactivate the Authentication Account or other tenant Actors.
  • Deactivating the global Actor removes global administrative authority.

Authorization consequences

  • Tenant Actor activates intrinsic self-service identity for the linked Person in that Tenant.
  • Tenant delegated Role Grants attach to tenant Actors.
  • Global Actor receives only global/control-plane authority.

Database invariants

  • Tenant Actor is bound to exactly one Membership and therefore exactly one Tenant.
  • Tenant Actor cannot be bound to a Membership belonging to another Person than the Account's Person identity.
  • Global Actor must have no Tenant, Person–Tenant Membership, Collaborator, or tenant Role Grant.
  • No wildcard tenant Actor exists.

4.3 Tenant

Purpose
Represent an independent ERS customer/operating domain and confidentiality boundary.

Ownership
Application-global control plane.

Cardinality

  • Tenant → Person–Tenant Memberships: 0..N.
  • Tenant → tenant Actors: 0..N through memberships.
  • Tenant → Collaborator Journeys: 0..N.
  • Tenant → tenant Role Grants: 0..N.
  • Tenant → Earnings/Expenses: 0..N.

Tenant scope
The Tenant is the scope boundary.

Lifecycle

  • Created and managed through global control-plane authority.
  • Historical tenant data must not be silently reassigned to another Tenant.

Activation/deactivation semantics

  • An inactive Tenant cannot be selected for normal tenant operations.
  • Deactivation must preserve history and must not reveal or migrate data to another Tenant.

Authorization consequences

  • All tenant operations require a tenant-specific authorization context or an active exceptional Support Access Lease.
  • Tenant identity alone grants no access.

Database invariants

  • Tenant identifiers are globally unique.
  • Every tenant-owned/tenant-provenance record must reference exactly one Tenant.
  • Cross-tenant foreign-key relationships must be prohibited unless explicitly global by design.

4.4 Person

Purpose
Represent one human in the ERS business domain.

Ownership
Global, not Tenant-owned.

Cardinality

  • Human → Person: 0..1 in ERS.
  • Person → Person–Tenant Membership: 0..N.
  • Person → Authentication Account: 0..1.
  • Person → Earnings/Expenses: 0..N.
  • Person → Collaborator Journeys: 0..N through memberships.

Tenant scope
None for the Person record itself.

Lifecycle

  • Any human may create an ERS Person record.
  • Person creation does not create Tenant membership.
  • Person history should be retained rather than duplicated per Tenant.

Activation/deactivation semantics

  • Global Person state must not be used as a shortcut for tenant access.
  • Tenant access is controlled through Membership/Actor lifecycle.

Authorization consequences

  • The Person record establishes self identity but does not by itself authorize access to a Tenant.
  • A Tenant Administrator may update global Person information only while the Person has an active Membership in that administrator's Tenant.
  • Every Tenant-initiated change to global Person data must be audited.

Database invariants

  • A Person has no tenant_id.
  • ERS must prevent creation of duplicate global Person identities.
  • Stable identity/deduplication rules must be global; exact field-level uniqueness rules shall be hardened during implementation rather than inferred from the former tenant-scoped indexes.
  • Tenant-private notes/status must not live on the global Person record.

4.5 Person–Tenant Membership

Purpose
Represent that a global Person participates in one Tenant.

Ownership
Tenant-specific relationship referencing a global Person.

Cardinality

  • Person → Membership: 0..N.
  • Tenant → Membership: 0..N.
  • Person + Tenant → Membership: at most one enduring membership identity.
  • Membership → tenant Actor: 0..1 current Actor.
  • Membership → Collaborator Journeys: 0..N over time.

Tenant scope
Exactly one Tenant.

Lifecycle

  • Only a Tenant Administrator may create a Membership.
  • Membership may exist before the Person is a Collaborator.
  • Membership history survives the end of collaboration.
  • Membership is not created by authentication.

Activation/deactivation semantics

  • Membership status represents the Tenant relationship, not delegated authorization.
  • Runtime access remains controlled by Actor activation.
  • If membership deactivation is implemented, it must not leave a usable tenant Actor; the implementation must keep the two lifecycle states consistent without converting Membership into a Role Grant.

Authorization consequences

  • Membership is a prerequisite for a tenant Actor.
  • Membership is a prerequisite for Collaborator creation.
  • Membership existence does not itself grant delegated Roles.

Database invariants

  • Unique (person_id, tenant_id) enduring membership.
  • Membership's Tenant cannot change.
  • A Tenant query may return only its own Memberships.
  • APIs must never expose the Person's Memberships in other Tenants to tenant users.
  • Tenant-private status, notes, and tenant-specific administrative metadata belong here, not on Person.

4.6 Collaborator / Collaborator Journey

Purpose
Represent a Person's period of active collaboration with a Tenant.

Ownership
Tenant-specific.

Cardinality

  • Membership → Collaborator Journeys: 0..N over time.
  • One active Journey per Membership unless a later business decision explicitly allows otherwise.

Tenant scope
Exactly the Membership's Tenant.

Lifecycle

  • Creation requires an existing Person–Tenant Membership.
  • Closing a Journey preserves it as historical.
  • A new Journey may later be created for the same Membership according to business rules.

Activation/deactivation semantics

  • Collaboration status affects collaborator-specific capabilities.
  • It does not create, replace, or destroy authentication identity.

Authorization consequences

  • Active collaboration augments intrinsic Person capabilities with current collaborator capabilities.
  • Ending collaboration removes current-collaborator capabilities but preserves self-service access to historical Person financial records, subject to active tenant Actor access.

Database invariants

  • Journey must reference Membership, not merely a Person.
  • Journey Tenant must equal Membership Tenant.
  • A Journey cannot be created for a Person lacking Membership in that Tenant.

4.7 Role

Purpose
Define a reusable bundle of delegated permissions.

Ownership
Application-global definition.

Cardinality

  • Role → Role Grants: 0..N.

Tenant scope

  • Tenant roles define permissions usable only by tenant Actors.
  • Global roles define control-plane authority usable only by global Actors.

Lifecycle

  • Roles are configuration/authorization definitions.
  • Deactivating a Role disables effective grants without deleting audit history.

Authorization consequences

  • Roles confer delegated authority only.
  • Self-service identity is not modeled as a Role.

Database invariants

  • Role scope must be explicit.
  • A tenant Role cannot be granted to a global Actor.
  • A global Role cannot be granted to a tenant Actor.

4.8 Role Grant

Purpose
Delegate a Role to an Actor.

Ownership
Belongs to the authorization domain.

Cardinality

  • Actor → Role Grants: 0..N.

Tenant scope

  • Tenant Role Grants inherit/must match the Actor's Tenant.
  • Global Role Grants apply only to global Actors.

Lifecycle

  • Grants are activated/deactivated/revoked while retaining history.

Activation/deactivation semantics

  • Revocation removes delegated authority only.
  • It does not remove intrinsic self-service rights.

Authorization consequences

  • Effective delegated permissions are Actor + active Role Grant + active Role.
  • There is no PERSON self-service grant in the target model.

Database invariants

  • Grant scope must equal Actor scope.
  • No tenant_id='*' wildcard shall be used to convert global authority into all-tenant authority.
  • Duplicate equivalent active grants are prohibited.

4.9 Self-Service Authorization

Purpose
Allow a Person to act on their own resources.

Ownership
Derived authorization; not a persisted administrator grant.

Cardinality
One intrinsic self-service identity per active tenant Actor/Person relationship.

Tenant scope
Selected tenant Actor's Tenant.

Lifecycle
Exists whenever the required Person/Membership/Actor relationship is valid and the Actor is active.

Activation/deactivation semantics
Tenant Actor activation controls whether the Person can exercise self-service in that Tenant.

Authorization consequences

Self-service decisions derive from:

  • authenticated Account;
  • selected active tenant Actor;
  • Actor's Membership;
  • Membership's Person;
  • target resource's person_id;
  • target resource's tenant_id.

Database invariants

  • Self-service authorization must never depend on a Tenant Administrator having created a PERSON Role Grant.
  • Own-resource checks must include both Person identity and Tenant provenance.

4.10 Delegated Authorization

Purpose
Allow an Actor to perform operations on resources that are not merely the Actor's own resources.

Ownership
Authorization domain.

Tenant scope
Actor scope.

Lifecycle
Controlled by Role Grants.

Authorization consequences
Delegated authority is always additive to intrinsic Person/self-service capabilities; it does not redefine who the Person is.

Database invariants

  • Tenant delegated permission can never cross the Actor's Tenant boundary.
  • An identifier from another Tenant must not become accessible merely because the caller possesses the same permission code in their own Tenant.

4.11 Session

Purpose
Represent an authenticated browser/client session for one Authentication Account.

Ownership
Authentication Account.

Cardinality

  • Authentication Account → Sessions: 0..N.
  • Session → Authentication Account: exactly 1.

Tenant scope
None inherently.

Lifecycle

  • Created after successful authentication.
  • Expires or is explicitly revoked.
  • Password change/reset and Account deactivation revoke Sessions according to authentication policy.

Activation/deactivation semantics

  • Session validity proves Account authentication only.
  • It does not make all of the Account's Actors simultaneously effective.

Authorization consequences

  • A protected tenant operation must resolve/select one of the Account's active tenant Actors.
  • A global-admin operation must resolve the Account's global Actor.
  • Global and tenant authority must never be silently combined in one effective authorization context.

Database invariants

  • Session always references exactly one Account.
  • Revoked/expired Sessions cannot authorize requests.
  • Session/audit correlation must preserve which Actor was effective for each privileged request.

4.12 Tenant Selection

Purpose
Select which of an ordinary user's tenant identities is active for tenant operations.

Ownership
Session/client authorization context.

Cardinality
At most one selected tenant Actor per normal workspace context.

Lifecycle

  • Available tenant choices are derived from the Account's active tenant Actors and valid Memberships.
  • Switching Tenant selects a different tenant Actor.

What changes on Tenant switch

  • selected Actor;
  • selected Tenant;
  • effective intrinsic self-service context;
  • effective delegated Role Grants;
  • tenant-bound client/query state.

What does not change

  • Authentication Account;
  • Session authentication identity;
  • global Person;
  • password/authentication state.

Database/authorization invariants

  • A caller cannot select a Tenant for which the Account has no active tenant Actor.
  • Tenant selection must never be inferred from a global Application Administrator wildcard.
  • Cross-tenant cached state must be cleared or segregated when the selected Actor changes.

4.13 Application Administrator / Global Authority

Purpose
Operate the ERS application control plane.

Ownership
Application-global.

Cardinality
Very small number of humans/Accounts.

Tenant scope
None.

Lifecycle

  • Explicit appointment/removal.
  • No conversion into a Tenant Person or Tenant Actor.

Activation/deactivation semantics

  • Global Actor activation controls global authority.
  • Account deactivation controls authentication.

Authorization consequences

Normal Application Administrator capabilities may include control-plane operations such as:

  • Tenant lifecycle administration;
  • authentication infrastructure administration;
  • global authorization/configuration administration;
  • platform/security configuration;
  • operational health functions.

Global authority does not confer ordinary access to:

  • People;
  • Collaborators;
  • Work Assignments;
  • Earnings;
  • Expenses;
  • Receipts;
  • tenant ledgers/current accounts;
  • other tenant business data.

Exceptional access requires a Tenant Support Access Lease.

Database invariants

  • Application Administrator Account has no Person.
  • Application Administrator Account has no Person–Tenant Membership.
  • Application Administrator Account has no tenant Actor.
  • Application Administrator has no tenant Role Grant.
  • Global Actor cannot be converted into a tenant Actor by selecting a Tenant.

4.14 Tenant Support Access Lease

Purpose
Provide explicit, temporary, accountable support access to one Tenant without making the Application Administrator a tenant user.

Ownership
Application security/control plane with Tenant approval/revocation authority.

Cardinality

  • Global Actor → Support Leases: 0..N historically.
  • Lease → Tenant: exactly 1.
  • Lease → approving Tenant Administrator Actor: exactly 1 for ordinary support access.

Tenant scope
Exactly one Tenant.

Lifecycle

  • Requested with reason/case.
  • Approved.
  • Active until earliest of expiration, Tenant Administrator termination, or administrative/security revocation.
  • Retained permanently enough for audit requirements.

Activation/deactivation semantics

  • Expiration automatically terminates authorization.
  • Tenant Administrator may terminate at any moment.
  • Termination must affect the next privileged authorization decision immediately.

Authorization consequences

  • Only the explicit lease capabilities are permitted.
  • Lease does not inherit the Tenant Administrator role.
  • Lease does not authorize another Tenant.
  • Lease is not ordinary role-based tenant access.

Database invariants

  • Requires global Actor, Tenant, approver, reason, scope, start, expiration, and revocation/termination metadata.
  • Cannot be active beyond expiration.
  • Cannot be used after termination.
  • Every support-authorized action records the Lease ID.

4.15 Earnings and Expenses

Purpose
Represent financial history belonging to the Person while preserving the Tenant in which the financial event occurred.

Ownership
Global Person with explicit Tenant provenance.

Cardinality

  • Person → Earnings: 0..N.
  • Person → Expenses: 0..N.
  • Tenant → Earnings/Expenses: 0..N.

Tenant scope
Every record references exactly one Tenant.

Lifecycle

  • Financial history survives Collaborator Journey closure and Actor deactivation.
  • Records retain correction/audit rules already required by their financial domain.

Authorization consequences

  • Self-service requires matching Person and selected Tenant.
  • Tenant operators require delegated authority in the record's Tenant.
  • Another Tenant must never receive access through the global Person relationship.

Database invariants

  • person_id is required.
  • tenant_id is required.
  • If collaborator_journey_id is retained as provenance, its Person/Membership/Tenant must agree with the financial record.
  • Financial ownership must not depend solely on an active Collaborator Journey.

4.16 Audit Identity

Purpose
Make every sensitive action attributable to the real authenticated identity, authorization context, Tenant, and exceptional-access mechanism.

Ownership
Application-global audit/security domain.

Tenant scope
Recorded explicitly for tenant-affecting actions.

Lifecycle
Append-only/immutable according to audit retention policy.

Authorization consequences
Audit records do not grant authority; they explain who exercised authority and why.

Required audit identity where applicable

  • Authentication Account ID;
  • effective Actor ID;
  • Actor scope (GLOBAL or TENANT);
  • Person ID, when the Actor represents a Person;
  • Person–Tenant Membership ID, when applicable;
  • Tenant ID;
  • Session/correlation identity;
  • Role/Grant or intrinsic authorization source;
  • Tenant Support Access Lease ID, when applicable;
  • operation;
  • target type/ID;
  • decision;
  • reason;
  • timestamp.

Database invariants

  • Ordinary administrators cannot rewrite or delete audit history.
  • Global Person changes initiated from a Tenant must record the originating Tenant and Actor.
  • Support Lease access must always be distinguishable from normal tenant access.
  • The affected Tenant must be able to review support-access history relevant to it.

5. Confidentiality Model

Inter-tenant confidentiality is a core ERS requirement.

The architecture shall reduce reliance on personal trust in Application Administrators by enforcing confidentiality through independent controls.

Required controls

  1. Tenant-specific Actors.
  2. Person–Tenant Membership confidentiality.
  3. Tenant-scoped delegated authorization.
  4. Person + Tenant checks for self-service financial records.
  5. No wildcard global-admin access to tenant data.
  6. Explicit, expiring, Tenant-revocable Support Access Leases.
  7. Immutable privileged-access audit.
  8. Tenant visibility into support access.
  9. Database constraints that prevent invalid cross-tenant relationships.
  10. Encryption at rest for production data/backups as an operational security baseline.

Encryption decision

Tenant-controlled/end-to-end encryption is not a Bite 30 requirement because it would materially complicate support, recovery, search, reporting, and operational access.

Per-tenant application-layer encryption keys may be evaluated later as defense-in-depth, but they do not replace authorization and are not required to establish the Bite 30 domain model.

6. Current Baseline vs Target Model

The Bite 28 baseline contains several structures that Bite 30 must deliberately replace.

Current baseline Target Bite 30 model
people.tenant_id Global Person with no Tenant owner
Person uniqueness scoped by Tenant One global Person identity
No Person–Tenant Membership entity First-class Membership
auth_user_accounts.actor_id UNIQUE One Account controls 0..N Actors
Actor has no explicit Tenant and may point to Person/Collaborator Tenant Actor binds to Membership; Global Actor has no tenant identity
Tenant scope carried primarily by Role Grant Tenant Actor itself is tenant-specific
PERSON Role and Role Grant provide self-service Self-service derived intrinsically from Actor → Membership → Person
Application Admin grant uses application scope / wildcard behavior Global Actor + explicit control-plane authority; no implicit tenant data access
Tenant options derived from Actor grants Tenant options derived from Account's active tenant Actors/Memberships
Collaborator created from eligible Person Collaborator created from eligible Person–Tenant Membership
Expenses reference Collaborator Journey Expense owned by Person + Tenant; Journey may remain provenance
Ledger Earnings/current-account records reference Collaborator Journey Financial record owned by Person + Tenant; Journey may remain provenance
Audit centers on Actor/Tenant/permission Audit preserves Account + Actor + Person/Membership + Tenant + Session + authorization source/Lease

These are architectural migrations, not cosmetic changes.

7. Lifecycle Rules

7.1 Person creation

  • Any human may create an ERS Person record.
  • Person creation is global.
  • Person creation creates no Tenant membership or tenant access.
  • ERS must prevent duplicate global Person identities.

7.2 Membership creation

  • Only a Tenant Administrator may create the Person–Tenant Membership for their Tenant.
  • The Tenant Administrator may find/select the global Person needed for the membership, but the system must not reveal that Person's relationships with other Tenants.
  • Creating Membership does not make the Person a Collaborator.

7.3 Tenant Actor creation

  • A tenant Actor requires an Authentication Account and Person–Tenant Membership.
  • Actor activation determines whether the Account can operate in that Tenant.
  • Actor deactivation affects only that Tenant.

7.4 Collaborator creation

  • Requires the Person–Tenant Membership.
  • Does not create another Authentication Account or Person.
  • Does not replace the tenant Actor.

7.5 Collaborator closure

  • Ends current-collaborator capabilities.
  • Preserves Membership, Person, financial history, and authorization history.
  • Historical Earnings/Expenses remain Person + Tenant records.

7.6 Account deactivation

  • Prevents authentication to all ERS contexts.
  • Revokes active Sessions.
  • Does not erase Persons, Memberships, Actors, Collaborator Journeys, Earnings, Expenses, or audit history.

7.7 Tenant Actor deactivation

  • Removes access only to that Tenant.
  • Does not affect authentication to other Tenants.
  • Preserves all historical records.

7.8 Tenant switch

  • Authentication Account remains the same.
  • Session authentication remains the same.
  • Global Person remains the same.
  • Effective tenant Actor changes.
  • Tenant, intrinsic self-service context, and delegated Role Grants change.
  • Tenant-bound frontend/cache state must not leak across the switch.

7.9 Global Person update

  • The Person may update permitted global fields.
  • A Tenant Administrator may update permitted global Person fields while the Person has an active Membership in that Tenant.
  • Tenant-private information remains on Membership.
  • Tenant-originated global changes are audited.

8. Database Invariant Summary

The target schema must enforce at least these invariants:

  1. One Authentication Account per human.
  2. One global Person per human represented in the business domain.
  3. Person has no Tenant owner.
  4. At most one enduring Person–Tenant Membership per (person, tenant).
  5. A Tenant user cannot enumerate another Tenant's Memberships.
  6. Tenant Actor references one Membership/one Tenant.
  7. One Account may control many tenant Actors.
  8. Global Application Administrator Account cannot own tenant Actors or Person identity.
  9. No wildcard Actor means "all tenants."
  10. Self-service does not require a persisted PERSON Role Grant.
  11. Tenant Role Grants cannot cross Actor Tenant.
  12. Collaborator Journey requires Membership and shares its Tenant.
  13. Earnings and Expenses require both person_id and tenant_id.
  14. Financial Journey provenance, when present, must agree with Person/Tenant.
  15. Account deactivation invalidates Sessions.
  16. Tenant Actor deactivation blocks only that Tenant.
  17. Support Lease is one-Tenant, time-bounded, revocable, attributable, and non-transferable.
  18. Support Lease termination takes effect immediately.
  19. Audit records preserve the complete effective identity/authorization chain.
  20. Historical identity, financial, collaboration, and authorization records are not silently reassigned across tenants.

9. Proposed Bite 30 Implementation Sequence

Bite 30A was intentionally completed before committing the implementation sequence. Based on the architectural decisions above and inspection of the Bite 28 baseline, the following sequence is now appropriate.

The exact patch contents may reveal minor boundary adjustments, but these are the intended implementation responsibilities.

Bite 30A — Identity and Access Domain Model Audit and Decision

Status: This document.

No schema migrations or behavior changes.

Deliverables:

  • authoritative model;
  • cardinality and ownership decisions;
  • lifecycle decisions;
  • confidentiality rules;
  • target authorization semantics;
  • implementation sequence.

Bite 30B — Global Person and Person–Tenant Membership Foundation

Purpose: Remove Tenant ownership from Person and introduce the explicit tenant participation relationship.

Implementation responsibilities:

  • create Person–Tenant Membership schema/model;
  • backfill one Membership for every existing tenant-owned Person;
  • migrate tenant-specific Person status/notes/administrative state to Membership where appropriate;
  • establish the global Person model;
  • replace tenant-scoped Person identity assumptions;
  • implement safe global-Person lookup for Membership creation without exposing other tenant relationships;
  • enforce that only Tenant Administrators create Memberships;
  • preserve/audit Tenant Administrator updates to global Person fields;
  • update Person APIs/repositories/services to separate global identity from tenant membership.

Migration must be additive/backfillable before destructive removal of legacy fields.

Bite 30C — Authentication Account and Actor Cardinality/Scope Refactor

Purpose: Implement one Account controlling multiple tenant Actors and explicit global-vs-tenant Actor semantics.

Implementation responsibilities:

  • replace the one-to-one auth_user_accounts.actor_id architecture;
  • associate tenant Actors with Person–Tenant Memberships;
  • establish explicit Actor scope;
  • support multiple tenant Actors per Account;
  • establish the Global Actor form;
  • prohibit Application Administrator Accounts from owning Person/tenant Actor identities;
  • backfill existing Accounts/Actors safely;
  • preserve authentication/session history.

Bite 30D — Self-Service and Delegated Authorization Refactor

Purpose: Separate intrinsic Person authorization from delegated administrative/operator authority.

Implementation responsibilities:

  • remove PERSON Role Grant as the source of self-service rights;
  • derive own-resource authorization from Account → tenant Actor → Membership → Person;
  • retain Role/Role Grant for delegated authority only;
  • constrain tenant Role Grants to the tenant Actor's Tenant;
  • replace wildcard/global-to-tenant authorization behavior;
  • establish separate global/control-plane permissions;
  • update route authorization and policy tests.

Bite 30E — Session and Tenant Selection Refactor

Purpose: Make Tenant selection select an Account-owned tenant Actor rather than merely applying a Tenant hint to one global Actor.

Implementation responsibilities:

  • tenant options derive from active tenant Actors/Memberships;
  • Tenant switching changes effective Actor/context;
  • Session remains Account-authenticated;
  • enforce Actor activation independently by Tenant;
  • prevent global and tenant authority from being combined;
  • clear/partition tenant-bound frontend state on Actor switch;
  • implement account/Actor deactivation and reactivation semantics consistently.

Bite 30F — Collaborator Membership Cutover

Purpose: Make Person–Tenant Membership the prerequisite and enduring parent relationship for collaboration.

Implementation responsibilities:

  • Collaborator creation requires Membership;
  • Collaborator eligibility searches Memberships rather than tenant-owned People;
  • Journey references/enforces Membership;
  • preserve multiple historical Journeys for one Membership;
  • ensure ending a Journey changes collaborator capabilities without destroying Person/Membership/Actor identity;
  • update collaborator UI/API/test fixtures.

Bite 30G — Person + Tenant Financial Ownership Refactor

Purpose: Make Earnings and Expenses enduring Person financial history with explicit Tenant provenance.

Implementation responsibilities:

  • add/establish person_id + tenant_id ownership on Expense and earning/ledger records;
  • backfill Person from existing Collaborator Journey relationships;
  • retain Journey/source references as provenance where useful;
  • enforce Person/Tenant/Journey consistency;
  • refactor Current Account/self-service queries to Person + Tenant;
  • preserve historical records after Journey closure;
  • verify Tenant operators remain tenant-confined.

This is intentionally separate from Bite 30F because the baseline currently makes Collaborator Journey the financial owner and migration risk is significant.

Bite 30H — Global Administration Control Plane and Tenant Support Access Lease

Purpose: Remove standing tenant-data authority from Application Administrators.

Implementation responsibilities:

  • define Global Actor/control-plane authorization;
  • remove Application Administrator wildcard tenant-data semantics;
  • ensure Application Administrator cannot become Person, Member, tenant Actor, or Collaborator;
  • implement Tenant Support Access Lease;
  • require Tenant approval for ordinary support access;
  • implement expiration;
  • implement immediate Tenant Administrator termination;
  • enforce narrow one-Tenant lease scope;
  • expose active/history support access to Tenant Administrators;
  • prevent lease access from being treated as Role Grant or tenant identity.

Break-glass access is out of scope unless separately decided.

Bite 30I — Audit Identity and Lifecycle Hardening

Purpose: Make the new identity chain and all privilege transitions fully attributable and lifecycle-safe.

Implementation responsibilities:

  • audit Account + effective Actor + Person/Membership + Tenant;
  • audit authorization source: intrinsic, Role Grant, global control plane, or Support Lease;
  • correlate sensitive requests to Session;
  • audit global Person changes with originating Tenant/Actor;
  • audit Actor/account/membership/collaborator lifecycle transitions;
  • harden append-only audit protections;
  • ensure Tenant visibility into its support-access audit;
  • verify deactivation/reactivation cannot leave stale privilege.

Bite 30J — Legacy Schema Removal and Migration Hardening

Purpose: Complete the architectural cutover and remove compatibility structures only after all runtime paths use the target model.

Implementation responsibilities:

  • remove legacy people.tenant_id assumptions;
  • remove obsolete Account→single-Actor constraints;
  • remove obsolete Actor Person/Collaborator linkage where superseded by Membership;
  • remove PERSON role/grant dependency;
  • remove tenant_id='*' authorization semantics;
  • remove obsolete Collaborator-as-financial-owner constraints;
  • enforce final foreign keys, uniqueness, immutability, and cross-tenant integrity triggers/constraints;
  • test fresh migration, upgrade migration, rollback strategy where supported, and seed/reset behavior;
  • validate production-compatible migration sequencing.

Bite 30K — Authorization Boundary and Identity E2E Verification

Purpose: Final Bite 30 verification and the replacement for deferred Bite 28E.

Required verification sequence:

  1. schema + migration hardening verification;
  2. authorization-boundary verification;
  3. Tenant/User/Auth E2E coverage;
  4. multi-tenant Authentication Account / Actor-selection E2E;
  5. cross-tenant Person–Membership confidentiality E2E;
  6. cross-tenant financial isolation E2E;
  7. Application Administrator control-plane isolation E2E;
  8. Tenant Support Access Lease approval/expiration/immediate-termination E2E;
  9. Account/Actor/Membership/Collaborator lifecycle E2E;
  10. password/session/deactivation/reactivation E2E;
  11. audit-attribution E2E;
  12. make local-check;
  13. deployment verification in the promotion path.

Bite 30K absorbs the intent of the originally planned Bite 28E rather than duplicating it.

10. Required End-State E2E Scenarios

The final verification must include at least these identities and transitions:

Ordinary Person — one Tenant

  • create Person;
  • Tenant Admin creates Membership;
  • Account controls tenant Actor;
  • Person authenticates;
  • Person sees only own permitted resources;
  • no PERSON Role Grant required.

Ordinary Person — multiple Tenants

  • one Account;
  • one global Person;
  • Membership A + Actor A;
  • Membership B + Actor B;
  • switch A ↔ B;
  • correct self-service financial records in each;
  • no cross-tenant cache/data leakage.

Cross-tenant confidentiality

  • Tenant A users can find/use Maria through Membership A;
  • they cannot discover Membership B;
  • they cannot infer Maria's Tenant-B Actor, Collaborator Journey, Roles, Earnings, Expenses, or other relationship data.

Collaborator lifecycle

  • Membership exists before collaboration;
  • create Journey from Membership;
  • active Collaborator sees current collaborator capabilities;
  • close Journey;
  • current collaborator capabilities disappear;
  • historical Person financial records remain available according to Person self-service rules.

Tenant Actor deactivation

  • deactivate Actor A;
  • Tenant A becomes inaccessible;
  • Tenant B remains accessible through Actor B;
  • reactivate Actor A;
  • Tenant A access returns without recreating the Account/Person/Membership.

Authentication Account deactivation

  • Account deactivation immediately invalidates Sessions;
  • no Tenant remains accessible;
  • reactivation does not corrupt Actor state.

Delegated authorization

  • Tenant Administrator/Operators receive only Tenant-local authority;
  • revoking a Role Grant removes delegated authority but not intrinsic own-resource authorization.

Application Administrator

  • Account has Global Actor only;
  • no Person;
  • no Membership;
  • no tenant Actor;
  • cannot read tenant business data through global authority;
  • can perform defined control-plane operations.

Support Access Lease

  • Tenant Administrator approves one-Tenant lease;
  • Global Administrator accesses only approved support scope;
  • another Tenant remains inaccessible;
  • lease expires automatically;
  • Tenant Administrator can terminate before expiration;
  • termination takes effect immediately;
  • every action is attributable to Account, Global Actor, Tenant, and Lease.

11. Decisions Intentionally Deferred

These matters do not block the Bite 30 implementation sequence unless new requirements make them necessary:

  • exact break-glass/emergency-access policy;
  • tenant-controlled/end-to-end encryption;
  • per-tenant application-layer encryption keys;
  • exact global Person deduplication algorithm beyond the requirement that duplicate global identities be prevented;
  • additional notification workflows when one Tenant Administrator changes shared global Person information.

They should not be accidentally implemented as part of a smaller Bite without a separate architectural decision.

12. Definition of Done for Bite 30

Bite 30 is complete only when:

  • the runtime model matches this authoritative identity model;
  • legacy contradictory structures are removed or rendered non-authoritative;
  • migration paths preserve existing production data and audit history;
  • Application Administrator authority cannot implicitly expose tenant business data;
  • Tenant A cannot discover Tenant B's relationship with the same global Person;
  • Person self-service no longer depends on delegated PERSON Role Grants;
  • one Authentication Account can operate through multiple tenant Actors;
  • Collaborator lifecycle depends on Membership;
  • Earnings and Expenses are owned by Person + Tenant;
  • Support Access Lease behavior is scoped, expiring, immediately revocable, and audited;
  • authorization-boundary tests pass;
  • Tenant/User/Auth E2E coverage passes;
  • cross-tenant isolation E2E passes;
  • lifecycle E2E passes;
  • make local-check passes;
  • deployment verification passes.

13. Architectural Decision Summary

Bite 30 replaces a model in which identity, Tenant ownership, Actor scope, self-service Roles, and Collaborator financial ownership are partially conflated with a model based on explicit separations:

Authentication Account identifies the human for authentication.

Person identifies the human globally in the business domain.

Person–Tenant Membership establishes participation in one Tenant.

Tenant Actor identifies that Person acting within that Tenant.

Self-service rights arise intrinsically from that identity chain.

Role Grants add delegated authority within the Actor's scope.

Collaborator Journey adds a tenant-specific business relationship and current collaborator capabilities.

Earnings and Expenses belong to Person + Tenant, with Journey retained only as provenance where applicable.

Global Actor provides Application Administration without tenant identity or standing tenant-data access.

Tenant Support Access Lease provides exceptional, explicit, expiring, Tenant-revocable and auditable support access without making the Application Administrator a tenant user.

This model is the architectural authority for Bite 30B and later implementation work.