@_mustachio/openauth 0.12.0 → 0.13.0

package/src/methods/saml-sp/acs.ts

@@ -47,7 +47,7 @@ import { authError } from "../../types/error"
 import type { MethodContext, MethodResult } from "../../types/method"
 
 import { mapProfile, type VerifiedProfile } from "./attributes"
-import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import { buildSamlInstance, resolveSpEntityId } from "./saml-instance"
 import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
 
 const { DOMParser } = xmldom
@@ -81,45 +81,51 @@ type NodeSamlProfile = {
  * library/infra fault — matching the rest of this handler's
  * classification).
  */
-function checkRecipient(
+function parseVerifiedAssertion(
   profile: NodeSamlProfile,
-  acsUrl: string,
-): MethodResult<SamlSpProperties, SamlSpState> | null {
+):
+  | { doc: Document }
+  | { failure: MethodResult<SamlSpProperties, SamlSpState> } {
   if (typeof profile.getAssertionXml !== "function") {
     // node-saml v5.1 populates this on a successful verify. Its
     // absence means the library contract changed under us — fail loud
-    // rather than skip a security check we now promise.
+    // rather than skip security checks we now promise.
     return {
-      kind: "error",
-      error: authError.internalError(
-        "saml-sp: node-saml profile exposes no getAssertionXml(); cannot " +
-          "perform the Recipient binding check. Refusing to authenticate.",
-      ),
+      failure: {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: node-saml profile exposes no getAssertionXml(); cannot " +
+            "perform the Recipient binding check. Refusing to authenticate.",
+        ),
+      },
     }
   }
-
-  let doc: Document
   try {
-    doc = new DOMParser().parseFromString(
-      profile.getAssertionXml(),
-      "text/xml",
-    ) as unknown as Document
+    return {
+      doc: new DOMParser().parseFromString(
+        profile.getAssertionXml(),
+        "text/xml",
+      ) as unknown as Document,
+    }
   } catch (e) {
     return {
-      kind: "error",
-      error: authError.internalError(
-        "saml-sp: failed to parse the verified assertion for the " +
-          "Recipient check",
-        e,
-      ),
+      failure: {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: failed to parse the verified assertion",
+          e,
+        ),
+      },
     }
   }
+}
 
