LikenessGuard

An open-source reference implementation of a consent-enforcement standard for AI image generation.

LikenessGuard stops non-consensual AI image generation before it happens — at the point of generation, not after. When an AI model receives a request to generate or edit an image involving a real person's face, LikenessGuard checks consent in real time. If consent is denied, the AI refuses. If consent is granted, a cryptographically signed Proof-of-Face certificate is issued.

Demo Screenshots

• LikenessGuard v2 Dashboard Home showing live metrics and recent activity.

• Real-time consent check flow with agent reasoning trace and Proof-of-Face result.

• Searchable activity logs with filtering by decision type, time range, and platform.

• Impact Dashboard showing consent enforcement metrics, cost savings, and compliance trends.

• Federated Registry view with cross-platform peer connections and sync status.

🎥 Demo Video: LikenessGuard in Action

See how LikenessGuard enforces consent before any AI image generation or editing involving a real person's likeness.

https://github.com/user-attachments/assets/f9c596e5-4b2f-492e-b3c6-be725ac8f4ee

Features

• Pre-generation enforcement — consent checked before any image is rendered
• Two operating modes — Registered-Subject Mode (protects registered subjects) and Closed-Consent Mode (default-deny for everyone); adopters choose based on their use case
• Deterministic consent evaluation — policy evaluation is deterministic given its inputs; no LLM on the decision path (v3)
• Hybrid facial matching — Rekognition + Titan Embeddings + OpenSearch Serverless k-NN (<0.5% false negatives)
• Cryptographic Proof-of-Face — KMS ECDSA P-256 signed C2PA-compatible manifests; every decision produces a signed manifest
• Edge enforcement — AWS IoT Greengrass v2 with offline default-deny
• Federated registry — JWT-authenticated cross-platform peer sharing
• Claude.ai integration — MCP connector for native consent enforcement in Claude
• Grok (xAI) integration — OpenAI-compatible function calling
• Natural language policies — write consent rules in plain English (policy authoring only, not on the decision path)
• <300ms P95 latency — production-ready performance
• ~$4.20/month at 100k checks — serverless cost efficiency

