@aion0/forge 0.10.40 → 0.10.41

package/lib/connectors/test-runner.ts

@@ -223,6 +223,12 @@ async function runBrowserProbe(
       pluginId: def.id,
       host_match: expandedHost,
       login_redirect: expandedLoginRedirect,
+      // Optional DOM-based auth check for sites that don't redirect to
+      // /login when unauthed (e.g. PMDB renders the login form inline).
+      // Extension v0.2.15+ runs querySelector after navigation; match →
+      // probe fails with "login required". Older extensions ignore it
+      // and fall back to URL-only checking.
+      auth_required_selector: def.test?.auth_required_selector || undefined,
       runner: def.runner || entry?.runner || 'main',
       timeout_ms: def.test?.timeout_ms || 30_000,
     });
@@ -243,10 +249,22 @@ async function runBrowserProbe(
     return { ok: false, error: friendly, duration_ms: Date.now() - t0 };
   }
   const r = (value || {}) as { ok?: boolean; url?: string; error?: string };
+  // A bare `ok: true` is not enough: an older extension navigates to
+  // host_match, hits a DNS / TCP failure (Chrome shows chrome-error://),
+  // then reports back without realising the request actually failed. We
+  // require the final URL to (a) exist and (b) not be a Chrome error
+  // page before treating the probe as successful.
+  const failedNetwork = !r.url || r.url.startsWith('chrome-error://') || r.url.startsWith('about:');
+  const succeeded = !!r.ok && !failedNetwork;
   return {
-    ok: !!r.ok,
-    message: r.ok ? `Session active${r.url ? ` · ${r.url}` : ''}` : undefined,
-    error: r.ok ? undefined : (r.error || 'login required'),
+    ok: succeeded,
+    message: succeeded ? `Session active${r.url ? ` · ${r.url}` : ''}` : undefined,
+    error: succeeded
+      ? undefined
+      : (r.error
+        || (failedNetwork
+          ? `Network unreachable — extension reached ${r.url || '(no url)'}. VPN / hostname / firewall?`
+          : 'login required')),
     url: r.url,
     duration_ms: Date.now() - t0,
   };

package/lib/connectors/types.ts

