@theholocron/holocron-plugin-clerk 5.0.0-alpha.278 → 5.0.0-alpha.279

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/dist/index.d.mts CHANGED
@@ -1,12 +1,16 @@
1
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
+ /** 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. */
3
4
  export declare const resolveToken: import("@theholocron/cli").TokenResolver;
4
5
  /** Every token this plugin takes, for `holocron doctor tokens`. */
5
6
  export declare const tokens: PluginToken[];
6
7
  type ClerkAuthOptions = Record<string, never>;
8
+ /** `auth` capability for Clerk, backed by Clerk's Backend REST API. */
7
9
  export declare class ClerkAuth implements Auth {
8
10
  private readonly client;
11
+ /** Capability key; always `"auth"`. */
9
12
  readonly key: "auth";
13
+ /** Provider name; always `"clerk"`. */
10
14
  readonly providerName = "clerk";
11
15
  constructor(client: () => ClerkClient, _opts?: ClerkAuthOptions);
12
16
  describe(): Promise<AuthDescription>;
@@ -17,24 +21,33 @@ export declare class ClerkAuth implements Auth {
17
21
  getWebhookDashboardUrl(): Promise<WebhookDashboardInfo>;
18
22
  createUser(input: CreateAuthUserInput): Promise<AuthUser>;
19
23
  }
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. */
20
25
  export declare function parseWebhook(input: ParseWebhookInput): Promise<AuthEvent>;
21
26
  interface VerifyTokenOptions {
22
27
  baseUrl?: string;
23
28
  fetch?: typeof fetch;
24
29
  }
30
+ /** Checks a Clerk secret key by fetching the instance and reports its environment type and id, or why it was rejected. */
25
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. */
26
33
  export interface ClerkPluginOptions extends ResolveTokenInput {
27
34
  /** Override base URL for tests. */
28
35
  baseUrl?: string;
29
36
  /** Override `fetch` for tests. */
30
37
  fetch?: typeof fetch;
31
38
  }
39
+ /** Shared state for one Clerk plugin instance: its options and a lazily created client. */
32
40
  export interface PluginContext {
41
+ /** The options the plugin was created with. */
33
42
  options: ClerkPluginOptions;
43
+ /** Returns the memoized Clerk client; the token is resolved on the first call, not at plugin load. */
34
44
  client: () => ClerkClient;
35
45
  }
46
+ /** Builds the plugin context from its options. */
36
47
  export declare function createContext(options?: ClerkPluginOptions): PluginContext;
48
+ /** Builds the `auth` capability for the context. */
37
49
  export declare function auth(ctx: PluginContext): Auth;
50
+ /** Creates the Clerk plugin: its `connection` probe and the `auth` capability. */
38
51
  export declare function createPlugin(options?: ClerkPluginOptions): {
39
52
  name: string;
40
53
  probes: {
package/dist/index.mjs CHANGED
@@ -3,6 +3,7 @@ import { createClerkClient } from "@theholocron/clerk-client";
3
3
  import { errorMessage } from "@theholocron/misc-utils";
4
4
  import { createHmac, timingSafeEqual } from "node:crypto";
5
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. */
6
7
  const resolveToken = createResolveToken({
7
8
  envName: "HOLOCRON_CLERK_SECRET_KEY",
8
9
  vendorEnvName: "CLERK_SECRET_KEY",
@@ -12,9 +13,12 @@ const resolveToken = createResolveToken({
12
13
  /** Every token this plugin takes, for `holocron doctor tokens`. */
13
14
  const tokens = [resolveToken.token];
14
15
  // src/capabilities/auth.ts
16
+ /** `auth` capability for Clerk, backed by Clerk's Backend REST API. */
15
17
  var ClerkAuth = class {
16
18
  client;
19
+ /** Capability key; always `"auth"`. */
17
20
  key = "auth";
21
+ /** Provider name; always `"clerk"`. */
18
22
  providerName = "clerk";
19
23
  constructor(client, _opts = {}) {
20
24
  this.client = client;
@@ -73,6 +77,7 @@ function isAlreadyExistsError(err) {
73
77
  return false;
74
78
  }
75
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. */
76
81
  async function verifyToken(token, opts = {}) {
77
82
  const client = createClerkClient({
78
83
  token,
@@ -112,6 +117,7 @@ const CLERK_TO_NORMALIZED = {
112
117
  "user.deleted": "user.deleted"
113
118
  };
114
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. */
115
121
  async function parseWebhook(input) {
116
122
  await verifySignature(input);
117
123
  const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
@@ -170,6 +176,7 @@ async function verifySignature(input) {
170
176
  })) throw new WebhookVerificationError("Svix signature verification failed");
171
177
  }
172
178
  // src/index.ts
179
+ /** Builds the plugin context from its options. */
173
180
  function createContext(options = {}) {
174
181
  let client;
175
182
  return {
@@ -181,9 +188,11 @@ function createContext(options = {}) {
181
188
  })
182
189
  };
183
190
  }
191
+ /** Builds the `auth` capability for the context. */
184
192
  function auth(ctx) {
185
193
  return new ClerkAuth(ctx.client);
186
194
  }
195
+ /** Creates the Clerk plugin: its `connection` probe and the `auth` capability. */
187
196
  function createPlugin(options = {}) {
188
197
  const ctx = createContext(options);
189
198
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-clerk",
3
- "version": "5.0.0-alpha.278",
3
+ "version": "5.0.0-alpha.279",
4
4
  "description": "Holocron plugin for Clerk. Implements the auth capability against Clerk's Backend REST API.",
5
5
  "keywords": [
6
6
  "auth",
@@ -41,18 +41,18 @@
41
41
  "typescript": "^5.9.3",
42
42
  "vitest": "^5.0.5",
43
43
  "@theholocron/clerk-client": "^1.58.0-alpha.3",
44
- "@theholocron/cli": "5.0.0-alpha.278",
45
- "@theholocron/http-client": "^1.58.0-alpha.3",
44
+ "@theholocron/eslint-config": "^8.9.0-alpha.4",
45
+ "@theholocron/cli": "5.0.0-alpha.279",
46
+ "@theholocron/misc-utils": "^1.16.1-alpha.3",
46
47
  "@theholocron/tsconfig": "^8.9.0-alpha.4",
48
+ "@theholocron/http-client": "^1.58.0-alpha.3",
47
49
  "@theholocron/tsdown-config": "^8.9.0-alpha.4",
48
- "@theholocron/misc-utils": "^1.16.1-alpha.3",
49
- "@theholocron/vitest-config": "^8.9.0-alpha.4",
50
- "@theholocron/eslint-config": "^8.9.0-alpha.4"
50
+ "@theholocron/vitest-config": "^8.9.0-alpha.4"
51
51
  },
52
52
  "peerDependencies": {
53
53
  "@theholocron/clerk-client": "^1.43.1",
54
54
  "@theholocron/misc-utils": "^1.16.0",
55
- "@theholocron/cli": "5.0.0-alpha.278"
55
+ "@theholocron/cli": "5.0.0-alpha.279"
56
56
  },
57
57
  "engines": {
58
58
  "node": ">=22"