@synqauth/js 0.0.0-stage → 0.0.0

package/dist/index.js

@@ -0,0 +1,605 @@
+import { a as problemError, i as isSynqError, n as secureUrl, o as toSynqError, r as SynqError, t as createApiClient } from "./api-Cf9K1Rc9.js";
+import * as oauth from "oauth4webapi";
+//#region src/storage.ts
+/**
+* Keeps everything in this process's memory: the default, and the only store
+* that holds refresh tokens unless told. Clients that share one share its
+* lock, so they never refresh one session twice at once.
+*/
+function memoryStorage() {
+	const values = /* @__PURE__ */ new Map();
+	const locks = /* @__PURE__ */ new Map();
+	return {
+		holdsRefreshTokens: true,
+		get: (key) => values.get(key),
+		set: (key, value) => {
+			values.set(key, value);
+		},
+		remove: (key) => {
+			values.delete(key);
+		},
+		keys: () => [...values.keys()],
+		lock(name, fn) {
+			const run = (locks.get(name) ?? Promise.resolve()).then(fn, fn);
+			const settled = run.then(() => void 0, () => void 0);
+			locks.set(name, settled);
+			settled.then(() => {
+				if (locks.get(name) === settled) locks.delete(name);
+			});
+			return run;
+		}
+	};
+}
+/** A store on one of the browser's Web Storage areas. */
+function webStorage(area) {
+	const store = globalThis[area];
+	if (!store) throw new SynqError("invalid_options", `${area} is only available in a browser`);
+	return {
+		holdsRefreshTokens: false,
+		get: (key) => store.getItem(key),
+		set: (key, value) => store.setItem(key, value),
+		remove: (key) => store.removeItem(key),
+		keys: () => {
+			const keys = [];
+			for (let i = 0; i < store.length; i++) {
+				const key = store.key(i);
+				if (key !== null) keys.push(key);
+			}
+			return keys;
+		}
+	};
+}
+/**
+* The tab's `sessionStorage`: it ends with the tab, and no other tab reads
+* it. As the session's store it keeps the access and ID tokens only, never
+* the refresh token.
+*/
+function browserSessionStorage() {
+	return webStorage("sessionStorage");
+}
+/**
+* The browser's `localStorage`, which every tab of the app's origin shares.
+* Where a sign-in's transaction goes by default in a browser: a magic link
+* or an email's link opens a new tab, which finishes the sign-in and comes
+* back to the app there, so the tab that started it can't be the only one
+* that knows it. Each transaction is kept under its own state, for an hour
+* at most, deleted when it finishes, and swept away when stale. The price:
+* any script on the app's origin can read a transaction meanwhile (its PKCE
+* verifier and nonce, useless without the code Synq sends to the app's own
+* redirect URI), as it can read anything else the app keeps. As the
+* session's store it keeps the access and ID tokens only, never the refresh
+* token.
+*/
+function browserLocalStorage() {
+	return webStorage("localStorage");
+}
+/**
+* Where a sign-in's transaction is kept unless the app says: the browser's
+* localStorage, else memory. Only a page has a `window`; Node's own Web
+* Storage is no browser's (and warns when touched without a file).
+*/
+function defaultTransactionStorage() {
+	const page = globalThis;
+	return typeof page.window === "object" && page.localStorage ? browserLocalStorage() : memoryStorage();
+}
+//#endregion
+//#region src/client.ts
+const SESSION_KEY = "synq.session";
+const REFRESH_KEY = "synq.refresh";
+const TRANSACTION_PREFIX = "synq.tx.";
+/** The store's lock a refresh runs under, when the store has one. */
+const REFRESH_LOCK = "synq.refresh";
+/** How long a sign-in's transaction is kept: as long as Synq keeps an interaction open. */
+const TRANSACTION_TTL_SECONDS = 3600;
+/** Parameters that belong to the flow itself, which `params` can't replace. */
+const FLOW_PARAMS = /* @__PURE__ */ new Set([
+	"client_id",
+	"response_type",
+	"redirect_uri",
+	"scope",
+	"state",
+	"nonce",
+	"code_challenge",
+	"code_challenge_method",
+	"resource",
+	"prompt",
+	"max_age",
+	"login_hint",
+	"synq_method",
+	"request",
+	"request_uri",
+	"response_mode"
+]);
+/** A client for one app at one of a brand's Synq issuers. */
+function createSynqClient(options) {
+	return new Client(options);
+}
+var Client = class {
+	#options;
+	#issuer;
+	#client;
+	#auth;
+	#http;
+	#storage;
+	#transactions;
+	#leeway;
+	#listeners = /* @__PURE__ */ new Set();
+	#server;
+	/** The session as last read or written; `undefined` until first read. */
+	#session;
+	/** The refresh token, here when the storage may not hold it. */
+	#refreshToken;
+	#refreshing;
+	/** Bumped by every sign-in and sign-out, so a refresh that started before one never writes over it. */
+	#generation = 0;
+	constructor(options) {
+		const issuer = secureUrl(options.issuer, "The issuer");
+		if (!options.clientId) throw new SynqError("invalid_options", "The clientId is missing");
+		if (!options.redirectUri) throw new SynqError("invalid_options", "The redirectUri is missing");
+		this.#options = options;
+		this.#issuer = issuer;
+		this.#client = { client_id: options.clientId };
+		this.#auth = options.clientSecret ? oauth.ClientSecretBasic(options.clientSecret) : oauth.None();
+		this.#http = {};
+		if (options.fetch) this.#http[oauth.customFetch] = options.fetch;
+		if (issuer.protocol === "http:") this.#http[oauth.allowInsecureRequests] = true;
+		this.#storage = options.storage ?? memoryStorage();
+		this.#transactions = options.transactionStorage ?? defaultTransactionStorage();
+		this.#leeway = options.refreshLeewaySeconds ?? 30;
+	}
+	async authorizationUrl(options = {}) {
+		const server = await this.#discover();
+		if (!server.authorization_endpoint) throw new SynqError("discovery_failed", "The issuer has no authorization endpoint");
+		await this.#sweepTransactions();
+		const verifier = oauth.generateRandomCodeVerifier();
+		const transaction = {
+			state: oauth.generateRandomState(),
+			nonce: oauth.generateRandomNonce(),
+			verifier,
+			redirectUri: this.#options.redirectUri,
+			resource: options.resource ?? this.#options.resource,
+			maxAge: options.maxAge,
+			createdAt: now()
+		};
+		const url = new URL(server.authorization_endpoint);
+		const params = url.searchParams;
+		for (const [name, value] of Object.entries(options.params ?? {})) {
+			if (FLOW_PARAMS.has(name)) throw new SynqError("invalid_options", `${name} is the flow's own parameter: use its option`);
+			params.set(name, value);
+		}
+		params.set("client_id", this.#options.clientId);
+		params.set("response_type", "code");
+		params.set("redirect_uri", transaction.redirectUri);
+		params.set("scope", options.scope ?? this.#options.scope ?? "openid");
+		params.set("state", transaction.state);
+		params.set("nonce", transaction.nonce);
+		params.set("code_challenge", await oauth.calculatePKCECodeChallenge(verifier));
+		params.set("code_challenge_method", "S256");
+		if (transaction.resource) params.set("resource", transaction.resource);
+		for (const extra of options.additionalResources ?? []) if (extra && extra !== transaction.resource) params.append("resource", extra);
+		if (options.prompt) params.set("prompt", options.prompt);
+		if (options.maxAge !== void 0) params.set("max_age", String(options.maxAge));
+		if (options.loginHint) params.set("login_hint", options.loginHint);
+		if (options.method) params.set("synq_method", options.method);
+		await this.#transactions.set(TRANSACTION_PREFIX + transaction.state, JSON.stringify(transaction));
+		if (!options.pushed) return url;
+		if (!server.pushed_authorization_request_endpoint) throw new SynqError("discovery_failed", "The issuer takes no pushed authorization requests");
+		let requestUri;
+		try {
+			const response = await oauth.pushedAuthorizationRequest(server, this.#client, this.#auth, new URLSearchParams([...params].filter(([name]) => name !== "client_id")), this.#http);
+			requestUri = (await oauth.processPushedAuthorizationResponse(server, this.#client, response)).request_uri;
+		} catch (error) {
+			await this.#transactions.remove(TRANSACTION_PREFIX + transaction.state);
+			throw toSynqError(error);
+		}
+		const pushed = new URL(server.authorization_endpoint);
+		pushed.searchParams.set("client_id", this.#options.clientId);
+		pushed.searchParams.set("request_uri", requestUri);
+		return pushed;
+	}
+	async signIn(options) {
+		const location = globalThis.location;
+		if (!location) throw new SynqError("invalid_options", "signIn() navigates a browser: use authorizationUrl()");
+		location.assign((await this.authorizationUrl(options)).href);
+	}
+	async handleCallback(url) {
+		const callback = new URL(url);
+		const state = callback.searchParams.get("state");
+		if (!state) throw new SynqError("unknown_state", "The callback has no state");
+		const key = TRANSACTION_PREFIX + state;
+		const stored = await this.#transactions.get(key);
+		await this.#transactions.remove(key);
+		const transaction = stored ? JSON.parse(stored) : void 0;
+		if (!transaction || now() - transaction.createdAt > TRANSACTION_TTL_SECONDS) throw new SynqError("unknown_state", "This sign-in wasn't started here, has already finished, or took too long");
+		const server = await this.#discover();
+		try {
+			const params = oauth.validateAuthResponse(server, this.#client, callback, transaction.state);
+			const response = await oauth.authorizationCodeGrantRequest(server, this.#client, this.#auth, params, transaction.redirectUri, transaction.verifier, {
+				...this.#http,
+				additionalParameters: resourceParams(transaction.resource)
+			});
+			const result = await oauth.processAuthorizationCodeResponse(server, this.#client, response, {
+				expectedNonce: transaction.nonce,
+				maxAge: transaction.maxAge ?? oauth.skipAuthTimeCheck,
+				requireIdToken: true
+			});
+			const claims = oauth.getValidatedIdTokenClaims(result);
+			this.#generation += 1;
+			await this.#clear();
+			const session = await this.#save(result, claims);
+			this.#emit({
+				type: "signed-in",
+				session
+			});
+			return session;
+		} catch (error) {
+			throw toSynqError(error);
+		}
+	}
+	async getSession() {
+		const stored = await this.#load();
+		return stored ? await this.#public(stored) : null;
+	}
+	async restoreSession(options = {}) {
+		const stored = await this.#load();
+		if (!stored) return null;
+		const session = await this.#public(stored);
+		if (session.refreshable || fresh(stored, this.#leeway)) return session;
+		this.#generation += 1;
+		await this.#clear();
+		await this.signIn({
+			...options,
+			prompt: "none"
+		});
+		return null;
+	}
+	async getAccessToken(options = {}) {
+		const stored = await this.#load();
+		if (!stored) throw new SynqError("not_signed_in", "Nobody is signed in");
+		if (fresh(stored, options.minValiditySeconds ?? this.#leeway)) return stored.accessToken;
+		return (await this.refresh()).accessToken;
+	}
+	refresh() {
+		this.#refreshing ??= this.#lockedRefresh().finally(() => {
+			this.#refreshing = void 0;
+		});
+		return this.#refreshing;
+	}
+	subscribe(listener) {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	}
+	async signOut(options = {}) {
+		const stored = await this.#load();
+		const refreshToken = await this.#readRefreshToken();
+		this.#generation += 1;
+		await this.#clear();
+		if (stored) this.#emit({
+			type: "signed-out",
+			session: null
+		});
+		const server = await this.#discover();
+		if (refreshToken && server.revocation_endpoint) for (let attempt = 1; attempt <= 2; attempt++) try {
+			const response = await oauth.revocationRequest(server, this.#client, this.#auth, refreshToken, {
+				...this.#http,
+				additionalParameters: { token_type_hint: "refresh_token" }
+			});
+			await oauth.processRevocationResponse(response);
+			break;
+		} catch (error) {
+			if (attempt === 2) console.warn("@synqauth/js: revoking the refresh token at sign-out failed; it stays usable until it expires", toSynqError(error).code);
+		}
+		if (!server.end_session_endpoint) return null;
+		const url = new URL(server.end_session_endpoint);
+		url.searchParams.set("client_id", this.#options.clientId);
+		if (stored?.idToken) url.searchParams.set("id_token_hint", stored.idToken);
+		const back = options.postLogoutRedirectUri ?? this.#options.postLogoutRedirectUri;
+		if (back) url.searchParams.set("post_logout_redirect_uri", back);
+		if (options.state) url.searchParams.set("state", options.state);
+		return url;
+	}
+	/**
+	* Refreshes under the store's lock, when it has one, so no other client
+	* sharing the store refreshes the same session at once. Inside it, the
+	* session is read again: when another client refreshed it meanwhile, its
+	* tokens are used, never the refresh token it already spent.
+	*/
+	async #lockedRefresh() {
+		const storage = this.#storage;
+		if (!storage.lock) return this.#refresh();
+		const before = (await this.#load())?.accessToken;
+		return storage.lock(REFRESH_LOCK, async () => {
+			this.#session = void 0;
+			const current = await this.#load();
+			if (current && current.accessToken !== before && fresh(current, this.#leeway)) {
+				const session = await this.#public(current);
+				this.#emit({
+					type: "refreshed",
+					session
+				});
+				return session;
+			}
+			return this.#refresh();
+		});
+	}
+	/** Removes sign-ins that were started but never finished, where the store can list them. */
+	async #sweepTransactions() {
+		const store = this.#transactions;
+		if (!store.keys) return;
+		try {
+			for (const key of await store.keys()) {
+				if (!key.startsWith(TRANSACTION_PREFIX)) continue;
+				const raw = await store.get(key);
+				let createdAt;
+				try {
+					createdAt = raw ? JSON.parse(raw).createdAt : void 0;
+				} catch {
+					createdAt = void 0;
+				}
+				if (typeof createdAt !== "number" || now() - createdAt > TRANSACTION_TTL_SECONDS) await store.remove(key);
+			}
+		} catch {}
+	}
+	async #refresh() {
+		const generation = this.#generation;
+		const stored = await this.#load();
+		if (!stored) throw new SynqError("not_signed_in", "Nobody is signed in");
+		const refreshToken = await this.#readRefreshToken();
+		if (!refreshToken) throw new SynqError("no_refresh_token", "This session has no refresh token: sign in again, or ask for offline_access");
+		const server = await this.#discover();
+		let result;
+		try {
+			const response = await oauth.refreshTokenGrantRequest(server, this.#client, this.#auth, refreshToken, {
+				...this.#http,
+				additionalParameters: resourceParams(this.#options.resource)
+			});
+			result = await oauth.processRefreshTokenResponse(server, this.#client, response);
+		} catch (error) {
+			const failure = toSynqError(error);
+			if (failure.code === "invalid_grant" && generation === this.#generation) {
+				this.#generation += 1;
+				await this.#clear();
+				this.#emit({
+					type: "signed-out",
+					session: null
+				});
+			}
+			throw failure;
+		}
+		if (generation !== this.#generation) throw new SynqError("not_signed_in", "The session ended while it was being refreshed");
+		const claims = oauth.getValidatedIdTokenClaims(result);
+		if (claims && stored.claims && claims.sub !== stored.claims.sub) throw new SynqError("invalid_response", "The refreshed ID token names someone else");
+		const session = await this.#save(result, claims ?? stored.claims, stored);
+		this.#emit({
+			type: "refreshed",
+			session
+		});
+		return session;
+	}
+	#discover() {
+		this.#server ??= (async () => {
+			try {
+				const response = await oauth.discoveryRequest(this.#issuer, {
+					...this.#http,
+					algorithm: "oidc"
+				});
+				return await oauth.processDiscoveryResponse(this.#issuer, response);
+			} catch (error) {
+				this.#server = void 0;
+				const failure = toSynqError(error);
+				throw failure.code === "network_error" ? failure : new SynqError("discovery_failed", `Synq's discovery document at ${this.#issuer.href} couldn't be read`, { cause: error });
+			}
+		})();
+		return this.#server;
+	}
+	async #save(result, claims, previous) {
+		const stored = {
+			accessToken: result.access_token,
+			tokenType: result.token_type,
+			expiresAt: result.expires_in === void 0 ? void 0 : now() + result.expires_in,
+			scope: result.scope ?? previous?.scope,
+			idToken: result.id_token ?? previous?.idToken,
+			claims
+		};
+		this.#session = stored;
+		await this.#storage.set(SESSION_KEY, JSON.stringify(stored));
+		if (result.refresh_token) await this.#writeRefreshToken(result.refresh_token);
+		return await this.#public(stored);
+	}
+	async #load() {
+		if (this.#session === void 0) {
+			const raw = await this.#storage.get(SESSION_KEY);
+			this.#session = raw ? JSON.parse(raw) : null;
+		}
+		return this.#session;
+	}
+	async #readRefreshToken() {
+		if (this.#storage.holdsRefreshTokens) return await this.#storage.get(REFRESH_KEY) ?? void 0;
+		return this.#refreshToken;
+	}
+	async #writeRefreshToken(token) {
+		if (this.#storage.holdsRefreshTokens) await this.#storage.set(REFRESH_KEY, token);
+		else this.#refreshToken = token;
+	}
+	async #clear() {
+		this.#session = null;
+		this.#refreshToken = void 0;
+		await this.#storage.remove(SESSION_KEY);
+		await this.#storage.remove(REFRESH_KEY);
+	}
+	async #public(stored) {
+		return {
+			...stored,
+			refreshable: await this.#readRefreshToken() !== void 0
+		};
+	}
+	#emit(event) {
+		for (const listener of this.#listeners) try {
+			listener(event);
+		} catch {}
+	}
+};
+function now() {
+	return Math.floor(Date.now() / 1e3);
+}
+/** Whether a session's access token is good for `leeway` seconds more (or Synq gave it no lifetime). */
+function fresh(session, leeway) {
+	return session.expiresAt === void 0 || session.expiresAt - now() > leeway;
+}
+function resourceParams(resource) {
+	return resource ? { resource } : void 0;
+}
+//#endregion
+//#region src/account.ts
+/**
+* The sign-in that finishes a link request, for `SynqClient.signIn` or
+* `authorizationUrl`: a fresh sign-in (`prompt=login`) carrying the request.
+*/
+function linkSignIn(request) {
+	const { prompt, ...params } = request.authorization_params;
+	return {
+		prompt,
+		params
+	};
+}
+/** The account API's URL for a brand: the resource its access tokens are for. */
+function accountApiUrl(issuer) {
+	return `${secureUrl(String(issuer), "The issuer").href.replace(/\/+$/, "")}/me`;
+}
+/** A client for the brand's account API, for an app that holds its own session: everything the signed-in person can do to their own account. */
+function createAccountClient(options) {
+	if (typeof options.accessToken !== "function") throw new SynqError("invalid_options", "Give the account client an accessToken function");
+	const raw = createApiClient({
+		baseUrl: accountApiUrl(options.issuer),
+		credential: options.accessToken,
+		fetch: options.fetch
+	});
+	async function run(send, pick) {
+		try {
+			const json = await send();
+			return {
+				data: pick ? pick(json) : json,
+				error: null
+			};
+		} catch (error) {
+			return {
+				data: null,
+				error: error instanceof SynqError ? error : new SynqError("network_error", String(error), { cause: error })
+			};
+		}
+	}
+	const read = (path, opts = {}, request = {}) => run(() => raw.get(path, {
+		...request,
+		signal: opts.signal
+	}));
+	const list = (path, opts = {}) => run(() => raw.get(path, { signal: opts.signal }), (json) => json.data);
+	const change = (method, path, opts = {}, request = {}) => run(() => raw[method](path, {
+		...request,
+		idempotencyKey: opts.idempotencyKey ?? crypto.randomUUID(),
+		signal: opts.signal
+	}), (json) => json === void 0 ? null : json);
+	return {
+		me: (opts) => read("/v1/profile", opts),
+		user: {
+			update: (changes, opts) => change("patch", "/v1/profile", opts, { body: changes }),
+			metadata: (opts) => read("/v1/metadata", opts),
+			usernameAvailable: (username, opts) => read("/v1/usernames/{username}", opts, { path: { username } })
+		},
+		wallets: {
+			list: (opts) => list("/v1/wallets", opts),
+			update: (wallet, changes, opts) => change("patch", "/v1/wallets/{wallet}", opts, {
+				path: { wallet },
+				body: changes
+			}),
+			remove: (wallet, opts) => change("delete", "/v1/identities/{identity}", opts, { path: { identity: wallet } })
+		},
+		accounts: {
+			list: (opts) => list("/v1/identities", opts),
+			link: (method, opts) => change("post", "/v1/link-requests", opts, { body: { method } }),
+			unlink: (identity, opts) => change("delete", "/v1/identities/{identity}", opts, { path: { identity } })
+		},
+		sessions: {
+			list: (opts) => list("/v1/sessions", opts),
+			revoke: (session, opts) => change("delete", "/v1/sessions/{session}", opts, { path: { session } })
+		},
+		passkeys: {
+			list: (opts) => list("/v1/passkeys", opts),
+			registrationOptions: (opts) => change("post", "/v1/passkeys/registration-options", opts),
+			register: (credential, opts) => change("post", "/v1/passkeys", opts, { body: { credential } }),
+			remove: (passkey, opts) => change("delete", "/v1/passkeys/{passkey}", opts, { path: { passkey } })
+		},
+		consents: {
+			list: (opts) => list("/v1/consents", opts),
+			withdraw: (consent, opts) => change("delete", "/v1/consents/{consent}", opts, { path: { consent } })
+		},
+		activity: (opts) => list("/v1/sign-ins", opts),
+		deletion: {
+			schedule: (opts) => change("post", "/v1/deletion", opts),
+			cancel: (opts) => change("delete", "/v1/deletion", opts)
+		}
+	};
+}
+//#endregion
+//#region src/generated/errors.ts
+/** Each `code` a Synq API's problem documents carry, with its HTTP status. */
+const ERROR_CODES = {
+	unauthorized: 401,
+	invalid_token: 401,
+	token_expired: 401,
+	api_key_revoked: 401,
+	forbidden: 403,
+	insufficient_permissions: 403,
+	not_found: 404,
+	validation_failed: 400,
+	idempotency_key_conflict: 422,
+	idempotency_key_in_flight: 409,
+	conflict: 409,
+	org_slug_taken: 409,
+	issuer_slug_taken: 409,
+	issuer_slug_immutable: 422,
+	plan_quota_exceeded: 403,
+	plan_feature_unavailable: 403,
+	org_creation_closed: 403,
+	email_unverified: 403,
+	org_quota_exceeded: 403,
+	recipient_org_quota_exceeded: 403,
+	fresh_sign_in_required: 403,
+	username_taken: 409,
+	last_sign_in_method: 409,
+	passkey_exists: 409,
+	sign_in_method_unavailable: 409,
+	identity_limit_reached: 409,
+	connection_rejected: 422,
+	token_gates_unavailable: 409,
+	passkey_rejected: 400,
+	email_undeliverable: 422,
+	email_domain_unavailable: 409,
+	email_domain_invalid: 422,
+	email_domain_limit_reached: 409,
+	email_domain_in_use: 409,
+	plan_not_sold: 422,
+	subscription_exists: 409,
+	no_billing_account: 409,
+	no_subscription: 409,
+	payment_failed: 402,
+	custom_domain_exists: 409,
+	hostname_taken: 409,
+	invalid_hostname: 422,
+	apex_not_supported: 422,
+	reserved_hostname: 422,
+	hostname_denied: 422,
+	hostname_not_allowed_here: 422,
+	payload_too_large: 413,
+	unsupported_media_type: 415,
+	upload_incomplete: 409,
+	upload_expired: 410,
+	file_rejected: 422,
+	upload_limit_reached: 409,
+	rate_limited: 429,
+	internal_error: 500,
+	service_unavailable: 503
+};
+//#endregion
+export { ERROR_CODES, SynqError, accountApiUrl, browserLocalStorage, browserSessionStorage, createAccountClient, createSynqClient, isSynqError, linkSignIn, memoryStorage, problemError };