@aderis-erp/cli 1.0.17 → 1.1.0

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/index.js

@@ -9,7 +9,7 @@ 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';
@@ -62,6 +62,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,
@@ -140,11 +143,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 +216,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;
@@ -16,6 +17,8 @@ export declare const KEYCLOAK_SCOPE = "openid profile email offline_access";
 export interface OidcDiscovery {
     authorization_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. */
@@ -43,8 +46,15 @@ export declare class KeycloakProvider implements AuthProvider {
      */
     discover(target: KeycloakTarget): Promise<OidcDiscovery>;
     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[]>;
+    /** 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>;
     /**
      * One refresh-token grant with the `tenant_id` form field, read by the
@@ -60,14 +70,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;
 }

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

@@ -3,7 +3,8 @@ 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 { verifyToken } from './jwks.js';
+import { 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
@@ -87,6 +88,7 @@ function validateDiscovery(url, data) {
     return {
         authorization_endpoint: requireEndpoint('authorization_endpoint'),
         issuer: requireString('issuer'),
+        jwks_uri: requireEndpoint('jwks_uri'),
         token_endpoint: requireEndpoint('token_endpoint'),
     };
 }
@@ -132,12 +134,13 @@ export class KeycloakProvider {
     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)));
+        await this.verifyNonce(context, discovery, response, nonce);
+        const claims = await this.verifyAccessToken(discovery, response.access_token);
+        return this.requireTenant(toTokenData(response, claims), claims);
     }
-    /** 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);
+    /** The access token's `availableTenants` claim lists every tenant the user may act in, read once its signature checks out. */
+    async listTenants(context, accessToken) {
+        const decoded = await this.readClaims(context, accessToken);
         const current = tenantIdOf(decoded);
         const tenants = tenantsOf(decoded);
         if (tenants === undefined) {
@@ -145,6 +148,23 @@ export class KeycloakProvider {
         }
         return tenants.map(({ id, name }) => ({ isDefault: id === current, name, tenantId: id }));
     }
+    /**
+     * 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).
+     */
+    async readClaims(context, accessToken) {
+        const discovery = await this.discover(context);
+        // A stored token may well be past its five-minute expiry; that says nothing
+        // about who issued it. The signature and issuer still have to hold, and the
+        // API enforces expiry on its own.
+        return verifyToken(accessToken, {
+            ignoreExpiration: true,
+            issuer: discovery.issuer,
+            jwksUri: discovery.jwks_uri,
+        });
+    }
     refresh(context, refreshToken) {
         return this.redeem(context, refreshToken);
     }
@@ -176,37 +196,46 @@ export class KeycloakProvider {
     }
     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;
+        const response = await redeemRefreshToken(discovery.token_endpoint, context, refreshToken, { tenantId });
+        const claims = await this.verifyAccessToken(discovery, response.access_token);
+        return this.requireTenant(toTokenData(response, claims), claims);
     }
     /**
-     * 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.
      */
-    requireTenant(tokens) {
+    requireTenant(tokens, claims) {
         if (tokens.tenant_id)
             return tokens;
-        const tenants = tenantsOf(decodeToken(tokens.access_token));
+        const tenants = tenantsOf(claims);
         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.');
     }
+    /**
+     * 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).
+     */
+    verifyAccessToken(discovery, accessToken) {
+        return verifyToken(accessToken, { issuer: discovery.issuer, jwksUri: discovery.jwks_uri });
+    }
     /** Consistency check only: the id_token signature is not checked (the API checks the access token). */
-    verifyNonce(response, expectedNonce) {
+    async verifyNonce(context, discovery, 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) {
+        // Verified rather than decoded: a nonce read off an unverified token proves
+        // nothing, since anyone able to tamper with it can set the nonce too.
+        const claims = await verifyToken(response.id_token, {
+            audience: requireClientId(context),
+            issuer: discovery.issuer,
+            jwksUri: discovery.jwks_uri,
+        });
+        if (claims.nonce !== expectedNonce) {
             throw new AuthError('The id_token nonce does not match the login request. Aborting — please try again.');
         }
     }

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

@@ -19,9 +19,8 @@ export interface DecodedToken {
     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;
+export declare function tenantIdOf(decoded: DecodedToken | null | undefined): string | undefined;
 /** One entry of the `availableTenants` claim, as the realm's tenant-claims mapper writes it. */
 export interface TenantClaim {
     id: string;
@@ -32,7 +31,13 @@ export interface TenantClaim {
  */
 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;
+/**
+ * Builds the stored token record from a token response and the claims that were
+ * verified from its access token. The claims are passed in rather than decoded
+ * here: a tenant read off an unverified token is attacker-controlled
+ * (AderisERP/cli#25).
+ */
+export declare function toTokenData(response: TokenResponse, claims: DecodedToken): 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.

package/dist/lib/auth/tokens.js

@@ -1,14 +1,9 @@
-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;
@@ -45,12 +40,18 @@ export function tenantsOf(decoded) {
     return claim.map((entry, index) => parseTenantClaim(entry, index + 1));
 }
 /** Map a token endpoint response onto the stored {@link TokenData} shape. */
-export function toTokenData(response) {
+/**
+ * Builds the stored token record from a token response and the claims that were
+ * verified from its access token. The claims are passed in rather than decoded
+ * here: a tenant read off an unverified token is attacker-controlled
+ * (AderisERP/cli#25).
+ */
+export function toTokenData(response, claims) {
     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)),
+        tenant_id: tenantIdOf(claims),
     };
 }
 /**

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

@@ -42,7 +42,11 @@ export interface AuthProvider {
     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-token grant. The tenant of the new token is the realm's to decide;
+     * only an explicit {@link switchTenant} names one. 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