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

package/dist/component/public/security/keys.d.ts

@@ -0,0 +1,209 @@
+declare namespace keys_d_exports {
+  export { keyDelete, keyGetByHashedKey, keyGetById, keyInsert, keyList, keyPatch };
+}
+/**
+ * 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,
+ *   },
+ * );
+ * ```
+ */
+declare const keyInsert: any;
+/**
+ * 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");
+ * }
+ * ```
+ */
+declare const keyGetByHashedKey: any;
+/**
+ * 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 },
+ *   );
+ * }
+ * ```
+ */
+declare const keyList: any;
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare const keyGetById: any;
+/**
+ * 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"] }],
+ *     },
+ *   },
+ * );
+ * ```
+ */
+declare const keyPatch: any;
+/**
+ * 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 },
+ * );
+ * ```
+ */
+declare const keyDelete: any;
+//#endregion
+export { keyDelete, keyGetByHashedKey, keyGetById, keyInsert, keyList, keyPatch, keys_d_exports };
+//# sourceMappingURL=keys.d.ts.map

package/dist/component/public/security/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","names":[],"sources":["../../../../src/component/public/security/keys.ts"],"mappings":";;;;;;;;;;;;;;AAqDA;;;;;AAmDA;;;;;AAyDA;;;;;AAwFA;;;;;AAsDA;;;;;AA8CA;;;cAxSa,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;cAmDA,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyDA,OAAA;;;;;;;;;;;;;;;;;;;;;;;cAwFA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAsDA,QAAA;;;;;;;;;;;;;;;;;;;;cA8CA,SAAA"}

package/dist/component/public/security/keys.js

@@ -0,0 +1,319 @@
+import { mutation, query } from "../../functions.js";
+import { vApiKeyDoc, vApiKeyRateLimit, vApiKeyRateLimitState, vApiKeyScope, vPaginated } from "../../model.js";
+import { ConvexError, v } from "convex/values";
+
+//#region src/component/public/security/keys.ts
+/**
+* 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,
+*   },
+* );
+* ```
+*/
+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");
+* }
+* ```
+*/
+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 },
+*   );
+* }
+* ```
+*/
+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 !== void 0) q = ctx.db.query("ApiKey").withIndex("user_id", (idx) => idx.eq("userId", where.userId));
+		else q = ctx.db.query("ApiKey");
+		if (where.revoked !== void 0) q = q.filter((f) => f.eq(f.field("revoked"), where.revoked));
+		if (where.name !== void 0) q = q.filter((f) => f.eq(f.field("name"), where.name));
+		if (where.prefix !== void 0) 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;
+		return {
+			items,
+			nextCursor: hasMore ? items[items.length - 1]._id : null
+		};
+	}
+});
+/**
+* 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);
+* }
+* ```
+*/
+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"] }],
+*     },
+*   },
+* );
+* ```
+*/
+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 }) => {
+		if (await ctx.db.get("ApiKey", keyId) === 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 },
+* );
+* ```
+*/
+const keyDelete = mutation({
+	args: { keyId: v.id("ApiKey") },
+	returns: v.null(),
+	handler: async (ctx, { keyId }) => {
+		if (await ctx.db.get("ApiKey", keyId) === null) throw new ConvexError({
+			code: "KEY_NOT_FOUND",
+			message: "API key not found",
+			keyId
+		});
+		await ctx.db.delete("ApiKey", keyId);
+		return null;
+	}
+});
+
+//#endregion
+export { keyDelete, keyGetByHashedKey, keyGetById, keyInsert, keyList, keyPatch };
+//# sourceMappingURL=keys.js.map

package/dist/component/public/security/keys.js.map

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

package/dist/component/public/security/limits.d.ts

@@ -0,0 +1,114 @@
+declare namespace limits_d_exports {
+  export { rateLimitCreate, rateLimitDelete, rateLimitGet, rateLimitPatch };
+}
+/**
+ * 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.");
+ * }
+ * ```
+ */
+declare const rateLimitGet: any;
+/**
+ * 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(),
+ *   },
+ * );
+ * ```
+ */
+declare const rateLimitCreate: any;
+/**
+ * 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(),
+ *     },
+ *   },
+ * );
+ * ```
+ */
+declare const rateLimitPatch: any;
+/**
+ * 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 },
+ * );
+ * ```
+ */
+declare const rateLimitDelete: any;
+//#endregion
+export { limits_d_exports, rateLimitCreate, rateLimitDelete, rateLimitGet, rateLimitPatch };
+//# sourceMappingURL=limits.d.ts.map

package/dist/component/public/security/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","names":[],"sources":["../../../../src/component/public/security/limits.ts"],"mappings":";;;;;;;;;;;;AA4BA;;;;;AAgDA;;;;;AA+CA;;;;;cA/Fa,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgDA,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+CA,cAAA;;;;;;;;;;;;;;;;;;;;;cAsCA,eAAA"}