fix(passkey): 断言时按凭据校验 UV，并把存储的 BE/BS 标志交给校验器，云同步 passkey 可以登录 (#9)

        is consumed atomically and the assertion is verified against it; on success a host-only felis_session cookie is minted. Both players

        and staff may log in this way — a passkey is a two-factor authenticator

        (possession + user verification), strong enough to stand alone without the

        in-game approval op-login requires. Every failure mode (unknown address, no

        live challenge for the signed value, expired challenge, bad assertion) collapses into one uniform

        passkey_login_invalid, so the door reveals nothing.

        in-game approval op-login requires. User verification is checked per

        credential: the passkey must have verified the user when it was bound, and this

        assertion must verify the user now. Every failure mode (unknown address, no

        live challenge for the signed value, expired challenge, bad assertion, a

        credential or assertion without user verification, a cloned authenticator)

        collapses into one uniform passkey_login_invalid, so the door reveals nothing.

      x-felis-face: [external]

      x-felis-tier: public

      security: []

        '400':

          description: >-

            Invalid email or missing assertion (bad_request); or the login could not be

            completed — unknown address, no live or expired challenge, or a failed

            assertion, all uniform (passkey_login_invalid).

            completed — unknown address, no live or expired challenge, a failed

            assertion, no user verification, or a cloned authenticator, all uniform

            (passkey_login_invalid).

          content:

            application/json:

              schema: { $ref: '#/components/schemas/Error' }

        verified against it; the account is resolved from the authenticator-revealed

        userHandle (the account's stable id), never from anything the client supplied,

        and the session is minted for the account the assertion actually resolved AND

        verified to. Both players and staff may log in this way. Every failure mode — a

        missing/expired/consumed login_id, a bad assertion, AND a userHandle that

        resolves to no account — collapses into one uniform passkey_login_invalid, so

        the door reveals nothing (not even whether the handle was well-formed).

        verified to. Both players and staff may log in this way, with the same

        per-credential user-verification check as the username-first door. Every failure

        mode — a missing/expired/consumed login_id, a bad assertion, no user

        verification, a cloned authenticator, AND a userHandle that resolves to no

        account — collapses into one uniform passkey_login_invalid, so the door reveals

        nothing (not even whether the handle was well-formed).

      x-felis-face: [external]

      x-felis-tier: public

      security: []

        '400':

          description: >-

            Missing login_id or assertion (bad_request); or the login could not be

            completed — no live/expired/consumed challenge, a failed assertion, or a

            userHandle that resolves to no account, all uniform (passkey_login_invalid).

            completed — no live/expired/consumed challenge, a failed assertion, no user

            verification, a cloned authenticator, or a userHandle that resolves to no

            account, all uniform (passkey_login_invalid).

          content:

            application/json:

              schema: { $ref: '#/components/schemas/Error' }

      summary: Finish the passkey assertion and mark this session reauthed for 5 minutes.

      description: >

        Verifies the assertion against the reauth challenge with the login door's

        clone check (a cloned authenticator is 400 passkey_login_invalid).

        user-verification and clone checks (a credential or assertion without user

        verification, or a cloned authenticator, is 400 passkey_login_invalid).

      x-felis-face: [external]

      x-felis-tier: app

      x-felis-setup-allowed: true

        '200':

          $ref: '#/components/responses/Reauthed'

        '400':

          description: Assertion invalid, challenge stale, or a cloned authenticator (passkey_login_invalid); no browser session (no_session).

          description: Assertion invalid, challenge stale, no user verification, or a cloned authenticator (passkey_login_invalid); no browser session (no_session).

          content:

            application/json:

              schema: { $ref: '#/components/schemas/Error' }

      summary: Finish the passkey assertion and confirm the migration (spec §B3 step-up).

      description: >

        Verifies the WebAuthn assertion against the fresh migrate-purpose challenge and,

        like the login door, applies the authenticator sign-count clone check: a cloned

        authenticator is rejected fail-closed (400 passkey_login_invalid) and audited. On

        success the migration advances to confirmed with confirm_factor passkey.

        like the login door, applies the per-credential user-verification check and the

        authenticator sign-count clone check: either refusal fails closed (400

        passkey_login_invalid) and is audited. On success the migration advances to

        confirmed with confirm_factor passkey.

      x-felis-face: [external]

      x-felis-tier: app

      security: [{ sessionCookie: [] }]

                properties:

                  confirmed: { type: boolean, const: true }

        '400':

          description: Assertion invalid, challenge stale, or a cloned authenticator was detected (passkey_login_invalid).

          description: Assertion invalid, challenge stale, no user verification, or a cloned authenticator was detected (passkey_login_invalid).

          content:

            application/json:

              schema: { $ref: '#/components/schemas/Error' }

	a.auditEntry(r, e)

}

// passkeyCloneRejected records an assertion refused for a regressed signature

// counter. It keeps its own action so a cloned authenticator stands out from

// ordinary failures, and counts as a failure of its door. u nil: a signed-in

// step-up, attributed to the caller.

func (a *API) passkeyCloneRejected(r *http.Request, door string, u *StaffUser, credentialID string) {

	metrics.AuthFailuresTotal.WithLabelValues(door, "clone_rejected").Inc()

// passkeyAssertionRejected records an assertion applyAssertion refused on policy: a

// regressed signature counter (auth.passkey_clone_rejected) or a user the credential

// or the assertion did not verify (auth.passkey_uv_rejected). Each keeps its own action

// so it stands out from ordinary failures, and counts as a failure of its door. u nil:

// a signed-in step-up, attributed to the caller. It reports false, recording nothing,

// for any other error, which the caller answers as a fault.

func (a *API) passkeyAssertionRejected(r *http.Request, door string, u *StaffUser, credentialID string, err error) bool {

	var reason string

	switch {

	case errors.Is(err, errPasskeyClonedAuthenticator):

		reason = "clone_rejected"

	case errors.Is(err, errPasskeyUserNotVerified):

		reason = "uv_rejected"

	default:

		return false

	}

	metrics.AuthFailuresTotal.WithLabelValues(door, reason).Inc()

	action := "auth.passkey_" + reason

	if u == nil {

		a.audit(r, "auth.passkey_clone_rejected", credentialID)

		return

		a.audit(r, action, credentialID)

	} else {

		a.auditAccount(r, u, action, credentialID)

	}

	a.auditAccount(r, u, "auth.passkey_clone_rejected", credentialID)

	return true

}

// isOTPRefusal reports whether err is a refused code (wrong, spent, or the

	repo := newFakeRepo()

	repo.seedUser(UserView{ID: "u1", Username: "old", Email: "[email protected]", Role: "user"})

	repo.links[uuid] = "u1"

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", CreatedAt: frozenNow}

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", UserVerified: true, CreatedAt: frozenNow}

	mk, mailer, _ := migrateEnv(repo)

	ih := mk(src).InternalHandler()

	repo := newFakeRepo()

	repo.seedUser(UserView{ID: "u1", Username: "old", Email: "[email protected]", Role: "user"})

	repo.links[uuid] = "u1"

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", CreatedAt: frozenNow}

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", UserVerified: true, CreatedAt: frozenNow}

	mk, _, v := migrateEnv(repo)

	ih := mk(src).InternalHandler()

	repo := newFakeRepo()

	repo.seedUser(UserView{ID: "u1", Username: "old", Email: "[email protected]", Role: "user"})

	repo.links[uuid] = "u1"

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", CreatedAt: frozenNow}

	repo.passkeyCreds["row1"] = PasskeyCredential{ID: "row1", UserID: "u1", CredentialID: "cred-1", PublicKey: "k", UserVerified: true, CreatedAt: frozenNow}

	mk, _, v := migrateEnv(repo)

	v.assertion = VerifiedAssertion{CredentialID: "cred-1", UserVerified: true, CloneWarning: true}

	"fmt"

	"io"

	"net/http"

	"slices"

	"strings"

	"time"

)

// and whether that counter regressed (a possible clone). Like VerifiedCredential it carries

// no secret. SignCount is a raw ceremony fact, NOT a policy verdict; CloneWarning IS the

// verifier's regression verdict, but the refuse-vs-allow decision is the handler's. Clone

// policy therefore lives in one place with the stored counter (applyAssertionCounter, which

// both login doors call). SignCount is legitimately 0 for authenticators that keep no counter.

// policy therefore lives in one place with the stored counter (applyAssertion, which

// every assertion door calls). SignCount is legitimately 0 for authenticators that keep no counter.

//

// applyAssertionCounter is that single consumer: it refuses a CloneWarning fail-closed and,

// on success, advances the stored counter and stamps last_used_at. This is the stable seam

// applyAssertion is that single consumer: it refuses an unverified user or a CloneWarning

// fail-closed and, on success, advances the stored counter and stamps last_used_at. This is the stable seam

// output the production adapter (internal/passkey) produces and its Oracle test asserts on,

// so handler and adapter agree on shape without either reshaping the other.

type VerifiedAssertion struct {

	// assertion and structurally never raise it. The login handlers refuse it fail-closed.

	CloneWarning bool

	// UserVerified records that a PIN/biometric (not mere presence) was performed

	// during the assertion ceremony. The verifier enforces UV=required at BeginLogin,

	// so this is always true for a successful assertion; persisting it makes the

	// guarantee auditable and survives a future policy that permits UV=preferred.

	// during this assertion. The verifier asks for UV=required today, so a successful

	// assertion carries it; applyAssertion checks it anyway, together with the

	// credential's stored bind-time flag, so a later UV=preferred policy or a door that

	// asks for less cannot let a presence-only assertion through.

	UserVerified bool

}

var errPasskeyUnavailable = newError(http.StatusServiceUnavailable, "passkey_unavailable",

	"passkey subsystem is not configured")

// errPasskeyClonedAuthenticator is the internal signal from applyAssertionCounter that a

// errPasskeyClonedAuthenticator is the internal signal from applyAssertion that a

// verified assertion carried a clone warning (its signature counter did not advance past the

// stored value). It never reaches the client verbatim: the login doors map it to the generic

// passkey_login_invalid envelope — no clone oracle to a prober — and audit it distinctly.

var errPasskeyClonedAuthenticator = errors.New("passkey assertion rejected: clone warning")

// applyAssertionCounter is the single consumer of a verified assertion's signature-counter

// facts, shared by the username-first (handlePasskeyLoginFinish) and discoverable

// (handlePasskeyLoginDiscoverableFinish) login doors so clone policy lives in one place with

// the stored counter. A CloneWarning fails closed with errPasskeyClonedAuthenticator;

// otherwise it advances the stored counter to the asserted value and stamps last_used_at.

// Counter-less/synced authenticators report 0 and never warn, so they pass through and simply

// re-stamp 0 — the check gates only counter-keeping authenticators, where a rollback is the

// meaningful clone signal. It runs BEFORE the session is minted, so a clone or a persist

// failure denies the login rather than leaving an advanced counter with no session.

func (a *API) applyAssertionCounter(ctx context.Context, va VerifiedAssertion) error {

// errPasskeyUserNotVerified is the internal signal from applyAssertion that the assertion,

// or the credential it came from, did not verify the user. Like the clone signal it is

// answered with the opaque envelope and audited distinctly.

var errPasskeyUserNotVerified = errors.New("passkey assertion rejected: user not verified")

// applyAssertion is the single consumer of a verified assertion, shared by the

// username-first and discoverable login doors and the step-up confirmation, so assertion

// policy lives in one place with the stored credential. creds are the account's bound

// passkeys the verifier checked the assertion against.

//

// Every one of those doors grants a session or confirms one, so each needs user

// verification, per credential (migration 0009): the credential must have verified the

// user when it was bound, and this assertion must have verified the user now. Either

// missing fails closed with errPasskeyUserNotVerified. A credential bound presence-only

// (a pre-0009 row, or a future UV=preferred enrollment) therefore cannot sign in; its

// owner still has the email-code door.

//

// A CloneWarning fails closed with errPasskeyClonedAuthenticator; otherwise it advances

// the stored counter to the asserted value and stamps last_used_at. Counter-less/synced

// authenticators report 0 and never warn, so they pass through and simply re-stamp 0 — the

// check gates only counter-keeping authenticators, where a rollback is the meaningful clone

// signal. It runs BEFORE the session is minted, so a refusal or a persist failure denies

// the login rather than leaving an advanced counter with no session.

func (a *API) applyAssertion(ctx context.Context, va VerifiedAssertion, creds []PasskeyCredential) error {

	bound := slices.IndexFunc(creds, func(c PasskeyCredential) bool { return c.CredentialID == va.CredentialID })

	if !va.UserVerified || bound < 0 || !creds[bound].UserVerified {

		return errPasskeyUserNotVerified

	}

	if va.CloneWarning {

		return errPasskeyClonedAuthenticator

	}

			"passkey login could not be completed; begin again"))

		return

	}

	// Clone policy + counter advance, in one place shared with the discoverable door. A

	// regressed counter is refused with the same opaque envelope (no clone oracle) but audited

	// distinctly; a successful assertion advances the stored counter and stamps last_used_at.

	if err := a.applyAssertionCounter(r.Context(), va); err != nil {

		if errors.Is(err, errPasskeyClonedAuthenticator) {

			a.passkeyCloneRejected(r, "passkey", u, va.CredentialID)

	// UV + clone policy + counter advance, in one place shared with the discoverable door. A

	// refusal is answered with the same opaque envelope (no oracle) but audited distinctly; a

	// successful assertion advances the stored counter and stamps last_used_at.

	if err := a.applyAssertion(r.Context(), va, creds); err != nil {

		if a.passkeyAssertionRejected(r, "passkey", u, va.CredentialID, err) {

			writeError(w, r, newError(http.StatusBadRequest, "passkey_login_invalid",

				"passkey login could not be completed; begin again"))

			return

	// the session below is minted for the account the assertion actually resolved AND verified to

	// — not anything the client supplied (the body carries only a challenge handle).

	var resolved *StaffUser

	var resolvedCreds []PasskeyCredential

	resolve := func(userHandle []byte) (PasskeyUser, error) {

		u, err := a.Repo.UserByID(r.Context(), string(userHandle))

		if err != nil {

		if err != nil {

			return PasskeyUser{}, err

		}

		resolved = u

		resolved, resolvedCreds = u, creds

		// Name/DisplayName are cosmetic at assertion time (nothing is shown to the user); use the

		// stable username so a nil email never matters.

		return PasskeyUser{ID: u.ID, Name: u.Username, DisplayName: u.Username, Credentials: creds}, nil

			"passkey login could not be completed; begin again"))

		return

	}

	// Same clone policy + counter advance as the username-first door (applyAssertionCounter): a

	// regressed counter is refused with the identical opaque envelope but audited under the

	// resolved account; a successful assertion advances the stored counter and stamps last_used_at.

	if err := a.applyAssertionCounter(r.Context(), va); err != nil {

		if errors.Is(err, errPasskeyClonedAuthenticator) {

			a.passkeyCloneRejected(r, "passkey_discoverable", resolved, va.CredentialID)

	// Same UV + clone policy + counter advance as the username-first door (applyAssertion): a

	// refusal gets the identical opaque envelope but is audited under the resolved account; a

	// successful assertion advances the stored counter and stamps last_used_at.

	if err := a.applyAssertion(r.Context(), va, resolvedCreds); err != nil {

		if a.passkeyAssertionRejected(r, "passkey_discoverable", resolved, va.CredentialID, err) {

			writeError(w, r, newError(http.StatusBadRequest, "passkey_login_invalid",

				"passkey login could not be completed; begin again"))

			return