@meistrari/auth-core 1.20.0 → 1.21.0

package/dist/index.mjs

@@ -2,13 +2,75 @@ import { decodeJwt, createRemoteJWKSet, jwtVerify } from 'jose';
 import { apiKeyClient } from '@better-auth/api-key/client';
 import { ssoClient } from '@better-auth/sso/client';
 import { createAuthClient } from 'better-auth/client';
-import { organizationClient, inferOrgAdditionalFields, twoFactorClient, jwtClient, adminClient, inferAdditionalFields } from 'better-auth/client/plugins';
+import { organizationClient, inferOrgAdditionalFields, twoFactorClient, jwtClient, adminClient, inferAdditionalFields, emailOTPClient } from 'better-auth/client/plugins';
 import { createAccessControl } from 'better-auth/plugins/access';
 import { defaultStatements } from 'better-auth/plugins/organization/access';
-import z$1, { z } from 'zod';
+import z, { z as z$1 } from 'zod';
 export { APIError } from 'better-auth';
 
-const version = "1.20.0";
+const version = "1.21.0";
+
+function parsedEnumValues(schema) {
+  return Object.fromEntries(
+    Object.entries(schema.enum).map(([key, value]) => [
+      key,
+      schema.parse(value)
+    ])
+  );
+}
+
+const AMRBrand = Symbol("amr");
+const AALBrand = Symbol("aal");
+const ACRBrand = Symbol("acr");
+const AuthMethodBrand = Symbol("authMethod");
+const AMR = z.enum({
+  Pwd: "pwd",
+  Otp: "otp",
+  Oauth: "oauth",
+  Sso: "sso",
+  Saml: "saml"
+}).brand(AMRBrand);
+const AAL = z.enum({
+  Aal1: "aal1",
+  Aal2: "aal2",
+  Aal3: "aal3"
+}).brand(AALBrand);
+const ACR = z.enum({
+  Unspecified: "urn:tela:auth:unspecified"
+}).brand(ACRBrand);
+const AuthMethod = z.enum({
+  Password: "password",
+  EmailOTP: "email_otp",
+  OAuth: "oauth",
+  SAML: "saml",
+  Unknown: "unknown"
+}).brand(AuthMethodBrand);
+const AMRs = parsedEnumValues(AMR);
+const AALs = parsedEnumValues(AAL);
+const ACRs = parsedEnumValues(ACR);
+const AuthMethods = parsedEnumValues(AuthMethod);
+const assuranceFields = {
+  authMethod: {
+    type: "string",
+    required: true
+  },
+  amr: {
+    type: "json",
+    required: true
+  },
+  aal: {
+    type: "string",
+    required: true
+  },
+  acr: {
+    type: "string",
+    required: true
+  },
+  assuredAt: {
+    type: "date",
+    required: true
+  }
+};
 
 const statements = {
   ...defaultStatements,
@@ -68,21 +130,36 @@ const invitationAdditionalFields = {
     required: false
   }
 };
