@marver-design/marver 0.10.2 → 0.11.0

package/dist/marver-id-B8-3WiHk.mjs

@@ -0,0 +1,411 @@
+import { createHash, createVerify, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/server/marver-id.ts
+/**
+* Marver ID - the canvas half of the protocol.
+*
+* A canvas never trusts a token because it looks well-formed. The sequence is:
+*
+*   1. mint()             - the canvas invents a nonce and remembers it, bound
+*                           to this browser and this exact origin.
+*   2. the TAB goes to id.marver.design/authorize and comes back to
+*      /__mv/id/finish with the assertion in the URL fragment. One tab, one
+*      redirect each way - no popup and no postMessage, because Google serves
+*      COOP: same-origin and severs window.opener permanently. See
+*      marver-id-gate.ts for the full reasoning.
+*   3. verifyAssertion()  - the canvas SERVER checks every claim against the
+*                           published keys, then consumes the transaction.
+*
+* Step 3 is the one that matters. `aud` must equal this canvas's own origin,
+* so an assertion captured on an attacker's site is inert here; the nonce must
+* match a transaction we actually issued, so a token cannot be injected from
+* nowhere; and the transaction is single-use, so it cannot be replayed even
+* within its short life.
+*
+* Everything here is dependency-free and runs in the OSS canvas, because every
+* self-hosted deployment needs to do this for itself. Nothing phones home
+* except the periodic fetch of public keys.
+*/
+/**
+* How long a sign-in may take, start to finish.
+*
+* Was five minutes, which quietly assumed the identity service answers
+* instantly. It does not: a sign-in there can mean waiting for an emailed code,
+* and mail is store-and-forward - a first-time sender can be greylisted and
+* deferred for minutes before the message is even accepted. Somebody who went to
+* find their code and came back to "unknown or spent nonce" did nothing wrong.
+*
+* Fifteen minutes covers a slow round trip with room to spare, and costs little:
+* the nonce is single-use, bound to one browser and one origin, and useless
+* without a signature from the issuer. The browser handle below is set to match,
+* so the two halves of the same deadline expire together rather than leaving a
+* window where the transaction lives but the handle that owns it is gone.
+*/
+const TRANSACTION_TTL_MS = 9e5;
+/** Servers drift; allow a little, but not enough to matter. */
+const CLOCK_TOLERANCE_S = 30;
+/** Public keys are cached; rotation publishes a key well before it signs. */
+const JWKS_TTL_MS = 6e5;
+/** A ceiling on token size - nothing legitimate is close to this. */
+const MAX_TOKEN_BYTES = 8192;
+/**
+* The transaction store.
+*
+* In memory on purpose: a transaction is short-lived, and a canvas that
+* restarts mid-sign-in should simply ask the person to try again rather than
+* persist half-finished authentications to disk.
+*/
+/** A ceiling on live transactions - /start is unauthenticated by necessity. */
+const MAX_TRANSACTIONS = 1e4;
+/** How often the expiry sweep is allowed to walk the whole map. */
+const SWEEP_INTERVAL_MS = 1e4;
+var TransactionStore = class {
+	items = /* @__PURE__ */ new Map();
+	/** nonce currently held by each browser, so one browser holds one slot. */
+	byBrowser = /* @__PURE__ */ new Map();
+	lastSweep = 0;
+	/** Invent a nonce for a sign-in attempt from this browser to this origin. */
+	mint(origin, browser, next) {
+		this.sweep();
+		const held = this.byBrowser.get(browser);
+		if (held) {
+			const live = this.items.get(held);
+			if (live && live.exp >= Date.now() && live.origin === origin) {
+				if (next) live.next = next;
+				live.exp = Date.now() + TRANSACTION_TTL_MS;
+				return live;
+			}
+			if (held) this.items.delete(held);
+		}
+		if (this.items.size >= MAX_TRANSACTIONS) {
+			const oldest = this.items.keys().next().value;
+			if (oldest) {
+				const victim = this.items.get(oldest);
+				this.items.delete(oldest);
+				if (victim && this.byBrowser.get(victim.browser) === oldest) this.byBrowser.delete(victim.browser);
+			}
+		}
+		const tx = {
+			nonce: randomBytes(32).toString("base64url"),
+			origin,
+			browser,
+			exp: Date.now() + TRANSACTION_TTL_MS,
+			...next ? { next } : {}
+		};
+		this.items.set(tx.nonce, tx);
+		this.byBrowser.set(browser, tx.nonce);
+		return tx;
+	}
+	/**
+	* Take a transaction, if it is real, unexpired, and belongs to this browser.
+	*
+	* The browser check happens BEFORE the delete, and that ordering is the whole
+	* point: a stranger who somehow learns a nonce must not be able to destroy
+	* somebody else's live sign-in by presenting it. Only the browser that owns a
+	* transaction can spend it - for anyone else it is inert, and left alone.
+	*
+	* Once ownership is proved the transaction is removed unconditionally, so the
+	* legitimate browser gets exactly one attempt and a forged signature cannot be
+	* ground against a live nonce.
+	*/
+	consume(nonce, browser) {
+		const tx = this.items.get(nonce);
+		if (!tx) return null;
+		if (!constantTimeEqual(tx.browser, browser)) return null;
+		this.items.delete(nonce);
+		if (this.byBrowser.get(tx.browser) === nonce) this.byBrowser.delete(tx.browser);
+		if (tx.exp < Date.now()) return null;
+		return tx;
+	}
+	/**
+	* Drop what has expired.
+	*
+	* Throttled, because this walks the whole map and it is reached from an
+	* unauthenticated endpoint - running it on every mint turns /start into a
+	* quadratic cost the caller controls. Expiry is still enforced exactly, in
+	* consume(); this only reclaims memory, and ten seconds late is fine.
+	*/
+	sweep() {
+		const now = Date.now();
+		if (now - this.lastSweep < SWEEP_INTERVAL_MS) return;
+		this.lastSweep = now;
+		for (const [k, v] of this.items) if (v.exp < now) {
+			this.items.delete(k);
+			if (this.byBrowser.get(v.browser) === k) this.byBrowser.delete(v.browser);
+		}
+	}
+	get size() {
+		return this.items.size;
+	}
+};
+/**
+* Reduce a configured issuer to a bare origin, or refuse it.
+*
+* The issuer is the trust root: its published keys decide who may open this
+* canvas. Taken as a raw string it is far too easy to configure into something
+* that is not a trust root at all - `http://` invites anyone on the path
+* between here and there to serve their own keys, and a value carrying a path,
+* a query or embedded credentials means the URL the operator read is not the
+* URL that gets fetched.
+*
+* Loopback over http is allowed because that is how the protocol is developed
+* against a local identity service, and there is no network to sit on.
+*
+* Returns null when the value cannot be trusted, so the caller can refuse to
+* start rather than run with a trust root nobody vetted.
+*/
+function normalizeIssuer(raw) {
+	if (!raw) return null;
+	let url;
+	try {
+		url = new URL(raw.trim());
+	} catch {
+		return null;
+	}
+	const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) return null;
+	if (url.username || url.password) return null;
+	if (url.pathname !== "/" || url.search || url.hash) return null;
+	return url.origin;
+}
+let jwksCache = null;
+/**
+* The last time an unknown kid forced a refetch, and how rarely that may happen.
+*
+* The token chooses the kid, so without a floor here a caller manufactures one
+* outbound request per attempt.
+*/
+let lastForcedFetch = 0;
+const FORCED_FETCH_COOLDOWN_MS = 3e4;
+/**
+* The fetch currently in flight, if there is one.
+*
+* The cooldown above bounds refetches for an UNKNOWN kid, but says nothing about
+* a cold cache: at boot, or the moment the cache ages out, every callback that
+* arrives at once sees no entry and starts its own request. That is a thundering
+* herd pointed at the identity service, and a caller holding transactions can
+* time it deliberately. One request per URL, shared by everyone waiting for it.
+*/
+let inFlight = null;
+async function fetchJwks(issuer, force = false) {
+	const url = `${issuer.replace(/\/$/, "")}/.well-known/jwks.json`;
+	if (!force && jwksCache && jwksCache.url === url && Date.now() - jwksCache.at < JWKS_TTL_MS) return jwksCache.jwks;
+	if (inFlight && inFlight.url === url) return inFlight.p;
+	const p = fetchJwksNow(url);
+	inFlight = {
+		url,
+		p
+	};
+	try {
+		return await p;
+	} finally {
+		if (inFlight?.p === p) inFlight = null;
+	}
+}
+async function fetchJwksNow(url) {
+	const res = await fetch(url, {
+		signal: AbortSignal.timeout(5e3),
+		redirect: "error"
+	});
+	if (!res.ok) throw new Error(`jwks fetch failed (${res.status})`);
+	const jwks = await res.json();
+	if (!Array.isArray(jwks.keys)) throw new Error("jwks malformed");
+	jwksCache = {
+		at: Date.now(),
+		url,
+		jwks
+	};
+	return jwks;
+}
+/**
+* Verify an assertion against everything it claims to be.
+*
+* Deliberately returns a reason string rather than throwing: the caller logs it
+* and shows the person a single generic failure. Distinguishing "expired" from
+* "wrong audience" to the browser would be handing an attacker a debugger.
+*/
+async function verifyAssertion(opts) {
+	const { token, origin, issuer, store, browser } = opts;
+	if (!token || token.length > MAX_TOKEN_BYTES) return {
+		ok: false,
+		reason: "token size"
+	};
+	const parts = token.split(".");
+	if (parts.length !== 3) return {
+		ok: false,
+		reason: "not a jws"
+	};
+	let header;
+	let claims;
+	try {
+		const h = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+		const c = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+		if (!isPlainObject(h) || !isPlainObject(c)) return {
+			ok: false,
+			reason: "malformed json"
+		};
+		header = h;
+		claims = c;
+	} catch {
+		return {
+			ok: false,
+			reason: "malformed json"
+		};
+	}
+	if (header.alg !== "ES256") return {
+		ok: false,
+		reason: "alg"
+	};
+	if (header.typ !== "marver-assertion+jwt") return {
+		ok: false,
+		reason: "typ"
+	};
+	if ("jku" in header || "x5u" in header || "jwk" in header) return {
+		ok: false,
+		reason: "header injection"
+	};
+	const kid = typeof header.kid === "string" ? header.kid : null;
+	if (!kid || kid.length > 128) return {
+		ok: false,
+		reason: "kid"
+	};
+	if (claims.iss !== issuer) return {
+		ok: false,
+		reason: "iss"
+	};
+	if (claims.aud !== origin) return {
+		ok: false,
+		reason: "aud"
+	};
+	if (claims.email_verified !== true) return {
+		ok: false,
+		reason: "email unverified"
+	};
+	const sub = typeof claims.sub === "string" ? claims.sub : "";
+	const email = typeof claims.email === "string" ? claims.email : "";
+	const nonce = typeof claims.nonce === "string" ? claims.nonce : "";
+	if (!sub || !email || !nonce) return {
+		ok: false,
+		reason: "missing claims"
+	};
+	const now = Math.floor(Date.now() / 1e3);
+	const exp = typeof claims.exp === "number" ? claims.exp : 0;
+	const nbf = typeof claims.nbf === "number" ? claims.nbf : 0;
+	const iat = typeof claims.iat === "number" ? claims.iat : 0;
+	if (!exp || exp + CLOCK_TOLERANCE_S < now) return {
+		ok: false,
+		reason: "expired"
+	};
+	if (nbf && nbf - CLOCK_TOLERANCE_S > now) return {
+		ok: false,
+		reason: "not yet valid"
+	};
+	if (!iat || iat - CLOCK_TOLERANCE_S > now) return {
+		ok: false,
+		reason: "issued in the future"
+	};
+	const tx = store.consume(nonce, browser);
+	if (!tx) return {
+		ok: false,
+		reason: "unknown or spent nonce"
+	};
+	if (tx.origin !== origin) return {
+		ok: false,
+		reason: "origin mismatch"
+	};
+	opts.onConsumed?.(tx);
+	let verified = false;
+	try {
+		verified = await verifySignature(parts, kid, issuer);
+	} catch {
+		return {
+			ok: false,
+			reason: "key fetch failed"
+		};
+	}
+	if (!verified) return {
+		ok: false,
+		reason: "signature"
+	};
+	return {
+		ok: true,
+		identity: {
+			subject: sub,
+			email,
+			...displayClaims(claims)
+		}
+	};
+}
+async function verifySignature(parts, kid, issuer) {
+	let jwks = await fetchJwks(issuer);
+	let jwk = jwks.keys.find((k) => k.kid === kid);
+	if (!jwk && Date.now() - lastForcedFetch >= FORCED_FETCH_COOLDOWN_MS) {
+		lastForcedFetch = Date.now();
+		jwks = await fetchJwks(issuer, true);
+		jwk = jwks.keys.find((k) => k.kid === kid);
+	}
+	if (!jwk) return false;
+	const k = jwk;
+	if (k.kty !== "EC" || k.crv !== "P-256") return false;
+	if (k.alg && k.alg !== "ES256") return false;
+	if (k.use && k.use !== "sig") return false;
+	if (Array.isArray(k.key_ops) && !k.key_ops.includes("verify")) return false;
+	const { createPublicKey } = await import("node:crypto");
+	const key = createPublicKey({
+		key: jwk,
+		format: "jwk"
+	});
+	const signature = Buffer.from(parts[2], "base64url");
+	if (signature.length !== 64) return false;
+	const v = createVerify("SHA256");
+	v.update(`${parts[0]}.${parts[1]}`);
+	v.end();
+	return v.verify({
+		key,
+		dsaEncoding: "ieee-p1363"
+	}, signature);
+}
+/**
+* The optional display claims, taken only if they are the right shape.
+*
+* Deliberately forgiving: a malformed name or picture drops that ONE field and
+* lets the sign-in through, because neither decides anything. Refusing a valid
+* assertion over a bad avatar URL would trade a cosmetic problem for a lockout.
+*
+* The bounds are what stop this being a hole. A name is capped so it cannot be
+* used to write a paragraph into somebody's comment sidebar, and control
+* characters go because that is how a value gets smuggled into a log line. A
+* picture must be https and bounded - the canvas will make a server-side request
+* to whatever survives this, so http, data:, file: and friends never get that
+* far.
+*/
+function displayClaims(claims) {
+	const out = {};
+	const name = (typeof claims.name === "string" ? claims.name : "").replace(/[\u0000-\u001f\u007f]/g, "").replace(/\s+/g, " ").trim().slice(0, 80);
+	if (name) out.name = name;
+	if (typeof claims.picture === "string" && claims.picture.length <= 2048) try {
+		const u = new URL(claims.picture);
+		if (u.protocol === "https:" && !u.username && !u.password) out.picture = u.toString();
+	} catch {}
+	return out;
+}
+/** A JSON object, and not an array or null - both of which pass `typeof === 'object'`. */
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Length-safe string compare, so a mismatch leaks nothing through timing. */
+function constantTimeEqual(a, b) {
+	const ha = createHash("sha256").update(a).digest();
+	const hb = createHash("sha256").update(b).digest();
+	return timingSafeEqual(ha, hb);
+}
+/**
+* A stable, opaque handle for "this browser", used to bind a transaction to the
+* client that started it. Derived from a random cookie value the canvas already
+* sets - never from IP or user agent, both of which change legitimately
+* mid-flow (mobile networks, upgrades) and would lock people out.
+*/
+function browserBinding(cookieValue) {
+	return createHash("sha256").update(cookieValue).digest("base64url");
+}
+//#endregion
+export { TransactionStore, browserBinding, normalizeIssuer, verifyAssertion };