@robelest/convex-auth 0.0.4-preview.32 → 0.0.4-preview.34

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

@@ -27,20 +27,6 @@ import { ConvexError, v } from "convex/values";
 * @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: {
@@ -66,35 +52,20 @@ const keyInsert = mutation({
 	}
 });
 /**
-* 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");
-* }
-* ```
+* Read an API key by identity — one function, all-optional args, unioned
+* return: `{ id }` (point lookup) or `{ hashedKey }` (Bearer-verify
+* index).
 */
-const keyGetByHashedKey = query({
-	args: { hashedKey: v.string() },
+const keyGet = query({
+	args: {
+		id: v.optional(v.id("ApiKey")),
+		hashedKey: v.optional(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();
+	handler: async (ctx, args) => {
+		if (args.hashedKey !== void 0) return await ctx.db.query("ApiKey").withIndex("hashed_key", (q) => q.eq("hashedKey", args.hashedKey)).first();
+		if (args.id === void 0) return null;
+		return await ctx.db.get("ApiKey", args.id);
 	}
 });
 /**
@@ -123,25 +94,6 @@ const keyGetByHashedKey = query({
 * @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: {
@@ -184,35 +136,6 @@ const keyList = query({
 	}
 });
 /**
-* 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
@@ -234,29 +157,6 @@ const keyGetById = query({
 *     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: {
@@ -292,13 +192,6 @@ const keyPatch = mutation({
 * @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") },
@@ -315,5 +208,5 @@ const keyDelete = mutation({
 });
 
 //#endregion
-export { keyDelete, keyGetByHashedKey, keyGetById, keyInsert, keyList, keyPatch };
+export { keyDelete, keyGet, keyInsert, keyList, keyPatch };
 //# sourceMappingURL=keys.js.map

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

@@ -16,16 +16,6 @@ import { v } from "convex/values";
 * @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.");
-* }
-* ```
 */
 const rateLimitGet = query({
 	args: { identifier: v.string() },
@@ -57,17 +47,6 @@ const rateLimitGet = query({
 *   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(),
-*   },
-* );
-* ```
 */
 const rateLimitCreate = mutation({
 	args: {
@@ -100,20 +79,6 @@ const rateLimitCreate = mutation({
 *   - `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(),
-*     },
-*   },
-* );
-* ```
 */
 const rateLimitPatch = mutation({
 	args: {
@@ -146,14 +111,6 @@ const rateLimitPatch = mutation({
 * @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 },
-* );
-* ```
 */
 const rateLimitDelete = mutation({
 	args: { rateLimitId: v.id("RateLimit") },

package/dist/component/public/sso/audit.js

@@ -24,24 +24,6 @@ import { ConvexError, v } from "convex/values";
 * @param args.metadata - An optional arbitrary object with additional event details.
 * @returns The ID of the newly created `GroupAuditEvent` document.
 *
-* @example
-* ```ts
-* const eventId = await ctx.runMutation(
-*   components.auth.group.sso.groupAuditEventCreate,
-*   {
-*     connectionId,
-*     groupId: orgGroupId,
-*     eventType: "user.login",
-*     actorType: "user",
-*     actorId: userId,
-*     subjectType: "session",
-*     subjectId: sessionId,
-*     status: "success",
-*     occurredAt: Date.now(),
-*     ip: "203.0.113.42",
-*   },
-* );
-* ```
 */
 const groupAuditEventCreate = mutation({
 	args: {
@@ -77,16 +59,6 @@ const groupAuditEventCreate = mutation({
 * @param args.limit - Maximum number of events to return (clamped between 1 and 100, defaults to 50).
 * @returns An array of audit event documents, most recent first.
 *
-* @example
-* ```ts
-* const events = await ctx.runQuery(
-*   components.auth.group.sso.groupAuditEventList,
-*   { connectionId, limit: 20 },
-* );
-* for (const event of events) {
-*   console.log(event.eventType, event.actorType, event.status);
-* }
-* ```
 */
 const groupAuditEventList = query({
 	args: {

package/dist/component/public/sso/core.js

@@ -18,18 +18,6 @@ import { v } from "convex/values";
 * @param args.extend - An optional arbitrary extension object for custom fields.
 * @returns The ID of the newly created `Group Connection` document.
 *
-* @example
-* ```ts
-* const connectionId = await ctx.runMutation(
-*   components.auth.group.sso.groupConnectionCreate,
-*   {
-*     groupId: orgGroupId,
-*     slug: "acme-corp",
-*     name: "Acme Corporation",
-*     status: "active",
-*   },
-* );
-* ```
 */
 const groupConnectionCreate = mutation({
 	args: {
@@ -50,69 +38,44 @@ const groupConnectionCreate = mutation({
 	}
 });
 /**
-* Retrieve a single group connection record by its document ID.
+* Read a group connection by identity.
 *
-* Returns the full group connection document if it exists, or `null` if no
-* group connection is found with the given ID.
+* Accepts exactly one selector:
+* - `connectionId` — direct document lookup, returning the
+*   `GroupConnection` document or `null`.
+* - `domain` — resolve the connection that owns a linked domain. Looks
+*   up the `GroupConnectionDomain` row, then its parent connection, and
+*   returns `{ connection, domain }` (or `null` if the domain is not
+*   registered or its connection no longer exists).
 *
-* @param args.connectionId - The document ID of the group connection to retrieve.
-* @returns The group connection document, or `null` if not found.
+* @param connectionId - Optional `_id` of the `GroupConnection`.
+* @param domain - Optional domain name to resolve (e.g. `"acme.com"`).
+* @returns For `connectionId`: the connection document or `null`. For
+*   `domain`: `{ connection, domain }` or `null`.
 *
-* @example
-* ```ts
-* const connection = await ctx.runQuery(
-*   components.auth.group.sso.groupConnectionGet,
-*   { connectionId },
-* );
-* if (connection) {
-*   console.log(group.sso.name, group.sso.status);
-* }
-* ```
 */
 const groupConnectionGet = query({
-	args: { connectionId: v.id("GroupConnection") },
-	returns: v.union(vGroupConnectionDoc, v.null()),
-	handler: async (ctx, { connectionId }) => {
-		return await ctx.db.get("GroupConnection", connectionId);
-	}
-});
-/**
-* Retrieve an group connection record by one of its linked domain names.
-*
-* Looks up a `GroupConnectionDomain` row matching the given domain string, then
-* resolves the parent group.sso. Returns both the group connection and the matched
-* domain document, or `null` if the domain is not registered or its group connection
-* no longer exists.
-*
-* @param args.domain - The domain name to search for (e.g. `"acme.com"`).
-* @returns An object containing the `group connection` and `domain` documents, or `null` if not found.
-*
-* @example
-* ```ts
-* const result = await ctx.runQuery(
-*   components.auth.group.sso.groupConnectionGetByDomain,
-*   { domain: "acme.com" },
-* );
-* if (result) {
-*   console.log(result.connection.name, result.domain.verifiedAt);
-* }
-* ```
-*/
-const groupConnectionGetByDomain = query({
-	args: { domain: v.string() },
-	returns: v.union(v.object({
+	args: {
+		connectionId: v.optional(v.id("GroupConnection")),
+		domain: v.optional(v.string())
+	},
+	returns: v.union(vGroupConnectionDoc, v.object({
 		connection: vGroupConnectionDoc,
 		domain: vGroupConnectionDomainDoc
 	}), v.null()),
-	handler: async (ctx, { domain }) => {
-		const domainRow = await ctx.db.query("GroupConnectionDomain").withIndex("domain", (idx) => idx.eq("domain", domain)).first();
-		if (!domainRow) return null;
-		const connection = await ctx.db.get("GroupConnection", domainRow.connectionId);
-		if (!connection) return null;
-		return {
-			connection,
-			domain: domainRow
-		};
+	handler: async (ctx, args) => {
+		if (args.domain !== void 0) {
+			const domainRow = await ctx.db.query("GroupConnectionDomain").withIndex("domain", (idx) => idx.eq("domain", args.domain)).first();
+			if (!domainRow) return null;
+			const connection = await ctx.db.get("GroupConnection", domainRow.connectionId);
+			if (!connection) return null;
+			return {
+				connection,
+				domain: domainRow
+			};
+		}
+		if (args.connectionId === void 0) return null;
+		return await ctx.db.get("GroupConnection", args.connectionId);
 	}
 });
 /**
@@ -130,25 +93,6 @@ const groupConnectionGetByDomain = query({
 * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
 * @returns A paginated result containing `items` (array of group connection documents) and `nextCursor` (`string | null`).
 *
-* @example
-* ```ts
-* const page = await ctx.runQuery(
-*   components.auth.group.sso.groupConnectionList,
-*   {
-*     where: { status: "active" },
-*     limit: 25,
-*     order: "asc",
-*   },
-* );
-* for (const ent of page.items) {
-*   console.log(ent.name);
-* }
-* // Fetch next page:
-* const nextPage = await ctx.runQuery(
-*   components.auth.group.sso.groupConnectionList,
-*   { where: { status: "active" }, cursor: page.nextCursor },
-* );
-* ```
 */
 const groupConnectionList = query({
 	args: {
@@ -200,16 +144,6 @@ const groupConnectionList = query({
 * @param args.data - An object containing the fields to update (e.g. `{ name, status, policy }`).
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(
-*   components.auth.group.sso.groupConnectionUpdate,
-*   {
-*     connectionId,
-*     data: { status: "active", name: "Acme Corp (Renamed)" },
-*   },
-* );
-* ```
 */
 const groupConnectionUpdate = mutation({
 	args: {
@@ -233,13 +167,6 @@ const groupConnectionUpdate = mutation({
 * @param args.connectionId - The document ID of the group connection to delete.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(
-*   components.auth.group.sso.groupConnectionDelete,
-*   { connectionId },
-* );
-* ```
 */
 const groupConnectionDelete = mutation({
 	args: { connectionId: v.id("GroupConnection") },
@@ -259,5 +186,5 @@ const groupConnectionDelete = mutation({
 });
 
 //#endregion
-export { groupConnectionCreate, groupConnectionDelete, groupConnectionGet, groupConnectionGetByDomain, groupConnectionList, groupConnectionUpdate };
+export { groupConnectionCreate, groupConnectionDelete, groupConnectionGet, groupConnectionList, groupConnectionUpdate };
 //# sourceMappingURL=core.js.map

package/dist/component/public/sso/domains.js

@@ -18,18 +18,6 @@ import { ConvexError, v } from "convex/values";
 * @param args.isPrimary - Whether this domain should be set as the primary domain for the connection. Defaults to `true` for the first domain.
 * @returns The ID of the created or updated `GroupConnectionDomain` document.
 *
-* @example
-* ```ts
-* const domainId = await ctx.runMutation(
-*   components.auth.connection.groupConnectionDomainAdd,
-*   {
-*     connectionId,
-*     groupId: orgGroupId,
-*     domain: "acme.com",
-*     isPrimary: true,
-*   },
-* );
-* ```
 */
 const groupConnectionDomainAdd = mutation({
 	args: {
@@ -71,16 +59,6 @@ const groupConnectionDomainAdd = mutation({
 * @param args.connectionId - The ID of the connection whose domains to list.
 * @returns An array of connection domain documents.
 *
-* @example
-* ```ts
-* const domains = await ctx.runQuery(
-*   components.auth.connection.groupConnectionDomainList,
-*   { connectionId },
-* );
-* for (const d of domains) {
-*   console.log(d.domain, d.isPrimary, d.verifiedAt);
-* }
-* ```
 */
 const groupConnectionDomainList = query({
 	args: {
@@ -102,13 +80,6 @@ const groupConnectionDomainList = query({
 * @param args.domainId - The document ID of the connection domain to remove.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(
-*   components.auth.connection.groupConnectionDomainDelete,
-*   { domainId },
-* );
-* ```
 */
 const groupConnectionDomainDelete = mutation({
 	args: { domainId: v.id("GroupConnectionDomain") },
@@ -129,16 +100,6 @@ const groupConnectionDomainDelete = mutation({
 * @param args.domainId - The document ID of the connection domain whose verification to retrieve.
 * @returns The domain verification document, or `null` if none exists.
 *
-* @example
-* ```ts
-* const verification = await ctx.runQuery(
-*   components.auth.connection.groupConnectionDomainVerificationGet,
-*   { domainId },
-* );
-* if (verification) {
-*   console.log(verification.recordName, verification.expiresAt);
-* }
-* ```
 */
 const groupConnectionDomainVerificationGet = query({
 	args: { domainId: v.id("GroupConnectionDomain") },
@@ -166,23 +127,6 @@ const groupConnectionDomainVerificationGet = query({
 * @param args.expiresAt - Epoch timestamp (ms) after which the challenge expires.
 * @returns The ID of the created or updated `GroupConnectionDomainVerification` document.
 *
-* @example
-* ```ts
-* const verificationId = await ctx.runMutation(
-*   components.auth.connection.groupConnectionDomainVerificationUpsert,
-*   {
-*     connectionId,
-*     groupId: orgGroupId,
-*     domainId,
-*     domain: "acme.com",
-*     recordName: "_convex-verify.acme.com",
-*     token: "abc123",
-*     tokenHash: "sha256:...",
-*     requestedAt: Date.now(),
-*     expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
-*   },
-* );
-* ```
 */
 const groupConnectionDomainVerificationUpsert = mutation({
 	args: {
@@ -223,13 +167,6 @@ const groupConnectionDomainVerificationUpsert = mutation({
 * @param args.domainId - The document ID of the connection domain whose verification to delete.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(
-*   components.auth.connection.groupConnectionDomainVerificationDelete,
-*   { domainId },
-* );
-* ```
 */
 const groupConnectionDomainVerificationDelete = mutation({
 	args: { domainId: v.id("GroupConnectionDomain") },
@@ -251,14 +188,6 @@ const groupConnectionDomainVerificationDelete = mutation({
 * @param args.verifiedAt - Epoch timestamp (ms) at which the domain was verified.
 * @returns The updated connection domain document with the `verifiedAt` field set.
 *
-* @example
-* ```ts
-* const verifiedDomain = await ctx.runMutation(
-*   components.auth.connection.groupConnectionDomainVerify,
-*   { domainId, verifiedAt: Date.now() },
-* );
-* console.log("Domain verified:", verifiedDomain.domain);
-* ```
 */
 const groupConnectionDomainVerify = mutation({
 	args: {