@bevel-software/platform-core-backend 0.1.0

package/src/shared/__tests__/frontmatter-id.test.ts

@@ -0,0 +1,88 @@
+import { describe, test, expect, vi } from 'vitest';
+import {
+  extractFrontmatter,
+  extractFrontmatterId,
+  resolveDeclaredId,
+  isValidId,
+  dedupeById,
+} from '../frontmatter-id.js';
+import { setFrontmatterField } from '@bevel-software/platform-shared';
+
+describe('extractFrontmatter', () => {
+  test('splits a leading --- block from the body', () => {
+    const r = extractFrontmatter('---\nid: foo\n---\ntype: http\n');
+    expect(r).toEqual({ frontmatter: 'id: foo', body: 'type: http\n' });
+  });
+  test('null when there is no fence', () => {
+    expect(extractFrontmatter('type: http')).toBeNull();
+  });
+});
+
+describe('extractFrontmatterId', () => {
+  test('reads a legacy kebab id from frontmatter', () => {
+    expect(extractFrontmatterId('---\nid: foo-bar\n---\n# x')).toBe('foo-bar');
+  });
+  test('null with no fence or no id', () => {
+    expect(extractFrontmatterId('# heading')).toBeNull();
+    expect(extractFrontmatterId('---\nnodeType: "[T](T.md)"\n---\n# x')).toBeNull();
+  });
+});
+
+describe('resolveDeclaredId', () => {
+  test('id wins over name, name over fallback', () => {
+    expect(resolveDeclaredId({ id: 'the_id', name: 'The Name' }, 'file')).toBe('the_id');
+    expect(resolveDeclaredId({ name: 'the_name' }, 'file')).toBe('the_name');
+    expect(resolveDeclaredId({}, 'file')).toBe('file');
+    expect(resolveDeclaredId({ id: '   ' }, 'file')).toBe('file'); // blank id ignored
+  });
+});
+
+describe('isValidId', () => {
+  test('accepts lowercase snake_case, rejects hyphens/uppercase/leading underscore', () => {
+    for (const ok of ['a', 'my_tool', 'weather1', 'a_b_c']) expect(isValidId(ok)).toBe(true);
+    for (const bad of ['a-b', 'My_Tool', '_x', '', 'a b']) expect(isValidId(bad)).toBe(false);
+  });
+});
+
+describe('dedupeById', () => {
+  test('keeps the first, refuses later duplicates and reports them', () => {
+    const onDup = vi.fn();
+    const items = [
+      { id: 'a', at: 1 },
+      { id: 'b', at: 2 },
+      { id: 'a', at: 3 }, // duplicate
+    ];
+    const out = dedupeById(items, (x) => x.id, (x, id) => onDup(id, x.at));
+    expect(out.map((x) => x.at)).toEqual([1, 2]); // first `a` kept, second dropped
+    expect(onDup).toHaveBeenCalledWith('a', 3);
+  });
+});
+
+describe('setFrontmatterField (shared, line-based)', () => {
+  test('replaces an existing key, leaving every other line byte-identical', () => {
+    const node = '---\nnodeType: "[Thing](../NodeTypes/Thing.md)"\nid: "old-id"\nwrite:\n  - Product Team\n---\n\n# Name\nFoo\n';
+    const out = setFrontmatterField(node, 'id', 'old-id2');
+    expect(out).toBe('---\nnodeType: "[Thing](../NodeTypes/Thing.md)"\nid: old-id2\nwrite:\n  - Product Team\n---\n\n# Name\nFoo\n');
+  });
+
+  test('inserts a missing key at the top of an existing block', () => {
+    const out = setFrontmatterField('---\nname: weather\n---\n{"type":"http"}\n', 'id', 'weather2');
+    expect(out).toBe('---\nid: weather2\nname: weather\n---\n{"type":"http"}\n');
+  });
+
+  test('creates a frontmatter block when the file has none', () => {
+    const out = setFrontmatterField('{"type":"http","url":"https://x/m"}', 'id', 'tool_x');
+    expect(out).toBe('---\nid: tool_x\n---\n{"type":"http","url":"https://x/m"}');
+  });
+
+  test('does not touch a same-named key in the BODY', () => {
+    const out = setFrontmatterField('---\nid: a\n---\nid: body-line stays\n', 'id', 'b');
+    expect(out).toBe('---\nid: b\n---\nid: body-line stays\n');
+  });
+
+  test("preserves a CRLF file's line endings byte-for-byte", () => {
+    const crlf = '---\r\nid: a\r\nname: keep\r\n---\r\nbody line\r\n';
+    const out = setFrontmatterField(crlf, 'id', 'b');
+    expect(out).toBe('---\r\nid: b\r\nname: keep\r\n---\r\nbody line\r\n');
+  });
+});

