@synqauth/js 0.0.0 → 0.2.0

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { c as SynqError, l as isSynqError, r as paths, t as components } from "./management-y9-9AIc-.js";
+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';
@@ -129,6 +129,61 @@ export type AccessTokenVerifier = (token: string, options?: VerifyAccessTokenOpt
  * 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. */
@@ -171,5 +226,56 @@ export type ManagementClient = ApiClient<paths>;
  * 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, SynqError, isSynqError };
+export { type components as ManagementComponents, type paths as ManagementPaths, type SavedSignIn, SignInFlow, type SignInFlowStep, type SignInStepResult, type StartSignInOptions, SynqError, isSynqError };

package/dist/server.js

@@ -1,4 +1,5 @@
-import { i as isSynqError, n as secureUrl, r as SynqError, t as createApiClient } from "./api-Cf9K1Rc9.js";
+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
 /**
@@ -123,6 +124,74 @@ function tokenError(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
@@ -193,5 +262,56 @@ function createManagementClient(options) {
 		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 { SynqError, createAccessTokenVerifier, createManagementClient, isSynqError, verifyWebhook };
+export { SignInFlow, SynqError, createAccessTokenVerifier, createApiKeyVerifier, createManagementClient, createOwnUiSignIn, isApiKey, isSynqError, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synqauth/js",
-  "version": "0.0.0",
+  "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": {

package/dist/api-Cf9K1Rc9.js

@@ -1,163 +0,0 @@
-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/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 { problemError as a, isSynqError as i, secureUrl as n, toSynqError as o, SynqError as r, createApiClient as t };