@robelest/convex-auth 0.0.1

package/src/server/implementation/signIn.ts

@@ -0,0 +1,253 @@
+import { GenericId } from "convex/values";
+import {
+  AuthProviderMaterializedConfig,
+  ConvexCredentialsConfig,
+  EmailConfig,
+  GenericActionCtxWithAuthConfig,
+  PhoneConfig,
+} from "../types.js";
+import {
+  AuthDataModel,
+  SessionInfo,
+  SessionInfoWithTokens,
+  Tokens,
+} from "./types.js";
+import {
+  callCreateVerificationCode,
+  callRefreshSession,
+  callSignIn,
+  callVerifier,
+  callVerifyCodeAndSignIn,
+} from "./mutations/index.js";
+import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
+import { requireEnv } from "../utils.js";
+import { OAuth2Config, OIDCConfig } from "@auth/core/providers/oauth.js";
+import { generateRandomString } from "./utils.js";
+
+const DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours
+
+type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
+
+export async function signInImpl(
+  ctx: EnrichedActionCtx,
+  provider: AuthProviderMaterializedConfig | null,
+  args: {
+    accountId?: GenericId<"account">;
+    params?: Record<string, any>;
+    verifier?: string;
+    refreshToken?: string;
+    calledBy?: string;
+  },
+  options: {
+    generateTokens: boolean;
+    allowExtraProviders: boolean;
+  },
+): Promise<
+  | { kind: "signedIn"; signedIn: SessionInfo | null }
+  // refresh tokens
+  | { kind: "refreshTokens"; signedIn: { tokens: Tokens } }
+  // Multi-step flows like magic link + OTP
+  | { kind: "started"; started: true }
+  // OAuth2 and OIDC flows
+  | { kind: "redirect"; redirect: string; verifier: string }
+> {
+  if (provider === null && args.refreshToken) {
+    const tokens: Tokens = (await callRefreshSession(ctx, {
+      refreshToken: args.refreshToken,
+    }))!;
+    return { kind: "refreshTokens", signedIn: { tokens } };
+  }
+  if (provider === null && args.params?.code !== undefined) {
+    const result = await callVerifyCodeAndSignIn(ctx, {
+      params: args.params,
+      verifier: args.verifier,
+      generateTokens: true,
+      allowExtraProviders: options.allowExtraProviders,
+    });
+    return {
+      kind: "signedIn",
+      signedIn: result,
+    };
+  }
+
+  if (provider === null) {
+    throw new Error(
+      "Cannot sign in: Missing `provider`, `params.code` or `refreshToken`",
+    );
+  }
+  if (provider.type === "email" || provider.type === "phone") {
+    return handleEmailAndPhoneProvider(ctx, provider, args, options);
+  }
+  if (provider.type === "credentials") {
+    return handleCredentials(ctx, provider, args, options);
+  }
+  if (provider.type === "oauth" || provider.type === "oidc") {
+    return handleOAuthProvider(ctx, provider, args, options);
+  }
+  const _typecheck: never = provider;
+  throw new Error(
+    `Provider type ${(provider as any).type} is not supported yet`,
+  );
+}
+
+async function handleEmailAndPhoneProvider(
+  ctx: EnrichedActionCtx,
+  provider: EmailConfig | PhoneConfig,
+  args: {
+    params?: Record<string, any>;
+    accountId?: GenericId<"account">;
+  },
+  options: {
+    generateTokens: boolean;
+    allowExtraProviders: boolean;
+  },
+): Promise<
+  | { kind: "started"; started: true }
+  | { kind: "signedIn"; signedIn: SessionInfoWithTokens }
+> {
+  if (args.params?.code !== undefined) {
+    const result = await callVerifyCodeAndSignIn(ctx, {
+      params: args.params,
+      provider: provider.id,
+      generateTokens: options.generateTokens,
+      allowExtraProviders: options.allowExtraProviders,
+    });
+    if (result === null) {
+      throw new Error("Could not verify code");
+    }
+    return {
+      kind: "signedIn",
+      signedIn: result as SessionInfoWithTokens,
+    };
+  }
+
+  const alphabet =
+    "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+  const code = provider.generateVerificationToken
+    ? await provider.generateVerificationToken()
+    : generateRandomString(32, alphabet);
+  const expirationTime =
+    Date.now() +
+    (provider.maxAge ?? DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S) * 1000;
+
+  const identifier = await callCreateVerificationCode(ctx, {
+    provider: provider.id,
+    accountId: args.accountId,
+    email: args.params?.email,
+    phone: args.params?.phone,
+    code,
+    expirationTime,
+    allowExtraProviders: options.allowExtraProviders,
+  });
+  const destination = await redirectAbsoluteUrl(
+    ctx.auth.config,
+    (args.params ?? {}) as { redirectTo: unknown },
+  );
+  const verificationArgs = {
+    identifier,
+    url: setURLSearchParam(destination, "code", code),
+    token: code,
+    expires: new Date(expirationTime),
+  };
+  if (provider.type === "email") {
+    await provider.sendVerificationRequest(
+      {
+        ...verificationArgs,
+        provider: {
+          ...provider,
+          from:
+            // Simplifies demo configuration of Resend
+            provider.from === "Auth.js <no-reply@authjs.dev>" &&
+            provider.id === "resend"
+              ? "My App <onboarding@resend.dev>"
+              : provider.from,
+        },
+        request: new Request("http://localhost"), // TODO: Document
+        theme: ctx.auth.config.theme,
+      },
+      // @ts-expect-error Figure out typing for email providers so they can
+      // access ctx.
+      ctx,
+    );
+  } else if (provider.type === "phone") {
+    await provider.sendVerificationRequest(
+      { ...verificationArgs, provider },
+      ctx,
+    );
+  }
+  return { kind: "started", started: true };
+}
+
+async function handleCredentials(
+  ctx: EnrichedActionCtx,
+  provider: ConvexCredentialsConfig,
+  args: {
+    params?: Record<string, any>;
+  },
+  options: {
+    generateTokens: boolean;
+  },
+): Promise<{ kind: "signedIn"; signedIn: SessionInfo | null }> {
+  const result = await provider.authorize(args.params ?? {}, ctx);
+  if (result === null) {
+    return { kind: "signedIn", signedIn: null };
+  }
+  const idsAndTokens = await callSignIn(ctx, {
+    userId: result.userId,
+    sessionId: result.sessionId,
+    generateTokens: options.generateTokens,
+  });
+  return {
+    kind: "signedIn",
+    signedIn: idsAndTokens,
+  };
+}
+
+async function handleOAuthProvider(
+  ctx: EnrichedActionCtx,
+  provider: OAuth2Config<any> | OIDCConfig<any>,
+  args: {
+    params?: Record<string, any>;
+    verifier?: string;
+  },
+  options: {
+    allowExtraProviders: boolean;
+  },
+): Promise<
+  | { kind: "signedIn"; signedIn: SessionInfoWithTokens | null }
+  | { kind: "redirect"; redirect: string; verifier: string }
+> {
+  // We have this action because:
+  // 1. We remember the current sessionId if any, so we can link accounts
+  // 2. The client doesn't need to know the HTTP Actions URL
+  //    of the backend (this simplifies using local backend)
+  // 3. The client doesn't need to know which provider is of which type,
+  //    and hence which provider requires client-side redirect
+  // 4. On mobile the client can complete the flow manually
+  if (args.params?.code !== undefined) {
+    const result = await callVerifyCodeAndSignIn(ctx, {
+      params: args.params,
+      verifier: args.verifier,
+      generateTokens: true,
+      allowExtraProviders: options.allowExtraProviders,
+    });
+    return {
+      kind: "signedIn",
+      signedIn: result as SessionInfoWithTokens | null,
+    };
+  }
+  const redirect = new URL(
+    (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv("CONVEX_SITE_URL")) + `/api/auth/signin/${provider.id}`,
+  );
+  const verifier = await callVerifier(ctx);
+  redirect.searchParams.set("code", verifier);
+  if (args.params?.redirectTo !== undefined) {
+    if (typeof args.params.redirectTo !== "string") {
+      throw new Error(
+        `Expected \`redirectTo\` to be a string, got ${args.params.redirectTo}`,
+      );
+    }
+    redirect.searchParams.set("redirectTo", args.params.redirectTo);
+  }
+  return { kind: "redirect", redirect: redirect.toString(), verifier };
+}

