@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/dist/routes/auth.js

@@ -1,9 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { Hono } from 'hono';
 import { statusFor, toWireError } from '../errors.js';
 import { encodeSessionToken } from '../middleware/auth.js';
+import { withholdFromReplay } from '../middleware/idempotency.js';
+import { tenantResourceAccess } from './tenant-access.js';
 const DEFAULT_STATE_TTL_MS = 10 * 60 * 1000;
 /**
  * Build the auth router. Two Hono routers are returned — one gated
@@ -20,6 +22,11 @@ export function authRouters(options) {
     const refreshToken = options.refreshToken;
     const stateTtlMs = options.stateTtlMs ?? DEFAULT_STATE_TTL_MS;
     const authed = new Hono();
+    // The provider catalog is tenant-wide: any GET (the list, one provider,
+    // its sign-in URLs) needs `read` on the tenant, any change `admin`.
+    const providerAccess = tenantResourceAccess(options.authorizer);
+    authed.use('/providers', providerAccess);
+    authed.use('/providers/*', providerAccess);
     // ---------- GET /providers ----------
     authed.get('/providers', async (c) => {
         const tenantId = c.get('tenantId');
@@ -50,9 +57,94 @@ export function authRouters(options) {
             }, requestId));
         }
         const outcome = await identityProvider.register({ tenantId, config: parsed.value });
+        if (outcome.kind === 'invalid') {
+            c.status(statusFor('identity-provider-invalid'));
+            return c.json(toWireError({
+                code: 'identity-provider-invalid',
+                message: outcome.message,
+                providerId: parsed.value.providerId,
+            }, requestId));
+        }
         c.status(201);
-        return c.json({ providerId: outcome.providerId });
+        return c.json({
+            providerId: outcome.providerId,
+            ...(outcome.provider !== undefined && {
+                provider: serializeProviderConfig(outcome.provider),
+            }),
+        });
+    });
+    // ---------- GET /providers/:providerId ----------
+    authed.get('/providers/:providerId', async (c) => {
+        const tenantId = c.get('tenantId');
+        const providerId = c.req.param('providerId');
+        const found = await identityProvider.get({ tenantId, providerId });
+        if (found === null)
+            return providerNotFound(c, providerId);
+        return c.json(serializeProviderConfig(found));
     });
+    // ---------- GET /providers/:providerId/sign-in ----------
+    const signInUrls = identityProvider.signInUrls;
+    if (signInUrls !== undefined) {
+        authed.get('/providers/:providerId/sign-in', async (c) => {
+            const requestId = c.get('requestId');
+            const tenantId = c.get('tenantId');
+            const providerId = c.req.param('providerId');
+            const asked = c.req.query('kind');
+            if (asked !== undefined && asked !== 'oidc' && asked !== 'saml' && asked !== 'oauth2') {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({ code: 'bad-input', message: '`kind` must be `oidc`, `saml` or `oauth2`' }, requestId));
+            }
+            const registered = await identityProvider.get({ tenantId, providerId });
+            const kind = asked ?? registered?.kind;
+            if (kind === undefined) {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({
+                    code: 'bad-input',
+                    message: `No identity provider "${providerId}" is registered yet: say which \`kind\` it will be (\`?kind=oidc\` or \`?kind=saml\`)`,
+                }, requestId));
+            }
+            const signIn = await signInUrls({ tenantId, providerId, kind });
+            if (signIn === undefined) {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({
+                    code: 'bad-input',
+                    message: `This deployment doesn't sign in with \`${kind}\` providers`,
+                }, requestId));
+            }
+            return c.json({ providerId, kind, signIn, registered: registered !== null });
+        });
+    }
+    // ---------- PATCH /providers/:providerId ----------
+    const update = identityProvider.update;
+    if (update !== undefined) {
+        authed.patch('/providers/:providerId', async (c) => {
+            const requestId = c.get('requestId');
+            const tenantId = c.get('tenantId');
+            const providerId = c.req.param('providerId');
+            const parsedJson = await parseJsonBody(c);
+            if (parsedJson.kind === 'err') {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError(parsedJson.error, requestId));
+            }
+            const existing = await identityProvider.get({ tenantId, providerId });
+            if (existing === null)
+                return providerNotFound(c, providerId);
+            const merged = mergeProviderChanges(existing, parsedJson.value);
+            const parsed = merged.kind === 'err' ? merged : parseProviderConfig(merged.value);
+            if (parsed.kind === 'err') {
+                c.status(statusFor(parsed.error.code));
+                return c.json(toWireError(parsed.error, requestId));
+            }
+            const outcome = await update({ tenantId, config: parsed.value });
+            if (outcome.kind === 'not-found')
+                return providerNotFound(c, providerId);
+            if (outcome.kind === 'invalid') {
+                c.status(statusFor('identity-provider-invalid'));
+                return c.json(toWireError({ code: 'identity-provider-invalid', message: outcome.message, providerId }, requestId));
+            }
+            return c.json({ providerId, provider: serializeProviderConfig(outcome.provider) });
+        });
+    }
     // ---------- POST /providers/:providerId/unregister ----------
     authed.post('/providers/:providerId/unregister', async (c) => {
         const requestId = c.get('requestId');
@@ -69,89 +161,100 @@ export function authRouters(options) {
         }
         return c.json({ providerId, unregistered: true });
     });
-    // ---------- POST /login/:providerId ----------
-    authed.post('/login/:providerId', async (c) => {
-        const requestId = c.get('requestId');
-        const tenantId = c.get('tenantId');
-        const providerId = c.req.param('providerId');
-        const config = await identityProvider.get({ tenantId, providerId });
-        if (config === null) {
-            c.status(statusFor('identity-provider-not-found'));
-            return c.json(toWireError({
-                code: 'identity-provider-not-found',
-                message: `No identity provider registered with id "${providerId}"`,
-                providerId,
-            }, requestId));
-        }
-        let redirectUri;
-        const parsedBody = await parseOptionalJsonBody(c);
-        if (parsedBody.kind === 'err') {
-            c.status(statusFor('bad-input'));
-            return c.json(toWireError(parsedBody.error, requestId));
-        }
-        if (parsedBody.value !== undefined) {
-            const raw = parsedBody.value.redirectUri;
-            if (raw !== undefined) {
-                if (typeof raw !== 'string' || raw.length === 0) {
-                    c.status(statusFor('bad-input'));
-                    return c.json(toWireError({ code: 'bad-input', message: '`redirectUri` must be a non-empty string' }, requestId));
+    if (exchangeCode !== undefined) {
+        // ---------- POST /login/:providerId ----------
+        authed.post('/login/:providerId', async (c) => {
+            const requestId = c.get('requestId');
+            const tenantId = c.get('tenantId');
+            const providerId = c.req.param('providerId');
+            const found = await identityProvider.get({ tenantId, providerId });
+            if (found === null) {
+                c.status(statusFor('identity-provider-not-found'));
+                return c.json(toWireError({
+                    code: 'identity-provider-not-found',
+                    message: `No identity provider registered with id "${providerId}"`,
+                    providerId,
+                }, requestId));
+            }
+            const config = oauthFlowOf(found);
+            if (config === null) {
+                c.status(statusFor('invalid-provider-config'));
+                return c.json(toWireError({
+                    code: 'invalid-provider-config',
+                    message: `Identity provider "${providerId}" (${found.kind}) signs in through the deployment's own sign-in, not this endpoint`,
+                    providerId,
+                }, requestId));
+            }
+            let redirectUri;
+            const parsedBody = await parseOptionalJsonBody(c);
+            if (parsedBody.kind === 'err') {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError(parsedBody.error, requestId));
+            }
+            if (parsedBody.value !== undefined) {
+                const raw = parsedBody.value.redirectUri;
+                if (raw !== undefined) {
+                    if (typeof raw !== 'string' || raw.length === 0) {
+                        c.status(statusFor('bad-input'));
+                        return c.json(toWireError({ code: 'bad-input', message: '`redirectUri` must be a non-empty string' }, requestId));
+                    }
+                    redirectUri = raw;
                 }
-                redirectUri = raw;
             }
-        }
-        const state = base64Url(randomBytes(32));
-        const codeVerifier = base64Url(randomBytes(64));
-        const codeChallenge = base64Url(createHash('sha256').update(codeVerifier).digest());
-        const effectiveRedirect = redirectUri ??
-            (typeof config.metadata?.defaultRedirectUri === 'string'
-                ? String(config.metadata?.defaultRedirectUri)
-                : '');
-        if (effectiveRedirect.length === 0) {
-            c.status(statusFor('bad-input'));
-            return c.json(toWireError({
-                code: 'bad-input',
-                message: '`redirectUri` must be supplied in the body or via `metadata.defaultRedirectUri` on the provider config',
-            }, requestId));
-        }
-        // OAuth 2.1 BCP redirect-URI allowlist enforcement. Absent /
-        // empty list means pass-through (no allowlist check); populated
-        // list requires an exact-string match against the effective
-        // redirect URI (either the body-supplied value or the resolved
-        // `metadata.defaultRedirectUri`). This is the primary gate — the
-        // callback route re-verifies against the same list for
-        // belt-and-suspenders defense in case the allowlist tightened
-        // between login and callback.
-        if (config.allowedRedirectUris !== undefined &&
-            config.allowedRedirectUris.length > 0 &&
-            !config.allowedRedirectUris.includes(effectiveRedirect)) {
-            c.status(statusFor('redirect-uri-not-allowed'));
-            return c.json(toWireError({
-                code: 'redirect-uri-not-allowed',
-                message: `redirect_uri "${effectiveRedirect}" is not in the provider's allowedRedirectUris list`,
+            const state = base64Url(randomBytes(32));
+            const codeVerifier = base64Url(randomBytes(64));
+            const codeChallenge = base64Url(createHash('sha256').update(codeVerifier).digest());
+            const effectiveRedirect = redirectUri ??
+                (typeof config.metadata?.defaultRedirectUri === 'string'
+                    ? String(config.metadata?.defaultRedirectUri)
+                    : '');
+            if (effectiveRedirect.length === 0) {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError({
+                    code: 'bad-input',
+                    message: '`redirectUri` must be supplied in the body or via `metadata.defaultRedirectUri` on the provider config',
+                }, requestId));
+            }
+            // OAuth 2.1 BCP redirect-URI allowlist enforcement. Absent /
+            // empty list means pass-through (no allowlist check); populated
+            // list requires an exact-string match against the effective
+            // redirect URI (either the body-supplied value or the resolved
+            // `metadata.defaultRedirectUri`). This is the primary gate — the
+            // callback route re-verifies against the same list for
+            // belt-and-suspenders defense in case the allowlist tightened
+            // between login and callback.
+            if (config.allowedRedirectUris !== undefined &&
+                config.allowedRedirectUris.length > 0 &&
+                !config.allowedRedirectUris.includes(effectiveRedirect)) {
+                c.status(statusFor('redirect-uri-not-allowed'));
+                return c.json(toWireError({
+                    code: 'redirect-uri-not-allowed',
+                    message: `redirect_uri "${effectiveRedirect}" is not in the provider's allowedRedirectUris list`,
+                    providerId,
+                }, requestId));
+            }
+            await stateStore.put({
+                state,
+                tenantId,
                 providerId,
-            }, requestId));
-        }
-        await stateStore.put({
-            state,
-            tenantId,
-            providerId,
-            codeVerifier,
-            redirectUri: effectiveRedirect,
-            expiresAt: Date.now() + stateTtlMs,
-        });
-        const authorizationUrl = buildAuthorizationUrl({
-            config,
-            state,
-            codeChallenge,
-            redirectUri: effectiveRedirect,
-        });
-        return c.json({
-            authorizationUrl,
-            state,
-            codeChallenge,
-            codeChallengeMethod: 'S256',
+                codeVerifier,
+                redirectUri: effectiveRedirect,
+                expiresAt: Date.now() + stateTtlMs,
+            });
+            const authorizationUrl = buildAuthorizationUrl({
+                config,
+                state,
+                codeChallenge,
+                redirectUri: effectiveRedirect,
+            });
+            return c.json({
+                authorizationUrl,
+                state,
+                codeChallenge,
+                codeChallengeMethod: 'S256',
+            });
         });
-    });
+    }
     // ---------- POST /refresh ----------
     authed.post('/refresh', async (c) => {
         const requestId = c.get('requestId');
@@ -164,6 +267,15 @@ export function authRouters(options) {
                 message: 'Refresh is only valid for session tokens (`kgi_sk_*`); bearer tokens are managed via `/v1/tokens`',
             }, requestId));
         }
+        if (c.get('sessionCookieName') !== undefined) {
+            // Refresh answers with the new token in its body, which a browser
+            // session must never hand to page scripts: it ends at its TTL.
+            c.status(statusFor('cookie-session-not-refreshable'));
+            return c.json(toWireError({
+                code: 'cookie-session-not-refreshable',
+                message: 'A browser session (cookie) is not refreshed: sign in again when it ends',
+            }, requestId));
+        }
         const current = await sessionStore.get({ tenantId, sessionId });
         if (current === null || current.revokedAt !== undefined) {
             c.status(statusFor('session-not-found'));
@@ -199,7 +311,7 @@ export function authRouters(options) {
             const fresh = await sessionStore.get({ tenantId, sessionId: createdSession.sessionId });
             if (fresh === null)
                 throw new Error('session vanished immediately after create');
-            created = { session: fresh, rawToken: encodeSessionToken(createdSession.sessionId) };
+            created = { session: fresh, rawToken: sessionTokenOf(createdSession) };
         }
         else {
             // Rotate the framework token only; keep provider tokens as-is.
@@ -207,7 +319,7 @@ export function authRouters(options) {
                 tenantId,
                 userId: current.userId,
                 providerId: current.providerId,
-                accessToken: current.accessToken,
+                ...(current.accessToken !== undefined && { accessToken: current.accessToken }),
                 ...(current.refreshToken !== undefined && { refreshToken: current.refreshToken }),
                 expiresAt: current.expiresAt,
                 scopes: current.scopes,
@@ -216,7 +328,7 @@ export function authRouters(options) {
             const fresh = await sessionStore.get({ tenantId, sessionId: createdSession.sessionId });
             if (fresh === null)
                 throw new Error('session vanished immediately after create');
-            created = { session: fresh, rawToken: encodeSessionToken(createdSession.sessionId) };
+            created = { session: fresh, rawToken: sessionTokenOf(createdSession) };
         }
         // OAuth 2.1 BCP: mark the old session as ROTATED (not just revoked)
         // so the middleware can return `401 refresh-token-invalid` on reuse
@@ -224,6 +336,8 @@ export function authRouters(options) {
         // compliant clients retry with the fresh token instead of forcing
         // a full re-auth.
         await sessionStore.revoke({ tenantId, sessionId, reason: 'rotate' });
+        // A session token: an Idempotency-Key repeat doesn't get it.
+        withholdFromReplay(c);
         return c.json({
             sessionToken: created.rawToken,
             sessionId: created.session.id,
@@ -231,110 +345,126 @@ export function authRouters(options) {
         });
     });
     // ---------- POST /logout ----------
-    authed.post('/logout', async (c) => {
-        const requestId = c.get('requestId');
-        const tenantId = c.get('tenantId');
-        const sessionId = c.get('sessionId');
-        if (sessionId === undefined) {
-            c.status(statusFor('auth-not-session-token'));
-            return c.json(toWireError({
-                code: 'auth-not-session-token',
-                message: 'Logout is only valid for session tokens (`kgi_sk_*`); bearer tokens are managed via `/v1/tokens`',
-            }, requestId));
-        }
-        const outcome = await sessionStore.revoke({ tenantId, sessionId });
-        return c.json({ sessionId, revoked: outcome.revoked });
-    });
+    authed.post('/logout', logoutHandler(sessionStore, options.auditEvents));
     const callback = new Hono();
     // ---------- POST /callback/:providerId (mounted outside the bearer chain) ----------
-    callback.post('/:providerId', async (c) => {
-        const requestId = c.get('requestId');
-        const providerId = c.req.param('providerId');
-        const parsedJson = await parseJsonBody(c);
-        if (parsedJson.kind === 'err') {
-            c.status(statusFor('bad-input'));
-            return c.json(toWireError(parsedJson.error, requestId));
-        }
-        const parsedCallback = parseCallbackBody(parsedJson.value);
-        if (parsedCallback.kind === 'err') {
-            c.status(statusFor(parsedCallback.error.code));
-            return c.json(toWireError(parsedCallback.error, requestId));
-        }
-        const { code, state } = parsedCallback.value;
-        // `state` alone is uniquely identifying (256 bits of entropy). The
-        // store returns the row's `tenantId` so we know which tenant the
-        // callback belongs to — cross-checking `providerId` guards against
-        // a stolen `state` being replayed against the wrong provider mount.
-        const entry = await stateStore.take({ state, providerId });
-        if (entry === null) {
-            c.status(statusFor('oauth-state-invalid'));
-            return c.json(toWireError({
-                code: 'oauth-state-invalid',
-                message: '`state` is unknown, expired, or already consumed',
-            }, requestId));
-        }
-        // Belt-and-suspenders redirect-URI check. Login already validated
-        // the stored redirect_uri against `allowedRedirectUris` when the
-        // row was written, but the allowlist may have tightened between
-        // login and callback — if so, refuse the exchange rather than
-        // handing the caller a session under a redirect the tenant no
-        // longer trusts. Also runs when the provider config went missing
-        // (unregister mid-flight) so we don't silently proceed.
-        const currentConfig = await identityProvider.get({
-            tenantId: entry.tenantId,
-            providerId,
-        });
-        if (currentConfig !== null &&
-            currentConfig.allowedRedirectUris !== undefined &&
-            currentConfig.allowedRedirectUris.length > 0 &&
-            !currentConfig.allowedRedirectUris.includes(entry.redirectUri)) {
-            c.status(statusFor('redirect-uri-mismatch'));
-            return c.json(toWireError({
-                code: 'redirect-uri-mismatch',
-                message: "redirect_uri from the login state row is not in the provider's current allowedRedirectUris list",
+    if (exchangeCode !== undefined) {
+        callback.post('/:providerId', async (c) => {
+            const requestId = c.get('requestId');
+            const providerId = c.req.param('providerId');
+            const parsedJson = await parseJsonBody(c);
+            if (parsedJson.kind === 'err') {
+                c.status(statusFor('bad-input'));
+                return c.json(toWireError(parsedJson.error, requestId));
+            }
+            const parsedCallback = parseCallbackBody(parsedJson.value);
+            if (parsedCallback.kind === 'err') {
+                c.status(statusFor(parsedCallback.error.code));
+                return c.json(toWireError(parsedCallback.error, requestId));
+            }
+            const { code, state } = parsedCallback.value;
+            // `state` alone is uniquely identifying (256 bits of entropy). The
+            // store returns the row's `tenantId` so we know which tenant the
+            // callback belongs to — cross-checking `providerId` guards against
+            // a stolen `state` being replayed against the wrong provider mount.
+            const entry = await stateStore.take({ state, providerId });
+            if (entry === null) {
+                c.status(statusFor('oauth-state-invalid'));
+                return c.json(toWireError({
+                    code: 'oauth-state-invalid',
+                    message: '`state` is unknown, expired, or already consumed',
+                }, requestId));
+            }
+            // Belt-and-suspenders redirect-URI check. Login already validated
+            // the stored redirect_uri against `allowedRedirectUris` when the
+            // row was written, but the allowlist may have tightened between
+            // login and callback — if so, refuse the exchange rather than
+            // handing the caller a session under a redirect the tenant no
+            // longer trusts. Also runs when the provider config went missing
+            // (unregister mid-flight) so we don't silently proceed.
+            const currentConfig = await identityProvider.get({
+                tenantId: entry.tenantId,
                 providerId,
-            }, requestId));
-        }
-        let outcome;
-        try {
-            outcome = await exchangeCode({
+            });
+            const currentAllowlist = currentConfig === null ? undefined : oauthFlowOf(currentConfig)?.allowedRedirectUris;
+            if (currentAllowlist !== undefined &&
+                currentAllowlist.length > 0 &&
+                !currentAllowlist.includes(entry.redirectUri)) {
+                c.status(statusFor('redirect-uri-mismatch'));
+                return c.json(toWireError({
+                    code: 'redirect-uri-mismatch',
+                    message: "redirect_uri from the login state row is not in the provider's current allowedRedirectUris list",
+                    providerId,
+                }, requestId));
+            }
+            let outcome;
+            try {
+                outcome = await exchangeCode({
+                    tenantId: entry.tenantId,
+                    providerId,
+                    code,
+                    codeVerifier: entry.codeVerifier,
+                    redirectUri: entry.redirectUri,
+                });
+            }
+            catch (err) {
+                c.status(statusFor('oauth-code-exchange-failed'));
+                return c.json(toWireError({
+                    code: 'oauth-code-exchange-failed',
+                    message: err instanceof Error ? err.message : 'code exchange failed',
+                }, requestId));
+            }
+            const created = await sessionStore.create({
                 tenantId: entry.tenantId,
+                userId: outcome.userId,
                 providerId,
-                code,
-                codeVerifier: entry.codeVerifier,
-                redirectUri: entry.redirectUri,
+                accessToken: outcome.accessToken,
+                ...(outcome.refreshToken !== undefined && { refreshToken: outcome.refreshToken }),
+                expiresAt: outcome.expiresAt.toISOString(),
+                scopes: outcome.scopes,
+                ...(outcome.claims !== undefined && { metadata: outcome.claims }),
+            });
+            // A session token: an Idempotency-Key repeat doesn't get it.
+            withholdFromReplay(c);
+            c.status(201);
+            return c.json({
+                sessionToken: sessionTokenOf(created),
+                sessionId: created.sessionId,
+                expiresAt: created.expiresAt,
             });
-        }
-        catch (err) {
-            c.status(statusFor('oauth-code-exchange-failed'));
-            return c.json(toWireError({
-                code: 'oauth-code-exchange-failed',
-                message: err instanceof Error ? err.message : 'code exchange failed',
-            }, requestId));
-        }
-        const created = await sessionStore.create({
-            tenantId: entry.tenantId,
-            userId: outcome.userId,
-            providerId,
-            accessToken: outcome.accessToken,
-            ...(outcome.refreshToken !== undefined && { refreshToken: outcome.refreshToken }),
-            expiresAt: outcome.expiresAt.toISOString(),
-            scopes: outcome.scopes,
-            ...(outcome.claims !== undefined && { metadata: outcome.claims }),
-        });
-        c.status(201);
-        return c.json({
-            sessionToken: encodeSessionToken(created.sessionId),
-            sessionId: created.sessionId,
-            expiresAt: created.expiresAt,
         });
-    });
+    }
     return { authed, callback };
 }
 // ---------- helpers ----------
+/** The token a store minted, or the older `kgi_sk_<sessionId>` for a store that mints none. */
+function sessionTokenOf(created) {
+    return created.token ?? encodeSessionToken(created.sessionId);
+}
 function base64Url(buf) {
     return buf.toString('base64url');
 }
