@redeemid/emdash 0.0.0-stage → 0.0.2

package/src/guard.ts

@@ -0,0 +1,45 @@
+/**
+ * Keeps members out of EmDash's own APIs and admin.
+ *
+ * EmDash's Subscriber role may read every published entry through
+ * /_emdash/api/content. With RedeemID, access comes from Shopify tags only, so
+ * a member with one level could otherwise read another level's posts there.
+ * This middleware runs after EmDash's auth and refuses Subscribers on every
+ * /_emdash path except the few public pages need.
+ */
+
+import { defineMiddleware } from "astro:middleware";
+
+import { siteConfig } from "./site-config.js";
+
+const SUBSCRIBER = 10;
+
+/** Paths signed-in members still need. Everything else under /_emdash is refused. */
+export const MEMBER_PATHS = [
+	"/_emdash/api/auth/redeemid/",
+	"/_emdash/api/auth/logout",
+	"/_emdash/api/media/file/",
+	"/_emdash/api/comments",
+	"/_emdash/api/plugins/",
+];
+
+export function memberMayUse(path: string, extra: string[] = []): boolean {
+	if (!path.startsWith("/_emdash")) return true;
+	return [...MEMBER_PATHS, ...extra].some((p) => path === p.replace(/\/$/, "") || path.startsWith(p));
+}
+
+export const onRequest = defineMiddleware(async ({ locals, url }, next) => {
+	const user = (locals as { user?: { role?: number } | null }).user;
+	if (!user || user.role !== SUBSCRIBER) return next();
+
+	const config = siteConfig((locals as { emdash?: { config?: unknown } }).emdash?.config);
+	if (memberMayUse(url.pathname, config?.memberPaths)) return next();
+
+	if (url.pathname.startsWith("/_emdash/admin")) {
+		return new Response(null, { status: 302, headers: { location: "/", "cache-control": "private, no-store" } });
+	}
+	return new Response(JSON.stringify({ error: { code: "FORBIDDEN", message: "Members can't use this API." } }), {
+		status: 403,
+		headers: { "content-type": "application/json", "cache-control": "private, no-store" },
+	});
+});

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * RedeemID for EmDash.
+ *
+ * Shopify runs the store and the customer account; EmDash runs the content.
+ * Add to astro.config.mjs:
+ *
+ *   integrations: [
+ *     emdash({ authProviders: [redeemid({ ... })] }),
+ *     redeemidGuard(),
+ *   ]
+ *
+ * In full:
+ *
+ *   emdash({
+ *     authProviders: [
+ *       redeemid({
+ *         shop: "my-store.myshopify.com",
+ *         levels: [{ slug: "member", name: "Member", tags: ["member"] }],
+ *         rules: [{ collection: "posts", taxonomy: "category", term: "members", levels: ["member"] }],
+ *       }),
+ *     ],
+ *   })
+ *
+ * Secrets come from the environment (see ENV in config.ts):
+ * REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID and, for confidential clients,
+ * REDEEMID_SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_SECRET (the Headless storefront's
+ * Customer Account API client), and REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_SECRET
+ * (the client secret of the Shopify app whose webhooks the site receives).
+ */
+
+import type { AstroIntegration } from "astro";
+import type { AuthProviderDescriptor } from "emdash";
+
+import { PROVIDER_ID, type RedeemIDConfig } from "./config.js";
+import { STORAGE_CONFIG } from "./storage.js";
+
+export type { LevelConfig, RedeemIDConfig, RuleConfig } from "./config.js";
+export type { MemberRecord } from "./storage.js";
+// Page-time helpers live in "@redeemid/emdash/access": they read the site's
+// build-time config module, which astro.config.mjs can't load.
+
+const BASE = "/_emdash/api/auth/redeemid";
+
+export function redeemid(config: RedeemIDConfig): AuthProviderDescriptor {
+	if (!config) throw new Error("RedeemID: pass a config object.");
+	return {
+		id: PROVIDER_ID,
+		label: config.label ?? "Sign in",
+		config,
+		// No adminEntry: members sign in from the site, not the EmDash login page.
+		routes: [
+			{ pattern: `${BASE}/login`, entrypoint: "@redeemid/emdash/routes/login.ts" },
+			{ pattern: `${BASE}/callback`, entrypoint: "@redeemid/emdash/routes/callback.ts" },
+			{ pattern: `${BASE}/logout`, entrypoint: "@redeemid/emdash/routes/logout.ts" },
+			{ pattern: `${BASE}/webhook`, entrypoint: "@redeemid/emdash/routes/webhook.ts" },
+			{ pattern: `${BASE}/buy`, entrypoint: "@redeemid/emdash/routes/buy.ts" },
+		],
+		publicRoutes: [`${BASE}/`],
+		storage: STORAGE_CONFIG,
+	};
+}
+
+/**
+ * Astro integration that keeps members (EmDash Subscribers) out of EmDash's
+ * content API and admin, so only RedeemID's checks decide who reads what.
+ */
+export function redeemidGuard(): AstroIntegration {
+	return {
+		name: "@redeemid/emdash/guard",
+		hooks: {
+			"astro:config:setup": ({ addMiddleware }) => {
+				addMiddleware({ entrypoint: "@redeemid/emdash/guard.ts", order: "post" });
+			},
+		},
+	};
+}
+
+export default redeemid;

