Connections, Contribution & Org Governance¶

CortexBuild connects to the services your repository depends on, tracks what you work on, and governs features by license — all local-first, secrets-in-the-OS-keychain, and privacy-first. This page is the operator guide for those surfaces (Phase 6).

One-line trust model. Credential values live only in your operating system's keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service). CortexBuild's files store only references — never a secret, never a token, never committed.

1. Connecting services¶

CortexBuild detects the connectable services your repo references and helps you store credentials safely.

Detect¶

cortexbuild connections detect

Detection is read-only and offline. It infers services from:

the git remote host (github.com, dev.azure.com / *.visualstudio.com, bitbucket.org),
CI / IaC fingerprint files (azure-pipelines.yml, bitbucket-pipelines.yml, .github/workflows, cdk.json, serverless.yml, SAM template.yaml),
cloud-SDK dependencies (boto3, @aws-sdk/, aws-cdk-lib) in requirements.txt / pyproject.toml / package.json / go.mod,
the names of variables declared in .env.example / .env.sample / .env.template (never the real .env, never a value).

Connect¶

cortexbuild connections connect github --account my-org
cortexbuild connections connect aws --account prod

The connect flow shows a per-service guide (where to mint the credential, the scopes it needs), then prompts for each credential field directly in the terminal. Secret fields are hidden (hide_input); the value is never passed as an argument, echoed, or sent through a model.

Multi-field services¶

Several services need more than one field — CortexBuild prompts for each and stores them as a set:

Service	Fields	Notes
GitHub	`GITHUB_TOKEN`	Fine-grained or classic PAT
Azure DevOps	`AZURE_DEVOPS_PAT`	Personal access token
Jira / Atlassian	`JIRA_BASE_URL` (config), `JIRA_EMAIL` (config), `JIRA_API_TOKEN` (secret)	Basic auth = site URL + email + token
Bitbucket	`BITBUCKET_USERNAME` (config), `BITBUCKET_APP_PASSWORD` (secret)	Username + app password
AWS	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` (optional)	Prefer short-lived STS/SSO credentials

The primary field is stored under the plain account; additional fields are stored under account#ENV_VAR in the keychain. The manifest records only which env-var names were stored — never the values.

Connect with OAuth (no PAT)¶

For GitHub and Atlassian you can connect via the OAuth 2.0 device flow instead of pasting a long-lived token — you approve a short code in the browser and CortexBuild stores a short-lived access token (plus a refresh token):

cortexbuild connections grant-auth --operator you@example.com   # one-time consent
export CORTEXBUILD_GITHUB_CLIENT_ID=<your-oauth-app-client-id>
cortexbuild connections connect-oauth github --account my-org
# → open the URL, enter the code; the token lands in your keychain

A one-time grant-auth records a dedicated connect-auth consent — OAuth network calls are fail-closed without it (zero bytes leave otherwise).
The OAuth-app client id is public and comes from CORTEXBUILD_<SERVICE>_CLIENT_ID or --client-id — it is never a secret.
doctor auto-refreshes an expiring OAuth token from its stored refresh token (when the connect-auth consent is on record), so you rarely re-approve.

Connect AWS with short-lived STS credentials (no long-lived keys)¶

Instead of storing a long-lived AWS access key, mint short-lived STS session credentials from your ambient AWS identity (env vars, a named profile, or SSO):

pip install cortexbuild-core[aws]
cortexbuild connections grant-auth --operator you@example.com   # one-time
cortexbuild connections connect-aws-sts --account prod --duration 3600
# → 3 short-lived fields (key id + secret + session token) land in your keychain

Uses sts:GetSessionToken against your existing AWS identity — no new long-lived keys are created. The credentials carry an expiry, so doctor warns before they lapse.
doctor --verify checks AWS via sts:GetCallerIdentity (it reports the caller ARN) rather than a bearer GET. boto3 is lazily imported behind the [aws] extra; the call is egress-gated by the same connect-auth consent.

Inspect & verify¶

cortexbuild connections list      # required vs connected (no secrets)
cortexbuild connections doctor    # verify every field resolves in the keychain
cortexbuild connections guide aws # show the fields + scopes for a service

doctor reports missing fields per connection and exits non-zero if anything is unresolved — it never prints a secret.

Token expiry awareness¶

You can record an optional expiry when connecting, and doctor will warn before a token lapses (offline, no network call):

cortexbuild connections connect github --account my-org --expires 2026-12-31
cortexbuild connections doctor   # warns "expires in 12d", or fails on EXPIRED

A connection with a recorded expiry within 14 days is flagged as expiring; a past date is EXPIRED and makes doctor exit non-zero so you rotate it.

Live verification¶

doctor --verify goes a step further and calls each provider's identity endpoint to confirm the token still authenticates (not just that it exists). It is opt-in and egress-gated — it only runs when a connect-auth consent is on record:

cortexbuild connections grant-auth --operator you@example.com   # one-time
cortexbuild connections doctor --verify
# → "live: valid" / "live: rejected (HTTP 401) — rotate the token"

GitHub, Atlassian/Jira, Azure DevOps, and Bitbucket support live verification; AWS falls back to a presence check (its identity call requires request signing). The token is read from the keychain only to build the request and is never printed; without consent, the check is skipped (zero bytes leave).

Validate & monitor from the Web UI¶

Everything doctor does is also available in the local dashboard. With the control plane running (cortexbuild serve) open the Connections page and use the Validate configuration card:

Re-check — confirms every recorded connection still resolves in your OS keychain and flags expiring/expired tokens. No egress; no secret leaves the keychain (only a per-connection resolves / expiring / expired badge is shown).
Live verify — the dashboard equivalent of doctor --verify: it calls each provider to confirm the credential still works. It is egress-gated exactly like the CLI — it runs only when a connections grant-auth consent is already on record, and is otherwise shown as skipped (the browser never grants consent and never performs egress on its own).

The card surfaces the same health via the loopback-only GET /connections/doctor endpoint (?verify=1 for the live check). The endpoint is secret-free — it returns presence + expiry + liveness status only, never a token — and refuses any non-loopback client. The Usage page complements this with run/command monitoring.

Disconnect¶

cortexbuild connections disconnect github --account my-org

Removes every stored field for that connection from the keychain and drops it from the manifest.

2. Injecting credentials into your agent tools¶

CortexBuild is tool-agnostic: it makes a stored credential available to whichever agent tool you drive — Claude Code, OpenAI Codex, GitHub Copilot (VS Code), or Cursor.

cortexbuild connections tools                       # detect tools + injectable env vars
cortexbuild connections wire claude                 # additive MCP config references
cortexbuild connections launch -- <command> [args]  # run a command with creds injected

launch resolves the keychain secrets and passes them only in the child process's environment for the duration of the run. They never touch disk and are never printed.
wire records env-var-NAME references ("${GITHUB_TOKEN}") in the tool's MCP config under a namespaced cortexbuild-credentials entry — an additive, non-clobbering merge that unwire fully reverses. No secret is written.

Least-privilege scoping¶

By default launch and wire expose every connected service's credentials. Use --service (repeatable) to restrict injection to only the services a given tool needs — so a tool that only talks to GitHub never receives your AWS or Jira credentials:

cortexbuild connections launch --service github -- claude
cortexbuild connections wire copilot --service github --service azure_devops

Fail-closed behaviour¶

If the OS keychain is unavailable (the [connections] extra is not installed, or the host has no usable backend — headless, locked, or unconfigured CI), every operation fails with a clear CredentialVaultUnavailable error. There is no plaintext fallback — CortexBuild will never write a secret to a file.

3. Contribution & focus tracking¶

CortexBuild derives which features, domains, and technologies you work on from git history — anonymous by default, counts and tags only, no file contents or commit messages.

cortexbuild contribution focus      # top areas + technologies (this repo)
cortexbuild contribution snapshot   # append a PII-free snapshot to the history
cortexbuild contribution history    # show the trajectory over time

Anonymous by default. Author identity is included only with an explicit --by-author flag, and CortexBuild never reads git config user.email.
Hash-chained, commit-anchored history at .cortexbuild/contributions/history.jsonl — tamper-evident, no wall-clock, deterministic. Author identity is never written to this file.

The dashboard Focus page renders the same data with area/technology bar charts and a snapshot trajectory.

4. License-based feature governance (enterprise)¶

Features are governed by a signed, super-admin-authored entitlement registry mapping plans to feature sets.

cortexbuild auth entitlements        # show the features your license enables

Plan	Adds
`free`	Local single-repo essentials: render, ledger, conformance, onboard, memory.local, mcp, a2a, usage.local, orchestrate.simulated, connections.personal, contribution.personal
`pro`	+ orchestrate.live (BYOK), providers.cloud, tooling.inject, insights.aggregate, contribution.focus_advanced, multi_repo
`enterprise`	+ org.central_service, org.governance, org.dashboards_fleet, memory.hosted, contribution.team_visible, standards.org_sync

Fail-closed: an absent / invalid / expired license, or an unknown plan, resolves to the minimal free set. A dev/CI license bypass also resolves to free — it disables the gate, it never grants a paid plan.
Org-admin overlay (enterprise). An org admin can further restrict which features a specific user gets via a signed .cortexbuild/org-policy.yaml. The overlay is clamp-only — it can only subtract from the plan ceiling, never escalate above it. Every change is recorded as a govern audit event.
Enforcement. The backend is the authority: a disabled feature is refused at the CLI, returns 403 at the control-plane, and is hidden in the UI nav — all resolved from the one registry. UI hiding is cosmetic; the backend always enforces.

5. Org-level rollup (enterprise, opt-in)¶

For an enterprise fleet, each machine can emit a redacted, numeric/tag-only rollup (usage counts, contribution area/tech counts, per-service connection coverage) to a self-managed central collector. There are no secrets, no code, no PII, and no author identity in a rollup.

Emission routes through the existing consent-gated telemetry choke-point — without a telemetry consent, zero bytes leave the machine.
The central service is enterprise-license-gated and operator-opt-in, never a mandatory hosted tier. It refuses to ingest or serve without an enterprise license, and rejects any rollup that contains a secret-shaped value.
The dashboard Org page renders the aggregated fleet view (machine count, top areas, per-service connection coverage) for org/super-admins only.

6. Agent observability (OpenTelemetry GenAI, opt-in)¶

CortexBuild can emit OpenTelemetry GenAI spans (gen_ai.* semantic conventions) for orchestrator runs, so an org can view agent activity in any OTel-compatible backend alongside the rest of its telemetry. This complements — never replaces — the tamper-evident hash-chained audit trail.

pip install cortexbuild-core[otel]
export CORTEXBUILD_OTEL=1          # or create .cortexbuild/otel/enabled
# orchestrator runs now emit gen_ai.orchestrate spans

Opt-in + best-effort — disabled by default; an emission failure never breaks a run. The OTel SDK is lazily imported, so the default install pulls no OTel dependency.
PII-free — spans carry operation/system/decision/mode + numeric token counts only, never prompts, code, or arguments.

Where things live¶

Data	Location	Contains
Credential values	OS keychain	the secrets (never on disk)
Connection references	`.cortexbuild/connections.yaml` (gitignored)	service, account, keychain-entry name, env-var names, scopes
Usage events	`.cortexbuild/usage/events.jsonl` (gitignored, opt-in)	command names + outcomes
Contribution history	`.cortexbuild/contributions/history.jsonl` (gitignored)	area/tech tags + counts, hash-chained
Entitlement override	`.cortexbuild/entitlements.yaml` (signed)	plan→feature map
Org policy overlay	`.cortexbuild/org-policy.yaml` (signed)	per-user feature clamp