@aderis-erp/cli 1.0.17 → 1.1.1

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

@@ -1,9 +1,10 @@
 import { URL } from 'node:url';
-import { REDIRECT_URI } from './constants.js';
+import { FORM_POST_HEADERS, REDIRECT_URI, SUPPORT_CLIENT_ID, SUPPORT_SESSION_GRANT_TYPE } 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 { authHttp, httpStatusOf, toAuthError } from './http.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
@@ -83,13 +84,25 @@ function validateDiscovery(url, data) {
             throw new AuthError(`Keycloak discovery document at ${url} advertises a ${field} outside the allowed hosts: ${value}`);
         }
     };
-    // `end_session_endpoint` is unused: logout is local-only.
     return {
         authorization_endpoint: requireEndpoint('authorization_endpoint'),
+        end_session_endpoint: requireEndpoint('end_session_endpoint'),
         issuer: requireString('issuer'),
+        jwks_uri: requireEndpoint('jwks_uri'),
         token_endpoint: requireEndpoint('token_endpoint'),
     };
 }
+/** `{id, name}` entries from the realm's support-tenant list; an entry without a usable id is dropped. */
+function parseSupportTenants(body) {
+    if (!Array.isArray(body))
+        return [];
+    return body.flatMap((entry) => {
+        const { id, name } = (entry ?? {});
+        if (typeof id !== 'string' || !id)
+            return [];
+        return [{ name: typeof name === 'string' && name ? name : id, tenantId: id }];
+    });
+}
 /**
  * Authorization Code + PKCE S256 with `state` and `nonce` against the public
  * `aderis-cli-login` client, endpoints from OIDC discovery. Tenants come from
@@ -129,15 +142,55 @@ export class KeycloakProvider {
         this.discoveryCache.set(key, pending);
         return pending;
     }
+    /**
+     * Ends exactly the support session. The operator's own login is a different
+     * Keycloak session and is left running.
+     */
+    async endSupportSession(context, refreshToken) {
+        const discovery = await this.discover(context);
+        const params = new URLSearchParams({ client_id: SUPPORT_CLIENT_ID, refresh_token: refreshToken });
+        try {
+            await authHttp.post(discovery.end_session_endpoint, params.toString(), { headers: FORM_POST_HEADERS });
+        }
+        catch (error) {
+            // A session Keycloak has already forgotten is the state we wanted.
+            const status = httpStatusOf(error);
+            if (status !== 400 && status !== 401 && status !== 404)
+                throw toAuthError(error, 'Support session logout');
+        }
+    }
     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);
+    }
+    /**
+     * 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.
+     */
+    async listSupportTenants(context, operatorAccessToken) {
+        const discovery = await this.discover(context);
+        const url = buildValidatedUrl(new URL(discovery.issuer).origin, `${new URL(discovery.issuer).pathname}/aderis-tenant-claims/me/support/tenants`);
+        let response;
+        try {
+            response = await authHttp.get(url, {
+                headers: { Accept: 'application/json', Authorization: `Bearer ${operatorAccessToken}` },
+            });
+        }
+        catch (error) {
+            if (httpStatusOf(error) === 403) {
+                throw new AuthError('Your account is not an Aderis Support operator, so it cannot act for a customer.');
+            }
+            throw toAuthError(error, 'Support tenant list');
+        }
+        return parseSupportTenants(response.data);
     }
-    /** 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,9 +198,81 @@ 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);
     }
+    /** Refreshes a support session. No tenant is named: the session never moves customer. */
+    async refreshSupportSession(context, refreshToken) {
+        const discovery = await this.discover(context);
+        const params = new URLSearchParams({
+            client_id: SUPPORT_CLIENT_ID,
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+        });
+        let response;
+        try {
+            response = await authHttp.post(discovery.token_endpoint, params.toString(), {
+                headers: FORM_POST_HEADERS,
+            });
+        }
+        catch (error) {
+            const status = httpStatusOf(error);
+            if (status === 400 || status === 401) {
+                throw new AuthError('The support session has ended. Start a new one with: aderis support start <tenant-id>', {
+                    status,
+                });
+            }
+            throw toAuthError(error, 'Support session refresh');
+        }
+        const claims = await this.verifyAccessToken(discovery, response.data.access_token);
+        return toTokenData(response.data, claims);
+    }
+    /**
+     * 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.
+     */
+    async startSupportSession(context, operatorAccessToken, tenantId) {
+        const discovery = await this.discover(context);
+        const params = new URLSearchParams({
+            client_id: SUPPORT_CLIENT_ID,
+            grant_type: SUPPORT_SESSION_GRANT_TYPE,
+            tenant_id: tenantId,
+        });
+        let response;
+        try {
+            response = await authHttp.post(discovery.token_endpoint, params.toString(), {
+                headers: { ...FORM_POST_HEADERS, Authorization: `Bearer ${operatorAccessToken}` },
+            });
+        }
+        catch (error) {
+            const status = httpStatusOf(error);
+            if (status === 400 || status === 401 || status === 403) {
+                throw new AuthError(`Keycloak refused a support session for tenant ${tenantId}. Check that your account is a support operator and that the customer is one you may act for.`, { status });
+            }
+            throw toAuthError(error, 'Support session');
+        }
+        const claims = await this.verifyAccessToken(discovery, response.data.access_token);
+        return toTokenData(response.data, claims);
+    }
     /**
      * 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
@@ -176,37 +301,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

package/dist/lib/config.d.ts

@@ -26,6 +26,18 @@ export interface CachedTenant {
     name: string;
     tenantId: string;
 }
+/**
+ * A running "act as Aderis Support" session, held beside the operator's own
+ * login rather than replacing it: ending it returns to the operator without a
+ * new browser login, exactly as the web app does.
+ */
+export interface SupportSession {
+    /** The operator's Keycloak `sub`; a session started by someone else is not reused. */
+    operator_sub: string;
+    tenant_id: string;
+    tenant_name: string;
+    tokens: TokenData;
+}
 export interface Context {
     api_key?: string;
     auth_type?: AuthType;
@@ -41,6 +53,8 @@ export interface Context {
      */
     keycloak_base_url?: string;
     name: string;
+    /** Set while acting as Aderis Support; the operator's own tokens stay in `tokens`. */
+    support?: SupportSession;
     tenant_id?: string;
     tokens?: TokenData;
 }
@@ -63,6 +77,10 @@ export declare function saveCachedTenants(contextName: string, tenants: CachedTe
 export declare function getCachedTenants(contextName: string): CachedTenant[] | undefined;
 export declare function getTokens(contextName: string): null | TokenData;
 export declare function clearTokens(contextName: string): void;
+export declare function saveSupportSession(contextName: string, support: SupportSession): void;
+export declare function clearSupportSession(contextName: string): void;
+/** The running support session of a context, if any. */
+export declare function getSupportSession(context: Context): SupportSession | undefined;
 export declare function saveApiKey(contextName: string, apiKey: string): void;
 export declare function clearApiKey(contextName: string): void;
 /**

package/dist/lib/config.js

@@ -128,6 +128,16 @@ export function getTokens(contextName) {
 export function clearTokens(contextName) {
     updateContext(contextName, { tokens: undefined });
 }
+export function saveSupportSession(contextName, support) {
+    updateContext(contextName, { support });
+}
+export function clearSupportSession(contextName) {
+    updateContext(contextName, { support: undefined });
+}
+/** The running support session of a context, if any. */
+export function getSupportSession(context) {
+    return context.support;
+}
 export function saveApiKey(contextName, apiKey) {
     updateContext(contextName, { api_key: apiKey, auth_type: 'api_key' });
 }