package/src/routes/buy.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /_emdash/api/auth/redeemid/buy: start a Shopify checkout for one plan.
+ *
+ * Takes a product handle, looks its variant up again on Shopify (never
+ * trusting a posted variant or price) and sends the buyer to checkout. A
+ * signed-in member's email is passed along so the order lands on the same
+ * customer. Tags, and so access, still only change when Shopify says so.
+ */
+
+import type { APIRoute } from "astro";
+
+import { readConfig, storeDomain } from "../config.js";
+import { safeReturn } from "../access.js";
+import { memberForUser, stores } from "../storage.js";
+import { checkoutUrl, plan } from "../storefront.js";
+import { fail } from "./shared.js";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request, locals, session, redirect }) => {
+	const form = await request.formData().catch(() => null);
+	const returnTo = safeReturn(String(form?.get("return") ?? "/"));
+	const handle = String(form?.get("plan") ?? "").trim();
+	const emdash = (locals as { emdash?: { config?: unknown; db?: unknown } }).emdash;
+	const config = readConfig(emdash?.config);
+	if (!config || !storeDomain(config)) return fail(redirect, returnTo, "not_configured");
+	if (!/^[a-z0-9][a-z0-9-]*$/i.test(handle)) return fail(redirect, returnTo, "plan_unavailable");
+
+	try {
+		const p = await plan(config, handle);
+		if (!p?.variantId || !p.availableForSale) return fail(redirect, returnTo, "plan_unavailable");
+		// Provider routes are public, so read the member from the session.
+		const user = (await session?.get("user")) as { id?: string } | undefined;
+		const member = user?.id && emdash?.db ? await memberForUser(stores(emdash.db), user.id) : null;
+		const to = await checkoutUrl(
+			config,
+			{ variantId: p.variantId, sellingPlanId: p.sellingPlanId },
+			{ email: member?.email ?? null, buyerIp: request.headers.get("cf-connecting-ip") },
+		);
+		return redirect(to, 303);
+	} catch {
+		return fail(redirect, returnTo, "checkout_failed");
+	}
+};

package/src/routes/callback.ts

