@synqauth/js 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @synqauth/js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Synq's framework-agnostic client: sign-in and sessions in the browser, the account API, and token and webhook verification on your server.
+
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+
+## The account API
+
+For an app that holds its own session, `createAccountClient` calls the brand's account API for the person signed in:
+
+```ts
+import { accountApiUrl, createAccountClient, createSynqClient, linkSignIn } from '@synqauth/js'
+
+const synq = createSynqClient({
+  issuer: 'https://acme.auth.synq.build',
+  clientId: 'app_…',
+  redirectUri: 'https://app.example.com/callback',
+  scope: 'openid offline_access me:read me:write',
+  resource: accountApiUrl('https://acme.auth.synq.build'),
+})
+const account = createAccountClient({
+  issuer: 'https://acme.auth.synq.build',
+  accessToken: () => synq.getAccessToken(),
+})
+
+const { data: me, error } = await account.me()
+await account.user.update({ name: 'Ada Lovelace' })
+
+// Adding a wallet: a link request, then a fresh sign-in that carries it.
+const { data: request } = await account.accounts.link('wallet')
+if (request) await synq.signIn(linkSignIn(request))
+```
+
+Every call answers `{ data, error }` and never throws for what Synq answers; branch on `error.code`.
+
+## License
+
+MIT

package/dist/api-CeYAjkvX.js

