@synqauth/js 0.0.0-stage → 0.2.0

package/dist/server.d.ts

@@ -0,0 +1,281 @@
+import { A as SignInFlowStep, M as StartSignInOptions, O as SavedSignIn, c as SynqError, j as SignInStepResult, k as SignInFlow, l as isSynqError, m as IdTokenClaims, r as paths, t as components } from "./management-CWdCiiEv.js";
+import { JWTPayload, JWTVerifyGetKey } from "jose";
+//#region src/api.d.ts
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/** The paths of a contract that answer `M`. */
+type PathsWith<Paths, M extends HttpMethod> = { [P in keyof Paths]: Paths[P] extends { readonly [K in M]: infer O; } ? [O] extends [never] ? never : P : never; }[keyof Paths] & string;
+type Operation<Paths, P extends keyof Paths, M extends HttpMethod> = Paths[P] extends { readonly [K in M]: infer O; } ? O : never;
+type PathParams<O> = O extends {
+  readonly parameters: {
+    readonly path: infer X;
+  };
+} ? X : never;
+type QueryParams<O> = O extends {
+  readonly parameters: {
+    readonly query?: infer X;
+  };
+} ? Exclude<X, undefined> : never;
+type JsonBody<O> = O extends {
+  readonly requestBody: {
+    readonly content: {
+      readonly 'application/json': infer B;
+    };
+  };
+} ? B : never;
+type OptionalJsonBody<O> = O extends {
+  readonly requestBody?: {
+    readonly content: {
+      readonly 'application/json': infer B;
+    };
+  };
+} ? B : never;
+/** What a successful call answers: the JSON of its 2xx responses, or nothing for a 204. */
+type Success<O> = O extends {
+  readonly responses: infer R;
+} ? { [S in keyof R]: S extends 200 | 201 | 202 | 203 ? R[S] extends {
+  readonly content: {
+    readonly 'application/json': infer J;
+  };
+} ? J : never : S extends 204 ? undefined : never; }[keyof R] : never;
+type Common = {
+  /** Sent as `Idempotency-Key`: a POST with the same key runs once (the management API keeps the answer 24 hours). */
+  idempotencyKey?: string;
+  signal?: AbortSignal;
+};
+/** The options of one call: its path parameters, query and body, as the contract has them. */
+type RequestOptions<O> = ([PathParams<O>] extends [never] ? {
+  path?: undefined;
+} : {
+  path: PathParams<O>;
+}) & ([QueryParams<O>] extends [never] ? {
+  query?: undefined;
+} : {
+  query?: QueryParams<O>;
+}) & ([JsonBody<O>] extends [never] ? [OptionalJsonBody<O>] extends [never] ? {
+  body?: undefined;
+} : {
+  body?: OptionalJsonBody<O>;
+} : {
+  body: JsonBody<O>;
+}) & Common;
+type Args<O> = object extends RequestOptions<O> ? [options?: RequestOptions<O>] : [options: RequestOptions<O>];
+type Call<Paths, M extends HttpMethod> = <P extends PathsWith<Paths, M>>(path: P, ...args: Args<Operation<Paths, P, M>>) => Promise<Success<Operation<Paths, P, M>>>;
+/** A client for one Synq contract: one method per HTTP method, each typed by the contract. */
+interface ApiClient<Paths> {
+  get: Call<Paths, 'get'>;
+  post: Call<Paths, 'post'>;
+  put: Call<Paths, 'put'>;
+  patch: Call<Paths, 'patch'>;
+  delete: Call<Paths, 'delete'>;
+}
+//#endregion
+//#region src/server.d.ts
+/** What an API checks every access token against. */
+export interface AccessTokenVerifierOptions {
+  /** The brand's issuer URL, as the dashboard shows it. */
+  issuer: string;
+  /** This API's identifier, as registered with Synq: the token's `aud`. */
+  audience: string;
+  /** The algorithms accepted: Synq signs API tokens with ES256. */
+  algorithms?: string[];
+  /** Seconds of clock difference forgiven on `exp`, `iat` and `nbf`: 5 by default. */
+  clockToleranceSeconds?: number;
+  fetch?: typeof fetch;
+  /** The keys to check with, instead of fetching the issuer's JWKS (for tests). */
+  keys?: JWTVerifyGetKey;
+}
+/** What one route wants of a token, on top of the verifier's checks. */
+export interface VerifyAccessTokenOptions {
+  /** Scopes the token must carry, every one. */
+  scopes?: readonly string[];
+  /** The apps (client_ids) whose tokens this route takes (`azp`). */
+  authorizedParties?: readonly string[];
+  /** The longest ago, in seconds, the person may have signed in (`auth_time`): for sensitive actions. */
+  maxAuthAgeSeconds?: number;
+}
+/** A Synq access token's claims (RFC 9068), once checked. */
+export interface AccessTokenClaims {
+  readonly iss: string;
+  /** The person (`usr_…`), or the machine app's client_id for client credentials. */
+  readonly sub: string;
+  readonly aud: string | string[];
+  /** The app the token was issued to. */
+  readonly azp: string | undefined;
+  readonly scopes: readonly string[];
+  readonly iat: number;
+  readonly exp: number;
+  readonly auth_time: number | undefined;
+  readonly acr: string | undefined;
+  readonly amr: readonly string[] | undefined;
+  /** An agent acting for the person (device flow): its client_id. */
+  readonly act: {
+    readonly type?: string;
+    readonly client_id?: string;
+  } | undefined;
+  /** Every claim, as the token carries it. */
+  readonly payload: JWTPayload;
+}
+/**
+ * Checks one access token for your API, as `createAccessTokenVerifier` makes
+ * it: the claims when the token is good, else a `SynqError`
+ * (`invalid_token`, `insufficient_scope` or `fresh_sign_in_required`).
+ */
+export type AccessTokenVerifier = (token: string, options?: VerifyAccessTokenOptions) => Promise<AccessTokenClaims>;
+/**
+ * A verifier for one API's access tokens. It reads the issuer's JWKS once
+ * and keeps it, fetching it again when a token names a key it doesn't have
+ * (a rotation), at most every 30 seconds. A discovery that failed is retried
+ * after 30 seconds, not on every token. Keep one per API, not one per
+ * request. The issuer and its JWKS must be https (http only on this machine).
+ */
+export declare function createAccessTokenVerifier(options: AccessTokenVerifierOptions): AccessTokenVerifier;
+/**
+ * Whether `credential` is one of your users' API keys (`ak_live_…` or
+ * `ak_test_…`, AERO-1693) rather than an access token: what tells an API
+ * which of `createApiKeyVerifier` and `createAccessTokenVerifier` to check
+ * a bearer credential with.
+ */
+export declare function isApiKey(credential: unknown): credential is string;
+/** What an API checks its users' API keys with: the brand's issuer, and the API's own app. */
+export interface ApiKeyVerifierOptions {
+  /** The brand's issuer URL, as the dashboard shows it. */
+  issuer: string;
+  /**
+   * The API's own app (its `client_id` in Synq), the one linked to the API:
+   * only it may check the API's keys.
+   */
+  clientId: string;
+  clientSecret: string;
+  fetch?: typeof fetch;
+}
+/** What one route wants of a key, on top of the verifier's checks. */
+export interface VerifyApiKeyOptions {
+  /** Scopes the key must carry, every one. */
+  scopes?: readonly string[];
+}
+/** One of your users' API keys, once Synq said it works. */
+export interface ApiKeyClaims {
+  readonly iss: string;
+  /** The person who made it (`usr_…`), as in their access tokens' `sub`. */
+  readonly sub: string;
+  /** Your API's identifier: the API it is for. */
+  readonly aud: string;
+  readonly scopes: readonly string[];
+  /** The key's id (`uak_…`), never the key. */
+  readonly keyId: string;
+  /** The name the person gave it. */
+  readonly name: string;
+  /** When it was made, in seconds. */
+  readonly iat: number;
+  /** When it stops working, in seconds; undefined for a key that doesn't expire. */
+  readonly exp: number | undefined;
+}
+/**
+ * Checks one of your users' API keys, as `createApiKeyVerifier` makes it:
+ * the claims when the key works, else a `SynqError` (`invalid_token` for a
+ * key that doesn't, `insufficient_scope` for one without a scope asked for).
+ */
+export type ApiKeyVerifier = (key: string, options?: VerifyApiKeyOptions) => Promise<ApiKeyClaims>;
+/**
+ * A verifier for the API keys your users make for your API (AERO-1693). It
+ * asks the brand's issuer about every key (`POST /api-keys/verify`, as the
+ * API's own app), and keeps nothing: revoking a key works from its next
+ * check. A key Synq says doesn't work is `invalid_token` (401), never why;
+ * your app's credentials refused are `invalid_client`.
+ */
+export declare function createApiKeyVerifier(options: ApiKeyVerifierOptions): ApiKeyVerifier;
+/** A Synq webhook's event: one row of the org's audit log (the management API's `WebhookEvent`). */
+export type WebhookEvent = components['schemas']['WebhookEvent'];
+/** A delivery that passed its check. */
+export interface VerifiedWebhook {
+  /** The delivery's `webhook-id`: the same on every retry, so a receiver drops one it has seen. */
+  readonly id: string;
+  /** When Synq signed it. */
+  readonly timestamp: Date;
+  readonly event: WebhookEvent;
+}
+type HeadersLike = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Checks a delivery's Standard Webhooks signature (`webhook-id`,
+ * `webhook-timestamp`, `webhook-signature`, HMAC-SHA256 over
+ * `<id>.<timestamp>.<body>`) against the subscription's `whsec_` secret, and
+ * that Synq signed it within `toleranceSeconds` (5 minutes by default), so a
+ * captured delivery can't be replayed later. Pass both secrets while one is
+ * being rotated: Synq signs with both for 24 hours. `body` is the request's
+ * raw body, exactly as it arrived.
+ */
+export declare function verifyWebhook(body: string, headers: HeadersLike, secrets: string | readonly string[], options?: {
+  toleranceSeconds?: number;
+  now?: Date;
+}): Promise<VerifiedWebhook>;
+/** Who a management API client acts as. */
+export interface ManagementClientOptions {
+  /** The management API's origin, as the dashboard shows it. */
+  baseUrl: string;
+  /** An org API key (`sk_live_…` or `sk_test_…`): it acts in its own org with the permissions it was given. */
+  apiKey?: string;
+  /** Or a Synq access token, acting as that person: a function so it can be refreshed. */
+  accessToken?: () => string | Promise<string>;
+  fetch?: typeof fetch;
+}
+/** The management API's typed client: every path, parameter, body and answer from its contract. */
+export type ManagementClient = ApiClient<paths>;
+/**
+ * A client for Synq's management API (`/v1`), typed by its contract. Server
+ * only: an API key never reaches a browser. Failures throw a `SynqError`
+ * with the problem's `code`, such as `insufficient_permissions`.
+ */
+export declare function createManagementClient(options: ManagementClientOptions): ManagementClient;
+/** What a server needs to sign people in on its app's own screens (AERO-1411). */
+export interface OwnUiSignInOptions {
+  /** The brand's issuer URL, as the dashboard shows it. */
+  issuer: string;
+  /** The app's client_id: one of the brand's own web apps, with own-UI sign-in on. */
+  clientId: string;
+  /** The app's secret, sent with HTTP Basic, as at the token endpoint. */
+  clientSecret?: string;
+  /** Or the key it signs its client assertions with (`private_key_jwt`). */
+  privateKey?: CryptoKey | {
+    key: CryptoKey;
+    kid?: string;
+  };
+  fetch?: typeof fetch;
+}
+/** What a server's own-UI sign-in ends with: the app keeps them as its session. */
+export interface OwnUiTokens {
+  readonly accessToken: string;
+  readonly tokenType: string;
+  /** When the access token expires, in seconds since the epoch, when Synq said. */
+  readonly expiresAt: number | undefined;
+  readonly scope: string | undefined;
+  readonly idToken: string;
+  readonly refreshToken: string | undefined;
+  /** The ID token's claims, validated: who signed in, and how. */
+  readonly claims: IdTokenClaims;
+}
+/** A server's own-UI sign-ins: one flow per sign-in, kept between requests with `toJSON`. */
+export interface OwnUiSignIn {
+  /**
+   * Starts a sign-in. `endUserIp` is the address the person is at, as your
+   * server saw it: Synq counts per-address limits for your app with it, and
+   * without it counts none.
+   */
+  start(options?: StartSignInOptions & {
+    endUserIp?: string;
+  }): SignInFlow<OwnUiTokens>;
+  /** Picks up the flow `toJSON()` saved, for the next request of the same sign-in. */
+  resume(saved: SavedSignIn | string, options?: {
+    endUserIp?: string;
+  }): SignInFlow<OwnUiTokens>;
+}
+/**
+ * Own-UI sign-in for a server (AERO-1411): its forms post to it, it calls
+ * Synq's Authorization Challenge Endpoint as its app, and a sign-in ends
+ * with tokens, not a cookie at Synq. The app keeps them, and the person's
+ * password or code never reaches a browser but the form they typed it in.
+ * `hosted` results can't `continue()` here: send the browser to an
+ * ordinary authorization request with the `method` and `loginHint` given.
+ */
+export declare function createOwnUiSignIn(options: OwnUiSignInOptions): OwnUiSignIn;
+//#endregion
+export { type components as ManagementComponents, type paths as ManagementPaths, type SavedSignIn, SignInFlow, type SignInFlowStep, type SignInStepResult, type StartSignInOptions, SynqError, isSynqError };

