@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/models/auth-constants.backend.ts

@@ -0,0 +1,141 @@
+/**
+ * Centralized constants for the auth system.
+ * Single source of truth for Redis key prefixes, operation names, token reasons, and auth sources.
+ */
+
+// ─── Redis Key Prefixes ──────────────────────────────────────────────
+
+export const AUTH_REDIS_KEYS = {
+  // Rate limiting — identify
+  IDENTIFY_IP: 'auth:identify:ip:',
+  IDENTIFY_EMAIL: 'auth:identify:email:',
+
+  // Rate limiting — password auth
+  PASSWORD_EMAIL: 'auth:password:',
+  PASSWORD_IP: 'auth:password:ip:',
+
+  // Rate limiting — registration (controller-level)
+  REGISTER_IP: 'auth:register:ip:',
+  REGISTER_EMAIL: 'auth:register:email:',
+  REGISTER_DOMAIN: 'auth:register:domain:',
+  INVITATION_ACCEPT_IP: 'auth:invitation:accept:ip:',
+  INVITATION_REJECT_IP: 'auth:invitation:reject:ip:',
+
+  // Rate limiting — password reset
+  RESET_EMAIL: 'auth:reset:email:',
+  RESET_IP: 'auth:reset:ip:',
+
+  // Rate limiting — email verification resend
+  RESEND_VERIF_EMAIL: 'auth:resend-verif:email:',
+  RESEND_VERIF_IP: 'auth:resend-verif:ip:',
+
+  // Rate limiting — MFA enrollment (W2.12)
+  TOTP_SETUP: 'auth:totp:setup:',
+  PASSKEY_REGISTER: 'auth:passkey:reg:',
+
+  // Rate limiting — native SDK token exchange
+  NATIVE_EXCHANGE_IP: 'auth:native-exchange:ip:',
+
+  // Rate limiting — one-off session (W7.3b)
+  ONE_OFF_CREATE_IP: 'auth:one-off:create:ip:',
+  ONE_OFF_EXCHANGE_IP: 'auth:one-off:exchange:ip:',
+  ONE_OFF_EXCHANGE_HOUR_IP: 'auth:one-off:exchange:hour:ip:',
+
+  // Rate limiting — anonymous session init (W7.3a)
+  ANONYMOUS_SESSION_INIT_IP: 'auth:anon-session:init:ip:',
+  ANONYMOUS_SESSION_INIT_HOUR_IP: 'auth:anon-session:init:hour:ip:',
+
+  // Rate limiting — magic link
+  MAGIC_LINK_MIN: 'magic_link:ratelimit:',
+  MAGIC_LINK_SEND_IP: 'magic_link:send:ip:',
+  MAGIC_LINK_VERIFY_IP: 'magic_link:verify:ip:',
+
+  // Rate limiting — SMS OTP
+  SMS_OTP_BURST: 'sms_otp:ratelimit:',
+  SMS_OTP_SEND_IP: 'sms_otp:send:ip:',
+
+  // Rate limiting — email OTP
+  EMAIL_OTP: 'otp:ratelimit:',
+
+  // Rate limiting — SAML
+  SAML_LOGIN_IP: 'saml:login:ip:',
+  SAML_ACS_IP: 'saml:acs:ip:',
+  SAML_SLO_IP: 'saml:slo:ip:',
+
+  // Rate limiting — phone verification
+  PHONE_VERIFY_SEND: 'phone_verify:send:',
+  PHONE_VERIFY_SEND_IP: 'phone_verify:send:ip:',
+  PHONE_VERIFY_CONFIRM: 'phone_verify:confirm:',
+
+  // Rate limiting — org onboarding (W5.7)
+  ORG_ONBOARDING_IP: 'auth:org-onboarding:ip:',
+
+  // Lockout
+  GLOBAL_LOCKOUT: 'auth_attempts:',
+
+  // Session
+  SESSION: 'auth:session:',
+
+  // Token management
+  TOKEN_INVALID_BEFORE: 'token_invalid_before:',
+  REFRESH_BLACKLIST: 'refresh_blacklist:',
+  ACTIVE_REFRESH_JTIS: 'active_refresh_jtis:',
+
+  // TOTP replay prevention
+  TOTP_USED: 'totp:used:',
+
+  // SAML
+  SAML_CERT_EXPIRY_WARNED: 'saml:cert-expiry-warned:',
+  SAML_REPLAY: 'saml:replay:',
+
+  // SSO grace
+  SSO_GRACE_LOGINS: 'sso_grace_logins:',
+} as const;
+
+// ─── Refresh Token Blacklist Reasons ─────────────────────────────────
+
+export enum RefreshTokenBlacklistReason {
+  ROTATED = 'rotated',
+  REVOKED = 'revoked',
+  EVICTED = 'evicted',
+}
+
+// ─── Auth Operations (error context) ─────────────────────────────────
+
+export const AUTH_OPERATION = {
+  PASSWORD_CHANGE: 'password_change',
+  PASSWORD_SET: 'password_set',
+  TOTP_DISABLE: 'totp_disable',
+  GET_MY_METHODS: 'get_my_methods',
+  GET_IDENTITY_LINKS: 'get_identity_links',
+  UNLINK_IDENTITY_LINK: 'unlink_identity_link',
+  REAUTH: 'reauth',
+  PASSKEY_REGISTER_OPTIONS: 'passkey_register_options',
+  PASSKEY_REGISTER_VERIFY: 'passkey_register_verify',
+  PASSKEY_AUTH_OPTIONS: 'passkey_auth_options',
+  PASSKEY_AUTH_VERIFY: 'passkey_auth_verify',
+  PASSKEY_LIST: 'passkey_list',
+  PASSKEY_REMOVE: 'passkey_remove',
+  PASSKEY_RENAME: 'passkey_rename',
+} as const;
+
+// ─── Auth Audit Method (for logUserLogin when not a standard AuthMethod) ───
+
+export const AUTH_AUDIT_METHOD = {
+  INVITATION_ACCEPTANCE: 'invitation_acceptance',
+  INVITATION_LINK: 'invitation_link',
+} as const;
+
+// ─── Auth Source (audit/log context) ─────────────────────────────────
+
+export enum AuthSource {
+  SAML = 'saml',
+  OIDC = 'oidc',
+}
+
+// ─── SSO Protocol Discriminant ───────────────────────────────────────
+
+export enum SsoProtocol {
+  SAML = 'saml',
+  OIDC = 'oidc',
+}