@@ -0,0 +1,106 @@
+/**
+ * GET /_emdash/api/auth/redeemid/callback
+ *
+ * Finishes Shopify customer account sign-in: checks state, exchanges the code,
+ * verifies the ID token, reads the customer, links or creates an EmDash
+ * Subscriber, mirrors the customer and starts the session.
+ *
+ * Refused: staff accounts (any role above Subscriber), disabled users, sites
+ * whose setup is not finished, and customers without a verified email.
+ */
+
+import { findOrCreateOAuthUser, OAuthError, Role } from "@emdash-cms/auth";
+import { createKyselyAdapter, type AuthTables } from "@emdash-cms/auth/adapters/kysely";
+import type { APIRoute } from "astro";
+import { OptionsRepository } from "emdash/api/route-utils";
+import type { Kysely } from "kysely";
+
+import { env, ENV, PROVIDER_ID, readConfig, storeDomain } from "../config.js";
+import { discover, exchangeCode, identity, ShopifyError, verifyIdToken } from "../shopify.js";
+import { emptyMember, stores } from "../storage.js";
+import { callbackUrl, fail, FLOW_TTL_MS, SESSION_FLOW, SESSION_ID_TOKEN, type Flow } from "./shared.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ request, locals, session, redirect }) => {
+	const url = new URL(request.url);
+	const emdash = (locals as { emdash?: { db?: unknown; config?: unknown } }).emdash;
+	const flow = (await session?.get(SESSION_FLOW)) as Flow | undefined;
+	session?.delete(SESSION_FLOW);
+	const returnTo = flow?.returnTo ?? "/";
+
+	const config = readConfig(emdash?.config);
+	const clientId = env(ENV.clientId);
+	if (!config || !storeDomain(config) || !clientId || !emdash?.db || !session) return fail(redirect, returnTo, "not_configured");
+
+	if (url.searchParams.get("error")) return fail(redirect, returnTo, "sign_in_cancelled");
+
+	const state = url.searchParams.get("state");
+	const code = url.searchParams.get("code");
+	if (!flow || !state || state !== flow.state || !code || Date.now() - flow.at > FLOW_TTL_MS) {
+		return fail(redirect, returnTo, "sign_in_expired");
+	}
+
+	try {
+		const options = new OptionsRepository(emdash.db as ConstructorParameters<typeof OptionsRepository>[0]);
+		const setup = await options.get("emdash:setup_complete");
+		// Never let a customer become the first (admin) user.
+		if (setup !== true && setup !== "true") return fail(redirect, returnTo, "site_not_ready");
+
+		const d = await discover(config);
+		const tokens = await exchangeCode(d, {
+			clientId,
+			clientSecret: env(ENV.clientSecret),
+			redirectUri: callbackUrl(url, emdash.config),
+			origin: new URL(callbackUrl(url, emdash.config)).origin,
+			code,
+			verifier: flow.verifier,
+		});
+		const claims = await verifyIdToken(d, tokens.idToken, { clientId, nonce: flow.nonce });
+		const who = await identity(d, tokens.accessToken);
+
+		const email = (typeof claims.email === "string" ? claims.email : who.email)?.toLowerCase() ?? null;
+		if (!email) return fail(redirect, returnTo, "email_required");
+		const emailVerified = claims.email_verified === true;
+
+		const adapter = createKyselyAdapter(emdash.db as Kysely<AuthTables>);
+
+		// Staff accounts never sign in through the store, even with the same email.
+		const linked = await adapter.getOAuthAccount(PROVIDER_ID, who.customerId);
+		const existing = linked ? await adapter.getUserById(linked.userId) : await adapter.getUserByEmail(email);
+		if (existing && existing.role > Role.SUBSCRIBER) return fail(redirect, returnTo, "staff_account");
+
+		const name = [who.firstName, who.lastName].filter(Boolean).join(" ") || null;
+		const user = await findOrCreateOAuthUser(
+			adapter,
+			PROVIDER_ID,
+			{ id: who.customerId, email, name, avatarUrl: null, emailVerified },
+			async () => ({ allowed: true, role: Role.SUBSCRIBER }),
+			{ requireVerifiedEmail: true },
+		);
+		if (user.disabled) return fail(redirect, returnTo, "account_disabled");
+		if (user.role > Role.SUBSCRIBER) return fail(redirect, returnTo, "staff_account");
+
+		const s = stores(emdash.db);
+		const member = (await s.members.get(who.customerId)) ?? emptyMember(who.customerId);
+		await s.members.put(who.customerId, {
+			...member,
+			userId: user.id,
+			email,
+			firstName: who.firstName,
+			lastName: who.lastName,
+			tags: who.tags,
+			syncedAt: new Date().toISOString(),
+			source: "sign-in",
+		});
+
+		session.regenerate?.();
+		session.set("user", { id: user.id });
+		session.set(SESSION_ID_TOKEN, tokens.idToken);
+		return redirect(returnTo);
+	} catch (e) {
+		const code = e instanceof ShopifyError ? e.code : e instanceof OAuthError ? "signup_not_allowed" : "sign_in_failed";
+		console.error("[redeemid] sign-in failed:", (e as Error).message);
+		return fail(redirect, returnTo, code);
+	}
+};

