appmesh 1.3.1 → 1.3.3

package/src/appmesh_oauth.js

@@ -0,0 +1,367 @@
+// appmesh_oauth.js - App Mesh client with Keycloak OAuth2 authentication support.
+// Mirrors the Python SDK's AppMeshClientOAuth (client_http_oauth.py): tokens are obtained
+// directly from Keycloak and the access token is used as the Bearer token for daemon calls.
+import axios from "axios";
+import AppMeshClient, { AppMeshError } from "./appmesh.js";
+
+// OAuth2 scopes requesting identity claims so userinfo returns preferred_username/email
+const DEFAULT_OAUTH_SCOPE = "openid profile email";
+
+/**
+ * AppMeshClient with Keycloak as the identity provider.
+ *
+ * Authentication (login, token renewal, logout, userinfo) is performed directly against
+ * Keycloak's OpenID Connect endpoints; the Keycloak access token is then used as this
+ * client's token for App Mesh daemon API calls (RBAC is enforced by the daemon).
+ */
+class AppMeshClientOAuth extends AppMeshClient {
+  /**
+   * Initialize an App Mesh client with Keycloak support.
+   * @param {Object} oauth2 - Keycloak configuration for oauth2 authentication:
+   *   - authServerUrl: Keycloak server URL (e.g. "https://keycloak.example.com/auth")
+   *   - realm: Keycloak realm
+   *   - clientId: Keycloak client ID
+   *   - clientSecret: Keycloak client secret (optional, confidential clients only)
+   * @param {string} [baseURL] - App Mesh daemon URL (see AppMeshClient)
+   * @param {Object|false|null} [sslConfig] - SSL tri-state for the daemon connection (see AppMeshClient)
+   */
+  constructor(oauth2, baseURL = undefined, sslConfig = null) {
+    super(baseURL, sslConfig);
+
+    if (!oauth2 || !oauth2.authServerUrl || !oauth2.realm || !oauth2.clientId) {
+      throw new AppMeshError(
+        "oauth2 config requires authServerUrl, realm and clientId",
+        400,
+        null,
+        "INVALID_OAUTH_CONFIG",
+      );
+    }
+
+    /** @type {Object} Keycloak configuration @private */
+    this._oauth2 = {
+      authServerUrl: String(oauth2.authServerUrl).replace(/\/+$/, ""),
+      realm: oauth2.realm,
+      clientId: oauth2.clientId,
+      clientSecret: oauth2.clientSecret || null,
+    };
+
+    /** @type {Object} Complete Keycloak token response (access_token, refresh_token, ...) @private */
+    this._oauthToken = {};
+
+    // Dedicated axios instance for Keycloak endpoints (the inherited this._client
+    // targets the App Mesh daemon and injects daemon-specific headers/cookies)
+    /** @private */
+    this._oauthClient = axios.create({
+      timeout: 60000,
+      validateStatus: () => true,
+    });
+  }
+
+  /**
+   * Build a Keycloak OpenID Connect endpoint URL for the configured realm.
+   * @param {string} name - Endpoint name (e.g. "token", "auth/device", "logout", "userinfo")
+   * @returns {string} Full endpoint URL
+   * @private
+   */
+  _oauthEndpoint(name) {
+    return `${this._oauth2.authServerUrl}/realms/${encodeURIComponent(this._oauth2.realm)}/protocol/openid-connect/${name}`;
+  }
+
+  /**
+   * POST x-www-form-urlencoded params to a Keycloak endpoint, adding client credentials.
+   * @param {string} endpoint - Endpoint name for _oauthEndpoint()
+   * @param {Object} params - Form fields (null/undefined values are skipped)
+   * @returns {Promise<any>} Raw axios response (any status)
+   * @private
+   */
+  async _oauthPost(endpoint, params) {
+    const form = new URLSearchParams();
+    form.append("client_id", this._oauth2.clientId);
+    if (this._oauth2.clientSecret)
+      form.append("client_secret", this._oauth2.clientSecret);
+    for (const [key, value] of Object.entries(params)) {
+      // Values are appended as-is (strings): TOTP codes keep leading zeros
+      if (value !== null && value !== undefined)
+        form.append(key, String(value));
+    }
+    return this._oauthClient.post(this._oauthEndpoint(endpoint), form);
+  }
+
+  /**
+   * Extract the OAuth2 "error" code from a Keycloak error response body.
+   * @param {any} data - Response body
+   * @returns {string} OAuth2 error code or ""
+   * @private
+   */
+  static _oauthErrorCode(data) {
+    if (typeof data === "string") {
+      try {
+        data = JSON.parse(data);
+      } catch (_) {
+        return "";
+      }
+    }
+    return data && typeof data === "object" && typeof data.error === "string"
+      ? data.error
+      : "";
+  }
+
+  /**
+   * Store a full Keycloak token response and propagate the access token to the base client.
+   * @param {Object} tokenResponse - Complete Keycloak token endpoint response
+   * @private
+   */
+  _storeOauthToken(tokenResponse) {
+    this._oauthToken = tokenResponse || {};
+    this._handleTokenUpdate(this._oauthToken.access_token || null);
+  }
+
+  /**
+   * Login with username and password using the OAuth2 Direct Access Grant (Resource
+   * Owner Password Credentials) against Keycloak.
+   * @param {string} username - The name of the user
+   * @param {string} password - The password of the user
+   * @param {string} [totpCode] - TOTP code if enabled for the user. Passed verbatim as a
+   *   string: leading zeros matter (e.g. "012345")
+   * @param {string|number} [tokenExpire] - Ignored by the Keycloak login flow
+   * @param {string} [audience] - Ignored by the Keycloak login flow
+   * @returns {Promise<void>} Resolves when login succeeds
+   * @throws {AppMeshError} If authentication fails
+   */
+  async login(
+    username,
+    password,
+    totpCode = null,
+    tokenExpire = null,
+    audience = null,
+  ) {
+    if (tokenExpire || audience) {
+      console.warn(
+        "tokenExpire and audience are ignored by the Keycloak login flow",
+      );
+    }
+    if (!username || !password) {
+      throw new AppMeshError(
+        "Username and password are required",
+        400,
+        null,
+        "INVALID_CREDENTIALS",
+      );
+    }
+
+    const response = await this._oauthPost("token", {
+      grant_type: "password",
+      username,
+      password,
+      scope: DEFAULT_OAUTH_SCOPE,
+      // Pass TOTP as-is (string): a numeric conversion would strip leading zeros
+      totp: totpCode ? String(totpCode) : null,
+    });
+    if (response.status !== 200) {
+      throw new AppMeshError(
+        `Keycloak login failed: ${this._extractErrorMessage(response.data)}`,
+        response.status,
+        response.data,
+        "OAUTH_LOGIN_FAILED",
+      );
+    }
+    this._storeOauthToken(response.data);
+  }
+
+  /**
+   * Login via the OAuth 2.0 Device Authorization Grant (RFC 8628).
+   *
+   * For browserless/input-constrained environments: the user opens
+   * `verification_uri_complete` (or `verification_uri` + `user_code`) on another device,
+   * and this call polls the token endpoint until approval, denial, or expiry.
+   *
+   * Requires "OAuth 2.0 Device Authorization Grant" enabled on the Keycloak client.
+   *
+   * @param {Function} [onPrompt] - Callback receiving the device authorization response
+   *   (keys per RFC 8628 §3.2: `user_code`, `verification_uri`, `verification_uri_complete`,
+   *   `expires_in`, `interval`) to present the instructions to the user. Defaults to
+   *   printing them to the console.
+   * @param {string} [scope] - OAuth2 scopes to request
+   * @returns {Promise<void>} Resolves once the user approved the request
+   * @throws {AppMeshError} When the user denies the request, the device code expires,
+   *   or the token request fails for any other reason
+   */
+  async login_device_flow(onPrompt = null, scope = DEFAULT_OAUTH_SCOPE) {
+    const deviceResponse = await this._oauthPost("auth/device", { scope });
+    if (deviceResponse.status !== 200) {
+      throw new AppMeshError(
+        `Device authorization request failed: ${this._extractErrorMessage(deviceResponse.data)}`,
+        deviceResponse.status,
+        deviceResponse.data,
+        "OAUTH_DEVICE_FLOW_FAILED",
+      );
+    }
+    const device = deviceResponse.data;
+
+    if (onPrompt) {
+      onPrompt(device);
+    } else {
+      const uri = device.verification_uri_complete || device.verification_uri;
+      console.log(
+        `To sign in, open ${uri} and enter code: ${device.user_code}`,
+      );
+    }
+
+    // RFC 8628 §3.5: poll no faster than "interval", stop once the device code expires
+    let interval = parseInt(device.interval, 10) || 5;
+    const deadline =
+      Date.now() + (parseInt(device.expires_in, 10) || 600) * 1000;
+
+    for (;;) {
+      const remaining = (deadline - Date.now()) / 1000;
+      if (remaining <= 0) {
+        throw new AppMeshError(
+          "Device authorization expired before the user approved the request",
+          null,
+          null,
+          "OAUTH_DEVICE_FLOW_EXPIRED",
+        );
+      }
+      await this._sleep(Math.min(interval, remaining));
+
+      const response = await this._oauthPost("token", {
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: device.device_code,
+      });
+      if (response.status === 200) {
+        this._storeOauthToken(response.data);
+        return;
+      }
+      const error = AppMeshClientOAuth._oauthErrorCode(response.data);
+      if (error === "authorization_pending") {
+        continue;
+      }
+      if (error === "slow_down") {
+        interval += 5; // RFC 8628 §3.5: back off by 5 seconds
+        continue;
+      }
+      throw new AppMeshError(
+        `Device authorization failed: ${error || this._extractErrorMessage(response.data)}`,
+        response.status,
+        response.data,
+        "OAUTH_DEVICE_FLOW_FAILED",
+      );
+    }
+  }
+
+  /**
+   * Sleep helper used by the device-flow polling loop.
+   * @param {number} seconds - Duration in seconds
+   * @returns {Promise<void>}
+   * @protected
+   */
+  _sleep(seconds) {
+    return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+  }
+
+  /**
+   * Renew the current Keycloak token using the refresh token.
+   * Keycloak rotates the refresh token: the complete new token response is stored.
+   * @param {string|number} [tokenExpire] - Ignored by the Keycloak refresh flow
+   * @returns {Promise<void>}
+   * @throws {AppMeshError} If no refresh token is available or the renewal fails
+   */
+  async renew_token(tokenExpire = null) {
+    // eslint-disable-line no-unused-vars
+    const refreshToken = this._oauthToken && this._oauthToken.refresh_token;
+    if (!refreshToken) {
+      throw new AppMeshError(
+        "No Keycloak refresh token available to renew",
+        null,
+        null,
+        "OAUTH_NO_REFRESH_TOKEN",
+      );
+    }
+
+    const response = await this._oauthPost("token", {
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+    });
+    if (response.status !== 200) {
+      throw new AppMeshError(
+        `Keycloak token renewal failed: ${this._extractErrorMessage(response.data)}`,
+        response.status,
+        response.data,
+        "OAUTH_RENEW_FAILED",
+      );
+    }
+    // Keycloak rotates refresh tokens: replace the whole stored token response
+    this._storeOauthToken(response.data);
+  }
+
+  /**
+   * Log out of the current session from Keycloak and the App Mesh daemon.
+   * The daemon logoff (super.logout) runs BEFORE the local token is cleared so it can
+   * still authenticate; the Keycloak session is revoked via the refresh token.
+   * @returns {Promise<boolean>} true when the Keycloak session was revoked
+   */
+  async logout() {
+    let result = false;
+    const refreshToken = this._oauthToken && this._oauthToken.refresh_token;
+    if (refreshToken) {
+      try {
+        const response = await this._oauthPost("logout", {
+          refresh_token: refreshToken,
+        });
+        if (response.status >= 200 && response.status < 300) {
+          result = true;
+        } else {
+          console.warn(
+            `Failed to logout from Keycloak: ${this._extractErrorMessage(response.data)}`,
+          );
+        }
+      } catch (error) {
+        console.warn(`Failed to logout from Keycloak: ${error.message}`);
+      }
+    }
+
+    // Daemon-side logoff before clearing the local token (it still needs the token)
+    await super.logout();
+    this._oauthToken = {};
+
+    return result;
+  }
+
+  /**
+   * Get Keycloak OIDC userinfo for the current access token, directly from Keycloak.
+   * Unlike get_current_user() (inherited), which asks the App Mesh daemon
+   * /appmesh/user/self, this queries the Keycloak userinfo endpoint without the daemon.
+   * @returns {Promise<Object>} Keycloak userinfo (OIDC claims such as `sub`,
+   *   `preferred_username`, `email`)
+   * @throws {AppMeshError} If no access token is available or the request fails
+   */
+  async get_oauth_userinfo() {
+    const accessToken = this._oauthToken && this._oauthToken.access_token;
+    if (!accessToken) {
+      throw new AppMeshError(
+        "No Keycloak access token available",
+        null,
+        null,
+        "OAUTH_NO_ACCESS_TOKEN",
+      );
+    }
+    const response = await this._oauthClient.get(
+      this._oauthEndpoint("userinfo"),
+      {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      },
+    );
+    if (response.status !== 200) {
+      throw new AppMeshError(
+        `Keycloak userinfo request failed: ${this._extractErrorMessage(response.data)}`,
+        response.status,
+        response.data,
+        "OAUTH_USERINFO_FAILED",
+      );
+    }
+    return response.data;
+  }
+}
+
+export { AppMeshClientOAuth };
+export default AppMeshClientOAuth;

