@convex-dev/workos-authkit 0.1.1

package/src/client/index.ts

@@ -0,0 +1,278 @@
+import {
+  type AuthConfig,
+  type FunctionReference,
+  type GenericDataModel,
+  type GenericMutationCtx,
+  type HttpRouter,
+  createFunctionHandle,
+  httpActionGeneric,
+  internalMutationGeneric,
+} from "convex/server";
+import type { RunQueryCtx } from "./types.js";
+import {
+  WorkOS,
+  type Event as WorkOSEvent,
+  type ActionContext as WorkOSActionContext,
+  type UserRegistrationActionResponseData,
+  type AuthenticationActionResponseData,
+} from "@workos-inc/node";
+import type { SetRequired } from "type-fest";
+import { v } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type WorkOSResponsePayload =
+  | AuthenticationActionResponseData
+  | UserRegistrationActionResponseData;
+
+type Options = {
+  authFunctions: AuthFunctions;
+  clientId?: string;
+  apiKey?: string;
+  webhookSecret?: string;
+  webhookPath?: string;
+  additionalEventTypes?: WorkOSEvent["event"][];
+  actionSecret?: string;
+  logLevel?: "DEBUG";
+};
+type Config = SetRequired<
+  Options,
+  "clientId" | "apiKey" | "webhookSecret" | "actionSecret"
+>;
+
+export type AuthFunctions = {
+  authKitAction: FunctionReference<
+    "mutation",
+    "internal",
+    { action: unknown },
+    WorkOSResponsePayload
+  >;
+  authKitEvent?: FunctionReference<
+    "mutation",
+    "internal",
+    { event: string; data: unknown },
+    null
+  >;
+};
+
+export class AuthKit<DataModel extends GenericDataModel> {
+  public workos: WorkOS;
+  private config: Config;
+  constructor(
+    public component: ComponentApi,
+    public options: Options
+  ) {
+    const clientId = options?.clientId ?? process.env.WORKOS_CLIENT_ID;
+    const apiKey = options?.apiKey ?? process.env.WORKOS_API_KEY;
+    const webhookSecret =
+      options?.webhookSecret ?? process.env.WORKOS_WEBHOOK_SECRET;
+    const actionSecret =
+      options?.actionSecret ?? process.env.WORKOS_ACTION_SECRET;
+    const missingEnvVars: string[] = [];
+    if (!clientId) {
+      missingEnvVars.push("WORKOS_CLIENT_ID");
+    }
+    if (!apiKey) {
+      missingEnvVars.push("WORKOS_API_KEY");
+    }
+    if (!webhookSecret) {
+      missingEnvVars.push("WORKOS_WEBHOOK_SECRET");
+    }
+    if (!actionSecret) {
+      missingEnvVars.push("WORKOS_ACTION_SECRET");
+    }
+    if (!clientId || !apiKey || !webhookSecret || !actionSecret) {
+      throw new Error(
+        `Missing environment variables: ${missingEnvVars.join(", ")}`
+      );
+    }
+    this.config = {
+      ...options,
+      clientId,
+      apiKey,
+      webhookSecret,
+      actionSecret,
+      webhookPath: options?.webhookPath ?? "/workos/webhook",
+    };
+    this.workos = new WorkOS(this.config.apiKey);
+  }
+
+  getAuthConfigProviders = () =>
+    [
+      {
+        type: "customJwt",
+        issuer: `https://api.workos.com/`,
+        algorithm: "RS256",
+        jwks: `https://api.workos.com/sso/jwks/${this.config.clientId}`,
+        applicationID: this.config.clientId,
+      },
+      {
+        type: "customJwt",
+        issuer: `https://api.workos.com/user_management/${this.config.clientId}`,
+        algorithm: "RS256",
+        jwks: `https://api.workos.com/sso/jwks/${this.config.clientId}`,
+      },
+    ] satisfies AuthConfig["providers"];
+
+  async getAuthUser(ctx: RunQueryCtx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+      return null;
+    }
+    return ctx.runQuery(this.component.lib.getAuthUser, {
+      id: identity.subject,
+    });
+  }
+  events<K extends WorkOSEvent["event"]>(opts: {
+    [Key in K]: <
+      E extends Extract<
+        WorkOSEvent,
+        {
+          event: Key;
+        }
+      >,
+    >(
+      ctx: GenericMutationCtx<DataModel>,
+      event: E
+    ) => Promise<void>;
+  }) {
+    return {
+      authKitEvent: internalMutationGeneric({
+        args: {
+          event: v.string(),
+          data: v.record(v.string(), v.any()),
+        },
+        returns: v.null(),
+        handler: async (ctx, args) => {
+          await opts[args.event as K](ctx, args as never);
+        },
+      }),
+    };
+  }
+  actions<K extends "authentication" | "userRegistration">(opts: {
+    [Key in K]: <
+      A extends Extract<
+        WorkOSActionContext,
+        {
+          object: Key extends "authentication"
+            ? "authentication_action_context"
+            : "user_registration_action_context";
+        }
+      >,
+    >(
+      ctx: GenericMutationCtx<DataModel>,
+      action: A,
+      {
+        allow,
+        deny,
+      }: {
+        allow: () => WorkOSResponsePayload;
+        deny: (errorMessage: string) => WorkOSResponsePayload;
+      }
+    ) => Promise<WorkOSResponsePayload>;
+  }) {
+    return {
+      authKitAction: internalMutationGeneric({
+        args: {
+          action: v.record(v.string(), v.any()),
+        },
+        returns: v.record(v.string(), v.any()),
+        handler: async (ctx, args) => {
+          const resp = {
+            type:
+              args.action.object === "authentication_action_context"
+                ? ("authentication" as const)
+                : ("user_registration" as const),
+            timestamp: new Date().getTime(),
+          };
+          const allow = () => ({ ...resp, verdict: "Allow" as const });
+          const deny = (errorMessage: string) => ({
+            ...resp,
+            verdict: "Deny" as const,
+            errorMessage,
+          });
+          const responsePayload = await opts[
+            (args.action.object === "authentication_action_context"
+              ? "authentication"
+              : "userRegistration") as K
+          ](ctx, args.action as never, {
+            allow,
+            deny,
+          });
+          return responsePayload;
+        },
+      }),
+    };
+  }
+  registerRoutes(http: HttpRouter) {
+    http.route({
+      path: "/workos/webhook",
+      method: "POST",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const payload = await request.text();
+        const sigHeader = request.headers.get("workos-signature");
+        if (!sigHeader) {
+          throw new Error("No signature header");
+        }
+        const secret = this.config.webhookSecret;
+        if (!secret) {
+          throw new Error("webhook secret is not set");
+        }
+        const event = await this.workos.webhooks.constructEvent({
+          payload: JSON.parse(payload),
+          sigHeader: sigHeader,
+          secret,
+        });
+        if (this.config.logLevel === "DEBUG") {
+          console.log("received event", event);
+        }
+        await ctx.runMutation(this.component.lib.enqueueWebhookEvent, {
+          apiKey: this.config.apiKey,
+          eventId: event.id,
+          event: event.event,
+          onEventHandle: this.config.authFunctions?.authKitEvent
+            ? await createFunctionHandle(this.config.authFunctions.authKitEvent)
+            : undefined,
+          updatedAt:
+            "updated_at" in event ? (event.updated_at as string) : undefined,
+          eventTypes: this.config.additionalEventTypes,
+          logLevel: this.config.logLevel,
+        });
+        return new Response("OK", { status: 200 });
+      }),
+    });
+    http.route({
+      path: "/workos/action",
+      method: "POST",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const payload = await request.text();
+        const sigHeader = request.headers.get("workos-signature");
+        if (!sigHeader) {
+          throw new Error("No signature header");
+        }
+        const secret = this.config.actionSecret;
+        if (!secret) {
+          throw new Error("webhook secret is not set");
+        }
+        const action = await this.workos.actions.constructAction({
+          payload: JSON.parse(payload),
+          sigHeader: sigHeader,
+          secret,
+        });
+        if (this.config.logLevel === "DEBUG") {
+          console.log("received action", action);
+        }
+        const responsePayload: WorkOSResponsePayload = await ctx.runMutation(
+          this.config.authFunctions.authKitAction,
+          {
+            action,
+          }
+        );
+        const response = await this.workos.actions.signResponse(
+          responsePayload,
+          this.config.actionSecret
+        );
+        return new Response(JSON.stringify(response), { status: 200 });
+      }),
+    });
+  }
+}