package/src/shared/__tests__/fs-walk.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { walkFiles } from '../fs-walk.js';
+
+describe('walkFiles', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'fs-walk-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('returns [] for a missing root', async () => {
+    expect(await walkFiles(path.join(root, 'nope'), () => true)).toEqual([]);
+  });
+
+  it('walks nested directories, filters by basename, and sorts the result', async () => {
+    await fs.mkdir(path.join(root, 'b/deep'), { recursive: true });
+    await fs.mkdir(path.join(root, 'a'), { recursive: true });
+    await fs.writeFile(path.join(root, 'b/deep/z.tool'), '');
+    await fs.writeFile(path.join(root, 'a/y.tool'), '');
+    await fs.writeFile(path.join(root, 'a/skip.md'), '');
+    await fs.writeFile(path.join(root, 'x.tool'), '');
+
+    const found = await walkFiles(root, (n) => n.endsWith('.tool'));
+    // Relative `/`-separated paths, sorted, only matching basenames.
+    expect(found).toEqual(['a/y.tool', 'b/deep/z.tool', 'x.tool']);
+  });
+
+  it('skips dot-prefixed entries — files AND whole directories (.git)', async () => {
+    await fs.mkdir(path.join(root, '.git/objects'), { recursive: true });
+    await fs.writeFile(path.join(root, '.git/objects/a.tool'), '');
+    await fs.writeFile(path.join(root, '.hidden.tool'), '');
+    await fs.writeFile(path.join(root, 'visible.tool'), '');
+
+    expect(await walkFiles(root, (n) => n.endsWith('.tool'))).toEqual(['visible.tool']);
+  });
+});

package/src/shared/__tests__/ssrf.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from 'vitest';
+import { isBlockedHost, assertSafeFetchUrl } from '../ssrf.js';
+
+describe('isBlockedHost', () => {
+  test('blocks loopback / private / link-local / metadata', () => {
+    for (const h of [
+      'localhost', 'app.localhost', 'localhost.', '127.0.0.1', '0.0.0.0', '10.1.2.3', '192.168.1.1',
+      '172.16.0.1', '169.254.169.254', '::1', '::', 'fe80::1', 'fe90::1', 'fc00::1', '::ffff:127.0.0.1',
+      // CGNAT 100.64.0.0/10 — includes Alibaba Cloud's metadata endpoint.
+      '100.64.0.1', '100.100.100.200', '100.127.255.255',
+    ]) {
+      expect(isBlockedHost(h)).toBe(true);
+    }
+  });
+
+  test('allows public hosts (incl. lookalikes)', () => {
+    for (const h of ['api.example.com', 'github.com', 'fc.example.org', '8.8.8.8', '172.15.0.1', '172.32.0.1', '100.63.255.255', '100.128.0.1']) {
+      expect(isBlockedHost(h)).toBe(false);
+    }
+  });
+
+  test('blocks IPv4-mapped IPv6 in the hex form new URL canonicalizes to', () => {
+    // `new URL('http://[::ffff:169.254.169.254]/').hostname` === '[::ffff:a9fe:a9fe]'
+    // — the mapped v4 is emitted as hex hextets, not dotted, so the guard must
+    // decode the hex mapping and not just match a dotted tail.
+    for (const h of ['[::ffff:a9fe:a9fe]', '::ffff:a9fe:a9fe', '::ffff:7f00:1', '::ffff:a00:1', '::ffff:c0a8:1']) {
+      expect(isBlockedHost(h)).toBe(true);
+    }
+    // A public address in the same mapped-hex form stays allowed (8.8.8.8 → 0808:0808).
+    expect(isBlockedHost('::ffff:808:808')).toBe(false);
+  });
+});
+
+describe('assertSafeFetchUrl', () => {
+  test('accepts a public https URL', () => {
+    expect(() => assertSafeFetchUrl('https://api.example.com/token', { requireHttps: true })).not.toThrow();
+  });
+
+  test('rejects http when https is required', () => {
+    expect(() => assertSafeFetchUrl('http://api.example.com/token', { requireHttps: true })).toThrow(/https/);
+  });
+
+  test('rejects internal/metadata hosts (SSRF)', () => {
+    expect(() => assertSafeFetchUrl('https://169.254.169.254/latest/meta-data/', { requireHttps: true })).toThrow(
+      /not allowed/,
+    );
+    expect(() => assertSafeFetchUrl('https://localhost:8080/token', { requireHttps: true })).toThrow(/not allowed/);
+  });
+
+  test('rejects a non-URL', () => {
+    expect(() => assertSafeFetchUrl('not a url')).toThrow(/valid URL/);
+  });
+});

