@aderis-erp/cli 1.0.14 → 1.0.17

package/dist/lib/api-client.js

@@ -1,6 +1,6 @@
 import axios from 'axios';
-import { getValidToken } from './auth.js';
-import { getBaseUrls, getCurrentContext } from './config.js';
+import { getAuthHeaders } from './auth/index.js';
+import { getBaseUrls, getCurrentContext, unauthorizedMessage } from './config.js';
 /**
  * Normalize a --sort-by value: comma-separated fields, each optionally suffixed
  * with `:ASC` or `:DESC`. Fields without an explicit direction default to DESC
@@ -39,14 +39,15 @@ export async function createApiClient(contextName, options = false) {
     if (!context) {
         throw new Error('No context configured. Run: aderis auth login --new');
     }
-    const token = await getValidToken(context.name);
+    const authHeaders = await getAuthHeaders(context.name);
     const { api: baseURL } = getBaseUrls(context.environment);
     const client = axios.create({
         baseURL,
         headers: {
             Accept: binary ? '*/*' : (acceptAny ? '*/*' : 'application/json'),
-            Authorization: `Bearer ${token}`,
             'Content-Type': 'application/json',
+            // Either `Authorization: Bearer <token>` or `x-api-key: <key>`.
+            ...authHeaders,
         },
         // Serialize arrays as repeated params (key=v1&key=v2) instead of bracket format (key[]=v1)
         paramsSerializer: { indexes: null },
@@ -56,9 +57,10 @@ export async function createApiClient(contextName, options = false) {
     // Response interceptor for error handling
     client.interceptors.response.use((response) => response, (error) => {
         if (error.response) {
-            // Handle 401 with a clear message
+            // Handle 401 with a clear message, pointing at the right remedy for the
+            // context's auth type — re-login only helps OAuth contexts.
             if (error.response.status === 401) {
-                throw new ApiError('Session expired. Please run: aderis auth login', 401, error.response.data);
+                throw new ApiError(unauthorizedMessage(context), 401, error.response.data);
             }
             const message = extractErrorMessage(error.response.data);
             throw new ApiError(message, error.response.status, error.response.data);

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

@@ -0,0 +1,11 @@
+/**
+ * Loopback redirect (RFC 8252 §7.3). The Keycloak client registers
+ * `http://localhost:*`; one shared port keeps every context on a registered redirect.
+ */
+export declare const CALLBACK_PORT = 8085;
+export declare const REDIRECT_URI = "http://localhost:8085/oauth/callback";
+/** Headers for `application/x-www-form-urlencoded` token endpoint requests (RFC 6749 §4.1.3). */
+export declare const FORM_POST_HEADERS: {
+    readonly Accept: "application/json";
+    readonly 'Content-Type': "application/x-www-form-urlencoded";
+};

package/dist/lib/auth/constants.js

@@ -0,0 +1,11 @@
+/**
+ * Loopback redirect (RFC 8252 §7.3). The Keycloak client registers
+ * `http://localhost:*`; one shared port keeps every context on a registered redirect.
+ */
+export const CALLBACK_PORT = 8085;
+export const REDIRECT_URI = `http://localhost:${CALLBACK_PORT}/oauth/callback`;
+/** Headers for `application/x-www-form-urlencoded` token endpoint requests (RFC 6749 §4.1.3). */
+export const FORM_POST_HEADERS = {
+    Accept: 'application/json',
+    'Content-Type': 'application/x-www-form-urlencoded',
+};

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

@@ -0,0 +1,17 @@
+/**
+ * An authentication-protocol failure reported to the user, distinct from
+ * transport errors (axios) and from `ApiError`. Never wraps the axios error:
+ * its request config carries the form body (refresh token, PKCE verifier,
+ * client secret).
+ */
+export declare class AuthError extends Error {
+    /** HTTP status of the response that caused this error, when there was one. */
+    readonly status?: number;
+    constructor(message: string, options?: {
+        status?: number;
+    });
+}
+/** The token that ended a tenant switch is not for the requested tenant; shown as "Tenant Switch Failed" (HTTP 400). */
+export declare class TenantMismatchError extends AuthError {
+    constructor(message: string);
+}

