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

package/dist/component/server/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../../../src/server/errors.ts"],"sourcesContent":["/**\n * Structured error handling for Convex Auth.\n *\n * Every error thrown by the auth system uses `ConvexError` with a\n * `{ code, message }` payload so clients can distinguish error types\n * and display user-friendly messages.\n *\n * @module\n */\n\nimport { ConvexError } from \"convex/values\";\n\n// ============================================================================\n// Error code → default message map  (single source of truth)\n// ============================================================================\n\n/**\n * Map of every auth error code to its default human-readable message.\n *\n * Use the keys as the `code` argument to {@link throwAuthError}.\n * Clients can match on these codes for conditional error handling.\n *\n * @example\n * ```ts\n * throwAuthError(\"NOT_SIGNED_IN\");\n * // ConvexError { data: { code: \"NOT_SIGNED_IN\", message: \"You must be signed in...\" } }\n * ```\n */\nexport const AUTH_ERRORS = {\n  // ---- Configuration ----\n  PROVIDER_NOT_CONFIGURED:\n    \"This sign-in method is not available.\",\n  EMAIL_CONFIG_REQUIRED:\n    \"Email transport is not configured. Configure email in your Auth constructor.\",\n  MISSING_ENV_VAR:\n    \"A required server environment variable is missing.\",\n  MISSING_ACTION_CONTEXT:\n    \"Action context is required for this operation.\",\n\n  // ---- Authentication ----\n  NOT_SIGNED_IN:\n    \"You must be signed in to perform this action.\",\n  INVALID_VERIFICATION_CODE:\n    \"Invalid or expired verification code.\",\n  INVALID_REFRESH_TOKEN:\n    \"Your session has expired. Please sign in again.\",\n  SIGN_IN_MISSING_PARAMS:\n    \"Cannot sign in: missing provider, code, or refresh token.\",\n  UNSUPPORTED_PROVIDER_TYPE:\n    \"This provider type is not supported.\",\n  INVALID_REDIRECT:\n    \"Invalid redirect URL.\",\n\n  // ---- Email / Phone ----\n  EMAIL_SEND_FAILED:\n    \"Failed to send verification email. Please try again.\",\n\n  // ---- API Keys ----\n  INVALID_API_KEY:\n    \"Invalid API key.\",\n  API_KEY_REVOKED:\n    \"This API key has been revoked.\",\n  API_KEY_EXPIRED:\n    \"This API key has expired.\",\n  API_KEY_RATE_LIMITED:\n    \"API key rate limit exceeded. Please try again later.\",\n  API_KEY_INVALID_SCOPE:\n    \"Invalid scope requested for API key.\",\n\n  // ---- HTTP Bearer Auth ----\n  MISSING_BEARER_TOKEN:\n    \"Missing or malformed Authorization: Bearer header.\",\n  SCOPE_CHECK_FAILED:\n    \"This API key does not have the required permissions.\",\n\n  // ---- OAuth ----\n  OAUTH_MISSING_PROVIDER:\n    \"Missing OAuth provider ID.\",\n  OAUTH_MISSING_VERIFIER:\n    \"Missing sign-in verifier.\",\n  OAUTH_INVALID_STATE:\n    \"Invalid OAuth state. Please try signing in again.\",\n  OAUTH_PROVIDER_ERROR:\n    \"The sign-in provider returned an error.\",\n  OAUTH_MISSING_ID_TOKEN:\n    \"ID token claims are missing from the provider response.\",\n  OAUTH_INVALID_PROFILE:\n    \"The sign-in provider returned an invalid profile.\",\n  OAUTH_UNSUPPORTED_AUTH_METHOD:\n    \"Unsupported OAuth client authentication method.\",\n  OAUTH_NO_USERINFO:\n    \"No userinfo endpoint configured for this provider.\",\n\n  // ---- Credentials ----\n  ACCOUNT_ALREADY_EXISTS:\n    \"An account with these credentials already exists.\",\n  ACCOUNT_NOT_FOUND:\n    \"Account not found.\",\n  INVALID_CREDENTIALS_PROVIDER:\n    \"This provider does not support credential operations.\",\n  MISSING_CRYPTO_FUNCTION:\n    \"This provider is missing a required cryptographic function.\",\n  USER_UPDATE_FAILED:\n    \"Could not update the user record.\",\n\n  // ---- Verifier ----\n  INVALID_VERIFIER:\n    \"Invalid or expired verifier.\",\n\n  // ---- Passkey ----\n  PASSKEY_MISSING_CONFIG:\n    \"Passkey provider requires SITE_URL or explicit rpId configuration.\",\n  PASSKEY_AUTH_REQUIRED:\n    \"Sign in first, then add a passkey to your account.\",\n  PASSKEY_MISSING_VERIFIER:\n    \"Missing verifier for passkey operation.\",\n  PASSKEY_INVALID_CLIENT_DATA:\n    \"Invalid passkey client data.\",\n  PASSKEY_INVALID_ORIGIN:\n    \"Passkey origin does not match the expected value.\",\n  PASSKEY_INVALID_CHALLENGE:\n    \"Invalid or expired passkey challenge.\",\n  PASSKEY_RP_MISMATCH:\n    \"Relying party ID mismatch.\",\n  PASSKEY_USER_PRESENCE:\n    \"User presence flag not set.\",\n  PASSKEY_USER_VERIFICATION:\n    \"User verification required but not performed.\",\n  PASSKEY_NO_CREDENTIAL:\n    \"No credential in attestation.\",\n  PASSKEY_UNSUPPORTED_ALGORITHM:\n    \"Unsupported passkey algorithm.\",\n  PASSKEY_INVALID_SIGNATURE:\n    \"Invalid passkey signature.\",\n  PASSKEY_UNKNOWN_CREDENTIAL:\n    \"Unknown passkey credential.\",\n  PASSKEY_COUNTER_ERROR:\n    \"Authenticator counter did not increase — possible credential cloning detected.\",\n  PASSKEY_MISSING_FLOW:\n    \"Missing passkey flow parameter.\",\n  PASSKEY_UNKNOWN_FLOW:\n    \"Unknown passkey flow.\",\n\n  // ---- TOTP ----\n  TOTP_AUTH_REQUIRED:\n    \"Sign in first, then set up two-factor authentication.\",\n  TOTP_MISSING_VERIFIER:\n    \"Missing verifier for TOTP operation.\",\n  TOTP_MISSING_CODE:\n    \"Missing TOTP code.\",\n  TOTP_MISSING_ID:\n    \"Missing TOTP enrollment ID.\",\n  TOTP_NOT_FOUND:\n    \"TOTP enrollment not found.\",\n  TOTP_ALREADY_VERIFIED:\n    \"TOTP enrollment is already verified.\",\n  TOTP_INVALID_CODE:\n    \"Invalid TOTP code.\",\n  TOTP_INVALID_VERIFIER:\n    \"Invalid or expired TOTP verifier.\",\n  TOTP_NO_ENROLLMENT:\n    \"No verified TOTP enrollment found.\",\n  TOTP_MISSING_FLOW:\n    \"Missing TOTP flow parameter.\",\n  TOTP_UNKNOWN_FLOW:\n    \"Unknown TOTP flow.\",\n\n  // ---- Device Authorization (RFC 8628) ----\n  DEVICE_CODE_EXPIRED:\n    \"The device code has expired. Please start a new authorization request.\",\n  DEVICE_CODE_DENIED:\n    \"The authorization request was denied.\",\n  DEVICE_AUTHORIZATION_PENDING:\n    \"The user has not yet authorized this device.\",\n  DEVICE_SLOW_DOWN:\n    \"Polling too frequently. Increase the interval between requests.\",\n  DEVICE_INVALID_USER_CODE:\n    \"Invalid or expired user code.\",\n  DEVICE_ALREADY_AUTHORIZED:\n    \"This device code has already been authorized.\",\n  DEVICE_MISSING_FLOW:\n    \"Missing device flow parameter.\",\n  DEVICE_UNKNOWN_FLOW:\n    \"Unknown device flow.\",\n\n  // ---- Internal (should never reach user) ----\n  INTERNAL_ERROR:\n    \"An unexpected error occurred.\",\n} as const satisfies Record<string, string>;\n\n/** Union of all recognized auth error code strings (keys of {@link AUTH_ERRORS}). */\nexport type AuthErrorCode = keyof typeof AUTH_ERRORS;\n\n// ============================================================================\n// Error helpers\n// ============================================================================\n\n/**\n * Throw a structured `ConvexError` with `{ code, message }`.\n *\n * @param code    Machine-readable error code from `AUTH_ERRORS`.\n * @param message Optional override for the default human-readable message.\n * @param context Optional extra fields merged into the error payload.\n */\nexport function throwAuthError(\n  code: AuthErrorCode,\n  message?: string,\n  context?: Record<string, unknown>,\n): never {\n  throw new ConvexError({\n    code,\n    message: message ?? AUTH_ERRORS[code],\n    ...context,\n  });\n}\n\n/**\n * Type guard: check whether a caught value is a structured auth `ConvexError`.\n *\n * @param error - The caught value (typically from a `catch` block).\n * @returns `true` when `error` is a `ConvexError` with `{ code, message }` data.\n *\n * @example\n * ```ts\n * try { await auth.signIn('email', { email }); }\n * catch (e) {\n *   if (isAuthError(e)) console.log(e.data.code); // \"EMAIL_SEND_FAILED\"\n * }\n * ```\n */\nexport function isAuthError(\n  error: unknown,\n): error is ConvexError<{ code: AuthErrorCode; message: string }> {\n  return (\n    error instanceof ConvexError &&\n    typeof error.data === \"object\" &&\n    error.data !== null &&\n    \"code\" in error.data &&\n    \"message\" in error.data\n  );\n}\n\n/**\n * Extract `{ code, message }` from a caught error.\n *\n * Works for `ConvexError` (from Convex actions), plain `Error`\n * instances, and structured auth errors. Returns `null` when the\n * value is not an error object.\n *\n * @param error - The caught value to parse.\n * @returns `{ code, message }` when extractable, or `null`.\n *   When `code` is `null`, the error is not a structured auth error\n *   but `message` still contains the error text.\n *\n * @example\n * ```ts\n * try {\n *   await auth.signIn(\"email\", { email });\n * } catch (e) {\n *   const err = parseAuthError(e);\n *   if (err?.code === \"EMAIL_SEND_FAILED\") { ... }\n * }\n * ```\n */\nexport function parseAuthError(\n  error: unknown,\n): { code: AuthErrorCode; message: string } | { code: null; message: string } | null {\n  if (isAuthError(error)) {\n    const { code, message } = error.data as { code: AuthErrorCode; message: string };\n    return { code, message };\n  }\n  if (error instanceof ConvexError && typeof error.data === \"string\") {\n    return { code: null, message: error.data };\n  }\n  if (error instanceof Error) {\n    return { code: null, message: error.message };\n  }\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,cAAc;CAEzB,yBACE;CACF,uBACE;CACF,iBACE;CACF,wBACE;CAGF,eACE;CACF,2BACE;CACF,uBACE;CACF,wBACE;CACF,2BACE;CACF,kBACE;CAGF,mBACE;CAGF,iBACE;CACF,iBACE;CACF,iBACE;CACF,sBACE;CACF,uBACE;CAGF,sBACE;CACF,oBACE;CAGF,wBACE;CACF,wBACE;CACF,qBACE;CACF,sBACE;CACF,wBACE;CACF,uBACE;CACF,+BACE;CACF,mBACE;CAGF,wBACE;CACF,mBACE;CACF,8BACE;CACF,yBACE;CACF,oBACE;CAGF,kBACE;CAGF,wBACE;CACF,uBACE;CACF,0BACE;CACF,6BACE;CACF,wBACE;CACF,2BACE;CACF,qBACE;CACF,uBACE;CACF,2BACE;CACF,uBACE;CACF,+BACE;CACF,2BACE;CACF,4BACE;CACF,uBACE;CACF,sBACE;CACF,sBACE;CAGF,oBACE;CACF,uBACE;CACF,mBACE;CACF,iBACE;CACF,gBACE;CACF,uBACE;CACF,mBACE;CACF,uBACE;CACF,oBACE;CACF,mBACE;CACF,mBACE;CAGF,qBACE;CACF,oBACE;CACF,8BACE;CACF,kBACE;CACF,0BACE;CACF,2BACE;CACF,qBACE;CACF,qBACE;CAGF,gBACE;CACH;;;;;;;;AAgBD,SAAgB,eACd,MACA,SACA,SACO;AACP,OAAM,IAAI,YAAY;EACpB;EACA,SAAS,WAAW,YAAY;EAChC,GAAG;EACJ,CAAC;;;;;;;;;;;;;;;;AAiBJ,SAAgB,YACd,OACgE;AAChE,QACE,iBAAiB,eACjB,OAAO,MAAM,SAAS,YACtB,MAAM,SAAS,QACf,UAAU,MAAM,QAChB,aAAa,MAAM"}
+{"version":3,"file":"errors.js","names":[],"sources":["../../../src/server/errors.ts"],"sourcesContent":["/**\n * Structured error handling for Convex Auth.\n *\n * Every error thrown by the auth system uses `ConvexError` with a\n * `{ code, message }` payload so clients can distinguish error types\n * and display user-friendly messages.\n *\n * **Consumer API:** Use {@link throwAuthError} to throw structured errors\n * from your own Convex functions (e.g. custom authorization checks).\n *\n * **Internal pattern:** The library itself uses `new AuthError(code)` with\n * the `@robelest/fx` effect system (`Fx.fail(new AuthError(code))`).\n * You do not need to use `AuthError` directly — it is an implementation detail.\n *\n * @module\n */\n\nimport { ConvexError } from \"convex/values\";\n\n// ============================================================================\n// Error code → default message map  (single source of truth)\n// ============================================================================\n\n/**\n * Map of every auth error code to its default human-readable message.\n *\n * Use the keys as the `code` argument to {@link throwAuthError}.\n * Clients can match on these codes for conditional error handling.\n *\n * @example\n * ```ts\n * throwAuthError(\"NOT_SIGNED_IN\");\n * // ConvexError { data: { code: \"NOT_SIGNED_IN\", message: \"You must be signed in...\" } }\n * ```\n */\nexport const AUTH_ERRORS = {\n  // ---- Configuration ----\n  PROVIDER_NOT_CONFIGURED: \"This sign-in method is not available.\",\n  EMAIL_CONFIG_REQUIRED:\n    \"Email transport is not configured. Configure email in createAuth(...).\",\n  MISSING_ENV_VAR: \"A required server environment variable is missing.\",\n  MISSING_ACTION_CONTEXT: \"Action context is required for this operation.\",\n  INVALID_PARAMETERS: \"The provided parameters are invalid.\",\n\n  // ---- Authentication ----\n  NOT_SIGNED_IN: \"You must be signed in to perform this action.\",\n  INVALID_VERIFICATION_CODE: \"Invalid or expired verification code.\",\n  INVALID_REFRESH_TOKEN: \"Your session has expired. Please sign in again.\",\n  AUTH_HANDSHAKE_TIMEOUT:\n    \"Sign-in succeeded but authentication confirmation timed out.\",\n  AUTH_HANDSHAKE_REJECTED:\n    \"Authentication was rejected while confirming the session.\",\n  SIGN_IN_MISSING_PARAMS:\n    \"Cannot sign in: missing provider, code, or refresh token.\",\n  UNSUPPORTED_PROVIDER_TYPE: \"This provider type is not supported.\",\n  INVALID_REDIRECT: \"Invalid redirect URL.\",\n\n  // ---- Email / Phone ----\n  EMAIL_SEND_FAILED: \"Failed to send verification email. Please try again.\",\n\n  // ---- API Keys ----\n  INVALID_API_KEY: \"Invalid API key.\",\n  API_KEY_REVOKED: \"This API key has been revoked.\",\n  API_KEY_EXPIRED: \"This API key has expired.\",\n  API_KEY_RATE_LIMITED: \"API key rate limit exceeded. Please try again later.\",\n  API_KEY_INVALID_SCOPE: \"Invalid scope requested for API key.\",\n  KEY_NOT_FOUND: \"API key not found.\",\n\n  // ---- HTTP Bearer Auth ----\n  MISSING_BEARER_TOKEN: \"Missing or malformed Authorization: Bearer header.\",\n  SCOPE_CHECK_FAILED: \"This API key does not have the required permissions.\",\n\n  // ---- OAuth ----\n  OAUTH_MISSING_PROVIDER: \"Missing OAuth provider ID.\",\n  OAUTH_MISSING_VERIFIER: \"Missing sign-in verifier.\",\n  OAUTH_INVALID_STATE: \"Invalid OAuth state. Please try signing in again.\",\n  OAUTH_PROVIDER_ERROR: \"The sign-in provider returned an error.\",\n  OAUTH_MISSING_ID_TOKEN:\n    \"ID token claims are missing from the provider response.\",\n  OAUTH_INVALID_PROFILE: \"The sign-in provider returned an invalid profile.\",\n  OAUTH_UNSUPPORTED_AUTH_METHOD:\n    \"Unsupported OAuth client authentication method.\",\n  OAUTH_NO_USERINFO: \"No userinfo endpoint configured for this provider.\",\n\n  // ---- Credentials ----\n  ACCOUNT_ALREADY_EXISTS: \"An account with these credentials already exists.\",\n  ACCOUNT_NOT_FOUND: \"Account not found.\",\n  INVALID_CREDENTIALS_PROVIDER:\n    \"This provider does not support credential operations.\",\n  MISSING_CRYPTO_FUNCTION:\n    \"This provider is missing a required cryptographic function.\",\n  USER_UPDATE_FAILED: \"Could not update the user record.\",\n\n  // ---- Verifier ----\n  INVALID_VERIFIER: \"Invalid or expired verifier.\",\n\n  // ---- Passkey ----\n  PASSKEY_MISSING_CONFIG:\n    \"Passkey provider requires SITE_URL or explicit rpId configuration.\",\n  PASSKEY_AUTH_REQUIRED: \"Sign in first, then add a passkey to your account.\",\n  PASSKEY_MISSING_VERIFIER: \"Missing verifier for passkey operation.\",\n  PASSKEY_INVALID_CLIENT_DATA: \"Invalid passkey client data.\",\n  PASSKEY_INVALID_ORIGIN: \"Passkey origin does not match the expected value.\",\n  PASSKEY_INVALID_CHALLENGE: \"Invalid or expired passkey challenge.\",\n  PASSKEY_RP_MISMATCH: \"Relying party ID mismatch.\",\n  PASSKEY_USER_PRESENCE: \"User presence flag not set.\",\n  PASSKEY_USER_VERIFICATION: \"User verification required but not performed.\",\n  PASSKEY_NO_CREDENTIAL: \"No credential in attestation.\",\n  PASSKEY_UNSUPPORTED_ALGORITHM: \"Unsupported passkey algorithm.\",\n  PASSKEY_INVALID_SIGNATURE: \"Invalid passkey signature.\",\n  PASSKEY_UNKNOWN_CREDENTIAL: \"Unknown passkey credential.\",\n  PASSKEY_COUNTER_ERROR:\n    \"Authenticator counter did not increase — possible credential cloning detected.\",\n  PASSKEY_MISSING_FLOW: \"Missing passkey flow parameter.\",\n  PASSKEY_UNKNOWN_FLOW: \"Unknown passkey flow.\",\n\n  // ---- TOTP ----\n  TOTP_AUTH_REQUIRED: \"Sign in first, then set up two-factor authentication.\",\n  TOTP_MISSING_VERIFIER: \"Missing verifier for TOTP operation.\",\n  TOTP_MISSING_CODE: \"Missing TOTP code.\",\n  TOTP_MISSING_ID: \"Missing TOTP enrollment ID.\",\n  TOTP_NOT_FOUND: \"TOTP enrollment not found.\",\n  TOTP_ALREADY_VERIFIED: \"TOTP enrollment is already verified.\",\n  TOTP_INVALID_CODE: \"Invalid TOTP code.\",\n  TOTP_INVALID_VERIFIER: \"Invalid or expired TOTP verifier.\",\n  TOTP_NO_ENROLLMENT: \"No verified TOTP enrollment found.\",\n  TOTP_MISSING_FLOW: \"Missing TOTP flow parameter.\",\n  TOTP_UNKNOWN_FLOW: \"Unknown TOTP flow.\",\n\n  // ---- Device Authorization (RFC 8628) ----\n  DEVICE_CODE_EXPIRED:\n    \"The device code has expired. Please start a new authorization request.\",\n  DEVICE_CODE_DENIED: \"The authorization request was denied.\",\n  DEVICE_AUTHORIZATION_PENDING: \"The user has not yet authorized this device.\",\n  DEVICE_SLOW_DOWN:\n    \"Polling too frequently. Increase the interval between requests.\",\n  DEVICE_INVALID_USER_CODE: \"Invalid or expired user code.\",\n  DEVICE_ALREADY_AUTHORIZED: \"This device code has already been authorized.\",\n  DEVICE_MISSING_FLOW: \"Missing device flow parameter.\",\n  DEVICE_UNKNOWN_FLOW: \"Unknown device flow.\",\n\n  // ---- Invites ----\n  INVITE_EXPIRED: \"This invitation has expired.\",\n  INVITE_EMAIL_MISMATCH: \"This invitation is for a different email.\",\n  INVITE_ALREADY_ACCEPTED: \"This invitation has already been accepted.\",\n  DUPLICATE_INVITE:\n    \"A pending invite already exists for this email in this group.\",\n  INVITE_NOT_FOUND: \"Invite not found.\",\n  INVITE_NOT_PENDING: \"Cannot accept or revoke invite that is not pending.\",\n\n  // ---- Groups / Members ----\n  FORBIDDEN: \"Access denied.\",\n  NO_ACTIVE_GROUP: \"User has no active group set.\",\n  DUPLICATE_MEMBERSHIP: \"User is already a member of this group.\",\n\n  // ---- Enterprise ----\n  ENTERPRISE_ALREADY_EXISTS:\n    \"An enterprise record already exists for this group.\",\n  ENTERPRISE_DOMAIN_TAKEN:\n    \"That domain is already attached to another enterprise.\",\n\n  // ---- Internal (should never reach user) ----\n  INTERNAL_ERROR: \"An unexpected error occurred.\",\n} as const satisfies Record<string, string>;\n\n/** Union of all recognized auth error code strings (keys of {@link AUTH_ERRORS}). */\nexport type AuthErrorCode = keyof typeof AUTH_ERRORS;\n\n// ============================================================================\n// Error helpers\n// ============================================================================\n\n/**\n * Throw a structured `ConvexError` with `{ code, message }`.\n *\n * Use this in your own Convex functions (queries, mutations, actions)\n * to throw auth-domain errors that clients can match on by `code`.\n * The library itself uses `AuthError` internally, but consumers\n * should prefer this helper for simplicity.\n *\n * @param code    Machine-readable error code from `AUTH_ERRORS`.\n * @param message Optional override for the default human-readable message.\n * @param context Optional extra fields merged into the error payload.\n *\n * @example\n * ```ts\n * import { throwAuthError } from \"@robelest/convex-auth/server\";\n *\n * // In a custom mutation:\n * if (!isAdmin) {\n *   throwAuthError(\"FORBIDDEN\");\n * }\n * ```\n *\n * @throws {ConvexError} Always — throws a `ConvexError` with `{ code, message }` payload.\n */\nexport function throwAuthError(\n  code: AuthErrorCode,\n  message?: string,\n  context?: Record<string, unknown>,\n): never {\n  throw new ConvexError({\n    code,\n    message: message ?? AUTH_ERRORS[code],\n    ...context,\n  });\n}\n\n/**\n * Type guard: check whether a caught value is a structured auth `ConvexError`.\n *\n * @param error - The caught value (typically from a `catch` block).\n * @returns `true` when `error` is a `ConvexError` with `{ code, message }` data.\n *\n * @example\n * ```ts\n * try { await auth.signIn('email', { email }); }\n * catch (e) {\n *   if (isAuthError(e)) console.log(e.data.code); // \"EMAIL_SEND_FAILED\"\n * }\n * ```\n */\nexport function isAuthError(\n  error: unknown,\n): error is ConvexError<{ code: AuthErrorCode; message: string }> {\n  return (\n    error instanceof ConvexError &&\n    typeof error.data === \"object\" &&\n    error.data !== null &&\n    \"code\" in error.data &&\n    \"message\" in error.data\n  );\n}\n\n/**\n * Extract `{ code, message }` from a caught error.\n *\n * Works for `ConvexError` (from Convex actions), plain `Error`\n * instances, and structured auth errors. Returns `null` when the\n * value is not an error object.\n *\n * @param error - The caught value to parse.\n * @returns `{ code, message }` when extractable, or `null`.\n *   When `code` is `null`, the error is not a structured auth error\n *   but `message` still contains the error text.\n *\n * @example\n * ```ts\n * try {\n *   await auth.signIn(\"email\", { email });\n * } catch (e) {\n *   const err = parseAuthError(e);\n *   if (err?.code === \"EMAIL_SEND_FAILED\") { ... }\n * }\n * ```\n */\nexport function parseAuthError(\n  error: unknown,\n):\n  | { code: AuthErrorCode; message: string }\n  | { code: null; message: string }\n  | null {\n  if (isAuthError(error)) {\n    const { code, message } = error.data as {\n      code: AuthErrorCode;\n      message: string;\n    };\n    return { code, message };\n  }\n  // Recognize the Fx-native AuthError class (has _tag + code)\n  if (\n    error instanceof Error &&\n    \"_tag\" in error &&\n    (error as any)._tag === \"AuthError\" &&\n    \"code\" in error &&\n    typeof (error as any).code === \"string\"\n  ) {\n    return {\n      code: (error as any).code as AuthErrorCode,\n      message: error.message,\n    };\n  }\n  if (error instanceof ConvexError && typeof error.data === \"string\") {\n    return { code: null, message: error.data };\n  }\n  if (error instanceof Error) {\n    return { code: null, message: error.message };\n  }\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,cAAc;CAEzB,yBAAyB;CACzB,uBACE;CACF,iBAAiB;CACjB,wBAAwB;CACxB,oBAAoB;CAGpB,eAAe;CACf,2BAA2B;CAC3B,uBAAuB;CACvB,wBACE;CACF,yBACE;CACF,wBACE;CACF,2BAA2B;CAC3B,kBAAkB;CAGlB,mBAAmB;CAGnB,iBAAiB;CACjB,iBAAiB;CACjB,iBAAiB;CACjB,sBAAsB;CACtB,uBAAuB;CACvB,eAAe;CAGf,sBAAsB;CACtB,oBAAoB;CAGpB,wBAAwB;CACxB,wBAAwB;CACxB,qBAAqB;CACrB,sBAAsB;CACtB,wBACE;CACF,uBAAuB;CACvB,+BACE;CACF,mBAAmB;CAGnB,wBAAwB;CACxB,mBAAmB;CACnB,8BACE;CACF,yBACE;CACF,oBAAoB;CAGpB,kBAAkB;CAGlB,wBACE;CACF,uBAAuB;CACvB,0BAA0B;CAC1B,6BAA6B;CAC7B,wBAAwB;CACxB,2BAA2B;CAC3B,qBAAqB;CACrB,uBAAuB;CACvB,2BAA2B;CAC3B,uBAAuB;CACvB,+BAA+B;CAC/B,2BAA2B;CAC3B,4BAA4B;CAC5B,uBACE;CACF,sBAAsB;CACtB,sBAAsB;CAGtB,oBAAoB;CACpB,uBAAuB;CACvB,mBAAmB;CACnB,iBAAiB;CACjB,gBAAgB;CAChB,uBAAuB;CACvB,mBAAmB;CACnB,uBAAuB;CACvB,oBAAoB;CACpB,mBAAmB;CACnB,mBAAmB;CAGnB,qBACE;CACF,oBAAoB;CACpB,8BAA8B;CAC9B,kBACE;CACF,0BAA0B;CAC1B,2BAA2B;CAC3B,qBAAqB;CACrB,qBAAqB;CAGrB,gBAAgB;CAChB,uBAAuB;CACvB,yBAAyB;CACzB,kBACE;CACF,kBAAkB;CAClB,oBAAoB;CAGpB,WAAW;CACX,iBAAiB;CACjB,sBAAsB;CAGtB,2BACE;CACF,yBACE;CAGF,gBAAgB;CACjB;;;;;;;;;;;;;;;AA2DD,SAAgB,YACd,OACgE;AAChE,QACE,iBAAiB,eACjB,OAAO,MAAM,SAAS,YACtB,MAAM,SAAS,QACf,UAAU,MAAM,QAChB,aAAa,MAAM"}

package/dist/component/server/http.js

@@ -0,0 +1,288 @@
+import { isAuthError } from "./errors.js";
+import { AuthError } from "./authError.js";
+import { logError } from "./utils.js";
+import { httpActionGeneric } from "convex/server";
+import { ConvexError } from "convex/values";
+import { parse } from "cookie";
+import { Fx } from "@robelest/fx";
+
+//#region src/server/http.ts
+function createHttpAction(auth) {
+	return (handler, options) => {
+		const corsConfig = options?.cors ?? {};
+		const corsHeaders = {
+			"Access-Control-Allow-Origin": corsConfig.origin ?? "*",
+			"Access-Control-Allow-Methods": corsConfig.methods ?? "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+			"Access-Control-Allow-Headers": corsConfig.headers ?? "Content-Type,Authorization"
+		};
+		return httpActionGeneric(async (genericCtx, request) => {
+			return Fx.run(Fx.from({
+				ok: async () => {
+					const authHeader = request.headers.get("Authorization");
+					if (!authHeader?.startsWith("Bearer ")) return new Response(JSON.stringify({
+						error: "Missing or malformed Authorization: Bearer header.",
+						code: "MISSING_BEARER_TOKEN"
+					}), {
+						status: 401,
+						headers: {
+							...corsHeaders,
+							"Content-Type": "application/json"
+						}
+					});
+					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$1) => ({
+							ok: true,
+							value: result$1
+						}),
+						err: (error) => ({
+							ok: false,
+							error
+						})
+					})));
+					if (!keyResult.ok) {
+						if (isAuthError(keyResult.error)) {
+							const { code, message } = keyResult.error.data;
+							return new Response(JSON.stringify({
+								error: message,
+								code
+							}), {
+								status: 403,
+								headers: {
+									...corsHeaders,
+									"Content-Type": "application/json"
+								}
+							});
+						}
+						throw keyResult.error;
+					}
+					if (options?.scope && !keyResult.value.scopes.can(options.scope.resource, options.scope.action)) return new Response(JSON.stringify({
+						error: "This API key does not have the required permissions.",
+						code: "SCOPE_CHECK_FAILED"
+					}), {
+						status: 403,
+						headers: {
+							...corsHeaders,
+							"Content-Type": "application/json"
+						}
+					});
+					const result = await handler(Object.assign(genericCtx, { key: {
+						userId: keyResult.value.userId,
+						keyId: keyResult.value.keyId,
+						scopes: keyResult.value.scopes
+					} }), request);
+					if (result instanceof Response) {
+						const headers = new Headers(result.headers);
+						for (const [k, val] of Object.entries(corsHeaders)) if (!headers.has(k)) headers.set(k, val);
+						return new Response(result.body, {
+							status: result.status,
+							statusText: result.statusText,
+							headers
+						});
+					}
+					return new Response(JSON.stringify(result), {
+						status: 200,
+						headers: {
+							...corsHeaders,
+							"Content-Type": "application/json"
+						}
+					});
+				},
+				err: (error) => error
+			}).pipe(Fx.recover((error) => {
+				logError(error);
+				return Fx.succeed(new Response(JSON.stringify({
+					error: "An unexpected error occurred.",
+					code: "INTERNAL_ERROR"
+				}), {
+					status: 500,
+					headers: {
+						...corsHeaders,
+						"Content-Type": "application/json"
+					}
+				}));
+			})));
+		});
+	};
+}
+function createHttpRoute(wrapAction) {
+	return (http, routeConfig) => {
+		const corsConfig = routeConfig.cors ?? {};
+		const corsHeaders = {
+			"Access-Control-Allow-Origin": corsConfig.origin ?? "*",
+			"Access-Control-Allow-Methods": corsConfig.methods ?? "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+			"Access-Control-Allow-Headers": corsConfig.headers ?? "Content-Type,Authorization"
+		};
+		http.route({
+			path: routeConfig.path,
+			method: "OPTIONS",
+			handler: httpActionGeneric(async () => {
+				return new Response(null, {
+					status: 204,
+					headers: corsHeaders
+				});
+			})
+		});
+		http.route({
+			path: routeConfig.path,
+			method: routeConfig.method,
+			handler: wrapAction(routeConfig.handler, {
+				scope: routeConfig.scope,
+				cors: routeConfig.cors
+			})
+		});
+	};
+}
+function convertErrorsToResponse(errorStatusCode, action) {
+	return async (ctx, request) => {
+		return Fx.run(Fx.from({
+			ok: () => action(ctx, request),
+			err: (error) => error
+		}).pipe(Fx.recover((error) => {
+			if (isAuthError(error)) return Fx.succeed(new Response(JSON.stringify({
+				code: error.data.code,
+				message: error.data.message
+			}), {
+				status: errorStatusCode,
+				headers: { "Content-Type": "application/json" }
+			}));
+			else if (error instanceof ConvexError) return Fx.succeed(new Response(null, {
+				status: errorStatusCode,
+				statusText: typeof error.data === "string" ? error.data : "Error"
+			}));
+			else {
+				logError(error);
+				return Fx.succeed(new Response(null, {
+					status: 500,
+					statusText: "Internal Server Error"
+				}));
+			}
+		})));
+	};
+}
+function getCookies(request) {
+	return parse(request.headers.get("Cookie") ?? "");
+}
+function parseEnterpriseRuntimeRoute(pathname, routeBase) {
+	const runtimePrefix = `${routeBase}/`;
+	const [runtimeEnterpriseId, protocol, ...rest] = pathname.startsWith(runtimePrefix) ? pathname.slice(runtimePrefix.length).split("/").filter(Boolean) : [];
+	if (runtimeEnterpriseId === void 0 || protocol !== "oidc" && protocol !== "saml" && protocol !== "scim" || rest.length === 0) return null;
+	return {
+		pathname,
+		enterpriseId: runtimeEnterpriseId,
+		protocol,
+		rest
+	};
+}
+function addOpenIdRoutes(http, deps) {
+	const cacheControl = "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400";
+	http.route({
+		path: "/.well-known/openid-configuration",
+		method: "GET",
+		handler: httpActionGeneric(async () => {
+			const issuer = deps.getIssuer();
+			return new Response(JSON.stringify({
+				issuer,
+				jwks_uri: `${issuer}/.well-known/jwks.json`
+			}), {
+				status: 200,
+				headers: {
+					"Content-Type": "application/json",
+					"Cache-Control": cacheControl
+				}
+			});
+		})
+	});
+	http.route({
+		path: "/.well-known/jwks.json",
+		method: "GET",
+		handler: httpActionGeneric(async () => {
+			return new Response(deps.getJwks(), {
+				status: 200,
+				headers: {
+					"Content-Type": "application/json",
+					"Cache-Control": cacheControl
+				}
+			});
+		})
+	});
+}
+function addAuthRoutes(http, deps) {
+	http.route({
+		pathPrefix: "/api/auth/signin/",
+		method: "GET",
+		handler: httpActionGeneric(deps.handleSignIn)
+	});
+	const callbackHandler = httpActionGeneric(deps.handleCallback);
+	http.route({
+		pathPrefix: "/api/auth/callback/",
+		method: "GET",
+		handler: callbackHandler
+	});
+	http.route({
+		pathPrefix: "/api/auth/callback/",
+		method: "POST",
+		handler: callbackHandler
+	});
+}
+function addSSORoutes(http, deps) {
+	const routePrefix = `${deps.routeBase}/`;
+	http.route({
+		pathPrefix: routePrefix,
+		method: "GET",
+		handler: httpActionGeneric(deps.convertErrorsToResponse(400, async (ctx, request) => {
+			const route = parseEnterpriseRuntimeRoute(new URL(request.url).pathname, deps.routeBase);
+			if (!route) throw new AuthError("INVALID_PARAMETERS", "Invalid enterprise runtime path.").toConvexError();
+			if (route.protocol === "saml" && route.rest.length === 1) {
+				if (route.rest[0] === "metadata") return await deps.handleSamlMetadata(ctx, request, route);
+				if (route.rest[0] === "signin") return await deps.handleSamlSignIn(ctx, request, route);
+				if (route.rest[0] === "acs") return await deps.handleSamlAcs(ctx, request, route);
+				if (route.rest[0] === "slo") return await deps.handleSamlSlo(ctx, request, route);
+			}
+			if (route.protocol === "oidc" && route.rest.length === 1) {
+				if (route.rest[0] === "signin") return await deps.handleOidcSignIn(ctx, request, route);
+				if (route.rest[0] === "callback") return await deps.handleOidcCallback(ctx, request, route);
+			}
+			if (route.protocol === "scim" && route.rest[0] === "v2") return await deps.handleScimRequest(ctx, request);
+			throw new AuthError("INVALID_PARAMETERS", "Invalid enterprise runtime path.").toConvexError();
+		}))
+	});
+	http.route({
+		pathPrefix: routePrefix,
+		method: "POST",
+		handler: httpActionGeneric(deps.convertErrorsToResponse(400, async (ctx, request) => {
+			const route = parseEnterpriseRuntimeRoute(new URL(request.url).pathname, deps.routeBase);
+			if (route?.protocol === "saml" && route.rest.length === 1) {
+				if (route.rest[0] === "acs") return await deps.handleSamlAcs(ctx, request, route);
+				if (route.rest[0] === "slo") return await deps.handleSamlSlo(ctx, request, route);
+			}
+			if (route?.protocol === "scim" && route.rest[0] === "v2") return await deps.handleScimRequest(ctx, request);
+			throw new AuthError("INVALID_PARAMETERS", "Invalid enterprise runtime path.").toConvexError();
+		}))
+	});
+	http.route({
+		pathPrefix: routePrefix,
+		method: "PUT",
+		handler: httpActionGeneric(deps.convertErrorsToResponse(400, async (ctx, request) => {
+			const route = parseEnterpriseRuntimeRoute(new URL(request.url).pathname, deps.routeBase);
+			if (route?.protocol === "scim" && route.rest[0] === "v2") return await deps.handleScimRequest(ctx, request);
+			throw new AuthError("INVALID_PARAMETERS", "Invalid enterprise runtime path.").toConvexError();
+		}))
+	});
+	for (const method of ["PATCH", "DELETE"]) http.route({
+		pathPrefix: routePrefix,
+		method,
+		handler: httpActionGeneric(async (ctx, request) => {
+			const route = parseEnterpriseRuntimeRoute(new URL(request.url).pathname, deps.routeBase);
+			if (!route || route.protocol !== "scim" || route.rest[0] !== "v2") return deps.scimError(404, "notFound", "SCIM resource not found.");
+			return await deps.handleScimRequest(ctx, request);
+		})
+	});
+}
+
+//#endregion
+export { addAuthRoutes, addOpenIdRoutes, addSSORoutes, convertErrorsToResponse, createHttpAction, createHttpRoute, getCookies };
+//# sourceMappingURL=http.js.map