package/src/security/authentications/models/authentications.backend.schemas.ts

@@ -0,0 +1,106 @@
+
+import { ExecutionContext_ExecutionType, SessionType, RolesSchema } from '@wildo-ai/saas-models';
+import { z } from 'zod';
+
+export const JwtClaimBaseSchema = z.object({
+  iat: z.number().optional(),        // Issued at
+  exp: z.number().optional(),        // Expires at
+  sub: z.string().optional(),        // Subject
+  aud: z.string().optional(),        // Audience
+  iss: z.string().optional()         // Issuer
+});
+
+export type JwtClaimBase = z.infer<typeof JwtClaimBaseSchema>;
+
+/** ──────────────────────────────────────────────────────────────
+ * Auth Base Schema - extends JwtClaimBaseSchema
+ * ────────────────────────────────────────────────────────────── */
+
+export const JwtClaim_App_Auth_BaseSchema = JwtClaimBaseSchema.extend({
+  type: z.enum(ExecutionContext_ExecutionType),
+});
+
+export type JwtClaim_App_Auth_Base = z.infer<typeof JwtClaim_App_Auth_BaseSchema>;
+
+/** ──────────────────────────────────────────────────────────────
+ * User Request JWT Claims
+ * ────────────────────────────────────────────────────────────── */
+
+export const JwtClaim_App_Auth_ExtraFieldsSchema_UserRequest: {
+  type: z.ZodLiteral<typeof ExecutionContext_ExecutionType.USER_REQUEST>;
+  userId: z.ZodString;
+  emailVerified: z.ZodOptional<z.ZodBoolean>;
+  lastAuthenticatedAt: z.ZodOptional<z.ZodNumber>;
+  activeUserType: z.ZodOptional<z.ZodString>;
+  sessionType: z.ZodOptional<z.ZodEnum<typeof SessionType>>;
+} = {
+  type: z.literal(ExecutionContext_ExecutionType.USER_REQUEST),
+  userId: z.string(),
+  /** W4.8: When emailVerification is 'deferred', tokens include emailVerified: false to enable guards on sensitive operations. */
+  emailVerified: z.boolean().optional(),
+  /** W7.1: Epoch seconds of last primary authentication. Used by step-up auth enforcement. */
+  lastAuthenticatedAt: z.number().optional(),
+  /** W7.1: Resolved user type from authentication. Used by step-up auth policy lookup. */
+  activeUserType: z.string().optional(),
+  /** W7.3b: 'ONE_OFF' for one-off sessions created via consumable token exchange. */
+  sessionType: z.enum(SessionType).optional(),
+};
+
+export const JwtClaim_App_Auth_UserRequest_Schema = JwtClaim_App_Auth_BaseSchema.extend(JwtClaim_App_Auth_ExtraFieldsSchema_UserRequest);
+
+export type JwtClaim_App_Auth_UserRequest = z.infer<typeof JwtClaim_App_Auth_UserRequest_Schema>;
+
+/** ──────────────────────────────────────────────────────────────
+ * Refresh Token Base Schema
+ * ────────────────────────────────────────────────────────────── */
+
+export const JwtClaim_App_RefreshToken_BaseSchema = JwtClaimBaseSchema.extend({
+  type: z.enum(ExecutionContext_ExecutionType),
+  jti: z.string(), // JWT ID (UUID)
+  sessionId: z.string().optional(), // Optional reference to original session
+});
+
+export type JwtClaim_App_RefreshToken_Base = z.infer<typeof JwtClaim_App_RefreshToken_BaseSchema>;
+
+/** ──────────────────────────────────────────────────────────────
+ * User Request Refresh Token
+ * ────────────────────────────────────────────────────────────── */
+
+export const JwtClaim_App_RefreshToken_ExtraFieldsSchema_UserRequest: {
+  type: z.ZodLiteral<typeof ExecutionContext_ExecutionType.USER_REQUEST>;
+  userId: z.ZodString;
+  lastAuthenticatedAt: z.ZodOptional<z.ZodNumber>;
+  activeUserType: z.ZodOptional<z.ZodString>;
+  sessionType: z.ZodOptional<z.ZodEnum<typeof SessionType>>;
+  refreshTokenExpiresAt: z.ZodOptional<z.ZodNumber>;
+} = {
+  type: z.literal(ExecutionContext_ExecutionType.USER_REQUEST),
+  userId: z.string(),
+  /** W7.1: Carried forward on refresh to preserve step-up auth clock. */
+  lastAuthenticatedAt: z.number().optional(),
+  /** W7.1: Carried forward on refresh so step-up policy lookup works after token rotation. */
+  activeUserType: z.string().optional(),
+  /** W7.3b: Carried forward on refresh. 'ONE_OFF' for one-off sessions. */
+  sessionType: z.enum(SessionType).optional(),
+  /** W7.3b: Unix timestamp of bounded refresh token expiry. Carried forward on each refresh
+   *  to reapply the bounded lifetime. Set from consumableToken.expiresAt at exchange time. */
+  refreshTokenExpiresAt: z.number().optional(),
+};
+
+export const JwtClaim_App_RefreshToken_UserRequest_Schema = JwtClaim_App_RefreshToken_BaseSchema.extend(JwtClaim_App_RefreshToken_ExtraFieldsSchema_UserRequest);
+
+export type JwtClaim_App_RefreshToken_UserRequest = z.infer<typeof JwtClaim_App_RefreshToken_UserRequest_Schema>;
+
+/** ──────────────────────────────────────────────────────────────
+ * Union Types
+ * ────────────────────────────────────────────────────────────── */
+
+export type Jwt_AppAuth_CreationParameter = JwtClaim_App_Auth_UserRequest;
+export type Jwt_RefreshToken_CreationParameter = JwtClaim_App_RefreshToken_UserRequest;
+
+export type JwtClaim_App_Auth = JwtClaim_App_Auth_UserRequest;
+export const JwtClaim_App_Auth_Schema: z.ZodType<JwtClaim_App_Auth> = JwtClaim_App_Auth_UserRequest_Schema;
+
+export type JwtClaim_App_RefreshToken = JwtClaim_App_RefreshToken_UserRequest;
+export const JwtClaim_App_RefreshToken_Schema: z.ZodType<JwtClaim_App_RefreshToken> = JwtClaim_App_RefreshToken_UserRequest_Schema;
+

