Hancock

Hancock is a cryptographic consent ledger that manages approvals for sensitive operations across Jetta infrastructure. It provides human-in-the-loop verification for AI agent actions and will evolve into a unified authentication gateway.

Production URL: https://hancock.jettaintelligence.com

Repository: aic-holdings/hancock

Overview

┌─────────────────────────────────────────────────────────────┐
│                        Hancock                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Consent   │    │    Auth     │    │   Login     │     │
│  │   Ledger    │    │   Methods   │    │  Gateway    │     │
│  │  (Current)  │    │  (Current)  │    │  (Future)   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│        │                  │                  │              │
│        ▼                  ▼                  ▼              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Cryptographic Proof Layer               │   │
│  │         (Signing Keys, TOTP, Duo Push*)              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
    ┌──────────┐       ┌──────────┐       ┌──────────┐
    │    AI    │       │  Human   │       │  Jetta   │
    │  Agents  │       │   Users  │       │   SSO    │
    └──────────┘       └──────────┘       └──────────┘

*Future capability

Current Capabilities

Hancock tracks approval requests for sensitive operations:

Field	Description
`requestor`	Who is asking (agent ID or user)
`requestor_type`	human, ai, or system
`action`	What action requires consent
`target`	Target of the action (ticket ID, service, etc.)
`description`	Human-readable explanation
`status`	pending, approved, rejected, expired

Authentication Methods

Users can authenticate approvals using:

Method	Description
PIN	6-digit PIN with bcrypt hashing
TOTP	Time-based one-time passwords (Google Authenticator, etc.)
Duo Push	Coming soon - Push notifications to mobile device

Multi-Approver Policies

For high-risk operations, Hancock supports policies requiring multiple approvers:

Policy: "deploy-production"
Required Approvals: 2
Current: 1/2 approved
Approvers: [daniel ✓, pending...]

MCPammer Integration

AI agents interact with Hancock via MCP tools:

Tool	Purpose
`hancock_request`	Create approval request
`hancock_check`	Check request status
`hancock_pending`	List pending approvals
`hancock_approve`	Approve with signing key
`hancock_reject`	Reject with reason
`hancock_health`	Check service health

Example: AI Agent Requesting Approval

# AI agent needs human approval for deployment
request = await hancock_request(
    requestor="claude-code",
    requestor_type="ai",
    action="deploy",
    target="production-api",
    description="Deploy v2.3.0 with database migration"
)

# Wait for human approval
while True:
    status = await hancock_check(request_id=request.id)
    if status.approved:
        # Proceed with deployment
        break
    elif status.rejected:
        # Handle rejection
        break
    await sleep(30)

Dashboard

The Hancock dashboard provides a web interface for managing approvals:

URL: https://hancock.jettaintelligence.com

Features

Pending Requests - View and approve/reject requests
Auth Methods - Configure PIN and TOTP
Recent Activity - Audit log of approvals
Multi-Approver Progress - Track approval status

Setting Up Authentication

Navigate to the dashboard
Click "Setup PIN" or "Setup TOTP"
For TOTP: Scan QR code with authenticator app
Verify with test code

Hancock will evolve beyond consent approvals to become the authentication gateway for all Jetta services.

Planned Architecture

┌─────────────────────────────────────────────────────────────┐
│                   Hancock Login Gateway                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   User Request                                               │
│        │                                                     │
│        ▼                                                     │
│   ┌─────────────┐                                           │
│   │  Username/  │                                           │
│   │  Password   │                                           │
│   └──────┬──────┘                                           │
│          │                                                   │
│          ▼                                                   │
│   ┌─────────────┐     ┌─────────────┐                       │
│   │  Duo Push   │────▶│   Mobile    │                       │
│   │  Challenge  │     │   Approve   │                       │
│   └──────┬──────┘     └─────────────┘                       │
│          │                                                   │
│          ▼                                                   │
│   ┌─────────────┐                                           │
│   │   Session   │                                           │
│   │   Created   │                                           │
│   └──────┬──────┘                                           │
│          │                                                   │
│          ▼                                                   │
│   Redirect to Jetta SSO with verified identity               │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Duo Push Integration

Duo Push will provide:

Push Notifications - Approve logins from your phone
Biometric Verification - Face ID / Touch ID on mobile
Offline Codes - Backup codes when offline
Device Trust - Remember trusted devices

User visits login.jettaintelligence.com
Enter username and password
Hancock sends Duo Push to registered device
User approves on mobile (with optional biometric)
Hancock creates verified session
Redirect to requested application with SSO token

Why Duo?

Feature	TOTP	Duo Push
User Experience	Enter 6 digits	One tap approve
Phishing Resistant	No	Yes (shows context)
Biometric Option	No	Yes
Admin Visibility	Limited	Full audit trail
Device Management	Manual	Centralized

Security Architecture

Database Isolation

Hancock uses a dedicated, isolated PostgreSQL database:

No public port exposure
SSL required for connections
Minimal app user privileges (no DELETE)
Append-only audit log
Credentials in Infisical

Cryptographic Proofs

Every approval generates a cryptographic proof:

{
  "request_id": "uuid",
  "approver": "daniel",
  "method": "totp",
  "timestamp": "2026-01-12T10:30:00Z",
  "proof": "sha256:abc123...",
  "signature": "..."
}

Audit Trail

All actions are logged for compliance:

Request creation
Approval/rejection with proof
Authentication method changes
Policy modifications

API Reference

Create Request

curl -X POST https://hancock.jettaintelligence.com/api/request \
  -H "Content-Type: application/json" \
  -d '{
    "requestor": "claude-code",
    "requestor_type": "ai",
    "action": "deploy",
    "description": "Deploy API v2.3.0"
  }'

Check Status

curl https://hancock.jettaintelligence.com/api/request/{id}

Approve Request

curl -X POST https://hancock.jettaintelligence.com/api/approve \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "uuid",
    "method": "totp",
    "totp_token": "123456"
  }'

Configuration

Environment Variables

# Database
HANCOCK_DB=postgresql://hancock_app:xxx@hancock-db:5432/hancock

# Jetta SSO
JETTA_SSO_URL=https://login.jettaintelligence.com

# Duo (Future)
DUO_INTEGRATION_KEY=xxx
DUO_SECRET_KEY=xxx
DUO_API_HOSTNAME=api-xxx.duosecurity.com

Roadmap

Phase	Status	Description
1. Database & API	✅ Complete	Core consent ledger
2. Dashboard UI	✅ Complete	Web interface
3. TOTP Support	✅ Complete	Authenticator apps
4. Multi-Approver	✅ Complete	Policy-based approvals
5. MCP Tools	✅ Complete	AI agent integration
6. Duo Push	🔜 Planned	Push notifications
7. Login Gateway	🔜 Planned	Unified authentication
8. SSO Integration	🔜 Planned	Replace current Jetta SSO

Overview​

Current Capabilities​

Consent Ledger​

Authentication Methods​

Multi-Approver Policies​

MCPammer Integration​

Example: AI Agent Requesting Approval​

Dashboard​

Features​

Setting Up Authentication​

Future: Unified Login Gateway​

Planned Architecture​

Duo Push Integration​

Login Flow (Planned)​

Why Duo?​

Security Architecture​

Database Isolation​

Cryptographic Proofs​

Audit Trail​

API Reference​

Create Request​

Check Status​

Approve Request​

Configuration​

Environment Variables​

Roadmap​