package/src/server/implementation/tokens.ts

@@ -0,0 +1,29 @@
+import { GenericId } from "convex/values";
+import { ConvexAuthConfig } from "../types.js";
+import { SignJWT, importPKCS8 } from "jose";
+import { requireEnv } from "../utils.js";
+import { TOKEN_SUB_CLAIM_DIVIDER } from "./utils.js";
+
+const DEFAULT_JWT_DURATION_MS = 1000 * 60 * 60; // 1 hour
+
+export async function generateToken(
+  args: {
+    userId: GenericId<"user">;
+    sessionId: GenericId<"session">;
+  },
+  config: ConvexAuthConfig,
+) {
+  const privateKey = await importPKCS8(requireEnv("JWT_PRIVATE_KEY"), "RS256");
+  const expirationTime = new Date(
+    Date.now() + (config.jwt?.durationMs ?? DEFAULT_JWT_DURATION_MS),
+  );
+  return await new SignJWT({
+    sub: args.userId + TOKEN_SUB_CLAIM_DIVIDER + args.sessionId,
+  })
+    .setProtectedHeader({ alg: "RS256" })
+    .setIssuedAt()
+    .setIssuer(requireEnv("CONVEX_SITE_URL"))
+    .setAudience("convex")
+    .setExpirationTime(expirationTime)
+    .sign(privateKey);
+}