@@ -456,9 +456,19 @@ export interface ConnectorTest {
   body_match_error?: string;
 
   // ── probe: 'browser' ─────────────────────────────────────
-  // No fields required — the extension reuses the connector's
-  // top-level host_match + login_redirect (1:1) or the first entry's
-  // (1:N) to find the tab and detect login redirects.
+  // Extension reuses the connector's top-level host_match +
+  // login_redirect (1:1) or the first entry's (1:N) to navigate
+  // and detect login redirects.
+  /**
+   * CSS selector that, if present on the loaded page, indicates the
+   * user is NOT logged in (e.g. `form#login`, `a[href*="/sign_in"]`).
+   * Used by sites that render a login form inline instead of
+   * redirecting to `/login` — without this, the URL-based probe
+   * passes even when the user can't see real content. Extension v0.2.15+
+   * runs `document.querySelector(selector)` after navigation; non-null
+   * match → probe fails with "login required".
+   */
+  auth_required_selector?: string;
 
   /** Override the default timeout (http: 15s, browser: 30s). */
   timeout_ms?: number;
@@ -568,9 +578,31 @@ export interface ConnectorMarketEntry {
   compatible: boolean;
   /**
    * Where this entry originates:
-   *   'registry' — listed in the remote registry (may also be installed)
+   *   'registry' — listed in a remote registry (may also be installed)
    *   'local'    — installed via /api/connectors/install-local, no
    *                registry counterpart (no Update path)
    */
   source: 'registry' | 'local';
+  /**
+   * Which registry source provided the winning entry. `public` = the
+   * default forge-connectors repo; `enterprise-<tenant>` = a private
+   * enterprise repo. Absent for `source: 'local'`. UI uses this for
+   * the source badge (e.g. `🔒 Fortinet`).
+   */
+  source_id?: string;
+  /**
+   * When `update_available` is true, this is the source that *publishes*
+   * the new version (the winning registry entry). Often differs from
+   * source_id, which reflects the *installed* manifest's origin — e.g.
+   * installed from public, enterprise just added with a newer version.
+   * UI uses this to show "Update from enterprise-fortinet" so users
+   * know what they're about to pull before they click.
+   */
+  update_source_id?: string;
+  /**
+   * Other sources that also list this id but were outranked. Surfaced
+   * in the marketplace detail view so users can see "this `mantis`
+   * comes from fortinet — public also has one (hidden)".
+   */
+  hidden_sources?: { source_id: string; display_name: string; version: string }[];
 }

package/lib/connectors/wizard-template.ts

@@ -0,0 +1,161 @@
+/**
+ * Wizard template resolution — picks the right onboarding template
+ * JSON for the current Forge instance.
+ *
+ * Priority (highest wins):
+ *
+ *   1. User-uploaded override at <dataDir>/config-template.json — admin
+ *      explicitly pasted a custom template via the import API; that
+ *      always wins.
+ *   2. Enterprise sources, in configured priority order. Each enterprise
+ *      registry.json may declare a `wizard_template` path; sync caches
+ *      the resolved JSON alongside the registry (P1.W3). First enterprise
+ *      source that has a cached template wins.
+ *   3. Public source. forge-connectors registry.json may declare a public
+ *      default (P1.W6 seeds this).
+ *   4. Bundled fallback shipped inside Forge main (templates/
+ *      connector-config-template.json). Callers JSON-import that
+ *      directly — this module deliberately doesn't, so the bundled file
+ *      stays a passive last-line-of-defence the caller owns.
+ *
+ * The returned `source` tag lets callers display a "using template from
+ * Fortinet" affordance in the wizard, or log which tier resolved.
+ *
+ * No network — every read is from a per-source cache file the sync
+ * layer wrote on its last successful pull. Returns `null` for tiers 1–3
+ * when nothing is cached, leaving the caller free to fall through to
+ * its bundled default.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '../dirs';
+import { listEnterpriseSourceMetas } from './sync';
+
+export interface ResolvedWizardTemplate {
+  /** `'user' | 'enterprise-<tenant_id>' | 'public'`. `'bundled'` is the caller's responsibility. */
+  source: string;
+  template: unknown;
+}
+
+function userOverridePath(): string {
+  return join(getDataDir(), 'config-template.json');
+}
+
+function sourceTemplatePath(sourceId: string): string {
+  return join(getDataDir(), 'connectors', 'sources', sourceId, 'wizard-template.json');
+}
+
+function sourceDeptPath(sourceId: string, deptId: string): string {
+  return join(getDataDir(), 'connectors', 'sources', sourceId, 'wizards', `${deptId}.json`);
+}
+
+function sourceDeptIndexFile(sourceId: string): string {
+  return join(getDataDir(), 'connectors', 'sources', sourceId, 'wizards', '_index.json');
+}
+
+export interface DeptInfo {
+  id: string;
+  display_name: string;
+  /** False when the dept exists in the registry without a `path` — the
+   *  user can still pick it as their department, but template
+   *  customization falls through to public/bundled defaults. */
+  has_template: boolean;
+}
+
+/**
+ * Return the list of department templates cached for a source, or [] if
+ * the source has only a single (non-dept-aware) template. The index is
+ * written by sync.ts when the source's registry advertises
+ * `wizard_templates: [...]`.
+ */
+export function listSourceDepartments(sourceId: string): DeptInfo[] {
+  const idx = readJsonOrNull(sourceDeptIndexFile(sourceId));
+  if (Array.isArray(idx)) {
+    return idx
+      .filter((d: any) => d && typeof d.id === 'string')
+      .map((d: any) => ({
+        id: d.id,
+        display_name: d.display_name || d.id,
+        // Legacy index entries (pre template-less) had no `has_template`
+        // — assume true so existing caches keep behaving as before.
+        has_template: d.has_template !== false,
+      }));
+  }
+  return [];
+}
+
+function readJsonOrNull(path: string): unknown | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the wizard template across all priority tiers. Returns
+ * `null` if no tier above the bundled fallback has anything — callers
+ * are expected to drop to their statically-imported bundled JSON in
+ * that case.
+ *
+ * When `sourceId` is given, bypass the priority chain and read ONLY
+ * that source's cached template. Used by the per-tenant wizard flow
+ * (E2): the UI passes `?source_id=enterprise-fortinet` to scope to a
+ * specific tenant instead of resolving across all of them. Returns
+ * `null` if the named source has no cached template (caller decides
+ * whether to fall back or surface a "not synced yet" error).
+ */
+export function resolveWizardTemplate(sourceId?: string, deptId?: string): ResolvedWizardTemplate | null {
+  if (sourceId) {
+    if (sourceId === 'user') {
+      const user = readJsonOrNull(userOverridePath());
+      return user ? { source: 'user', template: user } : null;
+    }
+    // E3: dept-scoped lookup. When `deptId` is given, read the per-dept
+    // file. When omitted, prefer the dept index's first entry (so
+    // sources that ship only dept templates still resolve a sensible
+    // default), then fall back to the legacy single template.
+    if (deptId) {
+      const t = readJsonOrNull(sourceDeptPath(sourceId, deptId));
+      return t ? { source: sourceId, template: t } : null;
+    }
+    const depts = listSourceDepartments(sourceId);
+    if (depts.length > 0) {
+      const first = readJsonOrNull(sourceDeptPath(sourceId, depts[0].id));
+      if (first) return { source: sourceId, template: first };
+    }
+    const t = readJsonOrNull(sourceTemplatePath(sourceId));
+    return t ? { source: sourceId, template: t } : null;
+  }
+
+  // Tier 1 — user override
+  const user = readJsonOrNull(userOverridePath());
+  if (user) return { source: 'user', template: user };
+
+  // Tier 2 — enterprise sources, priority order. Each source may ship
+  // either the legacy single wizard-template.json or the E3 multi-dept
+  // wizards/ tree; both shapes count as "has a template" for this tier.
+  for (const source of listEnterpriseSourceMetas()) {
+    const depts = listSourceDepartments(source.id);
+    if (depts.length > 0) {
+      const first = readJsonOrNull(sourceDeptPath(source.id, depts[0].id));
+      if (first) return { source: source.id, template: first };
+    }
+    const t = readJsonOrNull(sourceTemplatePath(source.id));
+    if (t) return { source: source.id, template: t };
+  }
+
+  // Tier 3 — public source cache (same dual-shape lookup).
+  const publicDepts = listSourceDepartments('public');
+  if (publicDepts.length > 0) {
+    const first = readJsonOrNull(sourceDeptPath('public', publicDepts[0].id));
+    if (first) return { source: 'public', template: first };
+  }
+  const publicT = readJsonOrNull(sourceTemplatePath('public'));
+  if (publicT) return { source: 'public', template: publicT };
+
+  // Tier 4 — caller falls back to bundled
+  return null;
+}

