Role-based delegation without password sharing: architecture walkthrough

The delegation problem

Small teams routinely share email access. An executive assistant reads and responds to their manager's inbox. A support team shares a help@ address. A founder delegates investor correspondence to a co-founder.

The standard solution is password sharing — sometimes literally writing the password on a sticky note, sometimes through a shared password manager. Both approaches conflate authentication (proving who you are) with authorization (defining what you can do). Anyone with the password has full access to the account, indistinguishable from the account owner.

TwinMail separates these concerns through role-based delegation.

Core concepts

TwinMail's delegation model introduces three abstractions:

Person — a logical grouping representing an individual. A Person owns one or more Accounts. The Person is the unit of identity in TwinMail.

Account — a provider identity (Gmail, Outlook, IMAP) with its own credentials and sync state. Accounts belong to exactly one Person.

Delegation — a permissioned access grant from one Person to another Person's Account or entire identity. Delegations are scoped, time-bounded, and revocable.

Delegation scopes

Each delegation grant specifies a scope that constrains what the delegate can do:

Scope	Permissions
read	View messages and threads, search
respond	Read + compose replies to existing threads
compose	Respond + initiate new threads
manage	Compose + apply labels, snooze, archive
admin	Manage + modify account settings, create sub-delegations

Scopes are hierarchical: each level includes all permissions from lower levels. The default delegation scope is read.

Scope constraints

Beyond the permission level, delegations can be further constrained by:

• Time window — delegation expires after a specified date
• Thread filter — delegation applies only to threads matching a label or sender pattern
• Action quota — delegation allows a maximum number of compose actions per day

These constraints are enforced at the vault level, not the UI level. A delegate's client cannot bypass them because the vault encryption keys for out-of-scope content are never shared.

The cryptographic model

Delegation does not involve sharing the account owner's credentials or vault encryption key. Instead, it uses a key derivation scheme:

1. The account owner generates a delegation-specific key pair using X25519
2. The delegation key is encrypted to the delegate's public key
3. The delegate uses the delegation key to decrypt only the content within their authorized scope

Content outside the delegation scope remains encrypted with the owner's vault key and is inaccessible to the delegate.

DelegationGrant {
  grantor: PersonID,
  grantee: PersonID,
  account: AccountID,
  scope: DelegationScope,
  constraints: DelegationConstraints,
  key: X25519EncryptedKey,
  created_at: ISO8601,
  expires_at: Option<ISO8601>,
  revoked: bool,
}

Revocation

When the account owner revokes a delegation, two things happen:

1. The delegation grant is marked as revoked in the owner's vault
2. The owner's vault re-encrypts any content that was accessible under the delegation, using a fresh key

The re-encryption step ensures that even if the delegate retained the delegation key, they cannot access content after revocation. This is a forward-secrecy property applied to authorization rather than transport.

Delegation discovery

When a delegate opens TwinMail, their client discovers active delegations through the sync layer. The sync server delivers delegation grant blobs (encrypted to the delegate) alongside the delegate's own vault operations.

The delegate's TwinMail instance renders delegated accounts in a distinct UI section with clear visual indicators:

• A delegation badge showing the scope level
• The account owner's name and the delegation expiration date
• Visual restrictions for out-of-scope actions (compose button disabled for read delegates)

Handoff integration

Delegation is designed to work with TwinMail's handoff system. A handoff is a guided action plan generated to transfer responsibility for a set of threads from one person to another.

When a handoff is created, TwinMail can automatically generate a delegation grant with the appropriate scope and constraints. For example, a "vacation handoff" might create a time-bounded respond delegation with a thread filter matching only active conversations.

The handoff document includes:

• Context summaries for each delegated thread
• Suggested response templates
• Escalation criteria (when the delegate should contact the owner)
• Automatic delegation revocation on the owner's return date

Audit trail

Every delegation action is logged in the account owner's vault:

• Grant creation (who, what scope, what constraints)
• Delegate actions within scope (messages read, replies sent)
• Constraint violations attempted (blocked and logged)
• Revocation events

The audit trail is encrypted in the owner's vault and is not accessible to the delegate. It provides a complete record of what the delegate did and did not do during the delegation period.

What this enables

Role-based delegation without password sharing makes several workflows practical:

1. Executive assistance — assistants get scoped access without knowing the executive's password
2. Team inboxes — shared addresses are managed through delegation, not credential distribution
3. Temporary coverage — vacation handoffs create and revoke delegations automatically
4. Compliance — the audit trail provides evidence of who accessed what and when

The underlying principle is that access should be as narrow as the task requires, as temporary as the need demands, and as auditable as the stakes warrant.