package/src/routes/login.ts

@@ -0,0 +1,49 @@
+/**
+ * GET /_emdash/api/auth/redeemid/login?return=/path
+ *
+ * Starts Shopify customer account sign-in (authorization code + PKCE).
+ */
+
+import type { APIRoute } from "astro";
+
+import { safeReturn } from "../access.js";
+import { env, ENV, readConfig, storeDomain } from "../config.js";
+import { authorizeUrl, challengeFor, discover, randomToken } from "../shopify.js";
+import { callbackUrl, fail, SESSION_FLOW, type Flow } from "./shared.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ request, locals, session, redirect }) => {
+	const url = new URL(request.url);
+	const returnTo = safeReturn(url.searchParams.get("return"));
+	const emdash = (locals as { emdash?: { config?: unknown } }).emdash;
+	const config = readConfig(emdash?.config);
+	const clientId = env(ENV.clientId);
+
+	if (!config || !storeDomain(config) || !clientId || !session) return fail(redirect, returnTo, "not_configured");
+
+	try {
+		const d = await discover(config);
+		const flow: Flow = {
+			state: randomToken(),
+			nonce: randomToken(),
+			verifier: randomToken(48),
+			returnTo,
+			at: Date.now(),
+		};
+		session.set(SESSION_FLOW, flow);
+		return redirect(
+			authorizeUrl(d, {
+				clientId,
+				redirectUri: callbackUrl(url, emdash?.config),
+				state: flow.state,
+				nonce: flow.nonce,
+				challenge: await challengeFor(flow.verifier),
+				locale: request.headers.get("accept-language")?.split(",")[0]?.trim(),
+			}),
+		);
+	} catch (e) {
+		console.error("[redeemid] sign-in start failed:", (e as Error).message);
+		return fail(redirect, returnTo, "sign_in_unavailable");
+	}
+};

package/src/routes/logout.ts

@@ -0,0 +1,41 @@
+/**
+ * POST /_emdash/api/auth/redeemid/logout?return=/path
+ *
+ * Ends the site session, then the Shopify customer session when the store
+ * publishes an end-session endpoint. After the store session ends the member
+ * lands on the site root (the logout URI registered in Shopify); without a
+ * store session they go straight back to `return`. POST only, so a link elsewhere can't
+ * sign members out.
+ */
+
+import type { APIRoute } from "astro";
+import { getPublicOrigin } from "emdash/api/route-utils";
+
+import { safeReturn } from "../access.js";
+import { readConfig } from "../config.js";
+import { discover, logoutUrl } from "../shopify.js";
+import { SESSION_ID_TOKEN } from "./shared.js";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request, locals, session, redirect }) => {
+	const url = new URL(request.url);
+	const returnTo = safeReturn(url.searchParams.get("return"));
+	const emdash = (locals as { emdash?: { config?: unknown } }).emdash;
+	const idToken = (await session?.get(SESSION_ID_TOKEN)) as string | undefined;
+	session?.destroy();
+
+	const config = readConfig(emdash?.config);
+	if (config && idToken) {
+		try {
+			const origin = getPublicOrigin(url, emdash?.config as Parameters<typeof getPublicOrigin>[1]);
+			// Shopify only returns to a registered logout URI, so register the
+			// site root and come back there rather than to the page.
+			const to = logoutUrl(await discover(config), idToken, `${origin}/`);
+			if (to) return redirect(to);
+		} catch {
+			// The site session is already gone; Shopify's ends on its own.
+		}
+	}
+	return redirect(returnTo);
+};

package/src/routes/shared.ts

