@voltro/plugin-sso-saml 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { ColumnDefinition } from '@voltro/database';
+import { Effect } from 'effect';
+import { HttpClient } from '@effect/platform';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { TableIndex } from '@voltro/database';
+import { TableLike } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/**
+ * A DataStore-backed {@link SamlLogoutStore}. `save` deletes any prior row for
+ * the key then inserts (a fresh login replaces the record), `load` reads +
+ * prunes on expiry, `remove` deletes (one-shot). Shared across replicas because
+ * the store is shared. `ttlMs` bounds how long a login's logout state stays
+ * valid (a stale row reads as absent and is pruned).
+ */
+export declare const dataStoreLogoutStore: (store: LogoutSessionStore, ttlMs?: number) => SamlLogoutStore;
+
+/**
+ * A DataStore-backed {@link SamlCacheProvider}. `saveAsync` INSERTs the request
+ * id (the `unique` column makes a concurrent duplicate insert throw → treated
+ * as "already present", i.e. a replay), `getAsync` reads it, `removeAsync`
+ * deletes it (one-time consumption). Shared across replicas because the store
+ * is shared.
+ *
+ * `ttlMs` bounds how long an outstanding request stays valid — a stale row past
+ * the window reads as absent (and is pruned on read), so an unconsumed request
+ * can't be replayed indefinitely.
+ */
+export declare const dataStoreReplayCache: (store: ReplayCacheStore, ttlMs?: number) => SamlCacheProvider;
+
+/** node-saml's `profile` object → a normalized identity. node-saml flattens
+ *  single-valued attributes onto the profile, and exposes the rest under
+ *  `attributes`. We pick the common claim URIs IdPs send. */
+export declare const extractProfile: (profile: Record<string, unknown>) => SamlProfileResult;
+
+/**
+ * Fetch + parse the IdP metadata at `url` via @effect/platform `HttpClient`.
+ * The returned Effect requires an `HttpClient` in context (provide
+ * `FetchHttpClient.layer` at the edge). Fetch failures → {@link SamlMetadataFetchError};
+ * a fetched-but-unparseable document → {@link SamlMetadataParseError}.
+ */
+export declare const fetchIdpMetadata: (url: string) => Effect.Effect<IdpMetadata, SamlMetadataFetchError | SamlMetadataParseError, HttpClient.HttpClient>;
+
+/** The two IdP values a metadata document supplies. */
+export declare interface IdpMetadata {
+    /** The `SingleSignOnService` `Location` (HTTP-Redirect binding preferred) — node-saml's `entryPoint`. */
+    readonly entryPoint: string;
+    /** The IdP signing certificate PEM body (from the signing `KeyDescriptor`). */
+    readonly idpCert: string;
+    /** The IdP `SingleLogoutService` `Location`, when the metadata declares one — node-saml's `logoutUrl`. */
+    readonly logoutUrl?: string;
+    /** The IdP `entityID` — node-saml's `idpIssuer`. */
+    readonly issuer?: string;
+}
+
+export declare const LOGOUT_SESSION_TABLE = "_voltro_saml_logout";
+
+/** Narrow slice of the framework DataStore the SLO store needs. */
+export declare interface LogoutSessionStore {
+    query: (descriptor: Record<string, unknown>) => Promise<ReadonlyArray<Record<string, unknown>>>;
+    insert: (table: string, row: Record<string, unknown>) => Promise<unknown>;
+    delete: (table: string, primaryKey: string) => Promise<unknown>;
+}
+
+/**
+ * In-memory {@link SamlLogoutStore} — the single-replica / dev default. Correct
+ * for one process; under >1 replica use {@link dataStoreLogoutStore} so a login
+ * on one replica can log out on another.
+ */
+export declare const memoryLogoutStore: (ttlMs?: number) => SamlLogoutStore;
+
+/**
+ * In-memory {@link SamlCacheProvider} — the single-replica / dev default.
+ * Correct for one process; under >1 replica use {@link dataStoreReplayCache}.
+ */
+export declare const memoryReplayCache: (ttlMs?: number) => SamlCacheProvider;
+
+/**
+ * Parse an IdP SAML-metadata XML string → the SSO endpoint + signing cert.
+ * Pure (no I/O) so it is unit-testable against a fixture document.
+ */
+export declare const parseIdpMetadata: (xml: string, url: string) => Effect.Effect<IdpMetadata, SamlMetadataParseError>;
+
+export declare const REPLAY_CACHE_TABLE = "_voltro_saml_replay";
+
+/** Narrow slice of the framework DataStore this cache needs. */
+export declare interface ReplayCacheStore {
+    query: (descriptor: Record<string, unknown>) => Promise<ReadonlyArray<Record<string, unknown>>>;
+    insert: (table: string, row: Record<string, unknown>) => Promise<unknown>;
+    delete: (table: string, primaryKey: string) => Promise<unknown>;
+}
+
+/** node-saml's `{ value, createdAt }` cache item (see @node-saml/node-saml types). */
+export declare interface SamlCacheItem {
+    readonly value: string;
+    readonly createdAt: number;
+}
+
+/** The node-saml `CacheProvider` contract (structurally — we don't import its type). */
+export declare interface SamlCacheProvider {
+    saveAsync(key: string, value: string): Promise<SamlCacheItem | null>;
+    getAsync(key: string): Promise<string | null>;
+    removeAsync(key: string | null): Promise<string | null>;
+}
+
+/** The persisted SLO record: a login's logout state, one-shot per `sloKey`. */
+export declare interface SamlLogoutRecord extends SamlLogoutSubject {
+    readonly sloKey: string;
+}
+
+/** Store contract the SLO record needs — save at ACS, load + consume at logout. */
+export declare interface SamlLogoutStore {
+    /** Persist the logout state under `sloKey` (overwrites any prior row). */
+    save(record: SamlLogoutRecord): Promise<void>;
+    /** Load the logout state for `sloKey`, or `null` when unknown / expired. */
+    load(sloKey: string): Promise<SamlLogoutSubject | null>;
+    /** Consume (delete) the record — logout is one-shot. */
+    remove(sloKey: string): Promise<void>;
+}
+
+/** The NameID + SessionIndex a `LogoutRequest` references (from the login assertion). */
+export declare interface SamlLogoutSubject {
+    /** The IdP `NameID` value (the login subject). */
+    readonly nameId: string;
+    /** The `NameID` `Format` URI, echoed on the LogoutRequest (optional). */
+    readonly nameIdFormat?: string;
+    /** The `SessionIndex` from the assertion (the IdP session to terminate). */
+    readonly sessionIndex?: string;
+}
+
+/**
+ * The slice of a built `Table` this package exposes. Annotated explicitly — the
+ * full inferred `Table` type leaks @voltro/database's private column-builder
+ * class across the package boundary (TS4094); the schema contribution only
+ * needs the name, columns, and indexes.
+ */
+export declare interface SamlLogoutTable extends TableLike {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+}
+
+/**
+ * The SLO-session table: one row per active login, holding the NameID +
+ * SessionIndex a LogoutRequest must reference. `sloKey` is the opaque cookie
+ * key (unique — a new login replaces the row); `createdAtMs` drives the TTL
+ * sweep. Built from column helpers so the DDL compiler handles per-dialect
+ * divergence.
+ */
+export declare const samlLogoutTable: SamlLogoutTable;
+
+/** The SLO-session table, ready to spread into `extendSchema.tables`. */
+export declare const samlLogoutTables: ReadonlyArray<SamlLogoutTable>;
+
+/** Fetching the IdP metadata document failed (network / non-2xx / empty body). */
+export declare class SamlMetadataFetchError extends SamlMetadataFetchError_base {
+}
+
+declare const SamlMetadataFetchError_base: Schema.TaggedErrorClass<SamlMetadataFetchError, "SamlMetadataFetchError", {
+    readonly _tag: Schema.tag<"SamlMetadataFetchError">;
+} & {
+    /** The metadata URL that was requested (safe to log — it's config, not a secret). */
+    url: typeof Schema.String;
+    /** Coarse reason (`status 404`, `network`, `empty-body`). Never a secret. */
+    reason: typeof Schema.String;
+}>;
+
+/** The IdP metadata XML was fetched but the SSO endpoint / signing cert could not be extracted. */
+export declare class SamlMetadataParseError extends SamlMetadataParseError_base {
+}
+
+declare const SamlMetadataParseError_base: Schema.TaggedErrorClass<SamlMetadataParseError, "SamlMetadataParseError", {
+    readonly _tag: Schema.tag<"SamlMetadataParseError">;
+} & {
+    url: typeof Schema.String;
+    /** What was missing (`no-entryPoint`, `no-signing-cert`). */
+    reason: typeof Schema.String;
+}>;
+
+/** The normalized identity extracted from a validated assertion. */
+export declare interface SamlProfileResult {
+    readonly nameId: string;
+    readonly email: string | null;
+    readonly displayName: string | null;
+    readonly attributes: Record<string, unknown>;
+}
+
+/**
+ * The slice of a built `Table` this package exposes. Annotated explicitly —
+ * the full inferred `Table` type leaks @voltro/database's private
+ * column-builder class across the package boundary (TS4094); the schema
+ * contribution only needs the name, columns, and indexes.
+ */
+export declare interface SamlReplayTable extends TableLike {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+}
+
+/**
+ * The replay cache table: one row per outstanding AuthnRequest id. `requestId`
+ * is the node-saml cache KEY (the SAML request/response id); `instant` is the
+ * ISO timestamp node-saml stores as the value; `createdAtMs` is the epoch-ms
+ * the pruning window measures against. Built purely from column helpers so the
+ * DDL compiler handles per-dialect divergence.
+ */
+export declare const samlReplayTable: SamlReplayTable;
+
+/** The replay-cache table, ready to spread into `extendSchema.tables`. */
+export declare const samlReplayTables: ReadonlyArray<SamlReplayTable>;
+
+export declare interface SamlSpConfig {
+    /** SP entity id (audience). e.g. `https://app.example.com/saml/metadata`. */
+    readonly entityId: string;
+    /** Assertion Consumer Service URL the IdP POSTs the response to. */
+    readonly acsUrl: string;
+    /** SP Single Logout Service URL — where the IdP sends LogoutRequest /
+     *  LogoutResponse (HTTP-Redirect binding). Advertised in the metadata when set. */
+    readonly sloUrl?: string;
+    /** Whether the SP signs its AuthnRequest / LogoutRequest — flips the metadata
+     *  `AuthnRequestsSigned` flag. Set when `privateKey` is configured. */
+    readonly authnRequestsSigned?: boolean;
+    /** The SP signing certificate (PEM body) — published in a signing
+     *  `KeyDescriptor` so the IdP can verify the SP's request signatures. */
+    readonly signingCert?: string;
+}
+
+export declare const samlSsoPlugin: (options: SamlSsoPluginOptions) => VoltroPlugin;
+
+export declare interface SamlSsoPluginOptions {
+    readonly idp: {
+        /** IdP SSO redirect endpoint (where the AuthnRequest goes). Omit ONLY when
+         *  `metadataUrl` is set — the endpoint is then read from the IdP metadata. */
+        readonly entryPoint?: string;
+        /** IdP signing certificate (PEM body) — used to verify the assertion. Omit
+         *  ONLY when `metadataUrl` is set (the cert is read + auto-rotated from it). */
+        readonly idpCert?: string;
+        /** Expected issuer (IdP entity id). Optional. */
+        readonly issuer?: string;
+        /** IdP Single Logout endpoint (where a LogoutRequest / LogoutResponse goes).
+         *  Optional — falls back to the metadata `SingleLogoutService` when fetched. */
+        readonly logoutUrl?: string;
+        /**
+         * IdP SAML metadata document URL. When set, the plugin FETCHES it at boot
+         * (via @effect/platform HttpClient) and reads `entryPoint` + the signing
+         * `idpCert` (+ `logoutUrl`) from it — so cert rotation on the IdP no longer
+         * needs a manual `idpCert` edit. Re-fetched every `metadataRefreshMs`.
+         * `entryPoint` / `idpCert` supplied explicitly still win as a fallback if
+         * the fetch fails.
+         */
+        readonly metadataUrl?: string;
+        /** How often to re-fetch `metadataUrl` (ms). Default 12h. `0` disables refresh. */
+        readonly metadataRefreshMs?: number;
+    };
+    readonly sp: SamlSpConfig;
+    /** HMAC secret for the minted session cookie. */
+    readonly sessionSecret: string;
+    /** Map the validated SAML identity → an app Subject (look up / JIT-create a
+     *  user). Return `null` to reject the login. */
+    readonly onLogin: (profile: SamlProfileResult) => Promise<Subject | null> | Subject | null;
+    /** Where to send the browser after a successful login. Default `/`. */
+    readonly successRedirect?: string;
+    /** Where to send the browser after logout completes. Default `/`. */
+    readonly logoutRedirect?: string;
+    /** Session cookie name. Default `voltro:session`. */
+    readonly cookieName?: string;
+    /** Mount prefix. Default `/saml`. */
+    readonly basePath?: string;
+    /** Lifetime of the minted session cookie, in seconds. Default 7 days. */
+    readonly sessionTtlSeconds?: number;
+    /**
+     * Encrypted-assertion support. The SP's PRIVATE key (PEM) node-saml uses to
+     * DECRYPT an `EncryptedAssertion` the IdP sends. Sourced from env / a secrets
+     * backend — NEVER a literal, NEVER logged. When set, encrypted assertions
+     * decrypt transparently; unencrypted ones still work.
+     */
+    readonly decryptionPvk?: string;
+    /**
+     * SP request signing. The SP PRIVATE key (PEM) node-saml uses to SIGN the
+     * AuthnRequest + LogoutRequest, so the IdP can verify they came from this SP.
+     * Sourced from env / a secrets backend — NEVER a literal, NEVER logged. When
+     * set, the SP metadata advertises `AuthnRequestsSigned="true"`.
+     */
+    readonly privateKey?: string;
+    /** The SP signing certificate (PEM) that pairs with `privateKey` — published in
+     *  the SP metadata so the IdP can verify the SP's request signatures. */
+    readonly signingCert?: string;
+    /**
+     * Clock-skew tolerance for assertion timestamp validation, in ms. IdP and SP
+     * clocks drift; a small window (e.g. 5000) avoids spurious `NotBefore` /
+     * `NotOnOrAfter` rejections. Wired to node-saml's `acceptedClockSkewMs`.
+     */
+    readonly acceptedClockSkewMs?: number;
+    /**
+     * Assertion-replay / `InResponseTo` protection. When enabled, node-saml is
+     * configured with `validateInResponseTo: 'always'` and a cache: the
+     * AuthnRequest id is stored at login and CONSUMED (one-time) at the ACS, so
+     * 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.
+     * - `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).
+     */
+    readonly replayProtection?: boolean | {
+        readonly store: true;
+        readonly ttlMs?: number;
+    };
+    /**
+     * Single Logout (SLO) state store. SP-initiated logout must reference the
+     * NameID + SessionIndex from the login, so they're persisted at ACS keyed by
+     * an opaque companion cookie.
+     *
+     * - `false` / omitted (default) — in-PROCESS store (single replica only).
+     * - `{ store: true }` — backed by the framework DataStore (a contributed
+     *   `_voltro_saml_logout` table), so a login on one replica can log out on
+     *   another. Requires `store:write`; the plugin declares it.
+     */
+    readonly sloStore?: boolean | {
+        readonly store: true;
+    };
+    readonly name?: string;
+}
+
+/** SP metadata XML to hand the IdP (it tells the IdP the ACS URL + entity id). */
+export declare const spMetadataXml: (sp: SamlSpConfig) => string;
+
+export { }