@aderis-erp/cli 1.0.17 → 1.1.1

package/dist/commands/workflows.js

@@ -1,5 +1,5 @@
 import { Command, Args, Flags } from '@oclif/core';
-import { apiRequest, ApiError, normalizeSortBy } from '../lib/api-client.js';
+import { apiRequest, ApiError, isTextualMediaType, normalizeSortBy } from '../lib/api-client.js';
 import { getCurrentContext, getContext, getBaseUrls, hasCredentials, missingCredentialsMessage } from '../lib/config.js';
 // Add 'import' action if both create and update exist
 const HAS_IMPORT = false;
@@ -8,9 +8,9 @@ const HAS_CAMT053 = false;
 const NESTED_IMPORTS = [];
 const SUBCOMMANDS = [...["list", "status", "find"], ...(HAS_IMPORT ? ['import'] : []), ...(HAS_EXPORT ? ['export'] : []), ...NESTED_IMPORTS.map(n => `import-${n}`)];
 const ENDPOINTS = {
-    'list': { method: 'GET', path: '/v1/workflows', summary: 'Get all workflows with their summary', pathParams: [], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'status': { method: 'POST', path: '/v1/workflows/status', summary: 'Create a new workflow status update', pathParams: [], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'find': { method: 'GET', path: '/v1/workflows/{workflowId}', summary: 'Get workflow details including status updates and entity changes', pathParams: ['workflowId'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
+    'list': { method: 'GET', path: '/v1/workflows', summary: 'Get all workflows with their summary', pathParams: [], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'status': { method: 'POST', path: '/v1/workflows/status', summary: 'Create a new workflow status update', pathParams: [], hasBody: true, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'find': { method: 'GET', path: '/v1/workflows/{workflowId}', summary: 'Get workflow details including status updates and entity changes', pathParams: ['workflowId'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
 };
 export default class Workflows extends Command {
     static description = 'Manage workflows';
@@ -258,10 +258,11 @@ export default class Workflows extends Command {
             process.stderr.write('\n');
         }
         try {
-            // Binary response: download to file
+            // Binary response: to -f / --file, or to stdout when it is redirected.
             if (endpoint.isBinaryResponse) {
-                if (!flags.file) {
-                    this.error(`Endpoint returns a binary file. Specify the output path with -f / --file (e.g. -f report.xlsx).`);
+                const toStdout = !flags.file;
+                if (toStdout && process.stdout.isTTY) {
+                    this.error(`Endpoint returns a binary file. Specify the output path with -f / --file (e.g. -f report.xlsx), or redirect stdout to a file.`);
                 }
                 const binResponse = await apiRequest(endpoint.method, apiPath, {
                     params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
@@ -269,24 +270,55 @@ export default class Workflows extends Command {
                     contextName: flags.context,
                     binary: true,
                 });
-                const fsModule = await import('node:fs');
                 const binData = binResponse.data;
                 const buffer = Buffer.isBuffer(binData)
                     ? binData
                     : Buffer.from(binData);
+                if (toStdout) {
+                    // Nothing else may reach stdout here — it is the file.
+                    process.stdout.write(buffer);
+                    return;
+                }
+                const fsModule = await import('node:fs');
                 fsModule.writeFileSync(flags.file, buffer);
                 this.log(`Saved ${buffer.length} bytes to ${flags.file}`);
                 return;
             }
-            const response = await apiRequest(endpoint.method, apiPath, {
-                params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
-                data,
-                contextName: flags.context,
-                acceptAny: true,
-            });
+            let response;
+            if (endpoint.hasBinaryVariant) {
+                // This route answers JSON or a file depending on the request body, so the
+                // bytes are read first and the response's own content-type decides. Asking
+                // for text here would corrupt an xlsx/pdf before anything could inspect it.
+                const raw = await apiRequest(endpoint.method, apiPath, {
+                    params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+                    data,
+                    contextName: flags.context,
+                    binary: true,
+                });
+                const rawType = String(raw.headers['content-type'] || '').toLowerCase();
+                const rawData = raw.data;
+                const buffer = Buffer.isBuffer(rawData) ? rawData : Buffer.from(rawData);
+                if (!isTextualMediaType(rawType)) {
+                    if (process.stdout.isTTY) {
+                        this.error(`The API returned ${rawType || 'binary data'}. Redirect stdout to a file, e.g. ... > report.xlsx`);
+                    }
+                    // Nothing else may reach stdout here — it is the file.
+                    process.stdout.write(buffer);
+                    return;
+                }
+                response = { data: buffer.toString('utf8'), headers: raw.headers, status: raw.status };
+            }
+            else {
+                response = await apiRequest(endpoint.method, apiPath, {
+                    params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+                    data,
+                    contextName: flags.context,
+                    acceptAny: true,
+                });
+            }
             // Check content-type for non-JSON responses (XML, text, etc.)
             const contentType = (response.headers['content-type'] || '').toLowerCase();
-            if (contentType.includes('xml') || contentType.includes('text/')) {
+            if (isTextualMediaType(contentType) && !contentType.startsWith('application/json')) {
                 // Output raw content for XML/text responses (CSV, plain, HTML, etc.)
                 this.log(String(response.data));
                 return;

package/dist/lib/api-client.d.ts

@@ -28,6 +28,12 @@ export interface PaginatedResponse<T> {
  * into repeated `sortBy=a:ASC&sortBy=b:DESC` params.
  */
 export declare function normalizeSortBy(input: string): string[];
+/**
+ * Whether a response body is text the CLI may decode. Matched on the media type
+ * rather than by substring: application/vnd.openxmlformats-officedocument...
+ * (xlsx) contains "xml" but is a zip, and decoding it corrupts every byte.
+ */
+export declare function isTextualMediaType(contentType: string): boolean;
 export declare class ApiError extends Error {
     status: number;
     data?: unknown | undefined;

package/dist/lib/api-client.js

@@ -21,6 +21,19 @@ export function normalizeSortBy(input) {
         return `${part}:${dateLike ? 'DESC' : 'ASC'}`;
     });
 }
+/**
+ * Whether a response body is text the CLI may decode. Matched on the media type
+ * rather than by substring: application/vnd.openxmlformats-officedocument...
+ * (xlsx) contains "xml" but is a zip, and decoding it corrupts every byte.
+ */
+export function isTextualMediaType(contentType) {
+    const type = contentType.split(';')[0].trim().toLowerCase();
+    if (type.startsWith('text/'))
+        return true;
+    if (type === 'application/json' || type === 'application/xml')
+        return true;
+    return type.endsWith('+json') || type.endsWith('+xml');
+}
 export class ApiError extends Error {
     status;
     data;

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

@@ -9,3 +9,15 @@ export declare const FORM_POST_HEADERS: {
     readonly Accept: "application/json";
     readonly 'Content-Type': "application/x-www-form-urlencoded";
 };
+/**
+ * Acting as Aderis Support. The realm mints a second login for the shared
+ * support account through a custom grant, taking the operator's own access
+ * token as the Bearer. The support token names the customer in `tenantId` and
+ * the operator in `impersonatorId`; the backend records that pair on every
+ * write (backend/docs/concepts/2026-09-23-support-impersonator-audit-attribution.md).
+ */
+export declare const SUPPORT_SESSION_GRANT_TYPE = "urn:aderis:params:oauth:grant-type:support-session";
+/** Public client of the support session; like the CLI client it holds no secret. */
+export declare const SUPPORT_CLIENT_ID = "aderis-support-session";
+/** Keycloak ends a support session after this long however active it is. */
+export declare const SUPPORT_SESSION_MAX_LIFESPAN_S: number;

package/dist/lib/auth/constants.js

@@ -9,3 +9,15 @@ export const FORM_POST_HEADERS = {
     Accept: 'application/json',
     'Content-Type': 'application/x-www-form-urlencoded',
 };
+/**
+ * Acting as Aderis Support. The realm mints a second login for the shared
+ * support account through a custom grant, taking the operator's own access
+ * token as the Bearer. The support token names the customer in `tenantId` and
+ * the operator in `impersonatorId`; the backend records that pair on every
+ * write (backend/docs/concepts/2026-09-23-support-impersonator-audit-attribution.md).
+ */
+export const SUPPORT_SESSION_GRANT_TYPE = 'urn:aderis:params:oauth:grant-type:support-session';
+/** Public client of the support session; like the CLI client it holds no secret. */
+export const SUPPORT_CLIENT_ID = 'aderis-support-session';
+/** Keycloak ends a support session after this long however active it is. */
+export const SUPPORT_SESSION_MAX_LIFESPAN_S = 4 * 60 * 60;

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

@@ -1,6 +1,7 @@
-import { type Context, type TokenData } from '../config.js';
+import { type Context, type SupportSession, type TokenData } from '../config.js';
 import { type FlowHooks } from './flow.js';
 import { type Tenant } from './types.js';
+export { type SupportSession } from '../config.js';
 export { CALLBACK_PORT, REDIRECT_URI } from './constants.js';
 export { AuthError, TenantMismatchError } from './errors.js';
 export { type FlowHooks } from './flow.js';
@@ -17,6 +18,15 @@ export declare function getValidToken(contextName: string): Promise<string>;
  * needed) or `x-api-key` for `api_key`. The one place credentials become headers.
  */
 export declare function getAuthHeaders(contextName: string): Promise<Record<string, string>>;
+/** Customers the operator may act for, as Keycloak lists them. */
+export declare function listSupportTenants(contextName: string): Promise<Tenant[]>;
+/**
+ * Starts a support session on the context and stores it beside the operator's
+ * own login. Subsequent API calls go out as Aderis Support until it is ended.
+ */
+export declare function startSupportSession(contextName: string, tenantId: string): Promise<SupportSession>;
+/** Ends the running support session; the operator's own login is untouched. */
+export declare function endSupportSession(contextName: string): Promise<null | SupportSession>;
 /** The user `/v1/auth/me` resolved for the session; the fields the CLI shows. */
 export interface AuthenticatedUser {
     email?: string;

package/dist/lib/auth/index.js

@@ -3,18 +3,20 @@
  * 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 { clearSupportSession, getAuthType, getBaseUrls, getContext, getSupportSession, missingCredentialsMessage, saveCachedTenants, saveSupportSession, 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 { 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';
+/** A token this close to expiry is refreshed rather than sent. */
+const EXPIRY_BUFFER_MS = 60_000;
 function requireContext(contextName) {
     const context = getContext(contextName);
     if (!context) {
@@ -62,6 +64,9 @@ export async function refreshTokens(contextName) {
     if (!context.tokens?.refresh_token) {
         throw new Error('No refresh token available. Please login again.');
     }
+    // The tenant of the new token is the realm's to decide: the CLI does not name
+    // one here, so a mapper that picks the wrong tenant is visible as a server
+    // bug rather than papered over per request.
     const refreshed = await keycloakProvider.refresh(context, context.tokens.refresh_token);
     const tokenData = {
         ...refreshed,
@@ -79,7 +84,7 @@ export async function getValidToken(contextName) {
     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.expires_at && context.tokens.expires_at < Date.now() + EXPIRY_BUFFER_MS) {
         if (context.tokens.refresh_token) {
             const newTokens = await refreshTokens(contextName);
             return newTokens.access_token;
@@ -100,8 +105,94 @@ export async function getAuthHeaders(contextName) {
         }
         return { 'x-api-key': context.api_key };
     }
+    // While acting as Aderis Support every call goes out as the support account,
+    // and the operator is told so — a write made here is attributed to them.
+    const support = getSupportSession(context);
+    if (support) {
+        const token = await validSupportToken(contextName, support);
+        warnActingAsSupport(context.name, support);
+        return { Authorization: `Bearer ${token}` };
+    }
     return { Authorization: `Bearer ${await getValidToken(contextName)}` };
 }
+/** Printed once per process, to stderr so it never lands in piped output. */
+let warnedAboutSupport = false;
+function warnActingAsSupport(contextName, support) {
+    if (warnedAboutSupport)
+        return;
+    warnedAboutSupport = true;
+    process.stderr.write(`! Acting as Aderis Support in ${support.tenant_name} (context ${contextName}). ` +
+        `Everything you do is recorded against you. End with: aderis support end\n`);
+}
+/** The support access token, refreshed when it is within the expiry buffer. */
+async function validSupportToken(contextName, support) {
+    if (support.tokens.expires_at && support.tokens.expires_at < Date.now() + EXPIRY_BUFFER_MS) {
+        if (!support.tokens.refresh_token) {
+            throw new AuthError('The support session has ended. Start a new one with: aderis support start <tenant-id>');
+        }
+        const context = requireContext(contextName);
+        const refreshed = await keycloakProvider.refreshSupportSession(context, support.tokens.refresh_token);
+        const tokens = { ...refreshed, refresh_token: refreshed.refresh_token || support.tokens.refresh_token };
+        saveSupportSession(contextName, { ...support, tokens });
+        return tokens.access_token;
+    }
+    return support.tokens.access_token;
+}
+/** Customers the operator may act for, as Keycloak lists them. */
+export async function listSupportTenants(contextName) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Support sessions');
+    if (getSupportSession(context)) {
+        throw new AuthError('A support session is already running. End it first with: aderis support end');
+    }
+    return keycloakProvider.listSupportTenants(context, await getValidToken(contextName));
+}
+/**
+ * Starts a support session on the context and stores it beside the operator's
+ * own login. Subsequent API calls go out as Aderis Support until it is ended.
+ */
+export async function startSupportSession(contextName, tenantId) {
+    const context = requireContext(contextName);
+    requireOAuthContext(context, 'Support sessions');
+    if (getSupportSession(context)) {
+        throw new AuthError('A support session is already running. End it first with: aderis support end');
+    }
+    const operatorToken = await getValidToken(contextName);
+    const operatorSub = decodedSub(operatorToken);
+    const tenants = await keycloakProvider.listSupportTenants(context, operatorToken);
+    const chosen = tenants.find((t) => t.tenantId === tenantId);
+    if (!chosen) {
+        throw new AuthError(`Tenant ${tenantId} is not one you may act for. List them with: aderis support tenants --context ${contextName}`);
+    }
+    const tokens = await keycloakProvider.startSupportSession(context, operatorToken, tenantId);
+    const support = {
+        operator_sub: operatorSub,
+        tenant_id: tenantId,
+        tenant_name: chosen.name,
+        tokens,
+    };
+    saveSupportSession(contextName, support);
+    return support;
+}
+/** Ends the running support session; the operator's own login is untouched. */
+export async function endSupportSession(contextName) {
+    const context = requireContext(contextName);
+    const support = getSupportSession(context);
+    if (!support)
+        return null;
+    if (support.tokens.refresh_token) {
+        // Keycloak may have ended it already; the local session goes either way.
+        await keycloakProvider.endSupportSession(context, support.tokens.refresh_token).catch(() => { });
+    }
+    clearSupportSession(contextName);
+    return support;
+}
+/** The operator's own `sub`, read from a token the realm signed. */
+function decodedSub(accessToken) {
+    const [, payload] = accessToken.split('.');
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    return claims.sub ?? '';
+}
 export async function testAuth(contextName) {
     const context = requireContext(contextName);
     const { api: apiUrl } = getBaseUrls(context.environment);
@@ -140,11 +231,19 @@ export function tenantLabel(tenant) {
 }
 export async function getCurrentTenant(contextName) {
     const context = requireContext(contextName);
-    // API-key contexts carry no JWT, so there is no tenant to decode locally.
+    // API-key contexts carry no JWT, so there is no tenant to read.
     if (getAuthType(context) === 'api_key' || !context.tokens?.access_token) {
         return null;
     }
-    const tenantId = tenantIdOf(decodeToken(context.tokens.access_token));
+    // The stored token is checked against the realm's keys before its tenant is
+    // believed; a token that fails verification reaches no tenant.
+    let tenantId;
+    try {
+        tenantId = tenantIdOf(await keycloakProvider.readClaims(context, context.tokens.access_token));
+    }
+    catch {
+        return null;
+    }
     if (!tenantId) {
         return null;
     }
@@ -205,7 +304,7 @@ export async function completeTenantSelection(contextName, choose) {
     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))) {
+    if (context.tenant_id || tenantIdOf(await keycloakProvider.readClaims(context, context.tokens.access_token))) {
         return null;
     }
     const tenants = await listTenants(contextName);

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

@@ -0,0 +1,19 @@
+import { type DecodedToken } from './tokens.js';
+/**
+ * Verifies a Keycloak-issued JWT against the realm's published signing keys and
+ * returns its claims.
+ *
+ * Claims are only trustworthy once the signature is checked: `jwt.decode` would
+ * return whatever a tampered token says. The algorithm is pinned to RS256 and
+ * the issuer is matched against the realm's discovery document, so a token from
+ * another realm — or one re-signed by the caller — is rejected
+ * (AderisERP/cli#25).
+ */
+export declare function verifyToken(token: string, { audience, ignoreExpiration, issuer, jwksUri, }: {
+    audience?: string;
+    ignoreExpiration?: boolean;
+    issuer: string;
+    jwksUri: string;
+}): Promise<DecodedToken>;
+/** Drops the cached key sets. Exposed for tests. */
+export declare function resetJwksCache(): void;

package/dist/lib/auth/jwks.js

@@ -0,0 +1,112 @@
+import jwt from 'jsonwebtoken';
+import { createPublicKey } from 'node:crypto';
+import { AuthError } from './errors.js';
+import { authHttp, toAuthError } from './http.js';
+/**
+ * The only signature algorithm the CLI accepts. Pinning it is what stops an
+ * `alg: none` or HMAC-with-the-public-key token from passing verification.
+ */
+const ALLOWED_ALGORITHMS = ['RS256'];
+/** Signing keys per JWKS URI, fetched once per process like the discovery document. */
+const keyCache = new Map();
+async function fetchKeys(jwksUri) {
+    let response;
+    try {
+        response = await authHttp.get(jwksUri, { headers: { Accept: 'application/json' } });
+    }
+    catch (error) {
+        throw new AuthError(`Could not load the Keycloak signing keys from ${jwksUri}: ${toAuthError(error, 'the request').message}`);
+    }
+    const keys = response.data?.keys;
+    if (!Array.isArray(keys) || keys.length === 0) {
+        throw new AuthError(`The Keycloak key set at ${jwksUri} lists no keys.`);
+    }
+    return keys;
+}
+function keysOf(jwksUri) {
+    const cached = keyCache.get(jwksUri);
+    if (cached)
+        return cached;
+    // A failed fetch must not be cached, or one network blip breaks the process.
+    const pending = fetchKeys(jwksUri).catch((error) => {
+        keyCache.delete(jwksUri);
+        throw error;
+    });
+    keyCache.set(jwksUri, pending);
+    return pending;
+}
+/** The `kid` a token was signed with, read from its header. */
+function keyIdOf(token) {
+    const [header] = token.split('.');
+    if (!header)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed.kid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function publicKeyFrom(jwk, jwksUri) {
+    try {
+        return createPublicKey({ format: 'jwk', key: jwk });
+    }
+    catch {
+        throw new AuthError(`A signing key in the Keycloak key set at ${jwksUri} could not be read.`);
+    }
+}
+/**
+ * Verifies a Keycloak-issued JWT against the realm's published signing keys and
+ * returns its claims.
+ *
+ * Claims are only trustworthy once the signature is checked: `jwt.decode` would
+ * return whatever a tampered token says. The algorithm is pinned to RS256 and
+ * the issuer is matched against the realm's discovery document, so a token from
+ * another realm — or one re-signed by the caller — is rejected
+ * (AderisERP/cli#25).
+ */
+export async function verifyToken(token, { audience, ignoreExpiration = false, issuer, jwksUri, }) {
+    const keys = await keysOf(jwksUri);
+    const kid = keyIdOf(token);
+    // A `kid` the key set does not list may mean the realm rotated its keys, so
+    // every signing key is tried before giving up.
+    const candidates = kid ? keys.filter((k) => k.kid === kid) : [];
+    const tried = candidates.length > 0 ? candidates : keys.filter((k) => k.use === undefined || k.use === 'sig');
+    let lastError;
+    for (const jwk of tried) {
+        try {
+            return jwt.verify(token, publicKeyFrom(jwk, jwksUri), {
+                algorithms: [...ALLOWED_ALGORITHMS],
+                ...(audience === undefined ? {} : { audience }),
+                ignoreExpiration,
+                issuer,
+            });
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    const detail = lastError instanceof Error ? lastError.message : 'no matching signing key';
+    // Read purely to name what was presented; these claims are not trusted.
+    const presented = unverifiedIssuerOf(token);
+    const named = presented && presented !== issuer ? ` The token names issuer ${presented}.` : '';
+    throw new AuthError(`Keycloak issued a token whose signature could not be verified against ${jwksUri}: ${detail}.${named}`);
+}
+/** The `iss` a token claims, for error messages only — never for a decision. */
+function unverifiedIssuerOf(token) {
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed.iss : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Drops the cached key sets. Exposed for tests. */
+export function resetJwksCache() {
+    keyCache.clear();
+}

package/dist/lib/auth/keycloak-provider.d.ts

@@ -1,4 +1,5 @@
 import { type Context, type Environment, type TokenData } from '../config.js';
+import { type DecodedToken } from './tokens.js';
 import { type AuthorizeParams, type AuthProvider, type AuthRound, type ExchangeParams, type Tenant } from './types.js';
 export interface KeycloakRealm {
     baseUrl: string;
@@ -15,7 +16,11 @@ export declare const KEYCLOAK_SCOPE = "openid profile email offline_access";
 /** The subset of the OIDC discovery document (RFC 8414 / OIDC Discovery 1.0) the CLI uses. */
 export interface OidcDiscovery {
     authorization_endpoint: string;
+    /** Ends one session without touching the operator's own login. */
+    end_session_endpoint: string;
     issuer: string;
+    /** Where the realm publishes the signing keys every issued token is checked against. */
+    jwks_uri: string;
     token_endpoint: string;
 }
 /** What decides which Keycloak a context talks to: its environment, and an optional host override. */
@@ -42,10 +47,37 @@ export declare class KeycloakProvider implements AuthProvider {
      * validated against the host allowlist; a failed fetch is not cached.
      */
     discover(target: KeycloakTarget): Promise<OidcDiscovery>;
+    /**
+     * Ends exactly the support session. The operator's own login is a different
+     * Keycloak session and is left running.
+     */
+    endSupportSession(context: Context, refreshToken: string): Promise<void>;
     exchangeCode(context: Context, { code, codeVerifier, nonce }: ExchangeParams): Promise<TokenData>;
-    /** No network call: the access token's `availableTenants` claim lists every tenant the user may act in. */
-    listTenants(_context: Context, accessToken: string): Promise<Tenant[]>;
+    /**
+     * Customers this operator may act for. Served by the realm's tenant-claims
+     * mapper against the operator's own Bearer, so Keycloak — not the CLI —
+     * decides who is an operator and which customers they may pick.
+     */
+    listSupportTenants(context: Context, operatorAccessToken: string): Promise<Tenant[]>;
+    /** The access token's `availableTenants` claim lists every tenant the user may act in, read once its signature checks out. */
+    listTenants(context: Context, accessToken: string): Promise<Tenant[]>;
+    /**
+     * The claims of an access token, once its signature has been checked against
+     * the realm's keys. Every caller that needs a claim goes through here: reading
+     * one off an unverified token would believe whatever the token says
+     * (AderisERP/cli#25).
+     */
+    readClaims(context: Context, accessToken: string): Promise<DecodedToken>;
     refresh(context: Context, refreshToken: string): Promise<TokenData>;
+    /** Refreshes a support session. No tenant is named: the session never moves customer. */
+    refreshSupportSession(context: Context, refreshToken: string): Promise<TokenData>;
+    /**
+     * Starts a support session for `tenantId`, authorised by the operator's own
+     * access token. The returned tokens belong to the shared support account and
+     * name the operator in `impersonatorId`; they are a second login, so the
+     * operator's own tokens stay valid and untouched.
+     */
+    startSupportSession(context: Context, operatorAccessToken: string, tenantId: string): Promise<TokenData>;
     /**
      * 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
@@ -60,14 +92,20 @@ export declare class KeycloakProvider implements AuthProvider {
      */
     tenantSwitchRounds(context: Context, tenantId: string): AuthRound[];
     private redeem;
-    /** Rejects a token whose `iss` differs from the discovery issuer; the API compares `iss` exactly. */
-    private requireIssuer;
     /**
-     * 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.
+     * A token may legitimately carry no `tenantId`: the mapper is fail-closed for
+     * a `tenant_id` the session cannot reach, and a service account reaching
+     * several tenants gets none. That token is stored and needs a tenant named
+     * (`completeTenantSelection`); a token reaching no tenant at all is refused.
      */
     private requireTenant;
+    /**
+     * Checks an access token's signature against the realm's published keys, and
+     * its issuer along with it. Every claim the CLI reads later — the tenant, the
+     * reachable tenants — is taken from the claims this returns, so no caller can
+     * read a claim that was not checked first (AderisERP/cli#25).
+     */
+    private verifyAccessToken;
     /** Consistency check only: the id_token signature is not checked (the API checks the access token). */
     private verifyNonce;
 }