task(passkey): Implement POST /passkey/wraps

[nshirley]

Because

• Passwordless Sync needs somewhere to store the envelope that lets a passkey unlock kB without a password.
• A wrap is create-only: rotating kB invalidates it, so a stale one is replaced by deleting the passkey and re-enrolling, never by an update.

This pull request

• Adds POST /passkey/wraps, one envelope per credential, behind a verified session token and the passwordlessSyncEnabled flag.
• Pins each of the five envelope fields to its one legal v1 width, which the fixed-width BINARY columns would otherwise zero-pad on a short one.
• Reports created: false on an identical repeat and 409s a different one, since there is no update path.
• Records wrap_created / wrap_creation_failure through a guarded helper, so an audit write cannot 500 a committed wrap or mask the error that preceded it.

Issue that this pull request solves

Closes: FXA-13142

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: packages/fxa-auth-server/lib/routes/passkey-wraps.ts
• Suggested review order: route → swagger notes → unit spec → integration spec
• Risky or complex parts: the auth tier. This takes a verified session, as passkey rename does, rather than the mfa:passkey scope registration and deletion take. Reasoning is in the handler JSDoc — the credential already cleared that bar at registration, and a wrap is inert without its PRF output.

Screenshots (Optional)

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

Other information (Optional)

• Supersedes the verification-proof design in feat(passkey): Add verification proof to the challenge manager #21114 (closed).
• The rate-limit config update will happen in a separate ticket
• Returning an existing wrap from authentication/finish, gated on wraps.createdAt being newer than the account's keysChangedAt, is scoped to the GET ticket.

[Copilot]

Pull request overview

Adds create-only passkey wrap storage for passwordless Sync, protected by verified sessions and feature gating.

Changes:

• Adds the validated, rate-limited, audited POST /passkey/wraps route.
• Registers and documents the endpoint.
• Adds unit and remote integration coverage.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/remote/passkey_wraps.in.spec.ts	Tests end-to-end storage and failures.
lib/routes/passkeys.ts	Exports the credential ID validator.
lib/routes/passkey-wraps.ts	Implements the endpoint.
lib/routes/passkey-wraps.spec.ts	Tests routing and validation.
lib/routes/index.js	Registers the new route.
docs/swagger/passkey-wraps-api.ts	Documents the API contract.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.