| namespace | aiwg |
| name | auth-factor-design |
| platforms | ["all"] |
| description | Decision-aid skill for authentication factor architecture. Forces explicit have/know/are mapping, coercion-resistance analysis, FIDO2 PIN/UV policy, and identifies anti-patterns like Python deps in PRF hot paths |
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
| Class | Examples | What "knowing it" means |
|---|
| Have | Hardware token, USB drive, smart card, phone with attestation | Possession demonstrates auth |
| Know | Password, PIN, passphrase, recovery code, pattern, security questions | Recall demonstrates auth |
| Are | Fingerprint, face, voice, gait, behavioral biometrics | Body demonstrates auth |
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:
| Factor | Class | Specific instance | Required for which operations? | Lost-recovery procedure |
|---|
| YubiKey 5 OTP slot | have | hardware HMAC-SHA1 PRF | unlock, secret derivation | revoke at HQ, reissue |
| YubiKey Bio (FIDO2 PRF) | are+have | fingerprint + hmac-secret w/ uv=true | unlock, signing | revoke + reissue (≤4 weeks per fingerprint enrollment) |
| FIDO2 PIN | know | PIN on Bio key | required when uv=true | reset via reset-protocol; bricks key after N failures |
| Recovery passphrase | know | 6-word BIP39 phrase | emergency rotation only | offline backup at HQ |
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.
| Factor | Coercible? | How | Mitigation |
|---|
| Password / PIN | Yes — operator under duress reveals it | Mitigation: duress code that triggers fail-closed silent lockout | |
| Hardware token | Yes — physical seizure | Mitigation: time-lock, witness requirement, second-factor at HQ | |
| Biometric | Always coerced. Operator's body is present; "extracting" the biometric is trivial under duress | Mitigation: pair with a "know" factor (FIDO2 PIN) so coerced biometric alone fails | |
| Geolocation | Coercible (move operator) | Mitigation: not a real factor; use as risk signal only | |
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
| Use case | Suggested tool | Vetted alternatives |
|---|
| Production C/C++ | libfido2 (Yubico's reference C lib) | python-fido2 only behind a sandbox; PyHanko/cose for high-level signing |
| FIDO2 CLI | fido2-token, fido2-assert (libfido2 binaries) | OpenSC for smart-card-style use |
| Browser-side WebAuthn | Web Crypto API + navigator.credentials.create/get | Server libs: webauthn4j (JVM), simplewebauthn (Node), python-fido2 (server) |
| Testing | Yubico's fido2-token -L, virtual authenticators (Chrome devtools, soft-fido2) | Hardware test rigs only for pre-production validation |
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:
- Use
libfido2 C binaries (fido2-token, fido2-assert) directly — they support hmac-secret. Drop Python from the hot path entirely.
- 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.
- 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
| Factor | Failure response |
|---|
| FIDO2 PIN | Hard lockout after N failures (default ~8); brick key on M (default 3 lockout cycles); requires reset protocol with PIN+attestation |
| Biometric on hardware token | Fall back to PIN (if PIN set); on N failures of bio, force PIN; never "skip bio" |
| Application password | Rate-limit + account lock with side-channel notification; CAPTCHA after 3 failures (anti-bot, not anti-human) |
| Recovery code (single-use) | Mark used immediately; rotate active set; alert on use |
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:
| Countermeasure | How |
|---|
| Duress PIN | Separate PIN that triggers visible-success but secret wipe. Hardware support varies; some FIDO2 firmware supports it, most don't. Document if your hardware does. |
| Time-lock | Operations require N-minute delay; operator can secretly trigger a longer delay during which silent alarm fires |
| Witness requirement | High-value operations require a second operator present (cryptographically verified — e.g., second YubiKey assertion) |
| Geographic / device fence | Operations only succeed from authorized locations or hardware; revocable centrally |
| Silent canary / heartbeat | Operator periodically demonstrates non-coercion; missed heartbeat triggers alert (review M7: heartbeat is killable by root, mitigate via signed live image) |
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
