@robelest/convex-auth 0.0.4-preview.22 → 0.0.4-preview.24

package/src/server/enterprise/http.ts

@@ -1,11 +1,10 @@
+import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import type { GenericActionCtx, HttpRouter } from "convex/server";
+import { ConvexError } from "convex/values";
 import { serialize as serializeCookie } from "cookie";
 
 import { redirectToParamCookie, useRedirectToParam } from "../cookies";
-import { isAuthError } from "../errors";
-import { Fx } from "@robelest/fx";
-
-import { AuthError } from "../authError";
 import { addSSORoutes, convertErrorsToResponse, getCookies } from "../http";
 import type { SSORuntimeRoute } from "../http";
 import { createOAuthAuthorizationURL, handleOAuthCallback } from "../oauth";
@@ -207,12 +206,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
           runtimeRoute.protocol !== "saml" ||
             runtimeRoute.rest.length !== 1 ||
             runtimeRoute.rest[0] !== "acs",
-          Fx.fail(
-            new AuthError(
-              "INVALID_PARAMETERS",
-              "Invalid enterprise runtime path.",
-            ).toConvexError(),
-          ),
+          Cv.fail({
+            code: "INVALID_PARAMETERS",
+            message: "Invalid enterprise runtime path.",
+          }),
         );
 
         const enterpriseId = runtimeRoute.enterpriseId;
@@ -230,10 +227,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
               config: loaded.config,
             }),
           err: (e) =>
-            new AuthError(
-              "OAUTH_PROVIDER_ERROR",
-              `SAML response parse failed: ${e instanceof Error ? e.message : String(e)}`,
-            ).toConvexError(),
+            Cv.error({
+              code: "OAUTH_PROVIDER_ERROR",
+              message: `SAML response parse failed: ${e instanceof Error ? e.message : String(e)}`,
+            }),
         });
 
         yield* Fx.from({
@@ -247,10 +244,11 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
             return Promise.resolve();
           },
           err: () =>
-            new AuthError(
-              "OAUTH_INVALID_STATE",
-              "SAML RelayState did not match the pending login request.",
-            ).toConvexError(),
+            Cv.error({
+              code: "OAUTH_INVALID_STATE",
+              message:
+                "SAML RelayState did not match the pending login request.",
+            }),
         });
 
         const { samlAttributes, samlSessionIndex, ...userProfile } =
@@ -331,10 +329,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
       runtimeRoute.rest.length !== 1 ||
       runtimeRoute.rest[0] !== "slo"
     ) {
-      throw new AuthError(
-        "INVALID_PARAMETERS",
-        "Invalid enterprise runtime path.",
-      ).toConvexError();
+      throw Cv.error({
+        code: "INVALID_PARAMETERS",
+        message: "Invalid enterprise runtime path.",
+      });
     }
     const { loaded, enterprise } = await loadActiveEnterpriseSamlOrThrow(
       ctx,
@@ -371,10 +369,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
     if (parsedMessage.hasSamlResponse) {
       return new Response(null, { status: 204 });
     }
-    throw new AuthError(
-      "INVALID_PARAMETERS",
-      "Missing SAML logout payload.",
-    ).toConvexError();
+    throw Cv.error({
+      code: "INVALID_PARAMETERS",
+      message: "Missing SAML logout payload.",
+    });
   };
 
   const handleScimRequest = async (
@@ -645,7 +643,7 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
           userId,
           data: patchData,
         });
