Skip to content

Confluence knowledge source - #19

Merged
TahubCS merged 6 commits into
mainfrom
feat/confluence-knowledge-source
Oct 18, 2026
Merged

TahubCS merged 6 commits into
mainfrom
feat/confluence-knowledge-source

Conversation

@TahubCS

@TahubCS TahubCS commented Oct 18, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds Confluence as a knowledge source. A workspace connects Atlassian once (OAuth 2.0, read-only), then adds spaces from a list. Each space's current pages are indexed, synced nightly, and cited by page title without links.

Commits, each reviewable on its own (all of them pass typecheck and lint):

  1. refactor(integrations): share the signed connect state between providers. The GitHub state helper moves to src/lib/connect-state.ts. The provider is part of the HMAC key, so a GitHub state is rejected by the Atlassian callback. GitHub's key is unchanged, so in-flight connects survive the deploy.
  2. fix(ui): show toasts raised while a page mounts. This bug already exists on main: the GitHub connect-result toast never appeared. <Toaster /> rendered after the page, so it subscribed after the page's effect had raised the toast, and sonner drops toasts nobody is listening for.
  3. feat(atlassian): store an encrypted Atlassian grant per workspace.
    • AES-256-GCM token sealing under a new INTEGRATIONS_ENCRYPTION_KEY, bound to workspace and purpose.
    • atlassian_connection table (migration 0030).
    • Token refresh under a row lock, because Atlassian rotates the refresh token on every refresh.
    • A revoked grant is marked reauth_required.
  4. feat(knowledge): index Confluence spaces.
    • Pages are loaded through the Confluence v2 API, up to 400, most recently edited first.
    • Storage format is converted to text. A fixture of a real page showed what the existing extractor got wrong: leaked CDATA, code macro parameters, missing link titles, task metadata, template placeholders and duplicated panels.
    • Citations have no URL.
    • The page version drives embedding reuse, so only edited pages are re-embedded.
  5. feat(knowledge): connect Confluence and add spaces from the knowledge base.
    • Callback route, server actions, a Confluence tab with a space picker, a reconnect prompt, and source cards.
    • Disconnecting removes every Confluence source in the workspace, so only workspace owners and admins can do it.
    • Docs.
  6. fix(atlassian): ask for a reconnect when stored tokens no longer decrypt. After the encryption key changes, or if a stored value is altered, the connection is marked reauth_required. Before, the Confluence tab stayed on its loading message and syncs failed with a crypto error. A missing or invalid key is still treated as a configuration error.

Design notes

  • No generic integration layer. Confluence mirrors the GitHub App integration directly. A shared abstraction waits until a second integration (Slack) shows what is actually shared.
  • One grant per workspace, not per site. A grant reaches several sites, and the rotating refresh token has to live in one place. Each source records its own site and space.
  • No links in citations. Customers can't open Confluence pages. The source row has no URL either, because retrieval falls back to the source URL for citations.
  • Site and space details come from Atlassian. The server re-reads them when a space is added rather than trusting the browser.
  • A revoked or unreadable grant keeps the last index. Sources keep answering from it and show "Reconnect Confluence to keep syncing".

Testing

  • Lint, both typechecks, unit tests and next build pass.
  • On a fresh database, migrations apply and a second run is a no-op. The full suite passes with the database: 246 tests.
  • New database tests, with Atlassian stubbed at fetch and no network:
    • Token refresh: one refresh for concurrent callers, rotation, revocation, undecryptable tokens, transient failures, reconnecting, and cascade on disconnect.
    • Indexing: a stubbed space through the real job queue and retrieval, partial re-embedding on a nightly sync, revoked access, a missing space, and the page cap.
    • Callback: state provider and user binding, capability, no Confluence sites, declined consent.
    • Actions: status, add, duplicates, unreadable sites and spaces, rename, disconnect roles.
  • Each guard was checked by removing it and confirming a test fails (32 mutations, all caught except one that is behaviorally equivalent).
  • Verified in Chromium against next dev: the authorize link (client, scopes, redirect, state), result toasts, forged and declined callbacks, the reconnect prompt, source cards and the name-only edit.
  • Not yet verified against a real Atlassian site. That needs an Atlassian OAuth app and ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET and INTEGRATIONS_ENCRYPTION_KEY set in the environment.

Setup

Create an OAuth 2.0 (3LO) integration in the Atlassian developer console:

  • Scopes read:space:confluence and read:page:confluence.
  • Callback URL <app>/api/integrations/atlassian/callback.
  • Set ATLASSIAN_CLIENT_ID, ATLASSIAN_CLIENT_SECRET and INTEGRATIONS_ENCRYPTION_KEY (openssl rand -base64 32).

Keep the key stable: changing it makes stored tokens unreadable, and each workspace has to reconnect.

The GitHub App connect flow signs a short-lived `state` that ties the
callback to the Supo user and product that started it. Confluence needs the
same round trip, so the helper moves from src/lib/github/state.ts to
src/lib/connect-state.ts and takes the provider as an argument.

The provider is part of the HMAC key, so a state issued for one provider is
rejected by the other's callback. GitHub's key is unchanged
(`<secret>:github-connect-state`), so states issued before a deploy still
verify; a test pins that.
After the GitHub App connect round trip, the knowledge page shows the result
as a toast from an effect and then clears the query parameter. The toast
never appeared: effects run in tree order, the root layout rendered
<Toaster /> after the page, and sonner only delivers a toast to Toasters
that have already subscribed. With the parameter cleared, the message was
lost for good.

