@appliqation/automation-sdk 2.5.1 → 2.7.0

package/README.md

@@ -274,6 +274,141 @@ npx playwright test tests/login.spec.js -- --appq --appq_run_title="Login Tests
 
 ---
 
+## Authenticated apps (gated SUTs)
+
+If your application requires login, the SDK ships a portable auth setup
+that works the same way in Appliqation's executor and in your own CI/local.
+
+The login flow itself is **your code, in your repo** (`tests/appliqation/auth/login.ts`).
+Appliqation's executor and `npx appq-auth-setup` both run that same function — so
+SSO, MFA, multi-step login, OAuth, captcha bypass, custom IDP redirects all work
+because you write the Playwright code that handles them.
+
+### One-time setup per project
+
+1. **In Appliqation**: configure roles + credentials in **Project Settings → Auth Config** (role-by-role usernames/passwords). Credentials are encrypted server-side via AWS Secrets Manager.
+
+2. **In your repo**: create `tests/appliqation/auth/login.ts` describing your login flow:
+
+   ```typescript
+   import { defineLogin } from '@appliqation/automation-sdk/login';
+
+   export default defineLogin(async (page, { username, password, role, baseURL }) => {
+     await page.goto('/login');                          // baseURL handles env (staging/prod)
+     await page.getByLabel('Email').fill(username);
+     await page.getByLabel('Password').fill(password);
+     await page.getByRole('button', { name: 'Sign in' }).click();
+     await page.waitForURL('**/dashboard');
+
+     // Branch on role for multi-role flows / SSO / role-specific landing pages
+     if (role === 'admin') {
+       await page.getByRole('button', { name: 'Switch to admin view' }).click();
+     }
+   });
+   ```
+
+   Push to the main branch of your project's GitHub repo. Appliqation's GitHub webhook ingests the file automatically.
+
+3. **In Appliqation**: click the small **📥 download .env for CI** link on the project settings page. Fill in the placeholders and add to your CI secrets:
+
+   ```bash
+   APPLIQATION_API_KEY="<paste your project's API key>"
+   APPLIQATION_BASE_URL="https://appliqation.io"
+   APPLIQATION_PROJECT_KEY=126
+   APPLIQATION_SUT_BASE_URL="<your SUT URL, e.g. https://staging.acme.com>"
+
+   # Role: default
+   APPQ_PROJECT_126_DEFAULT_USERNAME="<paste username>"
+   APPQ_PROJECT_126_DEFAULT_PASSWORD="<paste password>"
+   ```
+
+   `APPLIQATION_SUT_BASE_URL` is the URL of the system you're testing — your login function's `await page.goto('/login')` resolves against this, so the same code works against staging, preprod, and prod by changing one env var.
+
+4. **(Optional)** Click **🧪 Test login** on the project settings page to validate your `login.ts` works against the live SUT. Surfaces success / specific failure inline within ~10 seconds.
+
+### In your test files
+
+Use `setupAuth` to declare which storage state Playwright should use:
+
+```typescript
+const { mapAppqUuid, setupAuth } = require('@appliqation/automation-sdk/utils');
+const { test, expect } = require('@playwright/test');
+
+test.use({
+  storageState: setupAuth({ project_id: 126, role: 'default' }),
+});
+
+test('manager dashboard loads', async ({ page }, testInfo) => {
+  mapAppqUuid(testInfo, '1141-...');
+  await page.goto('/dashboard'); // already authenticated
+});
+```
+
+`setupAuth()` returns a deterministic file path (e.g. `~/.appq-auth/project-126-default.json`). It does NOT perform login — that's handled separately:
+
+- **In Appliqation's executor (cloud runs)**: the LoginHelper imports your `login.ts` from the canonical store, runs it, and writes the storage state at this path before your test runs. Nothing else for you to do.
+- **In your CI / local**: run `npx appq-auth-setup` once before `playwright test`.
+
+### CI workflow
+
+```yaml
+# .github/workflows/playwright.yml
+- run: npx appq-auth-setup --project-id 126 --role default
+- run: npx playwright test
+```
+
+The CLI:
+1. Reads `APPQ_PROJECT_126_DEFAULT_USERNAME` / `_PASSWORD` from env
+2. Reads `APPLIQATION_SUT_BASE_URL` for the SUT base URL
+3. Dynamically imports `tests/appliqation/auth/login.ts` from your local checkout
+4. Launches Chromium, runs your login function, saves the storage state to the path `setupAuth()` will resolve to
+5. Tests run, already authenticated
+
+Re-run the CLI when sessions expire (typical: once per CI run). Idempotent and fast on cache hits.
+
+#### TypeScript loader (peer dependency)
+
+If your `login.ts` is TypeScript (recommended for the type checking on `LoginContext`), the CLI needs a TS loader installed in your project. Install one as a dev dep:
+
+```bash
+npm install --save-dev tsx
+# or
+npm install --save-dev ts-node
+```
+
+Plain `.js` / `.mjs` / `.cjs` login files don't need either.
+
+#### Custom login file path
+
+Default convention is `tests/appliqation/auth/login.ts`. Override with the `--login-file` flag or `APPQ_LOGIN_FILE` env var if your project uses a different layout:
+
+```yaml
+- run: npx appq-auth-setup --project-id 126 --role default --login-file e2e/auth/login.ts
+```
+
+### Multiple roles
+
+Configure each role in Project Settings, download the updated `.env` template (it lists all configured roles), fill in the values:
+
+```bash
+APPQ_PROJECT_126_DEFAULT_USERNAME="..."
+APPQ_PROJECT_126_DEFAULT_PASSWORD="..."
+APPQ_PROJECT_126_MANAGER_USERNAME="..."
+APPQ_PROJECT_126_MANAGER_PASSWORD="..."
+```
+
+Then in CI — one `appq-auth-setup` call per role you want to test:
+
+```yaml
+- run: npx appq-auth-setup --project-id 126 --role default
+- run: npx appq-auth-setup --project-id 126 --role manager
+- run: npx playwright test
+```
+
+Tests reference the role they need: `setupAuth({ project_id: 126, role: 'manager' })`. Your `login.ts` receives the role in its `LoginContext` so you can branch login flow per role if needed.
+
+---
+
 ## Enabling Appliqation Reporting (--appq Flag)
 
 By default, Appliqation reporting is **DISABLED**. You must explicitly enable it by adding the `--appq` flag to your test command.

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@appliqation/automation-sdk",
-  "version": "2.5.1",
-  "description": "Appliqation Automation SDK with API key authentication, custom run titles, and framework-specific reporters",
+  "version": "2.7.0",
+  "description": "Appliqation Automation SDK — API key auth, custom run titles, framework reporters, portable storageState (setupAuth), and customer-defined login flows (defineLogin) for gated apps",
   "main": "src/index.js",
   "types": "src/index.d.ts",
