Feat/doc site update#73
Merged
Merged
Conversation
- New four-zone nav: Concepts / Getting Started / Guides / Reference - docs/stylesheets/extra.css: custom theme ported from JarvisCore docs with Nexus brand blue (#0071F7), Inter + JetBrains Mono fonts, tight prose density, polished sidebar, header, tables, admonitions - mkdocs.yml: updated theme config, nav, extra_css - docs/index.md: prose home page, no link dump - docs/concepts/how-nexus-works.md: four-component architecture, OAuth handshake, credential retrieval, connection states - docs/concepts/security-model.md: master vs usage secrets, three critical keys, network hardening, audit log - docs/concepts/provider-types.md: OAuth2 (discovery + manual), static key providers, credential payload, aliases - docs/getting-started/quickstart.md: key generation, Docker startup, health checks, first provider registration - docs/getting-started/configuration.md: all env vars with types and descriptions, production Azure deployment guide - docs/getting-started/first-connection.md: complete OAuth handshake walkthrough, status polling, credential retrieval - docs/guides/integrating-agents.md: Bridge library, manual HTTP, Go SDK, connection ID management patterns - docs/guides/managing-providers.md: OAuth2 and API key provider registration, listing, updating, deleting - docs/guides/security-as-code.md: nexus-cli plan/apply, manifest format, CI/CD integration, audit trail - docs/guides/obo-delegation.md: new page — OBO session creation, fixed clearance, scope validation, Go SDK usage - docs/reference/api.md: Gateway and Broker API surfaces, endpoint tables, credential payload, auth model - docs/reference/audit-log.md: event types, query params, response schema, retention, nexus-cli audit trail - docs/reference/roadmap.md: active work, known limitations, explicitly deferred features with rationale Writing rules enforced throughout: no em dashes, no bullet lists for explanatory prose, no numbered sub-headers, no bold for emphasis, code only when showing something runnable.
…table styles, audit log, agent identity, agent sessions, OBO delegation, security-as-code, infra deploy guide, brand CSS overhaul
….follow, clean developer journey
…, fix home page links, surface Bridge gRPC/observability, fix writing tone
…, sidebar nav with Website/Community/Blog, remove stats row
- Restructured nav: flattened providers, moved SDKs into Guides flow - Reordered Concepts for logical learning journey - Added changelog from real git history with accurate contributors - Added troubleshooting guide and client-libraries concept page - Added LLM assist widget (copy/view as markdown) on every page - Version chip now live from GitHub API (no hardcoded values) - Fixed mobile drawer: all nav items clickable, back arrows work, 44px touch targets, pointer-events scoped to desktop only - Search bar absolute positioning scoped to desktop only - Sidebar labels use white-space:nowrap, no wrapping - Header title shrinks properly on mobile screens - Footer social links: Website, X, LinkedIn, GitHub, Discord - Sidebar links updated with correct Discord invite URL - All reference pages have material icons in frontmatter - Removed navigation.expand to prevent mobile drawer bloat - Sidebar width (15rem) scoped to desktop only
Contributor
There was a problem hiding this comment.
Pull request overview
This PR is a large overhaul of the Nexus documentation site: it restructures mkdocs.yml navigation, replaces several core docs (architecture, security model, SDKs, audit log, API reference, provider/managing-providers, security-as-code, integrating-agents), adds new concept and guide pages (broker/gateway/bridge/connections/provider-types/auth-strategies/agent-identity/client-libraries, getting-started/quickstart/configuration/first-connection, troubleshooting/static-credentials/obo-delegation/agent-sessions/attention-state, CLI reference, deploying-nexus, roadmap, CHANGELOG), adds two new JS widgets (header.js, llm-assist.js), and tweaks the extra.css mobile responsiveness story (not included in the diffs reviewed here).
Changes:
- New navigation/IA in
mkdocs.yml, with custom theme, fonts, plugins, footer socials, and new JS assets. - A large set of new/rewritten concept, guide, and reference pages including a brand-new CHANGELOG and roadmap.
- Two new front-end JS widgets: live version chip + GitHub stars in the header, and a copy/view-as-markdown widget on every page.
Reviewed changes
Copilot reviewed 41 out of 44 changed files in this pull request and generated 14 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Theme/nav/plugins/socials overhaul; registers new JS and changelog. |
| docs/CHANGELOG.md | New release history page with contributor avatars per release. |
| docs/index.md | New hero, cards, and quick-start sections for the landing page. |
| docs/javascripts/header.js | Live version chip, GitHub repo+stars chip, external-link rewriting. |
| docs/javascripts/llm-assist.js | "Copy as Markdown" / "View as Markdown" widget injected on every page. |
| docs/concepts/architecture.md | New top-level Concepts intro covering control/data plane and components. |
| docs/concepts/how-nexus-works.md | Near-duplicate of architecture.md, not in nav. |
| docs/concepts/broker.md / gateway.md / bridge.md / connections.md / provider-types.md / auth-strategies.md / agent-identity.md / client-libraries.md / security-model.md / sdk.md | New concept pages; sdk.md is not in nav. |
| docs/getting-started/quickstart.md / configuration.md / first-connection.md | New onboarding flow under Getting Started. |
| docs/guides/registering-a-provider.md / managing-providers.md / integrating-agents.md / mcp-integration.md / static-credentials.md / obo-delegation.md / agent-sessions.md / attention-state.md / troubleshooting.md / security-as-code.md | New or rewritten guides. |
| docs/infrastructure/deploying-nexus.md | New production deployment guide. |
| docs/reference/api.md / cli.md / audit-log.md / security-model.md / roadmap.md | Reference rewrite + new CLI/roadmap pages; roadmap.md not in nav. |
| docs/sdks/{index,go,python,typescript}.md | Adds material/ icon frontmatter only. |
Comments suppressed due to low confidence (2)
mkdocs.yml:126
version: "0.2.3"is hardcoded underextra, but the PR description explicitly states: "Version chip now 100% live from GitHub API (latest tag) — no hardcoded fallback". Either remove this hardcoded value to match the stated intent, or document where this value is still consumed. As written it contradicts the PR description and risks drifting silently from the real latest tag.
docs/javascripts/llm-assist.js:135navigator.clipboard.writeText(text)is called without checking thatnavigator.clipboardis defined and without handling the returned Promise rejection. In non-secure contexts (e.g. previewing the docs over plainhttp://from a non-localhost origin)navigator.clipboardisundefinedand this will throw, leaving the check icon stuck intriggerMainfor 2 seconds with no user feedback. Recommend guarding the call and catching the Promise to restore the icon and optionally surface an error.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+134
to
+136
| - icon: fontawesome/brands/linkedin | ||
| link: https://linkedin.com/company/jarviscore | ||
| name: JarvisCore on LinkedIn |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on our company linkedin is https://www.linkedin.com/company/prescott-data/
Contributor
There was a problem hiding this comment.
Updated in commit bfdd6db — the LinkedIn link now points to https://www.linkedin.com/company/prescott-data/ with the display name "Prescott Data on LinkedIn".
| - Home: | ||
| - Overview: index.md | ||
| - Website: https://developers.prescottdata.io | ||
| - Community: https://discord.gg/AbskSXypq |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on this feedback
Contributor
There was a problem hiding this comment.
Fixed in commit fb8690f — all Discord URLs now consistently use https://discord.gg/AbskSXypq across mkdocs.yml, docs/index.md, and docs/guides/troubleshooting.md.
Comment on lines
+1
to
+3
| # Roadmap | ||
|
|
||
| This page documents what is actively being built, what has been intentionally deferred, and the known limitations of the current implementation. It is kept here rather than only in GitHub Issues so that developers integrating with Nexus can plan their own work against it. |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on Remove the file, not intended to ship
Contributor
There was a problem hiding this comment.
Removed in commit 75e6352 — docs/reference/roadmap.md has been deleted.
Comment on lines
+7
to
+17
| document.addEventListener('DOMContentLoaded', function () { | ||
|
|
||
| /* ── 1. Version chip — live from GitHub API ─────────── */ | ||
| var title = document.querySelector('.md-header__title'); | ||
| var chip; | ||
| if (title) { | ||
| chip = document.createElement('span'); | ||
| chip.className = 'nx-version-chip'; | ||
| chip.textContent = '…'; | ||
| title.insertAdjacentElement('afterend', chip); | ||
| } |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on this feedback
Contributor
There was a problem hiding this comment.
Fixed in commit 75e6352 — header.js now wraps initialization in an initHeader() function that runs on both DOMContentLoaded and via document$.subscribe(...), matching the pattern in llm-assist.js. The version chip, GitHub stars widget, and external tab handling now persist across instant navigation. Added guards to prevent duplicate injection on subsequent navigations.
| **Added** | ||
|
|
||
| - **Python SDK** (`nexus-sdk-python`): full-feature-parity Python client — `get_token_by_connection_id`, `resolve_token`, `request_connection`, `check_connection`. Zero external dependencies. | ||
| - **TypeScript SDK** (`@dromos/nexus-sdk`): evolved from `nexus-mcp-adapter`. MCP token resolution, in-memory caching, authenticated transport, and `resolveToken` for stateless MCP clients. Built to `dist/`, ESM imports hardened. |
Contributor
Author
There was a problem hiding this comment.
@copilot i think check the sdk code i think it is @prescott/nexus-sdk go confirm
@dromos/nexus-sdk could be the wrong thing
Contributor
There was a problem hiding this comment.
Checked the SDK source code at nexus-sdk-ts/package.json — the published package name is @dromos/nexus-sdk (line 2). The documentation is already correct and consistent:
docs/CHANGELOG.md:28✓@dromos/nexus-sdkdocs/sdks/typescript.md:7✓@dromos/nexus-sdkdocs/guides/integrating-agents.md:113✓@dromos/nexus-sdkdocs/concepts/client-libraries.md:26✓@dromos/nexus-sdk- Main
README.md:42✓@dromos/nexus-sdk
All references use the correct scoped package name that matches the actual published SDK.
Comment on lines
+100
to
+122
| - Deploy in Five Minutes: getting-started/quickstart.md | ||
| - Configuration: getting-started/configuration.md | ||
| - Your First Connection: getting-started/first-connection.md | ||
| - Guides: | ||
| - Providers: guides/registering-a-provider.md | ||
| - Integrating Agents: guides/integrating-agents.md | ||
| - Go SDK: sdks/go.md | ||
| - TypeScript SDK: sdks/typescript.md | ||
| - Python SDK: sdks/python.md | ||
| - Guides: | ||
| - Agent Integration: guides/integrating-agents.md | ||
| - Agent Sessions: guides/agent-sessions.md | ||
| - Static Credential Flow: guides/static-credentials.md | ||
| - OBO Delegation: guides/obo-delegation.md | ||
| - MCP Server Integration: guides/mcp-integration.md | ||
| - Managing Providers: guides/managing-providers.md | ||
| - Security-as-Code (nexus-cli): guides/security-as-code.md | ||
| - API Reference: | ||
| - API Overview: reference/api.md | ||
| - Handling Attention State: guides/attention-state.md | ||
| - Troubleshooting: guides/troubleshooting.md | ||
| - Security-as-Code: guides/security-as-code.md | ||
| - Deploying Nexus: infrastructure/deploying-nexus.md | ||
| - Reference: | ||
| - API Reference: reference/api.md | ||
| - CLI Reference: reference/cli.md | ||
| - Audit Log: reference/audit-log.md | ||
| - Technical Debt & Roadmap: reference/tech-debt.md | ||
| - Security Model: reference/security-model.md | ||
| - Changelog: CHANGELOG.md |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on remove the files
Contributor
There was a problem hiding this comment.
Removed in commit 6aa2474 — deleted docs/concepts/sdk.md and docs/concepts/how-nexus-works.md as they were not wired into the nav and overlapped with existing content (client-libraries.md and architecture.md respectively).
Agent-Logs-Url: https://github.com/Prescott-Data/nexus-framework/sessions/c05359bf-1a4d-4618-a5aa-df9731a928b5 Co-authored-by: ekizito96 <87319861+ekizito96@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/Prescott-Data/nexus-framework/sessions/dd4fcd81-77f7-4e35-8190-f7d47fa78223 Co-authored-by: ekizito96 <87319861+ekizito96@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| |---|---| | ||
| | **Source** | Browse the code, open issues, and submit PRs — [GitHub](https://github.com/Prescott-Data/nexus-framework){ target="_blank" rel="noopener" } | | ||
| | **OpenAPI** | The full Gateway v1 contract — [openapi.yaml](https://github.com/Prescott-Data/nexus-framework/blob/main/openapi.yaml){ target="_blank" rel="noopener" } | | ||
| | **Community** | Questions, showcases, and early feature previews — [Discord](https://discord.gg/AbskSXypq){ target="_blank" rel="noopener" } | |
Contributor
Author
Contributor
There was a problem hiding this comment.
Already fixed in commit fb8690f — docs/index.md now uses https://discord.gg/AbskSXypq.
| ## Getting more help | ||
|
|
||
| - **GitHub Issues**: [github.com/Prescott-Data/nexus-framework/issues](https://github.com/Prescott-Data/nexus-framework/issues) | ||
| - **Discord**: [discord.gg/AbskSXypq](https://discord.gg/AbskSXypq) |
Contributor
Author
Contributor
There was a problem hiding this comment.
Already fixed in commit fb8690f — docs/guides/troubleshooting.md now uses https://discord.gg/AbskSXypq.
| @@ -0,0 +1,152 @@ | |||
| # The SDK | |||
Contributor
There was a problem hiding this comment.
Already removed in commit 6aa2474 — docs/concepts/sdk.md has been deleted as it was not wired into the nav and overlapped with client-libraries.md.
Comment on lines
+3
to
+69
| Nexus is split into a control plane and a data plane. The control plane manages the lifecycle of credentials: registering providers, completing OAuth handshakes, storing tokens, and refreshing them before they expire. The data plane serves credentials to agents when they need them and injects those credentials into outgoing requests. | ||
|
|
||
| Understanding this separation is the mental model for everything else in this documentation. | ||
|
|
||
| --- | ||
|
|
||
| ## The four components | ||
|
|
||
| ### The Broker | ||
|
|
||
| The Broker is the most sensitive component in the system. It is the only service that ever holds refresh tokens or provider API keys. Everything it stores is encrypted at rest using AES-GCM 256-bit with a key you supply and manage. The Broker never sends a refresh token to any other service. When the Gateway asks for credentials, the Broker decrypts the stored token, fetches a fresh access token from the provider, and returns only that. | ||
|
|
||
| The Broker runs a background refresh loop. Before any stored token expires, the Broker fetches a new one using the stored refresh token. If a provider rejects the refresh (for example, because a user revoked access), the Broker transitions that connection to `attention_required` and records the failure in the audit log. The agent does not need to handle this case; it will simply receive an error on the next credential request and can surface it to the user. | ||
|
|
||
| ### The Gateway | ||
|
|
||
| The Gateway is the public-facing API that agents call. It accepts REST and gRPC requests, proxies them to the Broker using an internal API key, and returns the response. Agents never reach the Broker directly. This decoupling means you can expose the Gateway to agents running outside your network without exposing the Broker. | ||
|
|
||
| The Gateway handles CORS, request validation, and API versioning. From an agent's perspective, the Gateway is Nexus. | ||
|
|
||
| ### The Bridge | ||
|
|
||
| The Bridge is a Go library that runs inside your agent process. You instantiate it with a Gateway client, and it handles credential retrieval and request signing automatically. For a persistent WebSocket or gRPC connection, you call `bridge.MaintainWebSocket()` or the gRPC equivalent and the Bridge keeps the connection authenticated through token rotations, including exponential backoff on failures. It also exposes a Prometheus `/metrics` endpoint for operational visibility. | ||
|
|
||
| Use the Bridge when your agent is written in Go and makes ongoing connections to provider services. | ||
|
|
||
| ### The SDK | ||
|
|
||
| The SDK is a thin Go client for the Gateway API. It exposes `GetToken()` and related methods, giving you direct control over credential retrieval without the connection management logic the Bridge provides. Use the SDK when you want to fetch credentials explicitly rather than having them injected automatically, or when you are implementing a non-persistent integration pattern. | ||
|
|
||
| --- | ||
|
|
||
| ## The OAuth handshake flow | ||
|
|
||
| When a user connects a new provider account, the flow runs as follows. | ||
|
|
||
| Your application backend calls `POST /v1/request-connection` on the Gateway, passing the user identifier, the provider name, the requested scopes, and a return URL. The Gateway forwards this to the Broker, which generates a unique `state` parameter signed with the `STATE_KEY` and returns an authorization URL and a `connection_id`. | ||
|
|
||
| Your application redirects the user's browser to the authorization URL. The user authenticates with the provider and grants consent. The provider redirects back to the Broker's callback endpoint, which validates the `state` parameter, exchanges the authorization code for tokens, encrypts the tokens, and stores them in PostgreSQL. | ||
|
|
||
| The Broker then redirects the user's browser to your `return_url` with the `connection_id` and a `status=success` parameter. Your application captures the `connection_id` and stores it. That is the only thing your application needs to hold. The actual tokens stay in the Broker. | ||
|
|
||
| --- | ||
|
|
||
| ## The credential retrieval flow | ||
|
|
||
| When your agent needs to call a provider, the flow is simpler. | ||
|
|
||
| Your agent calls `GET /v1/token/{connection_id}` on the Gateway. The Gateway forwards the request to the Broker, which retrieves the stored tokens, decrypts them in RAM, and returns a credential payload to the Gateway. The payload contains a `strategy` field that describes how to use the credentials and a `credentials` object with the actual values. | ||
|
|
||
| The `strategy` field exists because Nexus supports multiple credential types. An OAuth2 connection returns `{"type": "oauth2"}` with an `access_token`. An API key connection returns `{"type": "api_key"}` with the key value in a field matching the provider's schema. The Bridge handles strategy interpretation automatically. If you are making direct HTTP calls, you inspect `strategy.type` and apply the credentials accordingly. | ||
|
|
||
| --- | ||
|
|
||
| ## Connection states | ||
|
|
||
| A connection moves through a small set of states during its lifetime. | ||
|
|
||
| `pending` is the initial state after `request-connection` returns but before the user has completed consent. `active` is the normal operating state: tokens are valid and the background refresh loop is keeping them current. `attention_required` means the last refresh attempt failed with a provider error that cannot be retried, typically because the user revoked the application's access. `failed` means the initial token exchange failed. | ||
|
|
||
| Your application should surface `attention_required` to the user so they can reconnect the provider account. | ||
|
|
||
| --- | ||
|
|
||
| ## What Nexus does not do | ||
|
|
||
| Nexus does not make API calls to providers on behalf of agents. It provides credentials; agents make the calls. Nexus does not manage authorization within your own application (which users can access which connections). It manages authentication with external providers. Nexus does not run inside your agent. The Bridge is an in-process library, but the Broker and Gateway are network services that you deploy separately. |
| @@ -0,0 +1,79 @@ | |||
| # Roadmap | |||
|
|
||
|
|
||
| extra: | ||
| version: "0.2.3" |
Comment on lines
+23
to
+29
| // Local dev fallback: derive the .md source path from the current URL. | ||
| // MkDocs serves /foo/bar/ from docs/foo/bar.md (or docs/foo/bar/index.md). | ||
| if (!rawUrl && window.location.hostname === 'localhost') { | ||
| var pathname = window.location.pathname.replace(/\/$/, '') || '/index'; | ||
| rawUrl = '/docs' + pathname + '.md'; | ||
| window._nxMdPathBase = pathname; | ||
| } |
Comment on lines
+20
to
+68
| fetch('https://api.github.com/repos/Prescott-Data/nexus-framework/tags') | ||
| .then(function (r) { return r.json(); }) | ||
| .then(function (tags) { | ||
| if (Array.isArray(tags) && tags.length > 0) { | ||
| var latestVersion = tags[0].name; | ||
| if (chip) chip.textContent = latestVersion; | ||
|
|
||
| /* Also update hero badge if present */ | ||
| var heroBadge = document.getElementById('nx-hero-version-badge'); | ||
| if (heroBadge) { | ||
| heroBadge.innerHTML = latestVersion + ' · Apache 2.0 · Production Ready'; | ||
| } | ||
| } | ||
| }) | ||
| .catch(function () { | ||
| /* On network failure, hide chip entirely rather than showing stale data */ | ||
| if (chip) chip.style.display = 'none'; | ||
| }); | ||
|
|
||
| /* ── 2. GitHub stars widget ─────────────────────────── */ | ||
| var inner = document.querySelector('.md-header__inner'); | ||
| var palette = document.querySelector('form[data-md-component="palette"]'); | ||
| if (inner && palette) { | ||
| var ghBtn = document.createElement('a'); | ||
| ghBtn.href = 'https://github.com/Prescott-Data/nexus-framework'; | ||
| ghBtn.target = '_blank'; | ||
| ghBtn.rel = 'noopener noreferrer'; | ||
| ghBtn.className = 'nx-gh-btn'; | ||
| ghBtn.setAttribute('aria-label', 'Star Nexus on GitHub'); | ||
| ghBtn.innerHTML = | ||
| '<span class="nx-gh-repo">Prescott-Data/nexus</span>' + | ||
| '<span class="nx-gh-sep">★</span>' + | ||
| '<span class="nx-stars-count">—</span>'; | ||
|
|
||
| inner.insertBefore(ghBtn, palette); | ||
| inner.appendChild(palette); | ||
| } | ||
|
|
||
| /* ── 3. Async star count ────────────────────────────── */ | ||
| fetch('https://api.github.com/repos/Prescott-Data/nexus-framework') | ||
| .then(function (r) { return r.json(); }) | ||
| .then(function (data) { | ||
| var el = document.querySelector('.nx-stars-count'); | ||
| if (el && typeof data.stargazers_count === 'number') { | ||
| var n = data.stargazers_count; | ||
| el.textContent = n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n); | ||
| } | ||
| }) | ||
| .catch(function () {}); |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/Prescott-Data/nexus-framework/sessions/cf0c72d4-33bf-4cdc-a755-2386d8a83d1c Co-authored-by: ekizito96 <87319861+ekizito96@users.noreply.github.com>
| - Moves theme palette toggle to far-right | ||
| - Opens external tabs in new window | ||
| */ | ||
| function initHeader() { |
Comment on lines
+3
to
+51
| The Nexus SDK is a Go HTTP client that wraps the Gateway's REST API. The Bridge uses it internally. Use it directly when you want explicit control over credential fetches rather than the Bridge's automatic lifecycle management. | ||
|
|
||
| ## Install | ||
|
|
||
| ```bash | ||
| go get github.com/Prescott-Data/nexus-framework/nexus-sdk@v0.1.1 | ||
| ``` | ||
|
|
||
| ## When to use the SDK | ||
|
|
||
| - Your agent makes discrete outgoing HTTP calls rather than holding a persistent connection. | ||
| - You are building orchestration logic — waiting for a user to complete a consent flow before proceeding. | ||
| - You are implementing Nexus in a language without a Bridge. The REST API is accessible from any HTTP client; the SDK is the Go reference implementation. | ||
|
|
||
| ## Client setup | ||
|
|
||
| ```go | ||
| client := oauthsdk.New( | ||
| "https://your-gateway.internal", | ||
| oauthsdk.WithRetry(oauthsdk.RetryPolicy{ | ||
| Retries: 3, | ||
| MinDelay: 200 * time.Millisecond, | ||
| MaxDelay: 5 * time.Second, | ||
| RetryOn429: true, | ||
| }), | ||
| oauthsdk.WithLogger(yourLogger), | ||
| ) | ||
| ``` | ||
|
|
||
| The SDK never logs token bodies. | ||
|
|
||
| Retries use exponential backoff with jitter. Retryable statuses: `502`, `503`, `504`, and optionally `429`. | ||
|
|
||
| ## The agent credential lifecycle | ||
|
|
||
| Whether you use the SDK directly or via the Bridge, a Nexus-integrated agent follows five phases: | ||
|
|
||
| **1. Resolution** — Fetch the strategy and credentials from the Gateway using the `connection_id`. The response tells you both the credentials and exactly how to apply them to a request. | ||
|
|
||
| ```go | ||
| token, err := client.GetToken(ctx, connectionID) | ||
| strategyType := token.Strategy["type"].(string) // "oauth2", "header", "hmac_payload", etc. | ||
| ``` | ||
|
|
||
| **2. Configuration** — Apply the strategy to your transport layer. For HTTP, inject the appropriate header or query parameter. For gRPC, inject metadata. The Bridge does this automatically; with the SDK you do it manually using the `strategy` and `credentials` fields. | ||
|
|
||
| **3. Maintenance** — Cache the token locally and monitor `ExpiresAt`. Refresh proactively before expiry to avoid latency spikes during active work. Do not wait for a `401` to refresh. | ||
|
|
||
| ```go |
Comment on lines
+3
to
+69
| Nexus is split into a control plane and a data plane. The control plane manages the lifecycle of credentials: registering providers, completing OAuth handshakes, storing tokens, and refreshing them before they expire. The data plane serves credentials to agents when they need them and injects those credentials into outgoing requests. | ||
|
|
||
| Understanding this separation is the mental model for everything else in this documentation. | ||
|
|
||
| --- | ||
|
|
||
| ## The four components | ||
|
|
||
| ### The Broker | ||
|
|
||
| The Broker is the most sensitive component in the system. It is the only service that ever holds refresh tokens or provider API keys. Everything it stores is encrypted at rest using AES-GCM 256-bit with a key you supply and manage. The Broker never sends a refresh token to any other service. When the Gateway asks for credentials, the Broker decrypts the stored token, fetches a fresh access token from the provider, and returns only that. | ||
|
|
||
| The Broker runs a background refresh loop. Before any stored token expires, the Broker fetches a new one using the stored refresh token. If a provider rejects the refresh (for example, because a user revoked access), the Broker transitions that connection to `attention_required` and records the failure in the audit log. The agent does not need to handle this case; it will simply receive an error on the next credential request and can surface it to the user. | ||
|
|
||
| ### The Gateway | ||
|
|
||
| The Gateway is the public-facing API that agents call. It accepts REST and gRPC requests, proxies them to the Broker using an internal API key, and returns the response. Agents never reach the Broker directly. This decoupling means you can expose the Gateway to agents running outside your network without exposing the Broker. | ||
|
|
||
| The Gateway handles CORS, request validation, and API versioning. From an agent's perspective, the Gateway is Nexus. | ||
|
|
||
| ### The Bridge | ||
|
|
||
| The Bridge is a Go library that runs inside your agent process. You instantiate it with a Gateway client, and it handles credential retrieval and request signing automatically. For a persistent WebSocket or gRPC connection, you call `bridge.MaintainWebSocket()` or the gRPC equivalent and the Bridge keeps the connection authenticated through token rotations, including exponential backoff on failures. It also exposes a Prometheus `/metrics` endpoint for operational visibility. | ||
|
|
||
| Use the Bridge when your agent is written in Go and makes ongoing connections to provider services. | ||
|
|
||
| ### The SDK | ||
|
|
||
| The SDK is a thin Go client for the Gateway API. It exposes `GetToken()` and related methods, giving you direct control over credential retrieval without the connection management logic the Bridge provides. Use the SDK when you want to fetch credentials explicitly rather than having them injected automatically, or when you are implementing a non-persistent integration pattern. | ||
|
|
||
| --- | ||
|
|
||
| ## The OAuth handshake flow | ||
|
|
||
| When a user connects a new provider account, the flow runs as follows. | ||
|
|
||
| Your application backend calls `POST /v1/request-connection` on the Gateway, passing the user identifier, the provider name, the requested scopes, and a return URL. The Gateway forwards this to the Broker, which generates a unique `state` parameter signed with the `STATE_KEY` and returns an authorization URL and a `connection_id`. | ||
|
|
||
| Your application redirects the user's browser to the authorization URL. The user authenticates with the provider and grants consent. The provider redirects back to the Broker's callback endpoint, which validates the `state` parameter, exchanges the authorization code for tokens, encrypts the tokens, and stores them in PostgreSQL. | ||
|
|
||
| The Broker then redirects the user's browser to your `return_url` with the `connection_id` and a `status=success` parameter. Your application captures the `connection_id` and stores it. That is the only thing your application needs to hold. The actual tokens stay in the Broker. | ||
|
|
||
| --- | ||
|
|
||
| ## The credential retrieval flow | ||
|
|
||
| When your agent needs to call a provider, the flow is simpler. | ||
|
|
||
| Your agent calls `GET /v1/token/{connection_id}` on the Gateway. The Gateway forwards the request to the Broker, which retrieves the stored tokens, decrypts them in RAM, and returns a credential payload to the Gateway. The payload contains a `strategy` field that describes how to use the credentials and a `credentials` object with the actual values. | ||
|
|
||
| The `strategy` field exists because Nexus supports multiple credential types. An OAuth2 connection returns `{"type": "oauth2"}` with an `access_token`. An API key connection returns `{"type": "api_key"}` with the key value in a field matching the provider's schema. The Bridge handles strategy interpretation automatically. If you are making direct HTTP calls, you inspect `strategy.type` and apply the credentials accordingly. | ||
|
|
||
| --- | ||
|
|
||
| ## Connection states | ||
|
|
||
| A connection moves through a small set of states during its lifetime. | ||
|
|
||
| `pending` is the initial state after `request-connection` returns but before the user has completed consent. `active` is the normal operating state: tokens are valid and the background refresh loop is keeping them current. `attention_required` means the last refresh attempt failed with a provider error that cannot be retried, typically because the user revoked the application's access. `failed` means the initial token exchange failed. | ||
|
|
||
| Your application should surface `attention_required` to the user so they can reconnect the provider account. | ||
|
|
||
| --- | ||
|
|
||
| ## What Nexus does not do | ||
|
|
||
| Nexus does not make API calls to providers on behalf of agents. It provides credentials; agents make the calls. Nexus does not manage authorization within your own application (which users can access which connections). It manages authentication with external providers. Nexus does not run inside your agent. The Bridge is an in-process library, but the Broker and Gateway are network services that you deploy separately. |
Comment on lines
+1
to
+5
| --- | ||
| icon: material/puzzle-edit-outline | ||
| --- | ||
|
|
||
| ## 1. OAuth 2.0 / OIDC Providers | ||
|
|
||
| ### Registration | ||
| # Managing Providers |
|
|
||
|
|
||
| extra: | ||
| version: "0.2.3" |
Agent-Logs-Url: https://github.com/Prescott-Data/nexus-framework/sessions/d1245265-d54d-4860-a245-fccc1535d478 Co-authored-by: ekizito96 <87319861+ekizito96@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment on lines
+1
to
10
| --- | ||
| icon: material/puzzle-edit-outline | ||
| --- | ||
|
|
||
| ## 1. OAuth 2.0 / OIDC Providers | ||
|
|
||
| ### Registration | ||
| # Managing Providers | ||
|
|
||
| The preferred method for registering OIDC-compliant providers is to use the `issuer` URL, which enables auto-discovery of the necessary endpoints. | ||
| A provider in Nexus represents the configuration for a third-party service your agents connect to. This guide covers how to register, update, and delete providers through the Gateway's REST API, and how to list the providers available in your workspace. | ||
|
|
||
| #### **Payload Fields:** | ||
| For declarative provider management using `nexus-cli`, see the [Security-as-Code](security-as-code.md) guide. For production environments where provider configuration is sensitive infrastructure, the declarative approach is preferred. | ||
|
|
Comment on lines
+97
to
+121
| - Security Model: concepts/security-model.md | ||
| - Client Libraries: concepts/client-libraries.md | ||
| - Getting Started: | ||
| - Quick Start: index.md | ||
| - Deployment & Config: deployment.md | ||
| - Component Deep Dives: | ||
| - Nexus Broker: services/broker.md | ||
| - Nexus Gateway: services/gateway.md | ||
| - Nexus Bridge: services/bridge.md | ||
| - SDKs: | ||
| - Overview: sdks/index.md | ||
| - Deploy in Five Minutes: getting-started/quickstart.md | ||
| - Configuration: getting-started/configuration.md | ||
| - Your First Connection: getting-started/first-connection.md | ||
| - Guides: | ||
| - Providers: guides/registering-a-provider.md | ||
| - Integrating Agents: guides/integrating-agents.md | ||
| - Go SDK: sdks/go.md | ||
| - TypeScript SDK: sdks/typescript.md | ||
| - Python SDK: sdks/python.md | ||
| - Guides: | ||
| - Agent Integration: guides/integrating-agents.md | ||
| - Agent Sessions: guides/agent-sessions.md | ||
| - Static Credential Flow: guides/static-credentials.md | ||
| - OBO Delegation: guides/obo-delegation.md | ||
| - MCP Server Integration: guides/mcp-integration.md | ||
| - Managing Providers: guides/managing-providers.md | ||
| - Security-as-Code (nexus-cli): guides/security-as-code.md | ||
| - API Reference: | ||
| - API Overview: reference/api.md | ||
| - Handling Attention State: guides/attention-state.md | ||
| - Troubleshooting: guides/troubleshooting.md | ||
| - Security-as-Code: guides/security-as-code.md | ||
| - Deploying Nexus: infrastructure/deploying-nexus.md | ||
| - Reference: | ||
| - API Reference: reference/api.md | ||
| - CLI Reference: reference/cli.md | ||
| - Audit Log: reference/audit-log.md | ||
| - Technical Debt & Roadmap: reference/tech-debt.md | ||
| - Security Model: reference/security-model.md |
Comment on lines
+22
to
+75
| if (chip) { | ||
| fetch('https://api.github.com/repos/Prescott-Data/nexus-framework/tags') | ||
| .then(function (r) { return r.json(); }) | ||
| .then(function (tags) { | ||
| if (Array.isArray(tags) && tags.length > 0) { | ||
| var latestVersion = tags[0].name; | ||
| if (chip) chip.textContent = latestVersion; | ||
|
|
||
| /* Also update hero badge if present */ | ||
| var heroBadge = document.getElementById('nx-hero-version-badge'); | ||
| if (heroBadge) { | ||
| heroBadge.innerHTML = latestVersion + ' · Apache 2.0 · Production Ready'; | ||
| } | ||
| } | ||
| }) | ||
| .catch(function () { | ||
| /* On network failure, hide chip entirely rather than showing stale data */ | ||
| if (chip) chip.style.display = 'none'; | ||
| }); | ||
| } | ||
|
|
||
| /* ── 2. GitHub stars widget ─────────────────────────── */ | ||
| var inner = document.querySelector('.md-header__inner'); | ||
| var palette = document.querySelector('form[data-md-component="palette"]'); | ||
| var existingGhBtn = document.querySelector('.nx-gh-btn'); | ||
|
|
||
| // Skip if already injected (instant navigation guard) | ||
| if (inner && palette && !existingGhBtn) { | ||
| var ghBtn = document.createElement('a'); | ||
| ghBtn.href = 'https://github.com/Prescott-Data/nexus-framework'; | ||
| ghBtn.target = '_blank'; | ||
| ghBtn.rel = 'noopener noreferrer'; | ||
| ghBtn.className = 'nx-gh-btn'; | ||
| ghBtn.setAttribute('aria-label', 'Star Nexus on GitHub'); | ||
| ghBtn.innerHTML = | ||
| '<span class="nx-gh-repo">Prescott-Data/nexus</span>' + | ||
| '<span class="nx-gh-sep">★</span>' + | ||
| '<span class="nx-stars-count">—</span>'; | ||
|
|
||
| inner.insertBefore(ghBtn, palette); | ||
| inner.appendChild(palette); | ||
| } | ||
|
|
||
| /* ── 3. Async star count ────────────────────────────── */ | ||
| fetch('https://api.github.com/repos/Prescott-Data/nexus-framework') | ||
| .then(function (r) { return r.json(); }) | ||
| .then(function (data) { | ||
| var el = document.querySelector('.nx-stars-count'); | ||
| if (el && typeof data.stargazers_count === 'number') { | ||
| var n = data.stargazers_count; | ||
| el.textContent = n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n); | ||
| } | ||
| }) | ||
| .catch(function () {}); |
|
|
||
|
|
||
| extra: | ||
| version: "0.2.3" |
Copilot stopped work on behalf of
sangalo20 due to an error
May 18, 2026 07:18
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
Description
Complete overhaul of the Nexus Documentation Hub for better DX. Restructured information architecture, fixed critical mobile responsiveness bugs, added missing content (changelog, troubleshooting, client libraries), and brought footer/sidebar/header parity with the JarvisCore doc site.
Type of Change
Changes Made
Navigation & Architecture (
mkdocs.yml)navigation.expandto prevent mobile drawer bloatdiscord.gg/AbskSXypq)llm-assist.jsinextra_javascriptNew Content
docs/CHANGELOG.md— rebuilt from real git history with accurate contributors and datesdocs/guides/troubleshooting.md— covers stack startup, OAuth, credentials, sessions, CLI, encryptiondocs/concepts/client-libraries.md— SDK concept overview pagedocs/javascripts/llm-assist.js— copy-as-markdown and view-as-markdown widget on every pageMobile Responsiveness (
docs/stylesheets/extra.css)pointer-events: noneon section labels to desktop only (min-width: 76.25em) — was killing Home/Concepts/Guides/Reference clickability in mobile drawer.md-nav__titleinteractivity on mobile (back button)Header (
docs/javascripts/header.js)…while loading, hides on network failureReference Pages
material/icon frontmatter to API, CLI, Audit Log, Security Model pageswhite-space: nowrapto prevent wrappingHow to Test
cd docs/ && rm -rf site/ && python3 -m mkdocs serve --dev-addr=127.0.0.1:8765v0.2.0), not a hardcoded valueMigration / Breaking Changes
Checklist