package/src/appmesh_tcp.js

@@ -31,14 +31,7 @@ const LOGOFF_PATH = '/appmesh/self/logoff'
 /**
  * TCP transport for secure TLS connections and framed App Mesh messages.
  *
- * `sslConfig` is a tri-state:
- * - `null`/`undefined` (default): verify the server certificate against the App Mesh default
- *   CA (/opt/appmesh/ssl/ca.pem) if installed, otherwise the system CAs.
- * - object: custom TLS material — `ca`/`cert`/`key` (Buffer or file path) with an optional
- *   `rejectUnauthorized` flag (defaults to `true`). An unreadable CA/cert/key path is a hard
- *   error (`fs.readFileSync` throws), never a silent fallback to no-verification.
- * - `false`: explicit insecure mode — server certificate verification is disabled.
- *   This is the only way to disable verification besides `rejectUnauthorized: false`.
+ * @param {Object|false|null} [sslConfig=null] - TLS config; same tri-state as AppMeshClient (null=default CA, object=custom ca/cert/key, false=insecure).
  */
 class TCPTransport {
   /**
@@ -250,13 +243,15 @@ class RequestMessage {
    * Serialize message to msgpack format
    */
   serialize () {
+    // Coerce header/query values to strings; the daemon expects map<string,string>.
+    const strMap = (o) => Object.fromEntries(Object.entries(o || {}).map(([k, v]) => [k, String(v)]))
     const data = {
       uuid: this.uuid,
       http_method: this.httpMethod,
       request_uri: this.requestUri,
       client_addr: this.clientAddr,
-      headers: this.headers,
-      query: this.query,
+      headers: strMap(this.headers),
+      query: strMap(this.query),
       body: this.body
     }
     return msgpack.encode(data)
@@ -331,16 +326,7 @@ class AppMeshClientTCP extends AppMeshClient {
    *   `new AppMeshClientTCP(sslConfig, {host, port})` — the address may be an explicit
    *   `{host, port}` object in either position.
    *
-   * `sslConfig` is a tri-state: `null`/`undefined` verifies the server certificate against the
-   * App Mesh default CA (/opt/appmesh/ssl/ca.pem) if installed, otherwise the system CAs; an
-   * object supplies custom TLS material (an unreadable ca/cert/key path is a hard error, never
-   * a silent no-verify fallback); `false` is the explicit insecure no-verification mode.
-   *
-   * @param {Object|false|null} [sslConfig=null] - SSL configuration (or `{host, port}` address)
-   * @param {Buffer|string} [sslConfig.ca] - CA certificate
-   * @param {Buffer|string} [sslConfig.cert] - Client certificate
-   * @param {Buffer|string} [sslConfig.key] - Client key
-   * @param {boolean} [sslConfig.rejectUnauthorized=true] - Whether to verify SSL
+   * @param {Object|false|null} [sslConfig=null] - TLS config; same tri-state as AppMeshClient (null=default CA, object=custom ca/cert/key, false=insecure).
    * @param {Array<string, number>|{host: string, port: number}} [tcpAddress=['127.0.0.1', 6059]] - TCP server address
    */
   constructor (sslConfig = null, tcpAddress = ['127.0.0.1', 6059]) {
@@ -594,12 +580,13 @@ class AppMeshClientTCP extends AppMeshClient {
    * Download a file through the TCP file-socket side channel.
    *
    * @param {string} filePath - Remote file path
-   * @param {string} localFile - Local destination path
+   * @param {string} [localFile=null] - Local destination path; defaults to the basename of filePath
    * @param {boolean} [applyAttrs=true] - Apply returned mode and best-effort owner/group metadata
    * on non-Windows Node.js hosts
    * @override
    */
-  async download_file (filePath, localFile, applyAttrs = true) {
+  async download_file (filePath, localFile = null, applyAttrs = true) {
+    if (!localFile) localFile = filePath.split(/[\\/]/).pop()
     const headers = {
       [HTTP_HEADER_KEY_X_FILE_PATH]: encodeURIComponent(filePath),
       [HTTP_HEADER_KEY_X_RECV_FILE_SOCKET]: 'true'
@@ -631,7 +618,12 @@ class AppMeshClientTCP extends AppMeshClient {
         writeStream.write(chunk)
       }
     } finally {
-      writeStream.end()
+      // Await the flush so the file is complete on disk before this resolves.
+      await new Promise((resolve, reject) => {
+        writeStream.once('finish', resolve)
+        writeStream.once('error', reject)
+        writeStream.end()
+      })
     }
 
     // Apply file attributes on Unix systems
@@ -660,12 +652,13 @@ class AppMeshClientTCP extends AppMeshClient {
    * Upload a file through the TCP file-socket side channel.
    *
    * @param {string} localFile - Local file path
-   * @param {string} filePath - Remote destination path
+   * @param {string} [filePath=null] - Remote destination path; defaults to the basename of localFile
    * @param {boolean} [applyAttrs=true] - Send local mode/uid/gid metadata so the server can
    * recreate permissions and ownership when supported
    * @override
    */
-  async upload_file (localFile, filePath, applyAttrs = true) {
+  async upload_file (localFile, filePath = null, applyAttrs = true) {
+    if (!filePath) filePath = localFile.split(/[\\/]/).pop()
     if (!fs.existsSync(localFile)) {
       throw new Error(`Local file not found: ${localFile}`)
     }
@@ -791,22 +784,13 @@ class AppMeshClientTCP extends AppMeshClient {
   }
 
   /**
-   * Subscribe-based wait for async run (TCP override).
-   *
-   * Instead of polling get_app_output in a loop, subscribes to STDOUT/EXIT/REMOVED
-   * events and does a one-shot backfill to cover output emitted before the subscribe
-   * took effect.  Deduplicates by byte-position offset.
-   *
-   * No sentinel exit codes (real exit codes may be negative for signal kills):
-   * non-EXIT terminations throw typed errors; null means caller-side timeout only.
-   *
+   * Wait for an async run to finish over TCP, streaming incremental output.
    * @param {AppRun} run - AppRun object
    * @param {Function} [stdoutHandler] - Stdout handler callback(data, position)
    * @param {number} [timeout=0] - Max wait time in seconds (0 = unlimited)
    * @returns {Promise<number|null>} Exit code, or null on timeout
    * @throws {AppRemovedError} If the app was removed before its exit was observed.
-   * @throws {TransportDisconnectedError} If the demuxer disconnected while waiting,
-   *   or the daemon delivered an unparseable exit code.
+   * @throws {TransportDisconnectedError} If the transport disconnected while waiting, or the daemon delivered an unparseable exit code.
    */
   async wait_for_async_run (run, stdoutHandler, timeout = 0) {
     if (!run || !run.appName) return null

package/src/{server.js → worker.js}

@@ -1,4 +1,4 @@
-// server.js - App Mesh Worker SDK for Node.js
+// worker.js - App Mesh Worker SDK for Node.js
 // This is a Node.js-only module - not included in browser builds
 
 // Environment check - only works in Node.js
@@ -57,7 +57,7 @@ const _DEFER_CLIENT = Symbol('appmesh.deferClient')
  *
  * @example
  * // HTTP Worker Example
- * import { AppMeshWorker } from 'appmesh/server';
+ * import { AppMeshWorker } from 'appmesh/worker';
  *
  * const worker = new AppMeshWorker();
  * const payload = await worker.fetch_task();
@@ -66,7 +66,7 @@ const _DEFER_CLIENT = Symbol('appmesh.deferClient')
  *
  * @example
  * // TCP Worker Example
- * import { AppMeshWorkerTCP } from 'appmesh/server';
+ * import { AppMeshWorkerTCP } from 'appmesh/worker';
  *
  * const worker = new AppMeshWorkerTCP();
  * try {
@@ -176,11 +176,6 @@ class AppMeshWorker {
    * @throws {ProcessSupersededError} The daemon reported HTTP 412 — this process key was
    *   superseded by a newer process instance; the caller should stop serving (an app
    *   entry point typically catches this and exits).
-   *
-   * @example
-   * const worker = new AppMeshWorker();
-   * const payload = await worker.fetch_task();
-   * console.log('Received payload:', payload);
    */
   async fetch_task () {
     const { processKey, appName } = this._getRuntimeEnv()
@@ -244,11 +239,6 @@ class AppMeshWorker {
    * @param {string|Buffer} result - Result payload to be delivered back to the client as-is
    * @returns {Promise<void>}
    * @throws {Error} If the task return fails
-   *
-   * @example
-   * const worker = new AppMeshWorker();
-   * const result = { status: 'success', data: processedData };
-   * await worker.send_task_result(JSON.stringify(result));
    */
   async send_task_result (result) {
     const { processKey, appName } = this._getRuntimeEnv()
@@ -292,7 +282,7 @@ class AppMeshWorker {
  * @extends AppMeshWorker
  *
  * @example
- * import { AppMeshWorkerTCP } from 'appmesh/server';
+ * import { AppMeshWorkerTCP } from 'appmesh/worker';
  *
  * const worker = new AppMeshWorkerTCP();
  * try {
@@ -319,12 +309,7 @@ class AppMeshWorkerTCP extends AppMeshWorker {
    * @param {Array<string, number>|{host: string, port: number}} [tcpAddress=['127.0.0.1', 6059]] - TCP server address
    * @param {Object} [options={}] - Additional options
    * @param {Object} [options.logger=console] - Logger instance
-   * @param {AppMeshClientTCP} [options.client] - Optional pre-built `AppMeshClientTCP` instance to reuse.
-   *   When supplied, `sslConfig` and `tcpAddress` are ignored and the worker shares the caller's
-   *   client (and therefore its token-refresh state). Use this when a single process needs both
-   *   client and worker roles to avoid two independent `/token/renew` loops fighting each other —
-   *   the daemon blacklists the previous token on every renew, so the slower refresher gets
-   *   401 "Token has been revoked".
+   * @param {AppMeshClientTCP} [options.client] - Pre-built client to reuse (shares token-refresh state); see AppMeshWorker for why. When set, sslConfig/tcpAddress are ignored.
    *
    * @example
    * import fs from 'fs';
@@ -392,14 +377,6 @@ class AppMeshWorkerTCP extends AppMeshWorker {
   /**
    * Close the TCP connection and release resources.
    * Should be called when done using the server.
-   *
-   * @example
-   * const worker = new AppMeshWorkerTCP();
-   * try {
-   *   // Use worker...
-   * } finally {
-   *   worker.close();
-   * }
    */
   close () {
     if (this._client && typeof this._client.close === 'function') {
@@ -417,7 +394,7 @@ class AppMeshWorkerTCP extends AppMeshWorker {
  * @returns {Promise<any>} Result from callback
  *
  * @example
- * import { withServer, AppMeshWorkerTCP } from 'appmesh/server';
+ * import { withServer, AppMeshWorkerTCP } from 'appmesh/worker';
  *
  * await withServer(
  *   () => new AppMeshWorkerTCP(),