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

package/dist/server/runtime.d.ts

@@ -1,6 +1,11 @@
-import { ConvexAuthConfig, Doc, SessionInfo } from "./types.js";
-import * as convex_server0 from "convex/server";
-import * as convex_values0 from "convex/values";
+import { ComponentCtx, ComponentReadCtx } from "./componentContext.js";
+import { AuthProviderConfig, ConvexAuthConfig, CorsConfig, HttpKeyContext, KeyDoc, KeyScope, ScopeChecker, UserOrderBy, UserWhere } from "./types.js";
+import { AuthProfile, SignInParams } from "./payloads.js";
+import { HttpAuthContext, HttpAuthContextConfig, OptionalHttpAuthContext } from "./http.js";
+import { createGroupConnectionDomain } from "./sso/domain.js";
+import * as convex_values1133 from "convex/values";
+import * as convex_server106 from "convex/server";
+import { GenericActionCtx, GenericDataModel, HttpRouter } from "convex/server";
 
 //#region src/server/runtime.d.ts
 /**
@@ -25,28 +30,520 @@ declare function Auth(config_: ConvexAuthConfig): {
   /**
    * Helper for configuring HTTP actions.
    */
-  auth: any;
+  auth: {
+    user: {
+      get: (ctx: ComponentReadCtx, userId: string) => Promise<any>;
+      list: (ctx: ComponentReadCtx, opts?: {
+        where?: UserWhere;
+        limit?: number;
+        cursor?: string | null;
+        orderBy?: UserOrderBy;
+        order?: "asc" | "desc";
+      }) => Promise<any>;
+      viewer: (ctx: ComponentReadCtx & {
+        auth: convex_server106.Auth;
+      }) => Promise<any>;
+      update: (ctx: ComponentCtx, userId: string, data: Record<string, unknown>) => Promise<{
+        userId: string;
+      }>;
+      setActiveGroup: (ctx: ComponentCtx, opts: {
+        userId: string;
+        groupId: string | null;
+      }) => Promise<{
+        userId: string;
+        groupId: null;
+      } | {
+        userId: string;
+        groupId: string;
+      }>;
+      getActiveGroup: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+      }) => Promise<string | null>;
+      delete: (ctx: ComponentCtx, userId: string, opts?: {
+        cascade?: boolean;
+      }) => Promise<{
+        userId: string;
+      }>;
+    };
+    session: {
+      current: (ctx: {
+        auth: convex_server106.Auth;
+      }) => Promise<convex_values1133.GenericId<"Session"> | null>;
+      invalidate: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+        userId: convex_values1133.GenericId<"User">;
+        except?: convex_values1133.GenericId<"Session">[];
+      }) => Promise<{
+        userId: convex_values1133.GenericId<"User">;
+        except: convex_values1133.GenericId<"Session">[];
+      }>;
+      get: (ctx: ComponentReadCtx, sessionId: string) => Promise<any>;
+      list: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+      }) => Promise<any>;
+    };
+    account: {
+      create: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+        provider: string;
+        account: {
+          id: string;
+          secret?: string;
+        };
+        profile: AuthProfile;
+        shouldLinkViaEmail?: boolean;
+        shouldLinkViaPhone?: boolean;
+      }) => Promise<{
+        account: {
+          _id: string;
+          userId: string;
+          secret?: string | null;
+        };
+        user: Record<string, unknown>;
+      }>;
+      get: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+        provider: string;
+        account: {
+          id: string;
+          secret?: string;
+        };
+      }) => Promise<{
+        account: {
+          _id: string;
+          userId: string;
+          secret?: string | null;
+        };
+        user: Record<string, unknown>;
+      } | null>;
+      update: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, args: {
+        provider: string;
+        account: {
+          id: string;
+          secret: string;
+        };
+      }) => Promise<{
+        accountId: string;
+      }>;
+      delete: (ctx: ComponentCtx, accountId: string) => Promise<{
+        accountId: string;
+      }>;
+      listPasskeys: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+      }) => Promise<any>;
+      renamePasskey: (ctx: ComponentCtx, passkeyId: string, name: string) => Promise<{
+        passkeyId: string;
+      }>;
+      deletePasskey: (ctx: ComponentCtx, passkeyId: string) => Promise<{
+        passkeyId: string;
+      }>;
+      listTotps: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+      }) => Promise<any>;
+      deleteTotp: (ctx: ComponentCtx, totpId: string) => Promise<{
+        totpId: string;
+      }>;
+    };
+    provider: {
+      signIn: (<DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, providerConfig: AuthProviderConfig, args: {
+        accountId?: convex_values1133.GenericId<"Account">;
+        params?: SignInParams;
+      }) => Promise<{
+        userId: string;
+        sessionId: string;
+      } | null>) | undefined;
+    };
+    group: {
+      create: (ctx: ComponentCtx, data: {
+        name: string;
+        slug?: string;
+        type?: string;
+        parentGroupId?: string;
+        tags?: Array<{
+          key: string;
+          value: string;
+        }>;
+        extend?: Record<string, unknown>;
+      }) => Promise<{
+        groupId: string;
+      }>;
+      get: (ctx: ComponentReadCtx, groupId: string) => Promise<any>;
+      list: (ctx: ComponentReadCtx, opts?: {
+        where?: {
+          slug?: string;
+          type?: string;
+          parentGroupId?: string;
+          name?: string;
+          isRoot?: boolean;
+          tagsAll?: Array<{
+            key: string;
+            value: string;
+          }>;
+          tagsAny?: Array<{
+            key: string;
+            value: string;
+          }>;
+        };
+        limit?: number;
+        cursor?: string | null;
+        orderBy?: "_creationTime" | "name" | "slug" | "type";
+        order?: "asc" | "desc";
+      }) => Promise<any>;
+      update: (ctx: ComponentCtx, groupId: string, data: Record<string, unknown>) => Promise<{
+        groupId: string;
+      }>;
+      delete: (ctx: ComponentCtx, groupId: string) => Promise<{
+        groupId: string;
+      }>;
+      ancestors: (ctx: ComponentReadCtx, opts: {
+        groupId: string;
+        maxDepth?: number;
+        includeSelf?: boolean;
+      }) => Promise<{
+        ancestors: Record<string, unknown>[];
+        cycleDetected: boolean;
+        maxDepthReached: boolean;
+      }>;
+    };
+    member: {
+      create: (ctx: ComponentCtx, data: {
+        groupId: string;
+        userId: string;
+        roleIds?: string[];
+        status?: string;
+        extend?: Record<string, unknown>;
+      }) => Promise<{
+        memberId: string;
+      }>;
+      get: (ctx: ComponentReadCtx, memberId: string) => Promise<any>;
+      list: (ctx: ComponentReadCtx, opts?: {
+        where?: {
+          groupId?: string;
+          userId?: string;
+          roleId?: string;
+          status?: string;
+        };
+        limit?: number;
+        cursor?: string | null;
+        orderBy?: "_creationTime" | "status";
+        order?: "asc" | "desc";
+      }) => Promise<any>;
+      delete: (ctx: ComponentCtx, memberId: string) => Promise<{
+        memberId: string;
+      }>;
+      update: (ctx: ComponentCtx, memberId: string, data: Record<string, unknown>) => Promise<{
+        memberId: string;
+      }>;
+      inspect: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+        groupId: string;
+        ancestry?: boolean;
+        maxDepth?: number;
+      }) => Promise<{
+        membership: null;
+        roleIds: string[];
+        grants: string[];
+      } | {
+        membership: {
+          _id: string;
+          _creationTime: number;
+          groupId: string;
+          userId: string;
+          role?: string;
+          roleIds?: string[];
+          status?: string;
+          extend?: Record<string, unknown>;
+        };
+        roleIds: string[];
+        grants: string[];
+      }>;
+      require: (ctx: ComponentReadCtx, opts: {
+        userId: string;
+        groupId: string;
+        ancestry?: boolean;
+        roleIds?: string[];
+        grants?: string[];
+        maxDepth?: number;
+      }) => Promise<{
+        membership: {
+          _id: string;
+          _creationTime: number;
+          groupId: string;
+          userId: string;
+          role?: string;
+          roleIds?: string[];
+          status?: string;
+          extend?: Record<string, unknown>;
+        };
+        roleIds: string[];
+        grants: string[];
+      }>;
+    };
+    invite: {
+      create: (ctx: ComponentCtx, data: {
+        groupId?: string;
+        invitedByUserId?: string;
+        email?: string;
+        roleIds?: string[];
+        expiresTime?: number;
+        extend?: Record<string, unknown>;
+      }) => Promise<{
+        inviteId: string;
+        token: string;
+      }>;
+      get: (ctx: ComponentReadCtx, inviteId: string) => Promise<any>;
+      token: {
+        get: (ctx: ComponentReadCtx, token: string) => Promise<any>;
+        accept: (ctx: ComponentCtx, args: {
+          token: string;
+          acceptedByUserId: string;
+        }) => Promise<any>;
+      };
+      list: (ctx: ComponentReadCtx, opts?: {
+        where?: {
+          tokenHash?: string;
+          groupId?: string;
+          status?: "pending" | "accepted" | "revoked" | "expired";
+          email?: string;
+          invitedByUserId?: string;
+          roleId?: string;
+          acceptedByUserId?: string;
+        };
+        limit?: number;
+        cursor?: string | null;
+        orderBy?: "_creationTime" | "status" | "email" | "expiresTime" | "acceptedTime";
+        order?: "asc" | "desc";
+      }) => Promise<any>;
+      accept: (ctx: ComponentCtx, inviteId: string, acceptedByUserId?: string) => Promise<{
+        inviteId: string;
+        acceptedByUserId: string | null;
+      }>;
+      revoke: (ctx: ComponentCtx, inviteId: string) => Promise<{
+        inviteId: string;
+      }>;
+    };
+    key: {
+      create: (ctx: ComponentCtx, opts: {
+        userId: string;
+        name: string;
+        scopes: KeyScope[];
+        rateLimit?: {
+          maxRequests: number;
+          windowMs: number;
+        };
+        expiresAt?: number;
+        metadata?: Record<string, unknown>;
+      }) => Promise<{
+        keyId: string;
+        secret: string;
+      }>;
+      verify: (ctx: ComponentCtx, rawKey: string) => Promise<{
+        userId: string;
+        keyId: string;
+        scopes: ScopeChecker;
+      }>;
+      list: (ctx: ComponentReadCtx, opts?: {
+        where?: {
+          userId?: string;
+          revoked?: boolean;
+          name?: string;
+          prefix?: string;
+        };
+        limit?: number;
+        cursor?: string | null;
+        orderBy?: "_creationTime" | "name" | "lastUsedAt" | "expiresAt" | "revoked";
+        order?: "asc" | "desc";
+      }) => Promise<any>;
+      get: (ctx: ComponentReadCtx, keyId: string) => Promise<KeyDoc | null>;
+      update: (ctx: ComponentCtx, keyId: string, data: {
+        name?: string;
+        scopes?: KeyScope[];
+        rateLimit?: {
+          maxRequests: number;
+          windowMs: number;
+        };
+      }) => Promise<{
+        keyId: string;
+      }>;
+      revoke: (ctx: ComponentCtx, keyId: string) => Promise<{
+        keyId: string;
+      }>;
+      delete: (ctx: ComponentCtx, keyId: string) => Promise<{
+        keyId: string;
+      }>;
+      rotate: (ctx: ComponentCtx, keyId: string, opts?: {
+        name?: string;
+        expiresAt?: number;
+      }) => Promise<{
+        keyId: string;
+        secret: string;
+      }>;
+    };
+  } & {
+    sso: ReturnType<typeof createGroupConnectionDomain>;
+  } & {
+    http: {
+      /**
+       * Register core HTTP routes for JWT verification and OAuth sign-in.
+       *
+       * ```ts
+       * import { httpRouter } from "convex/server";
+       * import { auth } from "./auth";
+       *
+       * const http = httpRouter();
+       *
+       * auth.http.add(http);
+       *
+       * export default http;
+       * ```
+       *
+       * The following routes are handled always:
+       *
+       * - `/.well-known/openid-configuration`
+       * - `/.well-known/jwks.json`
+       *
+       * The following routes are handled if OAuth is configured:
+       *
+       * - `/api/auth/signin/*`
+       * - `/api/auth/callback/*`
+       *
+       * @param http your HTTP router
+       */
+      add: (http: HttpRouter) => void;
+      /**
+       * Resolve mixed HTTP auth for a raw `httpAction`.
+       *
+       * Checks session auth first, then falls back to `Authorization: Bearer sk_*`
+       * API keys. This is the low-level helper for endpoints that intentionally
+       * accept either browser sessions or API keys.
+       * Pass `{ optional: true }` to get a null-shaped auth object instead of a
+       * `NOT_SIGNED_IN` error.
+       *
+       * ```ts
+       * http.route({
+       *   path: "/api/data",
+       *   method: "GET",
+       *   handler: httpAction(async (ctx, request) => {
+       *     const authContext = await auth.http.context(ctx, request);
+       *     return Response.json({
+       *       userId: authContext.userId,
+       *       source: authContext.source,
+       *     });
+       *   }),
+       * });
+       * ```
+       */
+      context: {
+        <TResolve extends Record<string, unknown> = Record<string, never>, TCtx extends {
+          auth: {
+            getUserIdentity: () => Promise<convex_server106.UserIdentity | null>;
+          };
+        } & ComponentReadCtx = {
+          auth: {
+            getUserIdentity: () => Promise<convex_server106.UserIdentity | null>;
+          };
+        } & ComponentReadCtx>(ctx: TCtx, request: Request, config: HttpAuthContextConfig<TResolve, TCtx> & {
+          optional: true;
+        }): Promise<OptionalHttpAuthContext & TResolve>;
+        <TResolve extends Record<string, unknown> = Record<string, never>, TCtx extends {
+          auth: {
+            getUserIdentity: () => Promise<convex_server106.UserIdentity | null>;
+          };
+        } & ComponentReadCtx = {
+          auth: {
+            getUserIdentity: () => Promise<convex_server106.UserIdentity | null>;
+          };
+        } & ComponentReadCtx>(ctx: TCtx, request: Request, config?: HttpAuthContextConfig<TResolve, TCtx>): Promise<HttpAuthContext & TResolve>;
+      };
+      /**
+       * Wrap an HTTP action handler with Bearer token authentication.
+       *
+       * Extracts the `Authorization: Bearer <key>` header, verifies the
+       * API key via `auth.key.verify()`, and injects `ctx.key` with the
+       * verified key info. Returns structured JSON error responses for
+       * missing/invalid/revoked/expired/rate-limited keys.
+       *
+       * If the handler returns a plain object, it is auto-wrapped in a
+       * `200 JSON` response. If it returns a `Response`, CORS headers
+       * are merged and the response is passed through.
+       *
+       * ```ts
+       * const handler = auth.http.action(async (ctx, request) => {
+       *   const data = await ctx.runQuery(api.data.get, { userId: ctx.key.userId });
+       *   return { data };
+       * });
+       * http.route({ path: "/api/data", method: "GET", handler });
+       * ```
+       *
+       * @param handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
+       * @param options.scope - Optional scope check; returns 403 if the key lacks permission.
+       * @param options.cors - CORS config; defaults to site URLs from environment.
+       */
+      action: (handler: (ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>, options?: {
+        scope?: {
+          resource: string;
+          action: string;
+        };
+        cors?: CorsConfig;
+      }) => convex_server106.PublicHttpAction;
+      /**
+       * Register a Bearer-authenticated route **and** its OPTIONS preflight
+       * in a single call.
+       *
+       * ```ts
+       * auth.http.route(http, {
+       *   path: "/api/messages",
+       *   method: "POST",
+       *   handler: async (ctx, request) => {
+       *     const { body } = await request.json();
+       *     await ctx.runMutation(internal.messages.sendAsUser, {
+       *       userId: ctx.key.userId,
+       *       body,
+       *     });
+       *     return { success: true };
+       *   },
+       * });
+       * ```
+       *
+       * @param http - The Convex HTTP router.
+       * @param routeConfig.path - The URL path to match.
+       * @param routeConfig.method - HTTP method (GET, POST, PUT, PATCH, DELETE).
+       * @param routeConfig.handler - Receives enriched `ctx` (with `ctx.key`) and the raw `Request`.
+       * @param routeConfig.scope - Optional scope check; returns 403 if the key lacks permission.
+       * @param routeConfig.cors - CORS config; defaults to site URLs from environment.
+       */
+      route: (http: {
+        route: (config: unknown) => void;
+      }, routeConfig: {
+        path: string;
+        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        handler: (ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>;
+        scope?: {
+          resource: string;
+          action: string;
+        };
+        cors?: CorsConfig;
+      }) => void;
+    };
+  };
   /**
    * Action called by the client to sign the user in.
    *
    * Also used for refreshing the session.
    */
-  signIn: convex_server0.RegisteredAction<"public", {
+  signIn: convex_server106.RegisteredAction<"public", {
     provider?: string | undefined;
-    params?: any;
     verifier?: string | undefined;
+    params?: Record<string, string | number | boolean | (string | number | boolean | null)[] | Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | null> | undefined;
     refreshToken?: string | undefined;
     calledBy?: string | undefined;
   }, Promise<SignInActionResult>>;
   /**
    * Action called by the client to invalidate the current session.
    */
-  signOut: convex_server0.RegisteredAction<"public", {}, Promise<void>>;
+  signOut: convex_server106.RegisteredAction<"public", {}, Promise<void>>;
   /**
    * Internal mutation used by the library to read and write
    * to the database during signin and signout.
    */
-  store: convex_server0.RegisteredMutation<"internal", {
+  store: convex_server106.RegisteredMutation<"internal", {
     args: {
       sessionId?: string | undefined;
       type: "signIn";
@@ -61,37 +558,54 @@ declare function Auth(config_: ConvexAuthConfig): {
       provider?: string | undefined;
       verifier?: string | undefined;
       type: "verifyCodeAndSignIn";
-      params: any;
+      params: Record<string, string | number | boolean | (string | number | boolean | null)[] | Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | null>;
       generateTokens: boolean;
       allowExtraProviders: boolean;
     } | {
+      signature?: string | undefined;
       type: "verifier";
     } | {
       type: "verifierSignature";
       verifier: string;
       signature: string;
     } | {
-      accountExtend?: any;
+      accountExtend?: {
+        identity?: {
+          type?: string | undefined;
+          provider?: string | undefined;
+          providerAccountId?: string | undefined;
+          protocol?: string | undefined;
+          connectionId?: string | undefined;
+          subject?: string | undefined;
+          issuer?: string | undefined;
+          discoveryUrl?: string | undefined;
+          entityId?: string | undefined;
+        } | undefined;
+        saml?: {
+          attributes?: Record<string, string | string[]> | undefined;
+          sessionIndex?: string | undefined;
+        } | undefined;
+      } | undefined;
+      profile: Record<string, string | number | boolean | (string | number | boolean | null)[] | Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | null>;
       type: "userOAuth";
       provider: string;
-      signature: string;
       providerAccountId: string;
-      profile: any;
+      signature: string;
     } | {
-      phone?: string | undefined;
       email?: string | undefined;
+      phone?: string | undefined;
       accountId?: string | undefined;
       type: "createVerificationCode";
+      expirationTime: number;
       provider: string;
-      allowExtraProviders: boolean;
       code: string;
-      expirationTime: number;
+      allowExtraProviders: boolean;
     } | {
       shouldLinkViaEmail?: boolean | undefined;
       shouldLinkViaPhone?: boolean | undefined;
+      profile: Record<string, string | number | boolean | (string | number | boolean | null)[] | Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | null>;
       type: "createAccountFromCredentials";
       provider: string;
-      profile: any;
       account: {
         secret?: string | undefined;
         id: string;
@@ -115,21 +629,7 @@ declare function Auth(config_: ConvexAuthConfig): {
       type: "invalidateSessions";
       userId: string;
     };
-  }, Promise<string | void | SessionInfo | {
-    userId: convex_values0.GenericId<"User">;
-    sessionId: convex_values0.GenericId<"Session">;
-  } | (string & {
-    __tableName: "AuthVerifier";
-  }) | {
-    token: string;
-    refreshToken: string;
-  } | {
-    account: Doc<"Account">;
-    user: Doc<"User">;
-  } | {
-    account: Doc<"Account">;
-    user: Doc<"User">;
-  } | null>>;
+  }, Promise<unknown>>;
 };
 //#endregion
 export { Auth };