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

package/README.md

@@ -3,6 +3,12 @@
 Clerk plugin for [Holocron](../cli). Implements the `auth` capability
 against [Clerk's Backend REST API](https://clerk.com/docs/reference/backend-api).
 
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-clerk@alpha
+```
+
 ## Auth
 
 Token resolution order:
@@ -12,7 +18,7 @@ Token resolution order:
 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.
+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.
 
@@ -20,9 +26,9 @@ Token resolution order:
 
 ```jsonc
 {
-  "providers": {
-    "auth": "clerk"
-  }
+	"providers": {
+		"auth": "clerk",
+	},
 }
 ```
 
@@ -32,17 +38,20 @@ 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)                  |
+| 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.
+**`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
+[Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
+APIs may still shift before stable v2.0.0.
+
+Real Svix HMAC verification in `parseWebhook` is deferred to
+[#80](https://github.com/theholocron/holocron/issues/80) — current
+implementation validates shape only.

package/dist/index.d.mts

@@ -4,10 +4,13 @@ import { Auth, AuthDescription, AuthEvent, AuthIdentity, AuthUser, CreateAuthUse
 /**
  * Token resolution for the Clerk plugin.
  *
- * Resolution order:
+ * 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.
@@ -20,6 +23,8 @@ interface ResolveTokenInput {
   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
@@ -38,7 +43,7 @@ interface RestClientOptions {
   baseUrl?: string;
 }
 interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
   body?: unknown;
   query?: Record<string, string>;
 }
@@ -69,6 +74,32 @@ declare class ClerkAuth implements Auth {
 //#region src/parse-webhook.d.ts
 declare function parseWebhook(input: ParseWebhookInput): Promise<AuthEvent>;
 //#endregion
+//#region src/verify-token.d.ts
+/**
+ * `verifyToken` — plugin-level export used by `holocron auth set` +
+ * `holocron auth check`. Hits Clerk's `/v1/instance` endpoint, which
+ * requires a valid secret key and returns instance metadata (id,
+ * environment_type, etc.). Invalid keys → 401.
+ *
+ * Clerk doesn't have a traditional user-oriented whoami — the "authed
+ * entity" is your Clerk INSTANCE, not a user. `/v1/instance` is the
+ * canonical "is this secret key valid?" endpoint.
+ */
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
 //#region src/index.d.ts
 interface ClerkPluginOptions extends ResolveTokenInput {
   /** Override base URL for tests. */
@@ -88,5 +119,12 @@ declare function createPlugin(options?: ClerkPluginOptions): {
     auth: () => Auth;
   };
 };
+/**
+ * One-line hint printed by `holocron auth set clerk` when no token
+ * is supplied or the supplied token is rejected. Points operators at
+ * the Clerk dashboard's API Keys section — MUST be the SECRET key
+ * (sk_test_* / sk_live_*), not the publishable key.
+ */
+declare const AUTH_HINT: string;
 //#endregion
-export { AuthError, ClerkAuth, ClerkPluginOptions, ClerkRestClient, PluginContext, ResolveTokenInput, auth, createContext, createPlugin, parseWebhook, resolveToken };
+export { AUTH_HINT, AuthError, ClerkAuth, ClerkPluginOptions, ClerkRestClient, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, auth, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };

package/dist/index.mjs

@@ -1,12 +1,15 @@
-import { ProviderApiError, WebhookVerificationError } from "@theholocron/cli";
+import { ProviderApiError, WebhookVerificationError, getToken } from "@theholocron/cli";
 //#region src/auth.ts
 /**
 * Token resolution for the Clerk plugin.
 *
-* Resolution order:
+* 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.
@@ -16,8 +19,9 @@ var AuthError = class extends Error {
 };
 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.");
+	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;
 }
 //#endregion
@@ -127,7 +131,9 @@ var ClerkRestClient = class {
 	constructor(opts) {
 		this.token = opts.token;
 		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		this.baseUrl = (opts.baseUrl ?? "https://api.clerk.com/v1").replace(/\/+$/, "");
+		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}`);
@@ -230,6 +236,36 @@ async function verifySignature(input) {
 	return Promise.resolve();
 }
 //#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth set` +
+* `holocron auth check`. Hits Clerk's `/v1/instance` endpoint, which
+* requires a valid secret key and returns instance metadata (id,
+* environment_type, etc.). Invalid keys → 401.
+*
+* Clerk doesn't have a traditional user-oriented whoami — the "authed
+* entity" is your Clerk INSTANCE, not a user. `/v1/instance` is the
+* 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);
+	try {
+		const instance = await rest.request("/instance");
+		return {
+			ok: true,
+			subject: `${instance?.environment_type ?? "unknown"} instance ${instance?.id ?? "unknown"}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
 //#region src/index.ts
 function createContext(options = {}) {
 	const restOpts = { token: resolveToken(options) };
@@ -250,5 +286,12 @@ function createPlugin(options = {}) {
 		capabilities: { auth: () => auth(ctx) }
 	};
 }
+/**
+* One-line hint printed by `holocron auth set clerk` when no token
+* is supplied or the supplied token is rejected. Points operators at
+* the Clerk dashboard's API Keys section — MUST be the SECRET key
+* (sk_test_* / sk_live_*), not the publishable key.
+*/
+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 { AuthError, ClerkAuth, ClerkRestClient, auth, createContext, createPlugin, parseWebhook, resolveToken };
+export { AUTH_HINT, AuthError, ClerkAuth, ClerkRestClient, auth, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-clerk",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.5",
   "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,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "devDependencies": {
     "@theholocron/tsconfig": "^4.1.0",
@@ -32,7 +32,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "tsdown": "^0.22.3",
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "publishConfig": {
     "access": "public"
@@ -47,7 +48,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
   },
   "types": "./dist/index.d.mts"
 }