Render <Toaster /> before the page so it subscribes first. The connect
result toast gets a fixed id, so React StrictMode's second effect run in
development updates it instead of stacking a duplicate.

Reproduced in Chromium against `next dev` with ?github=cancelled (no
toast), then verified the toast shows once.
Groundwork for Confluence as a knowledge source.

- secret-box: AES-256-GCM sealing for third-party tokens under a new
  INTEGRATIONS_ENCRYPTION_KEY, kept separate from BETTER_AUTH_SECRET so
  either can rotate on its own. Values are versioned (v1.iv.tag.ct), the
  tag length is pinned, and each value is bound to its workspace and
  purpose (AAD), so a token copied into another row or column won't open.
- atlassian_connection (migration 0030): one OAuth grant per workspace,
  since a grant can reach several sites and Atlassian rotates its refresh
  token. knowledge_source.atlassian_connection_id cascades, so removing
  the grant removes its sources.
- OAuth 2.0 (3LO): authorize URL, code exchange, refresh, and the sites a
  token can read Confluence pages on.
- getAccessToken refreshes under a row lock (SELECT ... FOR UPDATE) and
  re-checks after acquiring it. Concurrent callers reuse the token the
  first one stored instead of spending an already-rotated refresh token.
  invalid_grant marks the grant reauth_required (committed, not rolled
  back); other failures leave it active so a later run can retry.
- atlassianGet: gateway requests with one forced refresh on 401.

Database tests cover the single refresh under concurrency, rotation,
revocation, transient failures, reconnecting and cascade on disconnect.
Each guard was checked by removing it and confirming a test fails.
A "confluence" source reads every current page of one space through the
workspace's Atlassian grant (Confluence REST v2, storage-format bodies,
cursor pagination). Pages are ordered most recently edited first and capped
at 400, with a warning when a space has more.

Storage format is rewritten into plain HTML for the shared extractor. A
fixture of a real page showed what extractHtml got wrong on its own, and
each rewrite targets one of those cases:
- CDATA leaked as literal text. It is escaped first, so code that contains
  Confluence markup stays text and later rewrites can't touch it.
- Code macros leaked their language and theme parameters.
- Page links without their own text lost the page title.
- Task ids and statuses, template placeholders, and the new editor's
  duplicate fallback copy of panels were indexed.
- Expand titles are kept as a lead-in paragraph.

Citations have no URL, as with private GitHub repositories: customers can't
open Confluence pages. The page version is the document version, so a
nightly sync re-embeds only edited pages. A space that is gone or no longer
readable (403/404) gets an actionable message.

The auto-synced source types now live in src/lib/knowledge/source-types.ts
instead of being repeated in ingest and the sync cron; the knowledge UI
moves to it with the Confluence UI.

Tests: the fixture's exact text, plus database tests that run a stubbed
space through the real job queue, retrieval, partial re-embedding,
revocation, missing spaces and the page cap. Each guard was checked by
removing it and confirming a test fails.
… base

- Callback /api/integrations/atlassian/callback mirrors GitHub's: it
  verifies a state signed for Atlassian and bound to the signed-in user,
  requires knowledge access to the product, exchanges the code, and stores
  the grant only if it can read Confluence on at least one site.
- Server actions: connection status (active, reauth_required or not
  connected), spaces per site, add a space, disconnect. Site and space
  details are read from Atlassian, not taken from the browser. A space can
  be added once per product. The source has no URL, because retrieval
  falls back to the source URL for citations. Renaming is the only edit.
- Disconnecting deletes the grant and every Confluence source in the
  workspace, so it is limited to workspace owners and admins.
- UI: a Confluence tab with a space picker. It says that pages can be
  quoted to customers and are cited without links. A "Reconnect" prompt
  appears once access is revoked. Source cards show site, space and key.
- Docs: README, .env.example and CHANGELOG.

Database tests cover the callback (state provider and user binding,
capability, no-sites, declined consent) and the actions (status, add,
duplicates, unreadable sites and spaces, rename, disconnect roles). Each
guard was checked by removing it and confirming a test fails. Also
verified in Chromium against `next dev`: the connect link, result toasts,
the reconnect prompt, the source cards and the name-only edit.
@vercel

vercel Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
supo Ready Ready Preview Oct 18, 2026 1:35am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 090f8e93-7a01-4391-aa18-af212c89753c
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 18, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-18T01:32:23.446396Z f1ec993 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f1ec99328a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/lib/atlassian/connection.ts Resolved
After INTEGRATIONS_ENCRYPTION_KEY changes, or if a stored value is
altered, opening a sealed token threw a plain error instead of marking the
connection reauth_required. The knowledge page then stayed on "Loading
Confluence…" with no way to reconnect, and every sync failed with a crypto
error, although the docs promise a reconnect prompt after a key change.

- openSecret throws UnreadableSecretError when a value is malformed or
  fails authentication. A missing or invalid key is still a configuration
  error and doesn't cost workspaces their grants.
- getAccessToken treats an unreadable refresh token like a revoked grant:
  under the row lock it marks the connection reauth_required. An
  unreadable access token alone falls through to a normal refresh.
- The Confluence form shows a load error inline instead of staying on its
  loading message.

New tests cover a changed key (reconnect, no refresh spent) and an altered
access token (refreshes, stays active). Each guard was checked by removing
it and confirming a test fails.
@TahubCS
TahubCS merged commit 708bab4 into main Oct 18, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — 514ef7bb Deployed Oct 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant