@theholocron/holocron-plugin-clerk 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+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

@@ -0,0 +1,48 @@
+# `@theholocron/holocron-plugin-clerk`
+
+Clerk plugin for [Holocron](../cli). Implements the `auth` capability
+against [Clerk's Backend REST API](https://clerk.com/docs/reference/backend-api).
+
+## Auth
+
+Token resolution order:
+
+1. `--token <KEY>` flag on the holocron invocation
+2. `HOLOCRON_CLERK_SECRET_KEY` env var
+3. `CLERK_SECRET_KEY` env var (Clerk's own default; what their docs reference)
+
+> **Why not the `clerk` CLI?** Rando's adapter shells out to `npx clerk@latest
+> api …`, but the `clerk` CLI just wraps the same REST API holocron talks to.
+> Direct REST drops a system-binary dependency and matches the uniform auth/REST
+> pattern across the other holocron plugins.
+
+## Config
+
+```jsonc
+{
+  "providers": {
+    "auth": "clerk"
+  }
+}
+```
+
+No plugin-level options today. Per-instance scoping (Development vs.
+Production) is driven by which secret key the env var holds — `sk_test_*`
+for Development, `sk_live_*` for Production.
+
+## What's implemented
+
+| Method                    | What it does                                                                  |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `describe`                | Declares `CLERK_PUBLISHABLE_KEY` + `CLERK_SECRET_KEY` as runtime envs        |
+| `whoami`                  | `GET /users/count` reachability probe (returns user count)                    |
+| `ensureWebhookApp`        | `POST /webhooks/svix` — idempotent; already-exists → `{alreadyExists:true}`  |
+| `getWebhookDashboardUrl`  | `POST /webhooks/svix_url` — deep-link to Svix dashboard                       |
+| `createUser`              | `POST /users` — seeds users (test fixtures, admin bootstrap)                  |
+
+## Status
+
+**v0.0.0 — first port.** Capability matches Rando's
+`adapters/clerk-cli.ts` surface plus a holocron-native `describe()`,
+all via direct REST against `api.clerk.com/v1`. No `clerk` CLI binary
+required on the operator's machine.

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+import { Auth, AuthDescription, AuthEvent, AuthIdentity, AuthUser, CreateAuthUserInput, ParseWebhookInput, WebhookDashboardInfo } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the Clerk plugin.
+ *
+ * Resolution order:
+ *   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)
+ *
+ * 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;
+}
+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>;
+}
+//#endregion
+//#region src/capabilities/auth.d.ts
+type ClerkAuthOptions = Record<string, never>;
+declare class ClerkAuth implements Auth {
+  private readonly rest;
+  readonly key: "auth";
+  readonly providerName = "clerk";
+  constructor(rest: ClerkRestClient, _opts?: ClerkAuthOptions);
+  describe(): Promise<AuthDescription>;
+  whoami(): Promise<AuthIdentity>;
+  ensureWebhookApp(): Promise<{
+    alreadyExists: boolean;
+  }>;
+  getWebhookDashboardUrl(): Promise<WebhookDashboardInfo>;
+  createUser(input: CreateAuthUserInput): Promise<AuthUser>;
+}
+//#endregion
+//#region src/parse-webhook.d.ts
+declare function parseWebhook(input: ParseWebhookInput): Promise<AuthEvent>;
+//#endregion
+//#region src/index.d.ts
+interface ClerkPluginOptions extends ResolveTokenInput {
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: ClerkPluginOptions;
+  rest: ClerkRestClient;
+}
+declare function createContext(options?: ClerkPluginOptions): PluginContext;
+declare function auth(ctx: PluginContext): Auth;
+declare function createPlugin(options?: ClerkPluginOptions): {
+  name: string;
+  capabilities: {
+    auth: () => Auth;
+  };
+};
+//#endregion
+export { AuthError, ClerkAuth, ClerkPluginOptions, ClerkRestClient, PluginContext, ResolveTokenInput, auth, createContext, createPlugin, parseWebhook, resolveToken };

package/dist/index.mjs

@@ -0,0 +1,254 @@
+import { ProviderApiError, WebhookVerificationError } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the Clerk plugin.
+*
+* Resolution order:
+*   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)
+*
+* 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 token = input.cliToken || env.HOLOCRON_CLERK_SECRET_KEY || env.CLERK_SECRET_KEY;
+	if (!token) throw new AuthError("no Clerk secret key found. Pass --token <KEY>, or set HOLOCRON_CLERK_SECRET_KEY / CLERK_SECRET_KEY.");
+	return token;
+}
+//#endregion
+//#region src/capabilities/auth.ts
+/**
+* `auth` capability for Clerk.
+*
+* Ported from rando-id/rando.id `adapters/clerk-cli.ts`, swapped from
+* shell-out (`npx clerk@latest api ...`) to direct REST against
+* api.clerk.com/v1.
+*
+* Surface mirrors the Rando shape:
+*
+*  - `whoami` — `GET /users/count`. Cheap reachability probe; the user
+*    count doubles as a sanity signal for the operator.
+*  - `ensureWebhookApp` — `POST /webhooks/svix`. Idempotent — if a Svix
+*    app already exists, the API returns an error containing "already";
+*    we suppress it and return `{ alreadyExists: true }`.
+*  - `getWebhookDashboardUrl` — `POST /webhooks/svix_url`. Returns a
+*    one-time admin login URL to Svix's dashboard so the operator can
+*    finish endpoint config there.
+*  - `createUser` — `POST /users`. Used for seeding test users into
+*    staging without touching the dashboard.
+*  - `describe` — declares the runtime env keys a Clerk-using app needs.
+*
+* The configured secret key (`sk_test_*` vs `sk_live_*`) decides which
+* Clerk instance (Development vs Production) every call hits — there's
+* no per-call instance switch.
+*/
+var ClerkAuth = class {
+	rest;
+	key = "auth";
+	providerName = "clerk";
+	constructor(rest, _opts = {}) {
+		this.rest = rest;
+	}
+	async describe() {
+		return {
+			provider: "clerk",
+			envKeys: ["CLERK_PUBLISHABLE_KEY", "CLERK_SECRET_KEY"]
+		};
+	}
+	async whoami() {
+		return {
+			provider: "clerk",
+			details: { userCount: (await this.rest.request("/users/count")).total_count }
+		};
+	}
+	async ensureWebhookApp() {
+		try {
+			await this.rest.request("/webhooks/svix", { method: "POST" });
+			return { alreadyExists: false };
+		} catch (err) {
+			if (err instanceof ProviderApiError && isAlreadyExistsError(err)) return { alreadyExists: true };
+			throw err;
+		}
+	}
+	async getWebhookDashboardUrl() {
+		const body = await this.rest.request("/webhooks/svix_url", { method: "POST" });
+		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 email = body.email_addresses[0]?.email_address ?? input.email;
+		return {
+			id: body.id,
+			email
+		};
+	}
+};
+/**
+* Clerk returns a 4xx with `errors[0].code` of `you_already_have_a_svix_app`
+* (or text containing "already exists") when the Svix app already exists.
+* Treat that as a successful no-op so `ensureWebhookApp` is idempotent.
+*/
+function isAlreadyExistsError(err) {
+	if (typeof err.details === "string") {
+		const lower = err.details.toLowerCase();
+		return lower.includes("already") || lower.includes("exists");
+	}
+	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;
+		this.baseUrl = (opts.baseUrl ?? "https://api.clerk.com/v1").replace(/\/+$/, "");
+	}
+	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.
+*
+* Reference event shapes:
+*   https://clerk.com/docs/integrations/webhooks/overview
+*   https://clerk.com/docs/reference/backend-api/tag/Webhooks
+*/
+const CLERK_TO_NORMALIZED = {
+	"user.created": "user.created",
+	"user.updated": "user.updated",
+	"user.deleted": "user.deleted"
+};
+async function parseWebhook(input) {
+	await verifySignature(input);
+	const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
+	let payload;
+	try {
+		payload = JSON.parse(bodyStr);
+	} catch (err) {
+		throw new WebhookVerificationError(`Clerk webhook body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const normalizedType = CLERK_TO_NORMALIZED[payload.type];
+	if (!normalizedType) throw new WebhookVerificationError(`Clerk webhook event type "${payload.type}" has no normalized mapping yet`);
+	const primaryEmail = payload.data.email_addresses?.find((e) => e.id === payload.data.primary_email_address_id)?.email_address ?? payload.data.email_addresses?.[0]?.email_address;
+	const occurredAt = payload.created_at ? new Date(payload.created_at).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
+	return {
+		type: normalizedType,
+		user: {
+			id: payload.data.id,
+			email: primaryEmail ?? "",
+			...payload.data.first_name !== void 0 ? { firstName: payload.data.first_name } : {},
+			...payload.data.last_name !== void 0 ? { lastName: payload.data.last_name } : {},
+			raw: payload.data
+		},
+		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();
+}
+//#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)
+	};
+}
+function auth(ctx) {
+	return new ClerkAuth(ctx.rest);
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-clerk",
+		capabilities: { auth: () => auth(ctx) }
+	};
+}
+//#endregion
+export { AuthError, ClerkAuth, ClerkRestClient, auth, createContext, createPlugin, parseWebhook, resolveToken };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theholocron/holocron-plugin-clerk",
+  "version": "2.0.0-alpha.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-clerk"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.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",
+    "tsdown": "^0.22.3",
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "types": "./dist/index.d.mts"
+}