Documentation

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    AI Platforms & Clients                        │
│  Claude.ai (MCP)  │  Grok (xAI)  │  Python SDK  │  Node.js SDK │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
                           ▼
                  ┌─────────────────┐
                  │   API Gateway   │
                  │  /v2/consent/*  │
                  └────────┬────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │   Supervisor Lambda    │  ← Orchestrates 9-step pipeline
              │   <300ms P95           │
              └──┬──────┬──────┬───────┘
                 │      │      │
        ┌────────┘  ┌───┘  ┌──┘
        ▼           ▼      ▼
  ┌──────────┐ ┌────────┐ ┌──────────┐
  │ Anomaly  │ │Consent │ │  Policy  │
  │  Agent   │ │Orchest.│ │ Reasoner │
  │  Haiku   │ │Nova Pro│ │Nova Lite │
  └──────────┘ └────────┘ └──────────┘
        │           │
        ▼           ▼
  ┌──────────────────────┐    ┌─────────────┐
  │  Hybrid Matching     │    │  KMS ECDSA  │
  │  Rekognition+Titan   │    │  Proof-of-  │
  │  OpenSearch k-NN     │    │  Face Sign  │
  └──────────────────────┘    └─────────────┘
        │
        ▼
  ┌──────────────────────┐
  │  DynamoDB            │
  │  ConsentRegistry     │
  │  AuditLog (7yr)      │
  └──────────────────────┘

For the rationale behind key architecture decisions, see the RFCs:

• RFC-001: Supervisor Orchestration Pattern — why we use a Supervisor Lambda instead of Bedrock Agents or Step Functions
• RFC-002: Hybrid Facial Matching — three-layer matching pipeline design
• RFC-003: Proof-of-Face Signing — KMS ECDSA P-256 signing for C2PA-compatible manifests

Quick Start

Get LikenessGuard running in your AWS account in under 10 minutes.

What you'll need

• AWS account with Bedrock model access enabled in us-east-1 (enable models here)
• AWS CLI v2 — install guide
• AWS SAM CLI — install guide
• Python 3.12+ — download
• Node.js 20+ — download

Step 1: Clone and configure

git clone https://github.com/jsamuelkamau-dot/likenessguard.git
cd likenessguard
cp .env.example .env
# Open .env and replace YOUR_AWS_ACCOUNT_ID with your actual account ID

Step 2: Configure AWS credentials

If you haven't already, set up your AWS credentials:

aws configure
# Access Key ID:     <your-key>
# Secret Access Key: <your-secret>
# Default region:    us-east-1
# Output format:     json

Step 3: Deploy to AWS

make deploy

This builds all Lambda functions and deploys the full stack (API Gateway, DynamoDB, KMS, S3, OpenSearch, and 9 Lambda functions).

Step 4: Run post-deploy setup

make post-deploy

This creates the OpenSearch vector index and publishes the JWKS public key.

Step 5: Start the dashboard and MCP server

make start
# Dashboard:  http://localhost:5173
# MCP server: http://localhost:8080

Step 6: Test a consent check

from likenessguard import LikenessGuardClient

client = LikenessGuardClient(
    api_endpoint="https://YOUR_API_ID.execute-api.us-east-1.amazonaws.com/v1",
    platform_id="my-platform"
)

result = client.check_consent("face.jpg", usage_type="GENERAL_GENERATION")

if result.allowed:
    print(f"Consent granted. Proof: {result.proof_of_face['manifest_id']}")
else:
    print(f"Consent denied: {result.reason_code}")

For the full deployment guide with troubleshooting, see DEPLOY.md.

Contributing Without AWS

You don't need an AWS account to contribute. Most work — tests, docs, dashboard, SDKs — runs locally with mocked services:

make dev-mock    # Run property-based tests + unit tests (no AWS needed)

See CONTRIBUTING.md for the full list of what needs AWS and what doesn't.

Project Structure

likenessguard/
├── likenessguard-aws/
│   ├── src/
│   │   └── lambdas/
│   │       ├── supervisor/          # Orchestrator entry point
│   │       ├── anomaly_agent/       # Threat detection (Claude Haiku)
│   │       ├── consent_orchestrator/ # Policy evaluation (Nova Pro)
│   │       ├── policy_reasoner/     # NL→JSON policy (Nova Lite)
│   │       ├── proof_verify/        # KMS manifest verification
│   │       ├── federation/          # Federated registry + opt-out
│   │       ├── registration/        # Photo upload + fingerprint
│   │       ├── image_proxy/         # Base64→S3 presigned URL
│   │       └── shared/              # Titan, OpenSearch, KMS, schemas
│   ├── edge/                        # Greengrass v2 edge component
│   ├── sdk/
│   │   ├── python/                  # Python SDK
│   │   └── nodejs/                  # Node.js TypeScript SDK
│   ├── infrastructure/              # CloudFormation templates
│   ├── scripts/                     # Deploy, backfill, crosscheck
│   └── docs/                        # Architecture, guides
├── likenessguard-dashboard/         # React dashboard
├── likenessguard-mcp/               # MCP server (Claude.ai)
│   ├── server.py                    # MCP + OAuth stubs
│   ├── grok_integration.py          # Grok/xAI function calling
│   └── openai_integration.py        # OpenAI function calling
├── docs/
│   ├── threat-model.md              # Security threat model
│   └── rfcs/                        # Architecture decision records
├── .env.example                     # Environment template
├── .gitignore
├── LICENSE                          # Apache 2.0
├── Makefile                         # Common commands
├── CONTRIBUTING.md
├── SECURITY.md
├── ROADMAP.md
└── CHANGELOG.md

API Reference

Base URL: https://YOUR_API_ID.execute-api.us-east-1.amazonaws.com/v1

Consent Check Example

curl -X POST https://YOUR_API_ID.execute-api.us-east-1.amazonaws.com/v1/v2/consent/check \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/face.jpg",
    "usage_type": "GENERAL_GENERATION",
    "requester_id": "my-platform",
    "platform": "stable-diffusion"
  }'

Response:

{
  "decision": "ALLOW",
  "reason_code": "ALLOW_POLICY_PERMITS",
  "confidence": 0.97,
  "similarity_score": 0.923,
  "subject_id": "sub-abc123",
  "proof_of_face": {
    "manifest_id": "uuid",
    "proof": { "signature": "base64-ecdsa-sig", "algorithm": "ECDSA_SHA_256" }
  },
  "latency_ms": 263
}

Claude.ai Integration (MCP)

# Start MCP server
make start-mcp

# Expose publicly via ngrok
ngrok http 8080

# Add to Claude.ai: Settings → Connectors → Add custom connector
# URL: https://YOUR-NGROK-URL.ngrok-free.app/mcp

Claude will automatically call check_consent before generating any image involving a real person.

Production deployment: ngrok is for development/testing only. For production, deploy the MCP server to a stable HTTPS endpoint:

• AWS Lambda Function URL -- serverless, no infrastructure to manage
• Railway / Render -- one-click deploy from the included Dockerfile
• Any HTTPS server -- run python server.py behind nginx/caddy with a real domain and TLS certificate

Grok (xAI) Integration

cd likenessguard-mcp
export XAI_API_KEY=your-xai-key
python grok_integration.py

Performance

Cost at Scale

Contributing

See CONTRIBUTING.md for setup instructions, coding standards, and the PR process.

Security

See SECURITY.md for how to report vulnerabilities.

License

Apache License 2.0 — see LICENSE.

Contributions are accepted under the Apache 2.0 license via Developer Certificate of Origin (DCO) sign-off. See CONTRIBUTING.md for details.

Acknowledgements

Built by Samuel Jesse. ANZ Regional Champion — AWS AIdeas 2025. Powered by AWS Bedrock, OpenSearch Serverless, KMS, IoT Greengrass, and API Gateway. v3 reference implementation in progress — see ROADMAP-V3.md.