+const DEFAULT_OIDC_SCOPES = ['openid', 'email', 'profile'];
+/**
+ * The provider's OAuth flow settings, or `null` when it has none: a SAML
+ * provider, or an OIDC one whose endpoints the deployment hasn't
+ * discovered (it signs in through the deployment's own browser flow).
+ */
+function oauthFlowOf(config) {
+    if (config.kind === 'saml')
+        return null;
+    if (config.kind === 'oidc' && config.authorizationEndpoint === undefined)
+        return null;
+    return {
+        clientId: config.clientId,
+        authorizationEndpoint: config.authorizationEndpoint,
+        scopes: config.scopes ?? DEFAULT_OIDC_SCOPES,
+        ...(config.allowedRedirectUris !== undefined && {
+            allowedRedirectUris: config.allowedRedirectUris,
+        }),
+        ...(config.metadata !== undefined && { metadata: config.metadata }),
+    };
+}
 function buildAuthorizationUrl(input) {
     const { config, state, codeChallenge, redirectUri } = input;
     const url = new URL(config.authorizationEndpoint);
@@ -347,25 +477,113 @@ function buildAuthorizationUrl(input) {
     url.searchParams.set('code_challenge_method', 'S256');
     return url.toString();
 }
+function providerNotFound(c, providerId) {
+    c.status(statusFor('identity-provider-not-found'));
+    return c.json(toWireError({
+        code: 'identity-provider-not-found',
+        message: `No identity provider registered with id "${providerId}"`,
+        providerId,
+    }, c.get('requestId')));
+}
+/** What the issuer's discovery gave: stale once the issuer changes. */
+const DISCOVERED_OIDC_FIELDS = [
+    'authorizationEndpoint',
+    'tokenEndpoint',
+    'userinfoEndpoint',
+    'jwksEndpoint',
+];
+/**
+ * A PATCH body merged into the stored provider: a field given replaces
+ * it, `null` removes it, `providerId` and `kind` can't change. `signIn`
+ * is the deployment's, so it never comes from the stored copy. A new
+ * `issuer` drops the endpoints discovered from the old one.
+ */
+function mergeProviderChanges(existing, body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return { kind: 'err', error: { code: 'bad-input', message: 'Request body must be an object' } };
+    }
+    const changes = body;
+    if (changes.providerId !== undefined && changes.providerId !== existing.providerId) {
+        return invalid("`providerId` can't change: register the provider under the new id, then unregister this one");
+    }
+    if (changes.kind !== undefined && changes.kind !== existing.kind) {
+        return invalid("`kind` can't change: register a new provider of that kind, then unregister this one");
+    }
+    const { signIn: _deployments, ...stored } = serializeProviderConfig(existing);
+    const merged = stored;
+    if (existing.kind === 'oidc' &&
+        changes.issuer !== undefined &&
+        changes.issuer !== existing.issuer) {
+        for (const field of DISCOVERED_OIDC_FIELDS)
+            delete merged[field];
+    }
+    for (const [field, value] of Object.entries(changes)) {
+        if (value === null)
+            delete merged[field];
+        else
+            merged[field] = value;
+    }
+    return { kind: 'ok', value: merged };
+}
 function serializeProviderConfig(c) {
-    // Every field except clientSecretRef (which is a REFERENCE, not the
-    // secret itself) is safe to return. Clients need enough to render an
-    // "sign in with X" button and know what scopes they're granting.
-    return {
+    // References to secrets (`clientSecretRef`, `spSigningKeyRef`…) are safe
+    // to return: they aren't the secrets. Clients need enough to render a
+    // "Sign in with X" button and to configure the identity provider.
+    const base = {
         providerId: c.providerId,
         kind: c.kind,
-        clientId: c.clientId,
-        clientSecretRef: c.clientSecretRef,
-        authorizationEndpoint: c.authorizationEndpoint,
-        tokenEndpoint: c.tokenEndpoint,
-        ...(c.userinfoEndpoint !== undefined && { userinfoEndpoint: c.userinfoEndpoint }),
-        scopes: c.scopes,
-        ...(c.allowedRedirectUris !== undefined && {
-            allowedRedirectUris: c.allowedRedirectUris,
-        }),
-        ...(c.claimMapping !== undefined && { claimMapping: c.claimMapping }),
-        ...(c.metadata !== undefined && { metadata: c.metadata }),
+        ...definedOf(c, ['displayName', 'domains', 'join', 'signIn', 'metadata']),
     };
+    switch (c.kind) {
+        case 'oauth2':
+            return {
+                ...base,
+                clientId: c.clientId,
+                clientSecretRef: c.clientSecretRef,
+                authorizationEndpoint: c.authorizationEndpoint,
+                tokenEndpoint: c.tokenEndpoint,
+                scopes: c.scopes,
+                ...definedOf(c, ['userinfoEndpoint', 'allowedRedirectUris', 'claimMapping']),
+            };
+        case 'oidc':
+            return {
+                ...base,
+                issuer: c.issuer,
+                clientId: c.clientId,
+                clientSecretRef: c.clientSecretRef,
+                ...definedOf(c, [
+                    'scopes',
+                    'authorizationEndpoint',
+                    'tokenEndpoint',
+                    'userinfoEndpoint',
+                    'jwksEndpoint',
+                    'allowedRedirectUris',
+                    'claimMapping',
+                ]),
+            };
+        case 'saml':
+            return {
+                ...base,
+                ...definedOf(c, [
+                    'idpMetadataXml',
+                    'idpEntityId',
+                    'idpSsoUrl',
+                    'idpCertificates',
+                    'spSigningKeyRef',
+                    'spDecryptionKeyRef',
+                    'wantAssertionsSigned',
+                    'attributeMapping',
+                ]),
+            };
+    }
+}
+/** The named fields of `obj` that are set. */
+function definedOf(obj, keys) {
+    const out = {};
+    for (const k of keys)
+        if (obj[k] !== undefined)
+            out[k] = obj[k];
+    return out;
 }
 async function parseJsonBody(c) {
     try {
@@ -396,120 +614,228 @@ async function parseOptionalJsonBody(c) {
         };
     }
 }
+/**
+ * Fields that would carry a secret itself rather than a reference to one:
+ * refused outright, so a secret sent by mistake is never stored.
+ */
+const PLAINTEXT_SECRET_FIELDS = {
+    clientSecret: 'clientSecretRef',
+    spSigningKey: 'spSigningKeyRef',
+    spDecryptionKey: 'spDecryptionKeyRef',
+    privateKey: 'spSigningKeyRef',
+};
+const DOMAIN_RE = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+function invalid(message) {
+    return { kind: 'err', error: { code: 'invalid-provider-config', message } };
+}
+/** Reads typed fields off a request body, collecting the first problem. */
+class FieldReader {
+    b;
+    error;
+    constructor(b) {
+        this.b = b;
+    }
+    str(k) {
+        const v = this.b[k];
+        if (typeof v !== 'string' || v.length === 0) {
+            this.error ??= invalid(`Field \`${k}\` must be a non-empty string`);
+            return '';
+        }
+        return v;
+    }
+    optStr(k) {
+        const v = this.b[k];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'string' || v.length === 0) {
+            this.error ??= invalid(`\`${k}\` must be a non-empty string when supplied`);
+            return undefined;
+        }
+        return v;
+    }
+    url(k, required) {
+        const v = required ? this.str(k) : this.optStr(k);
+        if (v === undefined || v === '')
+            return v;
+        try {
+            new URL(v);
+        }
+        catch {
+            this.error ??= invalid(`\`${k}\` must be an absolute URL`);
+        }
+        return v;
+    }
+    strings(k, required) {
+        const v = this.b[k];
+        if (v === undefined) {
+            if (required)
+                this.error ??= invalid(`\`${k}\` must be an array of strings`);
+            return undefined;
+        }
+        if (!Array.isArray(v) || v.some((x) => typeof x !== 'string' || x.length === 0)) {
+            this.error ??= invalid(`\`${k}\` must be an array of non-empty strings`);
+            return undefined;
+        }
+        return v;
+    }
+    bool(k) {
+        const v = this.b[k];
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'boolean') {
+            this.error ??= invalid(`\`${k}\` must be a boolean when supplied`);
+            return undefined;
+        }
+        return v;
+    }
+    object(k) {
+        const v = this.b[k];
+        if (v === undefined)
+            return undefined;
+        if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+            this.error ??= invalid(`\`${k}\` must be an object when supplied`);
+            return undefined;
+        }
+        return v;
+    }
+}
 function parseProviderConfig(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body)) {
         return { kind: 'err', error: { code: 'bad-input', message: 'Request body must be an object' } };
     }
     const b = body;
-    const requiredStr = (k) => {
-        const v = b[k];
-        if (typeof v !== 'string' || v.length === 0) {
-            return {
-                kind: 'err',
-                error: {
-                    code: 'invalid-provider-config',
-                    message: `Field \`${k}\` must be a non-empty string`,
-                },
-            };
+    for (const [field, instead] of Object.entries(PLAINTEXT_SECRET_FIELDS)) {
+        if (b[field] !== undefined) {
+            return invalid(`\`${field}\` is never accepted: register \`${instead}\`, a reference the deployment resolves`);
         }
-        return v;
-    };
-    const providerId = requiredStr('providerId');
-    if (typeof providerId !== 'string')
-        return providerId;
-    const clientId = requiredStr('clientId');
-    if (typeof clientId !== 'string')
-        return clientId;
-    const clientSecretRef = requiredStr('clientSecretRef');
-    if (typeof clientSecretRef !== 'string')
-        return clientSecretRef;
-    const authorizationEndpoint = requiredStr('authorizationEndpoint');
-    if (typeof authorizationEndpoint !== 'string')
-        return authorizationEndpoint;
-    const tokenEndpoint = requiredStr('tokenEndpoint');
-    if (typeof tokenEndpoint !== 'string')
-        return tokenEndpoint;
-    const kindRaw = b.kind;
-    if (kindRaw !== 'oauth2' && kindRaw !== 'oidc') {
-        return {
-            kind: 'err',
-            error: {
-                code: 'invalid-provider-config',
-                message: '`kind` must be `oauth2` or `oidc`',
-            },
-        };
     }
-    const scopesRaw = b.scopes;
-    if (!Array.isArray(scopesRaw) || scopesRaw.some((s) => typeof s !== 'string')) {
-        return {
-            kind: 'err',
-            error: {
-                code: 'invalid-provider-config',
-                message: '`scopes` must be an array of strings',
-            },
-        };
+    const kind = b.kind;
+    if (kind !== 'oauth2' && kind !== 'oidc' && kind !== 'saml') {
+        return invalid('`kind` must be `oidc`, `saml` or `oauth2`');
     }
-    const scopes = scopesRaw;
-    const userinfoEndpointRaw = b.userinfoEndpoint;
-    if (userinfoEndpointRaw !== undefined && typeof userinfoEndpointRaw !== 'string') {
-        return {
-            kind: 'err',
-            error: {
-                code: 'invalid-provider-config',
-                message: '`userinfoEndpoint` must be a string when supplied',
-            },
-        };
+    const r = new FieldReader(b);
+    const providerId = r.str('providerId');
+    const displayName = r.optStr('displayName');
+    const domainsRaw = r.strings('domains', false);
+    const domains = domainsRaw?.map((d) => d.toLowerCase());
+    if (domains?.some((d) => !DOMAIN_RE.test(d))) {
+        r.error ??= invalid('`domains` must be email domains, e.g. `acme.com`');
     }
-    const metadataRaw = b.metadata;
-    if (metadataRaw !== undefined &&
-        (metadataRaw === null || typeof metadataRaw !== 'object' || Array.isArray(metadataRaw))) {
-        return {
-            kind: 'err',
-            error: {
-                code: 'invalid-provider-config',
-                message: '`metadata` must be an object when supplied',
-            },
-        };
+    const join = b.join;
+    if (join !== undefined && join !== 'invite' && join !== 'domain') {
+        r.error ??= invalid('`join` must be `invite` or `domain`');
     }
-    const allowedRedirectUrisRaw = b.allowedRedirectUris;
-    let allowedRedirectUris;
-    if (allowedRedirectUrisRaw !== undefined) {
-        if (!Array.isArray(allowedRedirectUrisRaw) ||
-            allowedRedirectUrisRaw.some((s) => typeof s !== 'string' || s.length === 0)) {
-            return {
-                kind: 'err',
-                error: {
-                    code: 'invalid-provider-config',
-                    message: '`allowedRedirectUris` must be an array of non-empty strings when supplied',
-                },
-            };
-        }
-        allowedRedirectUris = allowedRedirectUrisRaw;
+    if (join === 'domain' && (domains === undefined || domains.length === 0)) {
+        r.error ??= invalid('`join: domain` needs `domains`');
     }
-    const claimMappingRaw = b.claimMapping;
+    const metadata = r.object('metadata');
+    const base = {
+        providerId,
+        ...(displayName !== undefined && { displayName }),
+        ...(domains !== undefined && { domains }),
+        ...(join !== undefined && { join: join }),
+        ...(metadata !== undefined && { metadata }),
+    };
     let claimMapping;
-    if (claimMappingRaw !== undefined) {
-        const parsed = parseClaimMapping(claimMappingRaw);
+    if (kind !== 'saml' && b.claimMapping !== undefined) {
+        const parsed = parseClaimMapping(b.claimMapping);
         if (parsed.kind === 'err')
             return parsed;
         claimMapping = parsed.value;
     }
-    return {
-        kind: 'ok',
-        value: {
-            providerId,
-            kind: kindRaw,
+    let value;
+    if (kind === 'oauth2') {
+        const clientId = r.str('clientId');
+        const clientSecretRef = r.str('clientSecretRef');
+        const authorizationEndpoint = r.str('authorizationEndpoint');
+        const tokenEndpoint = r.str('tokenEndpoint');
+        const userinfoEndpoint = r.optStr('userinfoEndpoint');
+        const scopes = r.strings('scopes', true) ?? [];
+        const allowedRedirectUris = r.strings('allowedRedirectUris', false);
+        value = {
+            ...base,
+            kind,
             clientId,
             clientSecretRef,
             authorizationEndpoint,
             tokenEndpoint,
-            ...(typeof userinfoEndpointRaw === 'string' && { userinfoEndpoint: userinfoEndpointRaw }),
             scopes,
+            ...(userinfoEndpoint !== undefined && { userinfoEndpoint }),
             ...(allowedRedirectUris !== undefined && { allowedRedirectUris }),
             ...(claimMapping !== undefined && { claimMapping }),
-            ...(metadataRaw !== undefined && { metadata: metadataRaw }),
-        },
-    };
+        };
+    }
+    else if (kind === 'oidc') {
+        const issuer = r.url('issuer', true) ?? '';
+        const clientId = r.str('clientId');
+        const clientSecretRef = r.str('clientSecretRef');
+        const scopes = r.strings('scopes', false);
+        const authorizationEndpoint = r.url('authorizationEndpoint', false);
+        const tokenEndpoint = r.url('tokenEndpoint', false);
+        const userinfoEndpoint = r.url('userinfoEndpoint', false);
+        const jwksEndpoint = r.url('jwksEndpoint', false);
+        const allowedRedirectUris = r.strings('allowedRedirectUris', false);
+        value = {
+            ...base,
+            kind,
+            issuer,
+            clientId,
+            clientSecretRef,
+            ...(scopes !== undefined && { scopes }),
+            ...(authorizationEndpoint !== undefined && { authorizationEndpoint }),
+            ...(tokenEndpoint !== undefined && { tokenEndpoint }),
+            ...(userinfoEndpoint !== undefined && { userinfoEndpoint }),
+            ...(jwksEndpoint !== undefined && { jwksEndpoint }),
+            ...(allowedRedirectUris !== undefined && { allowedRedirectUris }),
+            ...(claimMapping !== undefined && { claimMapping }),
+        };
+    }
+    else {
+        const idpMetadataXml = r.optStr('idpMetadataXml');
+        const idpEntityId = r.optStr('idpEntityId');
+        const idpSsoUrl = r.url('idpSsoUrl', false);
+        const idpCertificates = r.strings('idpCertificates', false);
+        if (idpMetadataXml === undefined &&
+            (idpEntityId === undefined ||
+                idpSsoUrl === undefined ||
+                idpCertificates === undefined ||
+                idpCertificates.length === 0)) {
+            r.error ??= invalid('A SAML provider needs `idpMetadataXml`, or `idpEntityId` + `idpSsoUrl` + `idpCertificates`');
+        }
+        const spSigningKeyRef = r.optStr('spSigningKeyRef');
+        const spDecryptionKeyRef = r.optStr('spDecryptionKeyRef');
+        const wantAssertionsSigned = r.bool('wantAssertionsSigned');
+        const mappingRaw = r.object('attributeMapping');
+        let attributeMapping;
+        if (mappingRaw !== undefined) {
+            const m = new FieldReader(mappingRaw);
+            const userId = m.optStr('userId');
+            const email = m.optStr('email');
+            const displayName = m.optStr('displayName');
+            if (m.error !== undefined)
+                r.error ??= invalid(`\`attributeMapping\`: ${m.error.error.message}`);
+            attributeMapping = {
+                ...(userId !== undefined && { userId }),
+                ...(email !== undefined && { email }),
+                ...(displayName !== undefined && { displayName }),
+            };
+        }
+        value = {
+            ...base,
+            kind,
+            ...(idpMetadataXml !== undefined && { idpMetadataXml }),
+            ...(idpEntityId !== undefined && { idpEntityId }),
+            ...(idpSsoUrl !== undefined && { idpSsoUrl }),
+            ...(idpCertificates !== undefined && { idpCertificates }),
+            ...(spSigningKeyRef !== undefined && { spSigningKeyRef }),
+            ...(spDecryptionKeyRef !== undefined && { spDecryptionKeyRef }),
+            ...(wantAssertionsSigned !== undefined && { wantAssertionsSigned }),
+            ...(attributeMapping !== undefined && { attributeMapping }),
+        };
+    }
+    if (r.error !== undefined)
+        return r.error;
+    return { kind: 'ok', value };
 }
 function parseClaimMapping(raw) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -627,4 +953,52 @@ function parseCallbackBody(body) {
     }
     return { kind: 'ok', value: { code, state } };
 }
+/**
+ * `POST /v1/auth/logout`: revokes the caller's session; a browser session
+ * loses its cookie too. Also mounted on its own with cookie sessions and
+ * no identity providers (console token sign-in).
+ */
+export function logoutHandler(sessionStore, auditEvents) {
+    return async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const sessionId = c.get('sessionId');
+        if (sessionId === undefined) {
+            c.status(statusFor('auth-not-session-token'));
+            return c.json(toWireError({
+                code: 'auth-not-session-token',
+                message: 'Logout is only valid for session tokens (`kgi_sk_*`); bearer tokens are managed via `/v1/tokens`',
+            }, requestId));
+        }
+        const outcome = await sessionStore.revoke({ tenantId, sessionId });
+        const userId = c.get('userId');
+        if (auditEvents !== undefined && outcome.revoked) {
+            try {
+                const appended = await auditEvents.append([
+                    {
+                        id: randomUUID(),
+                        tenantId,
+                        kind: 'signed-out',
+                        timestamp: new Date().toISOString(),
+                        actor: userId !== undefined ? `user:${userId}` : 'system',
+                        outcome: 'succeeded',
+                        payload: { v: 1, doc: { sessionId } },
+                    },
+                ]);
+                if (appended.kind === 'err') {
+                    c.get('log').warn(`signed-out audit event failed: ${appended.error.message}`);
+                }
+            }
+            catch (cause) {
+                c.get('log').warn(`signed-out audit event failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+        const cookieName = c.get('sessionCookieName');
+        if (cookieName !== undefined) {
+            // A browser session: the cookie goes with it.
+            c.header('Set-Cookie', `${cookieName}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`);
+        }
+        return c.json({ sessionId, revoked: outcome.revoked });
+    };
+}
 //# sourceMappingURL=auth.js.map