package/src/security/authentications/models/jwt.backend.schemas.ts

@@ -0,0 +1,107 @@
+import jwt from 'jsonwebtoken';
+import { z } from 'zod';
+
+
+/**
+ * Application JWT Private Keys
+ * 
+ * Used by Wildo Applications (not platform services) to sign JWTs.
+ * Each application has its own key pair stored in MongoDB:
+ * - Private key: wildo_application_secrets.security.jwt.privateKey[key]
+ * - Public key: wildo_application_config.jwt.publicKey[key]
+ */
+export enum JwtPrivateKeys {
+    /** Application signing requests to platform services */
+    APPLICATION_PLATFORM_REQUEST = 'APPLICATION_PLATFORM_REQUEST',
+    /** Application signing webhooks */
+    APPLICATION_WEBHOOK = 'APPLICATION_WEBHOOK',
+    /** Application signing auth tokens */
+    APPLICATION_AUTH_TOKEN = 'APPLICATION_AUTH_TOKEN',
+}
+
+/**
+ * Platform Service JWT Public Keys
+ * 
+ * Used to verify JWTs from platform services.
+ * Public keys are stored in apps-manager env config.
+ * Env var pattern: PLATFORM_<SERVICE_NAME>_PUBLIC_KEY
+ */
+export enum JwtPublicKeys {
+    /** Platform service: apps-manager - central platform orchestrator */
+    PLATFORM_APPS_MANAGER = 'PLATFORM_APPS_MANAGER',
+
+    /** Platform service: crontabs-batches-manager - handles scheduled jobs */
+    PLATFORM_CRONTABS_BATCHES_MANAGER = 'PLATFORM_CRONTABS_BATCHES_MANAGER',
+    /** Platform service: file-generator - handles file generation */
+    PLATFORM_FILE_GENERATOR = 'PLATFORM_FILE_GENERATOR',
+}
+
+export const VerifiableJwtKeysSchema = z.enum([ ...Object.values(JwtPrivateKeys), ...Object.values(JwtPublicKeys)] as [string, ...string[]]);
+export type VerifiableJwtKeys = z.infer<typeof VerifiableJwtKeysSchema>;
+
+export const JwtDefaultSignOptions: jwt.SignOptions = {
+    algorithm: 'ES256',
+    expiresIn: '24h',
+}
+
+export const JwtDefaultVerifyOptions: jwt.VerifyOptions = {
+    algorithms: ['ES256'],
+    clockTolerance: 30,
+}
+
+export const JwtPrivateKeySignOptions: Record<JwtPrivateKeys, jwt.SignOptions> = {
+    [JwtPrivateKeys.APPLICATION_PLATFORM_REQUEST]: {
+        ...JwtDefaultSignOptions,
+        keyid: JwtPrivateKeys.APPLICATION_PLATFORM_REQUEST,
+        issuer: 'wildo-application',
+        audience: 'PLATFORM_SERVICE',
+    },
+    [JwtPrivateKeys.APPLICATION_WEBHOOK]: {
+        ...JwtDefaultSignOptions,
+        keyid: JwtPrivateKeys.APPLICATION_WEBHOOK,
+        issuer: 'wildo-application',
+        audience: 'WEBHOOK',
+    },
+    [JwtPrivateKeys.APPLICATION_AUTH_TOKEN]: {
+        ...JwtDefaultSignOptions,
+        keyid: JwtPrivateKeys.APPLICATION_AUTH_TOKEN,
+        issuer: 'wildo-application',
+        audience: 'AUTH_TOKEN',
+    },
+}
+
+export const JwtVerifyOptions: Record<VerifiableJwtKeys, jwt.VerifyOptions> = {
+    // Application keys - used to verify tokens from Wildo applications
+    [JwtPrivateKeys.APPLICATION_PLATFORM_REQUEST]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'wildo-application',
+        audience: 'PLATFORM_SERVICE',
+    },
+    [JwtPrivateKeys.APPLICATION_WEBHOOK]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'wildo-application',
+        audience: 'WEBHOOK',
+    },
+    [JwtPrivateKeys.APPLICATION_AUTH_TOKEN]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'wildo-application',
+        audience: 'AUTH_TOKEN',
+    },
+    // Platform service keys - used to verify tokens from platform services
+    [JwtPublicKeys.PLATFORM_APPS_MANAGER]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'platform_apps_manager',
+        audience: 'PLATFORM_SERVICE',
+    },
+
+    [JwtPublicKeys.PLATFORM_CRONTABS_BATCHES_MANAGER]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'platform_crontabs_batches_manager',
+        audience: 'SCHEDULED_JOB',
+    },
+    [JwtPublicKeys.PLATFORM_FILE_GENERATOR]: {
+        ...JwtDefaultVerifyOptions,
+        issuer: 'platform_file_generator',
+        audience: 'PLATFORM_SERVICE',
+    },
+}

