Auth Factor Design

auth-factor-design

Decision aid for authentication factor architecture. Use when designing or reviewing any system whose unlock, login, or operation gating depends on more than one factor — and especially when biometrics, hardware tokens, or "something you know" enter the design.

The skill forces three explicit exercises: a factor inventory, a coercion-resistance matrix, and a lockout/recovery policy. Without all three, the design isn't complete.

Triggers

• "factor design" / "MFA" / "multi-factor"
• "FIDO2 PIN" / "WebAuthn PIN"
• "biometric policy" / "uv=true"
• "coercion resistance" / "rubber-hose"
• "PRF hot path" / "hmac-secret"
• "what you know vs what you have"
• "duress code" / "duress factor"

When NOT to use this skill

• Pure password-based authentication for low-stakes systems (use OWASP ASVS L1 guidance)
• OAuth/OIDC client design (different layer; use sdlc-complete security-architect for protocol selection)
• Network-layer mutual TLS (cert authentication, not user authentication)

Section 1: The three factor classes

A "true" multi-factor system requires factors from at least two distinct classes. Three of the same class is not multi-factor — two passwords is one factor twice.

Common misclassifications

• SMS code: not a "have" factor on its own — SIM-swappable, network-interceptable. Treat as a weak channel-bound code, not a possession proof.
• TOTP from phone: weak "have" if phone is uncontrolled (any app can read TOTP seed if leaked). Stronger if seed is in a hardware-backed enclave (Apple Secure Enclave, Android Strongbox).
• Email confirmation link: not a factor — it's a recovery channel that demonstrates control of the email account, which itself depends on factors.
• "Security question" answers: nominally "know" but socially harvestable; treat as a fallback recovery hint, not a factor.

Section 2: Factor inventory exercise (mandatory)

Before declaring an auth design complete, fill out:

Required: at least one row from each of two classes for any operation that protects high-value assets. Document operations that bypass this rule with explicit risk acceptance.

Section 3: Coercion-resistance matrix (mandatory)

For each factor, document whether it can be coerced and what mitigates the coercion.

Anti-pattern: only have + are (review finding H2)

A system with hardware token + biometric and no "know" factor is not coercion-resistant. The attacker compels the operator to come to the device with the token in hand and the finger ready. There is nothing the operator can decline to provide.

A FIDO2 PIN as the third factor — REQUIRED for PRF assertion via uv=true — adds:

• A factor only the operator's mind contains (truly something they "know")
• A lockout-after-N-tries property (FIDO2 PIN bricks the key after retries; default ~8)
• Optional duress codes (some authenticators support a separate "wipe key on this PIN" entry)

Cost: zero hardware. Recommended for any production deployment of FIDO2/WebAuthn PRF.

Section 4: FIDO2 / WebAuthn PRF design

Suggested default

For hardware-backed authenticated key derivation:

• FIDO2 hmac-secret extension (PRF in WebAuthn-2 terminology) on a token with both PIN and biometric
• uv: required in the assertion — forces user verification
• PIN required — forces "know" alongside "have+are"
• Per-RP credential isolation — different RP IDs derive different PRF outputs

Tooling

Anti-pattern: Python in the PRF hot path (review finding H3)

python-fido2 in the biometric PRF assertion path introduces a wide attack surface for the most sensitive operation in the system:

• python-fido2, cryptography, cffi, pyusb — any of these getting a typosquat or supply-chain compromise = PRF interception
• The C path through libfido2 is ~50KB statically linkable, audited, fewer transitive deps

Remediation options:

1. Use libfido2 C binaries (fido2-token, fido2-assert) directly — they support hmac-secret. Drop Python from the hot path entirely.
2. If Python is mandatory: vendor and pin python-fido2 + transitive deps with hash-locked wheels in your bootstrap; verify per-wheel SHA-256 against an offline manifest; reproducibly build the bootstrap.
3. Either way: run the PRF call inside a sandboxed namespace (bubblewrap, no network, no /proc, read-only mounts).