-const JWTPayloadUser = z.object({
-  id: z.string(),
-  name: z.string(),
-  image: z.string().nullable().optional(),
-  role: z.string().nullable()
+const JWTPayloadUser = z$1.object({
+  id: z$1.string(),
+  name: z$1.string(),
+  image: z$1.string().nullable().optional(),
+  role: z$1.string().nullable()
 });
-const JWTPayloadWorkspace = z.object({
-  id: z.string(),
-  title: z.string()
+const JWTPayloadWorkspace = z$1.object({
+  id: z$1.string(),
+  title: z$1.string()
 });
-const JWTPayload = z.object({
-  email: z.string(),
+const JWTPayloadAssurance = z$1.object({
+  authMethod: AuthMethod,
+  amr: AMR.array(),
+  aal: AAL,
+  acr: ACR,
+  assuredAt: z$1.string().datetime()
+});
+const DEFAULT_JWT_ASSURANCE = {
+  authMethod: AuthMethods.Unknown,
+  amr: [],
+  aal: AALs.Aal1,
+  acr: ACRs.Unspecified,
+  assuredAt: (/* @__PURE__ */ new Date(0)).toISOString()
+};
+const JWTPayload = z$1.object({
+  email: z$1.string(),
   user: JWTPayloadUser,
   workspace: JWTPayloadWorkspace,
-  sessionKey: z.string()
+  sessionKey: z$1.string(),
+  assurance: JWTPayloadAssurance.optional().default(DEFAULT_JWT_ASSURANCE)
 });
 
 const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
@@ -227,6 +304,34 @@ function applicationsPluginClient() {
   };
 }
 
+function sessionAssurancePluginClient() {
+  return {
+    id: "session-assurance",
+    getActions: ($fetch) => ({
+      sessionAssurance: {
+        getSessionAssurance: async () => {
+          return await $fetch("/session-assurance");
+        },
+        stepUpWithPassword: async (body) => {
+          return await $fetch("/session-assurance/step-up/password", { method: "POST", body });
+        },
+        sendOtp: async () => {
+          return await $fetch("/session-assurance/step-up/otp/send", { method: "POST" });
+        },
+        verifyOtp: async (body) => {
+          return await $fetch("/session-assurance/step-up/otp/verify", { method: "POST", body });
+        },
+        beginOAuthStepUp: async (body) => {
+          return await $fetch("/session-assurance/step-up/oauth/begin", { method: "POST", body });
+        },
+        completeOAuthStepUp: async (body) => {
+          return await $fetch("/session-assurance/step-up/oauth/complete", { method: "POST", body });
+        }
+      }
+    })
+  };
+}
+
 function customEndpointsPluginClient() {
   return {
     id: "custom-endpoints",
@@ -263,7 +368,9 @@ function createAPIClient(apiUrl, fetchOptions = {}) {
       inferAdditionalFields({
         user: userAdditionalFields
       }),
-      applicationsPluginClient()
+      applicationsPluginClient(),
+      sessionAssurancePluginClient(),
+      emailOTPClient()
     ],
     fetchOptions: {
       ...fetchOptions,
@@ -308,6 +415,20 @@ class AuthorizationFlowError extends ApplicationError {
     this.code = "AUTHORIZATION_FLOW_ERROR";
   }
 }
+class ApplicationSessionAssuranceError extends ApplicationError {
+  payload;
+  currentAssurance;
+  requiredAssurance;
+  validStepUps;
+  constructor(payload = null, options) {
+    super("Session assurance does not meet application policy. Start a new device authorization flow.", options);
+    this.code = "APPLICATION_SESSION_ASSURANCE_NOT_MET";
+    this.payload = payload;
+    this.currentAssurance = payload?.currentAssurance ?? null;
+    this.requiredAssurance = payload?.requiredAssurance ?? null;
+    this.validStepUps = payload?.validStepUps ?? [];
+  }
+}
 class UserNotLoggedInError extends ApplicationError {
   constructor(message, options) {
     super(message, options);
@@ -345,6 +466,174 @@ class DeviceTransientServerError extends ApplicationError {
   }
 }
 
+const OAuthStepUpProvider = z.enum(["google", "microsoft"]);
+const StepUpOption = z.discriminatedUnion("method", [
+  z.object({ method: z.literal(AMRs.Pwd) }),
+  z.object({ method: z.literal(AMRs.Otp) }),
+  z.object({
+    method: z.literal(AMRs.Oauth),
+    providers: OAuthStepUpProvider.array().min(1)
+  })
+]);
+const SessionAssurancePolicy = z.object({
+  minAal: AAL,
+  acceptedAmr: AMR.array().min(1)
+});
+const SENSITIVE_ACTION_ASSURANCE_POLICY = {
+  minAal: AALs.Aal2,
+  acceptedAmr: [AMRs.Pwd, AMRs.Otp, AMRs.Oauth]
+};
+function getAalRank(aal) {
+  switch (aal) {
+    case AALs.Aal3:
+      return 3;
+    case AALs.Aal2:
+      return 2;
+    case AALs.Aal1:
+      return 1;
+    default:
+      return 0;
+  }
+}
+function maxAal(left, right) {
+  return getAalRank(left) >= getAalRank(right) ? left : right;
+}
+function isAssuranceSufficientForPolicy(assurance, policy) {
+  if (!assurance) {
+    return false;
+  }
+  if (getAalRank(assurance.aal) < getAalRank(policy.minAal)) {
+    return false;
+  }
+  if (!assurance.amr.length) {
+    return false;
+  }
+  return assurance.amr.some((amr) => policy.acceptedAmr.includes(amr));
+}
+function canStepUpWithAmr(assurance, amr) {
+  return !assurance.amr.includes(amr);
+}
+function mergeStepUpAssurance(assurance, amr, now = /* @__PURE__ */ new Date()) {
+  if (!canStepUpWithAmr(assurance, amr)) {
+    throw new Error(`AMR ${amr} is already present on the session`);
+  }
+  return {
+    ...assurance,
+    amr: [...assurance.amr, amr],
+    aal: maxAal(assurance.aal, AALs.Aal2),
+    assuredAt: now.toISOString()
+  };
+}
+
+const SessionAssuranceRequiredCode = z.enum([
+  "session_assurance_required",
+  "application_session_assurance_not_met"
+]);
+const SessionAssurancePayloadAssurance = z.preprocess((value) => {
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  const assurance = value;
+  if (!(assurance.assuredAt instanceof Date)) {
+    return value;
+  }
+  return {
+    ...assurance,
+    assuredAt: assurance.assuredAt.toISOString()
+  };
+}, JWTPayloadAssurance);
+const SessionAssuranceRequiredPayload = z.object({
+  code: SessionAssuranceRequiredCode,
+  currentAssurance: SessionAssurancePayloadAssurance,
+  requiredAssurance: SessionAssurancePolicy,
+  validStepUps: StepUpOption.array()
+});
+function getCandidatePayloads(error) {
+  const candidate = error;
+  return [
+    candidate.details,
+    candidate.error?.details,
+    candidate.data?.details,
+    candidate.body?.details,
+    candidate.payload,
+    error
+  ].filter((payload) => payload !== void 0);
+}
+function toSdkCode(code) {
+  return code.toUpperCase();
+}
+function parseSessionAssuranceRequiredPayload(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    for (const payload of getCandidatePayloads(current)) {
+      const result = SessionAssuranceRequiredPayload.safeParse(payload);
+      if (result.success) {
+        return result.data;
+      }
+    }
+    current = current.cause;
+  }
+  return null;
+}
+class SessionAssuranceRequiredError extends BaseError {
+  payload;
+  currentAssurance;
+  requiredAssurance;
+  validStepUps;
+  constructor(payload, options) {
+    super(toSdkCode(payload.code), "Session assurance is required for this action", options);
+    this.name = "SessionAssuranceRequiredError";
+    this.payload = payload;
+    this.currentAssurance = payload.currentAssurance;
+    this.requiredAssurance = payload.requiredAssurance;
+    this.validStepUps = payload.validStepUps;
+  }
+}
+
+const DEFAULT_SESSION_ASSURANCE_CONFIG = {
+  acceptedAmr: [
+    AMRs.Pwd,
+    AMRs.Oauth,
+    AMRs.Saml
+  ],
+  minAal: AALs.Aal1
+};
+const DEFAULT_APPLICATION_CONFIG = {
+  version: 1,
+  sessionAssurance: DEFAULT_SESSION_ASSURANCE_CONFIG
+};
+const ApplicationSessionAssuranceConfig = z.object({
+  acceptedAmr: AMR.array().optional().default(DEFAULT_SESSION_ASSURANCE_CONFIG.acceptedAmr),
+  minAal: AAL.refine(
+    (aal) => aal !== AALs.Aal3,
+    "Application session assurance currently supports aal1 and aal2 policies"
+  ).optional().default(DEFAULT_SESSION_ASSURANCE_CONFIG.minAal)
+});
+const ApplicationConfig = z.object({
+  version: z.literal(1),
+  sessionAssurance: ApplicationSessionAssuranceConfig.optional().default(DEFAULT_SESSION_ASSURANCE_CONFIG)
+});
+
+function allowsDefaultAmrPolicy(config) {
+  const acceptedAmr = new Set(config.sessionAssurance.acceptedAmr);
+  const defaultAcceptedAmr = DEFAULT_SESSION_ASSURANCE_CONFIG.acceptedAmr;
+  return config.sessionAssurance.minAal === DEFAULT_SESSION_ASSURANCE_CONFIG.minAal && defaultAcceptedAmr.every((amr) => acceptedAmr.has(amr));
+}
+function isSessionAssuranceSufficient(sessionAssurance, config = DEFAULT_APPLICATION_CONFIG) {
+  if (!sessionAssurance) {
+    return false;
+  }
+  if (!sessionAssurance.amr.length && allowsDefaultAmrPolicy(config)) {
+    return getAalRank(sessionAssurance.aal) >= getAalRank(config.sessionAssurance.minAal);
+  }
+  if (!isAssuranceSufficientForPolicy(sessionAssurance, config.sessionAssurance)) {
+    return false;
+  }
+  return true;
+}
+
 function parseErrorCode(error) {
   if (!error || typeof error !== "object") {
     return null;
@@ -376,6 +665,9 @@ function throwDeviceGrantError(error) {
   if (code === "temporarily_unavailable") {
     throw new DeviceTransientServerError({ cause: error });
   }
+  if (code === "application_session_assurance_not_met") {
+    throw new ApplicationSessionAssuranceError(parseSessionAssuranceRequiredPayload(error), { cause: error });
+  }
   throw new ApplicationError(parseErrorMessage(error), { cause: error });
 }
 class ApplicationService {
@@ -425,11 +717,26 @@ class ApplicationService {
    * @param organizationId - The organization ID to start the authorization flow for
    */
   async startAuthorizationFlow(applicationId, redirectUri, codeChallenge, organizationId) {
-    const response = await this.client.applications.startAuthorizationFlow(applicationId, redirectUri, codeChallenge, organizationId);
-    if (!response.data) {
-      throw new Error("No data returned from the API", { cause: response.error });
+    try {
+      const response = await this.client.applications.startAuthorizationFlow(applicationId, redirectUri, codeChallenge, organizationId);
+      if (!response.data) {
+        const payload = parseSessionAssuranceRequiredPayload(response.error);
+        if (payload) {
+          throw new SessionAssuranceRequiredError(payload, { cause: response.error });
+        }
+        throw new Error("No data returned from the API", { cause: response.error });
+      }
+      return response.data;
+    } catch (error) {
+      if (error instanceof SessionAssuranceRequiredError) {
+        throw error;
+      }
+      const payload = parseSessionAssuranceRequiredPayload(error);
+      if (payload) {
+        throw new SessionAssuranceRequiredError(payload, { cause: error });
+      }
+      throw error;
     }
-    return response.data;
   }
   /**
    * Starts a device authorization flow (RFC 8628).
@@ -505,6 +812,7 @@ class ApplicationService {
    * @throws {DeviceAccessDeniedError} The user denied the request
    * @throws {DeviceCodeExpiredError} The device code has expired
    * @throws {DeviceTransientServerError} Transient server error — safe to retry
+   * @throws {ApplicationSessionAssuranceError} Assurance policy changed or is no longer met — start a new flow
    */
   async exchangeDeviceCodeForTokens(deviceCode) {
     try {
@@ -960,14 +1268,20 @@ class SessionService {
    * @param options - Email/password sign-in configuration
    * @param options.email - User's email address
    * @param options.password - User's password
+   * @param options.callbackURL - URL to redirect to after successful authentication
    */
   async signInWithEmailAndPassword({
     email,
-    password
+    password,
+    callbackURL
   }) {
+    if (!isValidUrl(callbackURL)) {
+      throw new InvalidCallbackURL(`Invalid callback URL: ${callbackURL}`);
+    }
     await this.client.signIn.email({
       email,
-      password
+      password,
+      callbackURL
     });
   }
   /**
@@ -1097,22 +1411,123 @@ class ApiKeyService {
   }
 }
 
-const ApiKeyMetadata = z$1.object({
-  user: z$1.object({
-    id: z$1.string(),
-    email: z$1.string()
+function getApplicationId(options) {
+  if (!options?.applicationId) {
+    throw new Error("applicationId is required");
+  }
+  return options.applicationId;
+}
+class EmailOTPService {
+  /**
+   * Creates a new EmailOTPService instance.
+   *
+   * @param client - The API client for making email OTP requests
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Sends a sign-in verification OTP to an email address.
+   *
+   * @param email - Email address that should receive the OTP
+   * @param options - Request configuration
+   * @returns The underlying email OTP API response
+   */
+  async sendVerificationOTP(email, options) {
+    const applicationId = getApplicationId(options);
+    return await this.client.emailOtp.sendVerificationOtp({ email, type: "sign-in" }, { query: { applicationId } });
+  }
+  /**
+   * Completes email OTP sign-in with a one-time passcode.
+   *
+   * @param email - Email address that received the OTP
+   * @param otp - One-time passcode from the sign-in email
+   * @param options - Request configuration
+   * @returns The underlying email OTP sign-in API response
+   */
+  async signIn(email, otp, options) {
+    const applicationId = getApplicationId(options);
+    return await this.client.signIn.emailOtp({ email, otp }, { query: { applicationId } });
+  }
+}
+
+const ClientJWTPayloadAssurance = JWTPayloadAssurance.extend({
+  assuredAt: z.date()
+});
+const SessionAssuranceResponse = z.object({
+  assurance: ClientJWTPayloadAssurance,
+  validStepUps: StepUpOption.array()
+});
+const OAuthBeginStepUpResponse = z.object({
+  stepUpToken: z.string(),
+  callbackURL: z.string()
+});
+const OAuthCompleteStepUpResponse = SessionAssuranceResponse.extend({
+  returnPath: z.string()
+});
+const SendOtpResponse = z.object({
+  success: z.boolean()
+});
+function isBetterAuthResponse(response) {
+  return typeof response === "object" && response !== null && "data" in response && "error" in response;
+}
+function getResponseData(response) {
+  if (!isBetterAuthResponse(response)) {
+    return response;
+  }
+  if (response.data !== null && response.data !== void 0) {
+    return response.data;
+  }
+  throw new Error("No data returned from the API", { cause: response.error });
+}
+function parseResponse(schema, response) {
+  return schema.parse(getResponseData(response));
+}
+class SessionAssuranceService {
+  constructor(client) {
+    this.client = client;
+  }
+  async get() {
+    return parseResponse(SessionAssuranceResponse, await this.client.sessionAssurance.getSessionAssurance());
+  }
+  async stepUpWithPassword(password) {
+    return parseResponse(SessionAssuranceResponse, await this.client.sessionAssurance.stepUpWithPassword({ password }));
+  }
+  async sendOtp() {
+    return parseResponse(SendOtpResponse, await this.client.sessionAssurance.sendOtp());
+  }
+  async verifyOtp(otp) {
+    return parseResponse(SessionAssuranceResponse, await this.client.sessionAssurance.verifyOtp({ otp }));
+  }
+  async beginOAuthStepUp(params) {
+    return parseResponse(OAuthBeginStepUpResponse, await this.client.sessionAssurance.beginOAuthStepUp(params));
+  }
+  async completeOAuthStepUp(stepUpToken) {
+    return parseResponse(OAuthCompleteStepUpResponse, await this.client.sessionAssurance.completeOAuthStepUp({ stepUpToken }));
+  }
+}
+
+const ApiKeyMetadata = z.object({
+  user: z.object({
+    id: z.string(),
+    email: z.string()
   }),
-  workspace: z$1.object({
-    id: z$1.string(),
-    title: z$1.string()
+  workspace: z.object({
+    id: z.string(),
+    title: z.string()
   }),
-  application: z$1.object({
-    id: z$1.string(),
-    name: z$1.string()
+  application: z.object({
+    id: z.string(),
+    name: z.string()
   }).optional().nullable()
 });
 
 class AuthClient {
+  /**
+   * Configured Better Auth client used by the public service wrappers.
+   *
+   * @internal
+   */
   client;
   /**
    * Session management service for authentication operations
@@ -1130,6 +1545,14 @@ class AuthClient {
    * API key management service for API key operations
    */
   apiKey;
+  /**
+   * Email OTP service for passwordless sign-in operations
+   */
+  emailOtp;
+  /**
+   * Session assurance service for step-up operations
+   */
+  sessionAssurance;
   /**
    * Creates a new AuthClient instance.
    *
@@ -1142,6 +1565,8 @@ class AuthClient {
     this.organization = new OrganizationService(this.client);
     this.application = new ApplicationService(this.client);
     this.apiKey = new ApiKeyService(this.client);
+    this.emailOtp = new EmailOTPService(this.client);
+    this.sessionAssurance = new SessionAssuranceService(this.client);
   }
 }
 
@@ -1178,4 +1603,4 @@ function extractTokenPayload(token) {
   return payload;
 }
 
-export { ApiKeyMetadata, ApplicationError, AuthClient, AuthorizationFlowError, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadUser, JWTPayloadWorkspace, RefreshTokenExpiredError, Roles, UserNotLoggedInError, ac, extractTokenPayload, invitationAdditionalFields, isTokenExpired, memberAdditionalFields, organizationAdditionalFields, rolesAccessControl, userAdditionalFields, validateToken };
+export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-core",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "type": "module",
   "exports": {
     ".": {