package/dist/lib/auth/errors.js

@@ -0,0 +1,22 @@
+/**
+ * An authentication-protocol failure reported to the user, distinct from
+ * transport errors (axios) and from `ApiError`. Never wraps the axios error:
+ * its request config carries the form body (refresh token, PKCE verifier,
+ * client secret).
+ */
+export class AuthError extends Error {
+    /** HTTP status of the response that caused this error, when there was one. */
+    status;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'AuthError';
+        this.status = options.status;
+    }
+}
+/** The token that ended a tenant switch is not for the requested tenant; shown as "Tenant Switch Failed" (HTTP 400). */
+export class TenantMismatchError extends AuthError {
+    constructor(message) {
+        super(message);
+        this.name = 'TenantMismatchError';
+    }
+}

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

@@ -0,0 +1,27 @@
+import { type Context, type TokenData } from '../config.js';
+import { type PageMessage } from './pages.js';
+import { type AuthProvider, type AuthRound } from './types.js';
+export interface BrowserFlowOptions {
+    /** Line logger for the "Opening browser…" hints. Defaults to `console.log`. */
+    log?: (line: string) => void;
+    /** Opens the authorize URL. Defaults to the system browser; tests inject a stub. */
+    openBrowser?: (url: string) => Promise<unknown>;
+    /** Page shown after the last round succeeds. */
+    success: {
+        message: PageMessage | string;
+        title: string;
+    };
+}
+/** The injectable parts of a browser flow. */
+export type FlowHooks = Pick<BrowserFlowOptions, 'log' | 'openBrowser'>;
+/**
+ * Runs one or more authorization rounds through a single local callback server
+ * and a single browser tab. Per round: the browser lands on `/oauth/callback`,
+ * the code is exchanged via the provider, the tokens are saved to the context
+ * and the round's `afterExchange` hook runs (tokens it returns are saved and
+ * become the round's result). A following round is entered via
+ * a meta-refresh into its authorize URL; the last round answers the success
+ * page and resolves with its tokens. A callback whose `state` is not the
+ * expected round's is rejected.
+ */
+export declare function runBrowserFlow(context: Context, provider: AuthProvider, rounds: AuthRound[], options: BrowserFlowOptions): Promise<TokenData>;

package/dist/lib/auth/flow.js