package/src/client/types.ts

@@ -0,0 +1,71 @@
+import type {
+  Auth,
+  Expand,
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  StorageActionWriter,
+  StorageReader,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+
+// Type utils follow
+
+export type RunQueryCtx = {
+  auth: Auth;
+  runQuery: <Query extends FunctionReference<"query", "internal">>(
+    query: Query,
+    args: FunctionArgs<Query>
+  ) => Promise<FunctionReturnType<Query>>;
+};
+export type RunMutationCtx = RunQueryCtx & {
+  auth: Auth;
+  runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
+    mutation: Mutation,
+    args: FunctionArgs<Mutation>
+  ) => Promise<FunctionReturnType<Mutation>>;
+};
+export type RunActionCtx = RunMutationCtx & {
+  auth: Auth;
+  runAction<Action extends FunctionReference<"action", "internal">>(
+    action: Action,
+    args: FunctionArgs<Action>
+  ): Promise<FunctionReturnType<Action>>;
+};
+export type ActionCtx = RunActionCtx & {
+  storage: StorageActionWriter;
+};
+export type QueryCtx = RunQueryCtx & {
+  storage: StorageReader;
+};
+
+export type OpaqueIds<T> =
+  T extends GenericId<infer _T>
+    ? string
+    : T extends (infer U)[]
+      ? OpaqueIds<U>[]
+      : T extends ArrayBuffer
+        ? ArrayBuffer
+        : T extends object
+          ? {
+              [K in keyof T]: OpaqueIds<T[K]>;
+            }
+          : T;
+
+export type UseApi<API> = Expand<{
+  [mod in keyof API]: API[mod] extends FunctionReference<
+    infer FType,
+    "public",
+    infer FArgs,
+    infer FReturnType,
+    infer FComponentPath
+  >
+    ? FunctionReference<
+        FType,
+        "internal",
+        OpaqueIds<FArgs>,
+        OpaqueIds<FReturnType>,
+        FComponentPath
+      >
+    : UseApi<API[mod]>;
+}>;

