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

package/src/server/enterprise/shared.ts

@@ -0,0 +1,134 @@
+/** @internal */
+export type ParsedSamlMetadata = {
+  issuer: string;
+  sso: {
+    redirect?: string;
+    post?: string;
+  };
+  slo: {
+    redirect?: string;
+    post?: string;
+  };
+  signingCert: string | string[] | null;
+  encryptionCert: string | string[] | null;
+  nameIdFormats: string[];
+  wantsSignedAuthnRequests: boolean;
+};
+
+/** @internal */
+export type EnterpriseSamlSource = { kind: "enterprise"; id: string };
+
+/** @internal */
+export type EnterpriseSamlRelayState = {
+  source: EnterpriseSamlSource;
+  signature: string;
+  requestId: string;
+  state: string;
+  redirectTo?: string;
+};
+
+/** @internal */
+export type EnterpriseSamlUrls = {
+  metadataUrl: string;
+  acsUrl: string;
+  sloUrl?: string;
+};
+
+/** @internal */
+export type EnterpriseSamlLoadedSource = {
+  source: EnterpriseSamlSource;
+  config: unknown;
+  status?: string;
+};
+
+/** @internal */
+export type EnterpriseSamlHttpRequest = {
+  url: URL;
+  body: Record<string, string>;
+  query: Record<string, string>;
+  binding: "redirect" | "post";
+  relayState?: string;
+  hasSamlRequest: boolean;
+  hasSamlResponse: boolean;
+};
+
+/** @internal */
+export type ScimListRequest = {
+  startIndex: number;
+  count: number;
+  filter?: { attribute: string; value: string };
+};
+
+/** @internal */
+export const SCIM_USER_SCHEMA_ID = "urn:ietf:params:scim:schemas:core:2.0:User";
+/** @internal */
+export const SCIM_GROUP_SCHEMA_ID =
+  "urn:ietf:params:scim:schemas:core:2.0:Group";
+
+/** @internal */
+export const ENTERPRISE_OIDC_PROVIDER_PREFIX = "enterprise:oidc:";
+/** @internal */
+export const ENTERPRISE_SAML_PROVIDER_PREFIX = "enterprise:saml:";
+
+/** @internal */
+export function normalizeDomain(domain: string): string {
+  return domain.trim().toLowerCase().replace(/^@+/, "");
+}
+
+/** @internal */
+export function enterpriseOidcProviderId(enterpriseId: string): string {
+  return `${ENTERPRISE_OIDC_PROVIDER_PREFIX}${enterpriseId}`;
+}
+
+/** @internal */
+export function enterpriseSamlProviderId(enterpriseId: string): string {
+  return `${ENTERPRISE_SAML_PROVIDER_PREFIX}${enterpriseId}`;
+}
+
+/** @internal */
+export function getEnterpriseSamlUrls(opts: {
+  rootUrl: string;
+  source: EnterpriseSamlSource;
+}): EnterpriseSamlUrls {
+  const root = opts.rootUrl.replace(/\/$/, "");
+  const metadataBase = `${root}/api/auth/sso/${opts.source.id}/saml/metadata`;
+  const acsBase = `${root}/api/auth/sso/${opts.source.id}/saml/acs`;
+  const sloBase = `${root}/api/auth/sso/${opts.source.id}/saml/slo`;
+  return {
+    metadataUrl: metadataBase,
+    acsUrl: acsBase,
+    sloUrl: sloBase,
+  };
+}
+
+/** @internal */
+export function getEnterpriseOidcUrls(opts: {
+  rootUrl: string;
+  enterpriseId: string;
+}) {
+  const root = opts.rootUrl.replace(/\/$/, "");
+  return {
+    signInUrl: `${root}/api/auth/sso/${opts.enterpriseId}/oidc/signin`,
+    callbackUrl: `${root}/api/auth/sso/${opts.enterpriseId}/oidc/callback`,
+  };
+}
+
+/** @internal */
+export function isEnterpriseSamlSourceActive(
+  source: EnterpriseSamlLoadedSource,
+) {
+  return source.status === "active";
+}
+
+/** @internal */
+export function isEnterpriseProviderId(providerId: string): boolean {
+  return (
+    providerId.startsWith(ENTERPRISE_OIDC_PROVIDER_PREFIX) ||
+    providerId.startsWith(ENTERPRISE_SAML_PROVIDER_PREFIX)
+  );
+}
+
+export const asRecord = (value: unknown) =>
+  typeof value === "object" && value !== null
+    ? (value as Record<string, any>)
+    : null;

package/src/server/enterprise/validators.ts

@@ -0,0 +1,93 @@
+import { v } from "convex/values";
+
+/** @internal Shared validator for mounted enterprise connection status fields. */
+export const enterpriseStatusValidator = v.union(
+  v.literal("draft"),
+  v.literal("active"),
+  v.literal("disabled"),
+);
+
+/** @internal Structured validator for mounted enterprise policy patch payloads. */
+export const enterprisePolicyPatchValidator = v.object({
+  identity: v.optional(
+    v.object({
+      accountLinking: v.optional(
+        v.object({
+          oidc: v.optional(
+            v.union(v.literal("verifiedEmail"), v.literal("none")),
+          ),
+          saml: v.optional(
+            v.union(v.literal("verifiedEmail"), v.literal("none")),
+          ),
+        }),
+      ),
+    }),
+  ),
+  provisioning: v.optional(
+    v.object({
+      scimReuse: v.optional(
+        v.object({
+          user: v.optional(v.union(v.literal("externalId"), v.literal("none"))),
+        }),
+      ),
+      jit: v.optional(
+        v.object({
+          mode: v.optional(
+            v.union(
+              v.literal("off"),
+              v.literal("createUser"),
+              v.literal("createUserAndMembership"),
+            ),
+          ),
+          defaultRoleIds: v.optional(v.array(v.string())),
+        }),
+      ),
+      deprovision: v.optional(
+        v.object({
+          mode: v.optional(v.union(v.literal("soft"), v.literal("hard"))),
+        }),
+      ),
+    }),
+  ),
+});
+
+/** @internal Filter validator for mounted enterprise connection list queries. */
+export const enterpriseConnectionWhereValidator = v.object({
+  groupId: v.optional(v.string()),
+  slug: v.optional(v.string()),
+  status: v.optional(enterpriseStatusValidator),
+});
+
+/** @internal Domain replacement input validator for mounted enterprise APIs. */
+export const enterpriseDomainInputValidator = v.object({
+  domain: v.string(),
+  isPrimary: v.optional(v.boolean()),
+});
+
+/** @internal Input validator for enterprise domain verification actions. */
+export const enterpriseDomainVerificationInputValidator = v.object({
+  enterpriseId: v.string(),
+  domain: v.string(),
+});
+
+/** @internal SAML attribute mapping validator for mounted SSO admin APIs. */
+export const enterpriseSamlAttributeMappingValidator = v.object({
+  subject: v.optional(v.string()),
+  email: v.optional(v.string()),
+  name: v.optional(v.string()),
+  firstName: v.optional(v.string()),
+  lastName: v.optional(v.string()),
+});
+
+/** @internal SAML service-provider override validator for mounted admin APIs. */
+export const enterpriseSamlSpValidator = v.object({
+  entityId: v.optional(v.string()),
+  acsUrl: v.optional(v.string()),
+  sloUrl: v.optional(v.string()),
+  signingCert: v.optional(v.union(v.string(), v.array(v.string()))),
+  encryptCert: v.optional(v.union(v.string(), v.array(v.string()))),
+  privateKey: v.optional(v.string()),
+  privateKeyPass: v.optional(v.string()),
+  encPrivateKey: v.optional(v.string()),
+  encPrivateKeyPass: v.optional(v.string()),
+});

package/src/server/errors.ts

@@ -5,6 +5,13 @@
  * `{ code, message }` payload so clients can distinguish error types
  * and display user-friendly messages.
  *
