@nano133/nanoterra 0.11.0 → 0.12.0

package/src/admin-signin/adapters/d1.sql

@@ -1,9 +1,11 @@
 -- The admin sign-in tables of "@nano133/nanoterra/admin-signin/d1". Add this file to the game's migrations (for example
--- migrations/0009_admin_signin.sql) and run `wrangler d1 migrations apply`. The adapter reads and writes only these three tables, and only the
+-- migrations/0009_admin_signin.sql) and run `wrangler d1 migrations apply`. The adapter reads and writes only these five tables, and only the
 -- ADMIN rows of the first two (scope = 'admin').
 --
--- The game starter has all three already (migrations 0001, 0002, 0003, 0005 and 0006): it needs NO migration, and `IF NOT EXISTS` leaves its tables and
--- rows as they are if it runs this file anyway. A game that has the player sign-in's d1.sql has the first two: this file adds `admin_logins`.
+-- The game starter has the first three already (migrations 0001, 0002, 0003, 0005 and 0006), and `IF NOT EXISTS` leaves its tables and rows as they are if
+-- it runs this file anyway. The last two (since 0.12.0) are the owner's passkeys: a game that turns them on (`createAdminSignin({ passkeys: true })`) and
+-- has the first three adds only those two (the starter: migrations/0009_admin_passkeys.sql, the two CREATE TABLE statements at the end of this file). A
+-- game that has the player sign-in's d1.sql has the first two: this file adds the other three.
 -- Times are milliseconds since 1970 (Date.now()).
 
 -- Wallet sign-in requests (the player's and the admin's: `scope` says whose). An admin request lives 2 minutes; the clean-up deletes it 2 hours after it ends.
@@ -43,3 +45,18 @@ CREATE TABLE IF NOT EXISTS admin_logins (
   browser TEXT NOT NULL                -- a short name from fixed lists: "Chrome on macOS"
 );
 CREATE INDEX IF NOT EXISTS admin_logins_by_time ON admin_logins (at);
+
+-- The owner's passkeys (since 0.12.0): each passkey linked to the game's own address, at most 10 for an owner. Only a live WALLET admin session of the owner
+-- writes a link; a link opens /admin only while it is here and its owner is the game's address NOW.
+CREATE TABLE IF NOT EXISTS admin_passkeys (
+  owner TEXT NOT NULL,                 -- the game's own address when the link was made
+  address TEXT NOT NULL,               -- the passkey purse's address
+  created_at INTEGER NOT NULL,         -- ms since 1970
+  PRIMARY KEY (owner, address)
+);
+
+-- The passkeys' used signatures (the admin's own, apart from the player's signin_once): the hash of each signed text, so one signature counts once.
+CREATE TABLE IF NOT EXISTS admin_once (
+  key TEXT PRIMARY KEY,
+  until INTEGER NOT NULL               -- ms since 1970; the clean-up deletes the row after it
+);

package/src/admin-signin/adapters/d1.ts

@@ -1,6 +1,7 @@
 // The admin sign-in's store for a game on Cloudflare D1, on the game starter's OWN tables and columns: `signin_requests` and `sessions` (their admin
 // rows, scope = 'admin') and `admin_logins`. A starter moves onto it with no migration, and every creator who is signed in to /admin stays signed in.
-// A new game adds ./d1.sql to its migrations ("@nano133/nanoterra/admin-signin/d1.sql": the same tables, `IF NOT EXISTS`).
+// A new game adds ./d1.sql to its migrations ("@nano133/nanoterra/admin-signin/d1.sql": the same tables, `IF NOT EXISTS`). The owner's passkeys (since
+// 0.12.0) use two more tables, `admin_passkeys` and `admin_once` (the end of d1.sql): only a game that turns the passkeys on needs them.
 //
 //   import { createD1AdminSignin } from "@nano133/nanoterra/admin-signin/d1";
 //   const store = createD1AdminSignin(env.DB);
@@ -11,12 +12,12 @@
 // "Sign out everywhere" is the same two statements as the admin store's (`createD1Store(db, { logins: true })`): either one may run it.
 
 import type { D1Like } from "../../admin/adapters/d1.js";
-import { ADMIN_LOGIN_KEEP_MS, ADMIN_WAYS, type AdminSessionRecord, type AdminSigninStore, type AdminWay, type RequestStoreLike, type SigninRequest } from "../types.js";
+import { ADMIN_LOGIN_KEEP_MS, ADMIN_PASSKEY_LIMIT, ADMIN_WAYS, type AdminLinkResult, type AdminSessionRecord, type AdminSigninStore, type AdminWay, type RequestStoreLike, type SigninRequest } from "../types.js";
 
 export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
 
 /** The tables' names. Default: the game starter's. A game with other names changes d1.sql to match. */
-export type D1AdminSigninTables = { requests?: string; sessions?: string; logins?: string };
+export type D1AdminSigninTables = { requests?: string; sessions?: string; logins?: string; passkeys?: string; once?: string };
 
 type Row = { id: string; rid: string | null; starter: string; status: string; expires_at: number; nonce: string | null; issued_at: number | null; label: string | null; account: string | null };
 
@@ -34,8 +35,17 @@ const toRequest = (r: Row): SigninRequest => ({
 const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
 const changes = (res: unknown): number => Number((res as { meta?: { changes?: number } } | undefined)?.meta?.changes ?? 0);
 
-export function createD1AdminSignin(db: D1Like, tables: D1AdminSigninTables = {}): AdminSigninStore {
-  const T = { requests: tables.requests ?? "signin_requests", sessions: tables.sessions ?? "sessions", logins: tables.logins ?? "admin_logins" };
+/** True for D1's (and SQLite's) "no such table": a game that has not added the passkeys' tables. */
+const noTable = (e: unknown) => /no such table/i.test(String((e as { message?: unknown } | null)?.message ?? e));
+
+export function createD1AdminSignin(db: D1Like, tables: D1AdminSigninTables = {}): Required<AdminSigninStore> {
+  const T = {
+    requests: tables.requests ?? "signin_requests",
+    sessions: tables.sessions ?? "sessions",
+    logins: tables.logins ?? "admin_logins",
+    passkeys: tables.passkeys ?? "admin_passkeys",
+    once: tables.once ?? "admin_once",
+  };
   for (const n of Object.values(T)) if (!NAME.test(n)) throw new Error(`not a table name: ${n}`);
   const COLS = "id, rid, starter, status, expires_at, nonce, issued_at, label, account";
 
@@ -112,6 +122,49 @@ export function createD1AdminSignin(db: D1Like, tables: D1AdminSigninTables = {}
         db.prepare(`DELETE FROM ${T.sessions} WHERE expires_at < ? AND scope = 'admin'`).bind(now),
         db.prepare(`DELETE FROM ${T.logins} WHERE at < ?`).bind(now - ADMIN_LOGIN_KEEP_MS),
       ]);
+      // The used passkey signatures, on their own: a game without the passkeys' tables (they came in 0.12.0) still cleans the rest.
+      try {
+        await db.prepare(`DELETE FROM ${T.once} WHERE until <= ?`).bind(now).run();
+      } catch (e) {
+        if (!noTable(e)) throw e;
+      }
+    },
+    async createSession(s) {
+      await db.prepare(`INSERT INTO ${T.sessions} (id_hash, address, created_at, expires_at, via, scope) VALUES (?, ?, ?, ?, ?, 'admin')`).bind(s.idHash, s.address, s.createdAt, s.expiresAt, s.via).run();
+    },
+    async linkPasskey(owner, address, at): Promise<AdminLinkResult> {
+      // ONE statement holds the limit: the row is written only while the owner has fewer than the limit, and never twice.
+      const res = await db
+        .prepare(`INSERT INTO ${T.passkeys} (owner, address, created_at) SELECT ?, ?, ? WHERE (SELECT COUNT(*) FROM ${T.passkeys} WHERE owner = ?) < ? ON CONFLICT (owner, address) DO NOTHING`)
+        .bind(owner, address, at, owner, ADMIN_PASSKEY_LIMIT)
+        .run();
+      if (changes(res) === 1) return "linked";
+      const had = await db.prepare(`SELECT 1 AS one FROM ${T.passkeys} WHERE owner = ? AND address = ?`).bind(owner, address).first<{ one: number }>();
+      return had ? "exists" : "full";
+    },
+    async unlinkPasskey(owner, address) {
+      // The link, and the passkey's admin sessions with it.
+      const done = await db.batch([
+        db.prepare(`DELETE FROM ${T.passkeys} WHERE owner = ? AND address = ?`).bind(owner, address),
+        db.prepare(`DELETE FROM ${T.sessions} WHERE scope = 'admin' AND via = 'passkey' AND address = ?`).bind(address),
+      ]);
+      return changes(done[0]) > 0;
+    },
+    async passkeys(owner) {
+      const rows = (await db.prepare(`SELECT address, created_at FROM ${T.passkeys} WHERE owner = ? ORDER BY created_at, address`).bind(owner).all<{ address: string; created_at: number }>()).results;
+      return rows.map((r) => ({ address: String(r.address), createdAt: Number(r.created_at) }));
+    },
+    async linked(owner, address) {
+      return (await db.prepare(`SELECT 1 AS one FROM ${T.passkeys} WHERE owner = ? AND address = ?`).bind(owner, address).first<{ one: number }>()) !== null;
+    },
+    async useOnce(key, ttlMs) {
+      const now = Date.now();
+      // A row past its time may be taken again (its signature's window is long over); a live one may not.
+      const res = await db
+        .prepare(`INSERT INTO ${T.once} (key, until) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET until = excluded.until WHERE ${T.once}.until <= ?`)
+        .bind(key, now + ttlMs, now)
+        .run();
+      return changes(res) === 1;
     },
   };
 }

package/src/admin-signin/adapters/firestore.ts

@@ -9,15 +9,18 @@
 //   signin_requests/{key}   { id, way, starter, status, expiresAt, nonce?, issuedAt?, label?, account?, delivered, scope: "admin", deleteAt }
 //   sessions/{idHash}       { address, createdAt, expiresAt, via, scope: "admin", deleteAt }
 //   admin_logins/{id}       { at, country, browser, deleteAt }
-// Times are ms numbers; `deleteAt` is a Date (a Timestamp in Firestore): set a TTL policy on `deleteAt` for each collection. `{key}` is the request's id;
-// `{idHash}` the SHA-256 of "admin:" and the session's token. Every change that reads first is a transaction. Indexes: Firestore's own single-field
-// indexes are enough (`id`, `scope`, `expiresAt`, `at`).
+//   admin_passkeys/{owner}  { owner, passkeys: [{ address, createdAt }] }      (since 0.12.0: the owner's linked passkeys, at most 10; no deleteAt)
+//   admin_once/{key}        { until, deleteAt }                                (since 0.12.0: the passkeys' used signatures)
+// Times are ms numbers; `deleteAt` is a Date (a Timestamp in Firestore): set a TTL policy on `deleteAt` for each collection that has it. `{key}` is the
+// request's id; `{idHash}` the SHA-256 of "admin:" and the session's token. Every change that reads first is a transaction (the owner's passkeys are ONE
+// document, so a link holds the limit in its transaction). Indexes: Firestore's own single-field indexes are enough (`id`, `scope`, `expiresAt`, `at`,
+// `address`, `until`).
 //
 // The admin store for Firestore (`createFirestoreStore`) has no sign-in list and no "Sign out everywhere": give it this sign-in's,
 // `store.recentLogins = signin.recentLogins` and `store.signOutEverywhere = signin.signOutEverywhere`.
 
 import type { AdminLogin } from "../../admin/store.js";
-import { ADMIN_LOGIN_KEEP_MS, ADMIN_WAYS, type AdminSessionRecord, type AdminSigninStore, type AdminWay, type RequestStoreLike, type SigninRequest } from "../types.js";
+import { ADMIN_LOGIN_KEEP_MS, ADMIN_PASSKEY_LIMIT, ADMIN_WAYS, type AdminPasskey, type AdminSessionRecord, type AdminSigninStore, type AdminWay, type RequestStoreLike, type SigninRequest } from "../types.js";
 
 export type AdminSigninDocSnap = { exists: boolean; data(): Record<string, unknown> | undefined };
 export interface AdminSigninDocRef {
@@ -76,10 +79,24 @@ function requestOf(d: Record<string, unknown> | undefined, key: string, way: Adm
   };
 }
 
-export function createFirestoreAdminSignin(db: FirestoreAdminSigninLike, collections: { requests?: string; sessions?: string; logins?: string } = {}): AdminSigninStore {
+/** The links a passkeys document holds: only well-formed ones. */
+function linksOf(d: Record<string, unknown> | undefined): AdminPasskey[] {
+  const list = Array.isArray(d?.passkeys) ? (d.passkeys as unknown[]) : [];
+  return list.flatMap((p) => {
+    const v = p as Record<string, unknown> | null;
+    const address = text(v?.address);
+    return address !== undefined ? [{ address, createdAt: num(v?.createdAt) ?? 0 }] : [];
+  });
+}
+
+export type FirestoreAdminSigninCollections = { requests?: string; sessions?: string; logins?: string; passkeys?: string; once?: string };
+
+export function createFirestoreAdminSignin(db: FirestoreAdminSigninLike, collections: FirestoreAdminSigninCollections = {}): Required<AdminSigninStore> {
   const requestsCol = () => db.collection(collections.requests ?? "signin_requests");
   const sessionsCol = () => db.collection(collections.sessions ?? "sessions");
   const loginsCol = () => db.collection(collections.logins ?? "admin_logins");
+  const passkeysCol = () => db.collection(collections.passkeys ?? "admin_passkeys");
+  const onceCol = () => db.collection(collections.once ?? "admin_once");
 
   const sessionData = (s: AdminSessionRecord) => ({ address: s.address, createdAt: s.createdAt, expiresAt: s.expiresAt, via: s.via, scope: "admin", deleteAt: new Date(s.expiresAt) });
 
@@ -201,7 +218,57 @@ export function createFirestoreAdminSignin(db: FirestoreAdminSigninLike, collect
       const old = (await requestsCol().where("expiresAt", "<", now - 2 * 3_600_000).limit(BATCH).get()).docs.filter((d) => d.data().scope === "admin");
       const ended = (await sessionsCol().where("expiresAt", "<", now).limit(BATCH).get()).docs.filter((d) => d.data().scope === "admin");
       const logins = (await loginsCol().where("at", "<", now - ADMIN_LOGIN_KEEP_MS).limit(BATCH).get()).docs;
-      await deleteAll([...old, ...ended, ...logins]);
+      const used = (await onceCol().where("until", "<", now + 1).limit(BATCH).get()).docs;
+      await deleteAll([...old, ...ended, ...logins, ...used]);
+    },
+    async createSession(session) {
+      const ref = sessionsCol().doc(session.idHash);
+      await db.runTransaction(async (tx) => {
+        if ((await tx.get(ref)).exists) throw new Error("a session with this id exists");
+        tx.set(ref, sessionData(session));
+      });
+    },
+    async linkPasskey(owner, address, at) {
+      const ref = passkeysCol().doc(owner);
+      return db.runTransaction(async (tx) => {
+        const d = (await tx.get(ref)).data();
+        const list = d && d.owner === owner ? linksOf(d) : [];
+        if (list.some((p) => p.address === address)) return "exists" as const;
+        if (list.length >= ADMIN_PASSKEY_LIMIT) return "full" as const;
+        tx.set(ref, { owner, passkeys: [...list, { address, createdAt: at }] });
+        return "linked" as const;
+      });
+    },
+    async unlinkPasskey(owner, address) {
+      const ref = passkeysCol().doc(owner);
+      const had = await db.runTransaction(async (tx) => {
+        const d = (await tx.get(ref)).data();
+        const list = d && d.owner === owner ? linksOf(d) : [];
+        if (!list.some((p) => p.address === address)) return false;
+        tx.set(ref, { owner, passkeys: list.filter((p) => p.address !== address) });
+        return true;
+      });
+      // The passkey's admin sessions end with its link (after it: a session read in between finds no link and is refused anyway).
+      await deleteAll((await sessionsCol().where("address", "==", address).get()).docs.filter((x) => x.data().scope === "admin" && x.data().via === "passkey"));
+      return had;
+    },
+    async passkeys(owner) {
+      const d = (await passkeysCol().doc(owner).get()).data();
+      return d && d.owner === owner ? linksOf(d) : [];
+    },
+    async linked(owner, address) {
+      const d = (await passkeysCol().doc(owner).get()).data();
+      return Boolean(d && d.owner === owner && linksOf(d).some((p) => p.address === address));
+    },
+    async useOnce(key, ttlMs) {
+      const ref = onceCol().doc(key);
+      return db.runTransaction(async (tx) => {
+        const now = Date.now();
+        const d = (await tx.get(ref)).data();
+        if (d && (num(d.until) ?? Infinity) > now) return false;
+        tx.set(ref, { until: now + ttlMs, deleteAt: new Date(now + ttlMs) });
+        return true;
+      });
     },
   };
 }