package/lib/dirs.ts

@@ -85,6 +85,11 @@ export function migrateDataDir(): void {
   console.log('[forge] Migration complete. Old files kept as backup.');
 }
 
+/** Encrypted enterprise keys file — array of { tenant_id, repo_url, github_pat } */
+export function getEnterpriseKeysPath(): string {
+  return join(getDataDir(), '.enterprise-keys.json');
+}
+
 /** Claude config directory — skills, commands, sessions, etc. Override
  *  via the `CLAUDE_HOME` env var (same name claude CLI uses); defaults
  *  to `~/.claude`. The settings.yaml `claudeHome` field was removed in

package/lib/enterprise-known.ts

@@ -0,0 +1,34 @@
+/**
+ * Hard-coded mapping: tenant_id → enterprise repo URL.
+ *
+ * Short enterprise keys look like `<tenant_id>:<github_pat>` (e.g.
+ * `fortinet:github_pat_xxx`). The tenant_id is the lowercase company
+ * name itself — same string is used as the symmetric key for any
+ * `ent:…` secrets the template ships (see lib/enterprise-secret.ts).
+ * Keeping one name means there's nothing for users to look up.
+ *
+ * Long form (`<github_pat>@<repo_url>`) bypasses this table and is the
+ * escape hatch for ad-hoc / unregistered tenants.
+ *
+ * Adding a new tenant requires bumping Forge — that is intentional: it
+ * keeps the list of "blessed" enterprise repos small and reviewable.
+ * A future resolver service (design §1) can replace this if needed.
+ */
+
+export interface KnownTenant {
+  tenant_id: string;
+  display_name: string;
+  repo_url: string;
+}
+
+export const KNOWN_TENANTS: Record<string, KnownTenant> = {
+  fortinet: {
+    tenant_id: 'fortinet',
+    display_name: 'Fortinet',
+    repo_url: 'github.com/aiwatching/forge-enterprise-agent-fortinet',
+  },
+};
+
+export function lookupTenant(tenant_id: string): KnownTenant | null {
+  return KNOWN_TENANTS[tenant_id.toLowerCase()] || null;
+}