@@ -0,0 +1,26 @@
+import { getPublicOrigin } from "emdash/api/route-utils";
+
+export const SESSION_FLOW = "redeemid:flow";
+export const SESSION_ID_TOKEN = "redeemid:id_token";
+/** A sign-in started more than this long ago is refused. */
+export const FLOW_TTL_MS = 10 * 60 * 1000;
+
+export interface Flow {
+	state: string;
+	nonce: string;
+	verifier: string;
+	returnTo: string;
+	at: number;
+}
+
+export const CALLBACK_PATH = "/_emdash/api/auth/redeemid/callback";
+
+export function callbackUrl(url: URL, emdashConfig: unknown): string {
+	return `${getPublicOrigin(url, emdashConfig as Parameters<typeof getPublicOrigin>[1])}${CALLBACK_PATH}`;
+}
+
+/** Back to where the member was, with a notice code the theme can show. */
+export function fail(redirect: (to: string) => Response, returnTo: string, code: string): Response {
+	const sep = returnTo.includes("?") ? "&" : "?";
+	return redirect(`${returnTo}${sep}redeemid_notice=${encodeURIComponent(code)}`);
+}

package/src/routes/webhook.ts

@@ -0,0 +1,58 @@
+/**
+ * POST /_emdash/api/auth/redeemid/webhook
+ *
+ * Shopify webhooks. Verifies the HMAC over the raw body, drops duplicate
+ * deliveries, and updates the member mirror. Storage errors answer 500 so
+ * Shopify retries; a failed delivery is never recorded as seen.
+ */
+
+import type { APIRoute } from "astro";
+
+import { env, ENV } from "../config.js";
+import { stores } from "../storage.js";
+import { apply, kindOf, verifyHmac } from "../webhooks.js";
+
+export const prerender = false;
+
+const MAX_BYTES = 1024 * 1024;
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const emdash = (locals as { emdash?: { db?: unknown } }).emdash;
+	const secret = env(ENV.webhookSecret);
+	if (!emdash?.db || !secret) return new Response("Not configured", { status: 503 });
+
+	const body = new Uint8Array(await request.arrayBuffer());
+	if (body.byteLength > MAX_BYTES) return new Response("Too large", { status: 413 });
+
+	const ok = await verifyHmac(body, request.headers.get("x-shopify-hmac-sha256") ?? "", secret);
+	if (!ok) return new Response("Bad signature", { status: 401 });
+
+	const topic = (request.headers.get("x-shopify-topic") ?? "").toLowerCase();
+	const delivery = request.headers.get("x-shopify-event-id") || request.headers.get("x-shopify-webhook-id");
+	if (!kindOf(topic)) return new Response("Ignored", { status: 200 });
+
+	let payload: Record<string, unknown>;
+	try {
+		payload = JSON.parse(new TextDecoder().decode(body)) as Record<string, unknown>;
+	} catch {
+		return new Response("Bad JSON", { status: 400 });
+	}
+
+	const s = stores(emdash.db);
+	if (delivery) {
+		const claimed = await s.deliveries.compareAndSet(delivery, null, {
+			topic,
+			receivedAt: new Date().toISOString(),
+		});
+		if (!claimed.applied) return new Response("Duplicate", { status: 200 });
+	}
+
+	try {
+		const outcome = await apply(s, topic, payload);
+		return new Response(outcome, { status: 200 });
+	} catch (e) {
+		console.error("[redeemid] webhook failed:", topic, (e as Error).message);
+		if (delivery) await s.deliveries.delete(delivery).catch(() => undefined);
+		return new Response("Retry", { status: 500 });
+	}
+};

package/src/shopify.ts

