111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# Website (Test)
|
|
|
|
The test website is a minimal HTML page that exercises the full LOCQR session
|
|
flow end-to-end. It is a permanent development artifact — not a prototype of
|
|
a real product — and will not be replaced by a production website. Its only
|
|
purpose is to provide a realistic SDK integration target for testing the
|
|
extension, the web companion stub, and the Node server stub together.
|
|
|
|
---
|
|
|
|
## What it does
|
|
|
|
- Initialises the SDK with the test domain's registration certificate
|
|
- Presents a simple login form
|
|
- Calls `locqr.requestCredential()` on form focus or button press
|
|
- Displays the delivered credential to confirm end-to-end delivery worked
|
|
- Exercises error paths — unregistered domain, invalid cert, session failure —
|
|
to confirm the extension's error states and UI behave correctly
|
|
|
|
It is intentionally bare. No styling beyond readability; no application logic
|
|
beyond triggering and displaying LOCQR flows.
|
|
|
|
A visible event log panel is a core part of the test page, not an optional
|
|
addition. Every SDK event, Promise resolution, rejection, and error — including
|
|
the full payload — is appended to the log in real time with a timestamp. The
|
|
log is the primary debugging tool for the development environment; it should
|
|
capture everything the SDK surfaces, including security-class errors and their
|
|
reasons.
|
|
|
|
---
|
|
|
|
## Development environment
|
|
|
|
The test site is one part of a four-piece local development environment:
|
|
|
|
| Component | Implementation |
|
|
|---|---|
|
|
| Website | This test site |
|
|
| Extension | The real extension, loaded unpacked |
|
|
| Backend | Node.js server stub |
|
|
| Companion | Web companion stub (mobile browser or desktop) |
|
|
|
|
Running all four together constitutes a complete local LOCQR environment.
|
|
Start order, environment variables, shared configuration, and the one-time
|
|
setup script are documented in `../dev.md`.
|
|
|
|
### HTTPS requirement
|
|
|
|
`externally_connectable` requires a secure context. Service workers require
|
|
HTTPS. The test site must be served over HTTPS even in local development.
|
|
|
|
Options:
|
|
- **`mkcert`** — creates a locally-trusted CA and issues certs for custom local
|
|
domains. Recommended: clean, no browser warnings, no external dependency.
|
|
- **Self-signed cert with manual trust** — works but requires trusting the cert
|
|
in each browser profile used for testing.
|
|
- **Tunnel (ngrok, Cloudflare Tunnel)** — provides a real HTTPS domain; useful
|
|
for testing on physical mobile devices for the companion stub. Adds an
|
|
external dependency.
|
|
|
|
### Local domain
|
|
|
|
The registration certificate is domain-scoped. `localhost` is unsuitable —
|
|
it cannot hold a meaningful domain cert and is treated specially by browsers.
|
|
A custom local domain (e.g. `test.locqr.dev`) with a hosts file entry and a
|
|
`mkcert`-issued cert is the recommended approach.
|
|
|
|
The same domain must appear in:
|
|
- The registration certificate issued by the Node server stub at startup
|
|
- The `externally_connectable` origins list in the extension manifest
|
|
- The SDK `locqr.init({ cert })` call in the test page
|
|
|
|
### Extension ID in development
|
|
|
|
The unpacked extension has a different ID from the Store-published version.
|
|
The test site initialises the SDK with the dev extension ID:
|
|
|
|
```js
|
|
locqr.init({
|
|
cert: TEST_CERT,
|
|
extensionId: DEV_EXTENSION_ID
|
|
});
|
|
```
|
|
|
|
`DEV_EXTENSION_ID` is stable as long as the same `key.pem` is used for the
|
|
unpacked extension. Pinning `key.pem` in the repo (non-secret for dev builds)
|
|
keeps it consistent across machines.
|
|
|
|
### SSL certificates for stubs
|
|
|
|
The Node server stub also needs HTTPS — the extension and companion both
|
|
communicate with it over HTTPS. A second `mkcert` cert for the local server
|
|
domain (e.g. `api.locqr.dev`) covers this. The companion web stub, if opened
|
|
in a mobile browser over a tunnel, needs the tunnel's HTTPS certificate.
|
|
|
|
A shared `mkcert` setup script that issues certs for all local domains and
|
|
places them where each stub expects them would reduce per-developer setup
|
|
friction. Deferred until the dev environment stabilises.
|
|
|
|
---
|
|
|
|
## Registration certificate
|
|
|
|
The test domain's ML-DSA-44 registration certificate is generated by the Node
|
|
server stub at startup (using its pre-generated signing key) and either:
|
|
- Written to a known location for the test site to copy-paste into its
|
|
`locqr.init()` call, or
|
|
- Served by the stub at a known endpoint so the test site can fetch it on load
|
|
|
|
The exact mechanism is deferred; either works for development purposes.
|