@nano133/ticket 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+First release (Pre-alpha): `readTicket`, `verifyTicket`, `fetchKeys`, `ticketFromHash`,
+`hashWithoutTicket`. One ticket is pinned byte for byte in the tests, and nano133.com's own
+test pins the same one.
+The key list is read with a 5 second limit (`KEYS_TIMEOUT_MS`), so a slow nano133.com never holds a game's first screen. A ticket's `look` is a clean copy of its five colours.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nano133.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @nano133/ticket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stage: Pre-alpha. What this means: https://nano133.com/stages
+
+Read and check a Nanoterra sign-in ticket, in the player's browser. It is for a
+game on a **static site**: no server, no secret. A player who is signed in at
+nano133.com presses Play in Nanoterra, agrees once on a card, and arrives at your
+game with a signed ticket after the `#` of its address. This package checks the
+ticket and gives you the player's **username**, **Nano address** and
+**character** (the look and the cosmetics the player owns).
+
+If your game has a server, use the code exchange instead (the
+[game starter](https://github.com/nano133-com/nano-game-starter) does): a server that holds
+a secret can know who is at the other end. A ticket cannot.
+
+```ts
+import { readTicket } from "@nano133/ticket";
+
+const result = await readTicket();
+if (result.ok) {
+  const { username, address, look, items } = result.ticket;
+  // Ask first: "Sign in as {username}? Continue / Not me" (see "Rules" below).
+}
+// result.ok === false: a guest. result.reason says why ("none" is a plain visit).
+```
+
+`readTicket()` does four things, in this order:
+
+1. Finds `#nanoterra=<ticket>` in the page's address. With none, it answers
+   `{ ok: false, reason: "none" }` and does nothing else (no network call).
+2. **Takes the ticket out of the address bar** (`history.replaceState`), so a
+   reload, a copied link, a screenshot or a bookmark never carries it.
+3. Reads the public keys from `https://nano133.com/api/nanoterra/keys` (once for
+   the session, and again if a ticket names a key it does not know; it waits 5 seconds at most, then the player is a guest).
+4. Checks the signature, the kind, that the ticket is **for this origin** and that
+   it has not run out. It never throws.
+
+Call it once, when the page loads.
+
+## Rules
+
+- **A ticket proves nothing to your server.** The ticket sits in an address bar:
+  anyone who sees it can use it for two minutes. Use it to show the player's name
+  and character. **Never give a sale, a prize or a score on a ticket alone.**
+- **Ask before you treat the player as that name.** Anyone can send a link that holds
+  their *own* ticket (login CSRF). Show "Sign in as *name*? Continue / Not me" and
+  keep the player a guest until Continue.
+- **Show the name** wherever the player is "signed in", and say whose account it is
+  before a payment.
+- **The username comes from another site.** Put it in the page as text, never as HTML.
+- A guest is a normal visit. Every refusal (`reason`) means "play as a guest".
+
+## What you get
+
+```ts
+type Ticket = {
+  username: string;
+  address: string; // the whole Nano address; also the player's id
+  look: { skin: string; hair: string; shirt: string; pants: string; shoes: string }; // "#rrggbb"
+  items: string[]; // the Nanoterra cosmetics the player owns, in the character's slots
+  game: string; // your game's id at nano133.com
+  audience: string; // the origin the ticket is for
+  issuedAt: number; // ms since 1970
+  expiresAt: number;
+  id: string;
+};
+```
+
+The character is the same one `@nano133/character` draws in Three.js.
+
+## Refusals
+
+| `reason` | Meaning |
+|---|---|
+| `none` | no ticket in the address: a plain visit |
+| `unsupported` | this browser has no Ed25519 in Web Crypto (Chrome 137, Safari 17, Firefox 129 and later have it) |
+| `malformed` | not a ticket |
+| `keys` | the public keys could not be read (offline, or nano133.com did not answer) |
+| `unknown-key`, `signature` | signed with a key that is not nano133.com's, or the signature does not hold |
+| `wrong-kind` | signed right, but not a version 1 ticket from nano133.com |
+| `audience` | a ticket for another origin |
+| `expired`, `early`, `life` | the time does not hold. A player's clock may be a minute off, either way |
+
+## Options
+
+```ts
+readTicket({
+  keys, // pin the public keys: no fetch at all
+  keysUrl, // another place for the keys (tests)
+  keysTimeoutMs, // how long to wait for the keys; default 5,000 (a slow nano133.com never holds your first screen)
+  audience, // the origin to expect; default: this page's own
+});
+```
+
+`verifyTicket(token, { audience, keys })` checks a ticket you already hold, and
+`fetchKeys()`, `ticketFromHash(hash)` and `hashWithoutTicket(hash)` are the
+parts.
+
+## The format
+
+For any language. A ticket is `base64url(JSON claims) "." base64url(signature)`: an Ed25519 signature over the
+ASCII of the first part, made with the key whose `kid` the claims name.
+
+```json
+{ "v": 1, "typ": "ticket", "iss": "nano133.com", "kid": "fe812c12f3ab4ce6", "aud": "https://game.example",
+  "game": "gem-island", "sub": "nano_3i7m…", "name": "Ann",
+  "look": { "skin": "#f2c29b", "hair": "#3a2a1e", "shirt": "#2a9df4", "pants": "#1e2a4a", "shoes": "#ffffff" },
+  "items": ["hub.sun-hat"], "iat": 1800000000, "exp": 1800000120, "jti": "AAAAAAAAAAAAAAAA" }
+```
+
+`GET https://nano133.com/api/nanoterra/keys` answers `{ "keys": [{ "kid", "kty": "OKP", "crv": "Ed25519", "x", "alg": "EdDSA", "use": "sig" }] }`
+and may be read from any page. A ticket lives two minutes (`exp - iat` is 120; a longer life is refused).
+
+## Turn it on
+
+Your `nano-game.json` says `"signin": "ticket"`. Nanoterra's Play key then sends signed-in players to
+your play address with a ticket. A player who has not agreed, or who plays as a guest, arrives with no ticket.
+
+MIT license.

package/ai/PROMPT.md

@@ -0,0 +1,10 @@
+# Nanoterra sign-in ticket: the prompt
+
+```
+Take players who press Play in Nanoterra signed in on this static game (no server of its own).
+Use the npm package @nano133/ticket and follow its SPEC step by step:
+https://nano133.com/build/nanoterra
+Set "signin": "ticket" in nano-game.json. Call readTicket() once when the page loads, ask
+"Sign in as <name>? Continue / Not me" before treating the player as that name, and show the name.
+Never give a sale, a prize or a score on a ticket alone. Put the name in the page as text.
+```

package/ai/SPEC.md

@@ -0,0 +1,42 @@
+# Nanoterra sign-in ticket: implementation spec
+
+Package: `@nano133/ticket` (0.1.0 or later). For a game on a **static site** (no server of its
+own). A game with a server uses the code exchange instead (the game starter has it).
+
+## 0. Decide (ask)
+
+1. Does the game have a server? If yes, stop: use the code exchange. A ticket cannot prove who
+   is at the other end, so a server must not trust it.
+2. What the game does with the player's name and character: show them (fine), or give something
+   of value (a sale, a prize, a score). **Never give anything of value on a ticket alone.**
+
+## 1. Turn it on
+
+In `nano-game.json` set `"signin": "ticket"`. Nothing else is made at nano133.com (no secret).
+
+## 2. Read the ticket when the page loads
+
+```ts
+import { readTicket } from "@nano133/ticket";
+const result = await readTicket();
+```
+
+Call it once. It takes the ticket out of the address bar first. If `result.ok` is false the
+player is a guest (`result.reason` is `"none"` for a plain visit).
+
+## 3. Ask before you sign the player in
+
+Show "Sign in as *name*? Continue / Not me". Anyone can send a link that holds their own ticket.
+Until Continue, the player is a guest. Put the name in the page as text, never as HTML.
+
+## 4. Use the details
+
+`result.ticket`: `username`, `address`, `look` (five `#rrggbb` colours), `items` (catalogue ids).
+Keep them in memory or `sessionStorage`. Show the name wherever the player is signed in.
+
+## Checks
+
+- A plain visit (no `#nanoterra=`) makes no network call and shows no card.
+- A ticket for another origin, a changed ticket and an old ticket each give a guest.
+- The address bar has no ticket after the page loaded.
+- No sale, prize or score depends on the ticket.

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+export declare const TICKET_PARAM = "nanoterra";
+export declare const DEFAULT_KEYS_URL = "https://nano133.com/api/nanoterra/keys";
+export declare const ISSUER = "nano133.com";
+/** A ticket longer than this is not one. */
+export declare const MAX_LENGTH = 4096;
+/** A ticket lives this long (seconds). A longer life is refused. */
+export declare const MAX_LIFE_SECONDS = 120;
+/** A player's clock may be this far off (seconds), either way. */
+export declare const SLACK_SECONDS = 60;
+export type Look = {
+    skin: string;
+    hair: string;
+    shirt: string;
+    pants: string;
+    shoes: string;
+};
+/** What a ticket says about the player. Times are in milliseconds since 1970. */
+export type Ticket = {
+    username: string;
+    /** The player's whole Nano address. It is also the player's id. */
+    address: string;
+    look: Look;
+    /** The Nanoterra cosmetics the player owns, in the island character's slots (catalogue ids). */
+    items: string[];
+    /** The game's id at nano133.com, and the origin the ticket is for. */
+    game: string;
+    audience: string;
+    issuedAt: number;
+    expiresAt: number;
+    /** A random id of this ticket. */
+    id: string;
+};
+/** One public key of GET https://nano133.com/api/nanoterra/keys (a JWK, RFC 8037: Ed25519). */
+export type PublicKey = {
+    kid: string;
+    x: string;
+    kty?: string;
+    crv?: string;
+    alg?: string;
+    use?: string;
+};
+export type Keys = {
+    keys: PublicKey[];
+};
+export type Refusal = "none" | "unsupported" | "malformed" | "keys" | "unknown-key" | "signature" | "wrong-kind" | "audience" | "expired" | "early" | "life";
+export type Result = {
+    ok: true;
+    ticket: Ticket;
+} | {
+    ok: false;
+    reason: Refusal;
+};
+/** The ticket in an address's fragment (`location.hash`), or null. Other fragment parts are left alone. */
+export declare function ticketFromHash(hash: string): string | null;
+/** The fragment without the ticket ("" when nothing else is in it, else "#" and the rest). */
+export declare function hashWithoutTicket(hash: string): string;
+/** How long the page waits for the keys (milliseconds). A slow nano133.com must not hold a game's first screen. */
+export declare const KEYS_TIMEOUT_MS = 5000;
+/** The public keys, as nano133.com publishes them (any origin may read them). `cache: "reload"` skips the browser's copy. Rejects after KEYS_TIMEOUT_MS. */
+export declare function fetchKeys(url?: string, fetcher?: typeof fetch, cache?: RequestCache, timeoutMs?: number): Promise<Keys>;
+export type VerifyOptions = {
+    /** The origin this page is on, e.g. "https://game.example". A ticket for another origin is refused. */
+    audience: string;
+    keys: Keys;
+    /** Milliseconds since 1970 (for tests). */
+    now?: number;
+    /** Web Crypto's `subtle` (for tests). */
+    subtle?: SubtleCrypto;
+};
+/** Checks a ticket: the key, the signature, the kind, the audience and the time. Never throws. */
+export declare function verifyTicket(token: string, o: VerifyOptions): Promise<Result>;
+export type ReadOptions = {
+    /** Pin the keys (no fetch). Else they are read from `keysUrl` once, and again when a ticket names a key that is not in the list. */
+    keys?: Keys;
+    keysUrl?: string;
+    /** How long to wait for the keys (milliseconds): the default is KEYS_TIMEOUT_MS. */
+    keysTimeoutMs?: number;
+    /** The origin to expect. Default: this page's own origin. */
+    audience?: string;
+    location?: Pick<Location, "hash" | "pathname" | "search" | "origin">;
+    history?: Pick<History, "replaceState" | "state">;
+    fetch?: typeof fetch;
+    now?: number;
+    subtle?: SubtleCrypto;
+};
+/**
+ * Reads the ticket from this page's address, if there is one. FIRST it takes the ticket out of the address bar (the page's history
+ * entry is replaced), so a reload, a copied link, a screenshot or a bookmark never carries it; then it checks the ticket. Call it once, when
+ * the page loads. `{ ok: false, reason: "none" }` is a plain visit (no network call). Anything else that is not ok is a guest.
+ *
+ * Show "Sign in as <name>? Continue / Not me" before you treat the player as that name: anyone can send a link that holds their own ticket.
+ */
+export declare function readTicket(o?: ReadOptions): Promise<Result>;
+/** Forgets the keys read so far (for tests). */
+export declare function forgetKeys(): void;

package/dist/index.js

@@ -0,0 +1,173 @@
+// Read and check a Nanoterra sign-in ticket, in the player's browser. For a game on a STATIC site: no server to trade a one-time code.
+//
+// Nanoterra (nano133.com) opens the game's own address with the ticket after a `#`:  https://game.example/#nanoterra=<ticket>.
+// A fragment is never sent to a server. `readTicket()` takes the ticket out of the address bar at once, checks its signature with
+// nano133.com's public key and answers with the player's username, Nano address and character.
+//
+// WHAT A TICKET PROVES: that nano133.com said "this player, for this game, a moment ago". Anyone who sees the address can use the
+// ticket until it runs out (two minutes), so it proves nothing to YOUR SERVER. Use it to show the player's name and character. Never
+// give a sale, a prize or a score on a ticket alone: for that, use the code exchange (a server that holds a secret).
+//
+// Format (the same as nano133.com's receipts): base64url(JSON claims) "." base64url(Ed25519 signature over the first part).
+// Web Crypto only (Ed25519: Chrome 137, Safari 17, Firefox 129, Node 20 and later); no other import.
+export const TICKET_PARAM = "nanoterra";
+export const DEFAULT_KEYS_URL = "https://nano133.com/api/nanoterra/keys";
+export const ISSUER = "nano133.com";
+/** A ticket longer than this is not one. */
+export const MAX_LENGTH = 4096;
+/** A ticket lives this long (seconds). A longer life is refused. */
+export const MAX_LIFE_SECONDS = 120;
+/** A player's clock may be this far off (seconds), either way. */
+export const SLACK_SECONDS = 60;
+const TOKEN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const COLOUR = /^#[0-9a-fA-F]{6}$/;
+const ADDRESS = /^nano_[13][13-9a-km-uw-z]{59}$/;
+const dec = new TextDecoder();
+const enc = new TextEncoder();
+function unb64url(text) {
+    const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+    return Uint8Array.from(s, (c) => c.charCodeAt(0));
+}
+/** The ticket in an address's fragment (`location.hash`), or null. Other fragment parts are left alone. */
+export function ticketFromHash(hash) {
+    for (const part of hash.replace(/^#/, "").split("&")) {
+        if (part.startsWith(`${TICKET_PARAM}=`)) {
+            const value = part.slice(TICKET_PARAM.length + 1);
+            return value.length <= MAX_LENGTH && TOKEN.test(value) ? value : null;
+        }
+    }
+    return null;
+}
+/** The fragment without the ticket ("" when nothing else is in it, else "#" and the rest). */
+export function hashWithoutTicket(hash) {
+    const rest = hash.replace(/^#/, "").split("&").filter((part) => !part.startsWith(`${TICKET_PARAM}=`) && part !== "");
+    return rest.length ? `#${rest.join("&")}` : "";
+}
+/** How long the page waits for the keys (milliseconds). A slow nano133.com must not hold a game's first screen. */
+export const KEYS_TIMEOUT_MS = 5000;
+/** The public keys, as nano133.com publishes them (any origin may read them). `cache: "reload"` skips the browser's copy. Rejects after KEYS_TIMEOUT_MS. */
+export async function fetchKeys(url = DEFAULT_KEYS_URL, fetcher = fetch, cache = "default", timeoutMs = KEYS_TIMEOUT_MS) {
+    const stop = new AbortController();
+    const timer = setTimeout(() => stop.abort(), timeoutMs);
+    try {
+        const r = await fetcher(url, { credentials: "omit", cache, signal: stop.signal });
+        if (!r.ok)
+            throw new Error(`keys answered ${r.status}`);
+        return readKeys(await r.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readKeys(j) {
+    if (!j || !Array.isArray(j.keys))
+        throw new Error("keys: not a list");
+    return { keys: j.keys.filter((k) => !!k && typeof k.kid === "string" && typeof k.x === "string") };
+}
+/** Checks a ticket: the key, the signature, the kind, the audience and the time. Never throws. */
+export async function verifyTicket(token, o) {
+    const no = (reason) => ({ ok: false, reason });
+    if (typeof token !== "string" || token.length > MAX_LENGTH || !TOKEN.test(token))
+        return no("malformed");
+    const subtle = o.subtle ?? globalThis.crypto?.subtle;
+    if (!subtle)
+        return no("unsupported");
+    const [body, sig] = token.split(".");
+    let claims;
+    try {
+        claims = JSON.parse(dec.decode(unb64url(body)));
+    }
+    catch {
+        return no("malformed");
+    }
+    if (!claims || typeof claims !== "object" || typeof claims.kid !== "string")
+        return no("malformed");
+    const key = o.keys.keys.find((k) => k.kid === claims.kid);
+    if (!key)
+        return no("unknown-key");
+    try {
+        const publicKey = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: key.x }, { name: "Ed25519" }, false, ["verify"]);
+        if (!(await subtle.verify("Ed25519", publicKey, unb64url(sig), enc.encode(body))))
+            return no("signature");
+    }
+    catch (e) {
+        return no(e?.name === "NotSupportedError" ? "unsupported" : "signature");
+    }
+    // The signature holds: the claims are nano133.com's. They still must be what a ticket is, for this page, now.
+    if (claims.v !== 1 || claims.typ !== "ticket" || claims.iss !== ISSUER)
+        return no("wrong-kind");
+    if (claims.aud !== o.audience)
+        return no("audience");
+    const { iat, exp } = claims;
+    if (typeof iat !== "number" || typeof exp !== "number")
+        return no("malformed");
+    const now = (o.now ?? Date.now()) / 1000;
+    if (!(exp > now - SLACK_SECONDS))
+        return no("expired");
+    if (!(iat < now + SLACK_SECONDS))
+        return no("early");
+    if (!(exp - iat <= MAX_LIFE_SECONDS))
+        return no("life");
+    const { sub, name, look, items, game, jti } = claims;
+    const l = look;
+    if (typeof sub !== "string" || !ADDRESS.test(sub) || typeof name !== "string" || !name || name.length > 60 || typeof game !== "string" || typeof jti !== "string")
+        return no("malformed");
+    if (!l || typeof l !== "object" || !["skin", "hair", "shirt", "pants", "shoes"].every((p) => typeof l[p] === "string" && COLOUR.test(l[p])))
+        return no("malformed");
+    if (!Array.isArray(items) || items.length > 64 || !items.every((i) => typeof i === "string" && i.length <= 48))
+        return no("malformed");
+    const clean = { skin: l.skin, hair: l.hair, shirt: l.shirt, pants: l.pants, shoes: l.shoes };
+    return { ok: true, ticket: { username: name, address: sub, look: clean, items: [...items], game, audience: claims.aud, issuedAt: iat * 1000, expiresAt: exp * 1000, id: jti } };
+}
+let cached = null;
+/**
+ * Reads the ticket from this page's address, if there is one. FIRST it takes the ticket out of the address bar (the page's history
+ * entry is replaced), so a reload, a copied link, a screenshot or a bookmark never carries it; then it checks the ticket. Call it once, when
+ * the page loads. `{ ok: false, reason: "none" }` is a plain visit (no network call). Anything else that is not ok is a guest.
+ *
+ * Show "Sign in as <name>? Continue / Not me" before you treat the player as that name: anyone can send a link that holds their own ticket.
+ */
+export async function readTicket(o = {}) {
+    const loc = o.location ?? globalThis.location;
+    const hist = o.history ?? globalThis.history;
+    if (!loc)
+        return { ok: false, reason: "none" };
+    // A ticket is taken out of the address bar FIRST, also one that is not a good ticket.
+    if (!loc.hash.replace(/^#/, "").split("&").some((part) => part.startsWith(`${TICKET_PARAM}=`)))
+        return { ok: false, reason: "none" };
+    const token = ticketFromHash(loc.hash);
+    if (hist)
+        hist.replaceState(hist.state, "", loc.pathname + loc.search + hashWithoutTicket(loc.hash));
+    if (!token)
+        return { ok: false, reason: "malformed" };
+    const audience = o.audience ?? loc.origin;
+    const load = async (fresh) => {
+        if (o.keys)
+            return o.keys;
+        if (cached && !fresh)
+            return cached;
+        try {
+            cached = await fetchKeys(o.keysUrl, o.fetch, fresh ? "reload" : "default", o.keysTimeoutMs);
+            return cached;
+        }
+        catch {
+            return null;
+        }
+    };
+    let keys = await load(false);
+    if (!keys)
+        return { ok: false, reason: "keys" };
+    let result = await verifyTicket(token, { audience, keys, now: o.now, subtle: o.subtle });
+    if (!result.ok && result.reason === "unknown-key" && !o.keys) {
+        // nano133.com may have a new key since this page last read the list.
+        keys = await load(true);
+        if (!keys)
+            return { ok: false, reason: "keys" };
+        result = await verifyTicket(token, { audience, keys, now: o.now, subtle: o.subtle });
+    }
+    return result;
+}
+/** Forgets the keys read so far (for tests). */
+export function forgetKeys() {
+    cached = null;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@nano133/ticket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read and check a Nanoterra sign-in ticket in the player's browser: for a game on a static site. The player's name, address and character; no server, no secret.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "sideEffects": false,
+  "files": ["dist", "src", "README.md", "CHANGELOG.md", "LICENSE", "ai"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.15",
+    "typescript": "5.9"
+  },
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nano133-com/kit.git",
+    "directory": "packages/ticket"
+  },
+  "homepage": "https://nano133.com/build/nanoterra",
+  "license": "MIT",
+  "keywords": ["nano", "xno", "nanoterra", "sign in", "ticket", "ed25519", "static site"]
+}

package/src/index.ts

@@ -0,0 +1,221 @@
+// Read and check a Nanoterra sign-in ticket, in the player's browser. For a game on a STATIC site: no server to trade a one-time code.
+//
+// Nanoterra (nano133.com) opens the game's own address with the ticket after a `#`:  https://game.example/#nanoterra=<ticket>.
+// A fragment is never sent to a server. `readTicket()` takes the ticket out of the address bar at once, checks its signature with
+// nano133.com's public key and answers with the player's username, Nano address and character.
+//
+// WHAT A TICKET PROVES: that nano133.com said "this player, for this game, a moment ago". Anyone who sees the address can use the
+// ticket until it runs out (two minutes), so it proves nothing to YOUR SERVER. Use it to show the player's name and character. Never
+// give a sale, a prize or a score on a ticket alone: for that, use the code exchange (a server that holds a secret).
+//
+// Format (the same as nano133.com's receipts): base64url(JSON claims) "." base64url(Ed25519 signature over the first part).
+// Web Crypto only (Ed25519: Chrome 137, Safari 17, Firefox 129, Node 20 and later); no other import.
+
+export const TICKET_PARAM = "nanoterra";
+export const DEFAULT_KEYS_URL = "https://nano133.com/api/nanoterra/keys";
+export const ISSUER = "nano133.com";
+/** A ticket longer than this is not one. */
+export const MAX_LENGTH = 4096;
+/** A ticket lives this long (seconds). A longer life is refused. */
+export const MAX_LIFE_SECONDS = 120;
+/** A player's clock may be this far off (seconds), either way. */
+export const SLACK_SECONDS = 60;
+
+export type Look = { skin: string; hair: string; shirt: string; pants: string; shoes: string };
+
+/** What a ticket says about the player. Times are in milliseconds since 1970. */
+export type Ticket = {
+  username: string;
+  /** The player's whole Nano address. It is also the player's id. */
+  address: string;
+  look: Look;
+  /** The Nanoterra cosmetics the player owns, in the island character's slots (catalogue ids). */
+  items: string[];
+  /** The game's id at nano133.com, and the origin the ticket is for. */
+  game: string;
+  audience: string;
+  issuedAt: number;
+  expiresAt: number;
+  /** A random id of this ticket. */
+  id: string;
+};
+
+/** One public key of GET https://nano133.com/api/nanoterra/keys (a JWK, RFC 8037: Ed25519). */
+export type PublicKey = { kid: string; x: string; kty?: string; crv?: string; alg?: string; use?: string };
+export type Keys = { keys: PublicKey[] };
+
+export type Refusal =
+  | "none" // no ticket in the address: a plain visit
+  | "unsupported" // this browser has no Ed25519 in Web Crypto
+  | "malformed" // not a ticket
+  | "keys" // the public keys could not be read
+  | "unknown-key" // signed with a key that is not in the list
+  | "signature" // the signature does not hold
+  | "wrong-kind" // signed right, but not a version 1 ticket from nano133.com
+  | "audience" // a ticket for another origin
+  | "expired"
+  | "early" // issued in the future (a clock that is far off)
+  | "life"; // asks for a life longer than a ticket may have
+export type Result = { ok: true; ticket: Ticket } | { ok: false; reason: Refusal };
+
+const TOKEN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const COLOUR = /^#[0-9a-fA-F]{6}$/;
+const ADDRESS = /^nano_[13][13-9a-km-uw-z]{59}$/;
+const dec = new TextDecoder();
+const enc = new TextEncoder();
+
+function unb64url(text: string): Uint8Array<ArrayBuffer> {
+  const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+  return Uint8Array.from(s, (c) => c.charCodeAt(0));
+}
+
+/** The ticket in an address's fragment (`location.hash`), or null. Other fragment parts are left alone. */
+export function ticketFromHash(hash: string): string | null {
+  for (const part of hash.replace(/^#/, "").split("&")) {
+    if (part.startsWith(`${TICKET_PARAM}=`)) {
+      const value = part.slice(TICKET_PARAM.length + 1);
+      return value.length <= MAX_LENGTH && TOKEN.test(value) ? value : null;
+    }
+  }
+  return null;
+}
+
+/** The fragment without the ticket ("" when nothing else is in it, else "#" and the rest). */
+export function hashWithoutTicket(hash: string): string {
+  const rest = hash.replace(/^#/, "").split("&").filter((part) => !part.startsWith(`${TICKET_PARAM}=`) && part !== "");
+  return rest.length ? `#${rest.join("&")}` : "";
+}
+
+/** How long the page waits for the keys (milliseconds). A slow nano133.com must not hold a game's first screen. */
+export const KEYS_TIMEOUT_MS = 5000;
+
+/** The public keys, as nano133.com publishes them (any origin may read them). `cache: "reload"` skips the browser's copy. Rejects after KEYS_TIMEOUT_MS. */
+export async function fetchKeys(url: string = DEFAULT_KEYS_URL, fetcher: typeof fetch = fetch, cache: RequestCache = "default", timeoutMs: number = KEYS_TIMEOUT_MS): Promise<Keys> {
+  const stop = new AbortController();
+  const timer = setTimeout(() => stop.abort(), timeoutMs);
+  try {
+    const r = await fetcher(url, { credentials: "omit", cache, signal: stop.signal });
+    if (!r.ok) throw new Error(`keys answered ${r.status}`);
+    return readKeys(await r.json());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readKeys(j: Partial<Keys>): Keys {
+  if (!j || !Array.isArray(j.keys)) throw new Error("keys: not a list");
+  return { keys: j.keys.filter((k): k is PublicKey => !!k && typeof k.kid === "string" && typeof k.x === "string") };
+}
+
+export type VerifyOptions = {
+  /** The origin this page is on, e.g. "https://game.example". A ticket for another origin is refused. */
+  audience: string;
+  keys: Keys;
+  /** Milliseconds since 1970 (for tests). */
+  now?: number;
+  /** Web Crypto's `subtle` (for tests). */
+  subtle?: SubtleCrypto;
+};
+
+type Claims = { v?: unknown; typ?: unknown; iss?: unknown; kid?: unknown; aud?: unknown; game?: unknown; sub?: unknown; name?: unknown; look?: unknown; items?: unknown; iat?: unknown; exp?: unknown; jti?: unknown };
+
+/** Checks a ticket: the key, the signature, the kind, the audience and the time. Never throws. */
+export async function verifyTicket(token: string, o: VerifyOptions): Promise<Result> {
+  const no = (reason: Refusal): Result => ({ ok: false, reason });
+  if (typeof token !== "string" || token.length > MAX_LENGTH || !TOKEN.test(token)) return no("malformed");
+  const subtle = o.subtle ?? globalThis.crypto?.subtle;
+  if (!subtle) return no("unsupported");
+  const [body, sig] = token.split(".") as [string, string];
+  let claims: Claims;
+  try {
+    claims = JSON.parse(dec.decode(unb64url(body))) as Claims;
+  } catch {
+    return no("malformed");
+  }
+  if (!claims || typeof claims !== "object" || typeof claims.kid !== "string") return no("malformed");
+  const key = o.keys.keys.find((k) => k.kid === claims.kid);
+  if (!key) return no("unknown-key");
+  try {
+    const publicKey = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: key.x }, { name: "Ed25519" }, false, ["verify"]);
+    if (!(await subtle.verify("Ed25519", publicKey, unb64url(sig), enc.encode(body)))) return no("signature");
+  } catch (e) {
+    return no((e as { name?: string })?.name === "NotSupportedError" ? "unsupported" : "signature");
+  }
+  // The signature holds: the claims are nano133.com's. They still must be what a ticket is, for this page, now.
+  if (claims.v !== 1 || claims.typ !== "ticket" || claims.iss !== ISSUER) return no("wrong-kind");
+  if (claims.aud !== o.audience) return no("audience");
+  const { iat, exp } = claims;
+  if (typeof iat !== "number" || typeof exp !== "number") return no("malformed");
+  const now = (o.now ?? Date.now()) / 1000;
+  if (!(exp > now - SLACK_SECONDS)) return no("expired");
+  if (!(iat < now + SLACK_SECONDS)) return no("early");
+  if (!(exp - iat <= MAX_LIFE_SECONDS)) return no("life");
+  const { sub, name, look, items, game, jti } = claims;
+  const l = look as Record<string, unknown> | null;
+  if (typeof sub !== "string" || !ADDRESS.test(sub) || typeof name !== "string" || !name || name.length > 60 || typeof game !== "string" || typeof jti !== "string") return no("malformed");
+  if (!l || typeof l !== "object" || !(["skin", "hair", "shirt", "pants", "shoes"] as const).every((p) => typeof l[p] === "string" && COLOUR.test(l[p] as string))) return no("malformed");
+  if (!Array.isArray(items) || items.length > 64 || !items.every((i) => typeof i === "string" && i.length <= 48)) return no("malformed");
+  const clean: Look = { skin: l.skin as string, hair: l.hair as string, shirt: l.shirt as string, pants: l.pants as string, shoes: l.shoes as string };
+  return { ok: true, ticket: { username: name, address: sub, look: clean, items: [...(items as string[])], game, audience: claims.aud as string, issuedAt: iat * 1000, expiresAt: exp * 1000, id: jti } };
+}
+
+export type ReadOptions = {
+  /** Pin the keys (no fetch). Else they are read from `keysUrl` once, and again when a ticket names a key that is not in the list. */
+  keys?: Keys;
+  keysUrl?: string;
+  /** How long to wait for the keys (milliseconds): the default is KEYS_TIMEOUT_MS. */
+  keysTimeoutMs?: number;
+  /** The origin to expect. Default: this page's own origin. */
+  audience?: string;
+  location?: Pick<Location, "hash" | "pathname" | "search" | "origin">;
+  history?: Pick<History, "replaceState" | "state">;
+  fetch?: typeof fetch;
+  now?: number;
+  subtle?: SubtleCrypto;
+};
+
+let cached: Keys | null = null;
+
+/**
+ * Reads the ticket from this page's address, if there is one. FIRST it takes the ticket out of the address bar (the page's history
+ * entry is replaced), so a reload, a copied link, a screenshot or a bookmark never carries it; then it checks the ticket. Call it once, when
+ * the page loads. `{ ok: false, reason: "none" }` is a plain visit (no network call). Anything else that is not ok is a guest.
+ *
+ * Show "Sign in as <name>? Continue / Not me" before you treat the player as that name: anyone can send a link that holds their own ticket.
+ */
+export async function readTicket(o: ReadOptions = {}): Promise<Result> {
+  const loc = o.location ?? globalThis.location;
+  const hist = o.history ?? globalThis.history;
+  if (!loc) return { ok: false, reason: "none" };
+  // A ticket is taken out of the address bar FIRST, also one that is not a good ticket.
+  if (!loc.hash.replace(/^#/, "").split("&").some((part) => part.startsWith(`${TICKET_PARAM}=`))) return { ok: false, reason: "none" };
+  const token = ticketFromHash(loc.hash);
+  if (hist) hist.replaceState(hist.state, "", loc.pathname + loc.search + hashWithoutTicket(loc.hash));
+  if (!token) return { ok: false, reason: "malformed" };
+  const audience = o.audience ?? loc.origin;
+  const load = async (fresh: boolean): Promise<Keys | null> => {
+    if (o.keys) return o.keys;
+    if (cached && !fresh) return cached;
+    try {
+      cached = await fetchKeys(o.keysUrl, o.fetch, fresh ? "reload" : "default", o.keysTimeoutMs);
+      return cached;
+    } catch {
+      return null;
+    }
+  };
+  let keys = await load(false);
+  if (!keys) return { ok: false, reason: "keys" };
+  let result = await verifyTicket(token, { audience, keys, now: o.now, subtle: o.subtle });
+  if (!result.ok && result.reason === "unknown-key" && !o.keys) {
+    // nano133.com may have a new key since this page last read the list.
+    keys = await load(true);
+    if (!keys) return { ok: false, reason: "keys" };
+    result = await verifyTicket(token, { audience, keys, now: o.now, subtle: o.subtle });
+  }
+  return result;
+}
+
+/** Forgets the keys read so far (for tests). */
+export function forgetKeys(): void {
+  cached = null;
+}