-        const resolution = await auth.member.resolve(state.ctx, {
+        const resolution = await auth.member.inspect(state.ctx, {
           groupId: state.enterprise.groupId,
           userId,
         });
@@ -711,7 +709,7 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
         );
         if (missing) return missing;
         const userId = state.parsedPath.resourceId!;
-        const resolution = await auth.member.resolve(state.ctx, {
+        const resolution = await auth.member.inspect(state.ctx, {
           groupId: state.enterprise.groupId,
           userId,
         });
@@ -961,15 +959,12 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
             );
             const userId = match?.[1];
             if (userId) {
-              const resolution = await auth.member.resolve(
-                state.ctx,
-                { groupId, userId },
-              );
+              const resolution = await auth.member.inspect(state.ctx, {
+                groupId,
+                userId,
+              });
               if (resolution.membership) {
-                await auth.member.delete(
-                  state.ctx,
-                  resolution.membership._id,
-                );
+                await auth.member.delete(state.ctx, resolution.membership._id);
               }
             }
           }
@@ -1105,7 +1100,13 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
       ) {
         return scimError(400, "invalidFilter", error.message);
       }
-      if (isAuthError(error)) {
+      if (
+        error instanceof ConvexError &&
+        typeof error.data === "object" &&
+        error.data !== null &&
+        "code" in error.data &&
+        "message" in error.data
+      ) {
         const code = error.data.code as string;
         const status =
           code === "MISSING_BEARER_TOKEN" || code === "INVALID_API_KEY"
@@ -1141,7 +1142,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
       const url = new URL(request.url);
       const verifier = url.searchParams.get("code");
       if (!verifier) {
-        throw new AuthError("OAUTH_MISSING_VERIFIER").toConvexError();
+        throw Cv.error({
+          code: "OAUTH_MISSING_VERIFIER",
+          message: "Missing sign-in verifier.",
+        });
       }
       const { loaded, enterprise } = await loadActiveEnterpriseSamlOrThrow(
         ctx,
@@ -1204,7 +1208,10 @@ export function addEnterpriseHttpRuntime(deps: EnterpriseHttpRuntimeDeps) {
       const url = new URL(request.url);
       const verifier = url.searchParams.get("code");
       if (!verifier) {
-        throw new AuthError("OAUTH_MISSING_VERIFIER").toConvexError();
+        throw Cv.error({
+          code: "OAUTH_MISSING_VERIFIER",
+          message: "Missing sign-in verifier.",
+        });
       }
       const { enterprise, oidc } = await loadEnterpriseOidcOrThrow(
         ctx,

package/src/server/http.ts

@@ -1,3 +1,5 @@
+import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import {
   GenericActionCtx,
   GenericDataModel,
@@ -7,13 +9,262 @@ import {
 import { ConvexError } from "convex/values";
 import { parse as parseCookies } from "cookie";
 
-import { isAuthError } from "./errors";
-import { Fx } from "@robelest/fx";
-
-import { AuthError } from "./authError";
+import type {
+  AuthContext,
+  OptionalAuthContext,
+  UserDoc,
+} from "./auth";
+import {
+  createUnauthenticatedAuthContext,
+  getAuthContextForUser,
+  getSessionUserId,
+} from "./context";
 import type { CorsConfig, HttpKeyContext } from "./types";
 import { logError } from "./utils";
 
+type HttpContextAuthLike = {
+  user: {
+    get: (ctx: any, userId: string) => Promise<UserDoc>;
+    getActiveGroup: (
+      ctx: any,
+      args: { userId: string },
+    ) => Promise<string | null>;
+  };
+  member: {
+    inspect: (
+      ctx: any,
+      args: { userId: string; groupId: string },
+    ) => Promise<{
+      membership: unknown;
+      roleIds: string[];
+      grants: string[];
+    }>;
+  };
+  key: {
+    verify: (ctx: GenericActionCtx<any>, rawKey: string) => Promise<{
+      userId: string;
+      keyId: string;
+      scopes: HttpKeyContext["key"]["scopes"];
+    }>;
+  };
+};
+
+/**
+ * Auth context returned by `auth.http.context(ctx, request)`.
+ *
+ * This resolves raw HTTP authentication in two steps:
+ * 1. session auth from `ctx.auth.getUserIdentity()`
+ * 2. API key auth from `Authorization: Bearer sk_*`
+ *
+ * The `source` field tells you which authentication path succeeded.
+ * When `source === "key"`, the verified API key metadata is available on
+ * `key`.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.http.context(ctx, request);
+ * if (authContext.source === "key") {
+ *   console.log(authContext.key.keyId);
+ * }
+ * ```
+ */
+export type HttpAuthContext =
+  | (AuthContext & {
+      /** The request authenticated through a browser or session token. */
+      source: "session";
+      /** No API key was used for this request. */
+      key: null;
+    })
+  | (AuthContext & {
+      /** The request authenticated through an API key. */
+      source: "key";
+      /** Verified API key metadata for the request. */
+      key: HttpKeyContext["key"];
+    });
+
+/**
+ * Nullable HTTP auth context returned by
+ * `auth.http.context(ctx, request, { optional: true })`.
+ *
+ * This preserves a stable auth-shaped object for raw `httpAction` handlers
+ * that allow anonymous callers.
+ */
+export type OptionalHttpAuthContext =
+  | (OptionalAuthContext & {
+      /** No authentication source was resolved. */
+      source: null;
+      /** No API key metadata is available. */
+      key: null;
+    })
+  | HttpAuthContext;
+
+/**
+ * Configuration for {@link createAuth().http.context}.
+ *
+ * This mirrors {@link AuthContextConfig} for raw HTTP handlers and adds support
+ * for enriching mixed session/API-key auth results.
+ *
+ * @typeParam TResolve - Extra fields returned from `resolve()` and merged into
+ *   the resolved HTTP auth context.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.http.context(ctx, request, {
+ *   resolve: async (_ctx, user, authState) => ({
+ *     email: user.email,
+ *     isMachineRequest: authState.source === "key",
+ *   }),
+ * });
+ * ```
+ */
+export type HttpAuthContextConfig<
+  TResolve extends Record<string, unknown> = Record<string, never>,
+> = {
+  /**
+   * Allow unauthenticated callers and return a null-shaped auth object instead
+   * of throwing `NOT_SIGNED_IN`.
+   */
+  optional?: boolean;
+  /**
+   * Attach additional derived fields to the resolved HTTP auth context.
+   *
+   * This callback runs only when authentication succeeds.
+   */
+  resolve?: (
+    ctx: GenericActionCtx<any>,
+    user: UserDoc,
+    auth: HttpAuthContext,
+  ) => Promise<TResolve> | TResolve;
+  /**
+   * Override or wrap HTTP auth resolution.
+   *
+   * Return `undefined` to use the built-in session-or-key resolver, `null` for
+   * an explicit unauthenticated state, or a fully resolved
+   * {@link HttpAuthContext}.
+   */
+  authResolve?: (
+    ctx: GenericActionCtx<any>,
+    fallback: () => Promise<HttpAuthContext | null>,
+  ) =>
+    | Promise<HttpAuthContext | null | undefined>
+    | HttpAuthContext
+    | null
+    | undefined;
+};
+
+function createNotSignedInError() {
+  return Cv.error({
+    code: "NOT_SIGNED_IN",
+    message: "Authentication required.",
+  });
+}
+
+async function getHttpKeyContext(
+  auth: HttpContextAuthLike,
+  ctx: GenericActionCtx<any>,
+  request: Request,
+): Promise<HttpAuthContext | null> {
+  const authHeader = request.headers.get("Authorization");
+  if (!authHeader?.startsWith("Bearer sk_")) {
+    return null;
+  }
+
+  try {
+    const verified = await auth.key.verify(ctx, authHeader.slice(7));
+    const authContext = await getAuthContextForUser(auth, ctx, verified.userId);
+    return {
+      ...authContext,
+      source: "key",
+      key: {
+        userId: verified.userId,
+        keyId: verified.keyId,
+        scopes: verified.scopes,
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function resolveHttpAuthContext(
+  auth: HttpContextAuthLike,
+  ctx: GenericActionCtx<any>,
+  request: Request,
+): Promise<HttpAuthContext | null> {
+  const sessionUserId = await getSessionUserId(ctx);
+  if (sessionUserId !== null) {
+    const authContext = await getAuthContextForUser(auth, ctx, sessionUserId);
+    return {
+      ...authContext,
+      source: "session",
+      key: null,
+    };
+  }
+
+  return await getHttpKeyContext(auth, ctx, request);
+}
+
+/**
+ * @internal
+ * Create the implementation behind `auth.http.context(...)`.
+ */
+export function createHttpContext(auth: HttpContextAuthLike): {
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    ctx: GenericActionCtx<any>,
+    request: Request,
+    config: HttpAuthContextConfig<TResolve> & { optional: true },
+  ): Promise<OptionalHttpAuthContext & TResolve>;
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    ctx: GenericActionCtx<any>,
+    request: Request,
+    config?: HttpAuthContextConfig<TResolve>,
+  ): Promise<HttpAuthContext & TResolve>;
+} {
+  return (async (
+    ctx: GenericActionCtx<any>,
+    request: Request,
+    config?: HttpAuthContextConfig<any>,
+  ) => {
+    const fallback = () => resolveHttpAuthContext(auth, ctx, request);
+    const authOverride = config?.authResolve
+      ? await config.authResolve(ctx, fallback)
+      : undefined;
+    const resolved =
+      authOverride === undefined ? await fallback() : authOverride;
+
+    if (resolved === null) {
+      if (config?.optional !== true) {
+        throw createNotSignedInError();
+      }
+      return {
+        ...createUnauthenticatedAuthContext(),
+        source: null,
+        key: null,
+      };
+    }
+
+    const extra = config?.resolve
+      ? await config.resolve(ctx, resolved.user, resolved)
+      : {};
+
+    return {
+      ...resolved,
+      ...extra,
+    };
+  }) as {
+    <TResolve extends Record<string, unknown> = Record<string, never>>(
+      ctx: GenericActionCtx<any>,
+      request: Request,
+      config: HttpAuthContextConfig<TResolve> & { optional: true },
+    ): Promise<OptionalHttpAuthContext & TResolve>;
+    <TResolve extends Record<string, unknown> = Record<string, never>>(
+      ctx: GenericActionCtx<any>,
+      request: Request,
+      config?: HttpAuthContextConfig<TResolve>,
+    ): Promise<HttpAuthContext & TResolve>;
+  };
+}
+
 export function createHttpAction(auth: {
   key: { verify: (ctx: GenericActionCtx<any>, rawKey: string) => Promise<any> };
 }) {
@@ -59,19 +310,21 @@ export function createHttpAction(auth: {
             const rawKey = authHeader.slice(7);
 
             const keyResult = await Fx.run(
-              Fx.from({
-                ok: () => auth.key.verify(genericCtx, rawKey),
-                err: (error) => error,
-              }).pipe(
-                Fx.fold({
-                  ok: (result) => ({ ok: true, value: result }) as const,
-                  err: (error) => ({ ok: false, error }) as const,
-                }),
+              Fx.attempt(
+                () => auth.key.verify(genericCtx, rawKey),
+                (result) => ({ ok: true, value: result }) as const,
+                (error) => ({ ok: false, error }) as const,
               ),
             );
 
             if (!keyResult.ok) {
-              if (isAuthError(keyResult.error)) {
+              if (
+                keyResult.error instanceof ConvexError &&
+                typeof keyResult.error.data === "object" &&
+                keyResult.error.data !== null &&
+                "code" in keyResult.error.data &&
+                "message" in keyResult.error.data
+              ) {
                 const { code, message } = keyResult.error.data as {
                   code: string;
                   message: string;
@@ -219,7 +472,13 @@ export function convertErrorsToResponse(
         err: (error) => error,
       }).pipe(
         Fx.recover((error) => {
-          if (isAuthError(error)) {
+          if (
+            error instanceof ConvexError &&
+            typeof error.data === "object" &&
+            error.data !== null &&
+            "code" in error.data &&
+            "message" in error.data
+          ) {
             return Fx.succeed(
               new Response(
                 JSON.stringify({
@@ -426,10 +685,10 @@ export function addSSORoutes(
           deps.routeBase,
         );
         if (!route) {
-          throw new AuthError(
-            "INVALID_PARAMETERS",
-            "Invalid enterprise runtime path.",
-          ).toConvexError();
+          throw Cv.error({
+            code: "INVALID_PARAMETERS",
+            message: "Invalid enterprise runtime path.",
+          });
         }
         if (route.protocol === "saml" && route.rest.length === 1) {
           if (route.rest[0] === "metadata") {
@@ -456,10 +715,10 @@ export function addSSORoutes(
         if (route.protocol === "scim" && route.rest[0] === "v2") {
           return await deps.handleScimRequest(ctx, request);
         }
-        throw new AuthError(
-          "INVALID_PARAMETERS",
-          "Invalid enterprise runtime path.",
-        ).toConvexError();
+        throw Cv.error({
+          code: "INVALID_PARAMETERS",
+          message: "Invalid enterprise runtime path.",
+        });
       }),
     ),
   });
@@ -484,10 +743,10 @@ export function addSSORoutes(
         if (route?.protocol === "scim" && route.rest[0] === "v2") {
           return await deps.handleScimRequest(ctx, request);
         }
-        throw new AuthError(
-          "INVALID_PARAMETERS",
-          "Invalid enterprise runtime path.",
-        ).toConvexError();
+        throw Cv.error({
+          code: "INVALID_PARAMETERS",
+          message: "Invalid enterprise runtime path.",
+        });
       }),
     ),
   });
@@ -504,10 +763,10 @@ export function addSSORoutes(
         if (route?.protocol === "scim" && route.rest[0] === "v2") {
           return await deps.handleScimRequest(ctx, request);
         }
-        throw new AuthError(
-          "INVALID_PARAMETERS",
-          "Invalid enterprise runtime path.",
-        ).toConvexError();
+        throw Cv.error({
+          code: "INVALID_PARAMETERS",
+          message: "Invalid enterprise runtime path.",
+        });
       }),
     ),
   });

package/src/server/identity.ts

@@ -1,4 +1,4 @@
-import { AuthError } from "./authError";
+import { Cv } from "@robelest/fx/convex";
 
 /** @internal */
 export function userIdFromIdentitySubject(subject: string): string {
@@ -9,10 +9,10 @@ export function userIdFromIdentitySubject(subject: string): string {
     rest.length === 0 ||
     rest.some((segment) => segment.length === 0)
   ) {
-    throw new AuthError(
-      "INTERNAL_ERROR",
-      "Authenticated identity subject is malformed.",
-    );
+    throw Cv.error({
+      code: "INTERNAL_ERROR",
+      message: "Authenticated identity subject is malformed.",
+    });
   }
   return userId;
 }

package/src/server/index.ts

@@ -1,15 +1,21 @@
-export { AuthCtx, createAuth } from "./auth";
+export { createAuth } from "./auth";
 export type {
   AuthApi,
   AuthApiBase,
+  AuthContext,
+  AuthContextConfig,
   AuthConfig,
-  AuthCtxConfig,
-  AuthResolvedContext,
   ConvexAuthResult,
   InferAuth,
   InferClientApi,
+  OptionalAuthContext,
   UserDoc,
 } from "./auth";
+export type {
+  HttpAuthContext,
+  HttpAuthContextConfig,
+  OptionalHttpAuthContext,
+} from "./http";
 export type {
   EnterpriseAdminAuthorizationInput,
   EnterpriseAdminPermission,