@basaltkit/auth-saml 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basalt Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @basaltkit/auth-saml
+
+SAML 2.0 single sign-on for [`@basaltkit/auth`](https://www.npmjs.com/package/@basaltkit/auth). SP-initiated
+login for enterprise IdPs (ADFS, Okta, OneLogin, Azure AD, Shibboleth…) that speak
+SAML rather than OIDC.
+
+Signature verification, XML canonicalization and the SAML protocol are handled by
+[`@node-saml/node-saml`](https://github.com/node-saml/node-saml) — a vetted
+XML-DSig implementation. This package only wires a validated assertion into
+`Auth.socialLogin`, so a user proven by the IdP is logged in with the same tokens
+as any other login. **This deliberately does not hand-roll SAML crypto.**
+
+> For modern IdPs prefer OIDC — `@basaltkit/auth`'s `oidcProvider` /
+> `discoverOidcProvider` cover Okta, Azure AD, Auth0, Google Workspace and
+> Keycloak with no extra dependency. Reach for SAML only when the IdP requires it.
+
+## Install
+
+```bash
+pnpm add @basaltkit/auth-saml @node-saml/node-saml   # node-saml is a peer dependency
+```
+
+## Usage
+
+```ts
+import { authPlugin, authRoutes } from '@basaltkit/auth'
+import { samlPlugin, samlRoutes } from '@basaltkit/auth-saml'
+
+createApp({
+  plugins: [
+    authPlugin({ users, secret: env.APP_SECRET }),
+    fastifyPlugin({ routes: [...authRoutes(), ...samlRoutes()] }),
+    samlPlugin({
+      providers: [
+        {
+          name: 'okta',
+          entryPoint: 'https://acme.okta.com/app/…/sso/saml',
+          idpCert: env.OKTA_IDP_CERT,          // the IdP's signing certificate (PEM)
+          issuer: 'https://app.example.com/sp', // your SP entity id
+          callbackUrl: 'https://app.example.com/auth/saml/okta/acs',
+        },
+      ],
+    }),
+  ],
+})
+```
+
+Three routes per provider:
+
+| Route | Purpose |
+|---|---|
+| `GET  /auth/saml/:provider/login` | Redirects the browser to the IdP (SP-initiated). |
+| `POST /auth/saml/:provider/acs` | The IdP POSTs the signed `SAMLResponse` here; on a valid assertion the user is logged in. Responds with JSON tokens, or pass `samlRoutes({ successRedirect })` to bounce back to your SPA. |
+| `GET  /auth/saml/:provider/metadata` | SP metadata XML — hand it to the IdP admin to register the app. |
+
+The user is matched by **email** (find-or-create, passwordless); a validated
+assertion is trusted, so `emailVerified` is set. Read the email from a specific
+attribute with `emailAttribute` on the provider (default: `email`, common email
+claims, or an email-shaped `NameID`).
+
+`samlPlugin` is adapter-agnostic — the Fastify, Express and Hono adapters all
+parse the `application/x-www-form-urlencoded` ACS POST. Register it after `authPlugin`.

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { BasaltError } from '@basaltkit/core';
+import { Auth, PublicUser, TokenPair } from '@basaltkit/auth';
+import { BasaltRoute } from '@basaltkit/http';
+
+declare class SamlProviderUnknownError extends BasaltError {
+    readonly status = 404;
+    constructor(name: string);
+}
+declare class SamlResponseInvalidError extends BasaltError {
+    readonly status = 400;
+    constructor(detail?: string);
+}
+/** The subset of a node-saml profile we read. */
+interface SamlProfile {
+    nameID?: string;
+    email?: string;
+    [claim: string]: unknown;
+}
+/**
+ * The node-saml surface this package uses — kept minimal so the underlying
+ * library (which does the XML-DSig verification) is injectable in tests.
+ */
+interface SamlClient {
+    getAuthorizeUrlAsync(relayState: string, host: string | undefined, options: Record<string, unknown>): Promise<string>;
+    validatePostResponseAsync(container: Record<string, string>): Promise<{
+        profile: SamlProfile | null;
+        loggedOut: boolean;
+    }>;
+    generateServiceProviderMetadata(decryptionCert: string | null, signingCert?: string | null): string;
+}
+interface SamlProvider {
+    name: string;
+    /** IdP Single-Sign-On URL (HTTP-Redirect binding). */
+    entryPoint: string;
+    /** IdP signing certificate(s) (PEM). Used to verify the assertion signature. */
+    idpCert: string | string[];
+    /** SP entity id (this app's issuer). */
+    issuer: string;
+    /** ACS URL the IdP POSTs the SAMLResponse to. */
+    callbackUrl: string;
+    /** Attribute to read the email from. Default: `email` / common email claims / an email-shaped NameID. */
+    emailAttribute?: string;
+}
+interface SamlOptions {
+    /**
+     * Factory for the underlying SAML client. Default: `@node-saml/node-saml`.
+     * Injectable for tests so the crypto path is exercised by the real library
+     * in production but stubbed in unit tests.
+     */
+    createClient?: (provider: SamlProvider) => SamlClient;
+    /** Host used when building the AuthnRequest (optional). */
+    host?: string;
+}
+/** Extracts the user's email from a validated assertion. */
+declare function extractEmail(profile: SamlProfile, attribute?: string): string | undefined;
+/**
+ * SAML 2.0 SP-initiated SSO. Signature verification, canonicalization and the
+ * SAML protocol are delegated to `@node-saml/node-saml`; this only wires the
+ * result into {@link Auth.socialLogin}. A validated assertion is trusted, so the
+ * user is logged in with `emailVerified: true`.
+ */
+declare class Saml {
+    private readonly auth;
+    private readonly options;
+    private readonly providers;
+    private readonly clients;
+    constructor(auth: Auth, providers: SamlProvider[], options?: SamlOptions);
+    names(): string[];
+    private lookup;
+    /** The IdP redirect URL to start login (SP-initiated). */
+    loginUrl(name: string, relayState?: string): Promise<string>;
+    /** Validates a posted SAMLResponse and logs the user in by email. */
+    consume(name: string, body: {
+        SAMLResponse: string;
+        RelayState?: string;
+    }): Promise<{
+        user: PublicUser;
+        tokens: TokenPair;
+        created: boolean;
+    }>;
+    /** SP metadata XML (hand this to the IdP admin to register the SP). */
+    metadata(name: string): string;
+}
+declare const SAML_SSO: _basaltkit_core.Token<Saml>;
+interface SamlPluginOptions extends SamlOptions {
+    providers: SamlProvider[];
+}
+/**
+ * Registers the {@link Saml} service (token {@link SAML_SSO}). Adapter-agnostic —
+ * the Fastify, Express and Hono adapters all parse the
+ * `application/x-www-form-urlencoded` ACS POST. Register it after `authPlugin`.
+ */
+declare function samlPlugin(options: SamlPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+interface SamlRoutesOptions {
+    /**
+     * When set, the ACS redirects the browser here after login with
+     * `#access_token=…&refresh_token=…`. Omitted → JSON `{ user, accessToken, refreshToken }`.
+     */
+    successRedirect?: string;
+}
+/**
+ * Ready-made SAML routes:
+ *  - `GET  /auth/saml/:provider/login`    → 302 to the IdP.
+ *  - `POST /auth/saml/:provider/acs`      → validate the assertion and log in.
+ *  - `GET  /auth/saml/:provider/metadata` → SP metadata XML.
+ */
+declare function samlRoutes(options?: SamlRoutesOptions): BasaltRoute[];
+
+export { SAML_SSO, Saml, type SamlClient, type SamlOptions, type SamlPluginOptions, type SamlProfile, type SamlProvider, SamlProviderUnknownError, SamlResponseInvalidError, type SamlRoutesOptions, extractEmail, samlPlugin, samlRoutes };