@@ -0,0 +1,467 @@
+import * as oauth from "oauth4webapi";
+import { AuthorizationResponseError, OperationProcessingError, ResponseBodyError, WWWAuthenticateChallengeError } from "oauth4webapi";
+//#region src/errors.ts
+/**
+* Every error the SDK throws. Branch on `code`, which is stable: the API's
+* problem `code`, OAuth's `error`, or one of the SDK's own; never on the
+* message.
+*/
+var SynqError = class extends Error {
+	name = "SynqError";
+	code;
+	/** The HTTP status Synq answered with, when it answered. */
+	status;
+	/** What Synq said about it: OAuth's `error_description` or a problem's `detail`. */
+	description;
+	/**
+	* How many seconds to wait before trying again, from Synq's `Retry-After`:
+	* set on `rate_limited` (429), and wherever else Synq sends one.
+	*/
+	retryAfter;
+	constructor(code, message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.code = code;
+		this.status = options.status;
+		this.description = options.description;
+		this.retryAfter = options.retryAfter;
+	}
+};
+/** Whether `error` is a `SynqError`, with `code` when given. */
+function isSynqError(error, code) {
+	return error instanceof SynqError && (code === void 0 || error.code === code);
+}
+/** A `SynqError` for a problem document a Synq API answered with. */
+function problemError(status, problem, retryAfter) {
+	const code = typeof problem.code === "string" ? problem.code : `http_${status}`;
+	const description = typeof problem.detail === "string" ? problem.detail : void 0;
+	return new SynqError(code, description ?? problem.title ?? `Synq answered ${status}`, {
+		status,
+		description,
+		retryAfter,
+		cause: problem
+	});
+}
+/**
+* The seconds a `Retry-After` header asks for: a number of seconds, or an
+* HTTP date, counted from `now`. Undefined when there is none, or it can't
+* be read.
+*/
+function retryAfterSeconds(header, now = Date.now()) {
+	const value = header?.trim();
+	if (!value) return void 0;
+	if (/^[0-9]+$/.test(value)) return Number(value);
+	if (!/[A-Za-z]/.test(value)) return void 0;
+	const at = Date.parse(value);
+	return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - now) / 1e3));
+}
+/**
+* A `SynqError` for whatever went wrong talking to Synq's issuer: OAuth's
+* error responses keep their `error`, a failed check of Synq's answer is
+* `invalid_response`, and a request that never got an answer is
+* `network_error`.
+*/
+function toSynqError(error) {
+	if (error instanceof SynqError) return error;
+	if (error instanceof ResponseBodyError) return new SynqError(error.error, error.error_description ?? error.error, {
+		status: error.status,
+		description: error.error_description,
+		cause: error
+	});
+	if (error instanceof AuthorizationResponseError) return new SynqError(error.error, error.error_description ?? error.error, {
+		description: error.error_description,
+		cause: error
+	});
+	if (error instanceof WWWAuthenticateChallengeError) {
+		const challenge = error.cause[0];
+		const code = challenge?.parameters.error ?? "invalid_token";
+		const description = challenge?.parameters.error_description;
+		return new SynqError(code, description ?? code, {
+			status: error.status,
+			description,
+			cause: error
+		});
+	}
+	if (error instanceof OperationProcessingError) return new SynqError("invalid_response", error.message, { cause: error });
+	if (error instanceof TypeError) return new SynqError("network_error", `Synq couldn't be reached: ${error.message}`, { cause: error });
+	return new SynqError("invalid_response", error instanceof Error ? error.message : "Synq answered with something unexpected", { cause: error });
+}
+//#endregion
+//#region src/sign-in-flow.ts
+/** A new flow's state: a PKCE verifier and nonce of its own. */
+function newSignIn(scope, options) {
+	return {
+		v: 1,
+		verifier: oauth.generateRandomCodeVerifier(),
+		nonce: oauth.generateRandomNonce(),
+		scope,
+		...options.resource ? { resource: options.resource } : {},
+		...options.additionalResources?.length ? { additionalResources: [...options.additionalResources] } : {},
+		...options.acr ? { acr: options.acr } : {},
+		step: "start"
+	};
+}
+/** A saved flow, checked: one this SDK wrote. */
+function readSavedSignIn(saved) {
+	const value = typeof saved === "string" ? JSON.parse(saved) : saved;
+	if (value?.v !== 1 || typeof value.verifier !== "string" || typeof value.nonce !== "string" || typeof value.scope !== "string" || typeof value.step !== "string") throw new SynqError("invalid_options", "That is not a sign-in this SDK saved");
+	return value;
+}
+/** One sign-in on an app's own screens. */
+var SignInFlow = class {
+	#port;
+	#state;
+	constructor(port, state) {
+		this.#port = port;
+		this.#state = state;
+	}
+	/** What the app's screen asks for now. */
+	get step() {
+		return this.#state.step;
+	}
+	/** The address the sign-in is for, once one was typed. */
+	get address() {
+		return this.#state.email;
+	}
+	/** Email and password. */
+	password = {
+		signIn: (input) => this.#ask(this.#method("password", {
+			username: input.email,
+			password: input.password
+		}), { email: input.email }),
+		/** Makes an account where the brand lets people sign up; its address is verified next. */
+		signUp: (input) => this.#ask(this.#method("password", {
+			username: input.email,
+			password: input.password,
+			synq_screen: "sign-up"
+		}), { email: input.email })
+	};
+	/** A code by email. */
+	email = {
+		send: (email) => this.#ask(this.#method("email", { username: email }), { email }),
+		verify: (code) => this.#ask({ otp: code }),
+		resend: () => this.#ask({ synq_action: "resend" })
+	};
+	/** A passkey: `options()`, then the browser's assertion to `signIn`. */
+	passkey = {
+		options: () => this.#ask(this.#method("passkey", {})),
+		signIn: (credential, options = {}) => this.#ask({
+			synq_passkey: JSON.stringify(credential),
+			...options.related ? { synq_passkey_rp: "related" } : {}
+		})
+	};
+	/** Verifying an address after a sign-in that didn't prove it. */
+	verifyEmail = {
+		verify: (code) => this.#ask({ otp: code }),
+		resend: () => this.#ask({ synq_action: "resend" }),
+		skip: () => this.#ask({ synq_action: "skip" })
+	};
+	/** The flow, to keep between requests (a server's sealed cookie, a phone's secure storage). */
+	toJSON() {
+		return this.#state;
+	}
+	/** Fields that name `method`, which a session already under way switches to. */
+	#method(method, fields) {
+		return {
+			synq_method: method,
+			...fields
+		};
+	}
+	async #ask(fields, changes = {}) {
+		if (this.#state.step === "done") throw new SynqError("invalid_session", "This sign-in has finished: start another");
+		if (changes.email !== void 0) this.#state = {
+			...this.#state,
+			email: changes.email
+		};
+		const answer = await this.#send(fields);
+		return this.#read(answer);
+	}
+	async #send(fields) {
+		const port = this.#port;
+		const server = await port.server();
+		const endpoint = server.authorization_challenge_endpoint;
+		if (typeof endpoint !== "string") throw new SynqError("discovery_failed", "The issuer doesn't sign people in on apps' own screens");
+		const body = new URLSearchParams(fields);
+		const state = this.#state;
+		if (state.authSession) body.set("auth_session", state.authSession);
+		else {
+			body.set("response_type", "code");
+			body.set("scope", state.scope);
+			body.set("nonce", state.nonce);
+			body.set("code_challenge", await oauth.calculatePKCECodeChallenge(state.verifier));
+			body.set("code_challenge_method", "S256");
+			if (state.resource) body.set("resource", state.resource);
+			for (const extra of state.additionalResources ?? []) if (extra !== state.resource) body.append("resource", extra);
+			if (state.acr) {
+				if (state.acr.essential) body.set("claims", JSON.stringify({ id_token: { acr: {
+					essential: true,
+					values: [...state.acr.values]
+				} } }));
+				else body.set("acr_values", state.acr.values.join(" "));
+			}
+		}
+		const headers = new Headers({
+			accept: "application/json",
+			"content-type": "application/x-www-form-urlencoded",
+			...port.headers
+		});
+		await port.auth(server, port.client, body, headers);
+		let response;
+		try {
+			response = await port.fetch(endpoint, {
+				method: "POST",
+				headers,
+				body: body.toString(),
+				redirect: "manual"
+			});
+		} catch (error) {
+			throw toSynqError(error);
+		}
+		let parsed;
+		try {
+			parsed = await response.json();
+		} catch {
+			parsed = void 0;
+		}
+		if (!parsed || typeof parsed !== "object") throw new SynqError("invalid_response", `Synq answered ${response.status} with no JSON`, { status: response.status });
+		return {
+			status: response.status,
+			body: parsed,
+			retryAfter: retryAfterSeconds(response.headers.get("retry-after"))
+		};
+	}
+	async #read(answer) {
+		const { body } = answer;
+		const text = (name) => typeof body[name] === "string" ? body[name] : void 0;
+		const message = text("error_description") ?? "";
+		const problem = text("synq_problem");
+		const session = text("auth_session");
+		if (session) this.#state = {
+			...this.#state,
+			authSession: session
+		};
+		if (answer.status === 200 && typeof body.authorization_code === "string") {
+			this.#state = {
+				...this.#state,
+				step: "done"
+			};
+			return {
+				status: "signed-in",
+				session: await this.#redeem(body.authorization_code)
+			};
+		}
+		const error = text("error");
+		switch (error) {
+			case "insufficient_authorization": return this.#next(body, problem, message);
+			case "redirect_to_web": {
+				this.#state = {
+					...this.#state,
+					step: "done"
+				};
+				const method = text("synq_method");
+				const loginHint = text("login_hint") ?? this.#state.email;
+				return {
+					status: "hosted",
+					reason: text("synq_reason"),
+					...method ? { method } : {},
+					...loginHint ? { loginHint } : {},
+					continue: () => this.#port.hosted({
+						...method ? { method } : {},
+						...loginHint ? { loginHint } : {}
+					})
+				};
+			}
+			case "access_denied":
+				this.#state = {
+					...this.#state,
+					step: "done"
+				};
+				return {
+					status: "refused",
+					reason: text("synq_reason"),
+					message
+				};
+			case "too_many_requests":
+				if (session && problem) return {
+					status: "retry",
+					problem,
+					message,
+					...answer.retryAfter === void 0 ? {} : { retryAfter: answer.retryAfter }
+				};
+				throw new SynqError("too_many_requests", message || "Too many requests", {
+					status: answer.status,
+					description: message,
+					...answer.retryAfter === void 0 ? {} : { retryAfter: answer.retryAfter }
+				});
+			default:
+				if (error === "invalid_session") this.#state = {
+					...this.#state,
+					step: "done"
+				};
+				throw new SynqError(error ?? `http_${answer.status}`, message || `Synq answered ${answer.status}`, {
+					status: answer.status,
+					description: message || void 0
+				});
+		}
+	}
+	/** What Synq asks for next, or the same step again with what went wrong. */
+	#next(body, problem, message) {
+		const next = body.synq_next;
+		const step = next === "otp" ? "code" : next === "verify_email" ? "verify-email" : next === "method" ? "start" : next;
+		this.#state = {
+			...this.#state,
+			step
+		};
+		if (next === "passkey") {
+			const related = body.synq_passkey_related_options;
+			return {
+				status: "passkey",
+				options: body.synq_passkey_options,
+				...related ? { related: {
+					rpId: related.rp_id,
+					options: related.options
+				} } : {},
+				...problem ? {
+					problem,
+					message
+				} : {}
+			};
+		}
+		if (problem) return {
+			status: "retry",
+			problem,
+			message
+		};
+		const email = this.#state.email ?? "";
+		if (next === "otp") {
+			const seconds = typeof body.synq_code_expires_in === "number" ? body.synq_code_expires_in : 0;
+			return {
+				status: "code-sent",
+				email,
+				expiresAt: new Date(Date.now() + seconds * 1e3)
+			};
+		}
+		if (next === "verify_email") return {
+			status: "verify-email",
+			email,
+			canSkip: body.synq_can_skip === true
+		};
+		return {
+			status: "retry",
+			problem: "missing",
+			message
+		};
+	}
+	/** Redeems the code at the token endpoint, with the verifier and no redirect URI. */
+	async #redeem(code) {
+		const port = this.#port;
+		const server = await port.server();
+		if (!server.token_endpoint) throw new SynqError("discovery_failed", "The issuer has no token endpoint");
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			code_verifier: this.#state.verifier
+		});
+		if (this.#state.resource) body.set("resource", this.#state.resource);
+		const headers = new Headers({
+			accept: "application/json",
+			"content-type": "application/x-www-form-urlencoded"
+		});
+		await port.auth(server, port.client, body, headers);
+		try {
+			const response = await port.fetch(server.token_endpoint, {
+				method: "POST",
+				headers,
+				body: body.toString(),
+				redirect: "manual"
+			});
+			const result = await oauth.processAuthorizationCodeResponse(server, port.client, response, {
+				expectedNonce: this.#state.nonce,
+				maxAge: oauth.skipAuthTimeCheck,
+				requireIdToken: true
+			});
+			const claims = oauth.getValidatedIdTokenClaims(result);
+			const acr = this.#state.acr;
+			if (acr?.essential && !(typeof claims?.acr === "string" && acr.values.includes(claims.acr))) throw new SynqError("unmet_authentication_requirements", "The sign-in did not reach the level this app requires");
+			return await port.finish(result, claims);
+		} catch (error) {
+			throw toSynqError(error);
+		}
+	}
+};
+//#endregion
+//#region src/urls.ts
+/** Whether a host is this machine: a Synq stack under `localhost`, or a loopback address. */
+function isLoopback(hostname) {
+	return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+* `value` as a URL, which must be https: Synq's hosts always are. Plain http
+* only on this machine, for a local Synq stack. `what` names it in the error.
+*/
+function secureUrl(value, what) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new SynqError("invalid_options", `${what} isn't a URL: ${String(value)}`);
+	}
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) throw new SynqError("invalid_options", `${what} must be https: (http: only for a Synq stack on this machine, under 'localhost')`);
+	return url;
+}
+//#endregion
+//#region src/api.ts
+function createApiClient(options) {
+	const base = secureUrl(options.baseUrl, "The API base URL").href.replace(/\/+$/, "");
+	const call = (method) => ((path, request = {}) => send(method, path, request));
+	async function send(method, path, request) {
+		const url = new URL(base + fill(path, request.path));
+		for (const [name, value] of Object.entries(request.query ?? {})) {
+			if (value === void 0) continue;
+			for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(name, String(item));
+		}
+		const headers = new Headers({
+			accept: "application/json, application/problem+json",
+			authorization: `Bearer ${await options.credential()}`
+		});
+		if (request.body !== void 0) headers.set("content-type", "application/json");
+		if (request.idempotencyKey) headers.set("idempotency-key", request.idempotencyKey);
+		let response;
+		try {
+			response = await (options.fetch ?? fetch)(url, {
+				method: method.toUpperCase(),
+				headers,
+				body: request.body === void 0 ? void 0 : JSON.stringify(request.body),
+				signal: request.signal
+			});
+		} catch (error) {
+			throw new SynqError("network_error", `Synq couldn't be reached: ${String(error)}`, { cause: error });
+		}
+		const text = await response.text();
+		let json;
+		try {
+			json = text ? JSON.parse(text) : void 0;
+		} catch {
+			json = void 0;
+		}
+		if (!response.ok) throw problemError(response.status, json !== null && typeof json === "object" ? json : {}, retryAfterSeconds(response.headers.get("retry-after")));
+		return json;
+	}
+	return {
+		get: call("get"),
+		post: call("post"),
+		put: call("put"),
+		patch: call("patch"),
+		delete: call("delete")
+	};
+}
+/** The path with each `{name}` replaced by its parameter, encoded. */
+function fill(path, params = {}) {
+	return path.replace(/\{([^}]+)\}/g, (_, name) => {
+		const value = params[name];
+		if (value === void 0 || value === "") throw new SynqError("invalid_options", `The path ${path} needs ${name}`);
+		if (/^\.+$/.test(String(value))) throw new SynqError("invalid_options", `${name} can't be ${String(value)}`);
+		return encodeURIComponent(String(value));
+	});
+}
+//#endregion
+export { readSavedSignIn as a, problemError as c, newSignIn as i, toSynqError as l, secureUrl as n, SynqError as o, SignInFlow as r, isSynqError as s, createApiClient as t };