@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

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

@@ -1,307 +0,0 @@
-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

@@ -1,224 +0,0 @@
-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;
-  },
-});