package/src/shared/__tests__/utcp-namespace.test.ts

@@ -0,0 +1,19 @@
+import { describe, test, expect } from 'vitest';
+import { utcpNamespacedKey, utcpNamespacePrefix } from '../utcp-namespace.js';
+
+describe('utcp-namespace', () => {
+  test('alphanumeric name → plain `<name>_<VAR>` (existing tools unaffected)', () => {
+    expect(utcpNamespacedKey('weather', 'API_KEY')).toBe('weather_API_KEY');
+    expect(utcpNamespacePrefix('weather')).toBe('weather_');
+  });
+  test('snake_case name → underscores doubled (UTCP convention)', () => {
+    expect(utcpNamespacedKey('my_tool', 'KEY')).toBe('my__tool_KEY');
+    expect(utcpNamespacePrefix('my_tool')).toBe('my__tool_');
+    expect(utcpNamespacedKey('a_b_c', 'X')).toBe('a__b__c_X');
+  });
+  test('non-word chars sanitized to `_` BEFORE doubling (mirrors `@utcp/sdk`\'s `name.replace(/[^\\w]/g,"_")`)', () => {
+    expect(utcpNamespacedKey('my-tool', 'KEY')).toBe('my__tool_KEY'); // same key as `my_tool`
+    expect(utcpNamespacePrefix('my-tool')).toBe('my__tool_');
+    expect(utcpNamespacedKey('acme.api', 'TOKEN')).toBe('acme__api_TOKEN');
+  });
+});