+ * **Consumer API:** Use {@link throwAuthError} to throw structured errors
+ * from your own Convex functions (e.g. custom authorization checks).
+ *
+ * **Internal pattern:** The library itself uses `new AuthError(code)` with
+ * the `@robelest/fx` effect system (`Fx.fail(new AuthError(code))`).
+ * You do not need to use `AuthError` directly — it is an implementation detail.
+ *
  * @module
  */
 
@@ -28,164 +35,132 @@ import { ConvexError } from "convex/values";
  */
 export const AUTH_ERRORS = {
   // ---- Configuration ----
-  PROVIDER_NOT_CONFIGURED:
-    "This sign-in method is not available.",
+  PROVIDER_NOT_CONFIGURED: "This sign-in method is not available.",
   EMAIL_CONFIG_REQUIRED:
-    "Email transport is not configured. Configure email in your Auth constructor.",
-  MISSING_ENV_VAR:
-    "A required server environment variable is missing.",
-  MISSING_ACTION_CONTEXT:
-    "Action context is required for this operation.",
+    "Email transport is not configured. Configure email in createAuth(...).",
+  MISSING_ENV_VAR: "A required server environment variable is missing.",
+  MISSING_ACTION_CONTEXT: "Action context is required for this operation.",
+  INVALID_PARAMETERS: "The provided parameters are invalid.",
 
   // ---- Authentication ----
-  NOT_SIGNED_IN:
-    "You must be signed in to perform this action.",
-  INVALID_VERIFICATION_CODE:
-    "Invalid or expired verification code.",
-  INVALID_REFRESH_TOKEN:
-    "Your session has expired. Please sign in again.",
+  NOT_SIGNED_IN: "You must be signed in to perform this action.",
+  INVALID_VERIFICATION_CODE: "Invalid or expired verification code.",
+  INVALID_REFRESH_TOKEN: "Your session has expired. Please sign in again.",
+  AUTH_HANDSHAKE_TIMEOUT:
+    "Sign-in succeeded but authentication confirmation timed out.",
+  AUTH_HANDSHAKE_REJECTED:
+    "Authentication was rejected while confirming the session.",
   SIGN_IN_MISSING_PARAMS:
     "Cannot sign in: missing provider, code, or refresh token.",
-  UNSUPPORTED_PROVIDER_TYPE:
-    "This provider type is not supported.",
-  INVALID_REDIRECT:
-    "Invalid redirect URL.",
+  UNSUPPORTED_PROVIDER_TYPE: "This provider type is not supported.",
+  INVALID_REDIRECT: "Invalid redirect URL.",
 
   // ---- Email / Phone ----
-  EMAIL_SEND_FAILED:
-    "Failed to send verification email. Please try again.",
+  EMAIL_SEND_FAILED: "Failed to send verification email. Please try again.",
 
   // ---- API Keys ----
-  INVALID_API_KEY:
-    "Invalid API key.",
-  API_KEY_REVOKED:
-    "This API key has been revoked.",
-  API_KEY_EXPIRED:
-    "This API key has expired.",
-  API_KEY_RATE_LIMITED:
-    "API key rate limit exceeded. Please try again later.",
-  API_KEY_INVALID_SCOPE:
-    "Invalid scope requested for API key.",
+  INVALID_API_KEY: "Invalid API key.",
+  API_KEY_REVOKED: "This API key has been revoked.",
+  API_KEY_EXPIRED: "This API key has expired.",
+  API_KEY_RATE_LIMITED: "API key rate limit exceeded. Please try again later.",
+  API_KEY_INVALID_SCOPE: "Invalid scope requested for API key.",
+  KEY_NOT_FOUND: "API key not found.",
 
   // ---- HTTP Bearer Auth ----
-  MISSING_BEARER_TOKEN:
-    "Missing or malformed Authorization: Bearer header.",
-  SCOPE_CHECK_FAILED:
-    "This API key does not have the required permissions.",
+  MISSING_BEARER_TOKEN: "Missing or malformed Authorization: Bearer header.",
+  SCOPE_CHECK_FAILED: "This API key does not have the required permissions.",
 
   // ---- OAuth ----
-  OAUTH_MISSING_PROVIDER:
-    "Missing OAuth provider ID.",
-  OAUTH_MISSING_VERIFIER:
-    "Missing sign-in verifier.",
-  OAUTH_INVALID_STATE:
-    "Invalid OAuth state. Please try signing in again.",
-  OAUTH_PROVIDER_ERROR:
-    "The sign-in provider returned an error.",
+  OAUTH_MISSING_PROVIDER: "Missing OAuth provider ID.",
+  OAUTH_MISSING_VERIFIER: "Missing sign-in verifier.",
+  OAUTH_INVALID_STATE: "Invalid OAuth state. Please try signing in again.",
+  OAUTH_PROVIDER_ERROR: "The sign-in provider returned an error.",
   OAUTH_MISSING_ID_TOKEN:
     "ID token claims are missing from the provider response.",
-  OAUTH_INVALID_PROFILE:
-    "The sign-in provider returned an invalid profile.",
+  OAUTH_INVALID_PROFILE: "The sign-in provider returned an invalid profile.",
   OAUTH_UNSUPPORTED_AUTH_METHOD:
     "Unsupported OAuth client authentication method.",
-  OAUTH_NO_USERINFO:
-    "No userinfo endpoint configured for this provider.",
+  OAUTH_NO_USERINFO: "No userinfo endpoint configured for this provider.",
 
   // ---- Credentials ----
-  ACCOUNT_ALREADY_EXISTS:
-    "An account with these credentials already exists.",
-  ACCOUNT_NOT_FOUND:
-    "Account not found.",
+  ACCOUNT_ALREADY_EXISTS: "An account with these credentials already exists.",
+  ACCOUNT_NOT_FOUND: "Account not found.",
   INVALID_CREDENTIALS_PROVIDER:
     "This provider does not support credential operations.",
   MISSING_CRYPTO_FUNCTION:
     "This provider is missing a required cryptographic function.",
-  USER_UPDATE_FAILED:
-    "Could not update the user record.",
+  USER_UPDATE_FAILED: "Could not update the user record.",
 
   // ---- Verifier ----
-  INVALID_VERIFIER:
-    "Invalid or expired verifier.",
+  INVALID_VERIFIER: "Invalid or expired verifier.",
 
   // ---- Passkey ----
   PASSKEY_MISSING_CONFIG:
     "Passkey provider requires SITE_URL or explicit rpId configuration.",
-  PASSKEY_AUTH_REQUIRED:
-    "Sign in first, then add a passkey to your account.",
-  PASSKEY_MISSING_VERIFIER:
-    "Missing verifier for passkey operation.",
-  PASSKEY_INVALID_CLIENT_DATA:
-    "Invalid passkey client data.",
-  PASSKEY_INVALID_ORIGIN:
-    "Passkey origin does not match the expected value.",
-  PASSKEY_INVALID_CHALLENGE:
-    "Invalid or expired passkey challenge.",
-  PASSKEY_RP_MISMATCH:
-    "Relying party ID mismatch.",
-  PASSKEY_USER_PRESENCE:
-    "User presence flag not set.",
-  PASSKEY_USER_VERIFICATION:
-    "User verification required but not performed.",
-  PASSKEY_NO_CREDENTIAL:
-    "No credential in attestation.",
-  PASSKEY_UNSUPPORTED_ALGORITHM:
-    "Unsupported passkey algorithm.",
-  PASSKEY_INVALID_SIGNATURE:
-    "Invalid passkey signature.",
-  PASSKEY_UNKNOWN_CREDENTIAL:
-    "Unknown passkey credential.",
+  PASSKEY_AUTH_REQUIRED: "Sign in first, then add a passkey to your account.",
+  PASSKEY_MISSING_VERIFIER: "Missing verifier for passkey operation.",
+  PASSKEY_INVALID_CLIENT_DATA: "Invalid passkey client data.",
+  PASSKEY_INVALID_ORIGIN: "Passkey origin does not match the expected value.",
+  PASSKEY_INVALID_CHALLENGE: "Invalid or expired passkey challenge.",
+  PASSKEY_RP_MISMATCH: "Relying party ID mismatch.",
+  PASSKEY_USER_PRESENCE: "User presence flag not set.",
+  PASSKEY_USER_VERIFICATION: "User verification required but not performed.",
+  PASSKEY_NO_CREDENTIAL: "No credential in attestation.",
+  PASSKEY_UNSUPPORTED_ALGORITHM: "Unsupported passkey algorithm.",
+  PASSKEY_INVALID_SIGNATURE: "Invalid passkey signature.",
+  PASSKEY_UNKNOWN_CREDENTIAL: "Unknown passkey credential.",
   PASSKEY_COUNTER_ERROR:
     "Authenticator counter did not increase — possible credential cloning detected.",
-  PASSKEY_MISSING_FLOW:
-    "Missing passkey flow parameter.",
-  PASSKEY_UNKNOWN_FLOW:
-    "Unknown passkey flow.",
+  PASSKEY_MISSING_FLOW: "Missing passkey flow parameter.",
+  PASSKEY_UNKNOWN_FLOW: "Unknown passkey flow.",
 
   // ---- TOTP ----
-  TOTP_AUTH_REQUIRED:
-    "Sign in first, then set up two-factor authentication.",
-  TOTP_MISSING_VERIFIER:
-    "Missing verifier for TOTP operation.",
-  TOTP_MISSING_CODE:
-    "Missing TOTP code.",
-  TOTP_MISSING_ID:
-    "Missing TOTP enrollment ID.",
-  TOTP_NOT_FOUND:
-    "TOTP enrollment not found.",
-  TOTP_ALREADY_VERIFIED:
-    "TOTP enrollment is already verified.",
-  TOTP_INVALID_CODE:
-    "Invalid TOTP code.",
-  TOTP_INVALID_VERIFIER:
-    "Invalid or expired TOTP verifier.",
-  TOTP_NO_ENROLLMENT:
-    "No verified TOTP enrollment found.",
-  TOTP_MISSING_FLOW:
-    "Missing TOTP flow parameter.",
-  TOTP_UNKNOWN_FLOW:
-    "Unknown TOTP flow.",
+  TOTP_AUTH_REQUIRED: "Sign in first, then set up two-factor authentication.",
+  TOTP_MISSING_VERIFIER: "Missing verifier for TOTP operation.",
+  TOTP_MISSING_CODE: "Missing TOTP code.",
+  TOTP_MISSING_ID: "Missing TOTP enrollment ID.",
+  TOTP_NOT_FOUND: "TOTP enrollment not found.",
+  TOTP_ALREADY_VERIFIED: "TOTP enrollment is already verified.",
+  TOTP_INVALID_CODE: "Invalid TOTP code.",
+  TOTP_INVALID_VERIFIER: "Invalid or expired TOTP verifier.",
+  TOTP_NO_ENROLLMENT: "No verified TOTP enrollment found.",
+  TOTP_MISSING_FLOW: "Missing TOTP flow parameter.",
+  TOTP_UNKNOWN_FLOW: "Unknown TOTP flow.",
 
   // ---- Device Authorization (RFC 8628) ----
   DEVICE_CODE_EXPIRED:
     "The device code has expired. Please start a new authorization request.",
-  DEVICE_CODE_DENIED:
-    "The authorization request was denied.",
-  DEVICE_AUTHORIZATION_PENDING:
-    "The user has not yet authorized this device.",
+  DEVICE_CODE_DENIED: "The authorization request was denied.",
+  DEVICE_AUTHORIZATION_PENDING: "The user has not yet authorized this device.",
   DEVICE_SLOW_DOWN:
     "Polling too frequently. Increase the interval between requests.",
-  DEVICE_INVALID_USER_CODE:
-    "Invalid or expired user code.",
-  DEVICE_ALREADY_AUTHORIZED:
-    "This device code has already been authorized.",
-  DEVICE_MISSING_FLOW:
-    "Missing device flow parameter.",
-  DEVICE_UNKNOWN_FLOW:
-    "Unknown device flow.",
+  DEVICE_INVALID_USER_CODE: "Invalid or expired user code.",
+  DEVICE_ALREADY_AUTHORIZED: "This device code has already been authorized.",
+  DEVICE_MISSING_FLOW: "Missing device flow parameter.",
+  DEVICE_UNKNOWN_FLOW: "Unknown device flow.",
+
+  // ---- Invites ----
+  INVITE_EXPIRED: "This invitation has expired.",
+  INVITE_EMAIL_MISMATCH: "This invitation is for a different email.",
+  INVITE_ALREADY_ACCEPTED: "This invitation has already been accepted.",
+  DUPLICATE_INVITE:
+    "A pending invite already exists for this email in this group.",
+  INVITE_NOT_FOUND: "Invite not found.",
+  INVITE_NOT_PENDING: "Cannot accept or revoke invite that is not pending.",
+
+  // ---- Groups / Members ----
+  FORBIDDEN: "Access denied.",
+  NO_ACTIVE_GROUP: "User has no active group set.",
+  DUPLICATE_MEMBERSHIP: "User is already a member of this group.",
+
+  // ---- Enterprise ----
+  ENTERPRISE_ALREADY_EXISTS:
+    "An enterprise record already exists for this group.",
+  ENTERPRISE_DOMAIN_TAKEN:
+    "That domain is already attached to another enterprise.",
 
   // ---- Internal (should never reach user) ----
-  INTERNAL_ERROR:
-    "An unexpected error occurred.",
+  INTERNAL_ERROR: "An unexpected error occurred.",
 } as const satisfies Record<string, string>;
 
 /** Union of all recognized auth error code strings (keys of {@link AUTH_ERRORS}). */
