@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

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

@@ -0,0 +1,306 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import {
+  vEnterpriseWebhookDeliveryDoc,
+  vEnterpriseWebhookEndpointDoc,
+  vWebhookEndpointStatus,
+} from "../../model";
+
+/**
+ * Register a new webhook endpoint for an enterprise.
+ *
+ * Creates an `EnterpriseWebhookEndpoint` document with an initial failure
+ * count of `0`. The endpoint status defaults to `"active"` when not
+ * explicitly provided. Each endpoint subscribes to a set of event types
+ * that determine which deliveries are sent to it.
+ *
+ * @param args.enterpriseId - The ID of the enterprise this endpoint belongs to.
+ * @param args.groupId - The ID of the root group that owns the enterprise.
+ * @param args.url - The HTTPS URL where webhook payloads will be delivered.
+ * @param args.status - An optional lifecycle status (`"active"`, `"paused"`, or `"disabled"`). Defaults to `"active"`.
+ * @param args.secretHash - A hash of the signing secret used to verify delivery payloads.
+ * @param args.subscriptions - An array of event type strings this endpoint subscribes to (e.g. `["user.login", "scim.provision"]`).
+ * @param args.createdByUserId - An optional ID of the user who created this endpoint.
+ * @param args.extend - An optional arbitrary extension object for custom endpoint metadata.
+ * @returns The ID of the newly created `EnterpriseWebhookEndpoint` document.
+ *
+ * @example
+ * ```ts
+ * const endpointId = await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseWebhookEndpointCreate,
+ *   {
+ *     enterpriseId,
+ *     groupId: orgGroupId,
+ *     url: "https://acme.com/webhooks/auth",
+ *     secretHash: "sha256:whsec_...",
+ *     subscriptions: ["user.login", "user.created", "scim.provision"],
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseWebhookEndpointCreate = mutation({
+  args: {
+    enterpriseId: v.id("Enterprise"),
+    groupId: v.id("Group"),
+    url: v.string(),
+    status: v.optional(vWebhookEndpointStatus),
+    secretHash: v.string(),
+    subscriptions: v.array(v.string()),
+    createdByUserId: v.optional(v.id("User")),
+    extend: v.optional(v.any()),
+  },
+  returns: v.id("EnterpriseWebhookEndpoint"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("EnterpriseWebhookEndpoint", {
+      ...args,
+      status: args.status ?? "active",
+      failureCount: 0,
+    });
+  },
+});
+
+/**
+ * List all webhook endpoints registered for an enterprise.
+ *
+ * Returns all `EnterpriseWebhookEndpoint` documents associated with the
+ * given enterprise, regardless of status.
+ *
+ * @param args.enterpriseId - The ID of the enterprise whose webhook endpoints to list.
+ * @returns An array of webhook endpoint documents.
+ *
+ * @example
+ * ```ts
+ * const endpoints = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseWebhookEndpointList,
+ *   { enterpriseId },
+ * );
+ * for (const ep of endpoints) {
+ *   console.log(ep.url, ep.status, ep.subscriptions);
+ * }
+ * ```
+ */
+export const enterpriseWebhookEndpointList = query({
+  args: { enterpriseId: v.id("Enterprise") },
+  returns: v.array(vEnterpriseWebhookEndpointDoc),
+  handler: async (ctx, { enterpriseId }) => {
+    return await ctx.db
+      .query("EnterpriseWebhookEndpoint")
+      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
+      .collect();
+  },
+});
+
+/**
+ * Retrieve a single webhook endpoint by its document ID.
+ *
+ * Returns the full endpoint document if it exists, or `null` if no
+ * endpoint is found with the given ID.
+ *
+ * @param args.endpointId - The document ID of the webhook endpoint to retrieve.
+ * @returns The webhook endpoint document, or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const endpoint = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseWebhookEndpointGet,
+ *   { endpointId },
+ * );
+ * if (endpoint) {
+ *   console.log(endpoint.url, endpoint.failureCount);
+ * }
+ * ```
+ */
+export const enterpriseWebhookEndpointGet = query({
+  args: { endpointId: v.id("EnterpriseWebhookEndpoint") },
+  returns: v.union(vEnterpriseWebhookEndpointDoc, v.null()),
+  handler: async (ctx, { endpointId }) => {
+    return await ctx.db.get(endpointId);
+  },
+});
+
+/**
+ * Partially update (patch) an existing webhook endpoint.
+ *
+ * Merges the provided `data` fields into the endpoint document. Only the
+ * fields present in `data` are changed; all other fields are preserved.
+ * Common updates include changing the URL, rotating the secret, updating
+ * subscriptions, or changing the status.
+ *
+ * @param args.endpointId - The document ID of the webhook endpoint to update.
+ * @param args.data - An object containing the fields to update (e.g. `{ url, status, subscriptions }`).
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseWebhookEndpointUpdate,
+ *   {
+ *     endpointId,
+ *     data: {
+ *       status: "paused",
+ *       subscriptions: ["user.login"],
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseWebhookEndpointUpdate = mutation({
+  args: { endpointId: v.id("EnterpriseWebhookEndpoint"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { endpointId, data }) => {
+    await ctx.db.patch(endpointId, data);
+    return null;
+  },
+});
+
+/**
+ * Enqueue a webhook delivery for a specific endpoint.
+ *
+ * Creates a new `EnterpriseWebhookDelivery` document with an initial status
+ * of `"pending"` and an attempt count of `0`. The delivery will be picked up
+ * by the delivery worker once `nextAttemptAt` is reached.
+ *
+ * @param args.enterpriseId - The ID of the enterprise the delivery belongs to.
+ * @param args.endpointId - The ID of the webhook endpoint this delivery targets.
+ * @param args.auditEventId - An optional ID of the audit event that triggered this delivery.
+ * @param args.eventType - The event type string describing the payload (e.g. `"user.created"`).
+ * @param args.payload - The arbitrary JSON payload to deliver to the endpoint.
+ * @param args.nextAttemptAt - Epoch timestamp (ms) when the delivery should first be attempted.
+ * @returns The ID of the newly created `EnterpriseWebhookDelivery` document.
+ *
+ * @example
+ * ```ts
+ * const deliveryId = await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseWebhookDeliveryEnqueue,
+ *   {
+ *     enterpriseId,
+ *     endpointId,
+ *     auditEventId,
+ *     eventType: "user.created",
+ *     payload: { userId, email: "jane@acme.com" },
+ *     nextAttemptAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseWebhookDeliveryEnqueue = mutation({
+  args: {
+    enterpriseId: v.id("Enterprise"),
+    endpointId: v.id("EnterpriseWebhookEndpoint"),
+    auditEventId: v.optional(v.id("EnterpriseAuditEvent")),
+    eventType: v.string(),
+    payload: v.any(),
+    nextAttemptAt: v.number(),
+  },
+  returns: v.id("EnterpriseWebhookDelivery"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("EnterpriseWebhookDelivery", {
+      ...args,
+      status: "pending",
+      attemptCount: 0,
+    });
+  },
+});
+
+/**
+ * List pending webhook deliveries that are ready to be attempted.
+ *
+ * Queries the `status_next_attempt_at` index for deliveries with status
+ * `"pending"` whose `nextAttemptAt` is at or before the provided timestamp.
+ * This is used by the delivery worker to find deliveries due for processing.
+ *
+ * @param args.now - The current epoch timestamp (ms) used as the cutoff for `nextAttemptAt`.
+ * @param args.limit - Maximum number of deliveries to return (clamped between 1 and 100, defaults to 50).
+ * @returns An array of webhook delivery documents ready for dispatch.
+ *
+ * @example
+ * ```ts
+ * const ready = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseWebhookDeliveryListReady,
+ *   { now: Date.now(), limit: 10 },
+ * );
+ * for (const delivery of ready) {
+ *   await dispatchWebhook(delivery);
+ * }
+ * ```
+ */
+export const enterpriseWebhookDeliveryListReady = query({
+  args: { now: v.number(), limit: v.optional(v.number()) },
+  returns: v.array(vEnterpriseWebhookDeliveryDoc),
+  handler: async (ctx, { now, limit }) => {
+    return await ctx.db
+      .query("EnterpriseWebhookDelivery")
+      .withIndex("status_next_attempt_at", (idx) =>
+        idx.eq("status", "pending").lte("nextAttemptAt", now),
+      )
+      .take(Math.min(Math.max(limit ?? 50, 1), 100));
+  },
+});
+
+/**
+ * List webhook deliveries for a specific enterprise, ordered by most recent first.
+ *
+ * Returns deliveries in reverse chronological order, useful for displaying
+ * delivery history in an admin dashboard. Includes deliveries of all statuses.
+ *
+ * @param args.enterpriseId - The ID of the enterprise whose deliveries to list.
+ * @param args.limit - Maximum number of deliveries to return (clamped between 1 and 100, defaults to 50).
+ * @returns An array of webhook delivery documents, most recent first.
+ *
+ * @example
+ * ```ts
+ * const deliveries = await ctx.runQuery(
+ *   components.auth.enterprise.enterpriseWebhookDeliveryList,
+ *   { enterpriseId, limit: 25 },
+ * );
+ * for (const d of deliveries) {
+ *   console.log(d.eventType, d.status, d.attemptCount);
+ * }
+ * ```
+ */
+export const enterpriseWebhookDeliveryList = query({
+  args: { enterpriseId: v.id("Enterprise"), limit: v.optional(v.number()) },
+  returns: v.array(vEnterpriseWebhookDeliveryDoc),
+  handler: async (ctx, { enterpriseId, limit }) => {
+    return await ctx.db
+      .query("EnterpriseWebhookDelivery")
+      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
+      .order("desc")
+      .take(Math.min(Math.max(limit ?? 50, 1), 100));
+  },
+});
+
+/**
+ * Partially update (patch) an existing webhook delivery record.
+ *
+ * Merges the provided `data` fields into the delivery document. This is
+ * typically used by the delivery worker to update the delivery status,
+ * increment the attempt count, record response codes, or schedule retry
+ * timestamps after a delivery attempt.
+ *
+ * @param args.deliveryId - The document ID of the webhook delivery to update.
+ * @param args.data - An object containing the fields to update (e.g. `{ status, attemptCount, nextAttemptAt }`).
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.enterprise.enterpriseWebhookDeliveryPatch,
+ *   {
+ *     deliveryId,
+ *     data: {
+ *       status: "delivered",
+ *       attemptCount: 1,
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const enterpriseWebhookDeliveryPatch = mutation({
+  args: { deliveryId: v.id("EnterpriseWebhookDelivery"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { deliveryId, data }) => {
+    await ctx.db.patch(deliveryId, data);
+    return null;
+  },
+});

package/src/component/public/factors/devices.ts

@@ -0,0 +1,223 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vDeviceCodeDoc, vDeviceStatus } from "../../model";
+
+/**
+ * Insert a new device authorization record into the `DeviceCode` table.
+ *
+ * Creates a pending device authorization entry as part of the OAuth 2.0
+ * Device Authorization Grant (RFC 8628). The record tracks the hashed device
+ * code, the human-readable user code, expiry, and polling interval.
+ *
+ * @param deviceCodeHash - SHA-256 hash of the device code issued to the client.
+ *   Only the hash is stored; the raw code is never persisted.
+ * @param userCode - Short, human-readable code displayed to the end-user
+ *   so they can authorize the device on a separate screen.
+ * @param expiresAt - Unix timestamp (in milliseconds) after which the device
+ *   authorization request is no longer valid.
+ * @param interval - Minimum polling interval in seconds that the device client
+ *   must wait between token requests.
+ * @param status - Initial status of the device authorization (e.g. `"pending"`).
+ * @returns The `_id` of the newly created `DeviceCode` document.
+ *
+ * @example
+ * ```ts
+ * const deviceCodeId = await ctx.runMutation(
+ *   components.auth.factors.devices.deviceInsert,
+ *   {
+ *     deviceCodeHash: "a1b2c3d4e5f6...",
+ *     userCode: "ABCD-1234",
+ *     expiresAt: Date.now() + 10 * 60 * 1000,
+ *     interval: 5,
+ *     status: "pending",
+ *   },
+ * );
+ * ```
+ */
+export const deviceInsert = mutation({
+  args: {
+    deviceCodeHash: v.string(),
+    userCode: v.string(),
+    expiresAt: v.number(),
+    interval: v.number(),
+    status: vDeviceStatus,
+  },
+  returns: v.id("DeviceCode"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("DeviceCode", args);
+  },
+});
+
+/**
+ * Look up a device authorization record by its hashed device code.
+ *
+ * Queries the `DeviceCode` table using the `device_code_hash` index.
+ * This is the primary lookup used by the token endpoint when a device
+ * client polls for authorization status.
+ *
+ * @param deviceCodeHash - SHA-256 hash of the device code to look up.
+ * @returns The matching `DeviceCode` document, or `null` if no record
+ *   exists for the given hash.
+ *
+ * @example
+ * ```ts
+ * const deviceCode = await ctx.runQuery(
+ *   components.auth.factors.devices.deviceGetByCodeHash,
+ *   { deviceCodeHash: "a1b2c3d4e5f6..." },
+ * );
+ * if (deviceCode && deviceCode.status === "authorized") {
+ *   // Exchange for tokens
+ * }
+ * ```
+ */
+export const deviceGetByCodeHash = query({
+  args: { deviceCodeHash: v.string() },
+  returns: v.union(vDeviceCodeDoc, v.null()),
+  handler: async (ctx, { deviceCodeHash }) => {
+    return await ctx.db
+      .query("DeviceCode")
+      .withIndex("device_code_hash", (q) =>
+        q.eq("deviceCodeHash", deviceCodeHash),
+      )
+      .first();
+  },
+});
+
+/**
+ * Look up a pending device authorization by its user-facing code.
+ *
+ * Queries the `DeviceCode` table using the `user_code_status` compound index,
+ * filtering to only `"pending"` records. This is called when an authenticated
+ * user enters the code shown on the device to approve the authorization.
+ *
+ * @param userCode - The short, human-readable code the user typed in
+ *   (e.g. `"ABCD-1234"`).
+ * @returns The matching pending `DeviceCode` document, or `null` if no
+ *   pending authorization exists for the given user code.
+ *
+ * @example
+ * ```ts
+ * const pending = await ctx.runQuery(
+ *   components.auth.factors.devices.deviceGetByUserCode,
+ *   { userCode: "ABCD-1234" },
+ * );
+ * if (pending === null) {
+ *   throw new Error("Invalid or expired user code");
+ * }
+ * ```
+ */
+export const deviceGetByUserCode = query({
+  args: { userCode: v.string() },
+  returns: v.union(vDeviceCodeDoc, v.null()),
+  handler: async (ctx, { userCode }) => {
+    return await ctx.db
+      .query("DeviceCode")
+      .withIndex("user_code_status", (q) =>
+        q.eq("userCode", userCode).eq("status", "pending"),
+      )
+      .first();
+  },
+});
+
+/**
+ * Authorize a device code by linking it to a user and session.
+ *
+ * Transitions the device authorization status from `"pending"` to
+ * `"authorized"` and associates it with the approving user and their
+ * active session. After this mutation, the next poll from the device
+ * client will succeed and tokens can be issued.
+ *
+ * @param deviceId - The `_id` of the `DeviceCode` document to authorize.
+ * @param userId - The `_id` of the `User` who approved the device request.
+ * @param sessionId - The `_id` of the `Session` associated with the
+ *   approving user's current login.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.devices.deviceAuthorize,
+ *   {
+ *     deviceId: pending._id,
+ *     userId: currentUser._id,
+ *     sessionId: currentSession._id,
+ *   },
+ * );
+ * ```
+ */
+export const deviceAuthorize = mutation({
+  args: {
+    deviceId: v.id("DeviceCode"),
+    userId: v.id("User"),
+    sessionId: v.id("Session"),
+  },
+  returns: v.null(),
+  handler: async (ctx, { deviceId, userId, sessionId }) => {
+    await ctx.db.patch("DeviceCode", deviceId, {
+      status: "authorized",
+      userId,
+      sessionId,
+    });
+    return null;
+  },
+});
+
+/**
+ * Update the last-polled timestamp on a device authorization record.
+ *
+ * Called each time the device client polls the token endpoint. The
+ * timestamp is used to enforce the minimum polling interval and to
+ * detect slow-polling violations per RFC 8628.
+ *
+ * @param deviceId - The `_id` of the `DeviceCode` document to update.
+ * @param lastPolledAt - Unix timestamp (in milliseconds) of the most
+ *   recent poll request from the device client.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   components.auth.factors.devices.deviceUpdateLastPolled,
+ *   {
+ *     deviceId: deviceCode._id,
+ *     lastPolledAt: Date.now(),
+ *   },
+ * );
+ * ```
+ */
+export const deviceUpdateLastPolled = mutation({
+  args: { deviceId: v.id("DeviceCode"), lastPolledAt: v.number() },
+  returns: v.null(),
+  handler: async (ctx, { deviceId, lastPolledAt }) => {
+    await ctx.db.patch("DeviceCode", deviceId, { lastPolledAt });
+    return null;
+  },
+});
+
+/**
+ * Delete a device authorization record from the `DeviceCode` table.
+ *
+ * Permanently removes the device code entry. This should be called after
+ * the device authorization has been successfully exchanged for tokens, or
+ * when the authorization has expired and needs to be cleaned up.
+ *
+ * @param deviceId - The `_id` of the `DeviceCode` document to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Clean up after successful token exchange
+ * await ctx.runMutation(
+ *   components.auth.factors.devices.deviceDelete,
+ *   { deviceId: deviceCode._id },
+ * );
+ * ```
+ */
+export const deviceDelete = mutation({
+  args: { deviceId: v.id("DeviceCode") },
+  returns: v.null(),
+  handler: async (ctx, { deviceId }) => {
+    await ctx.db.delete("DeviceCode", deviceId);
+    return null;
+  },
+});