package/dist/server.js

@@ -0,0 +1,317 @@
+import { a as readSavedSignIn, i as newSignIn, n as secureUrl, o as SynqError, r as SignInFlow, s as isSynqError, t as createApiClient } from "./api-CeYAjkvX.js";
+import * as oauth from "oauth4webapi";
+import { createRemoteJWKSet, customFetch, errors, jwtVerify } from "jose";
+//#region src/server.ts
+/**
+* A verifier for one API's access tokens. It reads the issuer's JWKS once
+* and keeps it, fetching it again when a token names a key it doesn't have
+* (a rotation), at most every 30 seconds. A discovery that failed is retried
+* after 30 seconds, not on every token. Keep one per API, not one per
+* request. The issuer and its JWKS must be https (http only on this machine).
+*/
+function createAccessTokenVerifier(options) {
+	const issuer = secureUrl(options.issuer, "The issuer").href.replace(/\/+$/, "");
+	let keys = options.keys ? Promise.resolve(options.keys) : void 0;
+	/** When discovery last failed: it isn't asked again for DISCOVERY_RETRY_MS. */
+	let failedAt = 0;
+	const getKeys = () => {
+		if (!keys && Date.now() - failedAt < DISCOVERY_RETRY_MS) return Promise.reject(new SynqError("discovery_failed", `Synq's discovery document at ${issuer} couldn't be read`, { description: "It failed moments ago; it is asked again 30 seconds after." }));
+		keys ??= discoverKeys(issuer, options.fetch).catch((error) => {
+			keys = void 0;
+			failedAt = Date.now();
+			throw error;
+		});
+		return keys;
+	};
+	return async (token, verify = {}) => {
+		let payload;
+		try {
+			({payload} = await jwtVerify(token, await getKeys(), {
+				issuer,
+				audience: options.audience,
+				algorithms: options.algorithms ?? ["ES256"],
+				typ: "at+jwt",
+				clockTolerance: options.clockToleranceSeconds ?? 5,
+				requiredClaims: [
+					"sub",
+					"iat",
+					"exp"
+				]
+			}));
+		} catch (error) {
+			throw tokenError(error);
+		}
+		const claims = accessTokenClaims(payload);
+		if (verify.authorizedParties && !verify.authorizedParties.includes(claims.azp ?? "")) throw new SynqError("invalid_token", "The token was issued to an app this route takes none from", { status: 401 });
+		const missing = (verify.scopes ?? []).filter((scope) => !claims.scopes.includes(scope));
+		if (missing.length > 0) throw new SynqError("insufficient_scope", `The token lacks ${missing.join(" ")}`, {
+			status: 403,
+			description: missing.join(" ")
+		});
+		if (verify.maxAuthAgeSeconds !== void 0) {
+			const signedInAt = provenSignInTime(claims);
+			if ((signedInAt === void 0 ? Infinity : Date.now() / 1e3 - signedInAt) > verify.maxAuthAgeSeconds) throw new SynqError("fresh_sign_in_required", `This wants a sign-in from the last ${verify.maxAuthAgeSeconds} seconds: sign in again with max_age`, { status: 403 });
+		}
+		return claims;
+	};
+}
+/** How long a failed discovery is remembered before it is asked again. */
+const DISCOVERY_RETRY_MS = 3e4;
+/**
+* When the person signed in, for `maxAuthAgeSeconds`: the token's
+* `auth_time`, or `undefined` when it has none, which fails a recency check
+* closed. Synq itself goes further on its own routes: a sign-in whose time it
+* never saw proved (an upstream provider that says nothing of when, such as
+* Discord) is tracked on the issuer and never counts as fresh there. Tokens
+* carry no mark of it, so an API's own check here is `auth_time` alone; an
+* API that needs the stronger rule sends the person through Synq's
+* `max_age` sign-in.
+*/
+function provenSignInTime(claims) {
+	return claims.auth_time;
+}
+async function discoverKeys(issuer, fetcher) {
+	let jwksUri;
+	try {
+		const response = await (fetcher ?? fetch)(`${issuer}/.well-known/openid-configuration`);
+		if (!response.ok) throw new Error(`discovery answered ${response.status}`);
+		const metadata = await response.json();
+		if (metadata.issuer !== issuer || typeof metadata.jwks_uri !== "string") throw new Error("the discovery document names another issuer, or no JWKS");
+		jwksUri = secureUrl(metadata.jwks_uri, "The issuer's jwks_uri").href;
+	} catch (error) {
+		throw new SynqError("discovery_failed", `Synq's discovery document at ${issuer} couldn't be read`, { cause: error });
+	}
+	return createRemoteJWKSet(new URL(jwksUri), {
+		cooldownDuration: 3e4,
+		cacheMaxAge: 6e5,
+		...fetcher ? { [customFetch]: (url, init) => fetcher(url, init) } : {}
+	});
+}
+function accessTokenClaims(payload) {
+	const string = (value) => typeof value === "string" ? value : void 0;
+	const number = (value) => typeof value === "number" ? value : void 0;
+	const scope = string(payload.scope);
+	const amr = Array.isArray(payload.amr) ? payload.amr.filter((v) => typeof v === "string") : void 0;
+	const act = payload.act !== null && typeof payload.act === "object" ? payload.act : void 0;
+	return {
+		iss: payload.iss,
+		sub: payload.sub,
+		aud: payload.aud,
+		azp: string(payload.azp) ?? string(payload.client_id),
+		scopes: scope ? scope.split(" ").filter(Boolean) : [],
+		iat: payload.iat,
+		exp: payload.exp,
+		auth_time: number(payload.auth_time),
+		acr: string(payload.acr),
+		amr,
+		act,
+		payload
+	};
+}
+function tokenError(error) {
+	if (error instanceof SynqError) return error;
+	if (error instanceof errors.JWTExpired) return new SynqError("token_expired", "The access token has expired", {
+		status: 401,
+		cause: error
+	});
+	if (error instanceof errors.JWKSTimeout || error instanceof TypeError) return new SynqError("network_error", "Synq's keys couldn't be fetched", {
+		status: 503,
+		cause: error
+	});
+	return new SynqError("invalid_token", "The access token is not valid for this API", {
+		status: 401,
+		cause: error
+	});
+}
+/**
+* Whether `credential` is one of your users' API keys (`ak_live_…` or
+* `ak_test_…`, AERO-1693) rather than an access token: what tells an API
+* which of `createApiKeyVerifier` and `createAccessTokenVerifier` to check
+* a bearer credential with.
+*/
+function isApiKey(credential) {
+	return typeof credential === "string" && /^ak_(live|test)_[A-Za-z0-9_-]{43}$/.test(credential);
+}
+/**
+* A verifier for the API keys your users make for your API (AERO-1693). It
+* asks the brand's issuer about every key (`POST /api-keys/verify`, as the
+* API's own app), and keeps nothing: revoking a key works from its next
+* check. A key Synq says doesn't work is `invalid_token` (401), never why;
+* your app's credentials refused are `invalid_client`.
+*/
+function createApiKeyVerifier(options) {
+	const issuer = secureUrl(options.issuer, "The issuer").href.replace(/\/+$/, "");
+	if (!options.clientId || !options.clientSecret) throw new SynqError("invalid_options", "Give the API key verifier your API's own app: its clientId and clientSecret");
+	const form = (value) => encodeURIComponent(value).replace(/%20/g, "+");
+	const basic = btoa(`${form(options.clientId)}:${form(options.clientSecret)}`);
+	const fetcher = options.fetch ?? fetch;
+	return async (key, verify = {}) => {
+		if (!isApiKey(key)) throw new SynqError("invalid_token", "The API key is not valid for this API", { status: 401 });
+		let response;
+		try {
+			response = await fetcher(`${issuer}/api-keys/verify`, {
+				method: "POST",
+				headers: {
+					authorization: `Basic ${basic}`,
+					"content-type": "application/x-www-form-urlencoded"
+				},
+				body: new URLSearchParams({ token: key }).toString()
+			});
+		} catch (error) {
+			throw new SynqError("network_error", "Synq couldn't be reached to check the API key", {
+				status: 503,
+				cause: error
+			});
+		}
+		const body = await response.json().catch(() => void 0);
+		if (!response.ok) {
+			const error = typeof body?.error === "string" ? body.error : void 0;
+			const retryAfter = Number(response.headers.get("retry-after"));
+			throw new SynqError(error === "invalid_client" ? "invalid_client" : response.status === 429 ? "rate_limited" : "server_error", `Synq refused to check the API key (${response.status})`, {
+				status: response.status,
+				description: typeof body?.error_description === "string" ? body.error_description : void 0,
+				retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0
+			});
+		}
+		if (body?.active !== true) throw new SynqError("invalid_token", "The API key is not valid for this API", { status: 401 });
+		const string = (value) => typeof value === "string" ? value : "";
+		const claims = {
+			iss: string(body.iss),
+			sub: string(body.sub),
+			aud: string(body.aud),
+			scopes: string(body.scope).split(" ").filter(Boolean),
+			keyId: string(body.key_id),
+			name: string(body.name),
+			iat: typeof body.iat === "number" ? body.iat : 0,
+			exp: typeof body.exp === "number" ? body.exp : void 0
+		};
+		if (claims.iss !== issuer) throw new SynqError("invalid_response", "Synq's answer names another issuer", { status: 502 });
+		const missing = (verify.scopes ?? []).filter((scope) => !claims.scopes.includes(scope));
+		if (missing.length > 0) throw new SynqError("insufficient_scope", `The API key lacks ${missing.join(", ")}`, { status: 403 });
+		return claims;
+	};
+}
+/**
+* Checks a delivery's Standard Webhooks signature (`webhook-id`,
+* `webhook-timestamp`, `webhook-signature`, HMAC-SHA256 over
+* `<id>.<timestamp>.<body>`) against the subscription's `whsec_` secret, and
+* that Synq signed it within `toleranceSeconds` (5 minutes by default), so a
+* captured delivery can't be replayed later. Pass both secrets while one is
+* being rotated: Synq signs with both for 24 hours. `body` is the request's
+* raw body, exactly as it arrived.
+*/
+async function verifyWebhook(body, headers, secrets, options = {}) {
+	const id = header(headers, "webhook-id");
+	const timestamp = header(headers, "webhook-timestamp");
+	const signatures = header(headers, "webhook-signature");
+	if (!id || !timestamp || !signatures) throw new SynqError("invalid_signature", "The delivery is missing its webhook-* headers");
+	const seconds = Number(timestamp);
+	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3;
+	if (!Number.isInteger(seconds) || Math.abs(now - seconds) > (options.toleranceSeconds ?? 300)) throw new SynqError("stale_webhook", "The delivery was signed too long ago, or in the future");
+	const message = new TextEncoder().encode(`${id}.${seconds}.${body}`);
+	const given = signatures.split(" ").filter((signature) => signature.startsWith("v1,")).map((signature) => fromBase64(signature.slice(3))).filter((bytes) => bytes !== void 0);
+	for (const secret of typeof secrets === "string" ? [secrets] : secrets) {
+		const raw = fromBase64(secret.replace(/^whsec_/, ""));
+		if (!raw) throw new SynqError("invalid_options", "A webhook secret is not a whsec_ secret");
+		const key = await crypto.subtle.importKey("raw", raw, {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["verify"]);
+		for (const signature of given) if (await crypto.subtle.verify("HMAC", key, signature, message)) {
+			let event;
+			try {
+				event = JSON.parse(body);
+			} catch (error) {
+				throw new SynqError("invalid_signature", "The signed body is not JSON", { cause: error });
+			}
+			return {
+				id,
+				timestamp: /* @__PURE__ */ new Date(seconds * 1e3),
+				event
+			};
+		}
+	}
+	throw new SynqError("invalid_signature", "The delivery's signature matches none of the secrets");
+}
+function header(headers, name) {
+	if (headers instanceof Headers) return headers.get(name) ?? void 0;
+	const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+	return Array.isArray(entry) ? entry.join(" ") : entry;
+}
+function fromBase64(value) {
+	try {
+		const binary = atob(value);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	} catch {
+		return;
+	}
+}
+/**
+* A client for Synq's management API (`/v1`), typed by its contract. Server
+* only: an API key never reaches a browser. Failures throw a `SynqError`
+* with the problem's `code`, such as `insufficient_permissions`.
+*/
+function createManagementClient(options) {
+	const { apiKey, accessToken } = options;
+	if (!apiKey === !accessToken) throw new SynqError("invalid_options", "Give the management client an apiKey or an accessToken");
+	return createApiClient({
+		baseUrl: options.baseUrl,
+		credential: apiKey ? () => apiKey : accessToken,
+		fetch: options.fetch
+	});
+}
+/**
+* Own-UI sign-in for a server (AERO-1411): its forms post to it, it calls
+* Synq's Authorization Challenge Endpoint as its app, and a sign-in ends
+* with tokens, not a cookie at Synq. The app keeps them, and the person's
+* password or code never reaches a browser but the form they typed it in.
+* `hosted` results can't `continue()` here: send the browser to an
+* ordinary authorization request with the `method` and `loginHint` given.
+*/
+function createOwnUiSignIn(options) {
+	const issuer = secureUrl(options.issuer, "The issuer");
+	if (!options.clientId) throw new SynqError("invalid_options", "The clientId is missing");
+	if (!options.clientSecret === !options.privateKey) throw new SynqError("invalid_options", "Give createOwnUiSignIn a clientSecret or a privateKey");
+	const auth = options.clientSecret ? oauth.ClientSecretBasic(options.clientSecret) : oauth.PrivateKeyJwt(options.privateKey);
+	const http = {};
+	if (options.fetch) http[oauth.customFetch] = options.fetch;
+	if (issuer.protocol === "http:") http[oauth.allowInsecureRequests] = true;
+	let server;
+	const discover = () => server ??= (async () => {
+		try {
+			const response = await oauth.discoveryRequest(issuer, {
+				...http,
+				algorithm: "oidc"
+			});
+			return await oauth.processDiscoveryResponse(issuer, response);
+		} catch (error) {
+			server = void 0;
+			throw new SynqError("discovery_failed", `Synq's discovery document at ${issuer.href} couldn't be read`, { cause: error });
+		}
+	})();
+	const port = (endUserIp) => ({
+		server: discover,
+		client: { client_id: options.clientId },
+		auth,
+		fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+		...endUserIp ? { headers: { "synq-end-user-ip": endUserIp } } : {},
+		finish: (result, claims) => Promise.resolve({
+			accessToken: result.access_token,
+			tokenType: result.token_type,
+			expiresAt: result.expires_in === void 0 ? void 0 : Math.floor(Date.now() / 1e3) + result.expires_in,
+			scope: result.scope,
+			idToken: result.id_token,
+			refreshToken: result.refresh_token,
+			claims
+		}),
+		hosted: () => Promise.reject(new SynqError("redirect_to_web", "Only the hosted page can go on: send the browser to an authorization request with this result's method and loginHint"))
+	});
+	return {
+		start: ({ endUserIp, ...rest } = {}) => new SignInFlow(port(endUserIp), newSignIn(rest.scope ?? "openid", rest)),
+		resume: (saved, { endUserIp } = {}) => new SignInFlow(port(endUserIp), readSavedSignIn(saved))
+	};
+}
+//#endregion
+export { SignInFlow, SynqError, createAccessTokenVerifier, createApiKeyVerifier, createManagementClient, createOwnUiSignIn, isApiKey, isSynqError, verifyWebhook };

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@synqauth/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Synq's framework-agnostic client: sign-in and sessions in the browser, the account API, and token and webhook verification on your server.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerosol-build/synq.git",
+    "directory": "packages/js"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "5.0.2",
+    "openapi-typescript": "7.13.0",
+    "vitest": "5.0.2"
+  },
+  "dependencies": {
+    "oauth4webapi": "3.8.8",
+    "jose": "6.2.12"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "generate": "node scripts/generate.ts",
+    "lint": "eslint . && node scripts/generate.ts --check",
+    "typecheck": "tsc",
+    "test": "vitest run --coverage"
+  }
 }