SSZcreate/Pentab_server / .agents/skills/cybersecurity/skills/implementing-hardware-security-key-authentication
implementing-hardware-security-key-authentication
VerifiedBuilds a FIDO2/WebAuthn relying party server with the python-fido2 library, covering registration and authentication ceremonies, YubiKey enrollment, resident key (discoverable credential/passkey) workflows, and user verification policies. Use when implementing phishing-resistant MFA with hardware security keys, building a WebAuthn relying party, enrolling YubiKeys for a workforce, or migrating password-based authentication to passkeys.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 11.0 KB |
| SKILL.md | skill md | 17.5 KB |
| references/api-reference.md | markdown | 6.3 KB |
| scripts/agent.py | script | 37.9 KB |
references/api-reference.md
View on GitHub# API Reference: FIDO2/WebAuthn Hardware Security Key Authentication Server
## Overview
Implements a complete WebAuthn relying party server with registration/authentication ceremonies, YubiKey enrollment, credential management, recovery codes, and audit logging. Built on python-fido2 and Flask, supporting both roaming authenticators (USB/NFC security keys) and platform authenticators (Windows Hello, Touch ID).
## Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| fido2 | >=2.0.0 | Yubico's python-fido2 library for WebAuthn relying party operations |
| flask | >=2.3 | HTTP server framework for API endpoints and session management |
| cryptography | >=41.0 | Cryptographic primitives used by python-fido2 |
Install with: `pip install fido2 flask cryptography`
## CLI Usage
```bash
# Development server on localhost (no TLS needed)
python agent.py --rp-id localhost --rp-name "My App" --port 5000
# Production with strict security settings
python agent.py --rp-id auth.example.com --rp-name "Example Corp" \
--user-verification required --attestation direct --db prod_keys.db
# Verbose logging for debugging
python agent.py --rp-id localhost --rp-name "Test" -v
```
## Arguments
| Argument | Required | Description |
|----------|----------|-------------|
| `--rp-id` | No | Relying Party ID -- must match the application domain (default: localhost) |
| `--rp-name` | No | Relying Party display name shown in authenticator prompts (default: FIDO2 Demo) |
| `--host` | No | Server bind address (default: localhost) |
| `--port` | No | Server port (default: 5000) |
| `--db` | No | SQLite database path for credentials and users (default: webauthn.db) |
| `--attestation` | No | Attestation preference: none, indirect, direct, enterprise (default: none) |
| `--user-verification` | No | UV requirement: required, preferred, discouraged (default: preferred) |
| `-v, --verbose` | No | Enable debug logging |
## API Endpoints
### Registration
#### `POST /api/register/begin`
Start the WebAuthn registration ceremony.
**Request body:**
```json
{
"username": "alice",
"display_name": "Alice Smith",
"resident_key": true
}
```
**Response:** PublicKeyCredentialCreationOptions (JSON-serialized)
#### `POST /api/register/complete`
Complete registration with the authenticator's response.
**Request body:** Serialized PublicKeyCredential from `navigator.credentials.create()`
**Response:**
```json
{
"status": "OK",
"recovery_codes": ["A1B2C3D4", "E5F6G7H8", ...],
"message": "Save these recovery codes securely."
}
```
### Authentication
#### `POST /api/authenticate/begin`
Start the WebAuthn authentication ceremony.
**Request body:**
```json
{
"username": "alice"
}
```
Omit `username` for discoverable credential (passwordless) flow.
**Response:** PublicKeyCredentialRequestOptions (JSON-serialized)
#### `POST /api/authenticate/complete`
Complete authentication with the authenticator's assertion.
**Request body:** Serialized PublicKeyCredential from `navigator.credentials.get()`
**Response:**
```json
{
"status": "OK",
"username": "alice"
}
```
### Key Management
#### `GET /api/keys`
List all registered security keys for the authenticated user.
#### `POST /api/keys/<id>/revoke`
Revoke a security key. Requires at least one remaining active credential.
#### `PUT /api/keys/<id>/label`
Update a key's display label.
### Recovery
#### `POST /api/recover`
Authenticate using a recovery code when all keys are unavailable.
**Request body:**
```json
{
"username": "alice",
"recovery_code": "A1B2C3D4"
}
```
### Admin
#### `GET /api/admin/stats`
Deployment statistics: total users, credentials, backup key adoption, authentication metrics.
#### `GET /api/admin/audit-log?limit=100`
Authentication event audit trail with timestamps, usernames, event types, and IP addresses.
## Key Functions
### User Management
#### `create_user(conn, username, display_name)`
Creates a user with a cryptographically random 32-byte user handle.
#### `get_user_by_username(conn, username)` / `get_user_by_handle(conn, user_handle)`
User lookups by username (standard flow) or user handle (discoverable credential flow).
### Credential Management
#### `store_credential(conn, user_id, credential_id, public_key, sign_count, ...)`
Persists a WebAuthn credential with AAGUID, label, transport hints, and discoverable flag.
#### `get_user_credentials(conn, user_id)`
Retrieves all active (non-revoked) credentials for a user.
#### `revoke_credential(conn, credential_db_id, user_id)`
Soft-revokes a credential. Prevents revocation of the last remaining credential.
#### `update_sign_count(conn, credential_id, new_count)`
Updates sign count and last-used timestamp after successful authentication. Sign count regression is logged as a security event (possible cloned key).
### Recovery
#### `generate_recovery_codes(conn, user_id, count=8)`
Generates 8 one-time recovery codes (stored as SHA-256 hashes). Previous codes are invalidated.
#### `verify_recovery_code(conn, user_id, code)`
Verifies and consumes a recovery code (single-use).
### Helpers
#### `build_credential_descriptors(creds)`
Converts stored credentials to `PublicKeyCredentialDescriptor` list for WebAuthn ceremonies.
#### `reconstruct_credential_data(creds)`
Rebuilds `AttestedCredentialData` objects from database records for python-fido2 verification.
## Database Schema
| Table | Purpose |
|-------|---------|
| `users` | User accounts with random user handles, usernames, and passkey-only flag |
| `credentials` | WebAuthn credentials with public keys, sign counts, AAGUIDs, and revocation status |
| `auth_events` | Audit log of all registration, authentication, revocation, and recovery events |
| `recovery_codes` | Hashed one-time recovery codes with usage tracking |
## Security Features
| Feature | Implementation |
|---------|---------------|
| Phishing resistance | Origin binding via WebAuthn RP ID verification |
| Clone detection | Sign count validation with regression warnings |
| Recovery codes | SHA-256 hashed, single-use, auto-invalidated on regeneration |
| Session security | Secure, HttpOnly, SameSite=Strict cookies |
| Key revocation | Soft delete with minimum-one-key enforcement |
| Audit trail | All auth events logged with IP, user agent, and timestamp |
| Attestation verification | Configurable attestation preference for enterprise key verification |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |