spec: canonical-channel-access-v1 (DRAFT) — one-system access architecture#79
spec: canonical-channel-access-v1 (DRAFT) — one-system access architecture#79chitcommit wants to merge 2 commits into
Conversation
…cture
Canonical contract for how any channel acquires credentials to call a
ChittyOS service. Single broker (ChittyConnect), audience-scoped ephemeral
tokens, deprecates the shared CHITTY_AUTH_SERVICE_TOKEN pattern.
Implementation status (per §0.1):
- LIVE today on connect.chitty.cc (verified at chittyconnect/src/api/router.js:146-197,
auth header X-ChittyOS-API-Key):
/api/credentials/{provision,types,health,audit,revoke}
/api/v1/sessions/*, /api/auth/keys/*, /api/connections/*,
/api/v1/connect/*, /api/execute
- PROPOSED (tracked in chittyconnect#364, returns 404 today; do NOT consume):
/api/v1/tokens/mint, /api/v1/tokens/verify,
/api/v1/channels/register, /api/v1/channels/{id}/rotate-key
Issue closures (chittyconnect#231, chittyentity#343) are gated on §9.3 —
mint/verify routes verified live in production. References chittyentity#306
(parked tracking task).
Status: DRAFT. Owner: chittycanon://core/services/connect.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
More reviews will be available in 4 minutes and 37 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
|
@coderabbitai review |
There was a problem hiding this comment.
Pull request overview
Adds a DRAFT “canonical contract” spec that standardizes how all channel surfaces acquire credentials via ChittyConnect (broker-scoped keys → audience-scoped short-lived tokens), and documents the deprecation/migration away from the shared CHITTY_AUTH_SERVICE_TOKEN pattern.
Changes:
- Introduces a new canonical spec covering registration, token mint/verify, recovery routine, and operator-visibility gating.
- Documents the Tier 2+ migration pattern to minted-token verification (
verifyMintedToken/@chittyos/connect-verify). - Proposes a new compliance dimension (
channel-access-pattern) and its intended detection signal.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| This pattern is the root cause of the false-alarm issues | ||
| chittyconnect#231 / chittyentity#343. The shared token in 1Password vault | ||
| `ChittyOS/CHITTY_AUTH_SERVICE_TOKEN` (`ca1d75…`) does not match what is | ||
| deployed in the worker's `env.CHITTY_AUTH_SERVICE_TOKEN`. The drift is invisible |
| `@chittyos/connect-verify` is published by chittyconnect; offline JWT verify | ||
| with a 24h cache of ChittyConnect's signing key (KV: `connect:jwks`). One |
| 3. **Verify live**: `curl -fsS connect.chitty.cc/api/v1/tokens/mint` and | ||
| `/verify` return non-404 with documented shapes; record evidence in PR | ||
| body. This is the gate for §8 issue closure. |
| Add to `chittyops/compliance/checks.yml`: | ||
|
|
||
| ```yaml | ||
| channel-access-pattern: | ||
| description: | | ||
| Tier 2+ services must verify ChittyConnect-minted tokens (audience+scope), | ||
| NOT compare against a shared env.CHITTY_AUTH_SERVICE_TOKEN. | ||
| applies_to_tier: [2, 3, 4, 5] | ||
| signal: | ||
| - file: src/auth.ts (or equivalent) | ||
| - must_contain: "verifyMintedToken" OR "connect-verify" | ||
| # The live deprecated pattern in chittyagent-tasks/src/auth.ts:7 is | ||
| # h.slice(7) !== c.env.CHITTY_AUTH_SERVICE_TOKEN | ||
| # so the signal must catch any reference to the shared env var, not just | ||
| # a single equality form. | ||
| - must_not_contain_regex: "c\\.env\\.CHITTY_AUTH_SERVICE_TOKEN|env\\.CHITTY_AUTH_SERVICE_TOKEN" | ||
| remediation_template: templates/migrate-to-minted-auth.md | ||
| ``` |
| | **Cloudflare Worker** | `wrangler deploy` post-hook, registers as `did:chitty:channel:worker-<name>-<env>` | Worker secret `CHITTYCONNECT_BROKER_KEY` (set by chittyops reusable deploy workflow) | | ||
| | **GitHub Actions** | Workflow `getchitty-creds` action runs registration if no cached channel_id | Repo secret `CHITTYCONNECT_API_KEY` | | ||
| | **Homelab node** | `chittymarket-sync-daemon.sh` on first boot | `~/.ops/channel-broker-key` (mode 600, written by registration response) | | ||
| | **ChatGPT cloud MCP** | Gateway-mediated registration via `ch1tty.com/mcp` (server-side policy + sync, per global CLAUDE.md Capability Registration §) | ChittyConnect-held; never exposed to the client | |
…8 #306 status §3: prepend note that recovery routine is valid once §0.1 proposed routes ship; legacy shared-token path applies until then (per §4). §8 chittyentity#306: update bullet to reflect emit already landed via legacy path (task_id dadb508b-0420-4d36-aa71-a09f5b3f1439, privileged/legalink). #306 stays open as the §4 migration anchor; closure ties to §9.3. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
DRAFT canonical contract for how every channel (VM Claude Code, Workers, mobile, ChatGPT cloud MCP, homelab, future models) acquires credentials — single broker (ChittyConnect), audience-scoped ephemeral tokens, deprecates the shared CHITTY_AUTH_SERVICE_TOKEN pattern.
Implementation status (§0.1)
Live on connect.chitty.cc — verified at chittyconnect/src/api/router.js:146-197, auth header X-ChittyOS-API-Key:
Proposed — tracked in chittyconnect#364, returns 404 today; do NOT consume:
agent.chitty.cc/api/v1/channels/register is a target alias once chittyconnect#364 lands.
Issue closure (gated)
Per §8/§9, chittyconnect#231 and chittyentity#343 close only after §9.3 verifies mint/verify routes live in production. References chittyentity#306 (parked).
Companion PR
chittyentity#372 — corrects stale host + vault in INGESTION.md, marks shared-token Authorization line DEPRECATED inline.
Test plan
🤖 Generated with Claude Code