Credential rotation
Credential rotation is replacing a secret on a schedule while the systems that use it keep running. The hard part is never the new secret; it is every copy of the old one. On the current host Connect's database settings live in one place, the host's environment file, and nothing rotates them automatically. Each mailbox's token bundle is rebuilt on every refresh rather than held as a snapshot.
Rotation is a problem about copies#
A rotation has three moments: the new secret exists, both secrets are accepted, and the old one stops working. A service that fetches the secret when it needs it crosses all three without noticing. A service that read the secret once and wrote it into a file crosses the first two without noticing and then fails at the third — usually not at the moment of rotation, but at the next restart, which may be days later and will look like whatever else changed in between.
That delay is what makes stale credentials expensive to diagnose. The failure is not attributed to the rotation because the rotation succeeded and nothing broke that day. It is attributed to the deploy that happened to trigger the restart.
Where Connect's database password lives#
Today it is in the production host's environment file, the one the service manager loads when the application starts. PostgreSQL runs on the same host, the file is never in the repository, and no service rotates the password automatically. There is exactly one copy, so a change is a planned step: the database role and the file change together, then the services restart.
The code supports the other shape too. When MAYA_MAIL_DB_SECRET_ARN is set, boot reads the password from a managed secret store, which suits a managed database that rotates its own credential. An earlier host used it, because a stale copy left in an environment file there made the *next restart* authenticate as nobody, which presented as a bad deploy. The current host does not set it.
- Where it is stored now
- The host's environment file, outside the repository.
- When it is read
- At start, before the connection pool is built.
- What a change requires
- Changing the role and the file together, then a restart. Nothing rotates it behind your back.
- What breaks it
- A second copy somewhere else that is not changed with the first.
Credentials you did not issue: OAuth tokens#
A mailbox connected over Google OAuth or Microsoft Graph holds a refresh token and a short-lived access token. The access token rotates constantly and by design — every refresh produces a new one — so the code that stores it has to be able to write back.
In TenantMailbox the config bundle is a real setter rather than a read-only property, and the reason is precisely this: oauth.store_tokens rebuilds the dictionary and assigns it back, so a read-only property would silently drop every refreshed access token. The mailbox would keep working until the token in hand expired, then stop, and the cause would look like a provider outage.
Provider credentials that a workspace types in — an IMAP password, a messaging provider's key — are sealed by settings_store on every save and never echoed back to a screen. Rotating one means entering the new value, not reading the old one back to compare.
Does Connect use credential rotation?#
In different ways for different credentials, and it is worth separating them because they change on different clocks and fail differently.
| Credential | Rotated by | How Connect keeps up |
|---|---|---|
| Database password | Not rotated automatically on the current host; a person changes it, in one place | Read at start from the host's environment file. Reading a managed, rotated secret at boot (MAYA_MAIL_DB_SECRET_ARN) is supported but not configured on the current host |
| OAuth access tokens for a mailbox | The identity provider, continuously | oauth.store_tokens rebuilds and reassigns the config bundle on every refresh |
| Provider keys a workspace supplies | A person, when they choose | Sealed by settings_store on save; never displayed again |
| Your own sign-in | Google, or you | Google sign-in has no Connect password. A Connect password, where one is used, is stored only as an Argon2 hash |
What Connect does not do is claim a certification about any of this. The mechanism is documented so you can judge it; no audit badge is being asserted on the strength of it.
Failure modes worth recognising#
- Everything works, then a restart authenticates as nobody
- A stale credential copy somewhere the rotation system cannot see. Look at what holds a password, not at what deployed.
- One mailbox stops after roughly an hour
- Refreshed tokens are not being persisted. The symptom appears at access-token lifetime, not at reconnection.
- A rotation succeeds and reads fail intermittently
- Some instances hold the old value and some fetched the new one. Fetch-at-boot makes this a restart-ordering question rather than a permanent split.
- A key cannot be compared against what was entered
- Correct. Sealed values are not readable; re-enter rather than verify.
Questions#
Does a rotation interrupt Connect?
A database password change is a planned step on the current host: the role and the environment file change together, then the services restart. An OAuth refresh interrupts nothing, because it happens inside a normal fetch. What interrupts things is a copy of a secret that nobody updated.
Can I see the credentials a workspace has stored?
No. Provider credentials are sealed on save and are never echoed back to a screen, for either audience. You can see that a credential is present, and you can see the health verdicts that tell you whether it still works, but the value itself does not come back out.
Do I have a password to rotate for my own account?
Only if you use one. With Google sign-in, your account security is your Google account's, including its second factor. A Connect password is stored only as an Argon2 hash, sign-in codes are limited per network and per address, and a forgotten password is reset with a code.