docs(config): document the conformance and testing variables - #255
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs/configuration.mdis 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.FIDO_CONFORMANCE_MODE,FIDO_CONFORMANCE_MDS_URLS,FIDO_CONFORMANCE_MDS_ROOT_CERT_FILE,FIDO_CONFORMANCE_METADATA_DIR,DISABLE_AUTH_RATE_LIMITS, andALLOW_UNCREDENTIALED_DELIVERY_SECRETS, with the shared note that each is refused underNODE_ENV=production.FRONTEND_URLdocumented in the Application and minimal-boot tables, andfrontend_urladded to thesystem_configkey table.authenticator_policydefault in thesystem_configtable now showssyncedPasskeys,aaguidAllowListandaaguidDenyList, which it had been missing since those fields landed.FRONTEND_URL is boot-required, and .env.example said otherwise
.env.exampleclaimed it "falls back to the first ORIGINS entry when unset". It does not.frontend_urlhas no entry insystemConfig.defaults.tsand is.optional()in the schema, so with no row and no value set,bootstrapSystemConfigthrowsMissing required system config "frontend_url".validateEnvs.shdoes 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.examplenow ships"syncedPasskeys":"allow"so a stock local instance can enrol the passkey a developer's laptop or phone actually offers, rather than refusing it with403 synced_passkey_not_allowedon 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_DEFAULTSstill derives fromAuthenticatorPolicySchema.parse({}), which isblock, so the secure-by-default position holds for anyone deploying without this file.Also
getEndpointsexample indocs/fido-conformance.mdposted port 5313, which the page never introduces, five lines after telling you to give the tools 5312.docs/configuration.mdsaid the dashboard is pinned tov0.2.0; the Dockerfile ARG isv0.4.0. Corrected, along with the Dockerfile comment that read as the rationale for a different pin.Checks
format:check,lintandtypecheckclean.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-shoutchangeset already documents thesyncedPasskeysfield.I also re-ran a coverage diff afterwards: every variable in
.env.examplenow appears indocs/configuration.md, and every key insystemConfig.envMap.tsappears in itssystem_configtable.