ChittyConnect - Access Provisioning Broker

Version: 1.0.0 Status: Implementation in Progress Updated: October 21, 2025

Overview

ChittyConnect is an access provisioning broker, not an executor. It authenticates identity, observes context, provisions credentials, and manages access lifecycle - but the user executes actions themselves with provisioned credentials.

Architecture Pattern

┌──────────────────────────────────────────────────────────────┐
│                    Access Provisioning Flow                   │
└──────────────────────────────────────────────────────────────┘

1. AUTHENTICATE
   User → ChittyConnect.authenticate_chittyid()
   ↓
   Verify ChittyID ownership (JWT/signature)
   ↓
   Return: { session_token, chittyid, expires_at }

2. REQUEST ACCESS
   User → ChittyConnect.request_access(session_token, resource, context)
   ↓
   Observe context (what, where, when)
   Validate authority (ChittyAuth)
   ↓
   Provision credentials via chittysecrets
   ↓
   Return: { credential_path, expires_at, instructions }

3. EXECUTE
   User → Execute action with provisioned credentials
   ↓
   Example: git push using provisioned GitHub token
   ↓
   ChittyConnect observes (but does NOT execute)

4. REVOKE
   ChittyConnect → Automatic revocation when TTL expires
   ↓
   Credential lifecycle managed by ChittyConnect

Core Components

1. Authentication Service

Endpoint: POST /api/auth/chittyid

Request:

{
  "chittyid": "CHITTY-PEO-123456-ABC",
  "proof": "JWT_TOKEN_OR_SIGNATURE"
}

Response:

{
  "success": true,
  "session_token": "sess_abc123...",
  "chittyid": "CHITTY-PEO-123456-ABC",
  "expires_at": "2025-10-21T18:00:00Z",
  "ttl_seconds": 3600
}

Implementation:

Verify JWT signature against ChittyAuth
Validate ChittyID format and checksum
Create session in KV with TTL
Return session token for subsequent requests

2. Context Observer

Endpoint: POST /api/provision/observe

Request:

{
  "session_token": "sess_abc123...",
  "context": {
    "action": "git_push",
    "target": "github.com/chittyos/chittyos-data",
    "location": "/Users/nb/.claude/projects/-/CHITTYOS/chittyos-data",
    "branch": "main"
  }
}

Response:

{
  "success": true,
  "observation_id": "obs_xyz789...",
  "inferred_resource": "github:push:chittyos-data",
  "required_permissions": ["repo", "workflow"],
  "next_step": "request_access"
}

Implementation:

Parse context to understand user intent
Infer required resource and permissions
Validate request against ChittyAuth policies
Log observation to ChittyChronicle

3. Credential Provisioner

Endpoint: POST /api/provision/request

Request:

{
  "session_token": "sess_abc123...",
  "observation_id": "obs_xyz789...",
  "resource": "github:push:chittyos-data",
  "duration": "1h"
}

Response:

{
  "success": true,
  "provision_id": "prov_def456...",
  "credential_source": "chittysecrets",
  "credential_reference": "op://ChittyOS/github-chittyos-data/token",
  "service_account": "chittyos-automation@github.com",
  "expires_at": "2025-10-21T18:00:00Z",
  "instructions": {
    "method": "environment_variable",
    "variable_name": "GITHUB_TOKEN",
    "command": "op run --env-file=- -- git push origin main"
  }
}

Implementation:

Validate session token and observation
Check ChittyAuth for authorization
Provision credentials via chittysecrets Connect API
Create access record in D1
Return credential reference (NOT the credential itself)

4. Access Lifecycle Manager

Automatic Background Process

Responsibilities:

Monitor active provisioned access records
Revoke credentials when TTL expires
Send notifications before expiration
Log lifecycle events to ChittyChronicle

Database Schema:

CREATE TABLE access_provisions (
  provision_id TEXT PRIMARY KEY,
  session_token TEXT NOT NULL,
  chittyid TEXT NOT NULL,
  resource TEXT NOT NULL,
  credential_reference TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  expires_at DATETIME NOT NULL,
  revoked_at DATETIME,
  status TEXT DEFAULT 'active' -- active, expired, revoked
);

Cron Job (via Cloudflare Scheduled Events):