+  "bin": {
+    "appq-auth-setup": "./src/cli/auth-setup.js"
+  },
   "exports": {
     ".": {
       "require": "./src/index.js",
@@ -40,6 +43,11 @@
     "./utils": {
       "require": "./src/utils/index.js",
       "import": "./src/utils/index.js"
+    },
+    "./login": {
+      "types": "./src/login/index.d.ts",
+      "require": "./src/login/index.js",
+      "import": "./src/login/index.js"
     }
   },
   "files": [
@@ -110,7 +118,7 @@
     }
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "repository": {
     "type": "git",

package/src/cli/auth-setup.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * appq-auth-setup — populate Playwright storageState for an Appliqation
+ * project's role by dynamic-importing the customer's login.ts file
+ * and running it with role-specific creds from env vars.
+ *
+ *   npx appq-auth-setup --project-id 126 --role manager
+ *
+ * Customer setup (one-time, per project):
+ *   1. Configure roles in Appliqation Project Settings → Auth Config
+ *   2. Write `tests/appliqation/auth/login.ts` in their repo:
+ *
+ *      import { defineLogin } from '@appliqation/automation-sdk/login';
+ *      export default defineLogin(async (page, { username, password }) => {
+ *        await page.goto('/login');
+ *        await page.getByLabel('Email').fill(username);
+ *        await page.getByLabel('Password').fill(password);
+ *        await page.getByRole('button', { name: 'Sign in' }).click();
+ *        await page.waitForURL('**\/dashboard');
+ *      });
+ *
+ *   3. Download the .env template from Project Settings, fill in
+ *      values, drop into CI secrets
+ *   4. Add to CI yaml (one line per role used by their tests):
+ *      - run: npx appq-auth-setup --project-id 126 --role default
+ *      - run: npx playwright test
+ *
+ * What this CLI does:
+ *   1. Read APPQ_PROJECT_<id>_<ROLE>_USERNAME / _PASSWORD from env
+ *   2. Dynamic-import the customer's login.ts (path discoverable via
+ *      --login-file flag, env var, or convention)
+ *   3. Launch Chromium, run customer's login function with creds +
+ *      baseURL from APPLIQATION_SUT_BASE_URL env var
+ *   4. Save resulting Playwright storageState to the canonical path
+ *      from setupAuth({ project_id, role })
+ *
+ * Tests then load via:
+ *   test.use({ storageState: setupAuth({ project_id, role }) })
+ *
+ * Usage in CI: run BEFORE `playwright test`. Idempotent — fast on
+ * cache hit (~3s for the login flow), faster on no-op.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  authStatePath,
+  envVarNames,
+  sanitizeRole,
+} = require('../utils/setupAuth');
+
+const FATAL_EXIT = 1;
+const DEFAULT_LOGIN_FILE = 'tests/appliqation/auth/login.ts';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i++;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function fail(message) {
+  console.error(`✗ ${message}`);
+  process.exit(FATAL_EXIT);
+}
+
+/**
+ * Resolve the customer's login.ts path. Priority:
+ *   1. --login-file CLI flag (explicit override)
+ *   2. APPQ_LOGIN_FILE env var (CI override without changing CLI args)
+ *   3. Convention: tests/appliqation/auth/login.ts relative to CWD
+ *
+ * Throws clearly if the resolved path doesn't exist — customers who
+ * haven't created the file yet need a path-specific error, not a
+ * cryptic dynamic-import failure.
+ */
+function resolveLoginFile(args) {
+  const candidate = args['login-file']
+    || process.env.APPQ_LOGIN_FILE
+    || DEFAULT_LOGIN_FILE;
+  const absolute = path.isAbsolute(candidate)
+    ? candidate
+    : path.resolve(process.cwd(), candidate);
+  if (!fs.existsSync(absolute)) {
+    fail(
+      `Login file not found: ${absolute}\n`
+      + `  Create it (default path: ${DEFAULT_LOGIN_FILE}) and export your login flow as a default export:\n`
+      + `\n`
+      + `    import { defineLogin } from '@appliqation/automation-sdk/login';\n`
+      + `    export default defineLogin(async (page, { username, password, baseURL }) => {\n`
+      + `      await page.goto('/login');\n`
+      + `      // ... your login flow\n`
+      + `    });\n`
+    );
+  }
+  return absolute;
+}
+
+/**
+ * Dynamic-import the login file and return the default export. Handles
+ * both ESM (`export default ...`) and CommonJS (`module.exports = ...`)
+ * — the SDK's defineLogin is identity, so customers writing either
+ * style end up with a function we can call.
+ *
+ * For .ts files, requires the customer's repo to have a TS loader
+ * registered (tsx, ts-node, esbuild-node-loader). Most Playwright
+ * projects do via @playwright/test which transpiles TS on the fly,
+ * but the auth-setup CLI runs OUTSIDE the Playwright runner so we
+ * need the loader explicitly. We try `tsx` first (lightweight, the
+ * most common choice), then `ts-node`, then fail with a clear hint.
+ */
+async function loadLoginFunction(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.ts' || ext === '.tsx' || ext === '.mts' || ext === '.cts') {
+    let registered = false;
+    try {
+      require('tsx/cjs');
+      registered = true;
+    } catch {
+      try {
+        require('ts-node/register/transpile-only');
+        registered = true;
+      } catch { /* fall through */ }
+    }
+    if (!registered) {
+      fail(
+        `Login file is TypeScript (${path.basename(filePath)}) but no TS loader was found.\n`
+        + `  Install one as a dev dependency:\n`
+        + `    npm install --save-dev tsx\n`
+        + `  Or rename your login file to .js (CommonJS) / .mjs (ESM).`
+      );
+    }
+  }
+
+  let mod;
+  try {
+    mod = require(filePath);
+  } catch (requireErr) {
+    // ESM fallback — `require` of an ESM file throws ERR_REQUIRE_ESM.
+    try {
+      mod = await import(filePath);
+    } catch (importErr) {
+      fail(
+        `Failed to load ${filePath}:\n`
+        + `  CommonJS error: ${requireErr.message}\n`
+        + `  ESM error: ${importErr.message}`
+      );
+    }
+  }
+
+  const fn = mod && (mod.default || mod);
+  if (typeof fn !== 'function') {
+    fail(
+      `${filePath} did not default-export a function.\n`
+      + `  Expected:\n`
+      + `    export default defineLogin(async (page, ctx) => { ... });\n`
+      + `  Got: ${typeof fn}`
+    );
+  }
+  return fn;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  const project_id = args['project-id']
+    || process.env.APPLIQATION_PROJECT_KEY
+    || null;
+  const role = sanitizeRole(args.role || 'default');
+
+  if (!project_id) {
+    fail(
+      'Missing --project-id. Pass it as a flag or set APPLIQATION_PROJECT_KEY '
+      + 'in your env (the downloaded .env from your project settings includes it).'
+    );
+  }
+
+  const baseURL = (process.env.APPLIQATION_SUT_BASE_URL || '').replace(/\/$/, '');
+  if (!baseURL) {
+    fail(
+      'APPLIQATION_SUT_BASE_URL env var is not set. This is your SUT (System Under Test) URL '
+      + '— e.g. https://staging.acme.com — that the login flow runs against. Add it to your .env / CI secrets.'
+    );
+  }
+
+  const { username: userVar, password: pwdVar } = envVarNames({ project_id, role });
+  const username = process.env[userVar];
+  const password = process.env[pwdVar];
+  if (!username || !password) {
+    fail(
+      `Missing credential env vars: ${userVar} and/or ${pwdVar}.\n`
+      + `  Download the .env template from your project settings in Appliqation,\n`
+      + `  fill in the values, and add them to your CI secrets.`
+    );
+  }
+
+  const loginFile = resolveLoginFile(args);
+  console.log(`→ Loading login flow from ${path.relative(process.cwd(), loginFile)}`);
+  const loginFn = await loadLoginFunction(loginFile);
+
+  // Lazy-require playwright — it's a peer dep, not always installed.
+  let chromium;
+  try {
+    ({ chromium } = require('playwright'));
+  } catch {
+    fail(
+      'Playwright is not installed. Run `npm install --save-dev playwright` '
+      + '(or @playwright/test) and try again.'
+    );
+  }
+
+  const targetPath = authStatePath({ project_id, role });
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+  console.log(`→ Launching Chromium for login as role "${role}" against ${baseURL}`);
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    baseURL,
+    ignoreHTTPSErrors: true,
+  });
+  const page = await context.newPage();
+
+  try {
+    await loginFn(page, { username, password, role, baseURL });
+    await context.storageState({ path: targetPath });
+    console.log(`✓ Auth state saved to ${targetPath}`);
+    console.log(`  Tests using setupAuth({ project_id: ${project_id}, role: '${role}' }) will pick this up.`);
+  } catch (err) {
+    fail(`Login failed: ${err.message}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((err) => fail(err.message || String(err)));

package/src/index.d.ts

@@ -331,3 +331,60 @@ export const logger: {
  * ```
  */
 export function mapAppqUuid(testInfo: any, uuid: string): void;
+
+/**
+ * Returns the canonical Playwright `storageState` file path for a given
+ * Appliqation project + role. The same path resolves regardless of
+ * execution context, so the same generated/authored test runs unchanged
+ * in:
+ *   - Appliqation's executor (LoginHelper writes the file at this path)
+ *   - Customer CI / local (the `appq-auth-setup` CLI writes the file)
+ *
+ * Does NOT perform login itself — only computes the path. Pair with
+ * `npx appq-auth-setup --project-id X --role Y` (or Appliqation's
+ * executor) to populate the file before tests run.
+ *
+ * @example
+ * ```typescript
+ * import { test } from '@playwright/test';
+ * import { mapAppqUuid, setupAuth } from '@appliqation/automation-sdk/utils';
+ *
+ * test.use({ storageState: setupAuth({ project_id: 126, role: 'default' }) });
+ *
+ * test('manager dashboard loads', async ({ page }, testInfo) => {
+ *   mapAppqUuid(testInfo, '1141-...');
+ *   await page.goto('/dashboard'); // already authenticated
+ * });
+ * ```
+ */
+export function setupAuth(options: { project_id: number | string; role?: string }): string;
+
+/**
+ * Computes the canonical storageState file path. Same as setupAuth, but
+ * usable by tooling that needs the path without going through Playwright
+ * (e.g. the appq-auth-setup CLI writes to this path).
+ */
+export function authStatePath(options: { project_id: number | string; role?: string }): string;
+
+/**
+ * Base directory for storageState files. Defaults to `~/.appq-auth/`;
+ * overridable via APPQ_AUTH_STATE_DIR env (Appliqation's executor sets
+ * this per-run for tenant isolation).
+ */
+export function authStateDir(): string;
+
+/**
+ * The canonical env-var names the CLI looks up for credentials, given
+ * a project_id + role. Customers populate these from the `.env` template
+ * downloaded from Appliqation's project settings.
+ */
+export function envVarNames(options: { project_id: number | string; role?: string }): {
+  username: string;
+  password: string;
+};
+
+/**
+ * Normalize a role name to lowercase with only alphanumerics, underscore,
+ * and hyphen. Mirrors the role-name validation in the Appliqation UI.
+ */
+export function sanitizeRole(role: string): string;

package/src/login/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * TypeScript definitions for @appliqation/automation-sdk/login.
+ *
+ * Customers writing `tests/appliqation/auth/login.ts` import these
+ * types for autocomplete + compile-time checking on the login flow
+ * function shape. Same file gets imported (untyped, dynamically) by
+ * the Appliqation executor's LoginHelper and the appq-auth-setup CLI.
+ */
+
+import type { Page } from '@playwright/test';
+
+/**
+ * Per-call context passed to the customer's login function. Sourced
+ * differently in each runtime:
+ *
+ *   - Appliqation executor: username + password from AWS Secrets
+ *     Manager (read-only IAM); baseURL from the project's env
+ *     configuration; role from snapshot.auth_role.
+ *   - Customer CI (`npx appq-auth-setup`): username + password from
+ *     APPQ_PROJECT_<id>_<ROLE>_USERNAME/PASSWORD env vars; baseURL
+ *     from APPLIQATION_SUT_BASE_URL env var; role from --role flag.
+ */
+export interface LoginContext {
+  /** Username / email for the configured role. */
+  username: string;
+  /** Password for the configured role. */
+  password: string;
+  /**
+   * Role name as configured in Project Settings. Lets the customer
+   * branch login flow per role (e.g. an admin's login may include a
+   * "Switch to admin view" step that other roles skip).
+   */
+  role: string;
+  /**
+   * SUT base URL for the env this run targets. Use `await
+   * page.goto('/login')` — Playwright resolves the relative path
+   * against the context's baseURL, which is set from this value.
+   * Provided here for cases where the customer needs the full URL
+   * (e.g. cross-origin OAuth redirects).
+   */
+  baseURL: string;
+}
+
+/**
+ * Customer's login function. Should leave the page in an
+ * authenticated state — typically by navigating to the login URL,
+ * filling credentials, submitting, and waiting for a post-login URL
+ * or visible-element indicator. The caller (LoginHelper or
+ * appq-auth-setup) captures the resulting storageState immediately
+ * after this resolves.
+ *
+ * Throw on failure. The caller will surface the error verbatim in
+ * the executor's run audit / the CLI's exit code.
+ */
+export type LoginFunction = (
+  page: Page,
+  ctx: LoginContext,
+) => Promise<void>;
+
+/**
+ * Identity helper for type inference. Wrap your login function with
+ * this so your IDE provides autocomplete on the LoginContext fields:
+ *
+ * ```typescript
+ * import { defineLogin } from '@appliqation/automation-sdk/login';
+ *
+ * export default defineLogin(async (page, { username, password }) => {
+ *   await page.goto('/login');
+ *   await page.getByLabel('Email').fill(username);
+ *   await page.getByLabel('Password').fill(password);
+ *   await page.getByRole('button', { name: 'Sign in' }).click();
+ *   await page.waitForURL('**\/dashboard');
+ * });
+ * ```
+ */
+export function defineLogin<F extends LoginFunction>(fn: F): F;

package/src/login/index.js

@@ -0,0 +1,48 @@
+/**
+ * @appliqation/automation-sdk/login — types + helpers for customer-
+ * supplied login flows.
+ *
+ * Customers define their SUT's login flow as a Playwright function in
+ * their own repo (canonical path: `tests/appliqation/auth/login.ts`).
+ * The function is imported by:
+ *   1. Appliqation's executor (LoginHelper) — pulled from MongoDB
+ *      after a GitHub-webhook upsert into automan_canonical_scripts
+ *      with script_type:'login', dynamic-imported per role per cache
+ *      miss.
+ *   2. Customer CI (`npx appq-auth-setup`) — dynamic-imported from
+ *      disk, run with role-specific creds from env vars, output a
+ *      Playwright storageState file all tests load via
+ *      test.use({ storageState: setupAuth({ ... }) }).
+ *
+ * Same source file, two readers. Both run the customer's own code.
+ *
+ * Why offline GitOps and not in-app upload/edit:
+ *   - Customer's IDE + lint + PR review + git history come for free
+ *   - No in-app editor to build, no sandboxing concern beyond what we
+ *     already have for test scripts
+ *   - The login function is just Playwright code — it should live next
+ *     to the Playwright tests
+ *
+ * The selector-fill model in the legacy auth_config schema (login_url
+ * + 3 CSS selectors + success_indicator) only handled the simplest
+ * form-login case. SSO / MFA / OAuth / multi-step / captcha all
+ * require custom code anyway. Customer login.ts handles everything.
+ */
+
+/**
+ * Identity helper that gives type inference + auto-complete for
+ * customers writing their login.ts. Mirrors Playwright's
+ * `defineConfig` pattern — pure function, no runtime side-effects.
+ *
+ * @template {LoginFunction} F
+ * @param {F} fn
+ * @returns {F}
+ */
+function defineLogin(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('defineLogin: argument must be a function');
+  }
+  return fn;
+}
+
+module.exports = { defineLogin };

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/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,
+};