@aderis-erp/cli 1.0.14 → 1.0.17

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

@@ -0,0 +1,57 @@
+import { type Context, type TokenData } from '../config.js';
+export interface Tenant {
+    createdAt?: string;
+    isDefault?: boolean;
+    name: string;
+    tenantId: string;
+}
+/** Inputs to one authorization request. The flow generates them; the provider decides which to send. */
+export interface AuthorizeParams {
+    /** PKCE S256 challenge derived from this round's verifier. */
+    codeChallenge: string;
+    /** OIDC nonce; providers that support it echo it in the id_token. */
+    nonce: string;
+    prompt?: 'login' | 'none';
+    state: string;
+}
+export interface ExchangeParams {
+    code: string;
+    codeVerifier: string;
+    /** The nonce sent with the matching authorization request, for id_token verification. */
+    nonce: string;
+}
+/** One browser round of a login or tenant switch; the flow adds PKCE, state, nonce and the URL via the provider. */
+export interface AuthRound {
+    /**
+     * Runs after this round's tokens are exchanged and stored. Tokens it returns
+     * replace them as the round's result and are stored too; a throw aborts the flow.
+     */
+    afterExchange?: (tokens: TokenData) => Promise<TokenData | void>;
+    /** Forwarded to {@link AuthProvider.buildAuthorizeUrl} as `prompt`. */
+    prompt?: 'login' | 'none';
+}
+/**
+ * The seam between the login orchestration (`flow.ts`, `index.ts`) and Keycloak.
+ * The implementation owns endpoints, scopes and token semantics; it never starts
+ * servers or opens browsers.
+ */
+export interface AuthProvider {
+    /** The URL the browser is sent to. Async because Keycloak resolves endpoints via OIDC discovery. */
+    buildAuthorizeUrl(context: Context, params: AuthorizeParams): Promise<string>;
+    /** Redeem the authorization code. Must validate the id_token nonce when the provider issues one. */
+    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(context: Context, refreshToken: string): Promise<TokenData>;
+    /**
+     * Re-scopes a live session to `tenantId` with one token request and no
+     * browser. A rejected refresh must surface as the "Session expired" error.
+     */
+    switchTenant(context: Context, refreshToken: string, tenantId: string): Promise<TokenData>;
+    /**
+     * The browser rounds that end with a token for `tenantId` when no live
+     * session exists; the flow appends the tenant assertion.
+     */
+    tenantSwitchRounds(context: Context, tenantId: string): AuthRound[];
+}

package/dist/lib/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/auth/validated-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates `baseUrl` against the host allowlist and optionally appends `path`.
+ * Throws `Error('Invalid URL')` for anything off-list, non-http(s), or
+ * containing path traversal.
+ */
+export declare function buildValidatedUrl(baseUrl: string, path?: string): string;

package/dist/lib/auth/validated-url.js

@@ -0,0 +1,53 @@
+import { URL } from 'node:url';
+/**
+ * Hosts the CLI may talk to. Every outbound URL the auth layer builds — API,
+ * Keycloak discovery and the endpoints discovery returns — goes through
+ * {@link buildValidatedUrl}, so a tampered config file or discovery document
+ * cannot redirect tokens elsewhere.
+ */
+const ALLOWED_HOSTS = new Set([
+    'aderis-erp-nonprod.cloud-iam.com',
+    'aderis-erp-prod.cloud-iam.com',
+    'api-dev.aderis.com',
+    'api-staging.aderis.com',
+    'api-test.aderis.com',
+    'api.aderis.com',
+    'iam-dev.aderis.com',
+    'iam-staging.aderis.com',
+    'iam-test.aderis.com',
+    'iam.aderis.com',
+    'localhost',
+]);
+function hasTraversal(segment) {
+    return segment.includes('/../') || /\/%2e%2e\//i.test(segment);
+}
+/**
+ * Validates `baseUrl` against the host allowlist and optionally appends `path`.
+ * Throws `Error('Invalid URL')` for anything off-list, non-http(s), or
+ * containing path traversal.
+ */
+export function buildValidatedUrl(baseUrl, path) {
+    try {
+        if (hasTraversal(baseUrl)) {
+            throw new Error('Invalid path');
+        }
+        const url = new URL(baseUrl);
+        if (!ALLOWED_HOSTS.has(url.hostname)) {
+            throw new Error(`Invalid host: ${url.hostname}`);
+        }
+        if (!['http:', 'https:'].includes(url.protocol)) {
+            throw new Error('Invalid protocol');
+        }
+        if (path) {
+            if (hasTraversal(path)) {
+                throw new Error('Invalid path');
+            }
+            const cleanPath = path.startsWith('/') ? path : '/' + path;
+            url.pathname = url.pathname.replace(/\/$/, '') + cleanPath;
+        }
+        return url.href;
+    }
+    catch {
+        throw new Error('Invalid URL');
+    }
+}

