Skip to content

docs(config): document the conformance and testing variables - #255

Merged
Bccorb merged 1 commit into
mainfrom
docs/fido-conformance-env-reference
Sep 3, 2026
Merged

docs(config): document the conformance and testing variables#255
Bccorb merged 1 commit into
mainfrom
docs/fido-conformance-env-reference

Conversation

@Bccorb

@Bccorb Bccorb commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

What

docs/configuration.md is described as covering every environment variable, and README points at it as the full reference, but seven were missing. Six of them are exactly what a FIDO2 conformance run needs, so someone following README to the "full reference" found nothing about conformance at all.

  • New "Testing and conformance (never production)" section covering FIDO_CONFORMANCE_MODE, FIDO_CONFORMANCE_MDS_URLS, FIDO_CONFORMANCE_MDS_ROOT_CERT_FILE, FIDO_CONFORMANCE_METADATA_DIR, DISABLE_AUTH_RATE_LIMITS, and ALLOW_UNCREDENTIALED_DELIVERY_SECRETS, with the shared note that each is refused under NODE_ENV=production.
  • FRONTEND_URL documented in the Application and minimal-boot tables, and frontend_url added to the system_config key table.
  • authenticator_policy default in the system_config table now shows syncedPasskeys, aaguidAllowList and aaguidDenyList, which it had been missing since those fields landed.

FRONTEND_URL is boot-required, and .env.example said otherwise

.env.example claimed it "falls back to the first ORIGINS entry when unset". It does not. frontend_url has no entry in systemConfig.defaults.ts and is .optional() in the schema, so with no row and no value set, bootstrapSystemConfig throws Missing required system config "frontend_url". validateEnvs.sh does not check it either, so a container clears env validation and then exits. Both the file and the reference now say so.

More permissive AUTHENTICATOR_POLICY in .env.example

.env.example now ships "syncedPasskeys":"allow" so a stock local instance can enrol the passkey a developer's laptop or phone actually offers, rather than refusing it with 403 synced_passkey_not_allowed on the first attempt. That was the only genuinely restrictive field in the template; the rest were already the permissive option.

The product default is untouched. SYSTEM_CONFIG_DEFAULTS still derives from AuthenticatorPolicySchema.parse({}), which is block, so the secure-by-default position holds for anyone deploying without this file.

Also

  • The getEndpoints example in docs/fido-conformance.md posted port 5313, which the page never introduces, five lines after telling you to give the tools 5312.
  • docs/configuration.md said the dashboard is pinned to v0.2.0; the Dockerfile ARG is v0.4.0. Corrected, along with the Dockerfile comment that read as the rationale for a different pin.

Checks

format:check, lint and typecheck clean. npm run test:run: 107 files, 1232 passed, 1 skipped, 1 todo.

No changeset: documentation and a local template only, no runtime behavior change, and the pending hungry-bats-shout changeset already documents the syncedPasskeys field.

I also re-ran a coverage diff afterwards: every variable in .env.example now appears in docs/configuration.md, and every key in systemConfig.envMap.ts appears in its system_config table.

The configuration reference is described as covering every environment
variable, but seven were missing: the four FIDO_CONFORMANCE_* values, the
two testing flags that are refused in production, and FRONTEND_URL.

Add a testing and conformance section for the six flags. Document
FRONTEND_URL as boot-required: it is enforced by bootstrapSystemConfig
rather than validateEnvs.sh, so an instance with no frontend_url row and
no value set clears env validation and then exits. .env.example promised a
fallback to the first ORIGINS entry, which is not what happens.

Ship a permissive syncedPasskeys in .env.example so a stock local instance
can enrol the passkey a developer's device offers. The built-in default
stays block.

Also fix the getEndpoints example, which posted a port the conformance
page never introduces, and correct the pinned dashboard tag.
@Bccorb
Bccorb merged commit 9c19ab8 into main Sep 3, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant