Sign in with Nano

// The browser half of "Sign in with Nano": a purse, and the signature that signs a person in.
// From the nano133.com guide "Sign in with Nano". MIT license.
// One package (npm install nanocurrency-web). It needs no Node module, so a bundler can put it in your page.
// Use it in the browser. If you run it on a server, never let a seed leave the person's device.
//
// A purse is account 0 of a seed. The seed stays in the browser. The server never gets it.

import nano from "nanocurrency-web";

const { wallet, tools } = nano;

/** Step 1. The text that is signed. It names your domain, the account and the time (in ms). */
export const signinMessage = (domain, address, at) => `${domain}: sign in as ${address} at ${at}`;

const hexOf = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");

/** The address of a seed's account 0. */
export const purseAddress = (seed) => wallet.fromLegacySeed(seed).accounts[0].address;

/** Step 3. Sign a text with account 0 of the seed. The signature is over the hex of the text's UTF-8 bytes. */
export function signText(seed, text) {
  const account = wallet.fromLegacySeed(seed).accounts[0];
  return tools.sign(account.privateKey, hexOf(new TextEncoder().encode(text)));
}

/** Step 3. What the browser posts to sign in: { address, at, signature }. */
export function signinBody(domain, seed, at = Date.now()) {
  const address = purseAddress(seed);
  return { address, at, signature: signText(seed, signinMessage(domain, address, at)) };
}

// ---- Step 2. A seed from a passkey ----------------------------------------------------------------------------
// A passkey gives the page 32 secret bytes (its PRF answer). They become the seed of the purse. The server has no
// part in this: it keeps no passkey and checks no passkey. The proof of the account is the signature of step 3.
//
// THE SCHEME IS FROZEN. A person's account, and any XNO in it, lies at the address that these exact texts give.
// Choose them one time, test them with fixed vectors, and never edit one character. A new scheme is a new
// versionByte with new texts, never an edit of the old ones. Each domain makes its own account for a person.

/** The bytes the page asks the passkey to evaluate. */
export const prfInput = (scheme) => new TextEncoder().encode(scheme.input);

/**
 * The passkey's answer as 32 bytes, or null. It is strict on purpose: only a buffer or a list of exactly 32 bytes, and
 * never 32 equal bytes (a faulty provider that gives a blank answer would give everyone one purse).
 */
export function prfBuffer(value) {
  if (value === null || typeof value !== "object") return null;
  let bytes;
  if (ArrayBuffer.isView(value)) bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
  else if (value instanceof ArrayBuffer) bytes = new Uint8Array(value);
  else if (Array.isArray(value) && value.length === 32 && value.every((n, i) => Object.hasOwn(value, i) && Number.isInteger(n) && n >= 0 && n <= 255 && !Object.is(n, -0))) bytes = Uint8Array.from(value);
  else return null;
  if (bytes.length !== 32 || bytes.every((b) => b === bytes[0])) return null;
  return Uint8Array.from(bytes);
}

/** The purse's seed (64 upper-case hex characters) from a passkey's PRF answer. HKDF-SHA-256 under your frozen scheme. */
export async function seedFromPrf(prf, scheme) {
  const ikm = prfBuffer(prf);
  if (!ikm) throw new Error("the passkey gave no usable answer");
  const key = await globalThis.crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
  const utf8 = (s) => new TextEncoder().encode(s);
  const bits = await globalThis.crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: utf8(scheme.salt), info: utf8(scheme.info) }, key, 256);
  return hexOf(new Uint8Array(bits)).toUpperCase();
}

/** An example scheme for the domain example.com. Write your own, once, with your own domain. Never change it afterwards. */
export const EXAMPLE_SCHEME = { input: "example.com purse v1", salt: "example.com", info: "example.com purse seed v1", versionByte: 1 };

// The server half of "Sign in with Nano": check a signature, count it once, and make a session.
// From the nano133.com guide "Sign in with Nano". MIT license.
// Node.js 20 or newer, two packages (npm install nanocurrency-web @noble/curves). It needs no node and no Nano.
// Your server holds no key and no seed. It checks a signature that the person's browser made (purse.mjs).
//
//   node signin.mjs message <domain> <address> <time in ms>
//       prints the text that a person signs.
//
//   PURSE_SEED=<64 hex characters> node signin.mjs sign <domain> [time in ms]
//       what the browser posts: { address, at, signature }. The seed is a throwaway: it makes a test purse.
//
//   node signin.mjs check <domain> <folder> '<the posted JSON>'
//       checks it as the server does, counts it once, makes a session, and prints who signed in.
//       The folder holds the demo's records: one file for each sign-in, one for each session.
//
//   node signin.mjs whois <folder> '<the Cookie header>'
//       prints who a session cookie belongs to.
//
//   node signin.mjs passkey-address <32 byte values, 0 to 255, with commas>
//       the address that a passkey's answer gives under the example scheme of purse.mjs (it prints no seed).
//
//   node signin.mjs origin <domain> '<Origin header or ->' '<Sec-Fetch-Site header or ->'
//       says whether a request that changes something comes from your own pages.
//
// In a shop, the records are rows in your database (steps 5 and 6), never files.

import { createHash, randomBytes } from "node:crypto";
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
import nano from "nanocurrency-web";
import { ed25519 } from "@noble/curves/ed25519.js";
import { EXAMPLE_SCHEME, purseAddress, seedFromPrf, signinBody, signinMessage } from "./purse.mjs";

const { tools } = nano;

const WINDOW_MS = 5 * 60_000; // a sign-in is good for 5 minutes, before or after the time it names
const ONCE_LABEL = "example.com sign-in once v1"; // your own label; never change it
const SESSION_DAYS = 30;
const COOKIE = "session";

/** A refusal. `status` is the HTTP status to answer with. */
export class SigninError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

// ---- Step 4. Check the signature, strictly ----------------------------------------------------------------------

const ADDRESS = /^nano_[13][13456789abcdefghijkmnopqrstuwxyz]{59}$/;
const SIGNATURE = /^[0-9A-F]{128}$/i;
/** The order of the Ed25519 group: the second half of a signature must be below it. */
const L = 2n ** 252n + 27742317777372353535851937790883648493n;
const littleEndian = (hex) => BigInt(`0x${Buffer.from(hex, "hex").reverse().toString("hex") || "0"}`);

/** A whole address: its shape AND its checksum (the last 8 characters). */
export const validAddress = (a) => typeof a === "string" && ADDRESS.test(a) && tools.validateAddress(a);

/** A few public keys have a small order: forgeries exist for them, and nobody holds a key for them. The burn address is one. */
function strongKey(publicKey) {
  try {
    return !ed25519.Point.fromHex(publicKey.toLowerCase()).isSmallOrder();
  } catch {
    return false; // not a point on the curve at all
  }
}

/** Does this account's key sign this text? It answers a reason when not, and null when it does. */
export function whyNotSigned(address, text, signature) {
  const publicKey = tools.addressToPublicKey(address);
  if (!strongKey(publicKey)) return "this account's key is not allowed";
  // The second half of a signature has one right form. A second form of the same signature would count as a new sign-in.
  if (littleEndian(signature.slice(64)) >= L) return "the signature is in a form that is not allowed";
  return tools.verify(publicKey, signature, Buffer.from(text, "utf8").toString("hex")) ? null : "the signature does not match";
}

// ---- Step 5. Count each sign-in once ----------------------------------------------------------------------------

/** The key of one signed text. Not the signature's bytes: one signature can have two forms. */
export const onceKey = (text) => createHash("sha256").update(`${ONCE_LABEL}|${text}`).digest("hex");

/**
 * Records a key and answers false when it was already there. In a database this is one row with a unique key.
 * Here a file is made with the flag "wx", which fails when it exists: the same guarantee, made by the file system.
 */
export function useOnce(folder, key, address) {
  mkdirSync(join(folder, "once"), { recursive: true });
  try {
    writeFileSync(join(folder, "once", key), JSON.stringify({ address, at: Date.now() }), { flag: "wx" });
    return true;
  } catch (e) {
    if (e.code === "EEXIST") return false;
    throw e;
  }
}

/** Steps 4 and 5. Answers the address that signed in, or throws a SigninError. */
export function checkSignin({ domain, folder, now = Date.now() }, body) {
  if (!body || typeof body !== "object") throw new SigninError(400, "send { address, at, signature }");
  const { address, at, signature } = body;
  if (!validAddress(address)) throw new SigninError(400, "that is not a whole Nano address");
  if (!Number.isFinite(at) || Math.abs(now - at) > WINDOW_MS) throw new SigninError(400, "that sign-in is too old; try again");
  if (typeof signature !== "string" || !SIGNATURE.test(signature)) throw new SigninError(400, "that is not a signature");
  const text = signinMessage(domain, address, at);
  const why = whyNotSigned(address, text, signature);
  if (why) throw new SigninError(401, why);
  if (!useOnce(folder, onceKey(text), address)) throw new SigninError(409, "that sign-in was already used");
  return address;
}

// ---- Step 6. Make the session -----------------------------------------------------------------------------------

const sha = (s) => createHash("sha256").update(s).digest("hex");

/** A new session for an account: a random token for the cookie, and only its hash on the server. */
export function newSession(folder, address, now = Date.now()) {
  const token = randomBytes(32).toString("hex"); // a new one at every sign-in, never one that the browser sent
  mkdirSync(join(folder, "sessions"), { recursive: true });
  writeFileSync(join(folder, "sessions", sha(token)), JSON.stringify({ address, expiresAt: now + SESSION_DAYS * 86_400_000 }));
  const maxAge = SESSION_DAYS * 86_400;
  return { token, cookie: `${COOKIE}=${token}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}` };
}

/** Who a Cookie header belongs to, or null. The only way server code learns who is signed in. */
export function signedIn(folder, cookieHeader, now = Date.now()) {
  const token = String(cookieHeader ?? "").split(";").map((c) => c.trim()).find((c) => c.startsWith(`${COOKIE}=`))?.slice(COOKIE.length + 1);
  if (!token || !/^[0-9a-f]{64}$/.test(token)) return null;
  try {
    const row = JSON.parse(readFileSync(join(folder, "sessions", sha(token)), "utf8"));
    return row.expiresAt > now ? row.address : null;
  } catch {
    return null;
  }
}

/**
 * Refuses a request that another site's page sent (login CSRF: a page elsewhere signing a visitor's browser in to
 * someone else's account). A browser marks such a request with Sec-Fetch-Site and Origin. A request with neither
 * header comes from a server or an old client, which cannot carry a visitor's cookie for another site.
 */
export function sameOrigin({ domain, origin = null, secFetchSite = null }) {
  if (secFetchSite !== null && secFetchSite !== "same-origin" && secFetchSite !== "none") return false; // "same-site" too
  if (origin !== null && origin !== `https://${domain}`) return false; // "null" comes from sandboxed frames: never yours
  return true;
}

// ---- The command line -------------------------------------------------------------------------------------------

async function main(args) {
  const [command, ...rest] = args;
  if (command === "message") {
    const [domain, address, at] = rest;
    console.log(signinMessage(domain, address, Number(at)));
  } else if (command === "sign") {
    const [domain, at] = rest;
    if (!/^[0-9A-F]{64}$/i.test(process.env.PURSE_SEED ?? "")) throw new Error("Set PURSE_SEED to a throwaway seed: 64 hex characters (openssl rand -hex 32).");
    console.log(JSON.stringify(signinBody(domain, process.env.PURSE_SEED, at ? Number(at) : Date.now())));
  } else if (command === "check") {
    const [domain, folder, json] = rest;
    const address = checkSignin({ domain, folder }, JSON.parse(json));
    const { cookie } = newSession(folder, address);
    console.log(`signed in as ${address}`);
    console.log(`Set-Cookie: ${cookie}`);
  } else if (command === "passkey-address") {
    // The address that a passkey's 32 bytes give under the example scheme. It prints no seed.
    console.log(purseAddress(await seedFromPrf(rest[0].split(",").map(Number), EXAMPLE_SCHEME)));
  } else if (command === "whois") {
    const [folder, cookie] = rest;
    console.log(signedIn(folder, cookie) ?? "nobody");
  } else if (command === "origin") {
    const [domain, origin, site] = rest;
    console.log(sameOrigin({ domain, origin: origin === "-" ? null : origin, secFetchSite: site === "-" ? null : site }) ? "same site" : "refused");
  } else {
    throw new Error("Commands: message, sign, check, whois, origin, passkey-address. Read the top of this file.");
  }
}

// Run the command line only when this file is started by itself, not when your server imports it.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  try {
    await main(process.argv.slice(2));
  } catch (e) {
    console.error(e instanceof SigninError ? `refused (${e.status}): ${e.message}` : (e?.message ?? e));
    process.exit(1);
  }
}