@omega.js/desktop 0.1.0

package/dist/utils/safe-install.js

@@ -0,0 +1,4 @@
+// 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.
+module.exports = require('../vendor/devkit/safe-install.js');

package/dist/utils/sanitize-signing-env.js

@@ -0,0 +1,45 @@
+// Empty-string signing env vars are WORSE than unset ones: the consumer .env
+// template ships placeholders like CSC_LINK="" so dotenv injects them as
+// set-but-empty, and app-builder-lib only null-checks — it then calls
+// importCertificate('') whose path.resolve('') lands on the PROJECT ROOT and
+// dies with "<projectRoot> not a file". Same hazard for the notarization and
+// Windows signing placeholders.
+//
+// Rule: an empty (or whitespace-only) value on any of these keys means "not
+// configured" — delete it so electron-builder's own auto-discovery/skip logic
+// applies. Returns the list of removed keys (for logging).
+
+const SIGNING_ENV_KEYS = [
+  'CSC_LINK',
+  'CSC_KEY_PASSWORD',
+  'CSC_NAME',
+  // electron-builder's OWN Windows cert name — @omega.js/desktop's signer reads
+  // WIN_EV_TOKEN_PATH ([#337](https://github.com/Omega-JS-Stack/omega/issues/337)).
+  'WIN_CSC_LINK',
+  'WIN_CSC_KEY_PASSWORD',
+  'WIN_EV_TOKEN_PATH',
+  'WIN_TIMESTAMP_URL',
+  'SIGNTOOL_PATH',
+  'APPLE_API_KEY',
+  'APPLE_API_KEY_ID',
+  'APPLE_API_ISSUER',
+  'APPLE_ID',
+  'APPLE_APP_SPECIFIC_PASSWORD',
+  'APPLE_TEAM_ID',
+];
+
+function sanitizeSigningEnv(env) {
+  const removed = [];
+
+  for (const key of SIGNING_ENV_KEYS) {
+    if (typeof env[key] === 'string' && env[key].trim() === '') {
+      delete env[key];
+      removed.push(key);
+    }
+  }
+
+  return removed;
+}
+
+module.exports = sanitizeSigningEnv;
+module.exports.SIGNING_ENV_KEYS = SIGNING_ENV_KEYS;

package/dist/utils/sanitize-url.js

@@ -0,0 +1,28 @@
+// sanitize-url — zero-trust URL gate for any string passed to `shell.openExternal`,
+// `BrowserWindow.loadURL`, or any other API that resolves a URL protocol.
+//
+// Returns the URL unchanged when its protocol is `http:` or `https:`; returns `''`
+// for anything else (`javascript:`, `file:`, `data:`, `vbscript:`, `chrome:`, etc.).
+// Empty string is preferred over throwing because callers can no-op cleanly without
+// try/catch noise. shell.openExternal('') is a documented no-op on all platforms.
+//
+// This is for HTTP(S) URLs only. Custom schemes like `restart-manager://` or `mailto:`
+// must be passed through directly — do NOT route them through this helper.
+//
+// Usage:
+//   const sanitizeURL = require('./utils/sanitize-url.js');
+//   const safe = sanitizeURL(maybeHostileUrl);
+//   if (safe) shell.openExternal(safe);
+
+function sanitizeURL(url) {
+  if (!url || typeof url !== 'string') return '';
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '';
+    return url;
+  } catch (e) {
+    return '';
+  }
+}
+
+module.exports = sanitizeURL;

package/dist/utils/secure-remote-url.js

