feat(passkey): Add verification proof to the challenge manager by nshirley · Pull Request #21114 · mozilla/fxa

nshirley · 2026-08-26T23:24:53Z

Because:

A wrap write needs proof that a user-verified assertion just completed for a specific credential, which a session token alone cannot attest.
A proof is the same primitive as a challenge — a random value minted, then consumed once — so a second Redis module would be duplication.

This commit:

Adds a 'proof' challenge type, separately typed so an upgrade challenge handed out before any assertion cannot be spent as a proof.
Adds generateProofChallenge and consumeProofChallenge, credential-scoped.
Takes the proof TTL from PASSKEYS__VERIFICATION_PROOF_TIMEOUT, which spans the password entry a ceremony challenge does not.
Adds errnos 236 and 237 with their AppError factories.

Closes: Part of FXA-13142 (sister pr is the bulk of that work)

Checklist

Put an x in the boxes that apply

My commit is GPG signed.
If applicable, I have modified or added tests which pass locally.
I have added necessary documentation (if appropriate).
I have verified that my changes render correctly in RTL (if appropriate).
I have manually reviewed all AI generated code.

How to review (Optional)

Key files/areas to focus on:
Suggested review order:
Risky or complex parts:

Screenshots (Optional)

Please attach the screenshots of the changes made in case of change in user interface.

Other information (Optional)

Any other information that is important to this pull request.

nshirley · 2026-08-26T23:28:29Z

