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

package/src/component/public/security/keys.ts

@@ -1,366 +0,0 @@
-import { ConvexError, v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import {
-  vApiKeyDoc,
-  vApiKeyRateLimit,
-  vApiKeyRateLimitState,
-  vApiKeyScope,
-  vPaginated,
-} from "../../model";
-
-// ============================================================================
-// API Keys
-// ============================================================================
-
-/**
- * Insert a new API key record into the `ApiKey` table.
- *
- * Creates an API key entry with the given metadata and scopes. The caller
- * is responsible for generating and hashing the raw key before passing it
- * here -- this function only stores the hash, never the plaintext key.
- * The `createdAt` timestamp and `revoked: false` flag are set automatically.
- *
- * @param userId - The `_id` of the `User` who owns this API key.
- * @param prefix - A short, visible prefix for the key (e.g. `"sk_live_"`)
- *   that helps users identify which key was used without exposing the secret.
- * @param hashedKey - SHA-256 hash of the full API key string. Used for
- *   constant-time lookup during Bearer token verification.
- * @param name - Human-readable name for the key (e.g. `"Production Backend"`).
- * @param scopes - Array of permission scopes, each containing a `resource`
- *   name and an array of allowed `actions` (e.g.
- *   `[{ resource: "messages", actions: ["read", "write"] }]`).
- * @param rateLimit - Optional rate limit configuration to apply per-key
- *   (e.g. max requests per window).
- * @param expiresAt - Optional Unix timestamp (in milliseconds) after which
- *   the key is no longer valid. Omit for non-expiring keys.
- * @param metadata - Optional arbitrary metadata to attach to the key record.
- * @returns The `_id` of the newly created `ApiKey` document.
- *
- * @example
- * ```ts
- * const keyId = await ctx.runMutation(
- *   components.auth.security.keys.keyInsert,
- *   {
- *     userId: user._id,
- *     prefix: "sk_live_",
- *     hashedKey: await sha256(rawKey),
- *     name: "Production Backend",
- *     scopes: [{ resource: "messages", actions: ["read", "write"] }],
- *     expiresAt: Date.now() + 90 * 24 * 60 * 60 * 1000,
- *   },
- * );
- * ```
- */
-export const keyInsert = mutation({
-  args: {
-    userId: v.id("User"),
-    prefix: v.string(),
-    hashedKey: v.string(),
-    name: v.string(),
-    scopes: v.array(
-      v.object({
-        resource: v.string(),
-        actions: v.array(v.string()),
-      }),
-    ),
-    rateLimit: v.optional(vApiKeyRateLimit),
-    expiresAt: v.optional(v.number()),
-    metadata: v.optional(v.any()),
-  },
-  returns: v.id("ApiKey"),
-  handler: async (ctx, args) => {
-    return await ctx.db.insert("ApiKey", {
-      ...args,
-      createdAt: Date.now(),
-      revoked: false,
-    });
-  },
-});
-
-/**
- * Look up an API key by its SHA-256 hash.
- *
- * Queries the `ApiKey` table using the `hashed_key` index. This is the
- * primary lookup path during Bearer token verification: the incoming
- * token is hashed and matched against stored hashes in constant time.
- * Returns the full key record including scopes, rate limit state, and
- * revocation status so the caller can perform authorization checks.
- *
- * @param hashedKey - SHA-256 hash of the API key string extracted from
- *   the `Authorization: Bearer <token>` header.
- * @returns The matching `ApiKey` document (including rate limit state),
- *   or `null` if no key matches the given hash.
- *
- * @example
- * ```ts
- * const apiKey = await ctx.runQuery(
- *   components.auth.security.keys.keyGetByHashedKey,
- *   { hashedKey: await sha256(bearerToken) },
- * );
- * if (apiKey === null || apiKey.revoked) {
- *   throw new Error("Invalid or revoked API key");
- * }
- * ```
- */
-export const keyGetByHashedKey = query({
-  args: { hashedKey: v.string() },
-  returns: v.union(vApiKeyDoc, v.null()),
-  handler: async (ctx, { hashedKey }) => {
-    return await ctx.db
-      .query("ApiKey")
-      .withIndex("hashed_key", (q) => q.eq("hashedKey", hashedKey))
-      .first();
-  },
-});
-
-/**
- * List API keys with optional filtering, sorting, and cursor-based pagination.
- *
- * Returns a paginated result `{ items, nextCursor }` from the `ApiKey`
- * table. Supports filtering by `userId`, `revoked` status, `name`, and
- * `prefix`. The page size is clamped between 1 and 100 (default 50).
- * Pass the returned `nextCursor` as `cursor` in a subsequent call to
- * fetch the next page.
- *
- * @param where - Optional filter object. All specified fields are
- *   combined with AND logic:
- *   - `userId` -- restrict to keys owned by this user.
- *   - `revoked` -- `true` for revoked keys, `false` for active keys.
- *   - `name` -- exact match on the key's human-readable name.
- *   - `prefix` -- exact match on the key prefix string.
- * @param limit - Maximum number of items to return per page (1--100,
- *   default `50`).
- * @param cursor - Opaque cursor string (an `ApiKey` document `_id`)
- *   returned from a previous call. Pass `null` or omit for the first page.
- * @param orderBy - Field to sort by. One of `"_creationTime"`, `"name"`,
- *   `"lastUsedAt"`, `"expiresAt"`, or `"revoked"`. Defaults to
- *   `"_creationTime"`.
- * @param order - Sort direction, `"asc"` or `"desc"` (default `"desc"`).
- * @returns An object with `items` (array of `ApiKey` documents) and
- *   `nextCursor` (string ID of the last item, or `null` if no more pages).
- *
- * @example
- * ```ts
- * // Fetch the first page of active keys for a user
- * const page = await ctx.runQuery(
- *   components.auth.security.keys.keyList,
- *   {
- *     where: { userId: user._id, revoked: false },
- *     limit: 20,
- *     order: "desc",
- *   },
- * );
- * // Fetch the next page
- * if (page.nextCursor) {
- *   const page2 = await ctx.runQuery(
- *     components.auth.security.keys.keyList,
- *     { where: { userId: user._id, revoked: false }, cursor: page.nextCursor },
- *   );
- * }
- * ```
- */
-export const keyList = query({
-  args: {
-    where: v.optional(
-      v.object({
-        userId: v.optional(v.id("User")),
-        revoked: v.optional(v.boolean()),
-        name: v.optional(v.string()),
-        prefix: v.optional(v.string()),
-      }),
-    ),
-    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("lastUsedAt"),
-        v.literal("expiresAt"),
-        v.literal("revoked"),
-      ),
-    ),
-    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
-  },
-  returns: vPaginated(vApiKeyDoc),
-  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.userId !== undefined) {
-      q = ctx.db
-        .query("ApiKey")
-        .withIndex("user_id", (idx) => idx.eq("userId", where.userId!));
-    } else {
-      q = ctx.db.query("ApiKey");
-    }
-
-    if (where.revoked !== undefined) {
-      q = q.filter((f) => f.eq(f.field("revoked"), where.revoked!));
-    }
-    if (where.name !== undefined) {
-      q = q.filter((f) => f.eq(f.field("name"), where.name!));
-    }
-    if (where.prefix !== undefined) {
-      q = q.filter((f) => f.eq(f.field("prefix"), where.prefix!));
-    }
-
-    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 };
-  },
-});
-
-/**
- * Get a single API key by its document ID.
- *
- * Performs a direct document lookup on the `ApiKey` table. Useful when
- * you already have the key's `_id` (e.g. from a list query or a stored
- * reference) and need to retrieve its full details.
- *
- * @param keyId - The `_id` of the `ApiKey` document to retrieve.
- * @returns The `ApiKey` document, or `null` if no key exists with the
- *   given ID.
- *
- * @example
- * ```ts
- * const apiKey = await ctx.runQuery(
- *   components.auth.security.keys.keyGetById,
- *   { keyId: storedKeyId },
- * );
- * if (apiKey !== null) {
- *   console.log(apiKey.name, apiKey.scopes);
- * }
- * ```
- */
-export const keyGetById = query({
-  args: { keyId: v.id("ApiKey") },
-  returns: v.union(vApiKeyDoc, v.null()),
-  handler: async (ctx, { keyId }) => {
-    return await ctx.db.get("ApiKey", keyId);
-  },
-});
-
-/**
- * Patch an API key record with partial updates.
- *
- * Performs a partial update on the `ApiKey` document. Supports modifying
- * the key's name, scopes, rate limit configuration, rate limit state,
- * revocation flag, and last-used timestamp. Throws a `ConvexError` with
- * code `"KEY_NOT_FOUND"` if the key does not exist.
- *
- * @param keyId - The `_id` of the `ApiKey` document to update.
- * @param data - An object containing the fields to patch. All fields are
- *   optional:
- *   - `name` -- Updated human-readable name.
- *   - `scopes` -- Replacement array of permission scopes.
- *   - `rateLimit` -- Updated rate limit configuration.
- *   - `rateLimitState` -- Updated rate limit tracking state (token
- *     count, last refill time).
- *   - `revoked` -- Set to `true` to revoke the key, `false` to
- *     reinstate it.
- *   - `lastUsedAt` -- Unix timestamp (in milliseconds) of the most
- *     recent API call using this key.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * // Revoke an API key
- * await ctx.runMutation(
- *   components.auth.security.keys.keyPatch,
- *   {
- *     keyId: apiKey._id,
- *     data: { revoked: true },
- *   },
- * );
- *
- * // Rename and update scopes
- * await ctx.runMutation(
- *   components.auth.security.keys.keyPatch,
- *   {
- *     keyId: apiKey._id,
- *     data: {
- *       name: "Read-Only Key",
- *       scopes: [{ resource: "messages", actions: ["read"] }],
- *     },
- *   },
- * );
- * ```
- */
-export const keyPatch = mutation({
-  args: {
-    keyId: v.id("ApiKey"),
-    data: v.object({
-      name: v.optional(v.string()),
-      scopes: v.optional(v.array(vApiKeyScope)),
-      rateLimit: v.optional(vApiKeyRateLimit),
-      rateLimitState: v.optional(vApiKeyRateLimitState),
-      revoked: v.optional(v.boolean()),
-      lastUsedAt: v.optional(v.number()),
-    }),
-  },
-  returns: v.null(),
-  handler: async (ctx, { keyId, data }) => {
-    const key = await ctx.db.get("ApiKey", keyId);
-    if (key === null) {
-      throw new ConvexError({
-        code: "KEY_NOT_FOUND",
-        message: "API key not found",
-        keyId,
-      });
-    }
-    await ctx.db.patch("ApiKey", keyId, data);
-    return null;
-  },
-});
-
-/**
- * Hard-delete an API key record from the `ApiKey` table.
- *
- * Permanently removes the API key document. Unlike revocation (which
- * keeps the record for audit purposes), this is an irreversible
- * deletion. Throws a `ConvexError` with code `"KEY_NOT_FOUND"` if the
- * key does not exist.
- *
- * @param keyId - The `_id` of the `ApiKey` document to delete.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   components.auth.security.keys.keyDelete,
- *   { keyId: apiKey._id },
- * );
- * ```
- */
-export const keyDelete = mutation({
-  args: { keyId: v.id("ApiKey") },
-  returns: v.null(),
-  handler: async (ctx, { keyId }) => {
-    const key = await ctx.db.get("ApiKey", keyId);
-    if (key === null) {
-      throw new ConvexError({
-        code: "KEY_NOT_FOUND",
-        message: "API key not found",
-        keyId,
-      });
-    }
-    await ctx.db.delete("ApiKey", keyId);
-    return null;
-  },
-});