package/src/shared/frontmatter-id.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared identity helpers for the KB's `---`-frontmatter files, so tool manuals,
+ * skills, and node id-links all resolve identity the SAME way: a frontmatter `id`,
+ * then `name`, then a caller-supplied fallback (folder/filename). One grammar
+ * (lowercase `snake_case`) and one dedup rule (refuse duplicates) across all three.
+ * The `---` splitter itself lives in `@bevel-software/platform-shared` (used by the
+ * frontend too); re-exported here so backend callers keep one import site.
+ */
+import { extractFrontmatter } from '@bevel-software/platform-shared';
+
+export { extractFrontmatter };
+
+/**
+ * Extract a node's stable frontmatter `id` — the short token nodes cross-reference
+ * with (`[text](<id>)`). Null when the file has no leading `---` block or no `id:`
+ * scalar in it. Keeps the lowercase-kebab grammar the renderer's id-link uses, so
+ * any id this returns round-trips as a citation link. (Node-specific; tools/skills
+ * read `id`/`name` from the PARSED frontmatter via {@link resolveDeclaredId}.)
+ */
+export function extractFrontmatterId(markdown: string): string | null {
+  const fm = extractFrontmatter(markdown);
+  if (!fm) return null;
+  for (const line of fm.frontmatter.split(/\r?\n/)) {
+    const m = line.match(/^id:\s*["']?([a-z0-9][a-z0-9-]*)["']?\s*$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/** The ONE identity rule: frontmatter `id`, else `name`, else the caller's fallback. */
+export function resolveDeclaredId(frontmatter: Record<string, unknown>, fallback: string): string {
+  const id = typeof frontmatter.id === 'string' ? frontmatter.id.trim() : '';
+  if (id) return id;
+  const name = typeof frontmatter.name === 'string' ? frontmatter.name.trim() : '';
+  if (name) return name;
+  return fallback;
+}
+
+/**
+ * The canonical id grammar: lowercase `snake_case`. Enforced for tool manual ids
+ * because the id is used VERBATIM as the UTCP variable namespace, whose grammar is
+ * `[a-zA-Z0-9_]+` (underscores ok, hyphens rejected). Skills/nodes don't carry this
+ * constraint, so they don't validate against it.
+ */
+export function isValidId(id: string): boolean {
+  return /^[a-z0-9][a-z0-9_]*$/.test(id);
+}
+
+/**
+ * The ONE dedup rule: keep the first occurrence of each id, REFUSE later duplicates
+ * (skip + `onDuplicate`). Callers pass items in a deterministic order (e.g. sorted by
+ * path) so the winner is stable. Replaces tools' bespoke collision check and skills'
+ * auto-suffix with one shared behaviour.
+ */
+export function dedupeById<T>(
+  items: T[],
+  keyOf: (item: T) => string,
+  onDuplicate?: (item: T, id: string) => void,
+): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const item of items) {
+    const id = keyOf(item);
+    if (seen.has(id)) {
+      onDuplicate?.(item, id);
+      continue;
+    }
+    seen.add(id);
+    out.push(item);
+  }
+  return out;
+}

package/src/shared/fs-walk.ts

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/**
+ * The ONE recursive file walk for catalog scanners: relative (`/`-separated,
+ * sorted) paths of files under `root` whose basename matches. A missing root
+ * yields `[]`; dot-entries (incl. `.git`) are skipped. Scanners with different
+ * semantics (the skills scanner's stop-at-skill-folder walk, the access
+ * resolver's dir chains) deliberately keep their own walks.
+ */
+export async function walkFiles(root: string, match: (basename: string) => boolean): Promise<string[]> {
+  const out: string[] = [];
+  const walk = async (dir: string, rel: string): Promise<void> => {
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await walk(path.join(dir, entry.name), childRel);
+      else if (entry.isFile() && match(entry.name)) out.push(childRel);
+    }
+  };
+  await walk(root, '');
+  out.sort();
+  return out;
+}

package/src/shared/hash-email.ts

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Canonical user-identity hash: SHA-256 over the trimmed, lowercased email,
+ * returned as hex. Used wherever Bevel needs a stable email-derived identifier
+ * without storing the raw email — PR author-id markers, self-approval
+ * detection, etc. All callers MUST use this single function; a drift in the
+ * normalization (case, whitespace) would silently de-attribute every PR the
+ * bot opens because the hash embedded in the PR body would no longer match
+ * the hash computed at lookup time.
+ */
+export function hashEmail(email: string): string {
+  return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
+}

package/src/shared/kb-layout.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { ontologyOf } from './kb-layout.js';
+
+describe('ontologyOf', () => {
+  it('resolves a named ontology under Knowledge', () => {
+    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+  });
+
+  it('resolves a named ontology under NodeTypes', () => {
+    expect(ontologyOf('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
+  });
+
+  it('is space-safe in the ontology name', () => {
+    expect(ontologyOf('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
+      'KnowledgeBase/IT Architecture',
+    );
+  });
+
+  it('treats a nested ontology directory as the full prefix before the marker', () => {
+    expect(ontologyOf('KnowledgeBase/Group/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Group/Sub');
+  });
+
+  it('returns null when the marker sits directly under KnowledgeBase/', () => {
+    expect(ontologyOf('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
+    expect(ontologyOf('KnowledgeBase/NodeTypes/T.md')).toBeNull();
+  });
+
+  it('returns null for root-level Knowledge (not under KnowledgeBase/)', () => {
+    expect(ontologyOf('Knowledge/Foo.md')).toBeNull();
+  });
+
+  it('returns null for Data/ ontologies (deliberate session-ontology exemption)', () => {
+    // `Data/<X>` IS parsed into the graph (parser `ONTOLOGY_ROOTS`), but is
+    // intentionally NOT classified here so the session-ontology gate treats
+    // Data paths as neutral — pipeline agents read knowledge and write data
+    // in one session (owner decision 2026-07-27). See the `ontologyOf`
+    // docstring; this is not drift.
+    expect(ontologyOf('Data/Ops/Knowledge/x.md')).toBeNull();
+    expect(ontologyOf('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
+    // KnowledgeBase paths still classify as before.
+    expect(ontologyOf('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
+  });
+
+  it('returns null for Skills and root config (neutral)', () => {
+    expect(ontologyOf('Skills/some-skill/SKILL.md')).toBeNull();
+    expect(ontologyOf('access.md')).toBeNull();
+    expect(ontologyOf('roles.yaml')).toBeNull();
+  });
+
+  it('returns null for an ontology path with no marker segment', () => {
+    expect(ontologyOf('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
+  });
+
+  it('does not match substring lookalikes (segment equality)', () => {
+    expect(ontologyOf('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
+    expect(ontologyOf('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
+  });
+
+  it('strips a kbDirName prefix (normalized and un-normalized)', () => {
+    expect(ontologyOf('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
+      'KnowledgeBase/Product',
+    );
+    expect(ontologyOf('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
+      'KnowledgeBase/GTM',
+    );
+  });
+
+  it('normalizes backslashes and leading/trailing slashes', () => {
+    expect(ontologyOf('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
+    expect(ontologyOf('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
+  });
+
+  it('canonicalizes inner . and .. segments to the same ontology', () => {
+    expect(ontologyOf('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ontologyOf('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ontologyOf('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    // `..` also collapses inside the stripped kbDirName prefix.
+    expect(ontologyOf('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
+      'KnowledgeBase/GTM',
+    );
+  });
+
+  it('returns null for empty or root paths', () => {
+    expect(ontologyOf('')).toBeNull();
+    expect(ontologyOf('KnowledgeBase')).toBeNull();
+    expect(ontologyOf('KnowledgeBase/Product')).toBeNull();
+  });
+});

package/src/shared/kb-layout.ts

@@ -0,0 +1,101 @@
+import { KNOWLEDGE_BASE_DIR, ONTOLOGY_MARKERS, type Ontology } from '@bevel-software/platform-shared';
+
+/**
+ * Resolve which named ontology a KB path belongs to — the backend-side
+ * implementation of the layout contract whose constants/types live in
+ * `@bevel-software/platform-shared` (`kb-layout.ts`). It is backend-only and consumed by
+ * more than one domain module (the `workspace` read gate and the `workflow`
+ * session-ontology service), so it lives in `backend/src/shared` rather than in
+ * any single module — importable by both modules without crossing a module's
+ * internal boundary. Note it does NOT mirror the kb-graph parser one-to-one:
+ * see the `ontologyOf` docstring for the deliberate `Data/` exemption.
+ *
+ * Pure string handling — no IO, no DB.
+ */
+
+/**
+ * Split a path into repo-root-relative POSIX segments, dropping `./`,
+ * leading/trailing slashes, and an optional `kbDirName` prefix (the on-disk
+ * clone folder, e.g. `knowledge-base/`). Pure string handling — no IO.
+ */
+function toSegments(path: string, kbDirName?: string): string[] {
+  // Collapse to canonical segments: backslashes → `/`, drop empty and `.`
+  // segments, resolve `..` against the accumulated prefix. Canonicalizing the
+  // inner segments (not just the ends) means equivalent paths like
+  // `KnowledgeBase/Product/../Product/Knowledge/x.md` and
+  // `KnowledgeBase/Product/Knowledge/x.md` resolve to the same ontology.
+  const collapse = (s: string): string[] => {
+    const out: string[] = [];
+    for (const seg of s.replace(/\\/g, '/').split('/')) {
+      if (seg === '' || seg === '.') continue;
+      if (seg === '..') {
+        // Pop a real segment; a leading `..` (nothing to pop) is kept so it can
+        // never alias into a sibling ontology.
+        if (out.length > 0 && out[out.length - 1] !== '..') out.pop();
+        else out.push('..');
+        continue;
+      }
+      out.push(seg);
+    }
+    return out;
+  };
+
+  let segs = collapse(path);
+  const prefixSegs = kbDirName ? collapse(kbDirName) : [];
+  if (prefixSegs.length > 0 && prefixSegs.every((s, i) => segs[i] === s)) {
+    segs = segs.slice(prefixSegs.length);
+  }
+  return segs;
+}
+
+/**
+ * Resolve the named ontology a KB path belongs to, or `null` (neutral) when it
+ * belongs to none.
+ *
+ * Classification is deliberately NARROWER than the kb-graph parser: the parser
+ * discovers ontologies under every `ONTOLOGY_ROOTS` entry (`KnowledgeBase/`
+ * AND `Data/`), but this function classifies ONLY `KnowledgeBase/` paths.
+ * `Data/` ontologies are parsed into the graph yet are intentionally NOT
+ * classified here, so the session-ontology gate treats `Data/` paths as
+ * neutral — pipeline agents read knowledge and write data records in one
+ * session (owner decision 2026-07-27; the cross-ontology boundary mechanism
+ * itself may be redesigned). This divergence is on purpose, not drift.
+ *
+ * Within `KnowledgeBase/`, the shape matches the parser (`parser.ts`
+ * `walkForOntologies`): an ontology is the directory that holds both a
+ * `Knowledge/` and a `NodeTypes/` subfolder. That directory can sit at ANY
+ * depth under `KnowledgeBase/`, so the ontology id is the path PREFIX up to
+ * (but excluding) the first `Knowledge/` or `NodeTypes/` marker segment — as
+ * long as that prefix is inside `KnowledgeBase/` and is not `KnowledgeBase/`
+ * itself.
+ *
+ *   KnowledgeBase/Product/Knowledge/Foo.md            → "KnowledgeBase/Product"
+ *   KnowledgeBase/IT Architecture/NodeTypes/T.md      → "KnowledgeBase/IT Architecture"
+ *   KnowledgeBase/Group/Sub/Knowledge/x.md            → "KnowledgeBase/Group/Sub"
+ *   KnowledgeBase/Knowledge/Foo.md                    → null (marker directly under KB root)
+ *   Knowledge/Foo.md, Skills/x.md, access.md          → null (not under KnowledgeBase/)
+ *   Data/Ops/Knowledge/x.md                           → null (Data/ is exempt — see above)
+ *   KnowledgeBase/Product/Uploads/x.png               → null (no marker segment)
+ *
+ * Uses exact segment equality (never substring), so `KnowledgeBase/` and
+ * `Knowledge-notes.md` are never treated as markers; space-safe; pure (no IO).
+ *
+ * @param path       repo-root-relative POSIX path (may carry a `kbDirName` prefix)
+ * @param kbDirName  optional on-disk clone folder prefix to strip first
+ */
+export function ontologyOf(path: string, kbDirName?: string): Ontology {
+  const segs = toSegments(path, kbDirName);
+  // Must live under the dedicated KnowledgeBase/ container, with at least one
+  // ontology-name segment and a marker after it (so length >= 3).
+  if (segs.length < 3 || segs[0] !== KNOWLEDGE_BASE_DIR) return null;
+  // The ontology id is the prefix before the first marker segment. Require at
+  // least one name segment between `KnowledgeBase/` and the marker, so a marker
+  // sitting directly under `KnowledgeBase/` (`KnowledgeBase/Knowledge/...`) is
+  // neutral, matching the parser (it only discovers ontologies one level down).
+  for (let i = 1; i < segs.length; i++) {
+    if (ONTOLOGY_MARKERS.has(segs[i])) {
+      return i >= 2 ? segs.slice(0, i).join('/') : null;
+    }
+  }
+  return null;
+}

package/src/shared/ssrf.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal SSRF guard for user-supplied outbound URLs. Rejects obvious
+ * non-public targets (loopback, private, link-local, cloud-metadata) so an
+ * authenticated user can't point a server-side fetch at internal services.
+ *
+ * Only catches LITERAL hosts/IPs — DNS-rebinding (a public name that resolves to
+ * a private IP) is out of scope here; blunt that at fetch time / network layer.
+ */
+export function isBlockedHost(hostname: string): boolean {
+  let host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  // A trailing dot is the FQDN root and resolves identically: `localhost.` === `localhost`.
+  if (host.endsWith('.')) host = host.slice(0, -1);
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+
+  // IPv6 literals only: they contain a colon, whereas a plain hostname never does
+  // — so domains like `fc.example.org` / `fd.example.com` are not matched.
+  if (host.includes(':')) {
+    // IPv4-mapped IPv6 connects to the embedded v4 — validate it. The textual
+    // form may be dotted (`::ffff:169.254.169.254`) OR two hex hextets
+    // (`::ffff:a9fe:a9fe`) — WHATWG `new URL` canonicalizes the mapped address
+    // to the HEX form, so the dotted regex alone would miss a normalized
+    // hostname. Handle both.
+    const mappedDotted = /:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
+    if (mappedDotted && isBlockedV4(mappedDotted[1])) return true;
+    const mappedHex = /:ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (mappedHex) {
+      const hi = parseInt(mappedHex[1], 16);
+      const lo = parseInt(mappedHex[2], 16);
+      const v4 = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+      if (isBlockedV4(v4)) return true;
+    }
+    if (host === '::1' || host === '::') return true; // loopback / unspecified
+    // link-local fe80::/10 (fe80–febf) and unique-local fc00::/7 (fc/fd).
+    if (/^fe[89ab]/.test(host) || host.startsWith('fc') || host.startsWith('fd')) return true;
+    return false;
+  }
+  return isBlockedV4(host);
+}
+
+/** True for an IPv4 literal in a private / loopback / link-local (incl. cloud IMDS) range. */
+function isBlockedV4(host: string): boolean {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  if (a === 0 || a === 127 || a === 10) return true;
+  if (a === 169 && b === 254) return true; // link-local (incl. cloud IMDS 169.254.169.254)
+  if (a === 192 && b === 168) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64.0.0/10 (incl. Alibaba IMDS 100.100.100.200)
+  return false;
+}
+
+/**
+ * Parse + validate a user-supplied URL for a server-side fetch: must be http(s)
+ * (or https only when `requireHttps`), and its literal host must not be a
+ * blocked/internal target. Returns the parsed URL or throws a plain `Error`
+ * (callers wrap it in a domain error). `label` names the field in the message.
+ */
+export function assertSafeFetchUrl(
+  raw: string,
+  opts: { requireHttps?: boolean; label?: string } = {},
+): URL {
+  const label = opts.label ?? 'URL';
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new Error(`${label} must be a valid URL`);
+  }
+  if (opts.requireHttps) {
+    if (u.protocol !== 'https:') throw new Error(`${label} must use https`);
+  } else if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`${label} must be an http(s) URL`);
+  }
+  if (isBlockedHost(u.hostname)) throw new Error(`${label} host is not allowed`);
+  return u;
+}

package/src/shared/token-crypto.ts

@@ -0,0 +1,54 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+/**
+ * AES-256-GCM encryption for at-rest secrets. Output format is
+ * `<ivB64>:<tagB64>:<ciphertextB64>` so all three parts travel together in one
+ * text column. A DB leak alone yields only ciphertext; the key lives in the
+ * app's env, not the database. Shared primitive with several consumers, each
+ * bringing its own key: the secrets vault + MCP OAuth store (core), and the
+ * SharePoint token cache / connector configs (enterprise).
+ */
+export class TokenCrypto {
+  private readonly key: Buffer;
+
+  /** @param rawKey 32-byte key as hex (64 chars) or base64. */
+  constructor(rawKey: string) {
+    const key = decodeKey(rawKey);
+    if (key.length !== 32) {
+      throw new Error(
+        `SHAREPOINT_TOKEN_ENC_KEY must decode to 32 bytes (got ${key.length}). ` +
+          'Generate one with: `node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'base64\'))"`.',
+      );
+    }
+    this.key = key;
+  }
+
+  encrypt(plaintext: string): string {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', this.key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+  }
+
+  decrypt(blob: string): string {
+    const parts = blob.split(':');
+    if (parts.length !== 3) {
+      throw new Error('TokenCrypto.decrypt: malformed ciphertext blob (expected iv:tag:ct)');
+    }
+    const [ivB64, tagB64, ctB64] = parts;
+    if (!ivB64 || !tagB64 || !ctB64) {
+      throw new Error('TokenCrypto.decrypt: malformed ciphertext blob');
+    }
+    const decipher = createDecipheriv('aes-256-gcm', this.key, Buffer.from(ivB64, 'base64'));
+    decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+    return Buffer.concat([decipher.update(Buffer.from(ctB64, 'base64')), decipher.final()]).toString('utf8');
+  }
+}
+
+function decodeKey(raw: string): Buffer {
+  // Accept hex (64 chars, hex alphabet) or base64. Hex first to avoid a 64-char
+  // hex string being misread as base64.
+  if (/^[0-9a-fA-F]{64}$/.test(raw)) return Buffer.from(raw, 'hex');
+  return Buffer.from(raw, 'base64');
+}