+      return false;
+    }
+
+    if (stored.credentialId !== credentialId) {


Should be REALLY unlikely to happen, but defense-in-depth!

nshirley · 2026-08-27T19:01:16Z

 // Matches the config default (passkeys.challengeTimeout = 300,000 ms)
 const CHALLENGE_TIMEOUT_MS = 1000 * 60 * 5;

+// Different from CHALLENGE_TIEMOUT_MS to allow tests to deterministically default behavior of proofs


Suggested change

// Different from CHALLENGE_TIEMOUT_MS to allow tests to deterministically default behavior of proofs

// Different from CHALLENGE_TIMEOUT_MS so tests are able to deterministically verify which timeout is used

nshirley · 2026-08-27T19:30:39Z

+
+/**
+ * Length in base64url characters of a challenge or proof token, which are 32
+ * random bytes. Used to validate a proof on the wire before hitting Redis.


Suggested change

* random bytes. Used to validate a proof on the wire before hitting Redis.

* random bytes. Used for Joi validation of the proof before hitting Redis.

Because: * A wrap write needs proof that a user-verified assertion just completed for a specific credential, which a session token alone cannot attest. * A proof is the same primitive as a challenge — a random value minted, then consumed once — so a second Redis module would be duplication. This commit: * Adds a 'proof' challenge type, separately typed so an upgrade challenge handed out before any assertion cannot be spent as a proof. * Adds generateProofChallenge and consumeProofChallenge, credential-scoped. * Takes the proof TTL from PASSKEYS__VERIFICATION_PROOF_TIMEOUT, which spans the password entry a ceremony challenge does not. * Adds errno 236, PASSKEY_VERIFICATION_PROOF_INVALID, and its AppError factory.

vpomerleau

This looks straightforward, just some naming nits. 🎉

vpomerleau · 2026-08-27T19:33:51Z

 *   vice versa. UID is required when generating an upgrade challenge.
+ *
+ * - 'proof': Not a ceremony challenge. Minted *after* an assertion verifies and
+ *   consumed once to authorise key creation for that credential. Carries no key


Nit: Is it too specific to note this is specifically for key/wrap creation? Conceivably we could use this proof to authorize other actions in the future.

It's a good idea, but I don't think we would want to use this for that at this time. The challenges (create, proof, any of them) don't carry any additional authorization material like scopes, so anything that mints a proof could then use that same proof if we accept it on multiple endpoints.

That said, I think we could explore allowing passkeys as an option to mint the existing MFA JWT tokens. But that would likely need a lot more thought, UX, design, etc since we'd have to handle opt-in, fall backs, etc

vpomerleau · 2026-08-27T19:40:45Z

+ * - 'proof': Not a ceremony challenge. Minted *after* an assertion verifies and
+ *   consumed once to authorise key creation for that credential. Carries no key
+ *   material; it attests only that the assertion happened. Typed separately from
+ *   'upgrade' because an upgrade challenge is issued before any assertion — were


Nit: We currently are not using the upgrade challenge, and I wonder if we should rename more generically to authorization challenge? This would conceivably be the challenge we need whenever an already authenticated user uses the passkey to authorize account changes (such as storing a new key wrap or as alternative to the email code MFA).

Copilot

Pull request overview

Extends the passkey challenge manager with credential-scoped, single-use verification proofs for subsequent key-wrap creation.

Changes:

Adds proof generation and consumption with independent TTL configuration.
Adds proof validation errors and errno 236.
Adds unit and integration coverage for proof scope, expiry, and single use.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`packages/fxa-auth-server/config/index.ts`	Adds proof timeout configuration.
`libs/accounts/passkey/src/lib/webauthn-adapter.spec.ts`	Updates test configuration.
`libs/accounts/passkey/src/lib/passkey.service.spec.ts`	Updates service test configuration.
`libs/accounts/passkey/src/lib/passkey.provider.ts`	Extends raw passkey configuration.
`libs/accounts/passkey/src/lib/passkey.provider.spec.ts`	Updates provider fixtures.
`libs/accounts/passkey/src/lib/passkey.manager.spec.ts`	Updates manager fixtures.
`libs/accounts/passkey/src/lib/passkey.manager.in.spec.ts`	Updates integration fixtures.
`libs/accounts/passkey/src/lib/passkey.config.ts`	Models the proof timeout.
`libs/accounts/passkey/src/lib/passkey.challenge.manager.ts`	Implements credential-scoped proofs.
`libs/accounts/passkey/src/lib/passkey.challenge.manager.spec.ts`	Tests proof storage and TTL selection.
`libs/accounts/passkey/src/lib/passkey.challenge.manager.in.spec.ts`	Tests proof isolation and single use.
`libs/accounts/errors/src/index.spec.ts`	Tests the new AppError factory.
`libs/accounts/errors/src/constants.ts`	Adds proof-invalid errno 236.
`libs/accounts/errors/src/app-error.ts`	Adds the proof-invalid AppError factory.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+  @IsNumber()
+  public verificationProofTimeout!: number;


nshirley · 2026-08-31T17:44:07Z

After further conversation, we've decide to not implement this at this time. If we need it down the road we can always re-open or reference this pr

nshirley commented Aug 26, 2026

View reviewed changes

Comment thread libs/accounts/passkey/src/lib/passkey.challenge.manager.in.spec.ts Outdated

nshirley commented Aug 26, 2026

View reviewed changes

nshirley commented Aug 27, 2026

View reviewed changes

Comment thread libs/accounts/errors/src/app-error.ts Outdated

nshirley force-pushed the FXA-13142-1 branch 3 times, most recently from 30b6aca to fdcf48f Compare August 27, 2026 15:58

nshirley commented Aug 27, 2026

View reviewed changes

nshirley changed the title ~~task(passkey): Add verification proof to the challenge manager~~ feat(passkey): Add verification proof to the challenge manager Aug 27, 2026

nshirley commented Aug 27, 2026

View reviewed changes

Comment thread libs/accounts/passkey/src/lib/passkey.challenge.manager.ts Outdated

nshirley commented Aug 27, 2026

View reviewed changes

Comment thread libs/accounts/passkey/src/lib/passkey.challenge.manager.ts Outdated

nshirley force-pushed the FXA-13142-1 branch from fdcf48f to f7e8faa Compare August 27, 2026 19:35

vpomerleau approved these changes Aug 27, 2026

View reviewed changes

nshirley marked this pull request as ready for review August 27, 2026 23:30

nshirley requested a review from a team as a code owner August 27, 2026 23:30

Copilot AI balanced review requested due to automatic review settings August 27, 2026 23:30

Copilot started reviewing on behalf of nshirley August 27, 2026 23:30 View session

Copilot AI reviewed Aug 27, 2026

View reviewed changes

Comment thread libs/accounts/passkey/src/lib/passkey.config.ts

Comment on lines +97 to +98

@IsNumber()

public verificationProofTimeout!: number;

Comment thread libs/accounts/errors/src/constants.ts

nshirley closed this Aug 31, 2026

nshirley mentioned this pull request Aug 31, 2026

task(passkey): Implement POST /passkey/wraps #21116

Draft

5 tasks

Navigation Menu

Uh oh!

feat(passkey): Add verification proof to the challenge manager - #21114

feat(passkey): Add verification proof to the challenge manager#21114
nshirley wants to merge 1 commit into
mainfrom
FXA-13142-1

nshirley commented Aug 26, 2026

Uh oh!

Uh oh!

nshirley Aug 26, 2026

Uh oh!

Uh oh!

nshirley Aug 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

nshirley Aug 27, 2026

Uh oh!

Uh oh!

vpomerleau left a comment

Uh oh!

vpomerleau Aug 27, 2026

Uh oh!

nshirley Aug 28, 2026

Uh oh!

vpomerleau Aug 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

nshirley commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	// Different from CHALLENGE_TIEMOUT_MS to allow tests to deterministically default behavior of proofs
	// Different from CHALLENGE_TIMEOUT_MS so tests are able to deterministically verify which timeout is used

	* random bytes. Used to validate a proof on the wire before hitting Redis.
	* random bytes. Used for Joi validation of the proof before hitting Redis.

Uh oh!

Conversation

nshirley commented Aug 26, 2026

Checklist

How to review (Optional)

Screenshots (Optional)

Other information (Optional)

Uh oh!

Uh oh!

nshirley Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nshirley Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nshirley Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vpomerleau left a comment

Choose a reason for hiding this comment

Uh oh!

vpomerleau Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

nshirley Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

vpomerleau Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

nshirley commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nshirley Aug 27, 2026 •

edited

Loading