@@ -198,9 +173,26 @@ export type AuthErrorCode = keyof typeof AUTH_ERRORS;
 /**
  * Throw a structured `ConvexError` with `{ code, message }`.
  *
+ * Use this in your own Convex functions (queries, mutations, actions)
+ * to throw auth-domain errors that clients can match on by `code`.
+ * The library itself uses `AuthError` internally, but consumers
+ * should prefer this helper for simplicity.
+ *
  * @param code    Machine-readable error code from `AUTH_ERRORS`.
  * @param message Optional override for the default human-readable message.
  * @param context Optional extra fields merged into the error payload.
+ *
+ * @example
+ * ```ts
+ * import { throwAuthError } from "@robelest/convex-auth/server";
+ *
+ * // In a custom mutation:
+ * if (!isAdmin) {
+ *   throwAuthError("FORBIDDEN");
+ * }
+ * ```
+ *
+ * @throws {ConvexError} Always — throws a `ConvexError` with `{ code, message }` payload.
  */
 export function throwAuthError(
   code: AuthErrorCode,
@@ -264,11 +256,30 @@ export function isAuthError(
  */
 export function parseAuthError(
   error: unknown,
-): { code: AuthErrorCode; message: string } | { code: null; message: string } | null {
+):
+  | { code: AuthErrorCode; message: string }
+  | { code: null; message: string }
+  | null {
   if (isAuthError(error)) {
-    const { code, message } = error.data as { code: AuthErrorCode; message: string };
+    const { code, message } = error.data as {
+      code: AuthErrorCode;
+      message: string;
+    };
     return { code, message };
   }
+  // Recognize the Fx-native AuthError class (has _tag + code)
+  if (
+    error instanceof Error &&
+    "_tag" in error &&
+    (error as any)._tag === "AuthError" &&
+    "code" in error &&
+    typeof (error as any).code === "string"
+  ) {
+    return {
+      code: (error as any).code as AuthErrorCode,
+      message: error.message,
+    };
+  }
   if (error instanceof ConvexError && typeof error.data === "string") {
     return { code: null, message: error.data };
   }