knowledge

Overview ¶

connectors.go is the per-org app-connector control plane: OAuth into Slack / GitHub / Google, store the token in KMS (never plaintext, never logged), and sync external documents INTO the same per-org knowledge store + vector index as manual pages. A connector is a pure PRODUCER of framework documents (kb-source) — it creates them through framework.Ingest, so the SAME after_save indexing hook that serves manual pages indexes them. One knowledge store, many sources, one index.

SECURITY (the tenant + secret boundary):

• Every handler resolves its org from principal.Org (a validated principal), NEVER a client field. A caller can only ever connect/sync/disconnect its OWN org, and synced docs are written into that org's store only.
• The OAuth token is a RETRIEVABLE secret (it must be presented to the provider API), so it lives in KMS at a deterministic per-org path — never in the kb-connector document, never in a log line. The document holds only the KMS PATH (kms_ref) and non-secret connection metadata.
• The OAuth `state` is an HMAC over (org|provider|nonce|expiry) keyed by a server secret, so the callback re-derives the org from the STATE it signed — not from a client header and not from the provider — which defeats the login-CSRF / mix-up class (an attacker cannot bind their provider account to a victim org, nor steer a victim's callback to a foreign org).

Package kb declares the Hanzo Knowledge Base + unified AI memory model as DocType fixtures on the framework engine (clients/framework), and wires the ONE per-org vector-indexing path (index.go) that turns every knowledge document into retrievable org memory. It is the FOURTH app lane after cms/erp/help and the one that makes "a Notion-like wiki + agent memory" just another module on Base — no new Base, no new database.

Like cms/erp/help, the content model is fixtures: a wiki page IS a framework document (module "kb"), a memory IS a framework document, an ingested doc from a connector IS a framework document. CRUD, permissions, tenant isolation, and install are the framework's generic, already-live surface (/v1/framework/*) and the SAME generic @hanzo/ui DocType renderer that draws CMS and ERP.

UNLIKE the pure-fixture lanes, kb attaches BEHAVIOR (hooks.go): on every save of a knowledge document the after_save hook upserts its text to the org's vector namespace, and on trash it removes it. Human wiki + AI memory therefore share ONE per-org knowledge store, indexed once. kb ALSO mounts a thin retrieval + ingestion control-plane subsystem (subsystem.go, /v1/kb/*): semantic search (the RAG entry point an agent/chat calls) and app connectors (Slack/GitHub/ Google) that ingest external docs INTO the same store. Connectors are just producers of framework documents — they never fork the vector-write path.

Names are slug-style with a "kb-" prefix so they never collide with the CMS (Author/Media/Page/…), ERP (erp-*), or Help (hd-*) lanes and never carry a space the console's /cloud path filter would reject.

subsystem.go mounts the KB retrieval + ingestion control-plane at /v1/kb/*. It is the thin surface on top of the framework DocType store (CRUD lives at /v1/kb) and the vector index (index.go):

• POST /v1/kb/search — the RAG entry point. An agent/chat resolves the org from its validated principal and asks "what does this org know about X"; the org's OWN vector namespace answers. This is how human wiki + AI memory become retrievable org knowledge for an agent.

• GET /v1/kb/graph (graph.go) — the org's knowledge as a node/edge graph for a force-directed renderer: pages/memories/sources as nodes; the parent tree, wikilinks, and connector provenance as edges.

• POST /v1/kb/import (import.go) — an Obsidian-importer-equivalent that ingests an Obsidian/Notion/Roam/Evernote export as a kb-page tree with links intact.

• Connectors (connectors.go): per-org OAuth connections to Slack/GitHub/Google whose synced documents land in the SAME store + SAME index as manual pages.

Every handler resolves its tenant through principal.Org (the ONE boundary) and scopes strictly to that org — a caller can only ever search or connect its own knowledge.

sync.go implements OAuth code exchange and the per-provider document pull. Every pulled item is normalized to ONE shape (ingestDoc) and filed as a kb-source document via framework.Ingest — so the SAME after_save hook indexes it into the org's vector namespace, alongside manual pages and memories. This is the single ingestion path; providers differ only in how they LIST and FETCH, never in how they land in the store.

GitHub is implemented end-to-end (repo READMEs + issues via the REST API) as the proof. Slack and Google are wired to the SAME normalizer and OAuth lifecycle; their pull is scaffolded with an honest depth marker (they connect and record a connection, and the sync returns a clear "listing not yet implemented" rather than a fabricated ingest) so the depth is never overstated.