package/dist/component/server/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":["result","parseCookies"],"sources":["../../../src/server/http.ts"],"sourcesContent":["import {\n  GenericActionCtx,\n  GenericDataModel,\n  HttpRouter,\n  httpActionGeneric,\n} from \"convex/server\";\nimport { ConvexError } from \"convex/values\";\nimport { parse as parseCookies } from \"cookie\";\n\nimport { isAuthError } from \"./errors\";\nimport { Fx } from \"@robelest/fx\";\n\nimport { AuthError } from \"./authError\";\nimport type { CorsConfig, HttpKeyContext } from \"./types\";\nimport { logError } from \"./utils\";\n\nexport function createHttpAction(auth: {\n  key: { verify: (ctx: GenericActionCtx<any>, rawKey: string) => Promise<any> };\n}) {\n  return (\n    handler: (\n      ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext,\n      request: Request,\n    ) => Promise<Response | Record<string, unknown>>,\n    options?: {\n      scope?: { resource: string; action: string };\n      cors?: CorsConfig;\n    },\n  ) => {\n    const corsConfig = options?.cors ?? {};\n    const corsHeaders: Record<string, string> = {\n      \"Access-Control-Allow-Origin\": corsConfig.origin ?? \"*\",\n      \"Access-Control-Allow-Methods\":\n        corsConfig.methods ?? \"GET,POST,PUT,PATCH,DELETE,OPTIONS\",\n      \"Access-Control-Allow-Headers\":\n        corsConfig.headers ?? \"Content-Type,Authorization\",\n    };\n\n    return httpActionGeneric(async (genericCtx, request) => {\n      return Fx.run(\n        Fx.from({\n          ok: async () => {\n            const authHeader = request.headers.get(\"Authorization\");\n            if (!authHeader?.startsWith(\"Bearer \")) {\n              return new Response(\n                JSON.stringify({\n                  error: \"Missing or malformed Authorization: Bearer header.\",\n                  code: \"MISSING_BEARER_TOKEN\",\n                }),\n                {\n                  status: 401,\n                  headers: {\n                    ...corsHeaders,\n                    \"Content-Type\": \"application/json\",\n                  },\n                },\n              );\n            }\n            const rawKey = authHeader.slice(7);\n\n            const keyResult = await Fx.run(\n              Fx.from({\n                ok: () => auth.key.verify(genericCtx, rawKey),\n                err: (error) => error,\n              }).pipe(\n                Fx.fold({\n                  ok: (result) => ({ ok: true, value: result }) as const,\n                  err: (error) => ({ ok: false, error }) as const,\n                }),\n              ),\n            );\n\n            if (!keyResult.ok) {\n              if (isAuthError(keyResult.error)) {\n                const { code, message } = keyResult.error.data as {\n                  code: string;\n                  message: string;\n                };\n                return new Response(JSON.stringify({ error: message, code }), {\n                  status: 403,\n                  headers: {\n                    ...corsHeaders,\n                    \"Content-Type\": \"application/json\",\n                  },\n                });\n              }\n              throw keyResult.error;\n            }\n\n            if (\n              options?.scope &&\n              !keyResult.value.scopes.can(\n                options.scope.resource,\n                options.scope.action,\n              )\n            ) {\n              return new Response(\n                JSON.stringify({\n                  error: \"This API key does not have the required permissions.\",\n                  code: \"SCOPE_CHECK_FAILED\",\n                }),\n                {\n                  status: 403,\n                  headers: {\n                    ...corsHeaders,\n                    \"Content-Type\": \"application/json\",\n                  },\n                },\n              );\n            }\n\n            const enrichedCtx = Object.assign(genericCtx, {\n              key: {\n                userId: keyResult.value.userId,\n                keyId: keyResult.value.keyId,\n                scopes: keyResult.value.scopes,\n              },\n            });\n            const result = await handler(enrichedCtx, request);\n\n            if (result instanceof Response) {\n              const headers = new Headers(result.headers);\n              for (const [k, val] of Object.entries(corsHeaders)) {\n                if (!headers.has(k)) headers.set(k, val);\n              }\n              return new Response(result.body, {\n                status: result.status,\n                statusText: result.statusText,\n                headers,\n              });\n            }\n\n            return new Response(JSON.stringify(result), {\n              status: 200,\n              headers: {\n                ...corsHeaders,\n                \"Content-Type\": \"application/json\",\n              },\n            });\n          },\n          err: (error) => error,\n        }).pipe(\n          Fx.recover((error) => {\n            logError(error);\n            return Fx.succeed(\n              new Response(\n                JSON.stringify({\n                  error: \"An unexpected error occurred.\",\n                  code: \"INTERNAL_ERROR\",\n                }),\n                {\n                  status: 500,\n                  headers: {\n                    ...corsHeaders,\n                    \"Content-Type\": \"application/json\",\n                  },\n                },\n              ),\n            );\n          }),\n        ),\n      );\n    });\n  };\n}\n\nexport function createHttpRoute(\n  wrapAction: ReturnType<typeof createHttpAction>,\n) {\n  return (\n    http: { route: (config: any) => void },\n    routeConfig: {\n      path: string;\n      method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n      handler: (\n        ctx: GenericActionCtx<GenericDataModel> & HttpKeyContext,\n        request: Request,\n      ) => Promise<Response | Record<string, unknown>>;\n      scope?: { resource: string; action: string };\n      cors?: CorsConfig;\n    },\n  ) => {\n    const corsConfig = routeConfig.cors ?? {};\n    const corsHeaders: Record<string, string> = {\n      \"Access-Control-Allow-Origin\": corsConfig.origin ?? \"*\",\n      \"Access-Control-Allow-Methods\":\n        corsConfig.methods ?? \"GET,POST,PUT,PATCH,DELETE,OPTIONS\",\n      \"Access-Control-Allow-Headers\":\n        corsConfig.headers ?? \"Content-Type,Authorization\",\n    };\n\n    http.route({\n      path: routeConfig.path,\n      method: \"OPTIONS\",\n      handler: httpActionGeneric(async () => {\n        return new Response(null, { status: 204, headers: corsHeaders });\n      }),\n    });\n\n    http.route({\n      path: routeConfig.path,\n      method: routeConfig.method,\n      handler: wrapAction(routeConfig.handler, {\n        scope: routeConfig.scope,\n        cors: routeConfig.cors,\n      }),\n    });\n  };\n}\n\nexport function convertErrorsToResponse(\n  errorStatusCode: number,\n  action: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,\n) {\n  return async (ctx: GenericActionCtx<any>, request: Request) => {\n    return Fx.run(\n      Fx.from({\n        ok: () => action(ctx, request),\n        err: (error) => error,\n      }).pipe(\n        Fx.recover((error) => {\n          if (isAuthError(error)) {\n            return Fx.succeed(\n              new Response(\n                JSON.stringify({\n                  code: error.data.code,\n                  message: error.data.message,\n                }),\n                {\n                  status: errorStatusCode,\n                  headers: { \"Content-Type\": \"application/json\" },\n                },\n              ),\n            );\n          } else if (error instanceof ConvexError) {\n            return Fx.succeed(\n              new Response(null, {\n                status: errorStatusCode,\n                statusText:\n                  typeof error.data === \"string\" ? error.data : \"Error\",\n              }),\n            );\n          } else {\n            logError(error);\n            return Fx.succeed(\n              new Response(null, {\n                status: 500,\n                statusText: \"Internal Server Error\",\n              }),\n            );\n          }\n        }),\n      ),\n    );\n  };\n}\n\nexport function getCookies(\n  request: Request,\n): Record<string, string | undefined> {\n  return parseCookies(request.headers.get(\"Cookie\") ?? \"\");\n}\n\nexport type SSORuntimeRoute = {\n  pathname?: string;\n  enterpriseId: string;\n  protocol: \"oidc\" | \"saml\" | \"scim\";\n  rest: string[];\n};\n\nfunction parseEnterpriseRuntimeRoute(\n  pathname: string,\n  routeBase: string,\n): SSORuntimeRoute | null {\n  const runtimePrefix = `${routeBase}/`;\n  const runtimeParts = pathname.startsWith(runtimePrefix)\n    ? pathname.slice(runtimePrefix.length).split(\"/\").filter(Boolean)\n    : [];\n  const [runtimeEnterpriseId, protocol, ...rest] = runtimeParts;\n  if (\n    runtimeEnterpriseId === undefined ||\n    (protocol !== \"oidc\" && protocol !== \"saml\" && protocol !== \"scim\") ||\n    rest.length === 0\n  ) {\n    return null;\n  }\n  return {\n    pathname,\n    enterpriseId: runtimeEnterpriseId,\n    protocol,\n    rest,\n  };\n}\n\nexport function addOpenIdRoutes(\n  http: HttpRouter,\n  deps: {\n    getIssuer: () => string;\n    getJwks: () => string;\n  },\n) {\n  const cacheControl =\n    \"public, max-age=15, stale-while-revalidate=15, stale-if-error=86400\";\n\n  http.route({\n    path: \"/.well-known/openid-configuration\",\n    method: \"GET\",\n    handler: httpActionGeneric(async () => {\n      const issuer = deps.getIssuer();\n      return new Response(\n        JSON.stringify({\n          issuer,\n          jwks_uri: `${issuer}/.well-known/jwks.json`,\n        }),\n        {\n          status: 200,\n          headers: {\n            \"Content-Type\": \"application/json\",\n            \"Cache-Control\": cacheControl,\n          },\n        },\n      );\n    }),\n  });\n\n  http.route({\n    path: \"/.well-known/jwks.json\",\n    method: \"GET\",\n    handler: httpActionGeneric(async () => {\n      return new Response(deps.getJwks(), {\n        status: 200,\n        headers: {\n          \"Content-Type\": \"application/json\",\n          \"Cache-Control\": cacheControl,\n        },\n      });\n    }),\n  });\n}\n\nexport function addAuthRoutes(\n  http: HttpRouter,\n  deps: {\n    handleSignIn: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n    ) => Promise<Response>;\n    handleCallback: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n    ) => Promise<Response>;\n  },\n) {\n  http.route({\n    pathPrefix: \"/api/auth/signin/\",\n    method: \"GET\",\n    handler: httpActionGeneric(deps.handleSignIn),\n  });\n\n  const callbackHandler = httpActionGeneric(deps.handleCallback);\n\n  http.route({\n    pathPrefix: \"/api/auth/callback/\",\n    method: \"GET\",\n    handler: callbackHandler,\n  });\n\n  http.route({\n    pathPrefix: \"/api/auth/callback/\",\n    method: \"POST\",\n    handler: callbackHandler,\n  });\n}\n\nexport function addSSORoutes(\n  http: HttpRouter,\n  deps: {\n    routeBase: string;\n    convertErrorsToResponse: typeof convertErrorsToResponse;\n    handleSamlMetadata: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleSamlSignIn: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleOidcSignIn: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleOidcCallback: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleSamlAcs: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleSamlSlo: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n      route: SSORuntimeRoute,\n    ) => Promise<Response>;\n    handleScimRequest: (\n      ctx: GenericActionCtx<any>,\n      request: Request,\n    ) => Promise<Response>;\n    scimError: (status: number, scimType: string, detail: string) => Response;\n  },\n) {\n  const routePrefix = `${deps.routeBase}/`;\n\n  http.route({\n    pathPrefix: routePrefix,\n    method: \"GET\",\n    handler: httpActionGeneric(\n      deps.convertErrorsToResponse(400, async (ctx, request) => {\n        const route = parseEnterpriseRuntimeRoute(\n          new URL(request.url).pathname,\n          deps.routeBase,\n        );\n        if (!route) {\n          throw new AuthError(\n            \"INVALID_PARAMETERS\",\n            \"Invalid enterprise runtime path.\",\n          ).toConvexError();\n        }\n        if (route.protocol === \"saml\" && route.rest.length === 1) {\n          if (route.rest[0] === \"metadata\") {\n            return await deps.handleSamlMetadata(ctx, request, route);\n          }\n          if (route.rest[0] === \"signin\") {\n            return await deps.handleSamlSignIn(ctx, request, route);\n          }\n          if (route.rest[0] === \"acs\") {\n            return await deps.handleSamlAcs(ctx, request, route);\n          }\n          if (route.rest[0] === \"slo\") {\n            return await deps.handleSamlSlo(ctx, request, route);\n          }\n        }\n        if (route.protocol === \"oidc\" && route.rest.length === 1) {\n          if (route.rest[0] === \"signin\") {\n            return await deps.handleOidcSignIn(ctx, request, route);\n          }\n          if (route.rest[0] === \"callback\") {\n            return await deps.handleOidcCallback(ctx, request, route);\n          }\n        }\n        if (route.protocol === \"scim\" && route.rest[0] === \"v2\") {\n          return await deps.handleScimRequest(ctx, request);\n        }\n        throw new AuthError(\n          \"INVALID_PARAMETERS\",\n          \"Invalid enterprise runtime path.\",\n        ).toConvexError();\n      }),\n    ),\n  });\n\n  http.route({\n    pathPrefix: routePrefix,\n    method: \"POST\",\n    handler: httpActionGeneric(\n      deps.convertErrorsToResponse(400, async (ctx, request) => {\n        const route = parseEnterpriseRuntimeRoute(\n          new URL(request.url).pathname,\n          deps.routeBase,\n        );\n        if (route?.protocol === \"saml\" && route.rest.length === 1) {\n          if (route.rest[0] === \"acs\") {\n            return await deps.handleSamlAcs(ctx, request, route);\n          }\n          if (route.rest[0] === \"slo\") {\n            return await deps.handleSamlSlo(ctx, request, route);\n          }\n        }\n        if (route?.protocol === \"scim\" && route.rest[0] === \"v2\") {\n          return await deps.handleScimRequest(ctx, request);\n        }\n        throw new AuthError(\n          \"INVALID_PARAMETERS\",\n          \"Invalid enterprise runtime path.\",\n        ).toConvexError();\n      }),\n    ),\n  });\n\n  http.route({\n    pathPrefix: routePrefix,\n    method: \"PUT\",\n    handler: httpActionGeneric(\n      deps.convertErrorsToResponse(400, async (ctx, request) => {\n        const route = parseEnterpriseRuntimeRoute(\n          new URL(request.url).pathname,\n          deps.routeBase,\n        );\n        if (route?.protocol === \"scim\" && route.rest[0] === \"v2\") {\n          return await deps.handleScimRequest(ctx, request);\n        }\n        throw new AuthError(\n          \"INVALID_PARAMETERS\",\n          \"Invalid enterprise runtime path.\",\n        ).toConvexError();\n      }),\n    ),\n  });\n\n  for (const method of [\"PATCH\", \"DELETE\"] as const) {\n    http.route({\n      pathPrefix: routePrefix,\n      method,\n      handler: httpActionGeneric(async (ctx, request) => {\n        const route = parseEnterpriseRuntimeRoute(\n          new URL(request.url).pathname,\n          deps.routeBase,\n        );\n        if (!route || route.protocol !== \"scim\" || route.rest[0] !== \"v2\") {\n          return deps.scimError(404, \"notFound\", \"SCIM resource not found.\");\n        }\n        return await deps.handleScimRequest(ctx, request);\n      }),\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/component/server/identity.js

