Security
How local-cert protects the secrets it holds, how it marks what it writes in your zones, and the narrowest Route53 permissions it can run with.
Secrets and access
- Passwords are hashed with argon2id (19 MiB, t=2, p=1), with the parameters carried in the PHC string — raising them later keeps old hashes verifiable.
- Private keys are encrypted with AES-256-GCM (
MASTER_KEY) before being inserted into the database. They only travel in clear on/bundle, with thecert:exportscope, and every export is recorded in the audit log. - Every mutation goes through
audit_log(actor, action, target, IP). - Webhooks are signed with HMAC-SHA256 (
X-Signature: sha256=…, keyWEBHOOK_SECRET). httpOnly+SameSite=laxsession cookie: no CSRF on mutating endpoints, since the cookie is never attached to a cross-site POST.- Your own account's API key cannot be deleted from the console (revoking it is possible, and reversible). Rotate it with
scripts/reset-admin.ts. - No secret is written to disk: no token, no password, no bootstrap file.
Resource marking
Everything local-cert creates is stamped managed-with-local-cert.
AWS constraint: Route53 exposes no tags on resource record sets. ChangeTagsForResource only accepts hostedzone and healthcheck. Real AWS tags are therefore out of reach for DNS records. Provenance is recorded through the only two channels a record set allows.
1. The ChangeBatch comment
On every single write, without exception:
Comment: managed-with-local-cert | UPSERT A nas.home.example.com
Comment: managed-with-local-cert | UPSERT TXT _acme-challenge.nas.home.example.com
Comment: managed-with-local-cert | DELETE A nas.home.example.comVisible in the Route53 change history and in the matching CloudTrail event. Useful for auditing, but not queryable.
2. A companion TXT record
_local-cert.<name>, with the value managed-with-local-cert, written in the same ChangeBatch as the record itself (atomic: never an orphan marker after a partial write, and zero extra API calls):
nas.home.example.com. A 60 192.168.1.50
_local-cert.nas.home.example.com. TXT 60 "managed-with-local-cert"This is what makes ownership queryable: a plain dig is enough, and it survives a database that has lost track of a record.
dig +short TXT _local-cert.nas.home.example.com
# "managed-with-local-cert"GET /api/v1/dns/records resolves ownership from the markers present in the zone and annotates each row:
{ "name": "nas.home.example.com", "type": "A", "managed": true, "marker": false }
{ "name": "_local-cert.nas.home.example.com", "type": "TXT", "managed": false, "marker": true }
{ "name": "legacy.home.example.com", "type": "A", "managed": false, "marker": false }What is not marked, and why
| TXT marker | Comment | |
|---|---|---|
| Persistent A/AAAA/CNAME/TXT | yes | yes |
_acme-challenge.* | no — lives ~2 min, deleted at the end of the order | yes |
| Wildcard names | no — Route53 only accepts * as the leftmost label, _local-cert.*.x is invalid | yes |
TAG_RECORDS=0 disables the TXT markers; the comments remain.
Hosted zones: local-cert never creates any, it consumes existing zones. They are therefore not tagged — that would mean modifying a resource it does not own. If you want that tag, set it yourself:
aws route53 change-tags-for-resource --resource-type hostedzone \
--resource-id Z0123456ABCDEFGHIJK \
--add-tags Key=managed-with,Value=local-certRoute53 IAM
The console generates the provider's policy for you, with your real identifiers: see the AWS provider guide for the user / role model and the step-by-step setup. This section is the reference for writing or auditing a policy by hand.
Least-privilege policy — the application only needs to write _acme-challenge TXT records, plus the A/AAAA records you explicitly ask it for:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "route53:ChangeResourceRecordSets",
"Resource": "arn:aws:route53:::hostedzone/Z0123456ABCDEFGHIJK",
"Condition": {
"ForAllValues:StringEquals": {
"route53:ChangeResourceRecordSetsRecordTypes": ["TXT", "A", "AAAA"]
},
"ForAllValues:StringLike": {
"route53:ChangeResourceRecordSetsNormalizedRecordNames": [
"*.home.example.com"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"route53:GetChange",
"route53:GetHostedZone",
"route53:ListResourceRecordSets"
],
"Resource": "*"
}
]
}The TXT type covers both the _acme-challenge challenges and the _local-cert provenance markers. A ready-to-use copy is in docs/iam-policy.json in the repository (replace the zone ID).
Preflight
Permissions are probed when a domain is added: if a required call is missing, the domain is not created and the console shows exactly which one and why. ?force=true (the Save anyway button) lets you save it regardless and fix IAM afterwards.
The declared base name is also checked against the zone's actual apex: entering home.example.com with a zone that serves apps.exemple.co is rejected immediately.
The same checks from the command line:
npm run aws:check -- Z0123456ABCDEFGHIJK # provider PROVIDER_AWS_DEFAULT_*
npm run aws:check -- Z0123456ABCDEFGHIJK PROD # another declared providerIt probes the five calls the code actually makes and reports which ones are missing. Write access is tested with a DELETE of a record that cannot exist: Route53 evaluates IAM before validating the batch, so an authorized principal gets InvalidChangeBatch and a denied principal gets AccessDenied — in both cases the zone is left untouched.
Probing beats reading the policy: the IAM document is usually unreadable from a scoped key, and a condition that doesn't match produces exactly the same message as a missing statement.
zone Z0123456ABCDEFGHIJK (us-east-1) — home.example.com
OK ListResourceRecordSets
DENIED GetHostedZone REQUIRED — used to read the delegation set…
OK GetChange
DENIED ChangeResourceRecordSets (TXT) REQUIRED — DNS-01 is built on TXT records…
OK ChangeResourceRecordSets (A)Three pitfalls that produce the same AccessDenied
The message “because no identity-based policy allows the … action” doesn't mean there is no policy: it is also what AWS returns when a policy exists but a condition doesn't match.
1. TXT missing from ChangeResourceRecordSetsRecordTypes. DNS-01 relies entirely on TXT records — without this type, nothing can be issued. A policy that only allows A lets the host record be published and refuses everything else.
2. Two Condition blocks with the same operator. JSON silently keeps only the last one:
"Condition": {
"ForAllValues:StringEquals": { "route53:ChangeResourceRecordSetsRecordTypes": ["TXT","A"] },
"ForAllValues:StringEquals": { "route53:ChangeResourceRecordSetsActions": ["UPSERT","DELETE"] }
}The constraint on types disappears. Merge the keys into a single block per operator.
3. GetHostedZone forgotten. Often missing from “minimal” policies found online, because most ACME clients don't use it. local-cert needs it to read the delegation set and query the authoritative name servers — without it, issuance fails at the propagation step, after writing the challenge TXT.
Credentials come from the standard AWS chain (environment, ~/.aws/credentials, IRSA, instance role) when the provider carries no key pair. An aws_role_arn per domain lets you assume a dedicated role per zone — useful across multiple accounts.