package/lib/enterprise-secret.ts

@@ -0,0 +1,87 @@
+/**
+ * Enterprise secret obfuscation — light symmetric crypto for tokens
+ * that need to live in an enterprise repo's wizard template (which
+ * ships through git) without sitting in plaintext for casual scrapers.
+ *
+ * This is OBFUSCATION, not real security. The key is derived purely
+ * from the enterprise name (`fortinet`, `acme`, …), so anyone with
+ * the algorithm and the company name can decrypt — but a clone of
+ * the repo on its own gives nothing useful.
+ *
+ * Threat model:
+ *   ✓ Github web-scraper / search bot grabs the repo. They see
+ *     `ent:…` blobs; without knowing the algo + tenant name, the
+ *     token doesn't fall out.
+ *   ✓ Casual leak (someone posts the template content on Slack).
+ *     Plaintext token doesn't appear in the paste.
+ *   ✗ Determined attacker who knows this is Fortinet's repo and runs
+ *     the decryption with key='fortinet'. They get the token.
+ *
+ * For real secrets that must survive a determined attacker, prompt
+ * the user instead (`_prompts` block) and let Forge encrypt locally
+ * with the per-instance `.encrypt-key`.
+ *
+ * Format: `ent:<iv-base64>.<tag-base64>.<ciphertext-base64>`
+ * Algorithm: AES-256-GCM, key = SHA-256(enterpriseName.toLowerCase().trim())
+ */
+
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+
+const PREFIX = 'ent:';
+
+function deriveKey(enterpriseName: string): Buffer {
+  return createHash('sha256').update(enterpriseName.toLowerCase().trim()).digest();
+}
+
+export function isEnterpriseSecret(value: unknown): value is string {
+  return typeof value === 'string' && value.startsWith(PREFIX);
+}
+
+export function encryptForEnterprise(plaintext: string, enterpriseName: string): string {
+  if (!plaintext) return '';
+  const key = deriveKey(enterpriseName);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const enc = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${PREFIX}${iv.toString('base64')}.${tag.toString('base64')}.${enc.toString('base64')}`;
+}
+
+export function decryptForEnterprise(blob: string, enterpriseName: string): string {
+  if (!isEnterpriseSecret(blob)) return blob;
+  try {
+    const payload = blob.slice(PREFIX.length);
+    const [ivB64, tagB64, encB64] = payload.split('.');
+    if (!ivB64 || !tagB64 || !encB64) return '';
+    const key = deriveKey(enterpriseName);
+    const iv = Buffer.from(ivB64, 'base64');
+    const tag = Buffer.from(tagB64, 'base64');
+    const data = Buffer.from(encB64, 'base64');
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf-8');
+  } catch {
+    // Wrong key → auth tag mismatch → throws. Treat as "couldn't decrypt"
+    // and return empty so callers don't silently use a garbage value.
+    return '';
+  }
+}
+
+/**
+ * Walk an arbitrary JSON value, decrypting any string that looks like
+ * an `ent:…` blob. Non-strings + non-blobs pass through unchanged.
+ * Useful for the wizard-import path — apply this to the resolved
+ * template before merging into settings.
+ */
+export function decryptDeep(value: unknown, enterpriseName: string): unknown {
+  if (isEnterpriseSecret(value)) return decryptForEnterprise(value, enterpriseName);
+  if (Array.isArray(value)) return value.map((v) => decryptDeep(v, enterpriseName));
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = decryptDeep(v, enterpriseName);
+    }
+    return out;
+  }
+  return value;
+}

package/lib/enterprise.ts

@@ -0,0 +1,208 @@
+/**
+ * Enterprise key parsing — turn an array of opaque key strings into a
+ * structured list of marketplace sources for sync / registry to consume.
+ *
+ * Two key formats:
+ *   short:  `<tenant_id>:<github_pat>`      → looked up via KNOWN_TENANTS
+ *   long:   `<github_pat>@<repo_url>`       → tenant_id derived from repo
+ *
+ * Pure parsing — does no I/O. Persistence lives in lib/settings.ts; HTTP
+ * lives in lib/connectors/sync.ts.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { lookupTenant } from './enterprise-known';
+import { encryptSecret, decryptSecret, isEncrypted } from './crypto';
+import { getEnterpriseKeysPath } from './dirs';
+
+export interface EnterpriseSource {
+  tenant_id: string;
+  display_name: string;
+  repo_url: string;
+  github_pat: string;
+  priority: number;
+}
+
+export interface ParseResult {
+  sources: EnterpriseSource[];
+  errors: { key_preview: string; reason: string }[];
+}
+
+const SHORT_RE = /^([a-z0-9_-]+):(.+)$/i;
+const LONG_RE = /^(.+)@(github\.com\/[A-Za-z0-9_.\/-]+)$/;
+
+function preview(key: string): string {
+  if (key.length <= 12) return key.slice(0, 4) + '…';
+  return key.slice(0, 6) + '…' + key.slice(-4);
+}
+
+export function parseKey(key: string, priority: number): EnterpriseSource | { error: string } {
+  const trimmed = key.trim();
+  if (!trimmed) return { error: 'empty' };
+
+  const longMatch = trimmed.match(LONG_RE);
+  if (longMatch) {
+    const [, pat, repo_url] = longMatch;
+    const tenant_id = deriveTenantFromRepo(repo_url);
+    return {
+      tenant_id,
+      display_name: tenant_id,
+      repo_url,
+      github_pat: pat,
+      priority,
+    };
+  }
+
+  const shortMatch = trimmed.match(SHORT_RE);
+  if (shortMatch) {
+    const [, tenant_id, pat] = shortMatch;
+    const known = lookupTenant(tenant_id);
+    if (!known) {
+      return { error: `unknown tenant '${tenant_id}' — use long form '<pat>@<repo_url>' or update KNOWN_TENANTS` };
+    }
+    return {
+      tenant_id: known.tenant_id,
+      display_name: known.display_name,
+      repo_url: known.repo_url,
+      github_pat: pat,
+      priority,
+    };
+  }
+
+  return { error: 'unrecognized format — expected `<tenant>:<pat>` or `<pat>@<repo_url>`' };
+}
+
+export function parseKeys(keys: string[]): ParseResult {
+  const sources: EnterpriseSource[] = [];
+  const errors: ParseResult['errors'] = [];
+  const seenTenants = new Set<string>();
+
+  keys.forEach((key, idx) => {
+    const result = parseKey(key, idx);
+    if ('error' in result) {
+      errors.push({ key_preview: preview(key), reason: result.error });
+      return;
+    }
+    // Defensive dedup: even if `.enterprise-keys.json` somehow has two
+    // entries for the same tenant (e.g. legacy pre-dedup persist), the
+    // marketplace still surfaces only one source. Earlier index wins
+    // — matches how priority works for non-dup tenants.
+    if (seenTenants.has(result.tenant_id)) return;
+    seenTenants.add(result.tenant_id);
+    sources.push(result);
+  });
+
+  return { sources, errors };
+}
+
+function deriveTenantFromRepo(repo_url: string): string {
+  const parts = repo_url.split('/');
+  const last = parts[parts.length - 1] || 'unknown';
+  const m = last.match(/forge-enterprise-agent-(.+)/);
+  return m ? m[1] : last;
+}
+
+// ───────────────────────── persistence ─────────────────────────
+// Keys are stored as an encrypted JSON array at <dataDir>/.enterprise-keys.json.
+// The on-disk shape is { v: 1, keys: ["enc:...", "enc:..."] } so we can
+// rotate the encryption format later without breaking existing files.
+
+interface KeyFile {
+  v: 1;
+  keys: string[];  // each entry is encryptSecret(rawKey)
+}
+
+function readKeyFile(): KeyFile {
+  const path = getEnterpriseKeysPath();
+  if (!existsSync(path)) return { v: 1, keys: [] };
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.keys)) return { v: 1, keys: [] };
+    return { v: 1, keys: parsed.keys };
+  } catch {
+    return { v: 1, keys: [] };
+  }
+}
+
+function writeKeyFile(file: KeyFile): void {
+  const path = getEnterpriseKeysPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
+}
+
+/** Return raw key strings (decrypted) in priority order. */
+export function getEnterpriseKeys(): string[] {
+  const file = readKeyFile();
+  return file.keys.map(k => isEncrypted(k) ? decryptSecret(k) : k).filter(Boolean);
+}
+
+/** Replace the full key list. Order = priority (index 0 = highest). */
+export function setEnterpriseKeys(rawKeys: string[]): void {
+  const file: KeyFile = {
+    v: 1,
+    keys: rawKeys.filter(k => k && k.trim()).map(k => encryptSecret(k.trim())),
+  };
+  writeKeyFile(file);
+}
+
+/** Append a key (returns false if a key with the same tenant_id already exists). */
+export function addEnterpriseKey(rawKey: string): { ok: true; tenant_id: string } | { ok: false; reason: string } {
+  const parsed = parseKey(rawKey, 0);
+  if ('error' in parsed) return { ok: false, reason: parsed.error };
+
+  const existing = getEnterpriseKeys();
+  const existingSources = parseKeys(existing).sources;
+  if (existingSources.some(s => s.tenant_id === parsed.tenant_id)) {
+    return { ok: false, reason: `tenant '${parsed.tenant_id}' already configured — remove it first` };
+  }
+
+  setEnterpriseKeys([...existing, rawKey]);
+  return { ok: true, tenant_id: parsed.tenant_id };
+}
+
+/**
+ * Replace the key for a tenant_id with a new raw key. The new key's
+ * parsed tenant_id must match the target (otherwise it's an add, not an
+ * update — callers should remove+add explicitly).
+ */
+export function updateEnterpriseKey(
+  tenant_id: string,
+  rawKey: string,
+): { ok: true } | { ok: false; reason: string } {
+  const parsed = parseKey(rawKey, 0);
+  if ('error' in parsed) return { ok: false, reason: parsed.error };
+  if (parsed.tenant_id !== tenant_id) {
+    return { ok: false, reason: `key resolves to tenant '${parsed.tenant_id}', not '${tenant_id}' — remove the existing key first` };
+  }
+  const existing = getEnterpriseKeys();
+  let found = false;
+  const next = existing.map(k => {
+    const r = parseKey(k, 0);
+    if ('error' in r || r.tenant_id !== tenant_id) return k;
+    found = true;
+    return rawKey;
+  });
+  if (!found) return { ok: false, reason: `no key for tenant '${tenant_id}'` };
+  setEnterpriseKeys(next);
+  return { ok: true };
+}
+
+/** Remove all keys for a tenant_id. Returns true if anything was removed. */
+export function removeEnterpriseKey(tenant_id: string): boolean {
+  const existing = getEnterpriseKeys();
+  const filtered = existing.filter(k => {
+    const r = parseKey(k, 0);
+    return 'error' in r ? true : r.tenant_id !== tenant_id;
+  });
+  if (filtered.length === existing.length) return false;
+  setEnterpriseKeys(filtered);
+  return true;
+}
+
+/** Convenience: parsed + ordered source list for sync / registry to consume. */
+export function listEnterpriseSources(): EnterpriseSource[] {
+  return parseKeys(getEnterpriseKeys()).sources;
+}

package/lib/help-docs/00-overview.md

@@ -30,6 +30,18 @@ forge server start
 
 Open `http://localhost:8403`. First launch prompts you to set an admin password.
 
+### Optional — enterprise marketplace at install time
+
+Forge users inside a company that publishes its own connectors / pipelines through a private GitHub repo (an "enterprise marketplace") can register the key at install:
+
+```bash
+./install.sh --enterprise-key=<tenant>:<github_pat>
+# or multiple
+./install.sh --enterprise-key=fortinet:pat_xxx --enterprise-key=acme:pat_yyy
+```
+
+Equivalently, do it any time afterwards via `forge --add-enterprise-key --enterprise-key=...`, or paste the key into Forge chat ("here's our enterprise key: …"). See `01-settings.md` for the full picture.
+
 ## Requirements
 - Node.js >= 20
 - tmux (`brew install tmux` on macOS)

package/lib/help-docs/01-settings.md

@@ -196,7 +196,52 @@ Provider → adapter mapping for chat:
 
 ## Encrypted Fields
 
-`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. Agent profile `apiKey` fields are also encrypted. The encryption key is stored at `~/.forge/data/.encrypt-key`.
+`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. Agent profile `apiKey` fields are also encrypted. Enterprise marketplace keys (see below) live in `<dataDir>/.enterprise-keys.json` and are encrypted with the same key. The encryption key is stored at `~/.forge/data/.encrypt-key`.
+
+## Marketplace Providers (enterprise keys)
+
+Forge's connector + workflow marketplaces are layered. The default `forge-connectors` / `forge-workflow` repos are everyone's baseline; on top of those you can register one or more **enterprise repos** that override matching ids with company-specific versions and add private ones. This is opt-in — without any keys, you see only the public catalog.
+
+### Key formats
+
+- **Short** — `<tenant_id>:<github_pat>` (e.g. `fortinet:github_pat_xxxxx`). The tenant short code is resolved to a known enterprise repo URL via `lib/enterprise-known.ts`.
+- **Long** — `<github_pat>@<repo_url>` (e.g. `github_pat_xxxxx@github.com/myorg/forge-enterprise-agent-foo`). Escape hatch for tenants not in the known list.
+
+The PAT must be a GitHub **Fine-grained Personal Access Token** scoped to the enterprise repo with `Contents: Read`.
+
+### How to register
+
+Three equivalent paths — pick whichever fits the moment:
+
+```bash
+# A) at install time
+./install.sh --enterprise-key=fortinet:github_pat_xxxxx
+
+# B) one-shot from the CLI (persist + exit, no server start)
+forge --add-enterprise-key --enterprise-key=fortinet:github_pat_xxxxx
+
+# C) inside Forge chat — paste the key, the assistant calls add_enterprise_key
+```
+
+After registration:
+
+- The connector + workflow marketplaces auto-sync once so the new source appears immediately.
+- The Marketplace UI shows a `🔒 <tenant>` badge on every connector/pipeline sourced from this repo; the detail pane's "Sources" section lists the winning source plus any lower-priority sources that were outranked.
+- The Dashboard top nav shows `🔒 <tenant>` so you always know which enterprise overlays are active.
+
+### Manage via Settings → Marketplace Providers
+
+The Settings modal section lists every configured source with its priority + masked PAT preview. Add a new key, remove an existing one, or see what's loaded. Removing a source keeps already-installed connectors/workflows on disk (so you don't lose work) — they just stop receiving updates from that source.
+
+### Priority rules
+
+- Sources are ordered by registration sequence; the first key added wins on conflict.
+- For each id (e.g. `mantis`), the highest-priority source providing it is "in use"; lower sources land in `hidden_sources` (visible in the marketplace detail page).
+- A `connector-config-template.json` (onboarding wizard pre-fills) is also resolved across sources — user-uploaded at `<dataDir>/config-template.json` first, then enterprise sources by priority, then public, then the Forge-bundled fallback.
+
+### What stays out of public
+
+Fortinet-internal connectors (`nac`, `fortincm`, `tp`, `scap`, `pmdb`), Fortinet-flavored pipelines (`fortinet-*`), and the Fortinet wizard template live only in the private `forge-enterprise-agent-fortinet` repo. Public `forge-connectors` keeps generic versions of `gitlab` / `mantis` / `blackduck` etc. with empty `base_url` defaults.
 
 ## Settings UI
 
@@ -208,6 +253,7 @@ The Settings modal has these sections:
 | **Document Roots** | Markdown/Obsidian vault paths |
 | **Agents** | Detected CLI agents + configuration |
 | **Profiles** | Agent profiles (CLI + API) — API profiles also power Forge chat |
+| **Marketplace Providers** | Enterprise marketplace keys — add/remove tenants whose private connector + pipeline + wizard repos overlay on top of public |
 | **Memory (Temper)** | Long-term memory backend for the chat agent. When Temper URL+key are blank, chat falls back to a local SQLite store with the same block/episode tools (keyword search only — no semantic/graph search). |
 | **Chat backend** | Pick the default API profile for chat (extension / CLI / Telegram) |
 | **Telegram** | Bot token, chat ID, notification toggles |