package/src/security/authentications/models/oauth2-connection.backend.schemas.ts

@@ -0,0 +1,196 @@
+/**
+ * OAuth2 Resolved Connection & State Types
+ *
+ * These are the canonical types shared between the OAuth2 engine and its resolvers.
+ * Social resolver (Step 4) and Enterprise resolver (Step 15) both produce
+ * `OAuth2ResolvedConnection`. The engine methods (`buildAuthorizationUrl`,
+ * `handleCallback`, `provisionOrLinkUser`) consume it.
+ *
+ * `NormalizedUserProfile` has moved to `sso-connection.backend.schemas.ts` (shared
+ * between OIDC and SAML). Re-exported here for backward compatibility.
+ */
+
+import type { SSOResolvedConnectionBase } from './sso-connection.backend.schemas';
+import type { AuthScopeType } from '@wildo-ai/saas-models';
+
+export type { NormalizedUserProfile } from './sso-connection.backend.schemas';
+
+// ─────────────────────────────────────────────────────────────────
+// OAuth2ResolvedConnection
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical resolved OAuth2 connection — the engine's only input.
+ * Social resolver (Step 4) and Enterprise resolver (Step 15) both produce this.
+ * Extends SSOResolvedConnectionBase with OAuth2-specific protocol fields.
+ */
+export interface OAuth2ResolvedConnection extends SSOResolvedConnectionBase {
+  source: 'oidc';
+
+  // ─── OAuth2 Protocol Parameters ───
+  authorizationUrl: string;
+  tokenUrl: string;
+  /** Optional — Apple has none (identity from ID token) */
+  userInfoUrl?: string;
+  /** Redirect URI — computed by resolver, stored for exact match on callback */
+  redirectUri: string;
+  /** Issuer URL — for ID token validation (Apple, enterprise OIDC) */
+  issuer?: string;
+  /** JWKS endpoint — for ID token signature verification */
+  jwksUri?: string;
+
+  // ─── Client Credentials ───
+  clientId: string;
+  /**
+   * Client secret — always a string. For Apple (dynamic JWT secret), the RESOLVER
+   * generates the signed JWT and places the result here. The engine never knows
+   * how the secret was produced.
+   */
+  clientSecret: string;
+  /**
+   * How to send credentials to the token endpoint.
+   * - 'client_secret_post': credentials in POST body (Google, Microsoft, GitHub, Apple)
+   * - 'client_secret_basic': credentials in Authorization: Basic header (some enterprise IdPs)
+   * - 'none': no client auth (public clients, rare)
+   */
+  tokenEndpointAuthMethod: 'client_secret_post' | 'client_secret_basic' | 'none';
+
+  // ─── Scopes & Security ───
+  scopes: string[];
+  pkceMethod: 'S256' | 'plain' | null;
+
+  // ─── Response Configuration ───
+  /**
+   * How the IdP delivers the authorization response.
+   * - 'query': code & state in URL query params (default, most providers)
+   * - 'fragment': code & state in URL fragment (rare)
+   * - 'form_post': code & state in POST body (Apple REQUIRES this)
+   * The callback handler MUST accept both GET and POST and extract params accordingly.
+   */
+  responseMode: 'query' | 'fragment' | 'form_post';
+
+  /**
+   * Where user identity comes from after code exchange:
+   * - 'userinfo': fetch from userInfoUrl (Google, Microsoft, GitHub — default)
+   * - 'id_token': decode from ID token JWT (Apple — no userinfo endpoint)
+   * - 'callback_body': embedded in the callback POST body (Apple first-auth name)
+   */
+  identitySource: 'userinfo' | 'id_token' | 'callback_body';
+
+  // ─── Profile Mapping (unified) ───
+  /**
+   * Maps provider claim field names to canonical user profile fields.
+   * Works for both social `userProfileMapping` and enterprise `claimsMapping`.
+   */
+  profileMapping: OAuth2ProfileMapping;
+
+  // ─── Extra Parameters ───
+  extraAuthParams?: Record<string, string>;
+  extraTokenParams?: Record<string, string>;
+  tokenRequestHeaders?: Record<string, string>;
+
+  // ─── Provider-Specific Extensions ───
+  extensions?: Record<string, unknown>;
+
+  // ─── Enterprise-Specific (null for social) ───
+  /** Override: allowedDomains is required (non-optional) for OAuth2 enterprise connections */
+  organization?: OAuth2EnterpriseOrganization;
+}
+
+/**
+ * Profile mapping — translates provider claim field names to canonical fields.
+ */
+export interface OAuth2ProfileMapping {
+  id: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  name?: string;
+  image?: string;
+  emailVerified?: string;
+  roles?: string;
+  groups?: string;
+  department?: string;
+  employeeId?: string;
+}
+
+/**
+ * Enterprise-specific context within a resolved connection.
+ * Extends the base organization shape with OAuth2-specific field requirements.
+ */
+export interface OAuth2EnterpriseOrganization {
+  organizationId: string;
+  scopeType?: AuthScopeType;
+  scopeId?: string;
+  connectionId: string;
+  allowedDomains: string[];
+  autoCreateUsers: boolean;
+  autoVerifyEmail: boolean;
+  defaultRole?: string;
+  roleMapping?: Record<string, string>;
+  groupMapping?: Record<string, string[]>;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// State Token Metadata
+// ─────────────────────────────────────────────────────────────────
+
+
+/**
+ * Metadata stored in the OAUTH2_STATE consumable token.
+ * Carries connection context through the OAuth2 redirect so the callback handler
+ * can re-resolve the exact same connection configuration.
+ *
+ * Created by buildAuthorizationUrl() → consumed by resolveFromState().
+ *
+ * For social connections with per-scope credential overrides (P3), scopeType + scopeId
+ * are stored so resolveFromState() can re-apply the override on callback — ensuring
+ * the same clientId/clientSecret (and signed-JWT params) are used for the token exchange.
+ */
+export interface OAuth2StateTokenMetadata {
+  connectionType: 'social' | 'enterprise';
+  providerRef: string;
+  /** The clientId used at authorize time. Validated on callback to detect config drift. */
+  clientId: string;
+  responseMode: 'query' | 'fragment' | 'form_post';
+  pkceVerifier?: string;
+  redirectUri: string;
+  initiatedAt: string; // ISO timestamp
+  /** Config-defined frontend service identity for the surface that initiated the OAuth2 flow.
+   *  Used on callback to redirect back to the correct frontend. */
+  frontendServiceName?: string;
+  /** Scope context — set for enterprise connections AND social connections with
+   *  credential overrides (P3). Used by resolveFromState() to re-resolve the connection
+   *  with the correct org/app scope, including per-scope credential overrides. */
+  scopeType?: AuthScopeType;
+  /** The org or app ID. Combined with scopeType to load SsoConfig for credential overrides. */
+  scopeId?: string;
+  /** Post-auth frontend path to restore after the provider round-trip. */
+  returnUrl?: string;
+  /** Enterprise-only — identifies the specific SsoConnection resource. */
+  connectionId?: string;
+  /** @deprecated Use scopeId. Kept for backward compat with in-flight state tokens during rollout.
+   *  resolveFromState() falls back to this when scopeId is absent. */
+  organizationId?: string;
+}
+
+/**
+ * Parameters passed to the callback handler from the route.
+ * Extracted from query params (GET) or body (POST) based on responseMode.
+ */
+export interface OAuth2CallbackParams {
+  code: string;
+  state: string;
+  /** Apple form_post: the full POST body including `user` JSON (first auth only) */
+  body?: Record<string, unknown>;
+}
+
+/**
+ * Result of provisionOrLinkUser — the user and whether it was newly created.
+ */
+export interface OAuth2ProvisionResult {
+  /** The provisioned user ID — userId. */
+  userId: string;
+  /** Whether the user was newly created (JIT provisioning) vs linked to existing. */
+  isNewUser: boolean;
+}

package/src/security/authentications/models/saml-authentication.backend.schemas.ts

@@ -0,0 +1,124 @@
+/**
+ * SAML Authentication — Backend Schemas
+ *
+ * Types specific to the SAML 2.0 protocol engine (AUTH-2).
+ * Parallels `oauth2-connection.backend.schemas.ts` for the OIDC flow.
+ */
+
+import type { SSOResolvedConnectionBase } from './sso-connection.backend.schemas';
+
+// ─────────────────────────────────────────────────────────────────
+// SAMLResolvedConnection
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Resolved SAML connection — the SAML engine's input.
+ * Built from `SsoConnection` resource config at request time (per D2).
+ */
+export interface SAMLResolvedConnection extends SSOResolvedConnectionBase {
+  source: 'saml';
+
+  /** IdP's SAML entity ID (from connection config `saml.entityId`) */
+  idpEntityId: string;
+  /** IdP SSO service URL (HTTP-Redirect or HTTP-POST binding) */
+  ssoUrl: string;
+  /** IdP SLO service URL (optional — not all IdPs support SLO) */
+  sloUrl?: string;
+  /** IdP X.509 certificates for signature verification (supports rotation via array) */
+  x509Certificates: string[];
+
+  /** SP entity ID — per-scope: `https://{appDomain}/saml/sp/{scopeType}/{scopeId}` */
+  spEntityId: string;
+  /** SP Assertion Consumer Service URL */
+  acsUrl: string;
+  /** NameID format requested from IdP */
+  nameIdFormat: string;
+  /** Maps SAML attribute URIs/names to canonical profile fields */
+  attributeMapping: Record<string, string>;
+  /** Whether IdP-initiated SSO is allowed for this connection */
+  allowIdpInitiated: boolean;
+  /** Allowed clock drift in seconds for timestamp validation */
+  allowedClockDrift: number;
+  /** Whether AuthnRequests should be signed */
+  signRequests: boolean;
+  /** Whether assertions must be signed */
+  wantAssertionsSigned: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// SAMLStateMetadata
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Metadata stored in the SAML_AUTH_STATE consumable token.
+ * Carries request context through the SAML redirect (via RelayState).
+ * Consumed at the ACS endpoint for InResponseTo validation (per D3).
+ */
+export interface SAMLStateMetadata {
+  /** SAML AuthnRequest ID (for InResponseTo validation) */
+  requestId: string;
+  /** Which SsoConnection initiated this flow */
+  connectionId: string;
+  /** Scope type (organization or application) */
+  scopeType: string;
+  /** Organization/application ID */
+  scopeId: string;
+  /** Where to redirect after successful auth */
+  returnUrl: string;
+  /** Timestamp for age validation */
+  initiatedAt: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// SAMLAssertionData
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extracted and validated SAML assertion fields.
+ * Produced by `SAMLAssertionValidatorBackendService` after full validation.
+ */
+export interface SAMLAssertionData {
+  /** Unique assertion identifier (used for replay detection) */
+  assertionId: string;
+  /** Subject NameID value (comment-stripped, validated) */
+  nameId: string;
+  /** NameID format URI */
+  nameIdFormat: string;
+  /** Session index for SLO correlation */
+  sessionIndex?: string;
+  /** Extracted SAML attributes (values may be single or multi-valued) */
+  attributes: Record<string, string | string[]>;
+  /** IdP entity ID from the assertion's Issuer element */
+  issuer: string;
+  /** Assertion validity window start */
+  notBefore?: string;
+  /** Assertion validity window end */
+  notOnOrAfter?: string;
+  /** Audience restriction value (should match our SP entity ID) */
+  audienceRestriction?: string;
+  /** InResponseTo value (present for SP-initiated flows) */
+  inResponseTo?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// ParsedIdPMetadata
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Structured output of IdP metadata XML parsing.
+ * Returned by `SAMLMetadataBackendService.parseIdPMetadata()`.
+ */
+export interface ParsedIdPMetadata {
+  /** IdP entity ID from the metadata */
+  entityId: string;
+  /** SSO service URL (HTTP-Redirect or HTTP-POST) */
+  ssoUrl: string;
+  /** SLO service URL (optional) */
+  sloUrl?: string;
+  /** IdP signing certificates (PEM-encoded, may contain multiple for rotation) */
+  x509Certificates: string[];
+  /** Preferred NameID format from metadata */
+  nameIdFormat?: string;
+  /** SLO binding types supported by the IdP */
+  sloBindings?: string[];
+}