@theholocron/holocron-plugin-clerk 5.0.0-alpha.37 → 5.0.0-alpha.370
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/index.d.mts +30 -41
- package/dist/index.mjs +50 -43
- package/package.json +27 -25
package/README.md
CHANGED
|
@@ -22,7 +22,7 @@ Token resolution order:
|
|
|
22
22
|
5. Keyring `clerk` — unnamespaced fallback; set via `holocron auth set clerk <key>`
|
|
23
23
|
|
|
24
24
|
> **Why not the `clerk` CLI?** Rando's adapter shells out to `npx clerk@latest
|
|
25
|
-
api …`, but the `clerk` CLI
|
|
25
|
+
api …`, but the `clerk` CLI only wraps the same REST API holocron talks to.
|
|
26
26
|
> Direct REST drops a system-binary dependency and matches the uniform auth/REST
|
|
27
27
|
> pattern across the other holocron plugins.
|
|
28
28
|
|
package/dist/index.d.mts
CHANGED
|
@@ -1,13 +1,16 @@
|
|
|
1
|
-
import { Auth, AuthDescription, AuthError, AuthEvent, AuthIdentity, AuthUser, CreateAuthUserInput, ParseWebhookInput, ResolveTokenInput, WebhookDashboardInfo } from "@theholocron/cli";
|
|
1
|
+
import { Auth, AuthDescription, AuthError, AuthEvent, AuthIdentity, AuthUser, CreateAuthUserInput, ParseWebhookInput, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WebhookDashboardInfo } from "@theholocron/cli";
|
|
2
2
|
import { ClerkClient, ClerkClientOptions, createClerkClient } from "@theholocron/clerk-client";
|
|
3
|
-
|
|
4
|
-
declare const resolveToken: (
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
/** Resolves the Clerk secret key from `--token`, `HOLOCRON_CLERK_SECRET_KEY`, `CLERK_SECRET_KEY` or the keyring entry for `clerk`, and throws `AuthError` when none is set. */
|
|
4
|
+
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
5
|
+
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
6
|
+
export declare const tokens: PluginToken[];
|
|
7
7
|
type ClerkAuthOptions = Record<string, never>;
|
|
8
|
-
|
|
8
|
+
/** `auth` capability for Clerk, backed by Clerk's Backend REST API. */
|
|
9
|
+
export declare class ClerkAuth implements Auth {
|
|
9
10
|
private readonly client;
|
|
11
|
+
/** Capability key; always `"auth"`. */
|
|
10
12
|
readonly key: "auth";
|
|
13
|
+
/** Provider name; always `"clerk"`. */
|
|
11
14
|
readonly providerName = "clerk";
|
|
12
15
|
constructor(client: () => ClerkClient, _opts?: ClerkAuthOptions);
|
|
13
16
|
describe(): Promise<AuthDescription>;
|
|
@@ -18,51 +21,38 @@ declare class ClerkAuth implements Auth {
|
|
|
18
21
|
getWebhookDashboardUrl(): Promise<WebhookDashboardInfo>;
|
|
19
22
|
createUser(input: CreateAuthUserInput): Promise<AuthUser>;
|
|
20
23
|
}
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
declare function parseWebhook(input: ParseWebhookInput): Promise<AuthEvent>;
|
|
24
|
-
//#endregion
|
|
25
|
-
//#region src/verify-token.d.ts
|
|
26
|
-
/**
|
|
27
|
-
* `verifyToken` — plugin-level export used by `holocron auth set` +
|
|
28
|
-
* `holocron auth check`. Hits Clerk's `/v1/instance` endpoint, which
|
|
29
|
-
* requires a valid secret key and returns instance metadata (id,
|
|
30
|
-
* environment_type, etc.). Invalid keys → 401.
|
|
31
|
-
*
|
|
32
|
-
* Clerk doesn't have a traditional user-oriented whoami — the "authed
|
|
33
|
-
* entity" is your Clerk INSTANCE, not a user. `/v1/instance` is the
|
|
34
|
-
* canonical "is this secret key valid?" endpoint.
|
|
35
|
-
*/
|
|
36
|
-
interface VerifyTokenSuccess {
|
|
37
|
-
ok: true;
|
|
38
|
-
subject: string;
|
|
39
|
-
}
|
|
40
|
-
interface VerifyTokenFailure {
|
|
41
|
-
ok: false;
|
|
42
|
-
message: string;
|
|
43
|
-
}
|
|
44
|
-
type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
|
|
24
|
+
/** Verifies a Clerk webhook's signature and replay window, then turns it into a normalized `AuthEvent`; throws `WebhookVerificationError` on a bad signature, invalid JSON or an unmapped event type. */
|
|
25
|
+
export declare function parseWebhook(input: ParseWebhookInput): Promise<AuthEvent>;
|
|
45
26
|
interface VerifyTokenOptions {
|
|
46
27
|
baseUrl?: string;
|
|
47
28
|
fetch?: typeof fetch;
|
|
48
29
|
}
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
interface ClerkPluginOptions extends ResolveTokenInput {
|
|
30
|
+
/** Checks a Clerk secret key by fetching the instance and reports its environment type and id, or why it was rejected. */
|
|
31
|
+
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
32
|
+
/** Options for the Clerk plugin: the token lookup inputs plus test overrides. */
|
|
33
|
+
export interface ClerkPluginOptions extends ResolveTokenInput {
|
|
53
34
|
/** Override base URL for tests. */
|
|
54
35
|
baseUrl?: string;
|
|
55
36
|
/** Override `fetch` for tests. */
|
|
56
37
|
fetch?: typeof fetch;
|
|
57
38
|
}
|
|
58
|
-
|
|
39
|
+
/** Shared state for one Clerk plugin instance: its options and a lazily created client. */
|
|
40
|
+
export interface PluginContext {
|
|
41
|
+
/** The options the plugin was created with. */
|
|
59
42
|
options: ClerkPluginOptions;
|
|
43
|
+
/** Returns the memoized Clerk client; the token is resolved on the first call, not at plugin load. */
|
|
60
44
|
client: () => ClerkClient;
|
|
61
45
|
}
|
|
62
|
-
|
|
63
|
-
declare function
|
|
64
|
-
|
|
46
|
+
/** Builds the plugin context from its options. */
|
|
47
|
+
export declare function createContext(options?: ClerkPluginOptions): PluginContext;
|
|
48
|
+
/** Builds the `auth` capability for the context. */
|
|
49
|
+
export declare function auth(ctx: PluginContext): Auth;
|
|
50
|
+
/** Creates the Clerk plugin: its `connection` probe and the `auth` capability. */
|
|
51
|
+
export declare function createPlugin(options?: ClerkPluginOptions): {
|
|
65
52
|
name: string;
|
|
53
|
+
probes: {
|
|
54
|
+
connection: import("@theholocron/cli").Probe;
|
|
55
|
+
};
|
|
66
56
|
capabilities: {
|
|
67
57
|
auth: () => Auth;
|
|
68
58
|
};
|
|
@@ -73,6 +63,5 @@ declare function createPlugin(options?: ClerkPluginOptions): {
|
|
|
73
63
|
* the Clerk dashboard's API Keys section — MUST be the SECRET key
|
|
74
64
|
* (sk_test_* / sk_live_*), not the publishable key.
|
|
75
65
|
*/
|
|
76
|
-
declare const AUTH_HINT: string;
|
|
77
|
-
|
|
78
|
-
export { AUTH_HINT, AuthError, ClerkAuth, type ClerkClientOptions, ClerkPluginOptions, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, auth, createClerkClient, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };
|
|
66
|
+
export declare const AUTH_HINT: string;
|
|
67
|
+
export { AuthError, type ClerkClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createClerkClient };
|
package/dist/index.mjs
CHANGED
|
@@ -1,18 +1,24 @@
|
|
|
1
|
-
import { AuthError, ProviderApiError, WebhookVerificationError, createResolveToken } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, ProviderApiError, WebhookVerificationError, connectionProbe, createResolveToken } from "@theholocron/cli";
|
|
2
2
|
import { createClerkClient } from "@theholocron/clerk-client";
|
|
3
|
+
import { errorMessage } from "@theholocron/misc-utils";
|
|
3
4
|
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
4
|
-
|
|
5
|
+
// src/auth.ts
|
|
6
|
+
/** Resolves the Clerk secret key from `--token`, `HOLOCRON_CLERK_SECRET_KEY`, `CLERK_SECRET_KEY` or the keyring entry for `clerk`, and throws `AuthError` when none is set. */
|
|
5
7
|
const resolveToken = createResolveToken({
|
|
6
8
|
envName: "HOLOCRON_CLERK_SECRET_KEY",
|
|
7
9
|
vendorEnvName: "CLERK_SECRET_KEY",
|
|
8
10
|
keyringService: "clerk",
|
|
9
11
|
errorMessage: "no Clerk secret key found. Pass --token <KEY>, set HOLOCRON_CLERK_SECRET_KEY / CLERK_SECRET_KEY, or run: holocron auth set clerk <KEY>"
|
|
10
12
|
});
|
|
11
|
-
|
|
12
|
-
|
|
13
|
+
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
14
|
+
const tokens = [resolveToken.token];
|
|
15
|
+
// src/capabilities/auth.ts
|
|
16
|
+
/** `auth` capability for Clerk, backed by Clerk's Backend REST API. */
|
|
13
17
|
var ClerkAuth = class {
|
|
14
18
|
client;
|
|
19
|
+
/** Capability key; always `"auth"`. */
|
|
15
20
|
key = "auth";
|
|
21
|
+
/** Provider name; always `"clerk"`. */
|
|
16
22
|
providerName = "clerk";
|
|
17
23
|
constructor(client, _opts = {}) {
|
|
18
24
|
this.client = client;
|
|
@@ -70,8 +76,28 @@ function isAlreadyExistsError(err) {
|
|
|
70
76
|
}
|
|
71
77
|
return false;
|
|
72
78
|
}
|
|
73
|
-
|
|
74
|
-
|
|
79
|
+
// src/verify-token.ts
|
|
80
|
+
/** Checks a Clerk secret key by fetching the instance and reports its environment type and id, or why it was rejected. */
|
|
81
|
+
async function verifyToken(token, opts = {}) {
|
|
82
|
+
const client = createClerkClient({
|
|
83
|
+
token,
|
|
84
|
+
baseUrl: opts.baseUrl,
|
|
85
|
+
fetch: opts.fetch
|
|
86
|
+
});
|
|
87
|
+
try {
|
|
88
|
+
const inst = await client.instance.get();
|
|
89
|
+
return {
|
|
90
|
+
ok: true,
|
|
91
|
+
subject: `${inst?.environment_type ?? "unknown"} instance ${inst?.id ?? "unknown"}`
|
|
92
|
+
};
|
|
93
|
+
} catch (err) {
|
|
94
|
+
return {
|
|
95
|
+
ok: false,
|
|
96
|
+
message: errorMessage(err)
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
// src/parse-webhook.ts
|
|
75
101
|
/**
|
|
76
102
|
* Translates a Clerk webhook delivery into the normalized `AuthEvent`
|
|
77
103
|
* shape defined in `@theholocron/cli`, with full Svix HMAC-SHA256
|
|
@@ -91,6 +117,7 @@ const CLERK_TO_NORMALIZED = {
|
|
|
91
117
|
"user.deleted": "user.deleted"
|
|
92
118
|
};
|
|
93
119
|
const REPLAY_WINDOW_SECONDS = 300;
|
|
120
|
+
/** Verifies a Clerk webhook's signature and replay window, then turns it into a normalized `AuthEvent`; throws `WebhookVerificationError` on a bad signature, invalid JSON or an unmapped event type. */
|
|
94
121
|
async function parseWebhook(input) {
|
|
95
122
|
await verifySignature(input);
|
|
96
123
|
const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
|
|
@@ -98,7 +125,7 @@ async function parseWebhook(input) {
|
|
|
98
125
|
try {
|
|
99
126
|
payload = JSON.parse(bodyStr);
|
|
100
127
|
} catch (err) {
|
|
101
|
-
throw new WebhookVerificationError(`Clerk webhook body is not valid JSON: ${
|
|
128
|
+
throw new WebhookVerificationError(`Clerk webhook body is not valid JSON: ${errorMessage(err)}`);
|
|
102
129
|
}
|
|
103
130
|
const normalizedType = CLERK_TO_NORMALIZED[payload.type];
|
|
104
131
|
if (!normalizedType) throw new WebhookVerificationError(`Clerk webhook event type "${payload.type}" has no normalized mapping yet`);
|
|
@@ -141,46 +168,15 @@ async function verifySignature(input) {
|
|
|
141
168
|
let sigBytes;
|
|
142
169
|
try {
|
|
143
170
|
sigBytes = Buffer.from(sig.slice(comma + 1), "base64");
|
|
144
|
-
} catch
|
|
171
|
+
} catch /* istanbul ignore next -- Buffer.from('base64') never throws in Node.js */ {
|
|
145
172
|
return false;
|
|
146
173
|
}
|
|
147
174
|
if (sigBytes.length !== computed.length) return false;
|
|
148
175
|
return timingSafeEqual(sigBytes, computed);
|
|
149
176
|
})) throw new WebhookVerificationError("Svix signature verification failed");
|
|
150
177
|
}
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
/**
|
|
154
|
-
* `verifyToken` — plugin-level export used by `holocron auth set` +
|
|
155
|
-
* `holocron auth check`. Hits Clerk's `/v1/instance` endpoint, which
|
|
156
|
-
* requires a valid secret key and returns instance metadata (id,
|
|
157
|
-
* environment_type, etc.). Invalid keys → 401.
|
|
158
|
-
*
|
|
159
|
-
* Clerk doesn't have a traditional user-oriented whoami — the "authed
|
|
160
|
-
* entity" is your Clerk INSTANCE, not a user. `/v1/instance` is the
|
|
161
|
-
* canonical "is this secret key valid?" endpoint.
|
|
162
|
-
*/
|
|
163
|
-
async function verifyToken(token, opts = {}) {
|
|
164
|
-
const client = createClerkClient({
|
|
165
|
-
token,
|
|
166
|
-
baseUrl: opts.baseUrl,
|
|
167
|
-
fetch: opts.fetch
|
|
168
|
-
});
|
|
169
|
-
try {
|
|
170
|
-
const inst = await client.instance.get();
|
|
171
|
-
return {
|
|
172
|
-
ok: true,
|
|
173
|
-
subject: `${inst?.environment_type ?? "unknown"} instance ${inst?.id ?? "unknown"}`
|
|
174
|
-
};
|
|
175
|
-
} catch (err) {
|
|
176
|
-
return {
|
|
177
|
-
ok: false,
|
|
178
|
-
message: err instanceof Error ? err.message : String(err)
|
|
179
|
-
};
|
|
180
|
-
}
|
|
181
|
-
}
|
|
182
|
-
//#endregion
|
|
183
|
-
//#region src/index.ts
|
|
178
|
+
// src/index.ts
|
|
179
|
+
/** Builds the plugin context from its options. */
|
|
184
180
|
function createContext(options = {}) {
|
|
185
181
|
let client;
|
|
186
182
|
return {
|
|
@@ -192,13 +188,25 @@ function createContext(options = {}) {
|
|
|
192
188
|
})
|
|
193
189
|
};
|
|
194
190
|
}
|
|
191
|
+
/** Builds the `auth` capability for the context. */
|
|
195
192
|
function auth(ctx) {
|
|
196
193
|
return new ClerkAuth(ctx.client);
|
|
197
194
|
}
|
|
195
|
+
/** Creates the Clerk plugin: its `connection` probe and the `auth` capability. */
|
|
198
196
|
function createPlugin(options = {}) {
|
|
199
197
|
const ctx = createContext(options);
|
|
200
198
|
return {
|
|
201
199
|
name: "@theholocron/holocron-plugin-clerk",
|
|
200
|
+
probes: { connection: connectionProbe({
|
|
201
|
+
provider: "Clerk",
|
|
202
|
+
url: options.baseUrl ?? "https://api.clerk.com",
|
|
203
|
+
fetch: options.fetch,
|
|
204
|
+
token: () => resolveToken(options),
|
|
205
|
+
verify: (token) => verifyToken(token, {
|
|
206
|
+
baseUrl: options.baseUrl,
|
|
207
|
+
fetch: options.fetch
|
|
208
|
+
})
|
|
209
|
+
}) },
|
|
202
210
|
capabilities: { auth: () => auth(ctx) }
|
|
203
211
|
};
|
|
204
212
|
}
|
|
@@ -209,5 +217,4 @@ function createPlugin(options = {}) {
|
|
|
209
217
|
* (sk_test_* / sk_live_*), not the publishable key.
|
|
210
218
|
*/
|
|
211
219
|
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.";
|
|
212
|
-
|
|
213
|
-
export { AUTH_HINT, AuthError, ClerkAuth, auth, createClerkClient, createContext, createPlugin, parseWebhook, resolveToken, verifyToken };
|
|
220
|
+
export { AUTH_HINT, AuthError, ClerkAuth, auth, createClerkClient, createContext, createPlugin, parseWebhook, resolveToken, tokens, verifyToken };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-clerk",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.370",
|
|
4
4
|
"description": "Holocron plugin for Clerk. Implements the auth capability against Clerk's Backend REST API.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"auth",
|
|
@@ -8,12 +8,12 @@
|
|
|
8
8
|
"holocron",
|
|
9
9
|
"plugin"
|
|
10
10
|
],
|
|
11
|
-
"homepage": "https://
|
|
11
|
+
"homepage": "https://docs.theholocron.dev/holocron/plugins/clerk/",
|
|
12
12
|
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
13
13
|
"repository": {
|
|
14
14
|
"type": "git",
|
|
15
15
|
"url": "git+https://github.com/theholocron/holocron.git",
|
|
16
|
-
"directory": "
|
|
16
|
+
"directory": "plugins/holocron-plugin-clerk"
|
|
17
17
|
},
|
|
18
18
|
"license": "MIT",
|
|
19
19
|
"author": "Newton Koumantzelis",
|
|
@@ -30,27 +30,29 @@
|
|
|
30
30
|
"dist"
|
|
31
31
|
],
|
|
32
32
|
"devDependencies": {
|
|
33
|
-
"@theholocron/clerk-client": "^1.24.0",
|
|
34
|
-
"@theholocron/eslint-config": "^8.0.0",
|
|
35
|
-
"@theholocron/http-client": "^1.24.0",
|
|
36
|
-
"@theholocron/tsconfig": "^8.0.0",
|
|
37
|
-
"@theholocron/tsdown-config": "^8.0.0",
|
|
38
|
-
"@theholocron/vitest-config": "^8.0.0",
|
|
39
33
|
"@types/node": "^26",
|
|
40
|
-
"@vitest/coverage-v8": "^
|
|
41
|
-
"@vitest/eslint-plugin": "^1.6.
|
|
42
|
-
"eslint": "^10.
|
|
43
|
-
"eslint-plugin-n": "^18.
|
|
44
|
-
"globals": "^17.
|
|
45
|
-
"tsdown": "^0.
|
|
46
|
-
"tsx": "4.23.
|
|
34
|
+
"@vitest/coverage-v8": "^5.1.0",
|
|
35
|
+
"@vitest/eslint-plugin": "^1.6.28",
|
|
36
|
+
"eslint": "^10.14.0",
|
|
37
|
+
"eslint-plugin-n": "^18.5.0",
|
|
38
|
+
"globals": "^17.14.0",
|
|
39
|
+
"tsdown": "^0.23.5",
|
|
40
|
+
"tsx": "4.23.15",
|
|
47
41
|
"typescript": "^5.9.3",
|
|
48
|
-
"vitest": "^
|
|
49
|
-
"@theholocron/
|
|
42
|
+
"vitest": "^5.1.0",
|
|
43
|
+
"@theholocron/clerk-client": "^1.58.0-alpha.17",
|
|
44
|
+
"@theholocron/cli": "5.0.0-alpha.370",
|
|
45
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.11",
|
|
46
|
+
"@theholocron/http-client": "^1.58.0-alpha.17",
|
|
47
|
+
"@theholocron/misc-utils": "^1.17.0-alpha.2",
|
|
48
|
+
"@theholocron/tsdown-config": "^8.9.0-alpha.11",
|
|
49
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.11",
|
|
50
|
+
"@theholocron/tsconfig": "^8.9.0-alpha.11"
|
|
50
51
|
},
|
|
51
52
|
"peerDependencies": {
|
|
52
|
-
"@theholocron/clerk-client": "^1.
|
|
53
|
-
"@theholocron/
|
|
53
|
+
"@theholocron/clerk-client": "^1.43.1",
|
|
54
|
+
"@theholocron/misc-utils": "^1.16.0",
|
|
55
|
+
"@theholocron/cli": "5.0.0-alpha.370"
|
|
54
56
|
},
|
|
55
57
|
"engines": {
|
|
56
58
|
"node": ">=22"
|
|
@@ -59,11 +61,11 @@
|
|
|
59
61
|
"access": "public"
|
|
60
62
|
},
|
|
61
63
|
"scripts": {
|
|
62
|
-
"
|
|
63
|
-
"
|
|
64
|
+
"build": "tsdown",
|
|
65
|
+
"lint:code": "eslint .",
|
|
66
|
+
"test:unit": "vitest run --coverage",
|
|
64
67
|
"test:watch": "vitest",
|
|
65
|
-
"
|
|
66
|
-
"
|
|
67
|
-
"verification.unitTests": "holocron run verification.unitTests --"
|
|
68
|
+
"typecheck": "tsc --noEmit",
|
|
69
|
+
"validate:plugin": "tsx scripts/validate.mjs"
|
|
68
70
|
}
|
|
69
71
|
}
|