@appliqation/automation-sdk 2.5.1 → 2.8.0

package/src/utils/PayloadBuilder.js

@@ -114,36 +114,19 @@ class PayloadBuilder {
   static normalizeStatus(status) {
     if (!status) return 'unknown';
 
+    // Playwright-only status map. Cypress/Jest/generic variants were
+    // removed alongside the Cypress and Jest reporters — D1/D2/D3.
     const statusMap = {
-      // Standard statuses
       'passed': 'passed',
       'failed': 'failed',
       'skipped': 'skipped',
       'pending': 'pending',
-
-      // Playwright variants
       'expected': 'passed',
       'unexpected': 'failed',
       'flaky': 'flaky',
       'timedOut': 'failed',
-      'interrupted': 'skipped',
-
-      // Cypress variants
-      'pass': 'passed',
-      'fail': 'failed',
-
-      // Jest variants
-      'success': 'passed',
-      'error': 'failed',
-      'disabled': 'skipped',
-
-      // Generic variants
-      'ok': 'passed',
-      'success': 'passed',
-      'failure': 'failed',
-      'error': 'failed',
-      'skip': 'skipped',
-      'todo': 'pending'
+      // Aborted run, not a skip — see AppliqationReporter.mapStatus.
+      'interrupted': 'failed'
     };
 
     const normalized = statusMap[status.toLowerCase()];
@@ -212,6 +195,114 @@ class PayloadBuilder {
     };
   }
 
+  /**
+   * S8 — Pre-submission payload validation for the automation result
+   * endpoint. Runs AFTER buildAutomationResultPayload has assembled the
+   * final wire payload, immediately before the HTTP POST. Enforces the
+   * exact shape the backend's InputValidator + AutomationResultManager
+   * accept, so shape drift (wrong field name, missing required field,
+   * bad type) is caught at the client instead of failing at the server
+   * with a generic 400 mid-run.
+   *
+   * Defence-in-depth on top of H2 (which validates user-supplied CONFIG
+   * at startup) — S8 validates the assembled OUTGOING payload.
+   *
+   * Backend constraints (mirror of appq_mongo InputValidator +
+   * AutomationApiController::submitResultBatch):
+   *   run_id            required, matches /^[a-zA-Z0-9_:-]+$/ max 100
+   *   test_case_uuid    required, matches UuidValidator's regex
+   *   status            required, one of {passed, failed, skipped}
+   *   source            'automation' when SDK-submitted (post C1)
+   *   browser           required, matches /^[a-zA-Z0-9 .\-_(),\/]+$/ max 255
+   *   environment       matches /^[a-zA-Z0-9._-]+$/ max 255
+   *   duration          integer >= 0 when present
+   *   timestamp         positive integer when present
+   *
+   * @param {Object} payload - Fully assembled result payload
+   * @returns {{ valid: boolean, errors: string[] }}
+   */
+  static validateAutomationResultPayload(payload) {
+    const errors = [];
+
+    if (!payload || typeof payload !== 'object') {
+      return { valid: false, errors: ['payload must be an object'] };
+    }
+
+    // run_id
+    if (typeof payload.run_id !== 'string' || payload.run_id.length === 0) {
+      errors.push('run_id must be a non-empty string');
+    } else if (payload.run_id.length > 100) {
+      errors.push(`run_id exceeds 100 chars (got ${payload.run_id.length})`);
+    } else if (!/^[a-zA-Z0-9_:-]+$/.test(payload.run_id)) {
+      errors.push(`run_id contains invalid characters: "${payload.run_id}"`);
+    }
+
+    // test_case_uuid — reuse UuidValidator for the canonical check
+    if (!payload.test_case_uuid) {
+      errors.push('test_case_uuid is required');
+    } else {
+      // Require nid-prefixed uuid-v4 shape. Duplicated here to avoid a
+      // circular require between PayloadBuilder and UuidValidator.
+      const uuidPattern = /^\d+-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+      if (!uuidPattern.test(payload.test_case_uuid)) {
+        errors.push(`test_case_uuid does not match {nid}-{uuid-v4} shape: "${payload.test_case_uuid}"`);
+      }
+    }
+
+    // status
+    const ALLOWED_STATUSES = new Set(['passed', 'failed', 'skipped']);
+    if (!payload.status) {
+      errors.push('status is required');
+    } else if (!ALLOWED_STATUSES.has(String(payload.status).toLowerCase())) {
+      errors.push(`status must be one of {passed, failed, skipped} (got "${payload.status}")`);
+    }
+
+    // source — must be 'automation' when set (C1 contract)
+    if (payload.source !== undefined && payload.source !== 'automation') {
+      errors.push(`source must be "automation" if provided (got "${payload.source}")`);
+    }
+
+    // browser
+    if (payload.browser !== undefined) {
+      if (typeof payload.browser !== 'string' || payload.browser.length === 0) {
+        errors.push('browser must be a non-empty string when provided');
+      } else if (payload.browser.length > 255) {
+        errors.push(`browser exceeds 255 chars (got ${payload.browser.length})`);
+      } else if (!/^[a-zA-Z0-9 .\-_(),\/]+$/.test(payload.browser)) {
+        errors.push(`browser contains invalid characters: "${payload.browser}"`);
+      }
+    }
+
+    // environment
+    if (payload.environment !== undefined && payload.environment !== '') {
+      if (typeof payload.environment !== 'string') {
+        errors.push(`environment must be a string (got ${typeof payload.environment})`);
+      } else if (payload.environment.length > 255) {
+        errors.push(`environment exceeds 255 chars (got ${payload.environment.length})`);
+      } else if (!/^[a-zA-Z0-9._-]+$/.test(payload.environment)) {
+        errors.push(`environment contains invalid characters: "${payload.environment}"`);
+      }
+    }
+
+    // duration
+    if (payload.duration !== undefined && payload.duration !== null) {
+      const d = payload.duration;
+      if (typeof d !== 'number' || !Number.isFinite(d) || d < 0 || !Number.isInteger(d)) {
+        errors.push(`duration must be a non-negative integer (got ${d})`);
+      }
+    }
+
+    // timestamp
+    if (payload.timestamp !== undefined && payload.timestamp !== null) {
+      const t = payload.timestamp;
+      if (typeof t !== 'number' || !Number.isFinite(t) || t <= 0 || !Number.isInteger(t)) {
+        errors.push(`timestamp must be a positive integer (got ${t})`);
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
   /**
    * Validate run creation options
    * @param {Object} options - Run options

package/src/utils/index.js

@@ -6,6 +6,13 @@ const UuidValidator = require('./UuidValidator');
 const PayloadBuilder = require('./PayloadBuilder');
 const RunDataNormalizer = require('./RunDataNormalizer');
 const { mapAppqUuid } = require('./mapAppqUuid');
+const {
+  setupAuth,
+  authStatePath,
+  authStateDir,
+  envVarNames,
+  sanitizeRole,
+} = require('./setupAuth');
 const logger = require('./logger');
 
 module.exports = {
@@ -13,5 +20,10 @@ module.exports = {
   PayloadBuilder,
   RunDataNormalizer,
   mapAppqUuid,
+  setupAuth,
+  authStatePath,
+  authStateDir,
+  envVarNames,
+  sanitizeRole,
   logger
 };

package/src/utils/logger.js

@@ -5,7 +5,8 @@ const LOG_LEVELS = {
   DEBUG: 3
 };
 
-// Sensitive data patterns to sanitize
+// Regex-based sanitization catches value-shaped secrets inside string
+// payloads (raw JWTs in error messages, axios request dumps, etc).
 const SENSITIVE_PATTERNS = [
   // API Keys
   { pattern: /(appq_\w+_[a-f0-9]{32})/gi, replacement: 'appq_***_REDACTED' },
@@ -30,6 +31,51 @@ const SENSITIVE_PATTERNS = [
   { pattern: /("session"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' }
 ];
 
+// H5 — field-name-based sanitization catches custom-named fields the regex
+// list will miss: `x-secret`, `myAuthToken`, `dbPassword`, `serviceKey`, etc.
+// Applied recursively before the regex pass. Errs on the side of over-
+// redaction: any object key matching this pattern has its value replaced
+// regardless of nesting depth.
+const SENSITIVE_KEY_PATTERN = /token|secret|key|password|credential|auth/i;
+
+function redactByFieldName(value, seen) {
+  if (value === null || typeof value !== 'object') return value;
+  if (!seen) seen = new WeakSet();
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactByFieldName(item, seen));
+  }
+
+  const result = {};
+  for (const k of Object.keys(value)) {
+    const v = value[k];
+    if (SENSITIVE_KEY_PATTERN.test(k)) {
+      if (v === null || v === undefined) {
+        // Preserve null/undefined so consumers can detect "field present
+        // but empty" without leaking real values.
+        result[k] = v;
+      } else if (typeof v === 'object') {
+        // Recurse into nested objects/arrays. A sensitive container like
+        // `credentials: { user, password }` keeps its structure but its
+        // leaf values get redacted by the inner pass, so debug output
+        // still tells you which fields existed.
+        result[k] = redactByFieldName(v, seen);
+      } else if (typeof v === 'string' && /^Bearer\s+/i.test(v)) {
+        // Preserve scheme prefix for Authorization-style headers so the
+        // log reader can tell what kind of token was redacted.
+        result[k] = v.replace(/^(Bearer\s+).*$/i, '$1***REDACTED***');
+      } else {
+        result[k] = '***REDACTED***';
+      }
+    } else {
+      result[k] = redactByFieldName(v, seen);
+    }
+  }
+  return result;
+}
+
 class Logger {
   constructor(level = 'INFO') {
     this.level = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
@@ -55,17 +101,25 @@ class Logger {
       return sanitized;
     }
 
-    // Handle objects and arrays by converting to JSON and back
+    // Handle objects and arrays: redact by field name first (catches
+    // custom-named credential fields), then apply the regex pass to any
+    // remaining string values for value-shaped secrets.
     if (typeof data === 'object') {
       try {
-        let jsonString = JSON.stringify(data);
+        const redacted = redactByFieldName(data);
+        let jsonString = JSON.stringify(redacted);
         SENSITIVE_PATTERNS.forEach(({ pattern, replacement }) => {
           jsonString = jsonString.replace(pattern, replacement);
         });
         return JSON.parse(jsonString);
       } catch (error) {
-        // If JSON parsing fails, return original data
-        return data;
+        // If JSON serialization fails, return the field-redacted form
+        // rather than the raw data — never leak unfiltered objects.
+        try {
+          return redactByFieldName(data);
+        } catch (e) {
+          return data;
+        }
       }
     }
 

package/src/utils/setupAuth.js

@@ -0,0 +1,99 @@
+/**
+ * setupAuth — portable Playwright storageState resolution.
+ *
+ * Returns a deterministic file path. The same path resolves to the same
+ * file regardless of execution context, so the same generated/authored
+ * test script runs unchanged in:
+ *
+ *   - Appliqation's executor (the LoginHelper writes the file at this
+ *     path during validation prep, using AWS Secrets Manager-backed
+ *     credentials)
+ *
+ *   - Customer CI / local (the `appq-auth-setup` CLI writes the file at
+ *     this path, using credentials from env vars per the convention
+ *     downloaded from Project Settings → "download .env for CI")
+ *
+ * setupAuth() does NOT perform login itself — that's the CLI's job (CI)
+ * or the executor's job (Appliqation cloud). It only computes the path.
+ *
+ * Usage in a Playwright test file:
+ *
+ *   const { mapAppqUuid, setupAuth } = require('@appliqation/automation-sdk/utils');
+ *
+ *   test.use({ storageState: setupAuth({ project_id: 126, role: 'default' }) });
+ *
+ *   test('...', async ({ page }, testInfo) => {
+ *     mapAppqUuid(testInfo, '<uuid>');
+ *     // body — already authenticated
+ *   });
+ */
+
+const path = require('path');
+const os = require('os');
+
+/**
+ * Default base directory for storageState files. Overridable via
+ * APPQ_AUTH_STATE_DIR env var (Appliqation executor sets this per-run
+ * for tenant isolation; customers normally don't need to).
+ */
+function authStateDir() {
+  return process.env.APPQ_AUTH_STATE_DIR
+    || path.join(os.homedir(), '.appq-auth');
+}
+
+/**
+ * Compute the canonical storageState path for a given project + role.
+ * Pure function — no I/O. Both the SDK CLI and the Appliqation executor
+ * call this same function so they always agree on the location.
+ */
+function authStatePath({ project_id, role = 'default' }) {
+  if (project_id === undefined || project_id === null || project_id === '') {
+    throw new Error('authStatePath requires project_id');
+  }
+  const safeRole = sanitizeRole(role);
+  return path.join(authStateDir(), `project-${project_id}-${safeRole}.json`);
+}
+
+/**
+ * The public entry point. Returns a string suitable for Playwright's
+ * `storageState` option (a file path).
+ */
+function setupAuth({ project_id, role = 'default' } = {}) {
+  if (project_id === undefined || project_id === null || project_id === '') {
+    throw new Error(
+      'setupAuth requires project_id. Generated test files include this '
+      + 'as a literal; for hand-authored tests, copy from your project URL '
+      + 'in Appliqation.'
+    );
+  }
+  return authStatePath({ project_id, role });
+}
+
+/**
+ * Lowercase + alphanumeric/underscore/hyphen only. Mirrors the role-name
+ * validation in the Appliqation project settings UI so paths line up.
+ */
+function sanitizeRole(role) {
+  return String(role).toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+}
+
+/**
+ * Env-var name convention for the CLI (and any other consumer) to look
+ * up credentials. Matches what the "download .env for CI" feature in
+ * Appliqation generates. Exported so the CLI and the SDK never drift.
+ */
+function envVarNames({ project_id, role }) {
+  const safeRole = sanitizeRole(role).toUpperCase();
+  return {
+    username: `APPQ_PROJECT_${project_id}_${safeRole}_USERNAME`,
+    password: `APPQ_PROJECT_${project_id}_${safeRole}_PASSWORD`,
+  };
+}
+
+module.exports = {
+  setupAuth,
+  authStatePath,
+  authStateDir,
+  envVarNames,
+  sanitizeRole,
+};