# 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).