// Every 5 minutes
export default {
  async scheduled(event, env, ctx) {
    const now = new Date().toISOString();

    // Find expired provisions
    const expired = await env.DB.prepare(`
      SELECT * FROM access_provisions
      WHERE expires_at < ? AND status = 'active'
    `).bind(now).all();

    // Revoke each
    for (const provision of expired.results) {
      await revokeAccess(provision, env);
    }
  }
}

Integration with chittysecrets

chittysecrets Connect API

Setup:

# Store chittysecrets Connect credentials
wrangler secret put ONEPASSWORD_CONNECT_HOST
wrangler secret put ONEPASSWORD_CONNECT_TOKEN

Provisioning Flow:

async function provisionCredential(resource, chittyid, env) {
  const vaultId = await getVaultId('ChittyOS', env);
  const itemId = await getItemId(vaultId, resource, env);

  // Create a temporary access token for the credential
  const accessToken = await create1PasswordAccessToken(
    itemId,
    chittyid,
    { ttl: 3600 }, // 1 hour
    env
  );

  return {
    credential_reference: `op://ChittyOS/${resource}/token`,
    access_token: accessToken,
    expires_at: new Date(Date.now() + 3600000).toISOString()
  };
}

Revocation:

async function revokeAccess(provision, env) {
  // Revoke chittysecrets access token
  await revoke1PasswordAccessToken(provision.access_token, env);

  // Update database
  await env.DB.prepare(`
    UPDATE access_provisions
    SET status = 'revoked', revoked_at = datetime('now')
    WHERE provision_id = ?
  `).bind(provision.provision_id).run();

  // Log to ChittyChronicle
  await logToChronicle({
    event: 'access.revoked',
    provision_id: provision.provision_id,
    chittyid: provision.chittyid,
    resource: provision.resource
  }, env);
}

MCP Tools (Broker-Only Mode)

Before (Executor Mode) ❌

{
  name: 'github_push_commits',
  description: 'Push local git commits to GitHub repository using API',
  handler: async (args) => {
    // ❌ ChittyConnect executes the push
    execSync(`git push ${remoteUrl} ${branch}`, { cwd: repoPath });
    return { success: true };
  }
}

After (Broker Mode) ✅

{
  name: 'provision_github_access',
  description: 'Provision GitHub push access for authenticated ChittyID',
  handler: async (args) => {
    // ✅ ChittyConnect provisions credentials
    const provision = await provisionCredential(
      'github:push:' + args.repo,
      args.chittyid,
      env
    );

    return {
      success: true,
      provision_id: provision.provision_id,
      instructions: {
        command: `op run --env-file=- -- git push origin ${args.branch}`,
        credential_path: provision.credential_reference,
        expires_at: provision.expires_at
      }
    };
  }
}

Updated MCP Tool List

Authentication

authenticate_chittyid - Verify ChittyID ownership
refresh_session - Extend session TTL
revoke_session - End session and revoke all access

Context & Provisioning

observe_context - Register user intent
request_access - Provision credentials for resource
list_active_access - Show active provisions
revoke_access - Manually revoke provision

Resource-Specific (Broker Mode)

provision_github_access - GitHub repo access
provision_sendgrid_access - SendGrid API access
provision_notion_access - Notion API access
provision_1password_access - chittysecrets vault access

Example User Flow

Scenario: Push commits to chittyos-data

# 1. Authenticate with ChittyID
curl -X POST https://connect.chitty.cc/api/auth/chittyid \
  -H "Content-Type: application/json" \
  -d '{
    "chittyid": "CHITTY-PEO-123456-ABC",
    "proof": "eyJhbGc..."
  }'

# Response:
# {
#   "session_token": "sess_abc123...",
#   "expires_at": "2025-10-21T18:00:00Z"
# }

# 2. Request GitHub push access
curl -X POST https://connect.chitty.cc/api/provision/request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sess_abc123..." \
  -d '{
    "resource": "github:push:chittyos-data",
    "context": {
      "action": "git_push",
      "location": "/Users/nb/.claude/projects/-/CHITTYOS/chittyos-data",
      "branch": "main"
    },
    "duration": "1h"
  }'

# Response:
# {
#   "provision_id": "prov_def456...",
#   "credential_reference": "op://ChittyOS/github-chittyos-data/token",
#   "expires_at": "2025-10-21T18:00:00Z",
#   "instructions": {
#     "command": "op run --env-file=- -- git push origin main"
#   }
# }

# 3. Execute git push with provisioned credentials
cd /Users/nb/.claude/projects/-/CHITTYOS/chittyos-data
op run --env-file=- -- git push origin main

