@synqauth/js 0.0.0-stage → 0.0.0

package/dist/server.d.ts

@@ -0,0 +1,175 @@
+import { c as SynqError, l as isSynqError, r as paths, t as components } from "./management-y9-9AIc-.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;
+/** 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;
+//#endregion
+export { type components as ManagementComponents, type paths as ManagementPaths, SynqError, isSynqError };

package/dist/server.js

@@ -0,0 +1,197 @@
+import { i as isSynqError, n as secureUrl, r as SynqError, t as createApiClient } from "./api-Cf9K1Rc9.js";
+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
+	});
+}
+/**
+* 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
+	});
+}
+//#endregion
+export { SynqError, createAccessTokenVerifier, createManagementClient, 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.0.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"
+  }
 }