package/src/admin-signin/conformance.ts

@@ -6,11 +6,12 @@
 //
 // Each case gets a NEW, empty store from `make`. The rules: a request is finished once and delivered once, and a delivery writes its session in the same
 // step; the two wallet apps stay apart; a session lasts until its time; "Sign out everywhere" ends every session and every request not delivered; the
-// sign-in list keeps three things for 30 days. (The whole chain, with the player's sign-in beside it, is `adminSigninConformance` in
+// sign-in list keeps three things for 30 days; and (since 0.12.0) the owner's passkeys: a link is written once, at most 10 for an owner even when many come
+// at once, a removal ends the passkey's sessions, and a used signature counts once. (The whole chain, with the player's sign-in beside it, is `adminSigninConformance` in
 // "@nano133/nanoterra/admin/conformance".)
 
 import type { AdminSessionRecord, AdminSigninStore, SigninRequest } from "./types.js";
-import { ADMIN_LOGIN_KEEP_MS } from "./types.js";
+import { ADMIN_LOGIN_KEEP_MS, ADMIN_PASSKEY_LIMIT } from "./types.js";
 
 export type AdminSigninHarness = {
   store: AdminSigninStore;
@@ -38,9 +39,31 @@ function request(at: number, extra: Partial<SigninRequest> = {}): { key: string;
 }
 const session = (at: number, n: number, via = "wallet"): AdminSessionRecord => ({ idHash: hex(1_000_000 + n + serial++), address: OWNER, createdAt: at, expiresAt: at + 86_400_000, via });
 
-export function adminSigninStoreConformance(make: () => Promise<AdminSigninHarness>): AdminSigninConformanceCase[] {
+export type AdminSigninConformanceOptions = {
+  /**
+   * The owner's passkeys (the store's optional passkey methods). true: the cases run and the store must have them. false: no passkey case. Not set: the
+   * cases are listed, and a store with no `linkPasskey` passes them with nothing to check (a store written for 0.11.0).
+   */
+  passkeys?: boolean;
+};
+
+type PasskeyStore = Required<AdminSigninStore>;
+
+export function adminSigninStoreConformance(make: () => Promise<AdminSigninHarness>, options: AdminSigninConformanceOptions = {}): AdminSigninConformanceCase[] {
   const cases: AdminSigninConformanceCase[] = [];
   const add = (name: string, run: (h: AdminSigninHarness, now: number) => Promise<void>) => cases.push({ name, run: async () => run(await make(), Date.now()) });
+  /** A passkey case: it runs only on a store with the passkey methods (required with `passkeys: true`). */
+  const addPasskey = (name: string, run: (store: PasskeyStore, now: number, h: AdminSigninHarness) => Promise<void>) => {
+    if (options.passkeys === false) return;
+    add(`passkeys: ${name}`, async (h, now) => {
+      const has = ["createSession", "linkPasskey", "unlinkPasskey", "passkeys", "linked", "useOnce"].every((m) => typeof (h.store as unknown as Record<string, unknown>)[m] === "function");
+      if (!has) {
+        check(options.passkeys !== true, "the store has no passkey methods (createSession, linkPasskey, unlinkPasskey, passkeys, linked, useOnce)");
+        return;
+      }
+      await run(h.store as PasskeyStore, now, h);
+    });
+  };
 
   add("a request reads back as it was made, by its key and by its browser id, and only for its own wallet app", async ({ store }, now) => {
     const { key, r } = request(now, { label: "ADMIN of game.test sign-in ABCD-EFGH from US" });
@@ -208,5 +231,78 @@ export function adminSigninStoreConformance(make: () => Promise<AdminSigninHarne
     check((await store.recentLogins(10)).length === 0, "the sign-in row past 30 days went");
   });
 
+  addPasskey("a link is written once and read back exactly, oldest first, for its owner only", async (store, now) => {
+    const a = who("pka");
+    const b = who("pkb");
+    check((await store.passkeys(OWNER)).length === 0, "a new store lists no passkey");
+    check(!(await store.linked(OWNER, a)), "nothing is linked yet");
+    check((await store.linkPasskey(OWNER, a, now - 1000)) === "linked", "the first link");
+    check((await store.linkPasskey(OWNER, b, now)) === "linked", "a second passkey");
+    check((await store.linkPasskey(OWNER, a, now + 5)) === "exists", "the same passkey again is 'exists'");
+    const list = await store.passkeys(OWNER);
+    check(list.length === 2 && list[0].address === a && list[0].createdAt === now - 1000 && list[1].address === b, `the list: ${JSON.stringify(list)}`);
+    check(list.every((p) => Object.keys(p).sort().join() === "address,createdAt"), `a passkey carries only address and createdAt: ${JSON.stringify(list[0])}`);
+    check(await store.linked(OWNER, a), "linked");
+    check(!(await store.linked(who("oth"), a)), "another owner has no link to it");
+    check(!(await store.linked(OWNER.toUpperCase(), a)) && !(await store.linked(OWNER, a.toUpperCase())) && !(await store.linked(` ${OWNER}`, a)), "only the exact texts are linked");
+    check((await store.passkeys(who("oth"))).length === 0, "another owner lists none");
+  });
+
+  addPasskey(`at most ${ADMIN_PASSKEY_LIMIT} for an owner, even when many links come at once; another owner has its own ${ADMIN_PASSKEY_LIMIT}`, async (store, now) => {
+    const many = Array.from({ length: ADMIN_PASSKEY_LIMIT + 4 }, (_, i) => who(`m${i}`));
+    const got = await Promise.all(many.map((a, i) => store.linkPasskey(OWNER, a, now + i)));
+    check(got.filter((r) => r === "linked").length === ADMIN_PASSKEY_LIMIT && got.filter((r) => r === "full").length === 4, `results: ${JSON.stringify(got)}`);
+    check((await store.passkeys(OWNER)).length === ADMIN_PASSKEY_LIMIT, "the list holds the limit");
+    check((await store.linkPasskey(OWNER, who("late"), now)) === "full", "full");
+    const linked = (await store.passkeys(OWNER))[0].address;
+    check((await store.linkPasskey(OWNER, linked, now)) === "exists", "a passkey that is there is 'exists', not 'full'");
+    check((await store.linkPasskey(who("oth"), who("late"), now)) === "linked", "another owner is not full");
+    check(await store.unlinkPasskey(OWNER, linked), "a removal");
+    check((await store.linkPasskey(OWNER, who("late"), now)) === "linked", "a removal makes room for one");
+  });
+
+  addPasskey("a removal ends the link and every admin session of that passkey, and nothing else", async (store, now) => {
+    const a = who("rma");
+    const b = who("rmb");
+    await store.linkPasskey(OWNER, a, now);
+    await store.linkPasskey(OWNER, b, now);
+    const sa = { ...session(now, 60, "passkey"), address: a };
+    const sb = { ...session(now, 61, "passkey"), address: b };
+    const owner = session(now, 62, "wallet");
+    for (const s of [sa, sb, owner]) await store.createSession(s);
+    const read = await store.session(sa.idHash, now);
+    check(read?.address === a && read.via === "passkey" && read.createdAt === now && read.expiresAt === sa.expiresAt, `a passkey session reads back: ${JSON.stringify(read)}`);
+    check(await store.unlinkPasskey(OWNER, a), "the removal says it removed one");
+    check(!(await store.unlinkPasskey(OWNER, a)), "a second removal says false");
+    check(!(await store.linked(OWNER, a)) && (await store.linked(OWNER, b)), "only that link went");
+    check((await store.session(sa.idHash, now)) === null, "the passkey's session ended with its link");
+    check((await store.session(sb.idHash, now)) !== null && (await store.session(owner.idHash, now)) !== null, "the other passkey's session and the wallet's session stay");
+    let threw = false;
+    try {
+      await store.createSession(sb);
+    } catch {
+      threw = true;
+    }
+    check(threw, "a second session with the same hash is refused");
+    check((await store.signOutEverywhere()) === 2, "Sign out everywhere ends the passkey sessions too");
+    check((await store.session(sb.idHash, now)) === null, "and the passkey's session is gone");
+    check(await store.linked(OWNER, b), "Sign out everywhere keeps the links (a removal ends one)");
+  });
+
+  addPasskey("a used signature counts once, even twice at the same moment; after its time, or after clean, it may be used again", async (store) => {
+    const k = hex(31337);
+    check(await store.useOnce(k, 60_000), "the first use");
+    check(!(await store.useOnce(k, 60_000)), "the second use is refused");
+    const k2 = hex(31338);
+    const both = await Promise.all([store.useOnce(k2, 60_000), store.useOnce(k2, 60_000)]);
+    check(both.filter(Boolean).length === 1, `two at once: ${JSON.stringify(both)}`);
+    const k3 = hex(31339);
+    check(await store.useOnce(k3, 1), "a short one");
+    await new Promise((r) => setTimeout(r, 15));
+    check(await store.useOnce(k3, 60_000), "past its time it may be used again");
+    await store.clean(Date.now() + 120_000);
+    check(await store.useOnce(k, 60_000), "clean dropped the used row past its time");
+  });
+
   return cases;
 }

package/src/admin-signin/handler.ts

@@ -10,6 +10,19 @@
 //   POST {base}/check          the browser asks every 2 seconds: { id, way } → { status: "waiting" | "expired" | "elsewhere" | "used" | "not_owner" | "signedin", address? }
 //   POST {base}/signout        ends this browser's admin login only: { ok: true }
 //
+// With `passkeys: true` (since 0.12.0), the owner's linked passkeys (a passkey is only a key to /admin; the money stays in the owner's wallet):
+//
+//   POST {base}/passkey/link   { address, at, signature }: ONLY with a live WALLET admin session of the owner, and the passkey's own signature of
+//                              "Link this passkey to the ADMIN of <host>: sign in as <address> at <ms>": both sides prove their key → { ok, passkeys }
+//   POST {base}/passkey/unlink { address }: only with a live wallet admin session of the owner; the passkey's admin sessions end too → { ok, removed, passkeys }
+//   POST {base}/passkeys       the list, for any session the guard accepts → { passkeys, limit, via, canChange, you }
+//   POST {base}/passkey        { address, at, signature, turnstile? }: the passkey's signature of "ADMIN of <host>: sign in as <address> at <ms>" (never
+//                              the host alone, which a player's passkey signs), refused unless the passkey is linked to the owner → a NEW admin session
+//                              { via: "passkey" } of one day and the admin cookie
+//
+// Each passkey signature counts once (the admin's own table) and within 5 minutes. A passkey session opens /admin only while its link to the CURRENT owner
+// exists: `session(request)` reads the link on every request, so a removed link or a new owner address ends it at the next request.
+//
 // `base` is "/api/admin-signin" (ADMIN_SIGNIN_BASE). Berry Wallet and Nautilus sign a text that names the ADMIN: Berry signs the page `${origin}/admin`
 // with NO query (Berry refused "/admin?from=US" with "Sign-in requires a public HTTPS website", device test 2026-10-27), Nautilus signs the label "ADMIN of
 // <host> sign-in ABCD-EFGH from <country>" and shows "Sign in to the ADMIN of <host>. Started <time> UTC from <country>. If you did not start this, do not
@@ -29,6 +42,7 @@ import {
   answerNanoSignin,
   answerNautilus,
   checkNanchat,
+  checkSignatureSignin,
   checkNanoSignin,
   checkNautilus,
   nanchatNonce,
@@ -37,6 +51,7 @@ import {
   nanoSigninRefusal,
   nautilusReply,
   readNanoSignin,
+  SigninError,
   startNanchat,
   startNanoSignin,
   startNautilus,
@@ -47,13 +62,15 @@ import {
   type NautilusOptions,
   type RequestCheck,
 } from "@nano133/signin";
-import { ADMIN_SESSION_MS } from "../admin/guard.js";
+import { ADMIN_SESSION_MS, adminAccess } from "../admin/guard.js";
 import { fail, json, memoryLimiter, readLimited, sameOrigin } from "../admin/http.js";
 import type { AdminLogin } from "../admin/store.js";
 import { countryOf, shortBrowser } from "./browser.js";
 import {
   ADMIN_DELIVER_MS,
+  ADMIN_ONCE_MS,
   ADMIN_PAGE,
+  ADMIN_PASSKEY_LIMIT,
   ADMIN_REQUEST_MS,
   ADMIN_SIGNIN_BASE,
   ADMIN_SIGNIN_LIMITS,
@@ -61,6 +78,8 @@ import {
   ADMIN_WAYS,
   NANCHAT_REFUSAL,
   TOKEN_PATTERN,
+  adminLinkDomain,
+  adminPasskeyDomain,
   type AdminSigninSession,
   type AdminSigninStore,
   type AdminWay,
@@ -89,6 +108,13 @@ export type AdminSigninOptions = {
    * game sign-in. Turn it on only when the owner accepts that; give the panel the same `nanchat: true`.
    */
   nanchat?: boolean;
+  /**
+   * The owner's linked passkeys (since 0.12.0). Default false: no passkey route, and no passkey session opens /admin. With true, a live WALLET admin
+   * session of the owner may link up to 10 passkeys (each proves its key by signing), and a linked passkey's signature makes an admin login while its link to
+   * the current owner exists. The store needs the passkey methods (the package's stores have them; D1 needs the two tables at the end of d1.sql). Give the
+   * panel the same `passkeys: true` and the game's frozen passkey `scheme`.
+   */
+  passkeys?: boolean;
   /** The cookies' names. Default { session: "admin", starter: "starter-admin" } (the starter's). On https they get the __Host- prefix. */
   cookies?: { session?: string; starter?: string };
   /** The shared limiter of the starts: false means "too many". Default: a fixed window in this process's memory. */
@@ -156,6 +182,14 @@ function cookieHeader(req: Request, name: string, value: string, maxAgeSec: numb
 /** A cookie's value: on https only the `__Host-` name (a sibling subdomain can set the plain one; it cannot set a `__Host-` one). */
 const readCookie = (req: Request, name: string) => cookieValue(req, isHttps(req) ? `__Host-${name}` : name);
 
+/** What the owner reads for a refused passkey signature. */
+function passkeyWords(e: SigninError): string {
+  if (e.status === 409) return "That passkey signature was used already. Try again.";
+  if (e.status === 401) return "The passkey's signature does not match. Try again.";
+  if (/too old/.test(e.message)) return "That signature is too old. Check the clock of this device, then try again.";
+  return "That passkey signature could not be read. Try again.";
+}
+
 /** The limiters live at module level: a Worker makes the sign-in for each request, and a limiter made inside it would forget every call. */
 const fallbackLimit = memoryLimiter();
 const memory = memoryLimiter();
@@ -175,6 +209,13 @@ export function createAdminSignin(options: AdminSigninOptions): AdminSignin {
   const limit = options.limit ?? fallbackLimit;
   const siteAddress = owner && validAddress(owner) ? owner : EXAMPLE_ADDRESS;
   const nanchatOn = options.nanchat === true;
+  const passkeysOn = options.passkeys === true;
+  const pk = store as Required<AdminSigninStore>;
+  if (passkeysOn) {
+    for (const m of ["createSession", "linkPasskey", "unlinkPasskey", "passkeys", "linked", "useOnce"] as const) {
+      if (typeof store[m] !== "function") throw new Error(`passkeys: true needs a store with ${m}() (the package's stores have it)`);
+    }
+  }
   const report = (e: unknown) => {
     try {
       options.onError?.(e);
@@ -352,8 +393,87 @@ export function createAdminSignin(options: AdminSigninOptions): AdminSignin {
     if (!token || !TOKEN_PATTERN.test(token)) return null;
     // The scope is in the store's row (the adapter reads only admin rows) as well as in the hash: the two scopes stay apart in two ways.
     const s = await store.session(await adminKey(token), at);
-    // Only the two words a login can carry are read; any other is "unknown", never a wallet login (a fail-open map would turn a stray value into a login that opens /admin).
-    return s ? { address: s.address, createdAt: s.createdAt, via: s.via === "wallet" || s.via === "nanoterra" ? s.via : "unknown" } : null;
+    if (!s) return null;
+    if (s.via === "passkey") {
+      // A passkey's login counts only while its link to the CURRENT owner exists: read now, on every request. A removed link, a new owner address, or the
+      // passkeys turned off: no session at all (the page asks for a sign-in). `linkedTo` is set here only, and only after this check.
+      if (!passkeysOn || typeof owner !== "string" || !validAddress(owner)) return null;
+      return (await pk.linked(owner, s.address)) ? { address: s.address, createdAt: s.createdAt, via: "passkey", linkedTo: owner } : null;
+    }
+    // Only the words a login can carry are read; any other is "unknown", never a wallet login (a fail-open map would turn a stray value into a login that opens /admin).
+    return { address: s.address, createdAt: s.createdAt, via: s.via === "wallet" || s.via === "nanoterra" ? s.via : "unknown" };
+  }
+
+  // ---- the owner's passkeys ----
+
+  /** The host every passkey text names: `domain`, or this request's host. */
+  const hostOf = (req: Request) => options.domain ?? new URL(req.url).host;
+
+  /** The session the guard accepts now, or the refusal to send. `wallet`: only a wallet session of the owner (a link and a removal). */
+  async function ownerSession(req: Request, at: number, wallet: boolean): Promise<{ ok: true; session: AdminSigninSession } | { ok: false; res: Response }> {
+    const session = await sessionOf(req, at);
+    const access = adminAccess({ owner, session, now: at });
+    if (!access.ok) return { ok: false, res: fail(access.status, access.error, access.reason ? { reason: access.reason } : {}) };
+    if (wallet && session!.via !== "wallet") return { ok: false, res: fail(403, "Only a wallet sign-in can add or remove a passkey. Sign in with your wallet.", { reason: "wallet_only" }) };
+    return { ok: true, session: session! };
+  }
+
+  /** A passkey's signature of `domain`'s text, checked once: its address, or the refusal to send. */
+  async function passkeySignature(b: Record<string, unknown>, domain: string, label: string, at: number): Promise<{ ok: true; address: string } | { ok: false; res: Response }> {
+    try {
+      const address = await checkSignatureSignin(
+        { domain, useOnce: (k, ttl) => pk.useOnce(k, Math.max(ttl, ADMIN_ONCE_MS)), now: () => at, onceLabel: label },
+        { address: b.address as string, at: Number(b.at), signature: b.signature as string },
+      );
+      return { ok: true, address };
+    } catch (e) {
+      if (e instanceof SigninError) return { ok: false, res: fail(e.status, passkeyWords(e)) };
+      throw e;
+    }
+  }
+
+  async function passkeyList(session: AdminSigninSession): Promise<Record<string, unknown>> {
+    return { passkeys: await pk.passkeys(owner!), limit: ADMIN_PASSKEY_LIMIT, via: session.via, canChange: session.via === "wallet", you: session.address };
+  }
+
+  async function link(req: Request, b: Record<string, unknown>, at: number): Promise<Response> {
+    const o = await ownerSession(req, at, true);
+    if (!o.ok) return o.res;
+    if (!(await limit(`signin|${await visitorOf(req)}`, ADMIN_SIGNIN_LIMITS.signin.limit, ADMIN_SIGNIN_LIMITS.signin.windowMs, at))) return fail(429, "Too many tries. Wait a few minutes.");
+    const sig = await passkeySignature(b, adminLinkDomain(hostOf(req)), "nanoterra admin passkey link v1", at);
+    if (!sig.ok) return sig.res;
+    const r = await pk.linkPasskey(owner!, sig.address, at);
+    if (r === "full") return fail(409, `You have ${ADMIN_PASSKEY_LIMIT} passkeys. Remove one first.`, { reason: "full" });
+    if (r === "exists") return fail(409, "This passkey is linked already.", { reason: "exists" });
+    return json({ ok: true, address: sig.address, ...(await passkeyList(o.session)) });
+  }
+
+  async function unlink(req: Request, b: Record<string, unknown>, at: number): Promise<Response> {
+    const o = await ownerSession(req, at, true);
+    if (!o.ok) return o.res;
+    if (typeof b.address !== "string" || !validAddress(b.address)) return fail(400, "That is not a passkey's address.");
+    const removed = await pk.unlinkPasskey(owner!, b.address);
+    return json({ ok: true, removed, ...(await passkeyList(o.session)) });
+  }
+
+  async function list(req: Request, at: number): Promise<Response> {
+    const o = await ownerSession(req, at, false);
+    if (!o.ok) return o.res;
+    return json(await passkeyList(o.session));
+  }
+
+  async function passkeySignin(req: Request, b: Record<string, unknown>, at: number): Promise<Response> {
+    if (!(await limit(`signin|${await visitorOf(req)}`, ADMIN_SIGNIN_LIMITS.signin.limit, ADMIN_SIGNIN_LIMITS.signin.windowMs, at))) return fail(429, "Too many sign-ins. Wait a few minutes.");
+    if (!(await person(b.turnstile, req))) return fail(403, "The person check failed. Try again.");
+    if (typeof owner !== "string" || !validAddress(owner)) return fail(403, "Set the game's own Nano address first. Only that address can open this page.", { reason: "no_address" });
+    const sig = await passkeySignature(b, adminPasskeyDomain(hostOf(req)), "nanoterra admin passkey signin v1", at);
+    if (!sig.ok) return sig.res;
+    // The signature is checked first, so a stranger learns nothing of which passkeys are linked.
+    if (!(await pk.linked(owner, sig.address))) return fail(403, "This passkey is not linked to the game's address. Sign in with your wallet, then add this passkey in Settings.", { reason: "not_linked" });
+    const token = randomHex(32);
+    await pk.createSession({ idHash: await adminKey(token), address: sig.address, createdAt: at, expiresAt: at + ADMIN_SESSION_MS, via: "passkey" });
+    await store.recordLogin({ at, country: countryOf(req), browser: shortBrowser(req.headers.get("User-Agent")) });
+    return json({ status: "signedin", address: sig.address, linkedTo: owner }, 200, { "Set-Cookie": cookieHeader(req, sessionName, token, ADMIN_SESSION_MS / 1000) });
   }
 
   async function signOut(req: Request): Promise<string> {
@@ -366,7 +486,9 @@ export function createAdminSignin(options: AdminSigninOptions): AdminSignin {
     const url = new URL(req.url);
     const path = url.pathname;
     const berryId = path.startsWith(`${base}/nano/`) ? /^[0-9a-f]{32}$/.exec(path.slice(base.length + 6))?.[0] : undefined;
-    const mine = berryId !== undefined || [`${base}/start`, `${base}/check`, `${base}/signout`, `${base}/nautilus`].includes(path) || (nanchatOn && path === `${base}/nanchat`);
+    const passkeyPaths = [`${base}/passkey`, `${base}/passkey/link`, `${base}/passkey/unlink`, `${base}/passkeys`];
+    const mine =
+      berryId !== undefined || [`${base}/start`, `${base}/check`, `${base}/signout`, `${base}/nautilus`].includes(path) || (nanchatOn && path === `${base}/nanchat`) || (passkeysOn && passkeyPaths.includes(path));
     if (!mine) return null;
     try {
       if (options.domain && url.host !== options.domain) return fail(403, `This sign-in belongs to ${options.domain}.`);
@@ -393,12 +515,17 @@ export function createAdminSignin(options: AdminSigninOptions): AdminSignin {
       // The browser's own calls: a POST from the game's own page.
       if (req.method !== "POST") return fail(405, "Not allowed.", {}, { Allow: "POST" });
       if (path === `${base}/check` && !memory(`${base}|poll|${ip}`, ADMIN_SIGNIN_LIMITS.poll.limit, ADMIN_SIGNIN_LIMITS.poll.windowMs, at)) return fail(429, "Too many requests. Wait a minute.");
+      if (passkeyPaths.includes(path) && path !== `${base}/passkey` && !memory(`${base}|passkeys|${ip}`, ADMIN_SIGNIN_LIMITS.passkeys.limit, ADMIN_SIGNIN_LIMITS.passkeys.windowMs, at)) return fail(429, "Too many requests. Wait a minute.");
       if (!sameOrigin(req)) return fail(403, "This call must come from the game's own page.");
       // A sign-out reads no body.
       if (path === `${base}/signout`) return json({ ok: true }, 200, { "Set-Cookie": await signOut(req) });
       const b = await body(req);
       if (!b) return fail(400, "That request is not readable.");
       if (path === `${base}/check`) return await check(req, b, at);
+      if (path === `${base}/passkey`) return await passkeySignin(req, b, at);
+      if (path === `${base}/passkey/link`) return await link(req, b, at);
+      if (path === `${base}/passkey/unlink`) return await unlink(req, b, at);
+      if (path === `${base}/passkeys`) return await list(req, at);
       return await start(req, b, at);
     } catch (e) {
       report(e);

package/src/admin-signin/index.ts

@@ -1,5 +1,6 @@
 // "@nano133/nanoterra/admin-signin": the ADMIN's sign-in of a game (/admin), on ONE fixed route, "/api/admin-signin", in every game. Berry Wallet or
-// Nautilus signs a text that names the ADMIN; NanChat is off unless the game turns it on (its text cannot name the admin); no passkey. The game starter's
+// Nautilus signs a text that names the ADMIN; NanChat is off unless the game turns it on (its text cannot name the admin); the owner's linked passkeys
+// only with `passkeys: true` (since 0.12.0; a wallet session of the owner links them, each with its own signature). The game starter's
 // admin sign-in, moved into the package with every check and every signed text unchanged. The checks are @nano133/signin's (an optional peer: install it
 // with this package).
 //
@@ -17,13 +18,17 @@ export { countryOf, shortBrowser } from "./browser.js";
 export {
   ADMIN_DELIVER_MS,
   ADMIN_LOGIN_KEEP_MS,
+  ADMIN_ONCE_MS,
   ADMIN_PAGE,
+  ADMIN_PASSKEY_LIMIT,
   ADMIN_REQUEST_MS,
   ADMIN_SIGNIN_BASE,
   ADMIN_SIGNIN_LIMITS,
   ADMIN_STARTER_MAX_AGE_S,
   ADMIN_WAYS,
   NANCHAT_REFUSAL,
+  adminLinkDomain,
+  adminPasskeyDomain,
 } from "./types.js";
-export type { AdminSessionRecord, AdminSigninSession, AdminSigninStore, AdminWay, RequestStoreLike, SigninRequest } from "./types.js";
+export type { AdminLinkResult, AdminPasskey, AdminSessionRecord, AdminSigninSession, AdminSigninStore, AdminWay, RequestStoreLike, SigninRequest } from "./types.js";
 export { ADMIN_SESSION_MS } from "../admin/guard.js";