# ChittyConnect observes but does NOT execute
# Credentials auto-revoke at 18:00:00Z

Security Model

Zero Trust Principles

Always authenticate: Every request requires valid ChittyID
Context-aware: Permissions based on what/where/when
Time-limited: All access has TTL (default 1h, max 24h)
Audit everything: All provisioning logged to ChittyChronicle

Credential Isolation

Credentials never returned directly to user
Accessed via chittysecrets CLI or environment injection
Automatic revocation on expiry
No long-lived tokens

Authority Chain

User (ChittyID)
  ↓
ChittyConnect (Broker)
  ↓
ChittyAuth (Authorization)
  ↓
chittysecrets (Credential Store)
  ↓
External Service (GitHub, etc.)

Implementation Checklist

Phase 1: Core Infrastructure ✅

Rate limiting middleware
Circuit breakers
Error handling
ChittyOS ecosystem integration

Phase 2: Authentication (In Progress)

ChittyID authentication endpoint
Session management (KV-based)
JWT verification with ChittyAuth
Session refresh mechanism

Phase 3: Provisioning

Context observer implementation
chittysecrets Connect API integration
Credential provisioning flow
Resource-to-credential mapping

Phase 4: Lifecycle

Access provisions database schema
TTL-based revocation cron
Pre-expiry notifications
ChittyChronicle integration

Phase 5: MCP Tools

Remove executor tools (github_push_commits)
Add broker tools (provision_github_access)
Update tool descriptions
Add usage examples

Phase 6: Testing

Authentication flow tests
Provisioning flow tests
Lifecycle management tests
End-to-end integration tests

Phase 7: Documentation

API reference
User guide
Security documentation
Integration examples

Timeline

Phase 2 (Auth): 2-3 days
Phase 3 (Provisioning): 3-4 days
Phase 4 (Lifecycle): 2-3 days
Phase 5 (MCP): 1-2 days
Phase 6 (Testing): 2-3 days
Phase 7 (Docs): 1-2 days

Total: ~2-3 weeks to full implementation

Related Services

ChittyAuth: Authorization and policy enforcement
ChittyID: Identity authority and minting
ChittyChronicle: Audit logging
chittysecrets: Credential storage and provisioning
ChittyRegistry: Service discovery

Status: 🟡 Design Complete, Implementation Starting Next: Implement ChittyID authentication endpoint

Navigation Menu

Uh oh!

ChittyConnect - Access Provisioning Broker

Overview

Architecture Pattern

Core Components

1. Authentication Service

2. Context Observer

3. Credential Provisioner

4. Access Lifecycle Manager

Integration with chittysecrets

chittysecrets Connect API

MCP Tools (Broker-Only Mode)

Before (Executor Mode) ❌

After (Broker Mode) ✅

Updated MCP Tool List

Authentication

Context & Provisioning

Resource-Specific (Broker Mode)

Example User Flow

Scenario: Push commits to chittyos-data

Security Model

Zero Trust Principles

Credential Isolation

Authority Chain

Implementation Checklist

Phase 1: Core Infrastructure ✅

Phase 2: Authentication (In Progress)

Phase 3: Provisioning

Phase 4: Lifecycle

Phase 5: MCP Tools

Phase 6: Testing

Phase 7: Documentation

Timeline

Related Services

Uh oh!

FilesExpand file tree

ACCESS_PROVISIONING.md

Latest commit

History

ACCESS_PROVISIONING.md

File metadata and controls

ChittyConnect - Access Provisioning Broker

Overview

Architecture Pattern

Core Components

1. Authentication Service

2. Context Observer

3. Credential Provisioner

4. Access Lifecycle Manager

Integration with chittysecrets

chittysecrets Connect API

MCP Tools (Broker-Only Mode)

Before (Executor Mode) ❌

After (Broker Mode) ✅

Updated MCP Tool List

Authentication

Context & Provisioning

Resource-Specific (Broker Mode)

Example User Flow

Scenario: Push commits to chittyos-data

Security Model

Zero Trust Principles

Credential Isolation

Authority Chain

Implementation Checklist

Phase 1: Core Infrastructure ✅

Phase 2: Authentication (In Progress)

Phase 3: Provisioning

Phase 4: Lifecycle

Phase 5: MCP Tools

Phase 6: Testing

Phase 7: Documentation

Timeline

Related Services