@theholocron/holocron-plugin-clerk 2.0.0-alpha.9 → 2.0.0

package/README.md

@@ -5,8 +5,10 @@ against [Clerk's Backend REST API](https://clerk.com/docs/reference/backend-api)
 
 ## Install
 
+<!-- prettier-ignore -->
 ```bash
 pnpm add -D @theholocron/holocron-plugin-clerk@alpha
+
 ```
 
 ## Auth
@@ -24,12 +26,14 @@ api …`, but the `clerk` CLI just wraps the same REST API holocron talks to.
 
 ## Config
 
+<!-- prettier-ignore -->
 ```jsonc
 {
-	"providers": {
-		"auth": "clerk",
-	},
+  "providers": {
+    "auth": "clerk",
+  },
 }
+
 ```
 
 No plugin-level options today. Per-instance scoping (Development vs.

package/dist/index.d.mts

@@ -1,67 +1,16 @@
-import { Auth, AuthDescription, AuthEvent, AuthIdentity, AuthUser, CreateAuthUserInput, ParseWebhookInput, WebhookDashboardInfo } from "@theholocron/cli";
+import { Auth, AuthDescription, AuthError, AuthEvent, AuthIdentity, AuthUser, CreateAuthUserInput, ParseWebhookInput, ResolveTokenInput, WebhookDashboardInfo } from "@theholocron/cli";
+import { ClerkClient, createClerkClient } from "@theholocron/clerk-client";
 
 //#region src/auth.d.ts
-/**
- * Token resolution for the Clerk plugin.
- *
- * Resolution order (matches the standard 4-step precedence set by
- * `.notes/tech-auth-bootstrap.spec.md`):
- *   1. explicit `cliToken` argument (from `--token` flag)
- *   2. HOLOCRON_CLERK_SECRET_KEY env var (preferred — explicit intent)
- *   3. CLERK_SECRET_KEY env var (the default Clerk's docs reference)
- *   4. keyring (com.theholocron.cli / "clerk")
- *   5. AuthError naming all four options + the bootstrap hint
- *
- * The key (sk_test_* / sk_live_*) determines which Clerk instance —
- * Development or Production — every call hits.
- */
-declare class AuthError extends Error {
-  name: string;
-}
-interface ResolveTokenInput {
-  /** From `--token` CLI flag. */
-  cliToken?: string;
-  /** Env vars; passed in for testability. Defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv;
-  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
-  keyring?: (provider: string) => string | null;
-}
-declare function resolveToken(input?: ResolveTokenInput): string;
-//#endregion
-//#region src/rest.d.ts
-/**
- * Thin REST wrapper around api.clerk.com/v1.
- *
- * Same pattern as the github/vercel/neon REST clients — bearer auth,
- * JSON-only bodies, transport-failure wrapping with `status: 0` so the
- * orchestrator's soft-skip path sees a clear "Clerk GET /path failed"
- * message instead of a generic `TypeError: fetch failed`.
- */
-interface RestClientOptions {
-  token: string;
-  fetch?: typeof fetch;
-  baseUrl?: string;
-}
-interface RequestOptions {
-  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
-  body?: unknown;
-  query?: Record<string, string>;
-}
-declare class ClerkRestClient {
-  private readonly token;
-  private readonly fetchImpl;
-  readonly baseUrl: string;
-  constructor(opts: RestClientOptions);
-  request<T>(path: string, opts?: RequestOptions): Promise<T>;
-}
+declare const resolveToken: (input?: import("@theholocron/http-client").ResolveTokenInput) => string;
 //#endregion
 //#region src/capabilities/auth.d.ts
 type ClerkAuthOptions = Record<string, never>;
 declare class ClerkAuth implements Auth {
-  private readonly rest;
+  private readonly client;
   readonly key: "auth";
   readonly providerName = "clerk";
-  constructor(rest: ClerkRestClient, _opts?: ClerkAuthOptions);
+  constructor(client: ClerkClient, _opts?: ClerkAuthOptions);
   describe(): Promise<AuthDescription>;
   whoami(): Promise<AuthIdentity>;
   ensureWebhookApp(): Promise<{
@@ -109,7 +58,7 @@ interface ClerkPluginOptions extends ResolveTokenInput {
 }
 interface PluginContext {
   options: ClerkPluginOptions;
-  rest: ClerkRestClient;
+  client: ClerkClient;
 }
 declare function createContext(options?: ClerkPluginOptions): PluginContext;
 declare function auth(ctx: PluginContext): Auth;
@@ -127,4 +76,4 @@ declare function createPlugin(options?: ClerkPluginOptions): {
  */
 declare const AUTH_HINT: string;
 //#endregion
-export { AUTH_HINT, AuthError, ClerkAuth, ClerkPluginOptions, ClerkRestClient, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, auth, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };
+export { AUTH_HINT, AuthError, ClerkAuth, ClerkPluginOptions, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, auth, createClerkClient, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };

package/dist/index.mjs

@@ -1,29 +1,13 @@
-import { ProviderApiError, WebhookVerificationError, getToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, WebhookVerificationError, createResolveToken } from "@theholocron/cli";
+import { createClerkClient } from "@theholocron/clerk-client";
+import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/auth.ts
-/**
-* Token resolution for the Clerk plugin.
-*
-* Resolution order (matches the standard 4-step precedence set by
-* `.notes/tech-auth-bootstrap.spec.md`):
-*   1. explicit `cliToken` argument (from `--token` flag)
-*   2. HOLOCRON_CLERK_SECRET_KEY env var (preferred — explicit intent)
-*   3. CLERK_SECRET_KEY env var (the default Clerk's docs reference)
-*   4. keyring (com.theholocron.cli / "clerk")
-*   5. AuthError naming all four options + the bootstrap hint
-*
-* The key (sk_test_* / sk_live_*) determines which Clerk instance —
-* Development or Production — every call hits.
-*/
-var AuthError = class extends Error {
-	name = "AuthError";
-};
-function resolveToken(input = {}) {
-	const env = input.env ?? process.env;
-	const keyring = input.keyring ?? getToken;
-	const token = input.cliToken || env["HOLOCRON_CLERK_SECRET_KEY"] || env["CLERK_SECRET_KEY"] || keyring("clerk");
-	if (!token) throw new AuthError("no Clerk secret key found. Pass --token <KEY>, set HOLOCRON_CLERK_SECRET_KEY / CLERK_SECRET_KEY, or run: holocron auth set clerk <KEY>");
-	return token;
-}
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_CLERK_SECRET_KEY",
+	vendorEnvName: "CLERK_SECRET_KEY",
+	keyringService: "clerk",
+	errorMessage: "no Clerk secret key found. Pass --token <KEY>, set HOLOCRON_CLERK_SECRET_KEY / CLERK_SECRET_KEY, or run: holocron auth set clerk <KEY>"
+});
 //#endregion
 //#region src/capabilities/auth.ts
 /**
@@ -52,11 +36,11 @@ function resolveToken(input = {}) {
 * no per-call instance switch.
 */
 var ClerkAuth = class {
-	rest;
+	client;
 	key = "auth";
 	providerName = "clerk";
-	constructor(rest, _opts = {}) {
-		this.rest = rest;
+	constructor(client, _opts = {}) {
+		this.client = client;
 	}
 	async describe() {
 		return {
@@ -67,12 +51,12 @@ var ClerkAuth = class {
 	async whoami() {
 		return {
 			provider: "clerk",
-			details: { userCount: (await this.rest.request("/users/count")).total_count }
+			details: { userCount: (await this.client.users.count()).total_count }
 		};
 	}
 	async ensureWebhookApp() {
 		try {
-			await this.rest.request("/webhooks/svix", { method: "POST" });
+			await this.client.webhooks.ensureSvixApp();
 			return { alreadyExists: false };
 		} catch (err) {
 			if (err instanceof ProviderApiError && isAlreadyExistsError(err)) return { alreadyExists: true };
@@ -80,24 +64,21 @@ var ClerkAuth = class {
 		}
 	}
 	async getWebhookDashboardUrl() {
-		const body = await this.rest.request("/webhooks/svix_url", { method: "POST" });
+		const body = await this.client.webhooks.getSvixUrl();
 		const url = body.url ?? body.svix_url;
 		if (!url) throw new ProviderApiError("Clerk POST /webhooks/svix_url returned 200 but no `url` field", 500, void 0);
 		return { url };
 	}
 	async createUser(input) {
-		const body = await this.rest.request("/users", {
-			method: "POST",
-			body: {
-				email_address: [input.email],
-				password: input.password,
-				...input.firstName ? { first_name: input.firstName } : {},
-				...input.lastName ? { last_name: input.lastName } : {}
-			}
+		const user = await this.client.users.create({
+			email_address: [input.email],
+			password: input.password,
+			...input.firstName ? { first_name: input.firstName } : {},
+			...input.lastName ? { last_name: input.lastName } : {}
 		});
-		const email = body.email_addresses[0]?.email_address ?? input.email;
+		const email = user.email_addresses[0]?.email_address ?? input.email;
 		return {
-			id: body.id,
+			id: user.id,
 			email
 		};
 	}
@@ -115,84 +96,26 @@ function isAlreadyExistsError(err) {
 	return false;
 }
 //#endregion
-//#region src/rest.ts
-/**
-* Thin REST wrapper around api.clerk.com/v1.
-*
-* Same pattern as the github/vercel/neon REST clients — bearer auth,
-* JSON-only bodies, transport-failure wrapping with `status: 0` so the
-* orchestrator's soft-skip path sees a clear "Clerk GET /path failed"
-* message instead of a generic `TypeError: fetch failed`.
-*/
-var ClerkRestClient = class {
-	token;
-	fetchImpl;
-	baseUrl;
-	constructor(opts) {
-		this.token = opts.token;
-		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		let url = opts.baseUrl ?? "https://api.clerk.com/v1";
-		while (url.endsWith("/")) url = url.slice(0, -1);
-		this.baseUrl = url;
-	}
-	async request(path, opts = {}) {
-		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
-		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
-		const fullUrl = url.toString();
-		const headers = {
-			authorization: `Bearer ${this.token}`,
-			accept: "application/json"
-		};
-		const init = {
-			method: opts.method ?? "GET",
-			headers
-		};
-		if (opts.body !== void 0) {
-			headers["content-type"] = "application/json";
-			init.body = JSON.stringify(opts.body);
-		}
-		let res;
-		try {
-			res = await this.fetchImpl(fullUrl, init);
-		} catch (err) {
-			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
-			throw new ProviderApiError(`Clerk ${init.method} ${path} failed: ${detail}`, 0, void 0);
-		}
-		if (!res.ok) {
-			const body = await res.text().catch(() => "");
-			throw new ProviderApiError(`Clerk ${init.method} ${path} → ${res.status}`, res.status, body);
-		}
-		if (res.status === 204) return void 0;
-		const text = await res.text();
-		if (!text) return void 0;
-		return JSON.parse(text);
-	}
-};
-//#endregion
 //#region src/parse-webhook.ts
 /**
 * Translates a Clerk webhook delivery into the normalized `AuthEvent`
-* shape defined in `@theholocron/cli`. The first concrete example of
-* the cross-provider sync pattern (see `AuthEvent` JSDoc in core).
-*
-* Status: signature SHIPPED, body STUBBED. Real Svix signature
-* verification (HMAC-SHA256 over `svix-id.svix-timestamp.body` with
-* the `whsec_…` signing secret, base64-decoded) lands in a follow-up
-* (tracked at #80). For now, parseWebhook trusts the request and
-* focuses on shape translation — usable in environments where
-* signature verification happens upstream (e.g., Vercel middleware,
-* an API gateway), and an explicit error in production-grade
-* deployments until the verification body lands.
+* shape defined in `@theholocron/cli`, with full Svix HMAC-SHA256
+* signature verification (closes #80).
 *
-* Reference event shapes:
-*   https://clerk.com/docs/integrations/webhooks/overview
-*   https://clerk.com/docs/reference/backend-api/tag/Webhooks
+* Verification algorithm (https://docs.svix.com/receiving/verifying-payloads/how-manual):
+*   1. Require svix-id, svix-timestamp, svix-signature headers
+*   2. Reject if svix-timestamp is outside the ±5-minute replay window
+*   3. Decode the whsec_<base64> signing secret
+*   4. Compute HMAC-SHA256(secretBytes, "${id}.${timestamp}.${body}")
+*   5. Constant-time compare against each v1,<base64> signature in the
+*      space-separated svix-signature header (supports key rotation)
 */
 const CLERK_TO_NORMALIZED = {
 	"user.created": "user.created",
 	"user.updated": "user.updated",
 	"user.deleted": "user.deleted"
 };
+const REPLAY_WINDOW_SECONDS = 300;
 async function parseWebhook(input) {
 	await verifySignature(input);
 	const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
@@ -218,22 +141,37 @@ async function parseWebhook(input) {
 		occurredAt
 	};
 }
-/**
-* Stub for Svix signature verification. The real implementation
-* lands at #80 and will:
-*
-*   1. Read svix-id, svix-timestamp, svix-signature headers
-*   2. Verify svix-timestamp is within the replay window (±5 min)
-*   3. Compute HMAC-SHA256(<signing_secret>, `${id}.${timestamp}.${body}`)
-*   4. Compare (constant-time) against the base64 sig in svix-signature
-*
-* For now: throw WebhookVerificationError when the signing secret is
-* missing, so consumers see the contract; let the call through
-* otherwise (signature-validation TODO).
-*/
 async function verifySignature(input) {
 	if (!input.signingSecret) throw new WebhookVerificationError("Clerk webhook signingSecret is required (use the Svix whsec_… value from the Clerk dashboard)");
-	return Promise.resolve();
+	const lower = (s) => s.toLowerCase();
+	const h = (name) => {
+		const target = lower(name);
+		for (const [k, v] of Object.entries(input.headers)) if (lower(k) === target) return Array.isArray(v) ? v[0] : v;
+	};
+	const svixId = h("svix-id");
+	const svixTimestamp = h("svix-timestamp");
+	const svixSignature = h("svix-signature");
+	if (!svixId || !svixTimestamp || !svixSignature) throw new WebhookVerificationError("Missing required Svix headers: svix-id, svix-timestamp, svix-signature");
+	const ts = parseInt(svixTimestamp, 10);
+	if (isNaN(ts)) throw new WebhookVerificationError(`Invalid svix-timestamp: "${svixTimestamp}"`);
+	const nowSeconds = Math.floor(Date.now() / 1e3);
+	if (Math.abs(nowSeconds - ts) > REPLAY_WINDOW_SECONDS) throw new WebhookVerificationError(`Message timestamp is outside the ${REPLAY_WINDOW_SECONDS / 60}-minute replay window`);
+	const secretBase64 = input.signingSecret.startsWith("whsec_") ? input.signingSecret.slice(6) : input.signingSecret;
+	const secretBytes = Buffer.from(secretBase64, "base64");
+	const toSign = `${svixId}.${svixTimestamp}.${typeof input.body === "string" ? input.body : input.body.toString("utf8")}`;
+	const computed = createHmac("sha256", secretBytes).update(toSign).digest();
+	if (!svixSignature.split(" ").some((sig) => {
+		const comma = sig.indexOf(",");
+		if (comma === -1 || sig.slice(0, comma) !== "v1") return false;
+		let sigBytes;
+		try {
+			sigBytes = Buffer.from(sig.slice(comma + 1), "base64");
+		} catch {
+			return false;
+		}
+		if (sigBytes.length !== computed.length) return false;
+		return timingSafeEqual(sigBytes, computed);
+	})) throw new WebhookVerificationError("Svix signature verification failed");
 }
 //#endregion
 //#region src/verify-token.ts
@@ -248,15 +186,16 @@ async function verifySignature(input) {
 * canonical "is this secret key valid?" endpoint.
 */
 async function verifyToken(token, opts = {}) {
-	const restOpts = { token };
-	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
-	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
-	const rest = new ClerkRestClient(restOpts);
+	const client = createClerkClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
 	try {
-		const instance = await rest.request("/instance");
+		const inst = await client.instance.get();
 		return {
 			ok: true,
-			subject: `${instance?.environment_type ?? "unknown"} instance ${instance?.id ?? "unknown"}`
+			subject: `${inst?.environment_type ?? "unknown"} instance ${inst?.id ?? "unknown"}`
 		};
 	} catch (err) {
 		return {
@@ -268,16 +207,17 @@ async function verifyToken(token, opts = {}) {
 //#endregion
 //#region src/index.ts
 function createContext(options = {}) {
-	const restOpts = { token: resolveToken(options) };
-	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
-	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
 	return {
 		options,
-		rest: new ClerkRestClient(restOpts)
+		client: createClerkClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
 	};
 }
 function auth(ctx) {
-	return new ClerkAuth(ctx.rest);
+	return new ClerkAuth(ctx.client);
 }
 function createPlugin(options = {}) {
 	const ctx = createContext(options);
@@ -294,4 +234,4 @@ function createPlugin(options = {}) {
 */
 const AUTH_HINT = "grab your SECRET key (sk_test_* / sk_live_*) at https://dashboard.clerk.com → API Keys, then run: holocron auth set clerk <KEY>. Do NOT use the publishable key.";
 //#endregion
-export { AUTH_HINT, AuthError, ClerkAuth, ClerkRestClient, auth, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };
+export { AUTH_HINT, AuthError, ClerkAuth, auth, createClerkClient, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-clerk",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0",
   "description": "Holocron plugin for Clerk. Implements the auth capability against Clerk's Backend REST API.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-clerk#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,19 +21,26 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.9"
+    "@theholocron/clerk-client": "^1.1.0",
+    "@theholocron/cli": "2.0.0"
   },
   "devDependencies": {
-    "@theholocron/tsconfig": "^4.1.0",
-    "@tsconfig/node-lts": "^24.0.0",
-    "@vitest/coverage-v8": "^3.2.6",
-    "eslint": "^9.36.0",
-    "globals": "^16.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.6",
+    "@theholocron/clerk-client": "^1.1.0",
+    "@theholocron/eslint-config": "^7.3.0",
+    "@theholocron/tsconfig": "^7.3.0",
+    "@theholocron/tsdown-config": "^7.3.0",
+    "@theholocron/vitest-config": "^7.3.0",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "eslint": "^10.7.0",
+    "eslint-plugin-n": "^18.2.2",
+    "globals": "^17.7.0",
     "tsdown": "^0.22.3",
     "tsx": "^4.22.4",
-    "@theholocron/cli": "2.0.0-alpha.9"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "2.0.0"
   },
   "publishConfig": {
     "access": "public"