package/src/component/_generated/api.ts

@@ -0,0 +1,138 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {
+  eventWorkpool: {
+    lib: {
+      cancel: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          id: string;
+          logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any
+      >;
+      cancelAll: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          before?: number;
+          limit?: number;
+          logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+        },
+        any
+      >;
+      enqueue: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          config: {
+            logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+            maxParallelism: number;
+          };
+          fnArgs: any;
+          fnHandle: string;
+          fnName: string;
+          fnType: "action" | "mutation" | "query";
+          onComplete?: { context?: any; fnHandle: string };
+          retryBehavior?: {
+            base: number;
+            initialBackoffMs: number;
+            maxAttempts: number;
+          };
+          runAt: number;
+        },
+        string
+      >;
+      enqueueBatch: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          config: {
+            logLevel: "DEBUG" | "TRACE" | "INFO" | "REPORT" | "WARN" | "ERROR";
+            maxParallelism: number;
+          };
+          items: Array<{
+            fnArgs: any;
+            fnHandle: string;
+            fnName: string;
+            fnType: "action" | "mutation" | "query";
+            onComplete?: { context?: any; fnHandle: string };
+            retryBehavior?: {
+              base: number;
+              initialBackoffMs: number;
+              maxAttempts: number;
+            };
+            runAt: number;
+          }>;
+        },
+        Array<string>
+      >;
+      status: FunctionReference<
+        "query",
+        "internal",
+        { id: string },
+        | { previousAttempts: number; state: "pending" }
+        | { previousAttempts: number; state: "running" }
+        | { state: "finished" }
+      >;
+      statusBatch: FunctionReference<
+        "query",
+        "internal",
+        { ids: Array<string> },
+        Array<
+          | { previousAttempts: number; state: "pending" }
+          | { previousAttempts: number; state: "running" }
+          | { state: "finished" }
+        >
+      >;
+    };
+  };
+};

package/src/component/_generated/component.ts

@@ -0,0 +1,63 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      enqueueWebhookEvent: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          apiKey: string;
+          event: string;
+          eventId: string;
+          eventTypes?: Array<string>;
+          logLevel?: "DEBUG";
+          onEventHandle?: string;
+          updatedAt?: string;
+        },
+        any,
+        Name
+      >;
+      getAuthUser: FunctionReference<
+        "query",
+        "internal",
+        { id: string },
+        {
+          createdAt: string;
+          email: string;
+          emailVerified: boolean;
+          externalId?: null | string;
+          firstName?: null | string;
+          id: string;
+          lastName?: null | string;
+          lastSignInAt?: null | string;
+          locale?: null | string;
+          metadata: Record<string, any>;
+          profilePictureUrl?: null | string;
+          updatedAt: string;
+        } | null,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;