package/dist/lib/base-api-command.js

@@ -1,11 +1,13 @@
 import { Command, Flags } from '@oclif/core';
 import { ApiError, apiRequest } from './api-client.js';
-import { getCurrentContext } from './config.js';
+import { getCurrentContext, hasCredentials, missingCredentialsMessage } from './config.js';
 export class BaseApiCommand extends Command {
     static globalFlags = {
         context: Flags.string({
+            aliases: ['config'],
             char: 'c',
-            description: 'Context to use (defaults to current context)',
+            description: 'Context to use, overriding the current context (alias: --config)',
+            env: 'ADERIS_CONTEXT',
         }),
         output: Flags.string({
             char: 'o',
@@ -66,8 +68,8 @@ export class BaseApiCommand extends Command {
         if (!context) {
             this.error('No context configured. Run: aderis auth login --new');
         }
-        if (!context.tokens) {
-            this.error(`Not logged in to context "${context.name}". Run: aderis auth login`);
+        if (!hasCredentials(context)) {
+            this.error(missingCredentialsMessage(context));
         }
     }
     printTable(data) {

package/dist/lib/config.d.ts

@@ -1,11 +1,21 @@
 import Conf from 'conf';
-export type Environment = 'dev' | 'live' | 'staging';
+export type Environment = 'dev' | 'live' | 'staging' | 'test';
+/**
+ * How a context authenticates against the API.
+ *
+ * - `oauth2`: browser PKCE login, sends `Authorization: Bearer <access_token>`
+ * - `api_key`: a long-lived key, sends `x-api-key: <key>`
+ *
+ * Contexts created before API-key support have no `auth_type` field; they are
+ * treated as `oauth2`, so always read it through {@link getAuthType}.
+ */
+export type AuthType = 'api_key' | 'oauth2';
 export interface BaseUrls {
     api: string;
-    auth: string;
 }
 export declare const BASE_URLS: Record<Environment, BaseUrls>;
-export declare const DEFAULT_CLIENT_IDS: Record<Environment, string>;
+/** The Keycloak CLI client: one public client (PKCE S256, loopback redirect) in every realm. */
+export declare const DEFAULT_KEYCLOAK_CLIENT_ID = "aderis-cli-login";
 export interface TokenData {
     access_token: string;
     expires_at?: number;
@@ -17,10 +27,19 @@ export interface CachedTenant {
     tenantId: string;
 }
 export interface Context {
+    api_key?: string;
+    auth_type?: AuthType;
     cachedTenants?: CachedTenant[];
-    client_id: string;
+    /** Only required for `oauth2` contexts; API-key contexts have no OAuth client. */
+    client_id?: string;
     client_secret?: string;
     environment: Environment;
+    /**
+     * Keycloak origin to use instead of the environment's default host
+     * (`keycloak` contexts only; https, allowlisted, origin without a path). The
+     * realm is still the environment's.
+     */
+    keycloak_base_url?: string;
     name: string;
     tenant_id?: string;
     tokens?: TokenData;
@@ -44,5 +63,26 @@ 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 saveApiKey(contextName: string, apiKey: string): void;
+export declare function clearApiKey(contextName: string): void;
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export declare function getAuthType(context: Context): AuthType;
+/** Whether a context holds the credential its auth type needs to call the API. */
+export declare function hasCredentials(context: Context): boolean;
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export declare function missingCredentialsMessage(context: Context): string;
+/** Error message for an expired OAuth session; `aderis switch` matches on it to offer a re-login. */
+export declare const SESSION_EXPIRED_MESSAGE = "Session expired. Please run: aderis auth login";
+/** The error for a 401 on a context that holds a credential. */
+export declare function unauthorizedMessage(context: Context): string;
+/** Redact a key for display: first and last 4 characters only. */
+export declare function maskApiKey(apiKey: string): string;
 export declare function getBaseUrls(environment: Environment): BaseUrls;
 export { config };

package/dist/lib/config.js

@@ -3,26 +3,21 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 export const BASE_URLS = {
-    dev: {
-        api: 'https://api-dev.aderis.com',
-        auth: 'https://auth-dev.aderis.com',
-    },
-    live: {
-        api: 'https://api.aderis.com',
-        auth: 'https://auth.aderis.com',
-    },
-    staging: {
-        api: 'https://api-staging.aderis.com',
-        auth: 'https://auth-staging.aderis.com',
-    },
-};
-// Default OAuth client IDs per environment (public clients, no secret required)
-export const DEFAULT_CLIENT_IDS = {
-    dev: '74fd96f8-cf4b-49d8-b713-2a121ea22910',
-    live: '970d9568-84c9-4613-b966-30d7e1d93828',
-    staging: 'bf0e5dd6-419f-4d64-8951-2c385533651f',
+    dev: { api: 'https://api-dev.aderis.com' },
+    live: { api: 'https://api.aderis.com' },
+    staging: { api: 'https://api-staging.aderis.com' },
+    test: { api: 'https://api-test.aderis.com' },
 };
-const CONFIG_DIR = path.join(os.homedir(), '.aderis');
+/** The Keycloak CLI client: one public client (PKCE S256, loopback redirect) in every realm. */
+export const DEFAULT_KEYCLOAK_CLIENT_ID = 'aderis-cli-login';
+/**
+ * Directory of `config.json`: `ADERIS_CONFIG_DIR`, resolved to an absolute path
+ * so a relative value does not depend on each command's working directory, or
+ * `~/.aderis`.
+ */
+const CONFIG_DIR = process.env.ADERIS_CONFIG_DIR
+    ? path.resolve(process.env.ADERIS_CONFIG_DIR)
+    : path.join(os.homedir(), '.aderis');
 // Ensure config directory exists
 if (!fs.existsSync(CONFIG_DIR)) {
     fs.mkdirSync(CONFIG_DIR, { mode: 0o700, recursive: true });
@@ -133,6 +128,47 @@ export function getTokens(contextName) {
 export function clearTokens(contextName) {
     updateContext(contextName, { tokens: undefined });
 }
+export function saveApiKey(contextName, apiKey) {
+    updateContext(contextName, { api_key: apiKey, auth_type: 'api_key' });
+}
+export function clearApiKey(contextName) {
+    updateContext(contextName, { api_key: undefined });
+}
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export function getAuthType(context) {
+    return context.auth_type ?? 'oauth2';
+}
+/** Whether a context holds the credential its auth type needs to call the API. */
+export function hasCredentials(context) {
+    return getAuthType(context) === 'api_key' ? Boolean(context.api_key) : Boolean(context.tokens);
+}
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export function missingCredentialsMessage(context) {
+    return getAuthType(context) === 'api_key'
+        ? `No API key set for context "${context.name}". Run: aderis config set-api-key --context ${context.name}`
+        : `Not logged in to context "${context.name}". Run: aderis auth login --context ${context.name}`;
+}
+/** Error message for an expired OAuth session; `aderis switch` matches on it to offer a re-login. */
+export const SESSION_EXPIRED_MESSAGE = 'Session expired. Please run: aderis auth login';
+/** The error for a 401 on a context that holds a credential. */
+export function unauthorizedMessage(context) {
+    if (getAuthType(context) === 'api_key') {
+        return `API key for context "${context.name}" was rejected. Check the key with: aderis config set-api-key --context ${context.name}`;
+    }
+    // TODO(infrastructure-stacks#152): return SESSION_EXPIRED_MESSAGE once the API accepts iam-* issuers.
+    return 'Session rejected by the API (issuer or audience mismatch) — see https://github.com/AderisERP/infrastructure-stacks/issues/152, or run: aderis auth login';
+}
+/** Redact a key for display: first and last 4 characters only. */
+export function maskApiKey(apiKey) {
+    return apiKey.length <= 8 ? '*'.repeat(apiKey.length) : `${apiKey.slice(0, 4)}${'*'.repeat(8)}${apiKey.slice(-4)}`;
+}
 export function getBaseUrls(environment) {
     return BASE_URLS[environment];
 }