Credential security

DNSMigrator encrypts each provider credential before storing it and deletes it after the configured inactivity window. The key point is that every connection has its own data key and encryption context, so moving an encrypted blob to another workspace or connection does not make it decryptable there.

What is stored#

A connection row contains the provider ID, your label, a limited credential hint, the last access result and an encrypted secret. The connection list never receives the plaintext credential. Depending on the provider, the hint may contain a shortened account identifier, a username, or only the final characters of a token.

The secret is the provider credential object accepted by that adapter: for example, an API token, a service-account document or a role ARN plus server-supplied context. Zone records, migration plans and audit entries are stored separately from the credential.

Envelope encryption#

Production uses AWS KMS envelope encryption. DNSMigrator does not encrypt every credential directly with one reusable application key.

During decryption, KMS must unwrap the data key with the same workspaceId and connectionId. AES-GCM then authenticates that same canonical context. A wrong key, changed context or modified ciphertext fails closed with a decryption error.

Local development can use a 32-byte base64 master key through DNSM_MASTER_KEY. Production selects KMS with DNSM_KMS_KEY_ID; the runtime refuses a local master key in production unless an explicit operator override is present. The hosted security model is described at /security.

When credentials are decrypted#

A credential is decrypted only when a user action or worker job needs to contact the provider. Current reasons include checking access, listing zones, reading a migration source or destination, applying or rolling back a migration, importing or pushing a managed zone, backups, drift checks, and registrar cutover steps.

Every successful credential load writes a credentials.decrypt audit entry with:

• the workspace and connection target;
• whether the caller was a user or worker;
• a reason string for the operation; and
• the provider ID in scrubbed metadata.

The audit helper drops metadata keys whose names contain token, secret, password, key, credential or private. Provider HTTP clients can also register secret values for redaction before an error reaches the connection row. Unknown exceptions are replaced with a generic provider-contact message rather than returned verbatim.

See Activity log for what the web UI currently displays from these entries.

Credential lifetime and deletion#

The default inactivity window is 24 hours. Creation sets a deletion deadline, and each later credential load moves that deadline forward by the configured interval. This means Check access, listing zones and worker operations can extend the deadline; it is not limited to migration applies.

The purge worker selects expired connections and replaces the encrypted secret with null. It also clears recorded scopes, changes the connection status to Credentials deleted, removes the deadline and writes a connection.purge audit entry. It does not purge a connection while a preview, apply, verification or rollback job is actively using it.

You can delete sooner. On Connections, select Remove and then Remove and delete credentials. The service erases the secret immediately unless an apply, verification or rollback is using the connection. Historical migrations retain their records and events, but can no longer use that credential.

DNSMigrator has no “show secret” or secret-download action. Purge and removal are therefore irreversible from the UI.

Scope credentials at the provider#

Encryption limits exposure inside DNSMigrator; it does not reduce what a broad provider token can do. Scope the credential at its source:

Use separate source and destination credentials when that produces a narrower boundary. Revoke a credential in the provider console when the work is complete, even if its encrypted copy is waiting for automatic deletion.

Route 53 role access#

For Amazon Route 53, production rejects access-key credentials and uses a cross-account IAM role. Open CloudFormation creates a role whose trust policy allows DNSMigrator’s AWS account to call sts:AssumeRole only with your workspace external ID.

The read policy includes hosted-zone listing, hosted-zone details, record-set listing and change-status reads. If you select Include write access (needed to apply to Route 53), the stack also grants record-set changes and hosted-zone creation. The role session duration is capped by the generated role configuration, and DNSMigrator stores the role ARN rather than a customer access-key pair.

The external ID appears under Settings and in the Route 53 connection flow. It is not a password, but it is part of the trust boundary; do not reuse another workspace’s value.

Operational checklist#

• Prefer a dedicated, narrowly scoped provider identity.
• Use read-only access for source-only connections.
• Review Read or Read + write after connecting.
• Use Check access after changing scope, then inspect Activity.
• Remove access in DNSMigrator and revoke it at the provider when it is no longer needed.
• Never place credentials in a self-hosted endpoint URL. See Self-hosted providers for endpoint restrictions.

Credential security questions#