What's Changed

One way to authenticate: direct query LATEST

The Token Pool authentication option has been withdrawn. Direct query is simpler and fully effective on its own. The receiving provider finds the caller ID’s holder with Number Discovery and asks it to confirm the call, peer to peer, with signed answers. Token pools are no longer offered anywhere on the site.

• Presentations: the “Authentication: Token Pool” presentation is removed. “Authentication: Direct Query” is now simply Caller Authentication (the old address redirects). There are now 10 presentations, and every narration uses the Siri British English voice.
• Specification and API: the token pool section, endpoints (/auth/tokens), schemas, error codes and bearer-token scheme are removed. Authentication is a single mechanism (§5).
• SDKs and examples: token pool code and tests are removed from the TypeScript, Python and Go SDKs, and from the mock network. The examples are renumbered 01–05, with 05 the live number-discovery walkthrough.
• Documentation: the implementation guide, testing specification, examples guide and MAP guides are updated to match.

Number Discovery, broadcast presentations and a live test CP

PSTN2 now answers “who has this number?” in one consistent way across the whole site, using the mechanism from the Solution Overview: cache, Ofcom’s S1–S9 lists with a Range Holder URL, ask the Range Holder, follow a redirect if the number has been ported, cache the answer. There is no central database and no replicated directory.

🔎 Protocol v1.1: Number Discovery

• The Directory Service is gone. The specification’s §9 is now Number Discovery: GET {rangeHolderUrl}/pstn2/v1/numbers/{digits} answers held, redirect (from the Range Holder, for a ported-out number), not_held, or 404. The /directory/all, /directory/publish and /directory/lookup endpoints, hourly sync and eventual-consistency replication have been removed.
• Self-correcting caches: any PSTN2 response can carry cache.invalidate, so a stale cache entry costs one extra query, never a misrouted call.
• Answers are Ed25519-signed over canonical JSON, with each provider’s keys at /pstn2/v1/keys. The OpenAPI specification now passes validation.
• The redirect stays an HTTP 200 result, keeping the earlier decision to move away from HTTP 301.

🎬 Presentations

• Distributed Database rebuilt as “Who Has This Number?” It previously described replication, gossip propagation, directory servers and “latest timestamp wins”, which contradicted the Solution Overview. It now walks through the real mechanism step by step.
• Central database cost corrected to about £2m to build and about £600k a year to run (30% a year). The site previously said £5 billion.
• All presentations rebuilt for television and conference screens: a fixed 16:9 stage, professional pre-rendered UK narration, captions, chapters, full screen, and a kiosk loop (?kiosk=1). Fonts and libraries are self-hosted, so the decks work offline. Fictional providers and Ofcom’s reserved drama-range numbers are used throughout.
• New: Test Harness live demo. Three providers, each a Range Holder with ported numbers, and Ofcom’s numbering list. They answer “who has this number?” for unported, ported, cached and invalidated cases, with narration. It ends with an interactive mode that runs the real discovery engine.

💻 Code

• Real SDKs in all three languages. TypeScript was reworked, and Python and Go were written from scratch; previously they were examples only. Each has a Number Discovery client, a Range Holder responder, signature verification, and authentication, routing and emergency modules built on discovery.
• Runnable examples in every language, including a live number discovery walkthrough, which runs against the live test CP. Unit and integration tests in every language, plus a conformance suite that proves all three agree with the reference engine.
• New: live dummy test CP at pstn2.org/testcp. It offers a test numbering list, two test Range Holders, one ported number, and signed answers.
• The old MySQL test prototype was replaced with a dependency-free mock network and test environment. The Test Harness ZIP and Complete Download links now work.

Full site review and update

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.

Law Enforcement Access & MAP deployment guides

• New presentation: Law Enforcement Access (8 scenes).
• New documentation: MAP Overview, Multi-Tenant Design, AWS Deployment, and On-Premises Deployment guides.
• Updated homepage with documentation quick links and HTML views of all documents.

Initial launch — PSTN2 v1.0

• 9 animated presentations with narration.
• Protocol specification, OpenAPI definition, implementation guide, and testing specification.
• 15 sample implementations across TypeScript, Python, and Go.
• Complete project download and test-harness archives.