@@ -0,0 +1,13 @@
+import { AuthError } from "./authError.js";
+
+//#region src/server/identity.ts
+/** @internal */
+function userIdFromIdentitySubject(subject) {
+	const [userId, ...rest] = subject.split("|");
+	if (typeof userId !== "string" || userId.length === 0 || rest.length === 0 || rest.some((segment) => segment.length === 0)) throw new AuthError("INTERNAL_ERROR", "Authenticated identity subject is malformed.");
+	return userId;
+}
+
+//#endregion
+export { userIdFromIdentitySubject };
+//# sourceMappingURL=identity.js.map

package/dist/component/server/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","names":[],"sources":["../../../src/server/identity.ts"],"sourcesContent":["import { AuthError } from \"./authError\";\n\n/** @internal */\nexport function userIdFromIdentitySubject(subject: string): string {\n  const [userId, ...rest] = subject.split(\"|\");\n  if (\n    typeof userId !== \"string\" ||\n    userId.length === 0 ||\n    rest.length === 0 ||\n    rest.some((segment) => segment.length === 0)\n  ) {\n    throw new AuthError(\n      \"INTERNAL_ERROR\",\n      \"Authenticated identity subject is malformed.\",\n    );\n  }\n  return userId;\n}\n"],"mappings":";;;;AAGA,SAAgB,0BAA0B,SAAyB;CACjE,MAAM,CAAC,QAAQ,GAAG,QAAQ,QAAQ,MAAM,IAAI;AAC5C,KACE,OAAO,WAAW,YAClB,OAAO,WAAW,KAClB,KAAK,WAAW,KAChB,KAAK,MAAM,YAAY,QAAQ,WAAW,EAAE,CAE5C,OAAM,IAAI,UACR,kBACA,+CACD;AAEH,QAAO"}

