| uri | chittycanon://docs/ops/policy/chittyconnect-charter |
|---|---|
| namespace | chittycanon://docs/ops |
| type | policy |
| version | 1.0.0 |
| status | CERTIFIED |
| registered_with | chittycanon://core/services/canon |
| title | ChittyConnect Charter |
| certifier | chittycanon://core/services/chittycertify |
| visibility | PUBLIC |
- Canonical URI:
chittycanon://core/services/chittyconnect - Tier: 2 (Platform)
- Organization: CHITTYOS
- Domain: connect.chitty.cc
ChittyConnect is the AI-intelligent spine (itsChitty™) for the ChittyOS ecosystem with ContextConsciousness™ and MemoryCloude™. It provides the comprehensive connector enabling custom GPTs, Claude, and third-party integrations to interact with the entire ChittyOS ecosystem.
- Custom GPT Actions API with OpenAPI specification
- MCP (Model Context Protocol) server for Claude integration
- GitHub App integration with fast-ack webhook processing
- Third-party integration proxy (Notion, OpenAI, Neon, Google Calendar, Cloudflare AI)
- ContextConsciousness™ - Cross-session context maintenance
- MemoryCloude™ - Persistent memory for Claude interactions
- Service health monitoring across ChittyOS ecosystem
- API key management and rate limiting
- ChittyID minting coordination
- Legal case management via ChittyCases
- Evidence ingestion via ChittyEvidence
- User profile store — canonical writer for
neon_auth.user,neon_auth.account,neon_auth.session,neon_auth.verificationon Neon projectrestless-grass-40598426(ChittyOS-Core). Validates inbound Bearer JWTs against the ChittyAuth JWKS (auth.chitty.cc) and applies RLS bound to the verifiedsub(ChittyID DID). Seesrc/auth/neon-user-store.jsandmigrations/019_neon_auth_user_store.sql. - Multi-tenant org membership — canonical writer for
neon_auth.organization,neon_auth.member,neon_auth.invitation. Per-org RLS predicates derive from the caller's membership rows.
Neon Auth ownership split (binding). ChittyConnect owns the seven tables enumerated above; ChittyAuth owns
neon_auth.jwksandneon_auth.project_configperchittyauth/CHARTER.md:60-84and the canon proposalchittycanon://proposal/neon-auth-ownership-split. This service does NOT write tojwksorproject_configunder any circumstance.
- Direct identity generation (ChittyID)
- Token provisioning (ChittyAuth)
- Service registration (ChittyRegister)
- Certificate authority (ChittyTrust)
- Evidence verification (ChittyVerify)
- Event storage (ChittyChronicle)
- OpenAPI 3.0 specification at
/openapi.json - ChittyOS service proxying
- Third-party API unification
- Model Context Protocol tools
- Real-time resource access
- ContextConsciousness™ state
- Fast-ack webhook processing
- MCP normalization
- Issue/PR automation
| Type | Service | Purpose |
|---|---|---|
| Upstream | ChittyID | Identity minting |
| Upstream | ChittyAuth | Token validation |
| Upstream | ChittyRegistry | Service discovery |
| Peer | ChittyChronicle | Event logging |
| Peer | ChittyFinance | Banking integrations |
| Peer | ChittyCases | Case management |
| Peer | ChittyEvidence | Evidence management |
| Peer | ChittyLedger | Transaction recording |
| External | Notion API | Database operations |
| External | OpenAI API | Chat completions |
| External | Google Calendar | Event management |
| External | Neon Database | SQL queries |
Base URL: https://connect.chitty.cc
| Endpoint | Method | Purpose |
|---|---|---|
/health |
GET | Service health |
/openapi.json |
GET | OpenAPI specification |
/api/chittyid/mint |
POST | Mint ChittyID |
/api/chittyid/validate |
POST | Validate ChittyID |
/api/services/status |
GET | All services status |
/api/thirdparty/notion/query |
POST | Query Notion |
/api/thirdparty/openai/chat |
POST | OpenAI proxy |
| Endpoint | Method | Purpose |
|---|---|---|
/mcp/manifest |
GET | Server manifest |
/mcp/tools/list |
GET | Available tools |
/mcp/tools/call |
POST | Execute tool |
/mcp/resources/list |
GET | Available resources |
/mcp/resources/read |
GET | Read resource |
chittyid_mint- Mint ChittyIDs with contextchitty_contextual_analyze- ContextConsciousness™ analysischitty_case_create- Create legal caseschitty_evidence_ingest- Ingest evidencechitty_services_status- Monitor ecosystem healthchitty_finance_connect_bank- Connect banking
Note (2026-06): Prior revisions of this CHARTER proposed adding
git_commit,git_push,git_tagas MCP tools here. That framing is withdrawn. ChittyConnect is a broker (authorization server + credential broker), not an MCP tool host. Allgit_*MCP tools (read and write) live onchittyagent-git(the resource server). ChittyConnect exposes REST broker primitives that the resource server calls into. See "Git Broker Surface (REST, sensitive)" below.The legacy
/mcp/*endpoints on this service are deprecated and slated for removal; do not extend them.
Status: SPEC — these REST broker primitives are NOT YET IMPLEMENTED. Implementation tracked in #209.
Architecture (binding). ChittyConnect is an authorization server + credential broker, not an MCP tool host. The MCP surface for git lives on
chittyagent-git(the resource server, Cloudflare Worker inchittyentity), which exposes ALL git tools — both read (git_status,git_log,git_diff,git_show,git_blame,git_branch_list) and write (git_commit,git_push,git_tag).chittymcp/ch1ttyfederate that worker for discovery + transport but carry no policy.The endpoints below are the broker primitives the resource server calls back into. ChittyConnect never sits on the client→worker call path: the client carries a capability token, the worker validates it here and requests signing / ledger emission as needed.
Signing is mandatory and non-overridable for commit and tag operations. Signing keys are resolved from chittysecrets and never leave the broker; only the produced signature is returned.
Mint a short-TTL capability token scoped to a single caller × tenant × repo ×
operation × ref. Tokens are opaque to clients; their claims are obtained via
introspect. Capabilities are bound to a granular operation
(read | commit | tag | push) and MAY NOT be reused for a different action —
a commit capability cannot sign a tag or emit a push event. For
operation = "push" with force_class != "none", a fresh confirmation token
from /api/v1/capabilities/confirm is required.
{
"name": "capabilities.mint",
"input_schema": {
"type": "object",
"required": ["caller_chittyid", "tenant_id", "operation", "repo_path"],
"additionalProperties": false,
"properties": {
"caller_chittyid": { "type": "string", "pattern": "^[A-Z0-9]{2}-[A-Z0-9]-[A-Z0-9]{3}-[A-Z0-9]{4}-[PLTEA]-[0-9]{4}-[0-5]-[0-9]{2}$", "description": "Canonical ChittyID VV-G-LLL-SSSS-T-YYMM-C-XX per chittycanon://gov/governance. T in {P,L,T,E,A}; YYMM is year-month; C is trust level 0-5; XX is mod-97 checksum." },
"tenant_id": { "type": "string", "minLength": 1, "maxLength": 128 },
"operation": { "type": "string", "enum": ["read", "commit", "tag", "push"] },
"repo_path": { "type": "string", "minLength": 1, "description": "Absolute path; validated against tenant repo allowlist." },
"remote": { "type": "string", "description": "Required when operation='push'." },
"ref": { "type": "string", "description": "Required when operation ∈ {commit, tag, push}. Concrete ref (e.g. refs/heads/main, refs/tags/v1.2.3) the capability binds to." },
"force_class": { "type": "string", "enum": ["none", "force", "force_with_lease"], "default": "none" },
"confirmation_token": { "type": "string", "description": "Required when operation='push' AND force_class != 'none'." }
},
"allOf": [
{
"if": {
"properties": { "operation": { "enum": ["commit", "tag", "push"] } },
"required": ["operation"]
},
"then": { "required": ["ref"] }
},
{
"if": {
"properties": { "operation": { "const": "push" } },
"required": ["operation"]
},
"then": { "required": ["remote"] }
},
{
"if": {
"properties": { "force_class": { "enum": ["force", "force_with_lease"] } },
"required": ["force_class"]
},
"then": { "required": ["confirmation_token"] }
}
]
},
"output_schema": {
"type": "object",
"required": ["token", "token_type", "expires_at", "scope"],
"additionalProperties": false,
"properties": {
"token": { "type": "string", "description": "Opaque capability token. MUST NOT be logged or echoed in error envelopes." },
"token_type": { "type": "string", "const": "chittyconnect-capability" },
"expires_at": { "type": "string", "format": "date-time", "description": "TTL <= 300s." },
"scope": {
"type": "object",
"required": ["caller_chittyid", "tenant_id", "operation", "repo_path"],
"additionalProperties": false,
"properties": {
"caller_chittyid": { "type": "string" },
"tenant_id": { "type": "string" },
"operation": { "type": "string", "enum": ["read", "commit", "tag", "push"] },
"repo_path": { "type": "string" },
"remote": { "type": "string" },
"ref": { "type": "string" },
"force_class": { "type": "string", "enum": ["none", "force", "force_with_lease"] }
}
}
}
}
}Validate a capability token and return its claims. Resource servers
(chittyagent-git) call this on every inbound request before performing any
git operation. Fail-closed if unreachable.
{
"name": "capabilities.introspect",
"input_schema": {
"type": "object",
"required": ["token"],
"additionalProperties": false,
"properties": { "token": { "type": "string" } }
},
"output_schema": {
"type": "object",
"required": ["active"],
"additionalProperties": false,
"properties": {
"active": { "type": "boolean" },
"expires_at": { "type": "string", "format": "date-time" },
"scope": {
"type": "object",
"required": ["caller_chittyid", "tenant_id", "operation", "repo_path", "remote", "force_class"],
"additionalProperties": false,
"properties": {
"caller_chittyid": { "type": "string" },
"tenant_id": { "type": "string" },
"operation": { "type": "string", "enum": ["read", "commit", "tag", "push"] },
"repo_path": { "type": "string" },
"remote": { "type": "string" },
"ref": { "type": "string" },
"force_class": { "type": "string", "enum": ["none", "force", "force_with_lease"] }
}
}
},
"if": { "properties": { "active": { "const": true } }, "required": ["active"] },
"then": { "required": ["scope"] }
}
}Issue a short-TTL confirmation token. Required as a second factor before
minting a capability with force_class != "none". Confirmation tokens are
single-use and bound to caller+tenant+repo+remote+ref+force_class. A
confirmation issued for one (remote, ref) pair (e.g. origin +
refs/heads/feature) CANNOT be redeemed to force-push a different ref
(e.g. refs/heads/main) — the resource server MUST reject scope-mismatched
tokens with POLICY_BLOCKED_CONFIRMATION_INVALID.
{
"name": "capabilities.confirm",
"input_schema": {
"type": "object",
"required": ["caller_chittyid", "tenant_id", "repo_path", "remote", "ref", "force_class"],
"additionalProperties": false,
"properties": {
"caller_chittyid": { "type": "string" },
"tenant_id": { "type": "string" },
"repo_path": { "type": "string" },
"remote": { "type": "string", "description": "Remote the confirmation authorizes (e.g. 'origin')." },
"ref": { "type": "string", "description": "Concrete ref the confirmation authorizes (e.g. refs/heads/feature). NOT interchangeable across refs." },
"force_class": { "type": "string", "enum": ["force", "force_with_lease"] }
}
},
"output_schema": {
"type": "object",
"required": ["confirmation_token", "expires_at", "bound_scope"],
"additionalProperties": false,
"properties": {
"confirmation_token": { "type": "string" },
"expires_at": { "type": "string", "format": "date-time", "description": "TTL <= 120s." },
"bound_scope": {
"type": "object",
"required": ["caller_chittyid", "tenant_id", "repo_path", "remote", "ref", "force_class"],
"additionalProperties": false,
"properties": {
"caller_chittyid": { "type": "string" },
"tenant_id": { "type": "string" },
"repo_path": { "type": "string" },
"remote": { "type": "string" },
"ref": { "type": "string" },
"force_class": { "type": "string", "enum": ["force", "force_with_lease"] }
},
"description": "Echo of the exact (caller, tenant, repo, remote, ref, force_class) tuple this token binds to. Mint MUST reject if any field differs."
}
}
}
}Produce a detached signature over the canonical commit payload supplied by the
resource server. The signing key (resolved from chittysecrets by the broker) never
leaves ChittyConnect. The resource server MUST present a valid capability
token whose scope satisfies operation="commit" and matches repo_path and ref. A capability minted for tag or push is rejected.
{
"name": "signing.sign-commit",
"input_schema": {
"type": "object",
"required": ["capability_token", "repo_path", "commit_payload"],
"additionalProperties": false,
"properties": {
"capability_token": { "type": "string" },
"repo_path": { "type": "string" },
"commit_payload": { "type": "string", "description": "Canonical pre-signature commit object bytes (tree, parents, author, committer, message), base64-encoded." }
}
},
"output_schema": {
"type": "object",
"required": ["signature", "key_fingerprint"],
"additionalProperties": false,
"properties": {
"signature": { "type": "string", "description": "ASCII-armored signature block." },
"key_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the signing public key. Non-sensitive identifier; safe to log. The actual signing key reference (op:// path / chittysecrets UUID) is broker-internal and MUST NEVER appear in any response, ledger payload, or error envelope." }
}
}
}Same shape as sign-commit but signs an annotated-tag object payload. The presented capability MUST have operation="tag" and matching repo_path + ref; capabilities for commit or push are rejected.
{
"name": "signing.sign-tag",
"input_schema": {
"type": "object",
"required": ["capability_token", "repo_path", "tag_payload"],
"additionalProperties": false,
"properties": {
"capability_token": { "type": "string" },
"repo_path": { "type": "string" },
"tag_payload": { "type": "string", "description": "Canonical pre-signature tag object bytes, base64-encoded." }
}
},
"output_schema": {
"type": "object",
"required": ["signature", "key_fingerprint"],
"additionalProperties": false,
"properties": {
"signature": { "type": "string" },
"key_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hex digest of the signing public key. Non-sensitive; safe to log." }
}
}
}Resolve tenant policy: allowed repos, allowed remotes, force-push gates, default author identity. Called by the resource server during admission.
{
"name": "policy.resolve",
"input_schema": {
"type": "object",
"required": ["tenant_id", "caller_chittyid", "operation"],
"additionalProperties": false,
"properties": {
"tenant_id": { "type": "string" },
"caller_chittyid": { "type": "string" },
"operation": { "type": "string", "enum": ["read", "commit", "tag", "push"] }
}
},
"output_schema": {
"type": "object",
"required": ["allowed_repos", "allowed_remotes", "force_push_allowed", "protected_branches"],
"additionalProperties": false,
"properties": {
"allowed_repos": { "type": "array", "items": { "type": "string" }, "description": "Absolute path globs." },
"allowed_remotes": { "type": "array", "items": { "type": "string" }, "description": "URL globs (e.g. github.com/CHITTYOS/*)." },
"force_push_allowed": { "type": "boolean" },
"protected_branches": { "type": "array", "items": { "type": "string" }, "description": "Branches where force-push is hard-denied regardless of confirmation." },
"default_author": { "type": "string", "description": "'Name <email>' applied when caller does not override." }
}
}
}Emit a domain-tagged ChittyLedger event from the resource server. Returns the
ledger entry hash for inclusion in the resource server's response to the
client. Domain tag is fixed to git on this surface.
{
"name": "ledger.emit",
"input_schema": {
"type": "object",
"required": ["capability_token", "event_type", "payload"],
"additionalProperties": false,
"properties": {
"capability_token": { "type": "string" },
"event_type": { "type": "string", "enum": ["git.commit", "git.push", "git.tag"] },
"payload": {
"type": "object",
"description": "Event-specific fields (commit_sha, pushed_refs, tag_name, etc.). MUST NOT contain raw remote URLs with userinfo or raw git stderr — apply the redaction contract before submitting."
}
}
},
"output_schema": {
"type": "object",
"required": ["ledger_event_id", "entry_hash", "domain"],
"additionalProperties": false,
"properties": {
"ledger_event_id": { "type": "string" },
"entry_hash": { "type": "string", "description": "Hex sha256 of the canonicalized entry." },
"domain": { "type": "string", "const": "git" }
}
}
}- Signing key — resolved from chittysecrets via
op://reference per the sensitive-intent contract. Never read from env vars, disk, or chat. Signing is mandatory for commit and tag flows; broker exposes no disable knob. If chittysecrets is unreachable → fail closed. - Remote allowlist — per-tenant config returned by
policy.resolve. Default:github.com/CHITTYOS/*,github.com/CHITTYFOUNDATION/*. Resource server MUST refuse push to non-allowlisted remotes →POLICY_BLOCKED_REMOTE_NOT_ALLOWED. - Repo allowlist — per-tenant. Resource server MUST refuse repos outside the list →
POLICY_BLOCKED_REPO_NOT_ALLOWED. - Force-push guard — minting a capability with
force_class != "none"requires a freshconfirmation_tokenfrom/api/v1/capabilities/confirm. Confirmation tokens are single-use and bound to (caller, tenant, repo, force_class). Force-push to any branch inprotected_branchesis hard-denied regardless of token →POLICY_BLOCKED_FORCE_TO_PROTECTED.forceandforce_with_leaseare distinct values offorce_class— they cannot be combined. - Audit — every successful write requires the resource server to call
/api/v1/ledger/emit. The returnedledger_event_idis included in the response to the client. Domain tag isgit, hash-chained per the canonical projection model. - Broker liveness — if the broker is unreachable from the resource server, the resource server fails closed with
POLICY_BLOCKED_CHITTYCONNECT_UNAVAILABLE. No local fallback. - Credential redaction (binding contract) — any string the resource server places in a
ledger.emitpayload or any error envelope it returns to the client MUST pass through a redaction filter:- URL userinfo: strip the
userinfocomponent from any URL, rewritinghttps?://[^@]+@to scheme-onlyhttps?://. Applies to remote URLs and any URL in error messages. - CLI output: omit raw
gitstdout/stderr from error envelopes, or pass it through the userinfo strip plus a token-pattern scrub (gh[pousr]_[A-Za-z0-9_]{20,},github_pat_[A-Za-z0-9_]{20,},xox[bpars]-[A-Za-z0-9-]{10,}, 40+ char hex/base64 secrets adjacent to://orAuthorization:). When in doubt, omit. - Capability tokens, confirmation tokens, signatures, and signing-key references (op:// paths, chittysecrets UUIDs, secret names, env-var names referencing keys) MUST NEVER appear in any broker response (including
/signing/*outputs), ledger payloads, or error envelopes. Only the non-sensitivekey_fingerprint(sha256 of the public key) is exported.
- URL userinfo: strip the
| Code | Meaning |
|---|---|
POLICY_BLOCKED_REPO_NOT_ALLOWED |
repo_path not in tenant repo allowlist |
POLICY_BLOCKED_REMOTE_NOT_ALLOWED |
Remote URL not in tenant allowlist |
POLICY_BLOCKED_FORCE_TO_PROTECTED |
Force-push attempted against protected branch |
POLICY_BLOCKED_CONFIRMATION_REQUIRED |
force_class != "none" without valid confirmation_token |
POLICY_BLOCKED_CONFIRMATION_INVALID |
Confirmation token expired, reused, or scope-mismatched |
POLICY_BLOCKED_CAPABILITY_INVALID |
Capability token expired, malformed, or scope-mismatched |
POLICY_BLOCKED_SIGNING_KEY_UNAVAILABLE |
chittysecrets unreachable or key missing |
POLICY_BLOCKED_CHITTYCONNECT_UNAVAILABLE |
Broker unreachable; resource server fails closed |
GIT_DIRTY_INDEX |
Commit attempted with no staged changes and no paths (raised at resource server) |
GIT_REMOTE_REJECTED |
Underlying push returned non-zero. Embedded output MUST be redacted per the contract above; when in doubt the resource server omits raw output and returns only the exit code. |
X-ChittyOS-API-Key: {api_key}
Or:
Authorization: Bearer {token}
Cross-service awareness system providing:
- Real-time knowledge of all service states
- Contextual analysis (legal, financial, relational)
- Intelligent routing to optimal services
- State persistence via MemoryCloude™
ChittyContext is a local edge cache at ~/.claude/chittycontext/ that provides
offline-resilient session state for Claude Code sessions. It is a capability of
ChittyConnect, not a standalone service.
Responsibilities:
- Auto-resolve session context via MCP bridge on session start
- Cache last-known state locally for offline resilience
- Queue session metrics for async commit to ChittyConnect backend
- Maintain project-scoped state files per entity
Not a standalone service: ChittyContext has no charter, no deployment, no health endpoint. It is a client-side cache governed by ChittyConnect's ContextConsciousness™.
| Role | Owner |
|---|---|
| Service Owner | ChittyOS |
| Technical Lead | @chittyos-infrastructure |
| Security Contact | security@chitty.cc |
Source: chittycanon://gov/governance#three-aspects
| Aspect | Abbrev | Question | ChittyConnect Answer |
|---|---|---|---|
| Identity | TY | What IS it? | AI-intelligent spine — the universal connector enabling GPTs, Claude, and third-party integrations to interact with the ChittyOS ecosystem |
| Connectivity | VY | How does it ACT? | Three interfaces: REST API (Custom GPT Actions), MCP Server (Claude), GitHub App (webhooks); proxies Notion, OpenAI, Neon, Google Calendar; ContextConsciousness™ cross-session state |
| Authority | RY | Where does it SIT? | Tier 2 Platform — integration hub, not source of truth; delegates identity to ChittyID, auth to ChittyAuth, registration to ChittyRegister |
This charter is part of a synchronized documentation triad. Changes to shared fields must propagate.
| Field | Canonical Source | Also In |
|---|---|---|
| Canonical URI | CHARTER.md (Classification) | CHITTY.md (blockquote) |
| Tier | CHARTER.md (Classification) | CHITTY.md (blockquote) |
| Domain | CHARTER.md (Classification) | CHITTY.md (blockquote), CLAUDE.md (header) |
| Endpoints | CHARTER.md (API Contract) | CHITTY.md (Endpoints table), CLAUDE.md (API section) |
| Dependencies | CHARTER.md (Dependencies) | CHITTY.md (Dependencies table), CLAUDE.md (Architecture) |
| Certification badge | CHITTY.md (Certification) | CHARTER.md frontmatter status |
Related docs: CHITTY.md (badge/one-pager) | CLAUDE.md (developer guide)
- Service registered in ChittyRegistry
- Health endpoint operational at /health
- OpenAPI specification published
- CLAUDE.md development guide present
- MCP manifest published
- GitHub App webhook verified
Charter Version: 1.0.0 | Last Updated: 2026-02-23