package/src/component/public/security/limits.ts

@@ -1,174 +0,0 @@
-import { v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import { vRateLimitResult } from "../../model";
-
-/**
- * Look up a rate limit entry by its string identifier.
- *
- * Queries the `RateLimit` table using the `by_identifier` unique index.
- * Returns the rate limit state with camelCase field names (`attemptsLeft`,
- * `lastAttemptTime`) mapped from the snake_case storage format. Used to
- * check whether an action should be allowed or throttled.
- *
- * @param identifier - Unique string identifying the rate limit bucket
- *   (e.g. `"login:user@example.com"` or `"api:sk_live_abc123"`).
- * @returns The rate limit state object (including `attemptsLeft` and
- *   `lastAttemptTime`), or `null` if no entry exists for the identifier.
- *
- * @example
- * ```ts
- * const limit = await ctx.runQuery(
- *   components.auth.security.limits.rateLimitGet,
- *   { identifier: `login:${email}` },
- * );
- * if (limit !== null && limit.attemptsLeft <= 0) {
- *   throw new Error("Too many login attempts. Please try again later.");
- * }
- * ```
- */
-export const rateLimitGet = query({
-  args: { identifier: v.string() },
-  returns: v.union(vRateLimitResult, v.null()),
-  handler: async (ctx, { identifier }) => {
-    const row = await ctx.db
-      .query("RateLimit")
-      .withIndex("by_identifier", (q) => q.eq("identifier", identifier))
-      .unique();
-    if (row === null) {
-      return null;
-    }
-    return {
-      ...row,
-      attemptsLeft: row.attempts_left,
-      lastAttemptTime: row.last_attempt_time,
-    };
-  },
-});
-
-/**
- * Create a new rate limit entry in the `RateLimit` table.
- *
- * Initializes a rate limit bucket for a given identifier. The entry
- * tracks remaining attempts and the timestamp of the last attempt,
- * storing them in snake_case format internally. Call this when the
- * first rate-limited action occurs for an identifier that does not
- * yet have an entry.
- *
- * @param identifier - Unique string identifying the rate limit bucket
- *   (e.g. `"login:user@example.com"` or `"otp:+15551234567"`).
- * @param attemptsLeft - Number of remaining attempts before the action
- *   is throttled.
- * @param lastAttemptTime - Unix timestamp (in milliseconds) of the
- *   initial attempt.
- * @returns The `_id` of the newly created `RateLimit` document.
- *
- * @example
- * ```ts
- * const rateLimitId = await ctx.runMutation(
- *   components.auth.security.limits.rateLimitCreate,
- *   {
- *     identifier: `login:${email}`,
- *     attemptsLeft: 4, // 5 max minus this attempt
- *     lastAttemptTime: Date.now(),
- *   },
- * );
- * ```
- */
-export const rateLimitCreate = mutation({
-  args: {
-    identifier: v.string(),
-    attemptsLeft: v.number(),
-    lastAttemptTime: v.number(),
-  },
-  returns: v.id("RateLimit"),
-  handler: async (ctx, { identifier, attemptsLeft, lastAttemptTime }) => {
-    return await ctx.db.insert("RateLimit", {
-      identifier,
-      attempts_left: attemptsLeft,
-      last_attempt_time: lastAttemptTime,
-    });
-  },
-});
-
-/**
- * Patch a rate limit entry with partial data.
- *
- * Updates an existing `RateLimit` document with the provided fields.
- * Automatically maps camelCase field names (`attemptsLeft`,
- * `lastAttemptTime`) to the snake_case storage format before writing.
- * Typically called to decrement remaining attempts or to reset the
- * bucket after a cooldown window has elapsed.
- *
- * @param rateLimitId - The `_id` of the `RateLimit` document to update.
- * @param data - An object containing the fields to patch. Supports
- *   camelCase names which are transparently converted:
- *   - `attemptsLeft` -- Updated number of remaining attempts.
- *   - `lastAttemptTime` -- Updated timestamp of the most recent attempt.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * // Decrement attempts after a failed login
- * await ctx.runMutation(
- *   components.auth.security.limits.rateLimitPatch,
- *   {
- *     rateLimitId: limit._id,
- *     data: {
- *       attemptsLeft: limit.attemptsLeft - 1,
- *       lastAttemptTime: Date.now(),
- *     },
- *   },
- * );
- * ```
- */
-export const rateLimitPatch = mutation({
-  args: { rateLimitId: v.id("RateLimit"), data: v.any() },
-  returns: v.null(),
-  handler: async (ctx, { rateLimitId, data }) => {
-    const nextData: Record<string, unknown> = { ...data };
-    if (nextData.attemptsLeft !== undefined) {
-      nextData.attempts_left = nextData.attemptsLeft;
-      delete nextData.attemptsLeft;
-    }
-    if (nextData.lastAttemptTime !== undefined) {
-      nextData.last_attempt_time = nextData.lastAttemptTime;
-      delete nextData.lastAttemptTime;
-    }
-    await ctx.db.patch("RateLimit", rateLimitId, nextData);
-    return null;
-  },
-});
-
-/**
- * Delete a rate limit entry from the `RateLimit` table.
- *
- * Permanently removes the rate limit bucket. This effectively resets
- * rate limiting for the associated identifier, allowing the next
- * action to proceed without throttling. Useful for administrative
- * resets or cleanup of expired buckets.
- *
- * @param rateLimitId - The `_id` of the `RateLimit` document to delete.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * // Admin resets a user's login rate limit
- * await ctx.runMutation(
- *   components.auth.security.limits.rateLimitDelete,
- *   { rateLimitId: limit._id },
- * );
- * ```
- */
-export const rateLimitDelete = mutation({
-  args: { rateLimitId: v.id("RateLimit") },
-  returns: v.null(),
-  handler: async (ctx, { rateLimitId }) => {
-    await ctx.db.delete("RateLimit", rateLimitId);
-    return null;
-  },
-});
-
-// ============================================================================
-// Device Authorization (RFC 8628)
-// ============================================================================

package/src/component/public.ts

@@ -1,27 +0,0 @@
-/**
- * Flat public component namespace for `components.auth.public.*` references.
- *
- * The implementation files under `./public/**` stay grouped by domain for
- * maintainability, while this module preserves the single flat component API
- * surface consumed by the auth runtime and app code.
- */
-export * from "./public/identity/accounts";
-export * from "./public/factors/devices";
-export * from "./public/enterprise/audit";
-export * from "./public/enterprise/core";
-export * from "./public/enterprise/domains";
-export * from "./public/enterprise/scim";
-export * from "./public/enterprise/secrets";
-export * from "./public/enterprise/webhooks";
-export * from "./public/groups/core";
-export * from "./public/groups/invites";
-export * from "./public/groups/members";
-export * from "./public/security/keys";
-export * from "./public/factors/passkeys";
-export * from "./public/security/limits";
-export * from "./public/identity/tokens";
-export * from "./public/identity/sessions";
-export * from "./public/factors/totp";
-export * from "./public/identity/users";
-export * from "./public/identity/codes";
-export * from "./public/identity/verifiers";