@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/src/component/model.ts

@@ -29,6 +29,12 @@ export const TABLES = {
 
 export const vTag = v.object({ key: v.string(), value: v.string() });
 
+export const vPaginated = (item: any) =>
+  v.object({
+    items: v.array(item),
+    nextCursor: v.union(v.string(), v.null()),
+  });
+
 export const vInviteStatus = v.union(
   v.literal("pending"),
   v.literal("accepted"),

package/src/component/public/enterprise/audit.ts

@@ -0,0 +1,120 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vAuditActorType, vAuditStatus, vEnterpriseAuditEventDoc } from "../../model";
+
+/**
+ * Record a new audit event for an enterprise.
+ *
+ * Inserts an immutable audit log entry capturing who performed what action,
+ * on which subject, and whether it succeeded or failed. Use this to maintain
+ * a tamper-evident trail of security-relevant events.
+ *
+ * @param args.enterpriseId - The ID of the enterprise this event belongs to.
+ * @param args.groupId - The ID of the root group that owns the enterprise.
+ * @param args.eventType - A string identifying the type of event (e.g. `"user.login"`, `"scim.provision"`).
+ * @param args.actorType - The kind of actor: `"user"`, `"system"`, `"scim"`, `"api_key"`, or `"webhook"`.
+ * @param args.actorId - An optional identifier for the actor (e.g. a user ID or API key ID).
+ * @param args.subjectType - The type of the resource being acted upon (e.g. `"user"`, `"group"`).
+ * @param args.subjectId - An optional identifier for the subject resource.
+ * @param args.status - Whether the event represents a `"success"` or `"failure"`.
+ * @param args.occurredAt - Epoch timestamp (ms) when the event occurred.
+ * @param args.requestId - An optional correlation ID tying this event to a specific request.
+ * @param args.ip - An optional IP address of the actor.
+ * @param args.metadata - An optional arbitrary object with additional event details.
+ * @returns The ID of the newly created `EnterpriseAuditEvent` document.
+ *
+ * @example
+ * ```ts
+ * const eventId = await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseAuditEventCreate,
+ *   {
+ *     enterpriseId,
+ *     groupId: orgGroupId,
+ *     eventType: "user.login",
+ *     actorType: "user",
+ *     actorId: userId,
+ *     subjectType: "session",
+ *     subjectId: sessionId,
+ *     status: "success",
+ *     occurredAt: Date.now(),
+ *     ip: "203.0.113.42",
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseAuditEventCreate = mutation({
+  args: {
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    eventType: v.string(),
+    actorType: vAuditActorType,
+    actorId: v.optional(v.string()),
+    subjectType: v.string(),
+    subjectId: v.optional(v.string()),
+    status: vAuditStatus,
+    occurredAt: v.number(),
+    requestId: v.optional(v.string()),
+    ip: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+  },
+  returns: v.id("EnterpriseAuditEvent"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("EnterpriseAuditEvent", args);
+  },
+});
+
+/**
+ * List audit events, optionally filtered by enterprise or group.
+ *
+ * Returns audit events in reverse chronological order. When `enterpriseId` is
+ * provided, events are filtered using the `enterprise_id_occurred_at` index.
+ * When only `groupId` is provided, the `group_id_occurred_at` index is used.
+ * If neither filter is given, the most recent events across all enterprises
+ * are returned.
+ *
+ * @param args.enterpriseId - An optional enterprise ID to scope events to a single enterprise.
+ * @param args.groupId - An optional group ID to scope events to a single group.
+ * @param args.limit - Maximum number of events to return (clamped between 1 and 100, defaults to 50).
+ * @returns An array of audit event documents, most recent first.
+ *
+ * @example
+ * ```ts
+ * const events = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseAuditEventList,
+ *   { enterpriseId, limit: 20 },
+ * );
+ * for (const event of events) {
+ *   console.log(event.eventType, event.actorType, event.status);
+ * }
+ * ```
+ */
+export const enterpriseAuditEventList = query({
+  args: {
+    enterpriseId: v.optional(v.id("Enterprise")),
+    groupId: v.optional(v.id("Group")),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(vEnterpriseAuditEventDoc),
+  handler: async (ctx, args) => {
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+    if (args.enterpriseId !== undefined) {
+      return await ctx.db
+        .query("EnterpriseAuditEvent")
+        .withIndex("enterprise_id_occurred_at", (idx) =>
+          idx.eq("enterpriseId", args.enterpriseId!),
+        )
+        .order("desc")
+        .take(limit);
+    }
+    if (args.groupId !== undefined) {
+      return await ctx.db
+        .query("EnterpriseAuditEvent")
+        .withIndex("group_id_occurred_at", (idx) =>
+          idx.eq("groupId", args.groupId!),
+        )
+        .order("desc")
+        .take(limit);
+    }
+    return await ctx.db.query("EnterpriseAuditEvent").order("desc").take(limit);
+  },
+});

package/src/component/public/enterprise/core.ts

@@ -0,0 +1,354 @@
+import { ConvexError, v } from "convex/values";
+import { mutation, query } from "../../functions";
+import {
+  vEnterpriseDoc,
+  vEnterpriseDomainDoc,
+  vEnterprisePolicy,
+  vEnterpriseStatus,
+  vPaginated,
+} from "../../model";
+
+/**
+ * Create a new enterprise record attached to a root group.
+ *
+ * Each group may only have one enterprise record. If an enterprise already
+ * exists for the given group, a `ENTERPRISE_ALREADY_EXISTS` error is thrown.
+ * The enterprise status defaults to `"draft"` when not explicitly provided.
+ *
+ * @param args.groupId - The ID of the root group that owns this enterprise.
+ * @param args.slug - An optional URL-friendly identifier for the enterprise.
+ * @param args.name - An optional human-readable display name for the enterprise.
+ * @param args.status - The lifecycle status (`"draft"`, `"active"`, or `"disabled"`). Defaults to `"draft"`.
+ * @param args.policy - An optional enterprise policy object controlling identity linking, provisioning, and deprovisioning behavior.
+ * @param args.config - An optional arbitrary configuration blob for enterprise-specific settings.
+ * @param args.extend - An optional arbitrary extension object for custom fields.
+ * @returns The ID of the newly created `Enterprise` document.
+ *
+ * @example
+ * ```ts
+ * const enterpriseId = await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseCreate,
+ *   {
+ *     groupId: orgGroupId,
+ *     slug: "acme-corp",
+ *     name: "Acme Corporation",
+ *     status: "active",
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseCreate = mutation({
+  args: {
+    groupId: v.id("Group"),
+    slug: v.optional(v.string()),
+    name: v.optional(v.string()),
+    status: v.optional(vEnterpriseStatus),
+    policy: v.optional(vEnterprisePolicy),
+    config: v.optional(v.any()),
+    extend: v.optional(v.any()),
+  },
+  returns: v.id("Enterprise"),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("Enterprise")
+      .withIndex("group_id", (idx) => idx.eq("groupId", args.groupId))
+      .first();
+    if (existing) {
+      throw new ConvexError({
+        code: "ENTERPRISE_ALREADY_EXISTS",
+        message: "An enterprise record already exists for this group.",
+      });
+    }
+    return await ctx.db.insert("Enterprise", {
+      ...args,
+      status: args.status ?? "draft",
+    });
+  },
+});
+
+/**
+ * Retrieve a single enterprise record by its document ID.
+ *
+ * Returns the full enterprise document if it exists, or `null` if no
+ * enterprise is found with the given ID.
+ *
+ * @param args.enterpriseId - The document ID of the enterprise to retrieve.
+ * @returns The enterprise document, or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const enterprise = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseGet,
+ *   { enterpriseId },
+ * );
+ * if (enterprise) {
+ *   console.log(enterprise.name, enterprise.status);
+ * }
+ * ```
+ */
+export const enterpriseGet = query({
+  args: { enterpriseId: v.id("Enterprise") },
+  returns: v.union(vEnterpriseDoc, v.null()),
+  handler: async (ctx, { enterpriseId }) => {
+    return await ctx.db.get("Enterprise", enterpriseId);
+  },
+});
+
+/**
+ * Retrieve an enterprise record by the ID of its owning group.
+ *
+ * Looks up the enterprise that is linked to the specified group using the
+ * `group_id` index. Returns `null` if no enterprise is associated with the group.
+ *
+ * @param args.groupId - The ID of the root group whose enterprise record to look up.
+ * @returns The enterprise document, or `null` if the group has no enterprise.
+ *
+ * @example
+ * ```ts
+ * const enterprise = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseGetByGroup,
+ *   { groupId: orgGroupId },
+ * );
+ * ```
+ */
+export const enterpriseGetByGroup = query({
+  args: { groupId: v.id("Group") },
+  returns: v.union(vEnterpriseDoc, v.null()),
+  handler: async (ctx, { groupId }) => {
+    return await ctx.db
+      .query("Enterprise")
+      .withIndex("group_id", (idx) => idx.eq("groupId", groupId))
+      .first();
+  },
+});
+
+/**
+ * Retrieve an enterprise record by one of its linked domain names.
+ *
+ * Looks up an `EnterpriseDomain` row matching the given domain string, then
+ * resolves the parent enterprise. Returns both the enterprise and the matched
+ * domain document, or `null` if the domain is not registered or its enterprise
+ * no longer exists.
+ *
+ * @param args.domain - The domain name to search for (e.g. `"acme.com"`).
+ * @returns An object containing the `enterprise` and `domain` documents, or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const result = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseGetByDomain,
+ *   { domain: "acme.com" },
+ * );
+ * if (result) {
+ *   console.log(result.enterprise.name, result.domain.verifiedAt);
+ * }
+ * ```
+ */
+export const enterpriseGetByDomain = query({
+  args: { domain: v.string() },
+  returns: v.union(
+    v.object({
+      enterprise: vEnterpriseDoc,
+      domain: vEnterpriseDomainDoc,
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, { domain }) => {
+    const domainRow = await ctx.db
+      .query("EnterpriseDomain")
+      .withIndex("domain", (idx) => idx.eq("domain", domain))
+      .first();
+    if (!domainRow) {
+      return null;
+    }
+    const enterprise = await ctx.db.get("Enterprise", domainRow.enterpriseId);
+    if (!enterprise) {
+      return null;
+    }
+    return { enterprise, domain: domainRow };
+  },
+});
+
+/**
+ * List enterprise records with optional filtering and cursor-based pagination.
+ *
+ * Supports filtering by `groupId`, `slug`, and/or `status`. The query selects
+ * the most specific index available for the primary filter, then applies
+ * remaining predicates as post-filters. Results are ordered by creation time
+ * (or the specified field) and paginated using an opaque cursor.
+ *
+ * @param args.where - Optional filter criteria: `groupId`, `slug`, and/or `status`.
+ * @param args.limit - Maximum number of items per page (clamped between 1 and 100, defaults to 50).
+ * @param args.cursor - An opaque cursor string returned from a previous call to fetch the next page, or `null` / omitted for the first page.
+ * @param args.orderBy - The field to sort results by: `"_creationTime"`, `"name"`, `"slug"`, or `"status"`.
+ * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
+ * @returns A paginated result containing `items` (array of enterprise documents) and `nextCursor` (`string | null`).
+ *
+ * @example
+ * ```ts
+ * const page = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseList,
+ *   {
+ *     where: { status: "active" },
+ *     limit: 25,
+ *     order: "asc",
+ *   },
+ * );
+ * for (const ent of page.items) {
+ *   console.log(ent.name);
+ * }
+ * // Fetch next page:
+ * const nextPage = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseList,
+ *   { where: { status: "active" }, cursor: page.nextCursor },
+ * );
+ * ```
+ */
+export const enterpriseList = query({
+  args: {
+    where: v.optional(
+      v.object({
+        groupId: v.optional(v.id("Group")),
+        slug: v.optional(v.string()),
+        status: v.optional(vEnterpriseStatus),
+      }),
+    ),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.union(v.string(), v.null())),
+    orderBy: v.optional(
+      v.union(
+        v.literal("_creationTime"),
+        v.literal("name"),
+        v.literal("slug"),
+        v.literal("status"),
+      ),
+    ),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+  },
+  returns: vPaginated(vEnterpriseDoc),
+  handler: async (ctx, args) => {
+    const where = args.where ?? {};
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+    const order = args.order ?? "desc";
+
+    let q;
+    if (where.groupId !== undefined) {
+      q = ctx.db
+        .query("Enterprise")
+        .withIndex("group_id", (idx) => idx.eq("groupId", where.groupId!));
+    } else if (where.slug !== undefined) {
+      q = ctx.db
+        .query("Enterprise")
+        .withIndex("slug", (idx) => idx.eq("slug", where.slug!));
+    } else if (where.status !== undefined) {
+      q = ctx.db
+        .query("Enterprise")
+        .withIndex("status", (idx) => idx.eq("status", where.status!));
+    } else {
+      q = ctx.db.query("Enterprise");
+    }
+
+    if (where.groupId !== undefined && where.slug !== undefined) {
+      q = q.filter((f) => f.eq(f.field("slug"), where.slug!));
+    }
+    if (where.status !== undefined && where.groupId === undefined) {
+      // already handled by index in the dedicated branch
+    } else if (where.status !== undefined) {
+      q = q.filter((f) => f.eq(f.field("status"), where.status!));
+    }
+
+    q = q.order(order);
+    const all = await q.collect();
+    let startIdx = 0;
+    if (args.cursor) {
+      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);
+      if (cursorIdx !== -1) {
+        startIdx = cursorIdx + 1;
+      }
+    }
+    const page = all.slice(startIdx, startIdx + limit + 1);
+    const hasMore = page.length > limit;
+    const items = hasMore ? page.slice(0, limit) : page;
+    const nextCursor = hasMore ? items[items.length - 1]._id : null;
+    return { items, nextCursor };
+  },
+});
+
+/**
+ * Partially update (patch) an existing enterprise record.
+ *
+ * Merges the provided `data` fields into the existing enterprise document.
+ * Only the fields present in `data` are changed; all other fields are preserved.
+ *
+ * @param args.enterpriseId - The document ID of the enterprise to update.
+ * @param args.data - An object containing the fields to update (e.g. `{ name, status, policy }`).
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseUpdate,
+ *   {
+ *     enterpriseId,
+ *     data: { status: "active", name: "Acme Corp (Renamed)" },
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseUpdate = mutation({
+  args: { enterpriseId: v.id("Enterprise"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { enterpriseId, data }) => {
+    await ctx.db.patch(enterpriseId, data);
+    return null;
+  },
+});
+
+/**
+ * Delete an enterprise record and all of its associated child data.
+ *
+ * This cascading delete removes the enterprise document along with all linked
+ * domain records, domain verification records, and enterprise secrets. Callers
+ * should ensure that higher-level cleanup (e.g. SCIM identities, webhook
+ * endpoints) is handled separately if needed.
+ *
+ * @param args.enterpriseId - The document ID of the enterprise to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseDelete,
+ *   { enterpriseId },
+ * );
+ * ```
+ */
+export const enterpriseDelete = mutation({
+  args: { enterpriseId: v.id("Enterprise") },
+  returns: v.null(),
+  handler: async (ctx, { enterpriseId }) => {
+    const domains = await ctx.db
+      .query("EnterpriseDomain")
+      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
+      .collect();
+    for (const domain of domains) {
+      const verification = await ctx.db
+        .query("EnterpriseDomainVerification")
+        .withIndex("domain_id", (idx) => idx.eq("domainId", domain._id))
+        .first();
+      if (verification) {
+        await ctx.db.delete(verification._id);
+      }
+      await ctx.db.delete(domain._id);
+    }
+    const secrets = await ctx.db
+      .query("EnterpriseSecret")
+      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
+      .collect();
+    for (const secret of secrets) {
+      await ctx.db.delete(secret._id);
+    }
+    await ctx.db.delete(enterpriseId);
+    return null;
+  },
+});