@voltro/plugin-sso-saml 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -290,6 +290,33 @@ export declare interface SamlSsoPluginOptions {
      * `NotOnOrAfter` rejections. Wired to node-saml's `acceptedClockSkewMs`.
      */
     readonly acceptedClockSkewMs?: number;
+    /**
+     * Require the `<samlp:Response>` ENVELOPE to carry its own signature, in
+     * addition to the assertion signature.
+     *
+     * **The assertion signature is always required and is not configurable.** It
+     * is the one that matters: only signature-covered XML is ever read, and the
+     * assertion is what carries the NameID, the attributes, the audience
+     * restriction, the validity window and the `SubjectConfirmationData`. An
+     * envelope signature adds coverage of the response-level `Status`,
+     * `Destination` and `InResponseTo` — real, but a smaller surface than the
+     * name suggests.
+     *
+     * - `false` (default) — assertion-signed responses are accepted. This is
+     *   Okta's default application profile ("Sign assertion", response
+     *   unsigned), and Azure AD's, so it is what most deployments send.
+     * - `true` — both signatures required. Set this when your IdP signs the
+     *   response (it is one checkbox on Okta and Azure AD) — it is the stronger
+     *   posture and costs nothing once the IdP is configured for it.
+     *
+     * Why the default is `false`: it was effectively `true` before this option
+     * existed (node-saml's own default) and there was no way to say otherwise, so
+     * an Okta deployment on the default application could not log in at all. A
+     * refusal an operator cannot configure their way out of is not a stronger
+     * posture — it is a wall people climb by abandoning the plugin. The floor
+     * that actually protects the identity, `wantAssertionsSigned`, never moved.
+     */
+    readonly wantAuthnResponseSigned?: boolean;
     /**
      * Assertion-replay / `InResponseTo` protection. When enabled, node-saml is
      * configured with `validateInResponseTo: 'always'` and a cache: the
@@ -297,17 +324,32 @@ export declare interface SamlSsoPluginOptions {
      * a captured `SAMLResponse` can't be replayed and an unsolicited IdP-initiated
      * POST (no matching request) is rejected.
      *
-     * - `false` (default) — OFF (node-saml default; single captured response
-     *   replayable within its validity window). Keep the default only for a
-     *   single-replica dev/PoC.
+     * - `{ store: true }` (**default**) — ON, backed by the framework DataStore
+     *   (a contributed `_voltro_saml_replay` table). Shared across replicas, so
+     *   a login on one process and its ACS on another still pair up. Requires
+     *   `store:write` (table DDL); the plugin declares it. `ttlMs` bounds how
+     *   long an outstanding request stays valid (default 10 min).
      * - `true` — ON with an in-PROCESS cache. Correct for ONE replica; under
      *   >1 replica a login and its ACS can land on different processes and the
      *   check breaks. Boot warns when this is used.
-     * - `{ store: true }` — ON backed by the framework DataStore (a contributed
-     *   `_voltro_saml_replay` table). Shared across replicas — the correct
-     *   production choice. Requires `store:write` (table DDL); the plugin
-     *   declares it. `ttlMs` bounds how long an outstanding request stays valid
-     *   (default 10 min).
+     * - `false` — OFF. **This is also the switch that re-enables IdP-INITIATED
+     *   SSO** (the app-tile flow) — see below.
+     *
+     * **What ON costs: unsolicited responses are refused.** `validateInResponseTo:
+     * 'always'` means a `SAMLResponse` with no `InResponseTo` — which is exactly
+     * an IdP-initiated login, started from the Okta / Azure dashboard tile rather
+     * than from `/saml/login` — is rejected. There is no way to keep replay
+     * protection and IdP-initiated SSO at the same time, and the reason is
+     * structural rather than an implementation limit: the protection IS the
+     * requirement that the response answer a request this SP issued, and an
+     * unsolicited response answers none. `'ifPresent'` looks like the compromise
+     * and is not one — an attacker replaying a captured response simply DELETES
+     * the attribute and the check declines to run.
+     *
+     * So if you need the app tile, set `replayProtection: false` deliberately and
+     * know what you are accepting: a captured response is replayable for as long
+     * as its assertion is valid. Prefer pointing users at `/saml/login`, and
+     * prefer setting `wantAuthnResponseSigned: true` if you must run unsolicited.
      */
     readonly replayProtection?: boolean | {
         readonly store: true;
@@ -326,6 +368,19 @@ export declare interface SamlSsoPluginOptions {
     readonly sloStore?: boolean | {
         readonly store: true;
     };
+    /**
+     * Namespace for this plugin's HTTP mount + inspect surface. Default `sso-saml`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-sso-saml#eu`). Not a rename — for that use `alias`.
+     */
     readonly name?: string;
 }