>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3593589. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !6 >>> <p><strong>Summary</strong></p> <p>Let one Drupal instance host several isolated vault realms ("tenants"), each cryptographically sealed from the others, while users keep a single shared account. Motivating case: a city and its metropolitan authority each offer an electronic vault to the same citizens (one shared account), hosted on the same instance, but a citizen city-vault documents must stay unreadable by metropolitan services and the reverse.</p> <p><strong>What "tenant" means here</strong></p> <p>A tenant is a vault realm. The owner (citizen) is a single Drupal uid shared across tenants; each tenant holds a separate vault for that same user. Data therefore partitions on (tenant, owner_uid), and identity is NOT federated: owner_uid is unchanged. This deliberately excludes a per-tenant user identity, which the shared-account model makes unnecessary and which is the costliest part of generic multi-tenancy.</p> <p><strong>Confirmed design decisions</strong></p> <ul> <li><strong>Per-tenant Master KEK.</strong> Each tenant has its own Master KEK, so a key compromise or a rogue operator on one tenant cannot read another. This is a true isolation guarantee, not just a logical partition.</li> <li><strong>Generic, pluggable tenant resolution.</strong> A resolver abstraction decides the current tenant for a request; the core stays connector-agnostic. The API path is authoritative through "the calling consumer implies its tenant". A separate domain connector (resolving the tenant from the active domain, via the domain module) is provided for the owner-facing UI.</li> </ul> <p><strong>Why this is tractable on the current architecture</strong></p> <ul> <li>The key hierarchy is already Master KEK to per-owner Subject KEK to per-document DEK, so users are already cryptographically separated. The tenant dimension means a Subject KEK per (tenant, owner_uid), each wrapped under that tenant Master KEK.</li> <li>The re-wrap primitive exists: <code>MasterKeyRotator</code> already unwraps a Subject KEK under one Master KEK and re-wraps it under another, byte for byte. Per-tenant keying reuses it.</li> <li>The Master KEK is a config-referenced key module Key id (<code>pdv.settings:master_key_id</code>), so per-tenant keying is mostly key routing, not a crypto redesign.</li> <li>Pre-1.0 (alpha): no backward-compatibility constraint, so base fields and schema can change freely now. This is the cheap moment to do it.</li> </ul> <p><strong>Proposed components</strong></p> <ul> <li><strong>Tenant config entity</strong> (for example <code>pdv_tenant</code>): id, label, its own <code>master_key_id</code> (a key module Key), plus optional per-tenant overrides (consent TTL, flood). Supersedes the single site-wide <code>pdv.settings:master_key_id</code> for keying.</li> <li><strong>Tenant context service</strong> holding the active tenant for the request, set early and read where the single <code>Vault</code> and <code>SubjectKeyManager</code> services read config today.</li> <li><strong>TenantResolverInterface</strong> (pluggable): given the request context, return the active tenant. Core ships a consumer-based resolver (the calling consumer tenant, authoritative for API calls) and a safe default. The domain connector maps an active domain to a tenant.</li> <li><strong>Per-(tenant, owner_uid) Subject KEK</strong>: <code>pdv_subject_key</code> gains a tenant field; the unique constraint becomes (tenant, owner_uid); <code>SubjectKeyManager</code> resolves the Master KEK from the tenant.</li> <li><strong>Tenant column</strong> on <code>pdv_item</code>, <code>pdv_grant</code>, <code>pdv_consumer_authorization</code>, and <code>pdv_grant_request</code>, with every query scoped by tenant in addition to owner_uid (today queries are owner_uid only, e.g. <code>Vault::listForOwner</code>).</li> <li><strong>Tenant-scoped consumers</strong>: bind each consumer to a tenant (a mapping layer over drupal/consumers, which is global), so a consumer of one tenant can never resolve another tenant items. Trust and grant inherit the tenant through the consumer.</li> </ul> <p><strong>Decisions still open</strong></p> <ul> <li><strong>Kind catalogue</strong>: shared across tenants (simpler, start here) or per-tenant. <code>pdv_item_kind</code> is global config today.</li> <li><strong>Purge on a shared account</strong>: on user deletion, crypto-erase the Subject KEK of every tenant the user has; also support per-tenant erasure (a citizen using only one realm). Extends <code>Vault::purgeUser</code>, which already crypto-erases by destroying the Subject KEK.</li> <li><strong>Default tenant and migration</strong>: existing single-vault data maps to one default tenant; define the update path that assigns it and wraps the existing Subject KEKs under that tenant Master KEK.</li> <li><strong>Cross-site</strong>: confirm <code>pdv_vault_connection</code> and the consent flow carry the tenant end to end for <code>RemoteVaultClient</code>.</li> </ul> <p><strong>Phased plan</strong></p> <ol> <li>Tenant config entity, tenant context service, and resolver interface, with a single implicit default tenant (no behavior change; all existing data on the default tenant).</li> <li>Per-tenant Master KEK: <code>SubjectKeyManager</code> resolves the Master KEK from the tenant; <code>pdv_subject_key</code> gains tenant; update path wraps existing Subject KEKs under the default tenant KEK.</li> <li>Tenant column on the data tables and scope every query; tenant-scoped consumers; trust and grant inherit the tenant.</li> <li>Consumer-based resolver (API) and the domain connector (owner-facing UI).</li> <li>Purge semantics, kind-catalogue decision, and an admin UI for tenants.</li> </ol> <p><strong>Tests</strong></p> <ul> <li>Two tenants, same owner_uid: an item stored in tenant A is unreadable in tenant B (distinct Subject KEK under a distinct Master KEK).</li> <li>A consumer of tenant A cannot read, grant, or list items of tenant B.</li> <li>Trust and grant are scoped to their tenant.</li> <li>Per-tenant Master KEK rotation re-wraps only that tenant Subject KEKs.</li> <li>Purge crypto-erases per tenant; the default-tenant migration assigns and re-wraps existing data.</li> <li>The domain connector resolves the expected tenant; the consumer-based resolver stays authoritative for API calls.</li> </ul>