package/dist/{server/implementation → component/server}/keys.js

@@ -1,22 +1,12 @@
-import { throwAuthError } from "../errors.js";
 import { generateRandomString, sha256 } from "./utils.js";
 
-//#region src/server/implementation/keys.ts
-/**
-* API Key crypto utilities.
-*
-* Uses `@oslojs/crypto` primitives for key generation and hashing:
-* - SHA-256 for hashing keys (API keys have high entropy, no need for bcrypt)
-* - Cryptographically secure random generation for key material
-*
-* @module
-*/
-const DEFAULT_KEY_PREFIX = "sk_live_";
+//#region src/server/keys.ts
+const DEFAULT_KEY_PREFIX = "sk_";
 const KEY_RANDOM_LENGTH = 32;
 const KEY_RANDOM_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 /**
 * How many characters of the full key to store as the visible prefix.
-* Includes the prefix string (e.g. "sk_live_") plus a few random chars.
+* Includes the prefix string (e.g. "sk_") plus a few random chars.
 */
 const VISIBLE_PREFIX_EXTRA_CHARS = 4;
 /**
@@ -25,9 +15,10 @@ const VISIBLE_PREFIX_EXTRA_CHARS = 4;
 * Returns the raw key (to be shown once to the user) and metadata for storage.
 * The raw key is `{prefix}{32 random alphanumeric chars}`.
 *
-* @param prefix - Key prefix, defaults to "sk_live_"
+* @param prefix - Key prefix, defaults to "sk_"
 * @returns `{ raw, hashedKey, displayPrefix }`
 */
