Full site review and update LATEST
A top-to-bottom review of every page, presentation, specification, and code sample — with fixes applied across the whole site. The presentation player is now reliable in every mode, the protocol documents are internally consistent, and the TypeScript SDK compiles and follows the specification.
🎬 Presentations & player
- Autoplay with audio fixed in five presentations (Authentication Options 1 & 2, Direct Routing, Distributed Database, Emergency Services) — narration completion was never signalled, so Play appeared to do nothing.
- Play now starts narration immediately in every presentation, instead of waiting for a manual Next click.
- No more scene-skipping — pressing Next/Previous during playback used to advance two scenes at once; rapid clicking could cascade. A narration session guard now prevents it (this also fixed a dormant bug in the Law Enforcement deck that silently disabled its auto-advance).
- Law Enforcement Access no longer races through its scenes on load — it auto-started narration without a user gesture, which browsers block, causing the deck to flip through all 8 scenes on first visit. It now starts paused like the others.
- Toggling audio mid-playback no longer stalls or double-advances the deck; overlapping narration timers cleared; keyboard navigation no longer exits the presentation from the last scene.
- End-to-End Scenario corrected: scene 4 narrated the authentication query backwards (CP1 querying itself) — the terminating provider now correctly queries the originating provider, with the diagram arrows to match; scene 8's timing claim clarified.
- Unused animation library removed from all 10 presentation pages (faster loads); narration voice selection made reliable.
🏠 Landing page
- Corrected facts: Solution Overview is 10 scenes (was listed as 12); there are 10 animations (was "9"); UK emergency number 999 used consistently; cost-saving claims aligned to "up to 80%" to match the deep-dive figures.
- Copy fixes in the problem cards; consistent "Real-time 999" phrasing.
- Footer now lists all 10 presentations, and previously broken links (test environment, bare code directories, "All Presentations") now point to real destinations.
- Law Enforcement Access recategorised under "Complete Walkthrough & Use Cases".
- Added: page metadata for search/link previews, a site favicon, an accessible name for the architecture diagram, and improved text contrast in the hero and quick-links.
- This changes page, linked from the header and footer.
📚 Documentation
- Protocol specification made internally consistent: one token format everywhere (TK- + 16 alphanumeric characters); call references are proper UUIDs in every example; rate-limit figures reconciled; number-porting flow redesigned from a misused HTTP 301 to a clean 200 response with re-query guidance.
- Cryptography description corrected: Ed25519 is signature-only — media encryption keys now correctly come from the DTLS-SRTP handshake (X25519 inside DTLS 1.3, RFC 9147), with the Ed25519 identity key authenticating the certificate fingerprint.
- Replay protection added to the security considerations (message-ID cache over the timestamp window), closing a gap the testing specification assumed but the protocol never defined.
- OpenAPI specification fixes: signature made a required body field (bogus header scheme removed), 400 responses added, ETag/If-None-Match documented for the directory, version field added to all request schemas, invalid format identifiers replaced.
- MAP guides: PostgreSQL-valid schema DDL, TLS 1.3 minimum in the on-prem load-balancer config, Redis primary/replica config corrected, AWS guide reconciled with what its steps actually deploy, invalid example provider IDs fixed.
- Emergency-location retention statement aligned across documents (max 24 hours after call end).
- Broken cross-references repaired throughout; repository links point to the project's GitHub home; the missing Testing Specification HTML page now exists; in-page table-of-contents links now work in all HTML documents.
💻 Sample code & TypeScript SDK
- Real Ed25519 signatures implemented. The TypeScript SDK previously used a symmetric HMAC construction that could never verify across parties (and RSA key generation the spec doesn't call for). Signing and verification now use genuine Ed25519 keys, matching what the specification — and the examples' own output — always claimed.
- The SDK now compiles cleanly and follows the specification: endpoint paths (
/auth/verify,/routing/request,/emergency/location,/directory/all…), protocol headers (X-PSTN2-*), message envelope fields (messageId, version, timestamp, signature), and response field names all match the protocol documents. Previously the TypeScript SDK diverged from the spec that the Python and Go examples followed. - All five numbered TypeScript examples now type-check and run — they were written against an API surface the SDK didn't have. The SDK gained
client.close(), token verification, and options-object call signatures; a directory-caching bug that stored provider IDs where endpoint URLs belonged is fixed. - Reliability fixes learners would otherwise copy: routing rejections are returned (not thrown) so the documented
if (routing.accepted)pattern works; emergency-location failures are surfaced to the caller instead of silently returning nothing; cache timers no longer keep short scripts alive; ported-call retries no longer drop caller options; cache TTL configuration is consistently in seconds. - Go examples restructured so each builds as its own program, with a module definition.
- Honest install instructions: the READMEs no longer direct you to package registries where these SDKs aren't published yet — they explain what's runnable from this site today and show the intended published-package usage alongside.
- Documentation pages for the code samples regenerated to match, with working cross-links to the specifications.
🔧 Site infrastructure
- Project source is now open source on GitHub — github.com/njjholland-dot/pstn2 (public domain / CC0) — with a single reproducible deployment script.
- Documentation HTML pages are regenerated from their Markdown sources by a build script, so the two can no longer drift apart.