@omega.js/backend 0.1.0

package/dist/test/utils/firestore-rules-client.js

@@ -0,0 +1,277 @@
+/**
+ * Firestore Rules Testing Client
+ *
+ * Creates authenticated Firestore clients that respect security rules.
+ * Uses @firebase/rules-unit-testing to simulate authenticated users.
+ *
+ * This is different from the admin SDK (which bypasses rules) - these clients
+ * are subject to the same security rules as real client apps.
+ *
+ * @see https://firebase.google.com/docs/firestore/security/test-rules-emulator
+ */
+const {
+  initializeTestEnvironment,
+  assertSucceeds,
+  assertFails,
+} = require('@firebase/rules-unit-testing');
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const { TEST_DATA } = require('../test-accounts.js');
+
+let testEnv = null;
+
+/**
+ * Initialize the test environment
+ * Must be called before using any rules testing functions
+ *
+ * @param {object} options
+ * @param {string} options.projectId - Firebase project ID
+ * @param {string} options.rulesPath - Path to firestore.rules file (optional)
+ * @param {string} options.host - Emulator host (default: 127.0.0.1)
+ * @param {number} options.port - Emulator port (default: 8080)
+ */
+async function initRulesTestEnv(options) {
+  options = options || {};
+
+  const projectId = options.projectId || process.env.GCLOUD_PROJECT || TEST_DATA.defaultProjectId;
+  const host = options.host || '127.0.0.1';
+  const port = options.port || 8080;
+
+  // Load rules from file if path provided
+  let rules = null;
+  if (options.rulesPath && jetpack.exists(options.rulesPath)) {
+    rules = jetpack.read(options.rulesPath);
+  }
+
+  const config = {
+    projectId,
+    firestore: {
+      host,
+      port,
+    },
+  };
+
+  // Only add rules if we have them
+  if (rules) {
+    config.firestore.rules = rules;
+  }
+
+  testEnv = await initializeTestEnvironment(config);
+
+  return testEnv;
+}
+
+/**
+ * Get the test environment (initialize if needed)
+ */
+async function getTestEnv(options) {
+  if (!testEnv) {
+    await initRulesTestEnv(options);
+  }
+  return testEnv;
+}
+
+/**
+ * Create an authenticated Firestore client
+ * This client is subject to security rules as if it were a real authenticated user
+ *
+ * @param {string} uid - User UID to authenticate as
+ * @param {object} claims - Additional auth claims (email, admin, etc.)
+ * @returns {object} Firestore instance with authenticated context
+ */
+function getAuthenticatedFirestore(uid, claims) {
+  if (!testEnv) {
+    throw new Error('Test environment not initialized. Call initRulesTestEnv() first.');
+  }
+
+  claims = claims || {};
+
+  // Build token options - v5 automatically sets sub/user_id from first param
+  const tokenOptions = {
+    email: claims.email || `${uid}@test.com`,
+    ...claims,
+  };
+
+  const context = testEnv.authenticatedContext(uid, tokenOptions);
+  return context.firestore();
+}
+
+/**
+ * Create an unauthenticated Firestore client
+ * This client is subject to security rules as if no user is signed in
+ *
+ * @returns {object} Firestore instance without authentication
+ */
+function getUnauthenticatedFirestore() {
+  if (!testEnv) {
+    throw new Error('Test environment not initialized. Call initRulesTestEnv() first.');
+  }
+
+  const context = testEnv.unauthenticatedContext();
+  return context.firestore();
+}
+
+/**
+ * Clean up test environment
+ * Call this after all tests are complete
+ */
+async function cleanupTestEnv() {
+  if (testEnv) {
+    await testEnv.cleanup();
+    testEnv = null;
+  }
+}
+
+/**
+ * Clear all Firestore data in the emulator
+ * Useful between tests for clean state
+ */
+async function clearFirestore() {
+  if (!testEnv) {
+    throw new Error('Test environment not initialized. Call initRulesTestEnv() first.');
+  }
+  await testEnv.clearFirestore();
+}
+
+/**
+ * Helper to test that an operation succeeds
+ * @param {Promise} operation - Firestore operation promise
+ * @returns {Promise} Resolves if operation succeeds, rejects otherwise
+ */
+async function expectSuccess(operation) {
+  return assertSucceeds(operation);
+}
+
+/**
+ * Helper to test that an operation fails (permission denied)
+ * @param {Promise} operation - Firestore operation promise
+ * @returns {Promise} Resolves if operation fails, rejects if it succeeds
+ */
+async function expectFailure(operation) {
+  return assertFails(operation);
+}
+
+/**
+ * Seed test account documents into Firestore (bypasses security rules)
+ * This is needed because security rules like isAdmin() read from Firestore documents
+ *
+ * @param {object} accounts - Test accounts object with uid, email, etc.
+ */
+async function seedTestAccounts(accounts) {
+  if (!testEnv) {
+    throw new Error('Test environment not initialized. Call initRulesTestEnv() first.');
+  }
+
+  // Use withSecurityRulesDisabled to write ONLY roles (for isAdmin() rules checks)
+  // Do NOT write subscription — that's already set by createAccount with config-resolved product IDs
+  await testEnv.withSecurityRulesDisabled(async (context) => {
+    const db = context.firestore();
+    const { TEST_ACCOUNTS } = require('../test-accounts.js');
+
+    for (const [accountType, account] of Object.entries(accounts)) {
+      if (!account.uid) {
+        continue;
+      }
+
+      const staticDef = TEST_ACCOUNTS[accountType];
+
+      // Only write auth + roles for rules testing — subscription is already correct in the doc
+      const userData = {
+        auth: {
+          uid: account.uid,
+          email: account.email,
+        },
+        roles: staticDef?.properties?.roles || {},
+      };
+
+      await db.doc(`users/${account.uid}`).set(userData, { merge: true });
+    }
+  });
+}
+
+/**
+ * Create a rules testing context for use in @omega.js/backend tests
+ *
+ * @param {object} options
+ * @param {string} options.projectId - Firebase project ID
+ * @param {object} options.accounts - Test accounts object
+ * @returns {object} Rules testing context
+ */
+async function createRulesContext(options) {
+  options = options || {};
+
+  await getTestEnv(options);
+
+  // Seed test account documents so rules like isAdmin() work
+  if (options.accounts) {
+    await seedTestAccounts(options.accounts);
+  }
+
+  return {
+    /**
+     * Get Firestore client authenticated as a specific user
+     * @param {string} uid - User UID
+     * @param {object} claims - Additional claims
+     */
+    asUser: (uid, claims) => getAuthenticatedFirestore(uid, claims),
+
+    /**
+     * Get Firestore client authenticated as a test account
+     * @param {string} accountType - 'basic', 'admin', 'premium-active', etc.
+     */
+    asAccount: (accountType) => {
+      const account = options.accounts?.[accountType];
+      if (!account) {
+        throw new Error(`Unknown account type: ${accountType}`);
+      }
+
+      const claims = {
+        email: account.email,
+      };
+
+      // Add admin claim if this is the admin account
+      if (accountType === 'admin' || account.roles?.admin) {
+        claims.admin = true;
+      }
+
+      return getAuthenticatedFirestore(account.uid, claims);
+    },
+
+    /**
+     * Get unauthenticated Firestore client
+     */
+    asAnonymous: () => getUnauthenticatedFirestore(),
+
+    /**
+     * Assert that operation succeeds
+     */
+    expectSuccess,
+
+    /**
+     * Assert that operation fails (permission denied)
+     */
+    expectFailure,
+
+    /**
+     * Clear all Firestore data
+     */
+    clearData: clearFirestore,
+
+    /**
+     * Cleanup (call after tests)
+     */
+    cleanup: cleanupTestEnv,
+  };
+}
+
+module.exports = {
+  initRulesTestEnv,
+  getTestEnv,
+  getAuthenticatedFirestore,
+  getUnauthenticatedFirestore,
+  cleanupTestEnv,
+  clearFirestore,
+  expectSuccess,
+  expectFailure,
+  createRulesContext,
+};

package/dist/test/utils/http-client.js

@@ -0,0 +1,228 @@
+const fetch = require('wonderful-fetch');
+
+/**
+ * HTTP Client wrapper for making API calls during tests
+ * Supports:
+ *   - RESTful API: http.post('general/uuid', body), http.get(...), http.delete(...)
+ *   - Auth contexts: http.as('admin').post(...), http.as('basic').get(...)
+ */
+class HttpClient {
+  constructor(options) {
+    options = options || {};
+
+    // Use API URL (port 5002, the hosting emulator) for all requests, not the
+    // functions URL (port 5001). All requests go through /omega which
+    // rewrites to the omega_api function.
+    this.baseUrl = options.apiUrl || '';
+    this.defaultHeaders = {};
+    this.defaultAuthParams = {};
+    this.timeout = options.timeout || 30000;
+
+    // Store accounts reference for as() method
+    this.accounts = options.accounts || null;
+    this.adminKey = options.adminKey || '';
+    this.webhookKey = options.webhookKey || '';
+  }
+
+  /**
+   * Set authentication for subsequent requests
+   * @param {string} type - 'none', 'privateKey', 'adminKey', 'bearer'
+   * @param {object} credentials - Credentials object
+   */
+  setAuth(type, credentials) {
+    credentials = credentials || {};
+
+    switch (type) {
+      case 'privateKey':
+        this.defaultHeaders['Authorization'] = `Bearer ${credentials.privateKey}`;
+        this.defaultAuthParams = {};
+        break;
+      case 'adminKey':
+        delete this.defaultHeaders['Authorization'];
+        this.defaultHeaders['omega-admin-key'] = credentials.key;
+        this.defaultAuthParams = {};
+        break;
+      case 'bearer':
+        this.defaultHeaders['Authorization'] = `Bearer ${credentials.token}`;
+        this.defaultAuthParams = {};
+        break;
+      case 'none':
+      default:
+        delete this.defaultHeaders['Authorization'];
+        this.defaultAuthParams = {};
+        break;
+    }
+  }
+
+  /**
+   * Get auth config for a specific account type
+   * @param {string} accountType - 'admin', 'basic', 'premium', 'expired', 'none'
+   * @returns {object} - { headers, authParams } for the request
+   */
+  _getAuthConfig(accountType) {
+    if (accountType === 'none') {
+      return { headers: {}, authParams: {} };
+    }
+
+    if (accountType === 'admin') {
+      return {
+        headers: { 'omega-admin-key': this.adminKey },
+        authParams: {},
+      };
+    }
+
+    // User accounts - use privateKey
+    const account = this.accounts?.[accountType];
+    if (account?.privateKey) {
+      return {
+        headers: { 'Authorization': `Bearer ${account.privateKey}` },
+        authParams: {},
+      };
+    }
+
+    // Fallback to no auth if account not found
+    return { headers: {}, authParams: {} };
+  }
+
+  /**
+   * Build default auth config from instance defaults
+   */
+  _getDefaultAuthConfig() {
+    return {
+      headers: { ...this.defaultHeaders },
+      authParams: { ...this.defaultAuthParams },
+    };
+  }
+
+  /**
+   * Format response consistently for success/error cases
+   */
+  _formatResponse(response, error) {
+    if (error) {
+      return {
+        success: false,
+        status: error.status || error.code || 500,
+        data: null,
+        error: error.message || error,
+      };
+    }
+
+    return {
+      success: true,
+      status: response.status || 200,
+      data: response,
+      error: null,
+    };
+  }
+
+  /**
+   * Create a request helper bound to a specific auth context
+   * Usage:
+   *   - http.as('admin').post('marketing/contact', data)
+   *   - http.as('none').get('general/uuid', {version: '4'})
+   * @param {string} accountType - 'admin', 'basic', 'premium', 'expired', 'none'
+   * @returns {object} - Object with get(), post(), put(), delete() methods
+   */
+  as(accountType) {
+    const authConfig = this._getAuthConfig(accountType);
+
+    return {
+      get: (route, params, options) => this._fetch('get', route, params, authConfig, options),
+      post: (route, body, options) => this._fetch('post', route, body, authConfig, options),
+      put: (route, body, options) => this._fetch('put', route, body, authConfig, options),
+      delete: (route, body, options) => this._fetch('delete', route, body, authConfig, options),
+    };
+  }
+
+  /**
+   * Create a request helper with a specific private key
+   * Useful when testing with dynamically generated keys
+   * Usage:
+   *   - http.withPrivateKey(key).post('user/profile', data)
+   * @param {string} privateKey - The private key to use for authentication
+   * @returns {object} - Object with get(), post(), put(), delete() methods
+   */
+  withPrivateKey(privateKey) {
+    const authConfig = {
+      headers: { 'Authorization': `Bearer ${privateKey}` },
+      authParams: {},
+    };
+
+    return {
+      get: (route, params, options) => this._fetch('get', route, params, authConfig, options),
+      post: (route, body, options) => this._fetch('post', route, body, authConfig, options),
+      put: (route, body, options) => this._fetch('put', route, body, authConfig, options),
+      delete: (route, body, options) => this._fetch('delete', route, body, authConfig, options),
+    };
+  }
+
+  /**
+   * Internal: Make HTTP request with specific auth
+   * - GET: auth params merged into query string
+   * - POST/PUT/DELETE: auth params merged into body
+   */
+  async _fetch(method, route, data, authConfig, options) {
+    options = options || {};
+    data = data || {};
+
+    const isGet = method === 'get';
+    const endpoint = `/${route}`;
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = { ...authConfig.headers, ...options.headers };
+
+    const fetchOptions = {
+      method: method,
+      response: 'json',
+      timeout: options.timeout || this.timeout,
+      headers: headers,
+    };
+
+    // GET: auth params go into query string
+    // POST/PUT/DELETE: auth params go into body
+    if (isGet) {
+      fetchOptions.query = { ...authConfig.authParams, ...data };
+    } else {
+      fetchOptions.body = { ...authConfig.authParams, ...data };
+    }
+
+    try {
+      const response = await fetch(url, fetchOptions);
+      return this._formatResponse(response);
+    } catch (error) {
+      return this._formatResponse(null, error);
+    }
+  }
+
+  // ==================== Public API ====================
+  // These use the default auth set via setAuth()
+
+  /**
+   * Make a RESTful POST request (uses default auth)
+   */
+  async post(route, body, options) {
+    return this._fetch('post', route, body, this._getDefaultAuthConfig(), options);
+  }
+
+  /**
+   * Make a RESTful GET request (uses default auth)
+   */
+  async get(route, params, options) {
+    return this._fetch('get', route, params, this._getDefaultAuthConfig(), options);
+  }
+
+  /**
+   * Make a RESTful PUT request (uses default auth)
+   */
+  async put(route, body, options) {
+    return this._fetch('put', route, body, this._getDefaultAuthConfig(), options);
+  }
+
+  /**
+   * Make a RESTful DELETE request (uses default auth)
+   */
+  async delete(route, body, options) {
+    return this._fetch('delete', route, body, this._getDefaultAuthConfig(), options);
+  }
+}
+
+module.exports = HttpClient;

package/dist/test/utils/test-mode-file.js

@@ -0,0 +1,192 @@
+/**
+ * Shared state file that lets the test command and the running emulator
+ * agree on a small set of env vars without coordinated shell flags.
+ *
+ * The test command writes this file pre-flight (before invoking the runner).
+ * The emulator process watches it and mutates the corresponding entries in
+ * `process.env` in place when it changes. All existing branch sites read
+ * `process.env.X` per call so the mutation is invisible to them — no
+ * code-branch refactor needed.
+ *
+ * File lives at `<consumerProject>/.temp/test-mode.json` — `.temp/` is the
+ * standard transient cache directory across UJM/BXM/EM/@omega.js/backend consumer projects
+ * (sits at the repo root, gitignored by default).
+ *
+ * ## Allowlist
+ *
+ * `SYNCED_ENV_KEYS` is the explicit list of env vars allowed to flow from the
+ * test command into the emulator. Adding a new live-sync var = one-line addition.
+ *
+ * Why an allowlist (not "sync everything"):
+ *   - Some env vars are process-specific (e.g. FIRESTORE_EMULATOR_HOST is only
+ *     correct on the test runner, never on the emulator) and would break things
+ *     if synced. The allowlist prevents that.
+ *   - Sensitive values (API keys) shouldn't be silently overwritten on the
+ *     emulator just because the test runner happens to have them set.
+ *   - Keeps mutation explicit and reviewable.
+ *
+ * File format:
+ *   {
+ *     "env": {
+ *       "TEST_EXTENDED_MODE": "true"
+ *     },
+ *     "updatedAt": "2026-05-14T..."
+ *   }
+ *
+ * Values are strings to match `process.env` semantics. Empty string means
+ * "unset" — applyEnvFromFile() will `delete process.env[key]` when the value
+ * is empty, matching the way Node treats unset vs falsy env vars.
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const TEST_MODE_FILENAME = 'test-mode.json';
+const TEMP_DIR_NAME = '.temp';
+
+// Explicit allowlist of env vars that flow from the test command into the
+// running emulator. Add a key here to make it live-syncable; nothing else
+// flows through.
+const SYNCED_ENV_KEYS = [
+  'TEST_EXTENDED_MODE',
+];
+
+/**
+ * Resolve the absolute path to the test-mode file for a given consumer project.
+ *
+ * @param {string} projectDir - Consumer project root (the directory that
+ *                               contains `firebase.json` / `functions/`).
+ * @returns {string} Absolute path to `<projectDir>/.temp/test-mode.json`.
+ */
+function getTestModeFilePath(projectDir) {
+  return path.join(projectDir, TEMP_DIR_NAME, TEST_MODE_FILENAME);
+}
+
+/**
+ * Read the current test-mode payload from disk. Tolerant — returns `null`
+ * if the file is missing or unreadable, never throws.
+ *
+ * @param {string} projectDir
+ * @returns {{ env: Object<string, string>, updatedAt: string } | null}
+ */
+function readTestMode(projectDir) {
+  const filePath = getTestModeFilePath(projectDir);
+
+  if (!jetpack.exists(filePath)) {
+    return null;
+  }
+
+  try {
+    const data = jetpack.read(filePath, 'json');
+    if (!data || typeof data !== 'object') {
+      return null;
+    }
+    return {
+      env: (data.env && typeof data.env === 'object') ? data.env : {},
+      updatedAt: data.updatedAt || null,
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Write the desired env subset to disk. Atomic via fs-jetpack. Creates the
+ * `.temp/` directory if missing. Filters input through SYNCED_ENV_KEYS so
+ * only allowlisted keys are persisted, even if the caller passes extras.
+ *
+ * @param {string} projectDir
+ * @param {Object<string, string|undefined>} envInput - Map of env vars to sync.
+ *                                                       Keys outside SYNCED_ENV_KEYS are dropped.
+ *                                                       Empty/undefined values are persisted as ''
+ *                                                       (meaning "unset on receiving side").
+ * @returns {string} Absolute path of the written file (for logging).
+ */
+function writeTestMode(projectDir, envInput) {
+  const filePath = getTestModeFilePath(projectDir);
+  const env = {};
+
+  for (const key of SYNCED_ENV_KEYS) {
+    const v = envInput?.[key];
+    env[key] = v == null ? '' : String(v);
+  }
+
+  const payload = {
+    env,
+    updatedAt: new Date().toISOString(),
+  };
+
+  jetpack.write(filePath, payload, { atomic: true });
+
+  return filePath;
+}
+
+/**
+ * Capture the allowlisted subset of `process.env` into a plain object.
+ * Convenience for callers that want to write "whatever I currently have".
+ *
+ * @param {NodeJS.ProcessEnv} [source=process.env]
+ * @returns {Object<string, string>}
+ */
+function captureSyncedEnv(source) {
+  const src = source || process.env;
+  const out = {};
+
+  for (const key of SYNCED_ENV_KEYS) {
+    out[key] = src[key] == null ? '' : String(src[key]);
+  }
+
+  return out;
+}
+
+/**
+ * Apply a `data.env` payload to the current process's `process.env`. Used by
+ * the watcher inside the emulator process. Returns a list of `{key, was, now}`
+ * for any key that actually changed (caller can log these).
+ *
+ * Empty-string values in the payload are treated as "unset" — the
+ * corresponding `process.env[key]` is deleted. This matches Node semantics
+ * where `delete process.env.X` makes `process.env.X === undefined` and
+ * `!!process.env.X === false`.
+ *
+ * @param {{ env: Object<string, string> } | null} data
+ * @returns {Array<{ key: string, was: string|undefined, now: string|undefined }>}
+ */
+function applyEnvFromFile(data) {
+  if (!data || !data.env) {
+    return [];
+  }
+
+  const changed = [];
+
+  for (const key of SYNCED_ENV_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(data.env, key)) {
+      continue;
+    }
+
+    const was = process.env[key];
+    const next = data.env[key];
+
+    if (next === '' || next == null) {
+      if (was != null) {
+        delete process.env[key];
+        changed.push({ key, was, now: undefined });
+      }
+    } else if (was !== next) {
+      process.env[key] = next;
+      changed.push({ key, was, now: next });
+    }
+  }
+
+  return changed;
+}
+
+module.exports = {
+  TEST_MODE_FILENAME,
+  TEMP_DIR_NAME,
+  SYNCED_ENV_KEYS,
+  getTestModeFilePath,
+  readTestMode,
+  writeTestMode,
+  captureSyncedEnv,
+  applyEnvFromFile,
+};

package/dist/utils/merge-line-files.js

@@ -0,0 +1,6 @@
+// Shared devkit module — vendored into dist/vendor/devkit at prepare time by the
+// preparePackage `after` hook. This shim keeps the framework's internal require
+// paths stable while the implementation lives in @omega.js/devkit (@omega.js/backend contributed
+// the custom-key promotion: a key the framework newly adopts into its Default
+// section is promoted UP from the user's Custom section with their value).
+module.exports = require('../vendor/devkit/merge-line-files.js');