@aderis-erp/cli 1.0.15 → 1.1.0

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,228 @@
+/**
+ * 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 { 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.');
+    }
+    // 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,
+        // 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 read.
+    if (getAuthType(context) === 'api_key' || !context.tokens?.access_token) {
+        return null;
+    }
+    // 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;
+    }
+    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(await keycloakProvider.readClaims(context, 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);
+}

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

@@ -0,0 +1,91 @@
+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;
+    realm: string;
+}
+/**
+ * Default Keycloak origin and realm per environment. A context may override
+ * the origin with `keycloak_base_url`; a token carries the issuer of the origin
+ * it was requested from, and the API compares `iss` exactly.
+ */
+export declare const KEYCLOAK_REALMS: Record<Environment, KeycloakRealm>;
+/** The tenant claims need no extra scope; the tenant is selected by the CLI via `tenant_id`, not on the login page. */
+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;
+    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. */
+export type KeycloakTarget = Pick<Context, 'environment' | 'keycloak_base_url'>;
+/**
+ * Validates a Keycloak base URL as stored in `keycloak_base_url`: https, an
+ * allowlisted host, and nothing but the origin. Returns the normalized origin.
+ */
+export declare function parseKeycloakBaseUrl(value: string): string;
+/** The Keycloak origin a context uses: its override, re-validated, or the environment's default. */
+export declare function keycloakBaseUrlOf(target: KeycloakTarget): string;
+export declare function discoveryUrlFor(target: KeycloakTarget): string;
+/**
+ * Authorization Code + PKCE S256 with `state` and `nonce` against the public
+ * `aderis-cli-login` client, endpoints from OIDC discovery. Tenants come from
+ * the access token; a switch is a refresh-token grant carrying `tenant_id=<uuid>`.
+ */
+export declare class KeycloakProvider implements AuthProvider {
+    /** Discovery documents per discovery URL, fetched once per provider instance. */
+    private readonly discoveryCache;
+    buildAuthorizeUrl(context: Context, params: AuthorizeParams): Promise<string>;
+    /**
+     * The realm's discovery document, cached per discovery URL. Its endpoints are
+     * validated against the host allowlist; a failed fetch is not cached.
+     */
+    discover(target: KeycloakTarget): Promise<OidcDiscovery>;
+    exchangeCode(context: Context, { code, codeVerifier, nonce }: ExchangeParams): Promise<TokenData>;
+    /** 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
+     * realm's tenant-claims mapper: the minted token's `tenantId` becomes this
+     * tenant. No browser and no SSO session involved.
+     */
+    switchTenant(context: Context, refreshToken: string, tenantId: string): Promise<TokenData>;
+    /**
+     * One login round whose tokens are re-scoped to `tenantId` through
+     * {@link switchTenant} right after the exchange. A second browser round
+     * could not be silent: exchanging the code for an offline token ends the
+     * realm's SSO session.
+     */
+    tenantSwitchRounds(context: Context, tenantId: string): AuthRound[];
+    private redeem;
+    /**
+     * 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;
+}
+/** The one identity provider the CLI authenticates against. */
+export declare const keycloakProvider: KeycloakProvider;