Guía Rápida de ACP

⚡ Sin instalación: Ejecutar con Docker

Sin necesidad de instalar Go. Descarga la imagen pre-construida desde GHCR e inicia el servidor de referencia ACP con un solo comando.

docker run -p 8080:8080 \
  -e ACP_INSTITUTION_PUBLIC_KEY=cA4s58S2dEJ-qye6EpJaJKKaVfvPT8mAQf97Vo8TInk \
  ghcr.io/chelof100/acp-server:latest

La clave es RFC 8037 Test Key A — solo para desarrollo. El servidor inicia en http://localhost:8080. Verificar con: curl http://localhost:8080/acp/v1/health

Python: Demo de Admission Control

Ejecuta el demo offline del SDK Python — sin servidor. Demuestra el patrón ACPAdmissionGuard: emitir un token de capacidad, ejecutar una verificación de admisión y actuar solo si el resultado es APPROVED.

git clone https://github.com/chelof100/acp-framework.git
cd acp-framework/impl/python
pip install -e .
python examples/admission_control_demo.py

Requiere Python 3.10+. El demo ejecuta 4 escenarios: pago aprobado, capacidad denegada, lectura de datos y ledger de auditoría. Sin dependencias externas más allá del SDK.

🏛️ Demo Multi-Org: Validación Federada (GAP-14)

Levantá dos organizaciones independientes (Org-A y Org-B) en Docker. Org-A emite snapshots de política y reputación firmados criptográficamente; Org-B los valida de forma independiente usando los paquetes reales de ACP — sin estado compartido, sin suposiciones de confianza.

git clone https://github.com/chelof100/acp-framework.git
cd acp-framework/examples/multi-org-demo
docker compose up

Org-A: http://localhost:8081 · Org-B: http://localhost:8082. Demuestra firmas Ed25519 reales, canonicalización JCS, enforcement de validez temporal y reporte de divergencia cross-org (REP-WARN-002). Ver README para el walkthrough completo.

Paso 1: Clonar y Compilar (Go)

Clona el repositorio y compila la implementación de referencia. Requiere Go 1.21+.

git clone https://github.com/chelof100/acp-framework.git
cd acp-framework/impl/go

# Compilar todos los paquetes
go build ./...

# Ejecutar la suite de pruebas (73 firmados + 65 RISK-2.0, L1–L4)
go test ./...

Todas las pruebas deben pasar. La suite cubre identidad, tokens de capacidad, integridad del ledger, snapshots de política, evaluación de riesgo y tokens de ejecución.

Paso 2: Verificar una Cadena de Eventos (L3 — Ledger)

El paquete ledger aplica encadenamiento criptográfico de hashes y verificación de firmas Ed25519. Ejemplo mínimo usando la API de Go directamente.

package main

import (
    "crypto/ed25519"
    "crypto/rand"
    "fmt"
    "log"

    "github.com/chelof100/acp-framework/acp-go/pkg/ledger"
)

func main() {
    // Generar par de claves institucional
    pubKey, privKey, _ := ed25519.GenerateKey(rand.Reader)

    // Crear un nuevo ledger para la institución "banco-001"
    l := ledger.NewInMemoryLedger("banco-001", privKey)

    // Agregar evento GENESIS (obligatorio como primer evento)
    if err := l.Append(ledger.Event{
        EventType: ledger.EventGenesis,
        Payload:   map[string]interface{}{"institution_id": "banco-001"},
    }); err != nil {
        log.Fatal(err)
    }

    // Agregar evento AUTHORIZATION
    if err := l.Append(ledger.Event{
        EventType: ledger.EventAuthorization,
        Payload: map[string]interface{}{
            "agent_id":             "agente-pagos-001",
            "capability":           "acp:cap:financial.payment",
            "policy_snapshot_ref":  "psn-2026-001",
        },
    }); err != nil {
        log.Fatal(err)
    }

    // Verificar toda la cadena contra la clave pública institucional
    result := l.Verify(pubKey)
    if result.Valid {
        fmt.Println("Cadena verificada ✓ —", len(result.Events), "eventos")
    } else {
        for _, e := range result.Errors {
            fmt.Println("Error:", e.Code, "-", e.Message)
        }
    }
}

Paso 3: Emitir un Token de Capacidad (L1 — CT)

Los tokens de capacidad otorgan permisos acotados a los agentes, firmados por la institución emisora, con una cadena de delegación criptográfica hasta la raíz institucional.

import "github.com/chelof100/acp-framework/acp-go/pkg/ct"

token, err := ct.Issue(ct.IssueRequest{
    InstitutionID: "banco-001",
    AgentID:       "agente-pagos-001",
    Capability:    "acp:cap:financial.payment",
    Scope:         []string{"transfer", "query"},
    MaxRisk:       0.25,
    TTLSeconds:    86400, // 24 horas
}, privKey)

if err != nil {
    log.Fatal(err)
}

// Verificar la firma del token
if err := ct.Verify(token, pubKey); err != nil {
    log.Fatal("Token inválido:", err)
}

fmt.Println("Token emitido:", token.TokenID)

Paso 4: Ejecutar Vectores de Cumplimiento

ACP incluye 138 vectores de prueba (73 firmados para L1–L4 + 65 sin firma RISK-2.0 para scoring de anomalías) que cubren casos positivos y negativos para cada nivel de conformidad. Pueden usarse para validar cualquier implementación ACP de terceros.

# Los vectores están en compliance/test-vectors/
ls acp-framework/compliance/test-vectors/

# TS-LEDGER-POS-001.json  — Cadena genesis válida
# TS-LEDGER-NEG-003.json  — Hash manipulado (LEDGER-003)
# TS-EXEC-POS-001.json    — Token de ejecución válido
# TS-EXEC-NEG-005.json    — Token expirado (EXEC-005)
# ... 138 vectores en total

# Cada vector tiene la estructura:
# {
#   "meta": { "id": "TS-LEDGER-POS-001", "level": "L3" },
#   "input": { "institution_public_key": "...", "events": [...] },
#   "expected": { "decision": "VALID", "error_code": null }
# }

Resumen de Paquetes (23 paquetes, L1–L4)