@@ -0,0 +1,163 @@
+import * as http from 'node:http';
+import { URL } from 'node:url';
+import open from 'open';
+import { saveTokens } from '../config.js';
+import { CALLBACK_PORT } from './constants.js';
+import { TenantMismatchError } from './errors.js';
+import { renderAuthPage, renderRedirectPage } from './pages.js';
+import { generateNonce, generatePkce, generateState } from './pkce.js';
+const FLOW_TIMEOUT_MS = 5 * 60 * 1000;
+async function prepareRounds(context, provider, rounds) {
+    const prepared = [];
+    for (const round of rounds) {
+        const pkce = generatePkce();
+        const state = generateState();
+        const nonce = generateNonce();
+        const authorizeUrl = await provider.buildAuthorizeUrl(context, {
+            codeChallenge: pkce.challenge,
+            nonce,
+            prompt: round.prompt,
+            state,
+        });
+        prepared.push({ ...round, authorizeUrl, codeVerifier: pkce.verifier, nonce, state });
+    }
+    return prepared;
+}
+/**
+ * Runs one or more authorization rounds through a single local callback server
+ * and a single browser tab. Per round: the browser lands on `/oauth/callback`,
+ * the code is exchanged via the provider, the tokens are saved to the context
+ * and the round's `afterExchange` hook runs (tokens it returns are saved and
+ * become the round's result). A following round is entered via
+ * a meta-refresh into its authorize URL; the last round answers the success
+ * page and resolves with its tokens. A callback whose `state` is not the
+ * expected round's is rejected.
+ */
+export async function runBrowserFlow(context, provider, rounds, options) {
+    if (rounds.length === 0) {
+        throw new Error('A browser flow needs at least one authorization round');
+    }
+    const log = options.log ?? console.log;
+    const openBrowser = options.openBrowser ?? ((url) => open(url));
+    const prepared = await prepareRounds(context, provider, rounds);
+    return new Promise((resolve, reject) => {
+        const connections = new Set();
+        let currentRound = 0;
+        // States whose callback has been taken: a duplicate arriving while its
+        // exchange is in flight is answered, not redeemed again.
+        const redeemed = new Set();
+        // Holder: closeServer references the timer before it exists.
+        const timeout = {};
+        const closeServer = () => {
+            if (timeout.id)
+                clearTimeout(timeout.id);
+            for (const socket of connections) {
+                socket.destroy();
+            }
+            connections.clear();
+            server.close();
+            process.off('SIGINT', onSigint);
+        };
+        const onSigint = () => {
+            closeServer();
+            // Exit with the SIGINT status so the parent shell sees the termination.
+            // eslint-disable-next-line unicorn/no-process-exit, n/no-process-exit
+            process.exit(130);
+        };
+        const fail = (res, status, title, error) => {
+            res.writeHead(status, { 'Content-Type': 'text/html' });
+            res.end(renderAuthPage('error', title, error.message));
+            // Let the page reach the browser before the connection is torn down.
+            setImmediate(() => {
+                closeServer();
+                reject(error);
+            });
+        };
+        const server = http.createServer(async (req, res) => {
+            const url = new URL(req.url || '', `http://localhost:${CALLBACK_PORT}`);
+            if (url.pathname !== '/oauth/callback') {
+                res.writeHead(404);
+                res.end('Not Found');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const returnedState = url.searchParams.get('state');
+            const error = url.searchParams.get('error');
+            const errorDescription = url.searchParams.get('error_description');
+            if (error) {
+                fail(res, 400, 'Authentication Failed', new Error(errorDescription || error));
+                return;
+            }
+            // A callback already taken (a browser retry, or a late one after the last
+            // round) has nothing to redeem and must not abort the flow.
+            const round = prepared[currentRound];
+            if (!round || (returnedState && redeemed.has(returnedState))) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                res.end('This authorization response has already been used');
+                return;
+            }
+            if (!code || returnedState !== round.state) {
+                fail(res, 400, 'Authentication Failed', new Error('Invalid authorization response'));
+                return;
+            }
+            redeemed.add(round.state);
+            try {
+                const exchanged = await provider.exchangeCode(context, {
+                    code,
+                    codeVerifier: round.codeVerifier,
+                    nonce: round.nonce,
+                });
+                saveTokens(context.name, exchanged);
+                const tokens = (await round.afterExchange?.(exchanged)) ?? exchanged;
+                if (tokens !== exchanged)
+                    saveTokens(context.name, tokens);
+                currentRound += 1;
+                const next = prepared[currentRound];
+                if (next) {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(renderRedirectPage(next.authorizeUrl));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(renderAuthPage('success', options.success.title, options.success.message));
+                // Let the response flush before tearing the server down.
+                setImmediate(() => {
+                    closeServer();
+                    resolve(tokens);
+                });
+            }
+            catch (error_) {
+                const failure = error_ instanceof Error ? error_ : new Error(String(error_));
+                if (failure instanceof TenantMismatchError) {
+                    fail(res, 400, 'Tenant Switch Failed', failure);
+                }
+                else {
+                    fail(res, 500, 'Authentication Failed', failure);
+                }
+            }
+        });
+        // Tracked so closeServer can destroy them.
+        server.on('connection', (socket) => {
+            connections.add(socket);
+            socket.on('close', () => connections.delete(socket));
+        });
+        server.on('error', (err) => {
+            closeServer();
+            reject(new Error(`Failed to start local server: ${err.message}`));
+        });
+        process.once('SIGINT', onSigint);
+        server.listen(CALLBACK_PORT, () => {
+            const first = prepared[0].authorizeUrl;
+            log('Opening browser for authentication...');
+            log(`If the browser doesn't open, visit: ${first}`);
+            openBrowser(first).catch((error) => {
+                // The URL was printed above, so a browser that fails to launch is not fatal.
+                log(`Could not open the browser automatically: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        });
+        timeout.id = setTimeout(() => {
+            closeServer();
+            reject(new Error('Authentication timed out'));
+        }, FLOW_TIMEOUT_MS);
+    });
+}

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

@@ -0,0 +1,5 @@
+import { type Context } from '../config.js';
+/** Guard for OAuth-only flows (browser login, token refresh, tenant switching); API keys are issued per tenant. */
+export declare function requireOAuthContext(context: Context, action: string): void;
+/** `client_id` is optional on Context (API-key contexts have none), so OAuth flows must assert it. */
+export declare function requireClientId(context: Context): string;

package/dist/lib/auth/guards.js

@@ -0,0 +1,14 @@
+import { getAuthType } from '../config.js';
+/** Guard for OAuth-only flows (browser login, token refresh, tenant switching); API keys are issued per tenant. */
+export function requireOAuthContext(context, action) {
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`${action} requires OAuth. Context "${context.name}" authenticates with an API key, which is already scoped to one tenant.`);
+    }
+}
+/** `client_id` is optional on Context (API-key contexts have none), so OAuth flows must assert it. */
+export function requireClientId(context) {
+    if (!context.client_id) {
+        throw new Error(`Context "${context.name}" has no OAuth client ID. Recreate it with: aderis config add`);
+    }
+    return context.client_id;
+}

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

@@ -0,0 +1,16 @@
+import { AuthError } from './errors.js';
+/**
+ * Upper bound for every auth-layer HTTP request (OIDC discovery, token
+ * endpoint); the browser-flow timer only starts after discovery.
+ */
+export declare const HTTP_TIMEOUT_MS = 10000;
+/** The one axios instance the auth layer uses, so the timeout applies everywhere. */
+export declare const authHttp: import("axios").AxiosInstance;
+/** HTTP status behind an error, whether axios raised it or an {@link AuthError} wrapped it. */
+export declare function httpStatusOf(error: unknown): number | undefined;
+/**
+ * Turns any failure of an auth-layer request into an {@link AuthError} naming
+ * `what` was attempted and what came back (status and OAuth error code, timeout
+ * or transport message), never the request itself. An {@link AuthError} passes through.
+ */
+export declare function toAuthError(error: unknown, what: string): AuthError;

package/dist/lib/auth/http.js

@@ -0,0 +1,49 @@
+import axios from 'axios';
+import { AuthError } from './errors.js';
+/**
+ * Upper bound for every auth-layer HTTP request (OIDC discovery, token
+ * endpoint); the browser-flow timer only starts after discovery.
+ */
+export const HTTP_TIMEOUT_MS = 10_000;
+/** The one axios instance the auth layer uses, so the timeout applies everywhere. */
+export const authHttp = axios.create({ timeout: HTTP_TIMEOUT_MS });
+/** HTTP status behind an error, whether axios raised it or an {@link AuthError} wrapped it. */
+export function httpStatusOf(error) {
+    if (error instanceof AuthError)
+        return error.status;
+    if (axios.isAxiosError(error))
+        return error.response?.status;
+    return undefined;
+}
+function isTimeout(error) {
+    return error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT';
+}
+/** `error` / `error_description` from an OAuth error body (RFC 6749 §5.2), when the server sent them. */
+function describeErrorBody(data) {
+    if (!data || typeof data !== 'object')
+        return '';
+    const { error, error_description: description } = data;
+    if (typeof error !== 'string' || !error)
+        return '';
+    return typeof description === 'string' && description ? `: ${error} (${description})` : `: ${error}`;
+}
+/**
+ * Turns any failure of an auth-layer request into an {@link AuthError} naming
+ * `what` was attempted and what came back (status and OAuth error code, timeout
+ * or transport message), never the request itself. An {@link AuthError} passes through.
+ */
+export function toAuthError(error, what) {
+    if (error instanceof AuthError)
+        return error;
+    if (axios.isAxiosError(error)) {
+        if (error.response) {
+            const { status } = error.response;
+            return new AuthError(`${what} failed with HTTP ${status}${describeErrorBody(error.response.data)}`, { status });
+        }
+        if (isTimeout(error)) {
+            return new AuthError(`${what} timed out after ${error.config?.timeout ?? HTTP_TIMEOUT_MS} ms`);
+        }
+        return new AuthError(`${what} failed: ${error.message}`);
+    }
+    return new AuthError(`${what} failed: ${error instanceof Error ? error.message : String(error)}`);
+}

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

@@ -0,0 +1,49 @@
+import { type Context, type TokenData } from '../config.js';
+import { type FlowHooks } from './flow.js';
+import { type Tenant } from './types.js';
+export { CALLBACK_PORT, REDIRECT_URI } from './constants.js';
+export { AuthError, TenantMismatchError } from './errors.js';
+export { type FlowHooks } from './flow.js';
+export { keycloakBaseUrlOf, keycloakProvider, parseKeycloakBaseUrl } from './keycloak-provider.js';
+export { type AuthProvider, type Tenant } from './types.js';
+export { buildValidatedUrl } from './validated-url.js';
+export declare function login(context: Context, options?: FlowHooks & {
+    prompt?: 'login' | 'none';
+}): Promise<TokenData>;
+export declare function refreshTokens(contextName: string): Promise<TokenData>;
+export declare function getValidToken(contextName: string): Promise<string>;
+/**
+ * Auth headers for a context: a bearer token for `oauth2` (refreshed first when
+ * needed) or `x-api-key` for `api_key`. The one place credentials become headers.
+ */
+export declare function getAuthHeaders(contextName: string): Promise<Record<string, string>>;
+/** The user `/v1/auth/me` resolved for the session; the fields the CLI shows. */
+export interface AuthenticatedUser {
+    email?: string;
+    name?: string;
+}
+export declare function testAuth(contextName: string): Promise<AuthenticatedUser>;
+export declare function listTenants(contextName: string): Promise<Tenant[]>;
+/** A tenant for display: `name (id)`, or the id alone when the name is missing or equals the id. */
+export declare function tenantLabel(tenant: {
+    name?: string;
+    tenantId: string;
+}): string;
+export declare function getCurrentTenant(contextName: string): Promise<null | {
+    name?: string;
+    tenantId: string;
+}>;
+/**
+ * Switches the tenant of a context whose session is still valid: one
+ * refresh-token request carrying the tenant, asserted to have landed on
+ * `tenantId` and stored. No browser is involved, so there are no flow hooks.
+ */
+export declare function switchTenant(contextName: string, tenantId: string): Promise<TokenData>;
+/** Login and tenant switch for `aderis switch` on an expired session: the provider's rounds in one browser tab, asserted like {@link switchTenant}. */
+export declare function loginAndSwitchTenant(context: Context, tenantId: string, hooks?: FlowHooks): Promise<TokenData>;
+/**
+ * Gives a fresh login an active tenant when its token has none: the sole tenant
+ * is taken, several are offered to `choose`, and {@link switchTenant} follows.
+ * Resolves `null` when the stored token already has a tenant.
+ */
+export declare function completeTenantSelection(contextName: string, choose: (tenants: Tenant[]) => Promise<string>): Promise<null | TokenData>;

package/dist/lib/auth/index.js

@@ -0,0 +1,217 @@
+/**
+ * Public surface of the auth layer. OAuth contexts authenticate against
+ * Keycloak; the protocol details live in `keycloak-provider.ts`.
+ */
+import axios from 'axios';
+import { getAuthType, getBaseUrls, getContext, missingCredentialsMessage, saveCachedTenants, saveTokens, SESSION_EXPIRED_MESSAGE, unauthorizedMessage, } from '../config.js';
+import { AuthError, TenantMismatchError } from './errors.js';
+import { runBrowserFlow } from './flow.js';
+import { requireOAuthContext } from './guards.js';
+import { httpStatusOf } from './http.js';
+import { keycloakProvider } from './keycloak-provider.js';
+import { decodeToken, tenantIdOf } from './tokens.js';
+import { buildValidatedUrl } from './validated-url.js';
+export { CALLBACK_PORT, REDIRECT_URI } from './constants.js';
+export { AuthError, TenantMismatchError } from './errors.js';
+export { keycloakBaseUrlOf, keycloakProvider, parseKeycloakBaseUrl } from './keycloak-provider.js';
+export { buildValidatedUrl } from './validated-url.js';
+function requireContext(contextName) {
+    const context = getContext(contextName);
+    if (!context) {
+        throw new Error(`Context "${contextName}" not found`);
+    }
+    return context;
+}
+/** A tenant switch must have landed on the requested tenant. */
+function assertTenant(tokens, tenantId) {
+    if (tokens.tenant_id !== tenantId) {
+        throw new TenantMismatchError(`Keycloak returned a token for tenant ${tokens.tenant_id ?? 'none'} instead of ${tenantId}. Please try again in a few seconds.`);
+    }
+    return tokens;
+}
+/** The final round of a tenant switch ends with the tenant assertion on its resulting tokens. */
+function withTenantAssertion(rounds, tenantId) {
+    const last = rounds.at(-1);
+    if (!last)
+        return rounds;
+    const { afterExchange } = last;
+    return [
+        ...rounds.slice(0, -1),
+        {
+            ...last,
+            async afterExchange(tokens) {
+                return assertTenant((await afterExchange?.(tokens)) ?? tokens, tenantId);
+            },
+        },
+    ];
+}
+export async function login(context, options = {}) {
+    requireOAuthContext(context, 'Browser login');
+    return runBrowserFlow(context, keycloakProvider, [{ prompt: options.prompt }], {
+        log: options.log,
+        openBrowser: options.openBrowser,
+        success: {
+            message: { subject: context.name, tail: ` (${context.environment}).`, text: 'You have been logged in to ' },
+            title: 'Authentication Successful',
+        },
+    });
+}
+export async function refreshTokens(contextName) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Token refresh');
+    if (!context.tokens?.refresh_token) {
+        throw new Error('No refresh token available. Please login again.');
+    }
+    const refreshed = await keycloakProvider.refresh(context, context.tokens.refresh_token);
+    const tokenData = {
+        ...refreshed,
+        // A refresh response may omit the refresh token; the stored one stays valid.
+        refresh_token: refreshed.refresh_token || context.tokens.refresh_token,
+    };
+    saveTokens(contextName, tokenData);
+    return tokenData;
+}
+export async function getValidToken(contextName) {
+    const context = requireContext(contextName);
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`Context "${contextName}" authenticates with an API key and has no access token. Use getAuthHeaders() instead.`);
+    }
+    if (!context.tokens?.access_token) {
+        throw new Error('Not logged in. Please run: aderis auth login');
+    }
+    if (context.tokens.expires_at && context.tokens.expires_at < Date.now() + 60_000) {
+        if (context.tokens.refresh_token) {
+            const newTokens = await refreshTokens(contextName);
+            return newTokens.access_token;
+        }
+        throw new Error('Token expired. Please run: aderis auth login');
+    }
+    return context.tokens.access_token;
+}
+/**
+ * Auth headers for a context: a bearer token for `oauth2` (refreshed first when
+ * needed) or `x-api-key` for `api_key`. The one place credentials become headers.
+ */
+export async function getAuthHeaders(contextName) {
+    const context = requireContext(contextName);
+    if (getAuthType(context) === 'api_key') {
+        if (!context.api_key) {
+            throw new Error(missingCredentialsMessage(context));
+        }
+        return { 'x-api-key': context.api_key };
+    }
+    return { Authorization: `Bearer ${await getValidToken(contextName)}` };
+}
+export async function testAuth(contextName) {
+    const context = requireContext(contextName);
+    const { api: apiUrl } = getBaseUrls(context.environment);
+    try {
+        const response = await axios.get(buildValidatedUrl(apiUrl, '/v1/auth/me'), {
+            headers: {
+                Accept: 'application/json',
+                ...(await getAuthHeaders(contextName)),
+            },
+        });
+        const { user } = response.data;
+        if (!user) {
+            throw new Error('The API answered /v1/auth/me without a user object.');
+        }
+        return user;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 401) {
+            throw new Error(unauthorizedMessage(context));
+        }
+        throw error;
+    }
+}
+export async function listTenants(contextName) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Listing tenants');
+    const token = await getValidToken(contextName);
+    const tenants = await keycloakProvider.listTenants(context, token);
+    // Cached for the picker `aderis switch` shows once the access token has expired.
+    saveCachedTenants(contextName, tenants.map((t) => ({ name: t.name, tenantId: t.tenantId })));
+    return tenants;
+}
+/** A tenant for display: `name (id)`, or the id alone when the name is missing or equals the id. */
+export function tenantLabel(tenant) {
+    return tenant.name && tenant.name !== tenant.tenantId ? `${tenant.name} (${tenant.tenantId})` : tenant.tenantId;
+}
+export async function getCurrentTenant(contextName) {
+    const context = requireContext(contextName);
+    // API-key contexts carry no JWT, so there is no tenant to decode locally.
+    if (getAuthType(context) === 'api_key' || !context.tokens?.access_token) {
+        return null;
+    }
+    const tenantId = tenantIdOf(decodeToken(context.tokens.access_token));
+    if (!tenantId) {
+        return null;
+    }
+    try {
+        const tenants = await listTenants(contextName);
+        const tenant = tenants.find((t) => t.tenantId === tenantId);
+        return { name: tenant?.name, tenantId };
+    }
+    catch {
+        return { tenantId };
+    }
+}
+/**
+ * Switches the tenant of a context whose session is still valid: one
+ * refresh-token request carrying the tenant, asserted to have landed on
+ * `tenantId` and stored. No browser is involved, so there are no flow hooks.
+ */
+export async function switchTenant(contextName, tenantId) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Switching tenants');
+    const refreshToken = context.tokens?.refresh_token;
+    if (!refreshToken) {
+        throw new Error('No refresh token available. Please login again.');
+    }
+    try {
+        const tokens = assertTenant(await keycloakProvider.switchTenant(context, refreshToken, tenantId), tenantId);
+        saveTokens(contextName, tokens);
+        return tokens;
+    }
+    catch (error) {
+        const status = httpStatusOf(error);
+        if (status === 400 || status === 401) {
+            throw new AuthError(SESSION_EXPIRED_MESSAGE, { status });
+        }
+        throw error;
+    }
+}
+/** Login and tenant switch for `aderis switch` on an expired session: the provider's rounds in one browser tab, asserted like {@link switchTenant}. */
+export async function loginAndSwitchTenant(context, tenantId, hooks = {}) {
+    requireOAuthContext(context, 'Switching tenants');
+    const rounds = withTenantAssertion(keycloakProvider.tenantSwitchRounds(context, tenantId), tenantId);
+    return runBrowserFlow(context, keycloakProvider, rounds, {
+        ...hooks,
+        success: {
+            message: { subject: context.name, tail: ' on the selected tenant.', text: 'You have been logged in to ' },
+            title: 'Tenant Switched',
+        },
+    });
+}
+/**
+ * Gives a fresh login an active tenant when its token has none: the sole tenant
+ * is taken, several are offered to `choose`, and {@link switchTenant} follows.
+ * Resolves `null` when the stored token already has a tenant.
+ */
+export async function completeTenantSelection(contextName, choose) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Tenant selection');
+    if (!context.tokens?.access_token) {
+        throw new Error('Not logged in. Please run: aderis auth login');
+    }
+    if (context.tenant_id || tenantIdOf(decodeToken(context.tokens.access_token))) {
+        return null;
+    }
+    const tenants = await listTenants(contextName);
+    if (tenants.length === 0) {
+        throw new AuthError(`The Keycloak token for "${contextName}" lists no tenants, so you have reached no tenant. Contact your administrator.`);
+    }
+    const tenantId = tenants.length === 1 ? tenants[0].tenantId : await choose(tenants);
+    return switchTenant(contextName, tenantId);
+}