72 lines
4.8 KiB
Markdown
72 lines
4.8 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.
|
|
|
|
## Included in 0.1.0
|
|
|
|
- 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.
|
|
- 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, Google Authenticator migration QR payloads, the documented CSV shape and RFC 6030 PSKC files containing plain secrets. Encrypted PSKC is rejected rather than guessed.
|
|
- Explicit URI-list and CSV export with an unencrypted-secret warning.
|
|
- 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.
|
|
- Serializable registration/request option examples, browser capability diagnostics and an ephemeral in-memory live ceremony lab.
|
|
|
|
## 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. Camera and USB permissions are not requested. QR images can be selected locally when the browser implements `BarcodeDetector`; provisioning text can always be pasted.
|
|
|
|
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.1.0.zip` over HTTPS. Recommended response headers:
|
|
|
|
```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=(), 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 structures are decoded, but 0.1.0 does not establish attestation trust or silently download FIDO Metadata Service data. Assertion signatures are verified only with the explicitly supplied/created credential key.
|
|
- Google multi-QR batches must all be supplied; the current UI reviews one payload at a time. Google migration export and encrypted PSKC decryption are not claimed.
|
|
- CSV and URI exports contain raw OTP seeds. There is no encrypted vault format in this app.
|
|
- QR generation supports byte-mode error-correction M through version 10. Larger provisioning records remain available as text exports.
|
|
|
|
## Licence
|
|
|
|
`GPL-3.0-or-later`. See [LICENSE](LICENSE), [SOURCE.md](SOURCE.md), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|