@@ -0,0 +1,25 @@
+/**
+ * isSecureRemoteUrl(url) — transport gate for the remote code/config lanes
+ * (lib/remote-scripts.js, lib/remote-config.js), which execute or apply
+ * network-fetched content. Only `https:` passes; `http:` is allowed solely
+ * for loopback hosts so local dev servers keep working. Unparseable URLs
+ * fail closed.
+ *
+ * @param {string} url - The resolved fetch URL.
+ * @returns {boolean} True when the URL is safe to fetch remote content from.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+
+function isSecureRemoteUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    return false;
+  }
+
+  if (parsed.protocol === 'https:') return true;
+  return parsed.protocol === 'http:' && LOOPBACK_HOSTS.has(parsed.hostname);
+}
+
+module.exports = { isSecureRemoteUrl };

package/dist/utils/stealth-window.js

@@ -0,0 +1,37 @@
+// stealth-window — the single stealth-surfacing recipe for test runs.
+//
+// Makes a BrowserWindow render normally while staying invisible and
+// non-intrusive: opacity 0 (still painting — deliberately NOT hide()/minimize(),
+// which occlusion-throttle Chromium: rAF pauses and visibilityState flips, so
+// tests would exercise a DIFFERENT runtime), click-through (real OS clicks pass
+// to whatever is underneath; synthetic input — executeJavaScript,
+// sendInputEvent, CDP — is unaffected), and never focused.
+//
+// show()/focus() are rerouted because RAW windows (created with
+// `new BrowserWindow()` outside lib/window-manager — e.g. a consumer's
+// automation popup) call win.show() themselves: show() becomes showInactive()
+// so the window surfaces without taking keyboard focus, and focus() becomes a
+// no-op. Stealth is decided at application time — a window stealthed here stays
+// stealthed for its lifetime (OMEGA_TEST_SHOW=1 is honored by the callers, per
+// window, at creation/surface time).
+//
+// Consumers: lib/window-manager.js `_surface()` (named windows) and main.js's
+// `browser-window-created` hook (every other window during test runs). Shared
+// predicate: utils/test-stealth.js.
+//
+// Idempotent — applying twice is harmless.
+
+function applyStealth(win) {
+  if (!win || win.isDestroyed()) {
+    return;
+  }
+
+  win.setOpacity(0);
+  win.setIgnoreMouseEvents(true);
+
+  const showInactive = win.showInactive.bind(win);
+  win.show = () => showInactive();
+  win.focus = () => {};
+}
+
+module.exports = { applyStealth };

package/dist/utils/test-stealth.js

@@ -0,0 +1,29 @@
+// test-stealth — single source of truth for "should @omega.js/desktop keep test-run UI invisible
+// and non-intrusive?".
+//
+// True when the process is in Testing mode AND the developer hasn't opted into
+// watching the run (OMEGA_TEST_SHOW=1). Shared by:
+//   - lib/window-manager.js — stealth window surfacing (showInactive + opacity 0
+//     + click-through)
+//   - main.js — app-level activation suppression on macOS (accessory policy via
+//     app.dock.hide(), so a launching test app never steals keyboard focus)
+//   - test/harness/main-entry.js — same suppression for the spawned harness app,
+//     which initializes its Manager only after app ready (too late to prevent
+//     the launch activation)
+//
+// Pass the Manager when you have one — its isTesting() is authoritative (honors
+// config.em.environment overrides). Without one (the harness, pre-Manager code),
+// falls back to the standalone mode-helpers check (OMEGA_TEST_MODE=true).
+//
+// Usage:
+//   const isTestStealth = require('./utils/test-stealth.js');
+//   if (isTestStealth(manager)) { ... }
+
+const { isTesting } = require('./mode-helpers.js');
+
+function isTestStealth(manager) {
+  const testing = manager ? manager.isTesting() : isTesting();
+  return testing && process.env.OMEGA_TEST_SHOW !== '1';
+}
+
+module.exports = isTestStealth;

package/dist/utils/url-helpers.js

@@ -0,0 +1,169 @@
+// Backend URL helpers, shared across all Manager contexts (main / renderer / preload /
+// build). Mirror @omega.js/client's contract so @omega.js/desktop apps can hit the same dev/prod backends as
+// UJM and BXM consumers.
+//
+// `getEnvironment()` is the SINGLE SOURCE OF TRUTH and lives in src/utils/mode-helpers.js
+// (alongside the is*() family; mirrors @omega.js/backend/UJM/BXM). It returns exactly ONE of
+// 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+//
+// `getFunctionsUrl()` / `getApiUrl()` / `getWebsiteUrl()` route through
+// `this.getEnvironment()` and resolve to LOCAL urls in BOTH development AND testing —
+// callers normally pass NO argument. An explicit `environment` arg is an override
+// (used mainly by tests to pin a specific environment's mapping).
+
+// Guarded the way @omega.js/extension's twin is: the renderer bundle is a
+// browser context, and only the Node-side contexts (main, preload, build, the
+// test harness) carry the resolved-port env channel.
+function envPort(name) {
+  return typeof process !== 'undefined' && process.env
+    ? process.env[name]
+    : undefined;
+}
+
+// The classic dev WEBSITE ORIGIN: a lockstep copy of @omega.js/config's
+// CLASSIC_DEV_ORIGIN, which is the SSOT. This module is attached in the RENDERER
+// too (src/renderer.js), so it rides the browser bundle and cannot require that
+// Node-only package (fs, net, json5); @omega.js/client mirrors the same constant
+// for the same reason. The build suite pins this copy to the config package's
+// value, so a drift fails a test instead of a user
+// ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)).
+const CLASSIC_DEV_ORIGIN = 'https://localhost:4000';
+
+// One local port, from whichever channel this context has: the env var first
+// (the CLI that booted the stack publishes it, N7), then the `dev.ports` map
+// the bundle baked into OMEGA_BUILD_JSON: a PACKAGED main process has no
+// parent env, so a bumped emulator port reaches it only that way
+// ([#745](https://github.com/Omega-JS-Stack/omega/issues/745)). Same helper,
+// same order as @omega.js/extension's src/utils/url-helpers.js.
+function localPort(context, envName, name) {
+  return envPort(envName) || context?.config?.dev?.ports?.[name];
+}
+
+function getFunctionsUrl(environment) {
+  const env = environment || this.getEnvironment();
+  const projectId = this?.config?.cloud?.config?.projectId;
+
+  if (!projectId) {
+    throw new Error('cloud.config.projectId not set in config/omega.json5');
+  }
+
+  // Local for development OR testing; production otherwise. The port rides the
+  // same three-step chain getApiUrl() walks: the OMEGA_*_PORT env channel (N7),
+  // then the baked map, then the classic default.
+  if (env === 'development' || env === 'testing') {
+    const port = localPort(this, 'OMEGA_FUNCTIONS_PORT', 'functions') || 5001;
+    return `http://localhost:${port}/${projectId}/us-central1`;
+  }
+
+  return `https://us-central1-${projectId}.cloudfunctions.net`;
+}
+
+function getApiUrl(environment) {
+  const env = environment || this.getEnvironment();
+
+  // Local for development OR testing; production otherwise. Mirrors
+  // @omega.js/backend's getApiUrl (N7): a resolved OMEGA_HTTPS_PORT means
+  // `mgr serve`'s mkcert proxy is up (https); otherwise plain http to the
+  // hosting emulator (env port, baked port, or classic 5002).
+  if (env === 'development' || env === 'testing') {
+    const httpsPort = localPort(this, 'OMEGA_HTTPS_PORT', 'https');
+    return httpsPort
+      ? `https://localhost:${httpsPort}`
+      : `http://localhost:${localPort(this, 'OMEGA_HOSTING_PORT', 'hosting') || 5002}`;
+  }
+
+  // Prod: api.<brand host>. Mirrors @omega.js/client.getApiUrl. Never derive
+  // from authDomain — it is an auth concern (the brand host, with /__/auth/*
+  // self-hosted at build time) and must stay free to change independently.
+  const brandUrl = this?.config?.brand?.url;
+  if (!brandUrl) {
+    throw new Error('brand.url not set in config/omega.json5');
+  }
+
+  return `https://api.${new URL(brandUrl).hostname}`;
+}
+
+// Marketing-site / brand website URL. Dev → the local website's whole ORIGIN, the
+// same answer @omega.js/client's getDevWebsiteOrigin() gives every other surface
+// whenever the website published one
+// ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)): the baked
+// `dev.origin` the live website published (scheme, host AND port, the complete
+// fact) wins, else a port from the usual chain (OMEGA_WEBSITE_PORT, then the baked
+// `dev.ports.website`) composed over https, else the classic dev origin. The scheme
+// is https because `omega dev` fronts its public port with the mkcert proxy by
+// default, so a port alone can never say it
+// ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)).
+// Prod → `config.brand.url`. Use this whenever app code wants to link out to "the
+// website" (Help → Website tray/menu items, "Open in browser," billing portal
+// landings) so dev runs don't punch out to the real domain.
+function getWebsiteUrl(environment) {
+  const env = environment || this.getEnvironment();
+
+  // Local for development OR testing; production otherwise.
+  if (env === 'development' || env === 'testing') {
+    const origin = this?.config?.dev?.origin;
+    if (origin) {
+      return origin;
+    }
+
+    const port = localPort(this, 'OMEGA_WEBSITE_PORT', 'website');
+    return port ? `https://localhost:${port}` : CLASSIC_DEV_ORIGIN;
+  }
+
+  const url = this?.config?.brand?.url;
+  if (!url) {
+    throw new Error('brand.url not set in config/omega.json5');
+  }
+  return url;
+}
+
+// Sign-in URL that round-trips an auth token back to the app. Points at the brand
+// website's /signin page (UJM), chained through its /token page so a successful login
+// mints a Firebase custom token and redirects to `<brand.id>://auth/token` — the
+// deep-link built-in that hands the token to client-bridge (signInWithCustomToken).
+// Same env split as getWebsiteUrl: dev/test → the local website, prod → brand.url.
+// The token page redirects with ?authToken=<token> — the ONE modern shape the
+// auth/token route reads (legacy-app formats are UJM's concern, not @omega.js/desktop's).
+//
+// `returnUrl` overrides the final hop (default: `<brand.id>://auth/token`). Used by
+// lib/auth-flow.js in dev, where the custom scheme isn't OS-registered — the flow
+// returns to a loopback HTTP listener instead (RFC 8252 §7.3).
+function getAuthUrl(environment, returnUrl) {
+  const site = this.getWebsiteUrl(environment);
+  const brandId = this?.config?.brand?.id;
+  if (!brandId) {
+    throw new Error('brand.id not set in config/omega.json5');
+  }
+
+  const tokenUrl = new URL('/token', site);
+  tokenUrl.searchParams.set('authReturnUrl', returnUrl || `${brandId}://auth/token`);
+
+  const signinUrl = new URL('/signin', site);
+  signinUrl.searchParams.set('authReturnUrl', tokenUrl.toString());
+  return signinUrl.toString();
+}
+
+// Mix the URL helpers into a Manager constructor's prototype + the constructor itself.
+// getEnvironment() is NOT attached here — it's the SSOT in src/utils/mode-helpers.js.
+// These helpers call `this.getEnvironment()`, so mode-helpers' attachTo() must run before
+// (or alongside) this one — every Manager entry point attaches mode-helpers first.
+function attachTo(Manager) {
+  Manager.prototype.getFunctionsUrl  = getFunctionsUrl;
+  Manager.prototype.getApiUrl        = getApiUrl;
+  Manager.prototype.getWebsiteUrl    = getWebsiteUrl;
+  Manager.prototype.getAuthUrl       = getAuthUrl;
+  Manager.getFunctionsUrl  = getFunctionsUrl;
+  Manager.getApiUrl        = getApiUrl;
+  Manager.getWebsiteUrl    = getWebsiteUrl;
+  Manager.getAuthUrl       = getAuthUrl;
+}
+
+module.exports = {
+  attachTo,
+  CLASSIC_DEV_ORIGIN,
+  localPort,
+  getFunctionsUrl,
+  getApiUrl,
+  getWebsiteUrl,
+  getAuthUrl,
+};

package/dist/vendor/account/engine.js

@@ -0,0 +1,182 @@
+/**
+ * Schema resolution engine — extracted verbatim from @omega.js/backend's
+ * src/manager/helpers/user.js, with ONE change: the '$uuid'/'$randomId'/'$apiKey'
+ * value generators are injected via ctx.generators instead of being required
+ * in-module. Hosts that can generate them (@omega.js/backend, Node) inject real generators;
+ * hosts that can't (@omega.js/client, browser) pass none and the fields resolve to
+ * null — the doc's real values always come from the backend.
+ *
+ * The engine is environment-agnostic: no dependencies, no Node APIs.
+ */
+
+/**
+ * Check if a schema node is a leaf field definition (has 'type' and 'default')
+ */
+function isLeaf(node) {
+  return node !== null
+    && typeof node === 'object'
+    && typeof node.type === 'string'
+    && 'default' in node;
+}
+
+/**
+ * Coerce a value to the expected type. Returns the coerced value or undefined if coercion fails.
+ */
+function coerce(value, type) {
+  if (typeof value === type) {
+    return value;
+  }
+
+  switch (type) {
+    case 'number': {
+      const n = Number(value);
+      return Number.isNaN(n) ? undefined : n;
+    }
+    case 'boolean': {
+      if (value === 'true' || value === 1) return true;
+      if (value === 'false' || value === 0) return false;
+      return Boolean(value);
+    }
+    case 'string': {
+      return String(value);
+    }
+    default: {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Resolve a single leaf field value
+ */
+function resolveLeaf(leaf, value, ctx) {
+  // Null handling
+  if (value === null) {
+    return leaf.nullable ? null : resolveDefault(leaf.default, ctx);
+  }
+
+  // Undefined → apply default
+  if (value === undefined) {
+    return resolveDefault(leaf.default, ctx);
+  }
+
+  // Array type — just check it's an array, don't coerce
+  if (leaf.type === 'array') {
+    return Array.isArray(value) ? value : resolveDefault(leaf.default, ctx);
+  }
+
+  // Type coercion
+  if (typeof value !== leaf.type) {
+    const coerced = coerce(value, leaf.type);
+    return coerced !== undefined ? coerced : resolveDefault(leaf.default, ctx);
+  }
+
+  return value;
+}
+
+/**
+ * Resolve a default value, handling special tokens
+ */
+function resolveDefault(def, ctx) {
+  if (typeof def !== 'string' || !def.startsWith('$')) {
+    // For arrays, return a fresh copy to avoid shared references
+    if (Array.isArray(def)) {
+      return [...def];
+    }
+    return def;
+  }
+
+  switch (def) {
+    case '$uuid':
+      return ctx.generators.uuid ? ctx.generators.uuid() : null;
+    case '$randomId':
+      return ctx.generators.randomId ? ctx.generators.randomId() : null;
+    case '$apiKey':
+      return ctx.generators.apiKey ? ctx.generators.apiKey() : null;
+    case '$oldDate':
+      return ctx.oldDate;
+    case '$oldDateUNIX':
+      return ctx.oldDateUNIX;
+    case '$now':
+      return ctx.now;
+    case '$nowUNIX':
+      return ctx.nowUNIX;
+    default:
+      return def;
+  }
+}
+
+/**
+ * Expand $timestamp shorthand into a schema branch
+ */
+function expandTimestamp(variant) {
+  const useNow = variant === '$timestamp:now';
+
+  return {
+    timestamp: { type: 'string', default: useNow ? '$now' : '$oldDate' },
+    timestampUNIX: { type: 'number', default: useNow ? '$nowUNIX' : 0 },
+  };
+}
+
+/**
+ * Recursively resolve a schema node against input data
+ */
+function resolve(schema, data, ctx) {
+  data = data || {};
+  const result = {};
+
+  // If $passthrough, start by copying all existing keys from data
+  const isPassthrough = schema.$passthrough === true;
+  const template = schema.$template || null;
+
+  if (isPassthrough) {
+    // Copy all data keys first (they'll be overwritten by defined schema fields below)
+    for (const key of Object.keys(data)) {
+      if (template && !key.startsWith('$') && !(key in schema)) {
+        // Dynamic key — resolve against template
+        result[key] = resolve(template, data[key], ctx);
+      } else if (!(key in schema) || key.startsWith('$')) {
+        // Unknown key not in schema — passthrough as-is
+        result[key] = data[key];
+      }
+    }
+  }
+
+  // Now resolve each defined schema field
+  for (const [key, node] of Object.entries(schema)) {
+    // Skip meta keys
+    if (key.startsWith('$')) {
+      continue;
+    }
+
+    // Handle string shorthands
+    if (typeof node === 'string') {
+      if (node === '$template') {
+        // Resolve against parent's $template
+        result[key] = resolve(template, data[key], ctx);
+        continue;
+      }
+      if (node.startsWith('$timestamp')) {
+        // Expand timestamp shorthand and recurse
+        result[key] = resolve(expandTimestamp(node), data[key], ctx);
+        continue;
+      }
+    }
+
+    // Leaf field
+    if (isLeaf(node)) {
+      result[key] = resolveLeaf(node, data[key], ctx);
+      continue;
+    }
+
+    // Nested branch (plain object)
+    if (node !== null && typeof node === 'object') {
+      result[key] = resolve(node, data[key], ctx);
+      continue;
+    }
+  }
+
+  return result;
+}
+
+module.exports = { resolve };