@@ -0,0 +1,227 @@
+/**
+ * Shopify Customer Account API: discovery, PKCE, token exchange, ID token
+ * checks and the identity query. Web APIs only, so it runs on Node and Workers.
+ */
+
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+
+import { shopOrigin, type RedeemIDConfig } from "./config.js";
+
+/** Customer Account API version, pinned on the discovered GraphQL URL. */
+export const API_VERSION = "2026-10";
+export const SCOPES = "openid email customer-account-api:full";
+
+export interface Discovery {
+	issuer: string;
+	authorizationEndpoint: string;
+	tokenEndpoint: string;
+	endSessionEndpoint: string;
+	jwksUri: string;
+	graphqlApi: string;
+}
+
+const DISCOVERY_TTL_MS = 60 * 60 * 1000;
+const discoveryCache = new Map<string, { at: number; value: Discovery }>();
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+export class ShopifyError extends Error {
+	constructor(
+		public readonly code: string,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+/** Point the discovered GraphQL URL at the pinned version. */
+export function pinVersion(url: string): string {
+	return url.replace(/\/api\/(?:\d{4}-\d{2}|unstable)\/graphql(?:\.json)?$/, `/api/${API_VERSION}/graphql`);
+}
+
+export async function discover(config: RedeemIDConfig, fetcher: typeof fetch = fetch): Promise<Discovery> {
+	const origin = shopOrigin(config);
+	const hit = discoveryCache.get(origin);
+	if (hit && Date.now() - hit.at < DISCOVERY_TTL_MS) return hit.value;
+
+	const [openid, api] = await Promise.all([
+		getJson(fetcher, `${origin}/.well-known/openid-configuration`),
+		getJson(fetcher, `${origin}/.well-known/customer-account-api`),
+	]);
+	const str = (o: Record<string, unknown>, k: string) => (typeof o[k] === "string" ? (o[k] as string) : "");
+
+	const value: Discovery = {
+		issuer: str(openid, "issuer"),
+		authorizationEndpoint: str(openid, "authorization_endpoint"),
+		tokenEndpoint: str(openid, "token_endpoint"),
+		endSessionEndpoint: str(openid, "end_session_endpoint"),
+		jwksUri: str(openid, "jwks_uri"),
+		graphqlApi: pinVersion(str(api, "graphql_api")),
+	};
+	if (!value.authorizationEndpoint || !value.tokenEndpoint || !value.issuer || !value.jwksUri) {
+		throw new ShopifyError("discovery_failed", "The store did not publish customer account sign-in.");
+	}
+	discoveryCache.set(origin, { at: Date.now(), value });
+	return value;
+}
+
+async function getJson(fetcher: typeof fetch, url: string): Promise<Record<string, unknown>> {
+	const res = await fetcher(url, { headers: { Accept: "application/json" } });
+	if (!res.ok) throw new ShopifyError("discovery_failed", `Discovery failed (${res.status}) for ${url}`);
+	return (await res.json()) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------- PKCE
+
+export function randomToken(bytes = 32): string {
+	const buf = new Uint8Array(bytes);
+	crypto.getRandomValues(buf);
+	return base64url(buf);
+}
+
+export async function challengeFor(verifier: string): Promise<string> {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return base64url(new Uint8Array(digest));
+}
+
+export function base64url(bytes: Uint8Array): string {
+	let s = "";
+	for (const b of bytes) s += String.fromCharCode(b);
+	return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function authorizeUrl(
+	d: Discovery,
+	args: { clientId: string; redirectUri: string; state: string; nonce: string; challenge: string; locale?: string },
+): string {
+	const url = new URL(d.authorizationEndpoint);
+	url.searchParams.set("scope", SCOPES);
+	url.searchParams.set("client_id", args.clientId);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("redirect_uri", args.redirectUri);
+	url.searchParams.set("state", args.state);
+	url.searchParams.set("nonce", args.nonce);
+	url.searchParams.set("code_challenge", args.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (args.locale) url.searchParams.set("ui_locales", args.locale);
+	return url.toString();
+}
+
+// ---------------------------------------------------------------- tokens
+
+export interface Tokens {
+	accessToken: string;
+	idToken: string;
+}
+
+export async function exchangeCode(
+	d: Discovery,
+	args: { clientId: string; clientSecret: string; redirectUri: string; origin?: string; code: string; verifier: string },
+	fetcher: typeof fetch = fetch,
+): Promise<Tokens> {
+	const body = new URLSearchParams({
+		grant_type: "authorization_code",
+		client_id: args.clientId,
+		redirect_uri: args.redirectUri,
+		code: args.code,
+		code_verifier: args.verifier,
+	});
+	const headers: Record<string, string> = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json",
+	};
+	// Public clients are checked against their registered JavaScript origins.
+	if (args.origin) headers.Origin = args.origin;
+	if (args.clientSecret) headers.Authorization = `Basic ${btoa(`${args.clientId}:${args.clientSecret}`)}`;
+
+	const res = await fetcher(d.tokenEndpoint, { method: "POST", headers, body });
+	const data = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+	if (!res.ok || typeof data.access_token !== "string" || typeof data.id_token !== "string") {
+		throw new ShopifyError("token_failed", `Token exchange failed (${res.status}).`);
+	}
+	return { accessToken: data.access_token, idToken: data.id_token };
+}
+
+/** Verify the ID token's signature, issuer, audience, expiry and nonce. */
+export async function verifyIdToken(
+	d: Discovery,
+	idToken: string,
+	args: { clientId: string; nonce: string },
+): Promise<JWTPayload> {
+	let jwks = jwksCache.get(d.jwksUri);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(new URL(d.jwksUri));
+		jwksCache.set(d.jwksUri, jwks);
+	}
+	try {
+		const { payload } = await jwtVerify(idToken, jwks, {
+			issuer: d.issuer,
+			audience: args.clientId,
+			clockTolerance: 60,
+		});
+		if (payload.nonce !== args.nonce) throw new ShopifyError("bad_nonce", "ID token nonce mismatch.");
+		return payload;
+	} catch (e) {
+		if (e instanceof ShopifyError) throw e;
+		throw new ShopifyError("bad_id_token", `ID token rejected: ${(e as Error).message}`);
+	}
+}
+
+// ---------------------------------------------------------------- identity
+
+export interface Identity {
+	customerId: string;
+	email: string | null;
+	firstName: string | null;
+	lastName: string | null;
+	tags: string[];
+}
+
+export const IDENTITY_QUERY = `query RedeemIDIdentity {
+  customer {
+    id
+    firstName
+    lastName
+    emailAddress { emailAddress }
+    tags
+  }
+}`;
+
+export async function identity(d: Discovery, accessToken: string, fetcher: typeof fetch = fetch): Promise<Identity> {
+	if (!d.graphqlApi) throw new ShopifyError("identity_failed", "The store did not publish the Customer Account API.");
+	const res = await fetcher(d.graphqlApi, {
+		method: "POST",
+		// The Customer Account API takes the bare access token, without "Bearer".
+		headers: { "Content-Type": "application/json", Authorization: accessToken },
+		body: JSON.stringify({ query: IDENTITY_QUERY }),
+	});
+	const data = (await res.json().catch(() => ({}))) as {
+		data?: { customer?: Record<string, unknown> | null };
+	};
+	const c = data.data?.customer;
+	const gid = typeof c?.id === "string" ? c.id : "";
+	const m = /^gid:\/\/shopify\/Customer\/(\d+)$/.exec(gid);
+	if (!res.ok || !c || !m?.[1]) throw new ShopifyError("identity_failed", "Shopify did not return a customer.");
+	const s = (v: unknown) => (typeof v === "string" && v !== "" ? v : null);
+	const email = (c.emailAddress as { emailAddress?: unknown } | null)?.emailAddress;
+	return {
+		customerId: m[1],
+		email: s(email)?.toLowerCase() ?? null,
+		firstName: s(c.firstName),
+		lastName: s(c.lastName),
+		tags: Array.isArray(c.tags) ? c.tags.filter((t): t is string => typeof t === "string") : [],
+	};
+}
+
+export function logoutUrl(d: Discovery, idToken: string, after: string): string | null {
+	if (!d.endSessionEndpoint) return null;
+	const url = new URL(d.endSessionEndpoint);
+	url.searchParams.set("id_token_hint", idToken);
+	url.searchParams.set("post_logout_redirect_uri", after);
+	return url.toString();
+}
+
+/** For tests: forget cached discovery and keys. */
+export function resetCaches(): void {
+	discoveryCache.clear();
+	jwksCache.clear();
+}