@aderis-erp/cli 1.0.15 → 1.0.17

package/dist/lib/auth/keycloak-provider.js

@@ -0,0 +1,215 @@
+import { URL } from 'node:url';
+import { REDIRECT_URI } from './constants.js';
+import { AuthError } from './errors.js';
+import { requireClientId } from './guards.js';
+import { authHttp, toAuthError } from './http.js';
+import { decodeToken, exchangeAuthorizationCode, redeemRefreshToken, tenantIdOf, tenantsOf, toTokenData, } from './tokens.js';
+import { buildValidatedUrl } from './validated-url.js';
+/**
+ * Default Keycloak origin and realm per environment. A context may override
+ * the origin with `keycloak_base_url`; a token carries the issuer of the origin
+ * it was requested from, and the API compares `iss` exactly.
+ */
+export const KEYCLOAK_REALMS = {
+    dev: { baseUrl: 'https://iam-dev.aderis.com', realm: 'dev' },
+    live: { baseUrl: 'https://iam.aderis.com', realm: 'prod' },
+    staging: { baseUrl: 'https://iam-staging.aderis.com', realm: 'staging' },
+    test: { baseUrl: 'https://iam-test.aderis.com', realm: 'test' },
+};
+/** The tenant claims need no extra scope; the tenant is selected by the CLI via `tenant_id`, not on the login page. */
+export const KEYCLOAK_SCOPE = 'openid profile email offline_access';
+/**
+ * Validates a Keycloak base URL as stored in `keycloak_base_url`: https, an
+ * allowlisted host, and nothing but the origin. Returns the normalized origin.
+ */
+export function parseKeycloakBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AuthError(`"${value}" is not a valid URL`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new AuthError(`The Keycloak URL must use https, got "${value}"`);
+    }
+    if (url.pathname !== '/' || url.search || url.hash) {
+        throw new AuthError(`The Keycloak URL must be an origin only, without a path or query, got "${value}"`);
+    }
+    try {
+        buildValidatedUrl(url.origin);
+    }
+    catch {
+        throw new AuthError(`"${url.host}" is not an allowed Keycloak host`);
+    }
+    return url.origin;
+}
+/** The Keycloak origin a context uses: its override, re-validated, or the environment's default. */
+export function keycloakBaseUrlOf(target) {
+    return target.keycloak_base_url === undefined
+        ? KEYCLOAK_REALMS[target.environment].baseUrl
+        : parseKeycloakBaseUrl(target.keycloak_base_url);
+}
+export function discoveryUrlFor(target) {
+    const { realm } = KEYCLOAK_REALMS[target.environment];
+    return buildValidatedUrl(keycloakBaseUrlOf(target), `/realms/${realm}/.well-known/openid-configuration`);
+}
+async function fetchDiscovery(target) {
+    const url = discoveryUrlFor(target);
+    let data;
+    try {
+        const response = await authHttp.get(url, { headers: { Accept: 'application/json' } });
+        data = response.data;
+    }
+    catch (error) {
+        throw new AuthError(`Could not load the Keycloak OIDC discovery document from ${url}: ${toAuthError(error, 'the request').message}`);
+    }
+    return validateDiscovery(url, data);
+}
+function validateDiscovery(url, data) {
+    const requireString = (field) => {
+        const value = data[field];
+        if (typeof value !== 'string' || !value) {
+            throw new AuthError(`Keycloak discovery document at ${url} has no ${field}`);
+        }
+        return value;
+    };
+    const requireEndpoint = (field) => {
+        const value = requireString(field);
+        try {
+            return buildValidatedUrl(value);
+        }
+        catch {
+            throw new AuthError(`Keycloak discovery document at ${url} advertises a ${field} outside the allowed hosts: ${value}`);
+        }
+    };
+    // `end_session_endpoint` is unused: logout is local-only.
+    return {
+        authorization_endpoint: requireEndpoint('authorization_endpoint'),
+        issuer: requireString('issuer'),
+        token_endpoint: requireEndpoint('token_endpoint'),
+    };
+}
+/**
+ * Authorization Code + PKCE S256 with `state` and `nonce` against the public
+ * `aderis-cli-login` client, endpoints from OIDC discovery. Tenants come from
+ * the access token; a switch is a refresh-token grant carrying `tenant_id=<uuid>`.
+ */
+export class KeycloakProvider {
+    /** Discovery documents per discovery URL, fetched once per provider instance. */
+    discoveryCache = new Map();
+    async buildAuthorizeUrl(context, params) {
+        const discovery = await this.discover(context);
+        const url = new URL(discovery.authorization_endpoint);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', requireClientId(context));
+        url.searchParams.set('redirect_uri', REDIRECT_URI);
+        url.searchParams.set('scope', KEYCLOAK_SCOPE);
+        url.searchParams.set('code_challenge', params.codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('state', params.state);
+        url.searchParams.set('nonce', params.nonce);
+        if (params.prompt)
+            url.searchParams.set('prompt', params.prompt);
+        return url.toString();
+    }
+    /**
+     * The realm's discovery document, cached per discovery URL. Its endpoints are
+     * validated against the host allowlist; a failed fetch is not cached.
+     */
+    discover(target) {
+        const key = discoveryUrlFor(target);
+        const cached = this.discoveryCache.get(key);
+        if (cached)
+            return cached;
+        const pending = fetchDiscovery(target).catch((error) => {
+            this.discoveryCache.delete(key);
+            throw error;
+        });
+        this.discoveryCache.set(key, pending);
+        return pending;
+    }
+    async exchangeCode(context, { code, codeVerifier, nonce }) {
+        const discovery = await this.discover(context);
+        const response = await exchangeAuthorizationCode(discovery.token_endpoint, context, { code, codeVerifier });
+        this.verifyNonce(response, nonce);
+        return this.requireTenant(this.requireIssuer(discovery, toTokenData(response)));
+    }
+    /** No network call: the access token's `availableTenants` claim lists every tenant the user may act in. */
+    async listTenants(_context, accessToken) {
+        const decoded = decodeToken(accessToken);
+        const current = tenantIdOf(decoded);
+        const tenants = tenantsOf(decoded);
+        if (tenants === undefined) {
+            throw new AuthError("The Keycloak access token carries no `availableTenants` claim. Check the realm's tenant-claims mapper, then run: aderis auth login");
+        }
+        return tenants.map(({ id, name }) => ({ isDefault: id === current, name, tenantId: id }));
+    }
+    refresh(context, refreshToken) {
+        return this.redeem(context, refreshToken);
+    }
+    /**
+     * One refresh-token grant with the `tenant_id` form field, read by the
+     * realm's tenant-claims mapper: the minted token's `tenantId` becomes this
+     * tenant. No browser and no SSO session involved.
+     */
+    switchTenant(context, refreshToken, tenantId) {
+        return this.redeem(context, refreshToken, tenantId);
+    }
+    /**
+     * One login round whose tokens are re-scoped to `tenantId` through
+     * {@link switchTenant} right after the exchange. A second browser round
+     * could not be silent: exchanging the code for an offline token ends the
+     * realm's SSO session.
+     */
+    tenantSwitchRounds(context, tenantId) {
+        return [
+            {
+                afterExchange: (tokens) => {
+                    if (!tokens.refresh_token) {
+                        throw new AuthError('Keycloak returned no refresh token, so the tenant cannot be selected. Aborting.');
+                    }
+                    return this.switchTenant(context, tokens.refresh_token, tenantId);
+                },
+            },
+        ];
+    }
+    async redeem(context, refreshToken, tenantId) {
+        const discovery = await this.discover(context);
+        const tokens = toTokenData(await redeemRefreshToken(discovery.token_endpoint, context, refreshToken, { tenantId }));
+        return this.requireTenant(this.requireIssuer(discovery, tokens));
+    }
+    /** Rejects a token whose `iss` differs from the discovery issuer; the API compares `iss` exactly. */
+    requireIssuer(discovery, tokens) {
+        const issuer = decodeToken(tokens.access_token)?.iss;
+        if (issuer !== discovery.issuer) {
+            throw new AuthError(`Keycloak issued a token for issuer ${issuer ?? '(none)'}, but the realm's discovery document names ${discovery.issuer}. Aborting.`);
+        }
+        return tokens;
+    }
+    /**
+     * The mapper is fail-closed: with several reachable tenants and no `tenant_id`
+     * the token has no `tenantId`. That token is stored and needs a tenant picked
+     * (`completeTenantSelection`); a token reaching no tenant is refused.
+     */
+    requireTenant(tokens) {
+        if (tokens.tenant_id)
+            return tokens;
+        const tenants = tenantsOf(decodeToken(tokens.access_token));
+        if (tenants !== undefined && tenants.length > 0)
+            return tokens;
+        throw new AuthError('Keycloak issued a token with no tenants, so you have reached no tenant. Your user is not a member of any tenant in this realm. Contact your administrator.');
+    }
+    /** Consistency check only: the id_token signature is not checked (the API checks the access token). */
+    verifyNonce(response, expectedNonce) {
+        if (!response.id_token) {
+            throw new AuthError('Keycloak returned no id_token; the openid scope is missing from the client configuration.');
+        }
+        const claims = decodeToken(response.id_token);
+        if (claims?.nonce !== expectedNonce) {
+            throw new AuthError('The id_token nonce does not match the login request. Aborting — please try again.');
+        }
+    }
+}
+/** The one identity provider the CLI authenticates against. */
+export const keycloakProvider = new KeycloakProvider();

package/dist/lib/auth/pages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pages the loopback callback server serves. Everything interpolated into
+ * markup goes through {@link escapeHtml} (`message` can carry
+ * `error_description` from the authorization server); callers pass data, never markup.
+ */
+/** A message with an optional emphasised subject between `text` and `tail`. */
+export interface PageMessage {
+    /** Rendered in bold between `text` and `tail`. */
+    subject?: string;
+    /** Plain text after the subject. */
+    tail?: string;
+    /** Plain text before the subject. */
+    text: string;
+}
+/** Escapes a string for HTML text or a double-quoted attribute value. */
+export declare function escapeHtml(value: string): string;
+/**
+ * The page shown once the callback has been handled. The success page counts
+ * down and tries to close its tab; the error page never does.
+ */
+export declare function renderAuthPage(type: 'error' | 'success', title: string, message: PageMessage | string): string;
+/**
+ * Page that sends the browser tab into the next authorization round via meta refresh.
+ */
+export declare function renderRedirectPage(nextUrl: string): string;

package/dist/lib/auth/pages.js

@@ -0,0 +1,123 @@
+/**
+ * Pages the loopback callback server serves. Everything interpolated into
+ * markup goes through {@link escapeHtml} (`message` can carry
+ * `error_description` from the authorization server); callers pass data, never markup.
+ */
+const ADERIS_LOGO_URL = 'https://public.aderis.com/69da47c9-274a-4103-bc3e-d9123fd13fac.png';
+/** Seconds the success page counts down before it tries to close its tab. */
+const AUTO_CLOSE_SECONDS = 3;
+const CLOSE_HINT = 'You can close this tab and return to the CLI.';
+/** Escapes a string for HTML text or a double-quoted attribute value. */
+export function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+/** Palette of the `aderis` Keycloak login theme. */
+const PALETTE_CSS = [
+    '--aderis-purple:#9687F5',
+    '--aderis-purple-hover:#7d6cf0',
+    '--aderis-purple-light:#C1B8FA',
+    '--aderis-navy:#3C4A5A',
+    '--aderis-muted:#827D93',
+    '--aderis-border:#e2ddf8',
+    '--aderis-input-bg:#f3f1fe',
+].join(';');
+const SHARED_CSS = `
+    :root{${PALETTE_CSS}}
+    *{margin:0;padding:0;box-sizing:border-box}
+    body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:linear-gradient(135deg,#fff 0%,var(--aderis-input-bg) 100%);min-height:100vh;display:flex;align-items:center;justify-content:center;padding:20px;color:var(--aderis-navy)}
+    .container{background:#fff;border-radius:16px;box-shadow:0 10px 40px rgba(150,135,245,.15);padding:48px;max-width:440px;width:100%;text-align:center;border:1px solid var(--aderis-border)}
+    .logo{margin-bottom:32px}
+    .logo img{height:40px;width:auto}
+    .icon{margin-bottom:24px}
+    .icon.success{color:var(--aderis-purple)}
+    .icon.error{color:#dc2626}
+    h1{font-size:24px;font-weight:600;color:var(--aderis-navy);margin-bottom:12px}
+    .message{font-size:16px;color:var(--aderis-muted);line-height:1.6;margin-bottom:24px}
+    .message strong{color:var(--aderis-navy);font-weight:600}
+    .hint{font-size:14px;color:var(--aderis-muted);margin-top:24px}
+    .divider{height:1px;background:linear-gradient(90deg,transparent,var(--aderis-border),transparent);margin:24px 0}
+    .spinner{width:40px;height:40px;margin:0 auto 24px;border:4px solid var(--aderis-purple-light);border-top-color:var(--aderis-purple);border-radius:50%;animation:spin .8s linear infinite}
+    @keyframes spin{to{transform:rotate(360deg)}}
+`;
+const SUCCESS_ICON = `<svg width="64" height="64" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M8 12l3 3 5-6"/></svg>`;
+const ERROR_ICON = `<svg width="64" height="64" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M15 9l-6 6M9 9l6 6"/></svg>`;
+/**
+ * Counts down, then asks the browser to close the tab; browsers only close
+ * script-opened tabs, so the hint then tells the user to close it.
+ */
+const AUTO_CLOSE_SCRIPT = `<script>
+(function(){
+  var count=${AUTO_CLOSE_SECONDS};
+  var hint=document.getElementById('hint');
+  var counter=document.getElementById('count');
+  var tick=setInterval(function(){
+    count-=1;
+    if(count>0){counter.textContent=String(count);return;}
+    clearInterval(tick);
+    window.close();
+    setTimeout(function(){hint.textContent=${JSON.stringify(CLOSE_HINT)};},300);
+  },1000);
+})();
+</script>`;
+function renderShell(options) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  ${options.head ?? ''}
+  <title>${escapeHtml(options.title)} - Aderis CLI</title>
+  <style>${SHARED_CSS}</style>
+</head>
+<body>
+  <div class="container">
+    <div class="logo"><img src="${ADERIS_LOGO_URL}" alt="Aderis" /></div>
+${options.body}
+  </div>
+${options.script ?? ''}
+</body>
+</html>`;
+}
+function renderMessage(message) {
+    if (typeof message === 'string') {
+        return escapeHtml(message);
+    }
+    const subject = message.subject === undefined ? '' : `<strong>${escapeHtml(message.subject)}</strong>`;
+    return `${escapeHtml(message.text)}${subject}${escapeHtml(message.tail ?? '')}`;
+}
+/**
+ * The page shown once the callback has been handled. The success page counts
+ * down and tries to close its tab; the error page never does.
+ */
+export function renderAuthPage(type, title, message) {
+    const isSuccess = type === 'success';
+    const hint = isSuccess
+        ? `<p class="hint" id="hint">This tab closes in <span id="count">${AUTO_CLOSE_SECONDS}</span>…</p>`
+        : `<p class="hint">${CLOSE_HINT}</p>`;
+    return renderShell({
+        body: `    <div class="icon ${type}">${isSuccess ? SUCCESS_ICON : ERROR_ICON}</div>
+    <h1>${escapeHtml(title)}</h1>
+    <p class="message">${renderMessage(message)}</p>
+    <div class="divider"></div>
+    ${hint}`,
+        script: isSuccess ? AUTO_CLOSE_SCRIPT : undefined,
+        title,
+    });
+}
+/**
+ * Page that sends the browser tab into the next authorization round via meta refresh.
+ */
+export function renderRedirectPage(nextUrl) {
+    return renderShell({
+        body: `    <div class="spinner"></div>
+    <h1>Switching tenant…</h1>
+    <p class="message">Taking you back to the login page.</p>`,
+        head: `<meta http-equiv="refresh" content="0; url=${escapeHtml(nextUrl)}">`,
+        title: 'Switching tenant…',
+    });
+}

package/dist/lib/auth/pkce.d.ts

@@ -0,0 +1,11 @@
+export interface PkceChallenge {
+    challenge: string;
+    verifier: string;
+}
+/** RFC 7636 S256: base64url(sha256(verifier)). */
+export declare function codeChallengeFor(verifier: string): string;
+export declare function generatePkce(): PkceChallenge;
+/** Opaque per-request value echoed back on the callback to bind it to this login. */
+export declare function generateState(): string;
+/** Opaque per-request value that must reappear in the id_token (OIDC replay protection). */
+export declare function generateNonce(): string;

package/dist/lib/auth/pkce.js

@@ -0,0 +1,17 @@
+import * as crypto from 'node:crypto';
+/** RFC 7636 S256: base64url(sha256(verifier)). */
+export function codeChallengeFor(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+export function generatePkce() {
+    const verifier = crypto.randomBytes(32).toString('base64url');
+    return { challenge: codeChallengeFor(verifier), verifier };
+}
+/** Opaque per-request value echoed back on the callback to bind it to this login. */
+export function generateState() {
+    return crypto.randomBytes(16).toString('hex');
+}
+/** Opaque per-request value that must reappear in the id_token (OIDC replay protection). */
+export function generateNonce() {
+    return crypto.randomBytes(16).toString('hex');
+}

package/dist/lib/auth/tokens.d.ts

@@ -0,0 +1,54 @@
+import { URLSearchParams } from 'node:url';
+import { type Context, type TokenData } from '../config.js';
+/** Wire shape of an OAuth token endpoint response (RFC 6749 §5.1, plus OIDC `id_token`). */
+export interface TokenResponse {
+    access_token: string;
+    expires_in?: number;
+    id_token?: string;
+    refresh_token?: string;
+    token_type: string;
+}
+/** Claims the CLI reads from an access token. Decoded without signature verification — the API verifies. */
+export interface DecodedToken {
+    [claim: string]: unknown;
+    availableTenants?: unknown;
+    exp?: number;
+    iss?: string;
+    nonce?: string;
+    tenant_id?: string;
+    tenantId?: string;
+    tenants?: unknown;
+}
+export declare function decodeToken(token: string): DecodedToken | null;
+/** The tenant an access token is scoped to: `tenantId`, or the legacy `tenant_id`. */
+export declare function tenantIdOf(decoded: DecodedToken | null): string | undefined;
+/** One entry of the `availableTenants` claim, as the realm's tenant-claims mapper writes it. */
+export interface TenantClaim {
+    id: string;
+    name: string;
+}
+/**
+ * The token's tenant list, or `undefined` when it carries none. Throws on a malformed claim.
+ */
+export declare function tenantsOf(decoded: DecodedToken | null): TenantClaim[] | undefined;
+/** Map a token endpoint response onto the stored {@link TokenData} shape. */
+export declare function toTokenData(response: TokenResponse): TokenData;
+/**
+ * POSTs a form to a token endpoint (RFC 6749 §4.1.3 / §6). Failures surface as
+ * {@link AuthError} with the HTTP status; the form never leaves this function inside an error.
+ */
+export declare function postTokenRequest(tokenUrl: string, params: URLSearchParams): Promise<TokenResponse>;
+/** The PKCE authorization-code grant (RFC 7636 §4.5) against `tokenUrl`. */
+export declare function exchangeAuthorizationCode(tokenUrl: string, context: Context, { code, codeVerifier }: {
+    code: string;
+    codeVerifier: string;
+}): Promise<TokenResponse>;
+/**
+ * The refresh-token grant (RFC 6749 §6). `tenantId` is sent as the `tenant_id`
+ * form field, which selects the tenant of the minted token. A 400
+ * (`invalid_grant`) or 401 is reported as {@link SESSION_EXPIRED_MESSAGE},
+ * which `aderis switch` recognises.
+ */
+export declare function redeemRefreshToken(tokenUrl: string, context: Context, refreshToken: string, { tenantId }?: {
+    tenantId?: string;
+}): Promise<TokenResponse>;

package/dist/lib/auth/tokens.js

@@ -0,0 +1,104 @@
+import jwt from 'jsonwebtoken';
+import { URLSearchParams } from 'node:url';
+import { SESSION_EXPIRED_MESSAGE } from '../config.js';
+import { FORM_POST_HEADERS, REDIRECT_URI } from './constants.js';
+import { AuthError } from './errors.js';
+import { requireClientId } from './guards.js';
+import { authHttp, toAuthError } from './http.js';
+export function decodeToken(token) {
+    const decoded = jwt.decode(token);
+    return decoded && typeof decoded === 'object' ? decoded : null;
+}
+/** The tenant an access token is scoped to: `tenantId`, or the legacy `tenant_id`. */
+export function tenantIdOf(decoded) {
+    return decoded?.tenantId || decoded?.tenant_id;
+}
+function malformedTenantsClaim(detail) {
+    return new AuthError(`The access token's \`availableTenants\` claim is malformed (${detail}; expected a list of {id, name} objects). Check the realm's tenant-claims mapper, then run: aderis auth login`);
+}
+function parseTenantClaim(entry, position) {
+    // A bare string is an id without a name.
+    if (typeof entry === 'string' && entry !== '')
+        return { id: entry, name: entry };
+    if (entry === null || typeof entry !== 'object') {
+        throw malformedTenantsClaim(`entry ${position} is not an object`);
+    }
+    const { id, name } = entry;
+    if (typeof id !== 'string' || id === '') {
+        throw malformedTenantsClaim(`entry ${position} has no id`);
+    }
+    if (name !== undefined && typeof name !== 'string') {
+        throw malformedTenantsClaim(`entry ${position} has a non-string name`);
+    }
+    return { id, name: name || id };
+}
+/**
+ * The token's tenant list, or `undefined` when it carries none. Throws on a malformed claim.
+ */
+export function tenantsOf(decoded) {
+    // TODO(cli#13): remove the tenants fallback
+    const claim = decoded?.availableTenants ?? decoded?.tenants;
+    if (claim === undefined || claim === null)
+        return undefined;
+    if (!Array.isArray(claim))
+        throw malformedTenantsClaim(`got ${typeof claim}`);
+    return claim.map((entry, index) => parseTenantClaim(entry, index + 1));
+}
+/** Map a token endpoint response onto the stored {@link TokenData} shape. */
+export function toTokenData(response) {
+    return {
+        access_token: response.access_token,
+        expires_at: response.expires_in ? Date.now() + response.expires_in * 1000 : undefined,
+        refresh_token: response.refresh_token,
+        tenant_id: tenantIdOf(decodeToken(response.access_token)),
+    };
+}
+/**
+ * POSTs a form to a token endpoint (RFC 6749 §4.1.3 / §6). Failures surface as
+ * {@link AuthError} with the HTTP status; the form never leaves this function inside an error.
+ */
+export async function postTokenRequest(tokenUrl, params) {
+    try {
+        const response = await authHttp.post(tokenUrl, params.toString(), { headers: FORM_POST_HEADERS });
+        return response.data;
+    }
+    catch (error) {
+        throw toAuthError(error, `Token request to ${tokenUrl}`);
+    }
+}
+/** `client_id`, plus `client_secret` when the context is confidential — the part every grant shares. */
+function clientParams(context, params) {
+    params.set('client_id', requireClientId(context));
+    if (context.client_secret)
+        params.set('client_secret', context.client_secret);
+    return params;
+}
+/** The PKCE authorization-code grant (RFC 7636 §4.5) against `tokenUrl`. */
+export async function exchangeAuthorizationCode(tokenUrl, context, { code, codeVerifier }) {
+    const params = clientParams(context, new URLSearchParams({ grant_type: 'authorization_code' }));
+    params.set('code', code);
+    params.set('redirect_uri', REDIRECT_URI);
+    params.set('code_verifier', codeVerifier);
+    return postTokenRequest(tokenUrl, params);
+}
+/**
+ * The refresh-token grant (RFC 6749 §6). `tenantId` is sent as the `tenant_id`
+ * form field, which selects the tenant of the minted token. A 400
+ * (`invalid_grant`) or 401 is reported as {@link SESSION_EXPIRED_MESSAGE},
+ * which `aderis switch` recognises.
+ */
+export async function redeemRefreshToken(tokenUrl, context, refreshToken, { tenantId } = {}) {
+    const params = clientParams(context, new URLSearchParams({ grant_type: 'refresh_token' }));
+    params.set('refresh_token', refreshToken);
+    if (tenantId)
+        params.set('tenant_id', tenantId);
+    try {
+        return await postTokenRequest(tokenUrl, params);
+    }
+    catch (error) {
+        if (error instanceof AuthError && (error.status === 400 || error.status === 401)) {
+            throw new AuthError(SESSION_EXPIRED_MESSAGE, { status: error.status });
+        }
+        throw error;
+    }
+}

package/dist/lib/auth/types.d.ts

@@ -0,0 +1,57 @@
+import { type Context, type TokenData } from '../config.js';
+export interface Tenant {
+    createdAt?: string;
+    isDefault?: boolean;
+    name: string;
+    tenantId: string;
+}
+/** Inputs to one authorization request. The flow generates them; the provider decides which to send. */
+export interface AuthorizeParams {
+    /** PKCE S256 challenge derived from this round's verifier. */
+    codeChallenge: string;
+    /** OIDC nonce; providers that support it echo it in the id_token. */
+    nonce: string;
+    prompt?: 'login' | 'none';
+    state: string;
+}
+export interface ExchangeParams {
+    code: string;
+    codeVerifier: string;
+    /** The nonce sent with the matching authorization request, for id_token verification. */
+    nonce: string;
+}
+/** One browser round of a login or tenant switch; the flow adds PKCE, state, nonce and the URL via the provider. */
+export interface AuthRound {
+    /**
+     * Runs after this round's tokens are exchanged and stored. Tokens it returns
+     * replace them as the round's result and are stored too; a throw aborts the flow.
+     */
+    afterExchange?: (tokens: TokenData) => Promise<TokenData | void>;
+    /** Forwarded to {@link AuthProvider.buildAuthorizeUrl} as `prompt`. */
+    prompt?: 'login' | 'none';
+}
+/**
+ * The seam between the login orchestration (`flow.ts`, `index.ts`) and Keycloak.
+ * The implementation owns endpoints, scopes and token semantics; it never starts
+ * servers or opens browsers.
+ */
+export interface AuthProvider {
+    /** The URL the browser is sent to. Async because Keycloak resolves endpoints via OIDC discovery. */
+    buildAuthorizeUrl(context: Context, params: AuthorizeParams): Promise<string>;
+    /** Redeem the authorization code. Must validate the id_token nonce when the provider issues one. */
+    exchangeCode(context: Context, params: ExchangeParams): Promise<TokenData>;
+    /** Tenants the user can switch to, given a valid access token. */
+    listTenants(context: Context, accessToken: string): Promise<Tenant[]>;
+    /** Refresh-token grant. A rejected refresh must surface as the "Session expired" error. */
+    refresh(context: Context, refreshToken: string): Promise<TokenData>;
+    /**
+     * Re-scopes a live session to `tenantId` with one token request and no
+     * browser. A rejected refresh must surface as the "Session expired" error.
+     */
+    switchTenant(context: Context, refreshToken: string, tenantId: string): Promise<TokenData>;
+    /**
+     * The browser rounds that end with a token for `tenantId` when no live
+     * session exists; the flow appends the tenant assertion.
+     */
+    tenantSwitchRounds(context: Context, tenantId: string): AuthRound[];
+}

package/dist/lib/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/auth/validated-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates `baseUrl` against the host allowlist and optionally appends `path`.
+ * Throws `Error('Invalid URL')` for anything off-list, non-http(s), or
+ * containing path traversal.
+ */
+export declare function buildValidatedUrl(baseUrl: string, path?: string): string;