84 lines
7.5 KiB
Markdown
84 lines
7.5 KiB
Markdown
# OTP & Passkey Tools
|
|
|
|
A production-oriented, local-first browser workbench for OTP credentials and WebAuthn/passkey evidence. It is part of the [add·ideas Toolbox](https://git.add-ideas.de/lotobo/toolbox-portal), but its release ZIP also runs as a standalone static application.
|
|
|
|
Authentication material stays in the active tab. The application has no backend, telemetry, automatic network lookup, service worker, cookie, local-storage credential store, or IndexedDB database.
|
|
|
|
## Current source capabilities
|
|
|
|
- RFC 4226 HOTP and RFC 6238 TOTP generation and bounded diagnostic verification using SHA-1, SHA-256 or SHA-512, with exact 64-bit counters and preserved leading zeroes.
|
|
- Strict `otpauth://` parsing/serialization, random secret generation, masked values, interoperability findings, live period display and a project-owned QR encoder.
|
|
- Auditable TOTP time travel using positive/negative period offsets or a frozen local date/time in an explicit IANA timezone, including DST-gap rejection and repeated-time disambiguation.
|
|
- Bounded clock-drift search, past/current/future OTP timelines, downloadable interoperability vectors and custom RFC 6238 T0 diagnostics.
|
|
- RFC 6287 OCRA-1 suite parsing and computation for counter, numeric/alphanumeric/hex challenge, PIN/password hash, session and timestamp inputs. Official RFC interoperability vectors cover SHA-1, SHA-256 and SHA-512 paths.
|
|
- Import of line-delimited provisioning URIs, complete Google Authenticator multi-QR batches, password-encrypted or plaintext Aegis JSON, 2FAS JSON, andOTP plaintext JSON, legacy FreeOTP JSON, the documented CSV shape, and plain or password-encrypted RFC 6030 PSKC.
|
|
- Google Authenticator migration export in bounded multi-part QR batches and an authenticated PSKC password profile using PBKDF2, AES-CBC, an encrypted MAC key and per-secret `ValueMAC` verification.
|
|
- Cross-browser QR image decoding through native `BarcodeDetector` when available and a bundled jsQR fallback everywhere else, including an explicitly triggered, time-limited camera scanner on the dedicated origin.
|
|
- Credential-collection health reports, secret-free inventory snapshots, before/after comparison and prioritized rotation plans for duplicated secrets, changed parameters and removed credentials.
|
|
- Bounded HOTP resynchronization with one code or stronger consecutive-code confirmation; suggested counters are never applied automatically.
|
|
- Explicit URI-list and CSV export with an unencrypted-secret warning, plus a versioned authenticated encrypted backup using PBKDF2-SHA-256 and AES-256-GCM.
|
|
- Bounded CBOR, `clientDataJSON`, authenticator-data and attestation-object inspection, including flags, RP ID hash, counter, AAGUID, credential ID, COSE key and extensions.
|
|
- Layered assertion verification for challenge, origin, cross-origin state, RP ID hash, user presence/verification, signature counter, and ES256, RS256, PS256 or Ed25519 signatures.
|
|
- Layered registration verification for none, packed/self, FIDO U2F, TPM 2.0, Android Key and Apple anonymous attestation, including certificate signatures and format-specific credential/challenge bindings.
|
|
- Explicit offline FIDO Metadata Service v3 JWT snapshot import, signer verification, user-pinned PEM trust roots, signer-chain validation, historical effective-date and firmware-aware status policy evaluation. Imported metadata never silently establishes trust.
|
|
- Serializable registration/request option examples, browser capability diagnostics and an ephemeral in-memory live ceremony lab.
|
|
- A WebAuthn Extensions Lab for `credProps`, `prf`, `largeBlob`, `appid` and `appidExclude`, with `getClientCapabilities()` inspection and normalized request/result output.
|
|
- Versioned registration/authentication trace capture, raw or privacy-redacted export, offline cryptographic replay and structural comparison.
|
|
|
|
## Security boundary
|
|
|
|
The Toolbox app at `/apps/auth/` is deliberately **inspect-only for live WebAuthn ceremonies**. Every app under `toolbox.add-ideas.de` shares one browser origin and therefore one WebAuthn relying-party namespace. Credential creation/authentication is enabled only on localhost or the dedicated origin:
|
|
|
|
```text
|
|
https://auth.toolbox.add-ideas.de/
|
|
```
|
|
|
|
The same immutable release can be served there, top-level, with RP ID `auth.toolbox.add-ideas.de`. The RP ID is never widened to `add-ideas.de`, and arbitrary RP IDs can only be inspected offline.
|
|
|
|
Raw CTAP/token administration is not claimed: browsers expose ordinary WebAuthn but block the FIDO HID usage page from WebHID. USB is never requested. Camera access is granted only on the dedicated Auth Tools host and is requested only after clicking **Scan with camera**; tracks stop on success, cancellation, timeout or teardown. QR images and pasted provisioning text remain available without camera permission.
|
|
|
|
See [SECURITY.md](SECURITY.md) for the threat model and limitations.
|
|
|
|
## Develop and verify
|
|
|
|
Requirements: Node.js 22+, npm 11, and `zip` for deterministic release packaging.
|
|
|
|
```sh
|
|
npm ci
|
|
npm run check
|
|
npm run test:browser
|
|
npm run package:release
|
|
```
|
|
|
|
The Vite base is relative, so both `/` and nested paths work. `npm run toolbox:check` validates the built manifest and its assets.
|
|
|
|
## Static deployment
|
|
|
|
Serve `dist/` or the contents of `release/auth-tools-0.3.1.zip` over HTTPS. Recommended response headers for the dedicated Auth Tools origin:
|
|
|
|
```text
|
|
Content-Security-Policy: default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self'; worker-src 'self' blob:; manifest-src 'self'
|
|
Permissions-Policy: camera=(self), microphone=(), geolocation=(), usb=()
|
|
Referrer-Policy: no-referrer
|
|
X-Content-Type-Options: nosniff
|
|
Cross-Origin-Opener-Policy: same-origin
|
|
Cross-Origin-Resource-Policy: same-origin
|
|
```
|
|
|
|
For Portal integration, pin the immutable Gitea release ZIP and SHA-256 in `toolbox-portal/release/toolbox.lock.json` with target `auth`.
|
|
|
|
## Deliberate limits
|
|
|
|
- This is an engineering and interoperability workbench, not a certified authenticator, relying-party server, password manager, FIDO certification tool or recovery system.
|
|
- Live credentials are forgotten on reload and cannot be exported by WebAuthn design.
|
|
- Attestation cryptography and metadata status are evidence, not automatic device trust. No trust root is bundled, metadata is never downloaded silently, and the local signer-chain verifier is a pinned-root signature path check rather than a complete RFC 5280 PKIX/revocation implementation.
|
|
- All parts of a Google multi-QR batch must be supplied. Google export refuses settings its format cannot preserve. Aegis biometric/raw-key slots and FreeOTP 2.x encrypted XML are not claimed.
|
|
- Encrypted PSKC supports the documented password-derived PBKDF2 + AES-CBC + HMAC `ValueMAC` profile. A namespaced Auth Tools extension preserves non-SHA-1 OTP hash selection without changing the RFC container structure. Asymmetric, pre-shared-key and unverified encrypted-value profiles are rejected.
|
|
- CSV and URI exports contain raw OTP seeds. The encrypted export is a portable backup file, not a persistent browser vault or recovery service.
|
|
- QR generation supports byte-mode error-correction M through version 10. Larger provisioning records remain available as text exports.
|
|
- Redacted WebAuthn traces remove labels and top-level identifiers but retain signed ceremony blobs needed for replay; those blobs can contain stable correlatable identifiers.
|
|
|
|
## Licence
|
|
|
|
`GPL-3.0-or-later`. See [LICENSE](LICENSE), [SOURCE.md](SOURCE.md), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|