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

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
@@ -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
@@ -232,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) };
@@ -252,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.1",
+  "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.1"
+    "@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.1"
+    "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"
 }