RP ID guidance

rp.id in WebAuthn / FIDO2 is canonically a domain name. Some authenticators behave oddly with non-domain RP IDs (e.g., "agent-box"). For non-web contexts:

• Prefer a domain you control even if not actually web-served (agent-box.example.com)
• Test with multiple authenticator firmware versions before locking RP ID
• Document if you proceed with non-domain (review L1 finding)

Section 5: Lockout / retry policy

Required exercise: document the exact behavior

For each authenticator in your system, document:

Factor: FIDO2 PIN on Bio key
Wrong-PIN behavior:
  After 1: warning + 1-second delay
  After 3: 5-second delay
  After 5: 30-second delay
  After 8: full lockout, requires reset
  Lockout cycles before key brick: 3 (default)
Reset procedure:
  fido2-token -R (factory reset, wipes credentials)
  Re-enroll fingerprint, re-set PIN
  Re-register with all RPs (operationally expensive — design for this)

If your design doesn't have this written down, it's incomplete.

Section 6: Duress / coercion countermeasures

When the threat model includes coercion (high-value targets, journalists, security operators in hostile environments), build in:

Important: every coercion countermeasure has operational cost. A duress PIN that the operator forgets locks them out as effectively as the attacker does. Test the failure modes.

Section 7: Worked examples

Review finding H2 — "what you have + what you are" only

Original design: 2-of-2 with one biometric (YubiKey 5 + YubiKey Bio with fingerprint).

What this skill flags:

• Section 3 anti-pattern: no "know" factor → coercion gives the attacker everything
• Section 6: no duress countermeasure documented

Remediation:

• Set FIDO2 PIN on Bio key; require uv=true in PRF assertion
• Document PIN lockout policy
• Optionally add duress procedure (geographic alert, second-operator witness)

Review finding H3 — python-fido2 in PRF hot path

Original design: Python program calls python-fido2 to do the biometric PRF assertion.

What this skill flags:

• Section 4 anti-pattern: Python deps in hot path → wide attack surface

Remediation:

• Replace with libfido2 C tools (fido2-token, fido2-assert -h hmac-secret)
• If Python is mandatory: vendor + hash-lock all transitive deps; sandbox the call

Review finding M4 — biometric retry behavior unclear

Original design: uv: REQUIRED documented, but lockout/fallback behavior not specified.

What this skill flags:

• Section 5 mandatory exercise: exact lockout behavior must be documented

Remediation:

• Run fido2-token -L against a test key, document observed behavior under N failures
• Verify Bio key was not factory-defaulted to "no PIN" (if so, set one)
• Add behavior to factor-design-rationale.md per-factor

Section 8: Output format

When this skill is invoked as part of a review, produce a factor-design-rationale.md (template in templates/factor-design-rationale.md) with:

• Factor inventory table (Section 2)
• Coercion-resistance matrix (Section 3)
• Lockout/retry policy per factor (Section 5)
• Hardware/firmware constraints (FIDO2 version, PRF support, UV behavior)

If issues are found, produce findings in the standard format:

### Finding: <SHORT-NAME>

**Severity**: BLOCK | HIGH | MEDIUM | LOW
**Section**: auth-factor-design <section reference>
**Issue**: <one paragraph>
**Remediation**: <concrete fix>
**References**: <NIST SP 800-63B, FIDO2 spec, etc.>

Related

• Companion skill: physical-threat-modeling (Tier 2) — coercion is in its threat library
• Companion skill: degraded-mode-design (Tier 2) — what happens when factors fail
• Companion skill: chain-of-trust-design — the factors only matter if the verifier is trusted
• Template: factor-design-rationale.md

Standards referenced

• NIST SP 800-63B — Digital Identity Guidelines: Authentication
• FIDO2 / CTAP2 specification
• WebAuthn Level 2 / Level 3 specifications
• OWASP ASVS 4.0 §2 (Authentication)
• libfido2 documentation