+/** @internal */
 async function generateApiKey(prefix = DEFAULT_KEY_PREFIX) {
 	const raw = `${prefix}${generateRandomString(KEY_RANDOM_LENGTH, KEY_RANDOM_ALPHABET)}`;
 	return {
@@ -41,6 +32,7 @@ async function generateApiKey(prefix = DEFAULT_KEY_PREFIX) {
 *
 * Used during Bearer token verification to find the stored key record.
 */
+/** @internal */
 async function hashApiKey(rawKey) {
 	return sha256(rawKey);
 }
@@ -53,6 +45,7 @@ async function hashApiKey(rawKey) {
 * A wildcard action `"*"` grants all actions on that resource.
 * A wildcard resource `"*"` grants the action on all resources.
 */
+/** @internal */
 function buildScopeChecker(scopes) {
 	return {
 		scopes,
@@ -62,22 +55,6 @@ function buildScopeChecker(scopes) {
 	};
 }
 /**
-* Validate that requested scopes are a subset of the allowed scopes
-* defined in the API key config.
-*
-* @param requested - Scopes the user wants on the new key.
-* @param allowed - The scope definition from `apiKeys.scopes` config.
-* @throws Error if any requested scope is not in the allowed set.
-*/
-function validateScopes(requested, allowed) {
-	if (!allowed) return;
-	for (const scope of requested) {
-		const allowedActions = allowed[scope.resource];
-		if (!allowedActions) throwAuthError("API_KEY_INVALID_SCOPE", `Unknown resource "${scope.resource}" in API key scopes. Allowed resources: ${Object.keys(allowed).join(", ")}`);
-		for (const action of scope.actions) if (action !== "*" && !allowedActions.includes(action)) throwAuthError("API_KEY_INVALID_SCOPE", `Unknown action "${action}" for resource "${scope.resource}". Allowed actions: ${allowedActions.join(", ")}`);
-	}
-}
-/**
 * Check whether a key is rate-limited based on its stored state.
 *
 * Uses the same token-bucket algorithm as sign-in rate limiting:
@@ -85,6 +62,7 @@ function validateScopes(requested, allowed) {
 *
 * @returns `{ limited: boolean; newState: { attemptsLeft, lastAttemptTime } }`
 */
+/** @internal */
 function checkKeyRateLimit(rateLimit, state) {
 	const now = Date.now();
 	if (!state) return {
@@ -114,5 +92,5 @@ function checkKeyRateLimit(rateLimit, state) {
 }
 
 //#endregion
-export { buildScopeChecker, checkKeyRateLimit, generateApiKey, hashApiKey, validateScopes };
+export { buildScopeChecker, checkKeyRateLimit, generateApiKey, hashApiKey };
 //# sourceMappingURL=keys.js.map

package/dist/component/server/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","names":[],"sources":["../../../src/server/keys.ts"],"sourcesContent":["/**\n * API Key crypto utilities.\n *\n * Uses `@oslojs/crypto` primitives for key generation and hashing:\n * - SHA-256 for hashing keys (API keys have high entropy, no need for bcrypt)\n * - Cryptographically secure random generation for key material\n *\n * @module\n */\n\nimport type { KeyScope, ScopeChecker } from \"./types\";\nimport { sha256, generateRandomString } from \"./utils\";\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst DEFAULT_KEY_PREFIX = \"sk_\";\nconst KEY_RANDOM_LENGTH = 32;\nconst KEY_RANDOM_ALPHABET =\n  \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\n\n/**\n * How many characters of the full key to store as the visible prefix.\n * Includes the prefix string (e.g. \"sk_\") plus a few random chars.\n */\nconst VISIBLE_PREFIX_EXTRA_CHARS = 4;\n\n// ============================================================================\n// Key generation\n// ============================================================================\n\n/**\n * Generate a new API key.\n *\n * Returns the raw key (to be shown once to the user) and metadata for storage.\n * The raw key is `{prefix}{32 random alphanumeric chars}`.\n *\n * @param prefix - Key prefix, defaults to \"sk_\"\n * @returns `{ raw, hashedKey, displayPrefix }`\n */\n/** @internal */\nexport async function generateApiKey(\n  prefix: string = DEFAULT_KEY_PREFIX,\n): Promise<{\n  /** The full raw key — show to user once, never store. */\n  raw: string;\n  /** SHA-256 hex hash of the raw key — store this. */\n  hashedKey: string;\n  /** Truncated prefix for display (e.g. \"sk_aBc1...\"). */\n  displayPrefix: string;\n}> {\n  const randomPart = generateRandomString(\n    KEY_RANDOM_LENGTH,\n    KEY_RANDOM_ALPHABET,\n  );\n  const raw = `${prefix}${randomPart}`;\n  const hashedKey = await sha256(raw);\n  const displayPrefix = `${raw.substring(0, prefix.length + VISIBLE_PREFIX_EXTRA_CHARS)}...`;\n\n  return { raw, hashedKey, displayPrefix };\n}\n\n/**\n * Hash a raw API key for lookup.\n *\n * Used during Bearer token verification to find the stored key record.\n */\n/** @internal */\nexport async function hashApiKey(rawKey: string): Promise<string> {\n  return sha256(rawKey);\n}\n\n// ============================================================================\n// Scope checker\n// ============================================================================\n\n/**\n * Build a `ScopeChecker` from an array of `KeyScope` entries.\n *\n * The checker provides a `.can(resource, action)` method that returns `true`\n * if any scope entry grants the requested permission.\n *\n * A wildcard action `\"*\"` grants all actions on that resource.\n * A wildcard resource `\"*\"` grants the action on all resources.\n */\n/** @internal */\nexport function buildScopeChecker(scopes: KeyScope[]): ScopeChecker {\n  return {\n    scopes,\n    can(resource: string, action: string): boolean {\n      return scopes.some(\n        (scope) =>\n          (scope.resource === resource || scope.resource === \"*\") &&\n          (scope.actions.includes(action) || scope.actions.includes(\"*\")),\n      );\n    },\n  };\n}\n\n// ============================================================================\n// Per-key rate limiting (token-bucket)\n// ============================================================================\n\n/**\n * Check whether a key is rate-limited based on its stored state.\n *\n * Uses the same token-bucket algorithm as sign-in rate limiting:\n * tokens refill linearly over the configured window.\n *\n * @returns `{ limited: boolean; newState: { attemptsLeft, lastAttemptTime } }`\n */\n/** @internal */\nexport function checkKeyRateLimit(\n  rateLimit: { maxRequests: number; windowMs: number },\n  state: { attemptsLeft: number; lastAttemptTime: number } | undefined,\n): {\n  limited: boolean;\n  newState: { attemptsLeft: number; lastAttemptTime: number };\n} {\n  const now = Date.now();\n\n  if (!state) {\n    // First request — create initial state with one token consumed.\n    return {\n      limited: false,\n      newState: {\n        attemptsLeft: rateLimit.maxRequests - 1,\n        lastAttemptTime: now,\n      },\n    };\n  }\n\n  const elapsed = now - state.lastAttemptTime;\n  const refillRate = rateLimit.maxRequests / rateLimit.windowMs;\n  const refilled = Math.min(\n    rateLimit.maxRequests,\n    state.attemptsLeft + elapsed * refillRate,\n  );\n\n  if (refilled < 1) {\n    return {\n      limited: true,\n      newState: {\n        attemptsLeft: refilled,\n        lastAttemptTime: now,\n      },\n    };\n  }\n\n  return {\n    limited: false,\n    newState: {\n      attemptsLeft: refilled - 1,\n      lastAttemptTime: now,\n    },\n  };\n}\n"],"mappings":";;;AAiBA,MAAM,qBAAqB;AAC3B,MAAM,oBAAoB;AAC1B,MAAM,sBACJ;;;;;AAMF,MAAM,6BAA6B;;;;;;;;;;;AAgBnC,eAAsB,eACpB,SAAiB,oBAQhB;CAKD,MAAM,MAAM,GAAG,SAJI,qBACjB,mBACA,oBACD;AAKD,QAAO;EAAE;EAAK,WAHI,MAAM,OAAO,IAAI;EAGV,eAFH,GAAG,IAAI,UAAU,GAAG,OAAO,SAAS,2BAA2B,CAAC;EAE9C;;;;;;;;AAS1C,eAAsB,WAAW,QAAiC;AAChE,QAAO,OAAO,OAAO;;;;;;;;;;;;AAiBvB,SAAgB,kBAAkB,QAAkC;AAClE,QAAO;EACL;EACA,IAAI,UAAkB,QAAyB;AAC7C,UAAO,OAAO,MACX,WACE,MAAM,aAAa,YAAY,MAAM,aAAa,SAClD,MAAM,QAAQ,SAAS,OAAO,IAAI,MAAM,QAAQ,SAAS,IAAI,EACjE;;EAEJ;;;;;;;;;;;AAgBH,SAAgB,kBACd,WACA,OAIA;CACA,MAAM,MAAM,KAAK,KAAK;AAEtB,KAAI,CAAC,MAEH,QAAO;EACL,SAAS;EACT,UAAU;GACR,cAAc,UAAU,cAAc;GACtC,iBAAiB;GAClB;EACF;CAGH,MAAM,UAAU,MAAM,MAAM;CAC5B,MAAM,aAAa,UAAU,cAAc,UAAU;CACrD,MAAM,WAAW,KAAK,IACpB,UAAU,aACV,MAAM,eAAe,UAAU,WAChC;AAED,KAAI,WAAW,EACb,QAAO;EACL,SAAS;EACT,UAAU;GACR,cAAc;GACd,iBAAiB;GAClB;EACF;AAGH,QAAO;EACL,SAAS;EACT,UAAU;GACR,cAAc,WAAW;GACzB,iBAAiB;GAClB;EACF"}

package/dist/component/server/limits.js

@@ -0,0 +1,61 @@
+import { AuthError } from "./authError.js";
+import { errorMessage } from "./utils.js";
+import { authDb } from "./db.js";
+import { Fx } from "@robelest/fx";
+
+//#region src/server/limits.ts
+const DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR = 10;
+/**
+* Check whether the given identifier is currently rate-limited.
+*/
+/** @internal */
+const isSignInRateLimited = (ctx, identifier, config) => getRateLimitState(ctx, identifier, config).pipe(Fx.map((state) => state !== null && state.attemptsLeft < 1));
+/**
+* Record a failed sign-in attempt for the given identifier.
+*
+* If a record exists, decrement; otherwise create.
+*/
+/** @internal */
+const recordFailedSignIn = (ctx, identifier, config) => getRateLimitState(ctx, identifier, config).pipe(Fx.chain((state) => state !== null ? Fx.from({
+	ok: () => authDb(ctx, config).rateLimits.patch(state.limit._id, {
+		attemptsLeft: state.attemptsLeft - 1,
+		lastAttemptTime: Date.now()
+	}),
+	err: (e) => new AuthError("INTERNAL_ERROR", `Failed to patch rate limit: ${errorMessage(e)}`)
+}) : Fx.from({
+	ok: () => authDb(ctx, config).rateLimits.create({
+		identifier,
+		attemptsLeft: (config.signIn?.maxFailedAttemptsPerHour ?? DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR) - 1,
+		lastAttemptTime: Date.now()
+	}),
+	err: (e) => new AuthError("INTERNAL_ERROR", `Failed to create rate limit: ${errorMessage(e)}`)
+})), Fx.map(() => void 0));
+/**
+* Reset the rate limit for the given identifier (e.g. after successful sign-in).
+*/
+/** @internal */
+const resetSignInRateLimit = (ctx, identifier, config) => getRateLimitState(ctx, identifier, config).pipe(Fx.chain((state) => state !== null ? Fx.from({
+	ok: () => authDb(ctx, config).rateLimits.delete(state.limit._id),
+	err: (e) => new AuthError("INTERNAL_ERROR", `Failed to delete rate limit: ${errorMessage(e)}`)
+}) : Fx.unit));
+const getRateLimitState = (ctx, identifier, config) => {
+	const now = Date.now();
+	const maxAttemptsPerHour = config.signIn?.maxFailedAttemptsPerHour ?? DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR;
+	return Fx.from({
+		ok: () => authDb(ctx, config).rateLimits.get(identifier),
+		err: (e) => new AuthError("INTERNAL_ERROR", `Failed to get rate limit: ${errorMessage(e)}`)
+	}).pipe(Fx.map((raw) => {
+		const limit = raw;
+		if (limit === null) return null;
+		const elapsed = now - limit.lastAttemptTime;
+		const maxAttemptsPerMs = maxAttemptsPerHour / (3600 * 1e3);
+		return {
+			limit,
+			attemptsLeft: Math.min(maxAttemptsPerHour, limit.attemptsLeft + elapsed * maxAttemptsPerMs)
+		};
+	}));
+};
+
+//#endregion
+export { isSignInRateLimited, recordFailedSignIn, resetSignInRateLimit };
+//# sourceMappingURL=limits.js.map

package/dist/component/server/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","names":[],"sources":["../../../src/server/limits.ts"],"sourcesContent":["import { Fx } from \"@robelest/fx\";\n\nimport { authDb } from \"./db\";\nimport { AuthError } from \"./authError\";\nimport { Doc, MutationCtx } from \"./types\";\nimport { ConvexAuthConfig } from \"./types\";\nimport { errorMessage } from \"./utils\";\n\nconst DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR = 10;\n\n/**\n * Check whether the given identifier is currently rate-limited.\n */\n/** @internal */\nexport const isSignInRateLimited = (\n  ctx: MutationCtx,\n  identifier: string,\n  config: ConvexAuthConfig,\n): Fx<boolean, AuthError> =>\n  getRateLimitState(ctx, identifier, config).pipe(\n    Fx.map((state) => state !== null && state.attemptsLeft < 1),\n  );\n\n/**\n * Record a failed sign-in attempt for the given identifier.\n *\n * If a record exists, decrement; otherwise create.\n */\n/** @internal */\nexport const recordFailedSignIn = (\n  ctx: MutationCtx,\n  identifier: string,\n  config: ConvexAuthConfig,\n): Fx<void, AuthError> =>\n  getRateLimitState(ctx, identifier, config).pipe(\n    Fx.chain((state) =>\n      state !== null\n        ? Fx.from({\n            ok: () =>\n              authDb(ctx, config).rateLimits.patch(state.limit._id, {\n                attemptsLeft: state.attemptsLeft - 1,\n                lastAttemptTime: Date.now(),\n              }),\n            err: (e) =>\n              new AuthError(\n                \"INTERNAL_ERROR\",\n                `Failed to patch rate limit: ${errorMessage(e)}`,\n              ),\n          })\n        : Fx.from({\n            ok: () =>\n              authDb(ctx, config).rateLimits.create({\n                identifier,\n                attemptsLeft:\n                  (config.signIn?.maxFailedAttemptsPerHour ??\n                    DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR) - 1,\n                lastAttemptTime: Date.now(),\n              }),\n            err: (e) =>\n              new AuthError(\n                \"INTERNAL_ERROR\",\n                `Failed to create rate limit: ${errorMessage(e)}`,\n              ),\n          }),\n    ),\n    Fx.map(() => undefined),\n  );\n\n/**\n * Reset the rate limit for the given identifier (e.g. after successful sign-in).\n */\n/** @internal */\nexport const resetSignInRateLimit = (\n  ctx: MutationCtx,\n  identifier: string,\n  config: ConvexAuthConfig,\n): Fx<void, AuthError> =>\n  getRateLimitState(ctx, identifier, config).pipe(\n    Fx.chain((state) =>\n      state !== null\n        ? Fx.from({\n            ok: () => authDb(ctx, config).rateLimits.delete(state.limit._id),\n            err: (e) =>\n              new AuthError(\n                \"INTERNAL_ERROR\",\n                `Failed to delete rate limit: ${errorMessage(e)}`,\n              ),\n          })\n        : Fx.unit,\n    ),\n  );\n\n// ---------------------------------------------------------------------------\n// Internal\n// ---------------------------------------------------------------------------\n\ntype RateLimitState = {\n  limit: Doc<\"RateLimit\"> & { attemptsLeft: number; lastAttemptTime: number };\n  attemptsLeft: number;\n} | null;\n\nconst getRateLimitState = (\n  ctx: MutationCtx,\n  identifier: string,\n  config: ConvexAuthConfig,\n): Fx<RateLimitState, AuthError> => {\n  const now = Date.now();\n  const maxAttemptsPerHour =\n    config.signIn?.maxFailedAttemptsPerHour ??\n    DEFAULT_MAX_SIGN_IN_ATTEMPTS_PER_HOUR;\n\n  return Fx.from({\n    ok: () => authDb(ctx, config).rateLimits.get(identifier),\n    err: (e) =>\n      new AuthError(\n        \"INTERNAL_ERROR\",\n        `Failed to get rate limit: ${errorMessage(e)}`,\n      ),\n  }).pipe(\n    Fx.map((raw) => {\n      const limit = raw as\n        | (Doc<\"RateLimit\"> & { attemptsLeft: number; lastAttemptTime: number })\n        | null;\n      if (limit === null) return null;\n      const elapsed = now - limit.lastAttemptTime;\n      const maxAttemptsPerMs = maxAttemptsPerHour / (60 * 60 * 1000);\n      const attemptsLeft = Math.min(\n        maxAttemptsPerHour,\n        limit.attemptsLeft + elapsed * maxAttemptsPerMs,\n      );\n      return { limit, attemptsLeft };\n    }),\n  );\n};\n"],"mappings":";;;;;;AAQA,MAAM,wCAAwC;;;;;AAM9C,MAAa,uBACX,KACA,YACA,WAEA,kBAAkB,KAAK,YAAY,OAAO,CAAC,KACzC,GAAG,KAAK,UAAU,UAAU,QAAQ,MAAM,eAAe,EAAE,CAC5D;;;;;;;AAQH,MAAa,sBACX,KACA,YACA,WAEA,kBAAkB,KAAK,YAAY,OAAO,CAAC,KACzC,GAAG,OAAO,UACR,UAAU,OACN,GAAG,KAAK;CACN,UACE,OAAO,KAAK,OAAO,CAAC,WAAW,MAAM,MAAM,MAAM,KAAK;EACpD,cAAc,MAAM,eAAe;EACnC,iBAAiB,KAAK,KAAK;EAC5B,CAAC;CACJ,MAAM,MACJ,IAAI,UACF,kBACA,+BAA+B,aAAa,EAAE,GAC/C;CACJ,CAAC,GACF,GAAG,KAAK;CACN,UACE,OAAO,KAAK,OAAO,CAAC,WAAW,OAAO;EACpC;EACA,eACG,OAAO,QAAQ,4BACd,yCAAyC;EAC7C,iBAAiB,KAAK,KAAK;EAC5B,CAAC;CACJ,MAAM,MACJ,IAAI,UACF,kBACA,gCAAgC,aAAa,EAAE,GAChD;CACJ,CAAC,CACP,EACD,GAAG,UAAU,OAAU,CACxB;;;;;AAMH,MAAa,wBACX,KACA,YACA,WAEA,kBAAkB,KAAK,YAAY,OAAO,CAAC,KACzC,GAAG,OAAO,UACR,UAAU,OACN,GAAG,KAAK;CACN,UAAU,OAAO,KAAK,OAAO,CAAC,WAAW,OAAO,MAAM,MAAM,IAAI;CAChE,MAAM,MACJ,IAAI,UACF,kBACA,gCAAgC,aAAa,EAAE,GAChD;CACJ,CAAC,GACF,GAAG,KACR,CACF;AAWH,MAAM,qBACJ,KACA,YACA,WACkC;CAClC,MAAM,MAAM,KAAK,KAAK;CACtB,MAAM,qBACJ,OAAO,QAAQ,4BACf;AAEF,QAAO,GAAG,KAAK;EACb,UAAU,OAAO,KAAK,OAAO,CAAC,WAAW,IAAI,WAAW;EACxD,MAAM,MACJ,IAAI,UACF,kBACA,6BAA6B,aAAa,EAAE,GAC7C;EACJ,CAAC,CAAC,KACD,GAAG,KAAK,QAAQ;EACd,MAAM,QAAQ;AAGd,MAAI,UAAU,KAAM,QAAO;EAC3B,MAAM,UAAU,MAAM,MAAM;EAC5B,MAAM,mBAAmB,sBAAsB,OAAU;AAKzD,SAAO;GAAE;GAAO,cAJK,KAAK,IACxB,oBACA,MAAM,eAAe,UAAU,iBAChC;GAC6B;GAC9B,CACH"}

package/dist/component/server/mutations/account.js

@@ -0,0 +1,44 @@
+import { AuthError } from "../authError.js";
+import { LOG_LEVELS, logWithLevel, maybeRedact } from "../utils.js";
+import { authDb } from "../db.js";
+import { hash } from "../crypto.js";
+import { AUTH_STORE_REF } from "./store/refs.js";
+import { v } from "convex/values";
+import { Fx } from "@robelest/fx";
+
+//#region src/server/mutations/account.ts
+const modifyAccountArgs = v.object({
+	provider: v.string(),
+	account: v.object({
+		id: v.string(),
+		secret: v.string()
+	})
+});
+function modifyAccountImpl(ctx, args, getProviderOrThrow, config) {
+	const { provider, account } = args;
+	const db = authDb(ctx, config);
+	logWithLevel(LOG_LEVELS.DEBUG, "modifyAccountImpl args:", {
+		provider,
+		account: {
+			id: account.id,
+			secret: maybeRedact(account.secret ?? "")
+		}
+	});
+	return Fx.from({
+		ok: () => db.accounts.get(provider, account.id),
+		err: () => new AuthError("ACCOUNT_NOT_FOUND", `Cannot modify account with ID ${account.id} because it does not exist`)
+	}).pipe(Fx.chain((doc) => doc === null ? Fx.fail(new AuthError("ACCOUNT_NOT_FOUND", `Cannot modify account with ID ${account.id} because it does not exist`)) : Fx.succeed(doc)), Fx.chain((existingAccount) => hash(getProviderOrThrow(provider), account.secret).pipe(Fx.chain((hashedSecret) => Fx.from({
+		ok: () => db.accounts.patch(existingAccount._id, { secret: hashedSecret }),
+		err: () => new AuthError("INTERNAL_ERROR", "Failed to patch account")
+	})))), Fx.map(() => void 0));
+}
+const callModifyAccount = async (ctx, args) => {
+	return ctx.runMutation(AUTH_STORE_REF, { args: {
+		type: "modifyAccount",
+		...args
+	} });
+};
+
+//#endregion
+export { callModifyAccount, modifyAccountArgs, modifyAccountImpl };
+//# sourceMappingURL=account.js.map