package/src/server/implementation/types.ts

@@ -0,0 +1,220 @@
+import {
+  DataModelFromSchemaDefinition,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  TableNamesInDataModel,
+  defineSchema,
+  defineTable,
+} from "convex/server";
+import { GenericId, v } from "convex/values";
+import { GenericDoc } from "../convex_types.js";
+
+/**
+ * The table definitions required by the library.
+ *
+ * Your schema must include these so that the indexes
+ * are set up:
+ *
+ *
+ * ```ts filename="convex/schema.ts"
+ * import { defineSchema } from "convex/server";
+ * import { authTables } from "@robelest/convex-auth/component";
+ *
+ * const schema = defineSchema({
+ *   ...authTables,
+ * });
+ *
+ * export default schema;
+ * ```
+ *
+ * You can inline the table definitions into your schema
+ * and extend them with additional optional and required
+ * fields. See https://labs.convex.dev/auth/setup/schema
+ * for more details.
+ */
+export const authTables = {
+  /**
+   * Users.
+   */
+  user: defineTable({
+    name: v.optional(v.string()),
+    image: v.optional(v.string()),
+    email: v.optional(v.string()),
+    emailVerificationTime: v.optional(v.number()),
+    phone: v.optional(v.string()),
+    phoneVerificationTime: v.optional(v.number()),
+    isAnonymous: v.optional(v.boolean()),
+  })
+    .index("email", ["email"])
+    .index("phone", ["phone"]),
+  /**
+   * Sessions.
+   * A single user can have multiple active sessions.
+   * See [Session document lifecycle](https://labs.convex.dev/auth/advanced#session-document-lifecycle).
+   */
+  session: defineTable({
+    userId: v.id("user"),
+    expirationTime: v.number(),
+  }).index("userId", ["userId"]),
+  /**
+   * Accounts. An account corresponds to
+   * a single authentication provider.
+   * A single user can have multiple accounts linked.
+   */
+  account: defineTable({
+    userId: v.id("user"),
+    provider: v.string(),
+    providerAccountId: v.string(),
+    secret: v.optional(v.string()),
+    emailVerified: v.optional(v.string()),
+    phoneVerified: v.optional(v.string()),
+  })
+    .index("userIdAndProvider", ["userId", "provider"])
+    .index("providerAndAccountId", ["provider", "providerAccountId"]),
+  /**
+   * Refresh tokens.
+   * Refresh tokens are generally meant to be used once, to be exchanged for another
+   * refresh token and a JWT access token, but with a few exceptions:
+   * - The "active refresh token" is the most recently created refresh token that has
+   *   not been used yet. The parent of the active refresh token can always be used to
+   *   obtain the active refresh token.
+   * - A refresh token can be used within a 10 second window ("reuse window") to
+   *   obtain a new refresh token.
+   * - On any invalid use of a refresh token, the token itself and all its descendants
+   *   are invalidated.
+   */
+  token: defineTable({
+    sessionId: v.id("session"),
+    expirationTime: v.number(),
+    firstUsedTime: v.optional(v.number()),
+    // This is the ID of the refresh token that was exchanged to create this one.
+    parentRefreshTokenId: v.optional(v.id("token")),
+  })
+    // Sort by creationTime
+    .index("sessionId", ["sessionId"])
+    .index("sessionIdAndParentRefreshTokenId", [
+      "sessionId",
+      "parentRefreshTokenId",
+    ]),
+  /**
+   * Verification codes:
+   * - OTP tokens
+   * - magic link tokens
+   * - OAuth codes
+   */
+  verification: defineTable({
+    accountId: v.id("account"),
+    provider: v.string(),
+    code: v.string(),
+    expirationTime: v.number(),
+    verifier: v.optional(v.string()),
+    emailVerified: v.optional(v.string()),
+    phoneVerified: v.optional(v.string()),
+  })
+    .index("accountId", ["accountId"])
+    .index("code", ["code"]),
+  /**
+   * PKCE verifiers for OAuth.
+   */
+  verifier: defineTable({
+    sessionId: v.optional(v.id("session")),
+    signature: v.optional(v.string()),
+  }).index("signature", ["signature"]),
+  /**
+   * Rate limits for OTP and password sign-in.
+   */
+  limit: defineTable({
+    identifier: v.string(),
+    lastAttemptTime: v.number(),
+    attemptsLeft: v.number(),
+  }).index("identifier", ["identifier"]),
+
+  organization: defineTable({
+    name: v.string(),
+    slug: v.optional(v.string()),
+    ownerUserId: v.optional(v.id("user")),
+    parentOrganizationId: v.optional(v.id("organization")),
+    metadata: v.optional(v.any()),
+  })
+    .index("slug", ["slug"])
+    .index("ownerUserId", ["ownerUserId"])
+    .index("parentOrganizationId", ["parentOrganizationId"]),
+  team: defineTable({
+    organizationId: v.id("organization"),
+    name: v.string(),
+    slug: v.optional(v.string()),
+    parentTeamId: v.optional(v.id("team")),
+    metadata: v.optional(v.any()),
+  })
+    .index("organizationId", ["organizationId"])
+    .index("organizationIdAndSlug", ["organizationId", "slug"])
+    .index("parentTeamId", ["parentTeamId"]),
+  teamRelation: defineTable({
+    organizationId: v.id("organization"),
+    parentTeamId: v.id("team"),
+    childTeamId: v.id("team"),
+    relation: v.optional(v.string()),
+  })
+    .index("organizationId", ["organizationId"])
+    .index("organizationIdAndParentTeamId", ["organizationId", "parentTeamId"])
+    .index("organizationIdAndChildTeamId", ["organizationId", "childTeamId"]),
+  member: defineTable({
+    organizationId: v.id("organization"),
+    userId: v.id("user"),
+    teamId: v.optional(v.id("team")),
+    role: v.optional(v.string()),
+    status: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+  })
+    .index("organizationId", ["organizationId"])
+    .index("organizationIdAndUserId", ["organizationId", "userId"])
+    .index("teamId", ["teamId"])
+    .index("userId", ["userId"]),
+  invite: defineTable({
+    organizationId: v.optional(v.id("organization")),
+    teamId: v.optional(v.id("team")),
+    invitedByUserId: v.id("user"),
+    email: v.string(),
+    tokenHash: v.string(),
+    role: v.optional(v.string()),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("accepted"),
+      v.literal("revoked"),
+      v.literal("expired"),
+    ),
+    expiresTime: v.number(),
+    acceptedByUserId: v.optional(v.id("user")),
+    acceptedTime: v.optional(v.number()),
+    metadata: v.optional(v.any()),
+  })
+    .index("tokenHash", ["tokenHash"])
+    .index("emailAndStatus", ["email", "status"])
+    .index("invitedByUserIdAndStatus", ["invitedByUserId", "status"])
+    .index("organizationId", ["organizationId"])
+    .index("organizationIdAndStatus", ["organizationId", "status"]),
+};
+
+type DefaultSchema = ReturnType<typeof defineSchema<typeof authTables>>;
+
+export type AuthDataModel = DataModelFromSchemaDefinition<DefaultSchema>;
+export type ActionCtx = GenericActionCtx<AuthDataModel>;
+export type MutationCtx = GenericMutationCtx<AuthDataModel>;
+export type QueryCtx = GenericQueryCtx<AuthDataModel>;
+export type Doc<T extends TableNamesInDataModel<AuthDataModel>> = GenericDoc<
+  AuthDataModel,
+  T
+>;
+
+export type Tokens = { token: string; refreshToken: string };
+export type SessionInfo = {
+  userId: GenericId<"user">;
+  sessionId: GenericId<"session">;
+  tokens: Tokens | null;
+};
+export type SessionInfoWithTokens = {
+  userId: GenericId<"user">;
+  sessionId: GenericId<"session">;
+  tokens: Tokens;
+};