+function checkRecipient(
+  doc: Document,
+  acsUrl: string,
+): MethodResult<SamlSpProperties, SamlSpState> | null {
   // Namespace-agnostic: match by local name regardless of prefix.
-  const nodes = doc.getElementsByTagNameNS(
-    "*",
-    "SubjectConfirmationData",
-  )
+  const nodes = doc.getElementsByTagNameNS("*", "SubjectConfirmationData")
   const recipients: string[] = []
   for (let i = 0; i < nodes.length; i++) {
     const r = nodes[i]?.getAttribute("Recipient")
@@ -145,24 +151,14 @@ function checkRecipient(
 
 /**
  * For IdP-initiated replay dedup: pull the assertion `@ID` and the
- * tightest `NotOnOrAfter` from the **verified** assertion XML (the same
- * bytes `checkRecipient` reads). Returns `null` if the assertion XML is
- * unavailable (caller treats that as a fail-loud error — we will not
- * skip replay protection we promised).
+ * tightest `NotOnOrAfter` from the **verified** assertion (the same
+ * parsed document every other check reads). Returns `null` when the
+ * assertion carries no `@ID` — the caller treats that as a fail-loud
+ * error rather than skipping replay protection we promised.
  */
 function extractReplayInfo(
-  profile: NodeSamlProfile,
+  doc: Document,
 ): { assertionId: string; notOnOrAfterMs: number | null } | null {
-  if (typeof profile.getAssertionXml !== "function") return null
-  let doc: Document
-  try {
-    doc = new DOMParser().parseFromString(
-      profile.getAssertionXml(),
-      "text/xml",
-    ) as unknown as Document
-  } catch {
-    return null
-  }
   const root = doc.documentElement
   const assertionId = root?.getAttribute("ID") ?? ""
   if (!assertionId) return null
@@ -173,12 +169,57 @@ function extractReplayInfo(
       const v = els[i]?.getAttribute("NotOnOrAfter")
       if (!v) continue
       const ms = Date.parse(v)
-      if (!Number.isNaN(ms)) earliest = earliest === null ? ms : Math.min(earliest, ms)
+      if (!Number.isNaN(ms))
+        earliest = earliest === null ? ms : Math.min(earliest, ms)
     }
   }
   return { assertionId, notOnOrAfterMs: earliest }
 }
 
+/**
+ * Read the `<AuthnStatement>` facts the host needs but node-saml's
+ * `Profile` does not carry (`types.d.ts` exposes `nameID`,
+ * `nameIDFormat`, `sessionIndex` and the flattened attributes, and
+ * nothing else structural).
+ *
+ * Read from the **verified** assertion document — never the unsigned
+ * outer Response — for the same reason `checkRecipient` is: an
+ * attacker-controlled value outside the signature is not a fact.
+ *
+ * All three are optional in SAML, so every field is best-effort; the
+ * caller falls back rather than failing, since none of them is a
+ * security control on its own.
+ */
+function extractAuthnStatement(doc: Document): {
+  authnInstant?: string
+  sessionNotOnOrAfter?: number
+  authnContextClassRef?: string
+} {
+  const out: {
+    authnInstant?: string
+    sessionNotOnOrAfter?: number
+    authnContextClassRef?: string
+  } = {}
+  const stmt = doc.getElementsByTagNameNS("*", "AuthnStatement")[0]
+  if (!stmt) return out
+
+  const instant = stmt.getAttribute("AuthnInstant")
+  if (instant) out.authnInstant = instant
+
+  const sessionExpiry = stmt.getAttribute("SessionNotOnOrAfter")
+  if (sessionExpiry) {
+    const ms = Date.parse(sessionExpiry)
+    if (!Number.isNaN(ms)) out.sessionNotOnOrAfter = ms
+  }
+
+  const ref = stmt
+    .getElementsByTagNameNS("*", "AuthnContextClassRef")[0]
+    ?.textContent?.trim()
+  if (ref) out.authnContextClassRef = ref
+
+  return out
+}
+
 export async function consumeAssertion(
   ctx: MethodContext<SamlSpState>,
   methodId: string,
@@ -212,7 +253,8 @@ export async function consumeAssertion(
       }
     }
     // Same derivation as AuthnRequest / metadata — no drift.
-    spEntityId = deriveSpEntityId(
+    spEntityId = resolveSpEntityId(
+      config,
       ctx.dispatch.issuerUrl,
       ctx.tenant.id,
       methodId,
@@ -299,10 +341,7 @@ export async function consumeAssertion(
     // arrives but no decryptionPvk is configured. Give the operator a
     // signal that the *connection* is mis/under-configured rather than
     // a generic "assertion rejected".
-    if (
-      !config.allowEncryptedAssertions &&
-      msg.includes("No decryption key")
-    ) {
+    if (!config.allowEncryptedAssertions && msg.includes("No decryption key")) {
       return {
         kind: "denied",
         reason:
@@ -318,17 +357,25 @@ export async function consumeAssertion(
     return { kind: "denied", reason: "assertion produced no usable subject" }
   }
 
+  // One parse of the verified assertion, shared by every check below
+  // (Recipient binding, IdP-init replay dedup, AuthnStatement facts) —
+  // they all read the same signed bytes, so parsing once is both
+  // cheaper and impossible to accidentally diverge.
+  const parsed = parseVerifiedAssertion(profile)
+  if ("failure" in parsed) return parsed.failure
+  const assertionDoc = parsed.doc
+
   // Gauntlet item 6 — node-saml does not enforce @Recipient; we do,
   // against the exact ACS URL the IdP saw (committed for SP-init,
   // derived for IdP-init — identical value either way).
-  const recipientFailure = checkRecipient(profile, acsUrl)
+  const recipientFailure = checkRecipient(assertionDoc, acsUrl)
   if (recipientFailure) return recipientFailure
 
   // IdP-init replay: no InResponseTo single-use to lean on, so dedup
   // the signed assertion's @ID. SP-init does not need this (the
   // request id is already single-use).
   if (idpInitiated) {
-    const replay = extractReplayInfo(profile)
+    const replay = extractReplayInfo(assertionDoc)
     if (!replay) {
       return {
         kind: "error",
@@ -367,12 +414,15 @@ export async function consumeAssertion(
     }
   }
 
+  const authnStatement = extractAuthnStatement(assertionDoc)
+
   const verified: VerifiedProfile = {
     nameID: profile.nameID,
     nameIDFormat: profile.nameIDFormat ?? "",
     ...(profile.sessionIndex !== undefined
       ? { sessionIndex: profile.sessionIndex }
       : {}),
+    ...authnStatement,
     attributes: profile.attributes ?? {},
     responseXml: profile.getSamlResponseXml?.() ?? "",
   }

package/src/methods/saml-sp/attributes.ts

@@ -27,7 +27,12 @@ export type VerifiedProfile = {
   nameIDFormat: string
   sessionIndex?: string
   attributes: Record<string, unknown>
+  /** `AuthnStatement/@AuthnInstant`, raw XSD dateTime. */
   authnInstant?: string
+  /** `AuthnStatement/@SessionNotOnOrAfter`, already parsed to Unix ms. */
+  sessionNotOnOrAfter?: number
+  /** `AuthnContext/AuthnContextClassRef` — what the IdP actually asserted. */
+  authnContextClassRef?: string
   responseXml: string
 }
 
@@ -107,9 +112,7 @@ export function mapProfile(
   put("name", mapping.name)
   put("groups", mapping.groups)
   if (mapping.emailVerified) {
-    attributes["emailVerified"] = mapping.emailVerified.value
-      ? "true"
-      : "false"
+    attributes["emailVerified"] = mapping.emailVerified.value ? "true" : "false"
   }
   for (const [key, ref] of Object.entries(mapping.custom ?? {})) {
     put(key, ref)
@@ -131,6 +134,12 @@ export function mapProfile(
         ? { sessionIndex: profile.sessionIndex }
         : {}),
       authnInstant: Number.isNaN(authnInstant) ? Date.now() : authnInstant,
+      ...(profile.sessionNotOnOrAfter !== undefined
+        ? { sessionNotOnOrAfter: profile.sessionNotOnOrAfter }
+        : {}),
+      ...(profile.authnContextClassRef !== undefined
+        ? { authnContextClassRef: profile.authnContextClassRef }
+        : {}),
       raw: { responseXml: profile.responseXml },
     },
   }

package/src/methods/saml-sp/authnrequest.ts

@@ -13,7 +13,7 @@ import { authError } from "../../types/error"
 import type { MethodContext, MethodResult } from "../../types/method"
 import { isErr } from "../../types/result"
 
-import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import { buildSamlInstance, resolveSpEntityId } from "./saml-instance"
 import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
 
 export async function buildAuthnRequestRedirect(
@@ -43,7 +43,8 @@ export async function buildAuthnRequestRedirect(
     }
   }
 
-  const spEntityId = deriveSpEntityId(
+  const spEntityId = resolveSpEntityId(
+    config,
     ctx.dispatch.issuerUrl,
     ctx.tenant.id,
     methodId,

package/src/methods/saml-sp/factory.ts

@@ -80,17 +80,38 @@ const samlSpConfigSchema = z
       .optional(),
     idpInitiated: idpInitiatedSchema.optional(),
     clockSkewSeconds: z.number().int().nonnegative().optional(),
+    spEntityId: z.string().min(1).optional(),
+    forceAuthn: z.boolean().optional(),
+    requestedAuthnContext: z
+      .object({
+        classRefs: z.array(z.string().min(1)).min(1),
+        comparison: z
+          .enum(["exact", "minimum", "maximum", "better"])
+          .optional(),
+      })
+      .optional(),
+    requireSignedAssertion: z.boolean().optional(),
+    requireSignedResponse: z.boolean().optional(),
   })
   .refine((c) => !c.signAuthnRequest || c.signingKey !== undefined, {
     message: "signingKey is required when signAuthnRequest is true",
     path: ["signingKey"],
   })
+  .refine((c) => !c.allowEncryptedAssertions || c.decryptionKey !== undefined, {
+    message: "decryptionKey is required when allowEncryptedAssertions is true",
+    path: ["decryptionKey"],
+  })
+  // An assertion nobody signed, inside a Response nobody signed, is
+  // unauthenticated XML. Refuse the combination outright rather than
+  // let a connection be configured into accepting anything.
   .refine(
-    (c) => !c.allowEncryptedAssertions || c.decryptionKey !== undefined,
+    (c) =>
+      (c.requireSignedAssertion ?? true) || c.requireSignedResponse === true,
     {
       message:
-        "decryptionKey is required when allowEncryptedAssertions is true",
-      path: ["decryptionKey"],
+        "requireSignedAssertion may only be false when requireSignedResponse " +
+        "is true — at least one signature is mandatory",
+      path: ["requireSignedAssertion"],
     },
   )
 

package/src/methods/saml-sp/metadata.ts

@@ -8,7 +8,7 @@
  *
  * **Conformance invariant:** the `entityID` and ACS `Location` are
  * derived from the *same* inputs the live AuthnRequest / ACS path uses
- * (`deriveSpEntityId(issuerUrl, tenantId, methodId)` and
+ * (`resolveSpEntityId(config, issuerUrl, tenantId, methodId)` and
  * `ctx.dispatch.callbackUrl`). The metadata therefore describes exactly
  * what the runtime accepts — never an independently re-specified value
  * that could drift. `metadata.test.ts` asserts this equality against
@@ -18,13 +18,14 @@
  * (advertising a cert we cannot use would be the bug);
  * `SingleLogoutService` only when an IdP SLO endpoint is configured
  * and the `/sls` route is therefore served (advertising an endpoint we
- * do not serve would break interop). `AuthnRequestsSigned` /
- * `WantAssertionsSigned="true"` truthfully state actual behaviour.
+ * do not serve would break interop). `AuthnRequestsSigned` and
+ * `WantAssertionsSigned` are both read from config, so they state
+ * actual runtime behaviour rather than a hardcoded assumption.
  */
 import { authError } from "../../types/error"
 import type { MethodContext, MethodResult } from "../../types/method"
 
-import { deriveSpEntityId } from "./saml-instance"
+import { resolveSpEntityId } from "./saml-instance"
 import type {
   SamlNameIdFormat,
   SamlSpConfig,
@@ -40,8 +41,7 @@ const NAME_ID_FORMAT_URN: Record<SamlNameIdFormat, string> = {
 }
 
 const HTTP_POST = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
-const HTTP_REDIRECT =
-  "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
+const HTTP_REDIRECT = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
 
 /** Minimal XML attribute/text escaping for URL-shaped values. */
 function xmlEscape(s: string): string {
@@ -79,6 +79,14 @@ export type SpMetadataInput = {
    * what-we-serve invariant as the signing cert.
    */
   encryptionCertPem?: string
+  /**
+   * Whether we actually require a signed `<saml:Assertion>`
+   * (`config.requireSignedAssertion`, default `true`). Published as
+   * `WantAssertionsSigned` — same advertise-only-what-we-serve
+   * invariant as the certs: a connection relying on a signed
+   * `<Response>` instead must not claim otherwise in its metadata.
+   */
+  wantAssertionsSigned?: boolean
 }
 
 /** PEM cert body → bare base64 (SAML metadata X509Certificate form). */
@@ -97,6 +105,7 @@ export function buildSpMetadataXml(input: SpMetadataInput): string {
   const entityId = xmlEscape(input.spEntityId)
   const acs = xmlEscape(input.acsUrl)
   const signed = input.signingCertPem !== undefined
+  const wantAssertionsSigned = input.wantAssertionsSigned ?? true
   const nameIdLine =
     input.nameIdFormat !== undefined
       ? `\n    <md:NameIDFormat>${NAME_ID_FORMAT_URN[input.nameIdFormat]}</md:NameIDFormat>`
@@ -132,7 +141,7 @@ export function buildSpMetadataXml(input: SpMetadataInput): string {
     `xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ` +
     `entityID="${entityId}">\n` +
     `  <md:SPSSODescriptor AuthnRequestsSigned="${signed}" ` +
-    `WantAssertionsSigned="true" ` +
+    `WantAssertionsSigned="${wantAssertionsSigned}" ` +
     `protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">` +
     keyDescriptor +
     sls +
@@ -164,7 +173,8 @@ export async function buildSpMetadata(
     }
   }
 
-  const spEntityId = deriveSpEntityId(
+  const spEntityId = resolveSpEntityId(
+    config,
     ctx.dispatch.issuerUrl,
     ctx.tenant.id,
     methodId,
@@ -182,6 +192,7 @@ export async function buildSpMetadata(
     ...(config.idp.nameIdFormat !== undefined
       ? { nameIdFormat: config.idp.nameIdFormat }
       : {}),
+    wantAssertionsSigned: config.requireSignedAssertion ?? true,
     // Truthful: advertise signing iff we actually sign AuthnRequests.
     ...(config.signAuthnRequest && config.signingKey
       ? { signingCertPem: config.signingKey.certPem }

package/src/methods/saml-sp/parse-idp-metadata.ts

@@ -66,9 +66,7 @@ function toPem(rawX509: string): string {
   )
 }
 
-export function parseSamlIdpMetadata(
-  xml: string,
-): Result<SamlIdpConfig> {
+export function parseSamlIdpMetadata(xml: string): Result<SamlIdpConfig> {
   if (typeof xml !== "string" || xml.trim().length === 0) {
     return err(authError.invalidRequest("metadata XML is empty"))
   }
@@ -94,15 +92,11 @@ export function parseSamlIdpMetadata(
 
   const entityDescriptor = els(doc, "EntityDescriptor")[0]
   if (!entityDescriptor) {
-    return err(
-      authError.invalidRequest("metadata has no <EntityDescriptor>"),
-    )
+    return err(authError.invalidRequest("metadata has no <EntityDescriptor>"))
   }
   const entityId = entityDescriptor.getAttribute("entityID")
   if (!entityId) {
-    return err(
-      authError.invalidRequest("EntityDescriptor has no entityID"),
-    )
+    return err(authError.invalidRequest("EntityDescriptor has no entityID"))
   }
 
   const idp = els(entityDescriptor, "IDPSSODescriptor")[0]

package/src/methods/saml-sp/saml-instance.ts

@@ -105,6 +105,26 @@ export function deriveSpEntityId(
   return `${base}/${tenantId}/${methodId}`
 }
 
+/**
+ * The SP entityID this connection actually presents — the configured
+ * override if the operator set one (to adopt an entityID that already
+ * exists at the IdP), else the derived default.
+ *
+ * **Every** consumer must go through this one function: the
+ * `AuthnRequest` issuer, `AudienceRestriction` validation, SP metadata,
+ * and logout messages all have to agree, or the IdP rejects us. That
+ * shared-resolution property is what the metadata anti-drift test
+ * guards.
+ */
+export function resolveSpEntityId(
+  config: SamlSpConfig,
+  issuerUrl: string,
+  tenantId: string,
+  methodId: string,
+): string {
+  return config.spEntityId ?? deriveSpEntityId(issuerUrl, tenantId, methodId)
+}
+
 export function buildSamlInstance(
   config: SamlSpConfig,
   binding: SamlBindingContext,
@@ -146,9 +166,28 @@ export function buildSamlInstance(
       : binding.idpInitiated
         ? ValidateInResponseTo.ifPresent
         : ValidateInResponseTo.always,
-    wantAssertionsSigned: true,
-    wantAuthnResponseSigned: false,
+    wantAssertionsSigned: config.requireSignedAssertion ?? true,
+    wantAuthnResponseSigned: config.requireSignedResponse ?? false,
     acceptedClockSkewMs: (config.clockSkewSeconds ?? 60) * 1000,
+    // ForceAuthn — a request, never a guarantee. SAML gives the IdP no
+    // obligation to honour it and the Response carries no proof either
+    // way, so nothing downstream may treat it as freshness evidence.
+    forceAuthn: config.forceAuthn ?? false,
+    // RequestedAuthnContext. node-saml's own defaults are
+    // `disableRequestedAuthnContext: false` +
+    // `authnContext: [PasswordProtectedTransport]` +
+    // `racComparison: "exact"`, i.e. every AuthnRequest would demand
+    // exactly password-over-TLS. An IdP with an MFA sign-on policy can
+    // answer that with `NoAuthnContext` instead of a login, so we
+    // invert the default: send no RequestedAuthnContext unless the
+    // operator explicitly configured the class refs their IdP honours.
+    ...(config.requestedAuthnContext
+      ? {
+          disableRequestedAuthnContext: false,
+          authnContext: [...config.requestedAuthnContext.classRefs],
+          racComparison: config.requestedAuthnContext.comparison ?? "exact",
+        }
+      : { disableRequestedAuthnContext: true }),
     cacheProvider: methodScratchCacheProvider(
       binding.scratch,
       IN_RESPONSE_TO_TTL_MS,
@@ -166,8 +205,6 @@ export function buildSamlInstance(
     // SLO endpoint). node-saml's logout URL builder reads `logoutUrl`.
     ...(binding.logoutUrl ? { logoutUrl: binding.logoutUrl } : {}),
     // Encrypted-assertion decryption (opt-in per connection).
-    ...(binding.decryptionPvk
-      ? { decryptionPvk: binding.decryptionPvk }
-      : {}),
+    ...(binding.decryptionPvk ? { decryptionPvk: binding.decryptionPvk } : {}),
   })
 }

package/src/methods/saml-sp/slo-initiate.ts

@@ -32,7 +32,7 @@ import type { MethodContext, MethodResult } from "../../types/method"
 
 import {
   buildSamlInstance,
-  deriveSpEntityId,
+  resolveSpEntityId,
   NAME_ID_FORMAT_URN,
 } from "./saml-instance"
 import type {
@@ -78,7 +78,9 @@ export async function initiateSpLogout(
   } catch {
     return {
       kind: "error",
-      error: authError.internalError("saml-sp: /logout could not read POST body"),
+      error: authError.internalError(
+        "saml-sp: /logout could not read POST body",
+      ),
     }
   }
 
@@ -112,7 +114,8 @@ export async function initiateSpLogout(
         ? NAME_ID_FORMAT_URN[config.idp.nameIdFormat]
         : NAME_ID_FORMAT_URN.persistent
 
-  const spEntityId = deriveSpEntityId(
+  const spEntityId = resolveSpEntityId(
+    config,
     ctx.dispatch.issuerUrl,
     ctx.tenant.id,
     methodId,

package/src/methods/saml-sp/sls.ts

@@ -33,7 +33,7 @@ import { authError } from "../../types/error"
 import type { MethodContext, MethodResult } from "../../types/method"
 import { isErr } from "../../types/result"
 
-import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import { buildSamlInstance, resolveSpEntityId } from "./saml-instance"
 import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
 
 /** Minimal view of node-saml's `Profile` — never leaked publicly. */
@@ -79,7 +79,8 @@ export async function consumeSls(
     }
   }
 
-  const spEntityId = deriveSpEntityId(
+  const spEntityId = resolveSpEntityId(
+    config,
     ctx.dispatch.issuerUrl,
     ctx.tenant.id,
     methodId,

package/src/methods/saml-sp/types.ts

@@ -152,6 +152,80 @@ export type SamlSpConfig = {
   idpInitiated?: SamlIdpInitiatedConfig
   /** Clock skew allowance for `NotBefore` / `NotOnOrAfter`. Seconds. */
   clockSkewSeconds?: number
+  /**
+   * Override the derived SP entityID.
+   *
+   * By default the entityID is derived as
+   * `<issuerUrl>/<tenantId>/<methodId>` (SAML-AD5) — stable, no config
+   * required, and guaranteed to match what SP metadata publishes. Set
+   * this **only** to adopt an entityID that already exists at the IdP,
+   * so an existing SAML app can be migrated without the customer
+   * editing their production SSO config.
+   *
+   * The override flows through every consumer at once — `AuthnRequest`
+   * issuer, `AudienceRestriction` validation, SP metadata, and logout
+   * messages — so the anti-drift invariant holds either way. Changing
+   * it on a live connection invalidates the IdP-side trust config;
+   * treat it as an IdP-coordination event.
+   */
+  spEntityId?: string
+  /**
+   * Set `ForceAuthn="true"` on the outbound `AuthnRequest`, asking the
+   * IdP to re-authenticate the user even if it has a live session.
+   * Default `false`.
+   *
+   * Note that this is a *request*: SAML gives the IdP no obligation to
+   * honour it, and there is no way to verify from the Response that it
+   * did. Do not treat a successful assertion as proof of fresh
+   * authentication.
+   */
+  forceAuthn?: boolean
+  /**
+   * Request specific authentication context classes (e.g. MFA) from
+   * the IdP via `<RequestedAuthnContext>`.
+   *
+   * **Omitted ⇒ no `RequestedAuthnContext` element is sent at all**,
+   * which lets the IdP apply its own sign-on policy. That is the right
+   * default for nearly every deployment: a `RequestedAuthnContext` the
+   * IdP cannot satisfy exactly is answered with `NoAuthnContext`
+   * instead of a login, and an MFA policy at the IdP is a common way
+   * to *not* satisfy `PasswordProtectedTransport` under
+   * `Comparison="exact"`.
+   *
+   * Set it only when the IdP has told you which class refs it honours.
+   * `comparison` maps to the `Comparison` attribute and defaults to
+   * `"exact"`; `"minimum"` is usually the safer choice when requesting
+   * MFA.
+   *
+   * Requesting a context does **not** verify one was used — read
+   * `SamlSpProperties.authnContextClassRef` for what the IdP actually
+   * asserted.
+   */
+  requestedAuthnContext?: {
+    /** Full URNs, e.g. `urn:oasis:names:tc:SAML:2.0:ac:classes:MultiFactorAuthn`. */
+    classRefs: ReadonlyArray<string>
+    comparison?: "exact" | "minimum" | "maximum" | "better"
+  }
+  /**
+   * Require the `<saml:Assertion>` itself to carry a valid XML-DSig.
+   * **Defaults to `true` and should stay that way** — the identity,
+   * conditions, and audience all live inside the assertion, so signing
+   * it is what actually binds them.
+   *
+   * Set `false` only for an IdP that signs the outer `<Response>` and
+   * nothing else, and only together with `requireSignedResponse: true`.
+   * The schema refuses to let both be off.
+   */
+  requireSignedAssertion?: boolean
+  /**
+   * Require the outer `<samlp:Response>` to carry a valid XML-DSig.
+   * Default `false` — requiring it is stricter than the Okta / Entra
+   * default and would reject the majority of real IdPs. Enable it for
+   * an IdP that signs the Response, either as defence in depth
+   * alongside a signed assertion or (with
+   * `requireSignedAssertion: false`) as the only signature on offer.
+   */
+  requireSignedResponse?: boolean
 }
 
 /**
@@ -197,6 +271,27 @@ export type SamlSpProperties = {
   sessionIndex?: string
   /** Unix ms — the assertion's `AuthnInstant`. */
   authnInstant: number
+  /**
+   * Unix ms — the `AuthnStatement/@SessionNotOnOrAfter` the IdP
+   * asserted, when it supplied one. This is the IdP's own view of when
+   * its session for this user expires.
+   *
+   * The library does **not** act on it: token and session lifetimes are
+   * host policy, and this library owns no session. Hosts that want
+   * "when their IdP session ends, ours ends" should clamp their own
+   * session/token TTL to this value in the `success` callback.
+   */
+  sessionNotOnOrAfter?: number
+  /**
+   * The `AuthnContext/AuthnContextClassRef` the IdP actually asserted —
+   * i.e. how it says it authenticated the user. Absent when the
+   * assertion carries none.
+   *
+   * This is the value to check for step-up decisions ("was this really
+   * MFA?"). `SamlSpConfig.requestedAuthnContext` only *asks*; this is
+   * the answer, and the two can differ.
+   */
+  authnContextClassRef?: string
   raw: {
     responseXml: string
   }