---
id: "0134"
title: "Mesh protocol spec: capability manifests, ed25519 envelopes, enrollment, audit chain"
status: pending
type: spec
domain:
  - infra
  - cybersecurity
  - protocols
scope: cross-app
priority: high
depends: []
blocks:
  - "0135"
  - "0136"
  - "0137"
  - "0138"
  - "0139"
  - "0140"
  - "0141"
  - "0142"
  - "0143"
related:
  - "0069"
related_flows:
  - "0009"
created: 2026-05-24
updated: 2026-05-24
tags: [mesh, wireguard, matrix, e2ee, ed25519, manifest, audit-chain, security, spec, agents, devices]
flow: "0009"
dependencies: []
---

# 0134 — Mesh protocol spec

**Status:** pending

## Por que

Flow 0009 (`agentes-dispositivos-mesh`) introduce un bus de control multi-device sobre WireGuard + Matrix donde cada dispositivo (PC, movil, raspberry, container Docker) ejecuta capabilities firmadas por el operador. Sin un protocolo formal compartido, cada implementacion (device_agent en Go, bot dispatcher en agents_and_robots, panel Mesh en agents_dashboard, hub en wg_hub) va a derivar.

Este issue cierra Fase B del flow: define el contrato exacto que **toda** implementacion debe respetar — wire format, firmas, replay protection, approval flow, audit chain, error model, threat model. Las issues 0135-0143 implementan lo que aqui se define.

Una vez aceptado este spec, ningun cambio en el wire format se acepta sin un nuevo issue + bump de `protocol_version`.

## Anti-scope

- NO define como provision el WG hub (ver 0136).
- NO define UI del panel Mesh (ver 0138).
- NO define implementacion concreta del bot Matrix (ver 0142).
- NO entra en como se persiste `pass operator/ed25519` mas alla de su uso.
- NO define schema de la `operations.db` de cada app — solo el subset estrictamente compartido (`audit_log`, `room_devices`, `seen_nonces`).

## Conventions

- `protocol_version` (string): **"mesh/1"** — incluido en todo envelope.
- Todo timestamp es Unix epoch **segundos** (`int64`).
- Todo `*_id` es `[a-z0-9_-]+` lowercase, 4-64 chars.
- Todo nonce es 16 bytes random (`crypto/rand`), serializado como **base64url sin padding**.
- Todo hash es SHA-256, serializado como **hex lowercase** (64 chars).
- Toda firma ed25519 es 64 bytes, serializada como **base64url sin padding** (86 chars).
- Toda clave publica ed25519 es 32 bytes, serializada como **base64url sin padding** (43 chars).
- Fingerprint de clave publica = primeros 16 bytes hex de `SHA-256(pubkey_raw_32_bytes)`.
- JSON canonical: claves ordenadas alfabeticamente, sin espacios, UTF-8, sin BOM. Para firmas siempre usar la forma canonica.

---

## 1. JSON envelope

Toda invocacion de capability viaja como par request/response, ya sea sobre Matrix (eventos `m.room.message` con `msgtype = m.capability.*`) o sobre HTTP dentro del mesh WG (`POST /capability`).

### 1.1 Request

```json
{
  "protocol_version": "mesh/1",
  "request_id": "req_01J9XYZABCDEF",
  "manifest_id": "manifest_home-wsl_v3",
  "capability": "fs.read",
  "args": {
    "path": "/var/log/syslog",
    "max_bytes": 4096
  },
  "ts": 1748131200,
  "nonce": "Yk9p6Xs_3hZQk4mB7lWcvA",
  "signature": "u2vh...QkA"
}
```

- `request_id`: ULID generado por el caller (agents_and_robots o el operador). Idempotency key — si la misma request llega 2x, device_agent debe devolver el mismo response sin re-ejecutar.
- `manifest_id`: id del capability manifest contra el cual se evalua. El device debe tener este manifest activo o rechazar `manifest_invalid`.
- `capability`: dotted name, ej. `shell.exec`, `fs.read`, `docker.container.list`. Debe estar en `manifest.capabilities[].name`.
- `args`: objeto JSON especifico de la capability. Schema validado por device_agent contra el manifest.
- `ts`: Unix seconds. Edad maxima 60s (ver §5).
- `nonce`: 16 bytes random, base64url. Unico por request (ver §5).
- `signature`: ed25519 sobre canonical bytes (ver 1.3).

### 1.2 Response

```json
{
  "protocol_version": "mesh/1",
  "request_id": "req_01J9XYZABCDEF",
  "ok": true,
  "result": {
    "stdout": "May 24 12:00:00 localhost systemd[1]: Started session-1.scope.\n",
    "stderr": "",
    "exit_code": 0,
    "truncated": false
  },
  "error": null,
  "duration_ms": 42,
  "audit_hash": "a3f5...09bc"
}
```

- `ok`: boolean. Si false, `result` ausente y `error` poblado.
- `error`: objeto `{code, message, details?}` cuando `ok=false`. `code` debe estar en §10.
- `duration_ms`: tiempo de ejecucion en device_agent (no incluye latencia Matrix).
- `audit_hash`: `this_hash` del registro en `audit_log` (ver §7). Permite al caller verificar la cadena.

Response NO va firmado por defecto — viaja sobre canal autenticado (Matrix E2EE o WG mesh). Si en el futuro se requiere firma de response (audit externo), se anade campo opcional `response_signature` con el mismo esquema canonical.

### 1.3 Canonical bytes para firma del request

```
canonical = "mesh/1\n" +
            request_id + "\n" +
            manifest_id + "\n" +
            capability + "\n" +
            sha256_hex(json_canonical(args)) + "\n" +
            int_to_string(ts) + "\n" +
            nonce
```

Bytes UTF-8, separador `\n` (0x0A). No trailing newline. Hash del args para no exponer args grandes a la firma (la firma se valida contra el hash, y `args` se reentrega tal cual; cualquier modificacion rompe la firma).

`json_canonical(args)`:
1. Si `args` es null o ausente, `json_canonical = "null"`.
2. Si `args` es objeto, recursivo: ordenar claves alfabeticamente, valores serializados sin espacios, strings con escape JSON estandar.
3. Si `args` es array, recursivo sobre cada elemento, sin reordenar.

### 1.4 Transport binding

| Transport | Request encoding | Response encoding |
|---|---|---|
| Matrix room event | `content.body` = JSON string, `msgtype` = `m.capability.request` | `m.capability.response` event en el mismo room |
| HTTP intra-mesh (`https://10.42.0.10:7777/capability`) | `POST` body JSON | response body JSON |
| SSE (streaming logs, `docker.logs --follow`) | request via POST | response inicial JSON `{ok, result: {stream_id}}` + SSE `event: chunk` |

Matrix es default. HTTP solo lo activa el operador con `mesh_http=true` en el manifest para casos de baja latencia (`docker.logs` tail interactivo, transferencias >1MB que Matrix limita).

---

## 2. Capability manifest

Documento firmado por el operador que autoriza a un device a ejecutar un set acotado de capabilities. Sin manifest valido, device_agent rechaza todo.

### 2.1 Schema YAML (legible) — fuente de verdad

```yaml
# manifest_home-wsl_v3.yaml
protocol_version: mesh/1
manifest_id: manifest_home-wsl_v3
device_id: home-wsl
operator: egutierrez@aurgi.com
operator_pubkey_fingerprint: "a1b2c3d4e5f60718"
issued_at: 1748131200
expires_at: 1779667200   # 1 year later
capabilities:
  - name: shell.exec
    requires_approval: false
    constraints:
      binaries_whitelist: [ls, cat, head, tail, grep, ps, df, du, uname, uptime]
      max_duration_s: 10
      max_output_bytes: 65536
      cwd_allowed: ["/home/lucas", "/tmp"]
  - name: fs.read
    requires_approval: false
    constraints:
      paths_allowed: ["/home/lucas/**", "/var/log/syslog", "/etc/os-release"]
      paths_denied: ["/home/lucas/.ssh/**", "/home/lucas/.password-store/**"]
      max_bytes: 1048576
  - name: fs.write
    requires_approval: true
    constraints:
      paths_allowed: ["/home/lucas/inbox/**"]
      max_bytes: 1048576
  - name: docker.container.list
    requires_approval: false
  - name: docker.container.exec
    requires_approval: true
    constraints:
      containers_allowed: ["agents_and_robots", "registry_api"]
      binaries_whitelist: [ls, cat, ps]
      max_duration_s: 30
```

### 2.2 JSON canonical (lo que se firma)

```json
{
  "capabilities": [
    {"constraints": {"binaries_whitelist": ["ls","cat","head","tail","grep","ps","df","du","uname","uptime"], "cwd_allowed":["/home/lucas","/tmp"], "max_duration_s": 10, "max_output_bytes": 65536}, "name": "shell.exec", "requires_approval": false},
    {"constraints": {"max_bytes": 1048576, "paths_allowed": ["/home/lucas/**","/var/log/syslog","/etc/os-release"], "paths_denied": ["/home/lucas/.ssh/**","/home/lucas/.password-store/**"]}, "name": "fs.read", "requires_approval": false},
    {"constraints": {"max_bytes": 1048576, "paths_allowed":["/home/lucas/inbox/**"]}, "name": "fs.write", "requires_approval": true},
    {"name": "docker.container.list", "requires_approval": false},
    {"constraints": {"binaries_whitelist": ["ls","cat","ps"], "containers_allowed": ["agents_and_robots","registry_api"], "max_duration_s": 30}, "name": "docker.container.exec", "requires_approval": true}
  ],
  "device_id": "home-wsl",
  "expires_at": 1779667200,
  "issued_at": 1748131200,
  "manifest_id": "manifest_home-wsl_v3",
  "operator": "egutierrez@aurgi.com",
  "operator_pubkey_fingerprint": "a1b2c3d4e5f60718",
  "protocol_version": "mesh/1"
}
```

Producido por `capability_manifest_canonicalize_go_infra` (function 0135 entrega).

### 2.3 Canonical bytes para firma del manifest

```
manifest_canonical = "mesh/1/manifest\n" + json_canonical(manifest_without_signature)
```

Donde `manifest_without_signature` es el JSON canonical de §2.2. El prefijo `mesh/1/manifest\n` es domain separator — evita que una firma de manifest pueda interpretarse como firma de envelope.

### 2.4 Manifest signed envelope (lo que se entrega al device)

```json
{
  "manifest": { /* §2.2 */ },
  "signature": "k7Yp...QwE"
}
```

Persistido en device como `~/.config/device_agent/manifests/manifest_home-wsl_v3.json`.

### 2.5 Reglas de verificacion (device_agent al arrancar y al recibir request)

1. Parsear `manifest` y `signature`.
2. Computar `manifest_canonical`.
3. Verificar `ed25519.Verify(operator_pubkey, manifest_canonical, signature)`.
4. Rechazar si `expires_at < now()` → `manifest_invalid` con `details.reason = "expired"`.
5. Rechazar si `issued_at > now() + 300` (clock skew) → `manifest_invalid` con `details.reason = "future_issued"`.
6. Rechazar si `device_id` no coincide con `~/.config/device_agent/device_id` → `manifest_invalid`.
7. Rechazar si `operator_pubkey_fingerprint` no coincide con la pubkey conocida → `manifest_invalid`.

### 2.6 Rotacion

Un manifest nuevo coexiste con el anterior hasta su `expires_at`. Para forzar revocacion inmediata: el hub publica un evento `manifest_revoked` (en room `#operator-broadcast`) firmado por el operador con la lista de `manifest_id` revocados. device_agent mantiene `~/.config/device_agent/revoked_manifests.json` y lo consulta antes de aceptar.

---

## 3. ed25519 signing flow

### 3.1 Keypair

- **Privada** del operador: `pass operator/ed25519`. Linea 1 = base64url de los 32 bytes del seed ed25519. Lineas siguientes = metadata (operador email, created_at, fingerprint).
- **Publica** del operador: `~/.fn_operator.pub`. Contenido = base64url de los 32 bytes raw + `\n`. Distribuida a cada device en su `~/.config/device_agent/operator.pub` durante enrollment.

### 3.2 Generacion (una sola vez en la vida del operador, idempotente)

```bash
# Funcion del registry: operator_keygen_bash_infra (0135 entrega)
operator_keygen() {
  if pass show operator/ed25519 >/dev/null 2>&1; then
    echo "operator key already exists; skipping"
    return 0
  fi
  local seed pub fp
  seed=$(openssl rand 32 | base64 -w0 | tr '+/' '-_' | tr -d '=')
  pub=$(echo "$seed" | go_ed25519_derive_pub)  # helper Go: seed → pub
  fp=$(echo -n "$(echo "$pub" | base64url -d)" | sha256sum | cut -c1-32)
  pass insert -m operator/ed25519 <<EOF
$seed
operator: $(git config user.email)
created_at: $(date +%s)
fingerprint: $fp
pubkey: $pub
EOF
  echo "$pub" > ~/.fn_operator.pub
  chmod 600 ~/.fn_operator.pub
}
```

### 3.3 Sign

```go
// capability_manifest_sign_go_infra (issue 0135)
func SignManifest(m Manifest, seed []byte) ([]byte, error) {
    if len(seed) != ed25519.SeedSize {
        return nil, ErrInvalidSeed
    }
    canonical, err := canonicalizeManifest(m)
    if err != nil { return nil, err }
    msg := append([]byte("mesh/1/manifest\n"), canonical...)
    priv := ed25519.NewKeyFromSeed(seed)
    return ed25519.Sign(priv, msg), nil
}
```

Para envelopes:

```go
func SignRequest(r Request, seed []byte) ([]byte, error) {
    canonical, err := canonicalRequestBytes(r)
    if err != nil { return nil, err }
    priv := ed25519.NewKeyFromSeed(seed)
    return ed25519.Sign(priv, canonical), nil
}
```

`canonicalRequestBytes` implementa §1.3.

### 3.4 Verify (device_agent)

```go
// capability_manifest_verify_go_infra (issue 0135)
func VerifyManifest(signed SignedManifest, pubkey []byte) error {
    if len(pubkey) != ed25519.PublicKeySize {
        return ErrInvalidPubkey
    }
    canonical, err := canonicalizeManifest(signed.Manifest)
    if err != nil { return err }
    msg := append([]byte("mesh/1/manifest\n"), canonical...)
    if !ed25519.Verify(pubkey, msg, signed.Signature) {
        return ErrSignatureInvalid
    }
    return nil
}
```

### 3.5 Domain separators (criticos)

Cada tipo de firma usa prefix unico para evitar cross-protocol attacks:

| Tipo | Prefix |
|---|---|
| Manifest | `"mesh/1/manifest\n"` |
| Request envelope | `"mesh/1/request\n"` (implicito en §1.3 — usa el `\n` join) |
| Enrollment token | `"mesh/1/enroll\n"` |
| Approval token | `"mesh/1/approval\n"` |
| Manifest revocation | `"mesh/1/revoke\n"` |

---

## 4. Enrollment token

Token corto firmado por el operador que un device usa **una sola vez** para registrarse contra `wg_hub` y obtener su config WireGuard + manifest inicial.

### 4.1 Payload JSON (canonical)

```json
{
  "allowed_capabilities": ["shell.exec", "fs.read", "docker.container.list"],
  "device_id": "home-wsl",
  "expires_at": 1748131800,
  "issued_at": 1748131200,
  "nonce": "Tk9NbjVxV3JLcF9j",
  "operator_pubkey_fingerprint": "a1b2c3d4e5f60718",
  "protocol_version": "mesh/1",
  "purpose": "enroll"
}
```

- `expires_at - issued_at` <= 600s (10 min). Hub rechaza si excede.
- `allowed_capabilities`: subset que el operador autoriza a este enrollment. El manifest final puede ser mas restrictivo pero no mas amplio.
- `nonce` previene replay incluso si el operador reusa el token por error.
- `purpose: "enroll"` es discriminator interno; los otros valores reservados son `"approval"` (§6) y `"revoke"`.

### 4.2 Wire format

```
base64url(json_canonical(payload)) + "." + base64url(ed25519_signature)
```

Ejemplo (truncado):

```
eyJhbGxvd2VkX2NhcGFiaWxpdGllcyI6WyJzaGVsbC5leGVjIiwiZnMucmVhZCJdLCJkZXZpY2VfaWQiOiJob21lLXdzbCIsLi4u.k7YpQwE9Vh...
```

Aproximadamente 280-320 bytes. Cabe en un QR Code v6 (error correction M).

### 4.3 Generacion (operador)

```bash
# enroll_device pipeline (issue 0139) llama:
./fn run enrollment_token_create home-wsl \
    --capabilities "shell.exec,fs.read,docker.container.list" \
    --ttl 600
# stdout: token base64url
```

### 4.4 Verificacion (wg_hub `POST /enroll`)

```go
// enrollment_token_verify_go_infra (issue 0135)
func VerifyEnrollToken(raw string, pubkey []byte) (*EnrollPayload, error) {
    parts := strings.Split(raw, ".")
    if len(parts) != 2 { return nil, ErrTokenMalformed }
    payloadBytes, err := base64.RawURLEncoding.DecodeString(parts[0])
    if err != nil { return nil, ErrTokenMalformed }
    sig, err := base64.RawURLEncoding.DecodeString(parts[1])
    if err != nil { return nil, ErrTokenMalformed }
    msg := append([]byte("mesh/1/enroll\n"), payloadBytes...)
    if !ed25519.Verify(pubkey, msg, sig) {
        return nil, ErrSignatureInvalid
    }
    var p EnrollPayload
    if err := json.Unmarshal(payloadBytes, &p); err != nil {
        return nil, ErrTokenMalformed
    }
    now := time.Now().Unix()
    if p.ExpiresAt < now { return nil, ErrTokenExpired }
    if p.IssuedAt > now + 300 { return nil, ErrTokenFutureIssued }
    if p.Purpose != "enroll" { return nil, ErrTokenWrongPurpose }
    return &p, nil
}
```

### 4.5 POST /enroll (wg_hub)

```
POST https://organic-machine.com/enroll
Content-Type: application/json

{
  "enrollment_token": "eyJhbGxv...QwE",
  "device_pubkey_wg": "K3v8...j0c=",       // WG public key del device, generada por wg_keygen
  "device_hostname": "home-wsl",
  "device_os": "linux-wsl2",
  "device_arch": "x86_64"
}
```

Response:

```json
{
  "ok": true,
  "wg_config": "[Interface]\nPrivateKey = <keep on device>\nAddress = 10.42.0.10/24\n[Peer]\nPublicKey = ...\nEndpoint = organic-machine.com:51820\nAllowedIPs = 10.42.0.0/24\nPersistentKeepalive = 25\n",
  "manifest": { /* signed manifest */ },
  "matrix_room": "!abc123:organic-machine.com",
  "matrix_invite_url": "https://matrix.to/#/!abc123:organic-machine.com?via=organic-machine.com"
}
```

Hub marca el token como `consumed` en `wg_enrollment_tokens` (token_nonce as PK) — segundo uso rechazado con `nonce_replay`.

---

## 5. Replay protection

### 5.1 Nonces

- 16 bytes `crypto/rand` por request.
- Server (device_agent O hub) mantiene tabla `seen_nonces`:

```sql
CREATE TABLE IF NOT EXISTS seen_nonces (
    nonce TEXT PRIMARY KEY,           -- base64url
    seen_at INTEGER NOT NULL,         -- unix seconds
    request_id TEXT NOT NULL,
    expires_at INTEGER NOT NULL       -- seen_at + 300
);
CREATE INDEX IF NOT EXISTS idx_seen_nonces_expires ON seen_nonces(expires_at);
```

- TTL = 300s. Job periodico (cada 60s) borra entradas con `expires_at < now()`.

### 5.2 Timestamp

- `ts` debe estar en `[now-60, now+30]`. Mas viejo → `nonce_replay`. Mas futuro → `signature_invalid` con `details.reason="clock_skew"`.
- Asume devices con NTP sync (`chrony`/`systemd-timesyncd`). Si un device tiene clock drift >30s, el operador recibe alerta en `#operator-approvals`.

### 5.3 Algoritmo

```go
// Pseudo
func AcceptNonce(db *sql.DB, nonce string, ts int64, requestID string) error {
    now := time.Now().Unix()
    if ts < now - 60 { return ErrNonceReplay }
    if ts > now + 30 { return ErrSignatureInvalid /* clock_skew */ }
    _, err := db.Exec(
        `INSERT INTO seen_nonces(nonce, seen_at, request_id, expires_at) VALUES(?,?,?,?)`,
        nonce, now, requestID, now+300,
    )
    if isUniqueViolation(err) { return ErrNonceReplay }
    return err
}
```

`AcceptNonce` se llama **antes** de ejecutar la capability, despues de verificar la firma. Si la firma es invalida pero el nonce es nuevo, NO se inserta (evita amplificar log spam).

---

## 6. Approval flow

Para capabilities con `requires_approval: true`, device_agent NO ejecuta sin recibir un approval token firmado por el operador.

### 6.1 Secuencia

```
[operator]      [agents_and_robots]      [device_agent]      [#operator-approvals]
   |                    |                       |                    |
   | !exec rm -rf /tmp/x in #dev-home-wsl       |                    |
   |------------------->|                       |                    |
   |                    |--- request envelope ->|                    |
   |                    |                       |--- decide: approval needed
   |                    |                       |                    |
   |                    |<--- approval_request -|                    |
   |                    |--- post to #op-approvals ----------------->|
   |                    |                       |                    |
   |<--- notification --|                       |                    |
   |                                                                 |
   |--- reacts 👍 OR posts !approve req_01J9... ------------------->|
   |                                                                 |
   |                    |<--- captures reaction/cmd -----------------|
   |                    |--- signs approval_token (via operator key)
   |                    |--- posts approval_token to #dev-home-wsl
   |                    |                       |                    |
   |                    |--- approval_token --->|                    |
   |                    |                       |--- verifies token  |
   |                    |                       |--- executes        |
   |                    |<--- response ---------|                    |
   |<-- output in #dev-home-wsl                                      |
```

### 6.2 Approval token payload

```json
{
  "protocol_version": "mesh/1",
  "purpose": "approval",
  "request_id": "req_01J9XYZABCDEF",
  "manifest_id": "manifest_home-wsl_v3",
  "capability": "shell.exec",
  "args_hash": "a3f5...09bc",
  "approver": "egutierrez@aurgi.com",
  "approved_at": 1748131245,
  "expires_at": 1748131305,
  "nonce": "Yk9p6Xs_3hZQk4mB7lWcvA"
}
```

`args_hash` debe coincidir con `sha256_hex(json_canonical(args))` del request original — evita que el operador apruebe `ls /tmp` y el bot reemplace por `rm -rf /tmp`.

### 6.3 Wire format

Igual que enrollment token: `base64url(payload) + "." + base64url(signature)`, domain separator `"mesh/1/approval\n"`.

### 6.4 Captura por agents_and_robots

`agents_and_robots` corre como bot Matrix con la operator key cargada (a traves de `pass operator/ed25519` montado en `/etc/agents_and_robots/operator.key` con permisos 400, owned by service user). Cuando detecta:

- Reaccion `m.reaction` con key `👍` (U+1F44D) sobre el evento `approval_request` en `#operator-approvals`, **emitida por el matrix_id del operador** (configurado en `apps/agents_and_robots/config.yaml::operator_matrix_id`).
- O mensaje `!approve <request_id>` en `#operator-approvals` desde el mismo matrix_id.

Entonces firma el approval token y lo envia a device_agent (via Matrix event `m.capability.approval` en el room del device).

### 6.5 Timeout

Si device_agent no recibe approval token en 60s tras enviar approval_request, responde al room con error `approval_timeout`. El operador puede re-emitir el comando original (genera nuevo `request_id`, nuevo nonce, nueva approval).

### 6.6 Approval denegada

Reaccion `👎` (U+1F44E) o comando `!deny <request_id>` → bot firma un `approval_denied_token` (mismo formato + `denied=true`). device_agent responde `approval_denied`.

### 6.7 Verificacion en device_agent

```go
// Pseudo
func VerifyApproval(token string, req Request, pubkey []byte) error {
    payload, err := decodeApprovalToken(token, pubkey)
    if err != nil { return err }
    if payload.RequestID != req.RequestID { return ErrApprovalMismatch }
    if payload.Capability != req.Capability { return ErrApprovalMismatch }
    if payload.ArgsHash != sha256Hex(canonicalJSON(req.Args)) { return ErrApprovalMismatch }
    if payload.ExpiresAt < time.Now().Unix() { return ErrApprovalExpired }
    if payload.Denied { return ErrApprovalDenied }
    return nil
}
```

---

## 7. Audit log hash chain

Append-only log local a cada device_agent con hash chain que detecta tampering. Replicado periodicamente al hub para archivo tamper-evident off-device.

### 7.1 Schema (`apps/device_agent/audit.db`)

```sql
CREATE TABLE IF NOT EXISTS audit_log (
    id           INTEGER PRIMARY KEY AUTOINCREMENT,
    ts           INTEGER NOT NULL,
    request_id   TEXT NOT NULL,
    manifest_id  TEXT NOT NULL,
    capability   TEXT NOT NULL,
    args_hash    TEXT NOT NULL,
    approval_id  TEXT,              -- nullable, request_id del approval token usado
    exit_code    INTEGER,           -- nullable mientras no haya respuesta
    ok           INTEGER NOT NULL,  -- 0/1
    error_code   TEXT,              -- nullable
    duration_ms  INTEGER NOT NULL,
    prev_hash    TEXT NOT NULL,     -- hex 64 chars
    this_hash    TEXT NOT NULL,     -- hex 64 chars
    UNIQUE(request_id)
);
CREATE INDEX IF NOT EXISTS idx_audit_log_ts ON audit_log(ts);
```

Migracion vive en `apps/device_agent/migrations/001_init.sql`. Regla `db_migrations.md`.

### 7.2 Hash chain

```
record_canonical = ts + "|" + request_id + "|" + manifest_id + "|" +
                   capability + "|" + args_hash + "|" + approval_id_or_empty + "|" +
                   exit_code_str + "|" + ok_str + "|" + error_code_or_empty + "|" +
                   duration_ms_str

this_hash = sha256_hex(prev_hash + "\n" + record_canonical)
```

Para el primer registro `prev_hash = "0000...0000"` (64 zeros).

`wg_peer_revoke_go_infra` (ya existente) hace algo similar para revocations; este spec usa el mismo patron para todas las invocaciones.

### 7.3 Append helper

```go
// device_audit_append_go_infra (issue 0135)
func AppendAudit(db *sql.DB, rec Record) (string, error) {
    var prev string
    err := db.QueryRow(`SELECT this_hash FROM audit_log ORDER BY id DESC LIMIT 1`).Scan(&prev)
    if err == sql.ErrNoRows {
        prev = strings.Repeat("0", 64)
    } else if err != nil {
        return "", err
    }
    canonical := canonicalRecord(rec)
    h := sha256.Sum256([]byte(prev + "\n" + canonical))
    this := hex.EncodeToString(h[:])
    _, err = db.Exec(`INSERT INTO audit_log(...) VALUES(...)`, /* fields, prev, this */)
    if err != nil { return "", err }
    return this, nil
}
```

Transaccion con `BEGIN IMMEDIATE` para evitar carrera entre prev_hash select y insert.

### 7.4 Verificacion (cualquiera con copia del db)

```go
// device_audit_verify_go_infra (issue 0135)
func VerifyChain(db *sql.DB) error {
    rows, _ := db.Query(`SELECT id, prev_hash, this_hash, /* fields */ FROM audit_log ORDER BY id`)
    expected := strings.Repeat("0", 64)
    for rows.Next() {
        var rec Record
        rows.Scan(&rec.ID, &rec.PrevHash, &rec.ThisHash /* ... */)
        if rec.PrevHash != expected { return fmt.Errorf("chain broken at id %d", rec.ID) }
        canonical := canonicalRecord(rec)
        h := sha256.Sum256([]byte(rec.PrevHash + "\n" + canonical))
        if hex.EncodeToString(h[:]) != rec.ThisHash {
            return fmt.Errorf("hash mismatch at id %d", rec.ID)
        }
        expected = rec.ThisHash
    }
    return nil
}
```

### 7.5 Replicacion al hub

Cada 60s device_agent hace `POST /audit/replicate` al hub con el bloque de registros nuevos (delta sobre el ultimo replicado). El hub valida la cadena, anade su propio `replicated_at`, y almacena en `apps/wg_hub/operations.db::device_audit` (tabla espejo + meta `last_replicated_id` por device).

Si el hub detecta `chain_broken` o `hash_mismatch`, emite evento a `#operator-approvals` con severity=critical y marca device como `status='compromised'` en `wg_peers`.

---

## 8. Room ↔ device mapping

### 8.1 Schema (`apps/agents_and_robots/operations.db`)

```sql
CREATE TABLE IF NOT EXISTS room_devices (
    room_id      TEXT PRIMARY KEY,            -- !abc123:organic-machine.com
    device_id    TEXT NOT NULL,
    manifest_id  TEXT NOT NULL,
    role         TEXT NOT NULL,               -- 'device' | 'container' | 'approval' | 'broadcast'
    created_at   INTEGER NOT NULL,
    updated_at   INTEGER NOT NULL,
    active       INTEGER NOT NULL DEFAULT 1
);
CREATE INDEX IF NOT EXISTS idx_room_devices_device_id ON room_devices(device_id);
CREATE INDEX IF NOT EXISTS idx_room_devices_role ON room_devices(role);
```

Migracion: `apps/agents_and_robots/migrations/NNN_room_devices.sql`.

### 8.2 Roles especiales

- `role='approval'`: hay exactamente UN room con este rol, default alias `#operator-approvals:organic-machine.com`. Bot publica `approval_request` aqui y escucha reacciones del operador.
- `role='broadcast'`: alias `#operator-broadcast:organic-machine.com`. Bot publica eventos de control firmados (revocations, manifest rotations).
- `role='device'`: room 1:1 por device. Alias por convencion `#dev-<device_id>:organic-machine.com`.
- `role='container'`: para modo "deep" docker (containers como peers WG). Alias `#cont-<container_id>:organic-machine.com`.

### 8.3 Resolucion al dispatchar

Cuando el bot recibe un `!cmd` en cualquier room:

1. Busca `SELECT device_id, manifest_id, role FROM room_devices WHERE room_id=? AND active=1`.
2. Si no existe → ignora (o responde "this room is not bound to a device").
3. Si `role='device'`, dispatcha al `device_agent` correspondiente.
4. Si `role='approval'` o `role='broadcast'`, NO acepta `!exec`/`!fs.*`/`!docker.*` — solo `!approve`, `!deny`, `!revoke`, `!help`.

---

## 9. Element commands

Comandos que el bot de `agents_and_robots` parsea y traduce a envelopes. Estos viven en rooms `role='device'` o `role='container'` (excepto `!approve`/`!deny` que viven en `role='approval'`).

| Command | Capability | Args | Notas |
|---|---|---|---|
| `!help` | (meta) | none | Bot responde con capability matrix del manifest del device del room |
| `!exec <argv...>` | `shell.exec` | `{argv: [...], cwd?: string}` | argv splits por shlex, sin shell wrapping |
| `!fs.read <path> [bytes]` | `fs.read` | `{path, max_bytes?}` | default max_bytes = manifest.max_bytes |
| `!fs.write <path> <<<content` | `fs.write` | `{path, content_base64}` | content viene en heredoc o quoted; bot codifica base64 |
| `!fs.ls <path>` | `fs.list` | `{path}` | output: array de {name,type,size} |
| `!docker exec <container> <argv...>` | `docker.container.exec` | `{container, argv}` | container debe estar en `containers_allowed` |
| `!docker logs <container> [tail]` | `docker.container.logs` | `{container, tail?, follow?}` | `--follow` activa SSE |
| `!docker ps` | `docker.container.list` | `{}` | output: tabla containers vivos |
| `!approve <req_id>` | (meta) | `{request_id}` | solo en `role='approval'`, solo del operator_matrix_id |
| `!deny <req_id>` | (meta) | `{request_id, reason?}` | idem |
| `!revoke <device_id>` | (meta) | `{device_id, reason?}` | solo del operator_matrix_id; emite `manifest_revoked` + `wg_peer_revoke` |
| `!status` | (meta) | none | bot responde: device IP WG, last_handshake, manifest_id activo, capabilities count |

### 9.1 Parsing rules

- Lexer shlex-style (`shlex.split` Python o equivalente). Quoted strings respetan espacios.
- Si parsing falla → `!help` corto en la misma linea + abort.
- Args desconocidos para una capability → `manifest_invalid` con `details.unknown_args: [...]`.

### 9.2 Output rendering

El bot formatea responses para Matrix:

- `ok=true`, output corto (<2KB): formatted text con `<pre><code>...</code></pre>` (Matrix `formatted_body`).
- `ok=true`, output largo: trim a 2KB + link al artifact subido (Matrix media repo si el homeserver lo permite, sino paste a `paste.organic-machine.com`).
- `ok=false`: render como `[ERROR error_code] message\n<details>` con codigo de color rojo en clientes que soportan colored text.

---

## 10. Error model

Todos los `error.code` son strings snake_case. El cliente NO debe parsear `message` — solo `code`. `details` es objeto libre por code.

| code | meaning | details fields | retry? |
|---|---|---|---|
| `manifest_invalid` | Manifest no firma, expirado, device_id mismatch, o no tiene la capability | `reason`, `manifest_id`, `expires_at?` | no — pedir manifest nuevo |
| `capability_denied` | Capability esta en manifest pero los args violan constraints | `constraint_violated`, `value` | no — ajustar args |
| `binary_not_whitelisted` | shell.exec con binario fuera de `binaries_whitelist` | `binary`, `whitelist` | no |
| `path_not_allowed` | fs.* con path fuera de `paths_allowed` o en `paths_denied` | `path`, `allowed_globs`, `denied_globs` | no |
| `container_not_allowed` | docker.* sobre container fuera de `containers_allowed` | `container`, `allowed_list` | no |
| `approval_timeout` | requires_approval=true y no llego token en 60s | `waited_s` | si — re-enviar |
| `approval_denied` | operador denego | `approver`, `reason?` | no |
| `approval_mismatch` | approval token args_hash != request args_hash | `expected_hash`, `got_hash` | no — posible MITM |
| `nonce_replay` | nonce ya visto en ventana TTL=300s | `nonce`, `first_seen_at` | no — generar nonce nuevo |
| `signature_invalid` | firma ed25519 no verifica | `reason` (e.g. `clock_skew`, `bad_pubkey`, `corrupted`) | no |
| `token_expired` | enrollment o approval token expirado | `expires_at`, `now` | no |
| `token_consumed` | enrollment token ya usado (nonce en `wg_enrollment_tokens`) | `first_use_at` | no |
| `device_revoked` | device esta en revocation list | `revoked_at`, `reason` | no |
| `capability_not_found` | capability name no existe en device_agent | `name`, `available` | no |
| `execution_failed` | la capability ejecuto y devolvio exit != 0 | `exit_code`, `stderr` (trimmed) | depende — semantica de la capability |
| `output_too_large` | output > `max_output_bytes` | `bytes`, `limit` | no — pedir con tail/head |
| `duration_exceeded` | timeout `max_duration_s` excedido | `limit_s`, `killed_signal` | no |
| `transport_error` | error de Matrix/HTTP transport debajo del envelope | `transport`, `inner_error` | si con backoff |
| `internal` | bug en device_agent/hub/bot; NO leakear stack al room | `incident_id` | no — operator debe ver logs |

### 10.1 Mapping a HTTP status (transport HTTP intra-mesh)

| code | HTTP |
|---|---|
| `manifest_invalid`, `signature_invalid`, `token_*` | 401 |
| `capability_denied`, `binary_not_whitelisted`, `path_not_allowed`, `container_not_allowed`, `device_revoked` | 403 |
| `capability_not_found` | 404 |
| `nonce_replay`, `approval_mismatch` | 409 |
| `approval_timeout`, `duration_exceeded` | 408 |
| `output_too_large` | 413 |
| `approval_denied` | 403 |
| `execution_failed` | 200 (con ok=false, exit_code en body) |
| `transport_error`, `internal` | 500 |

Matrix transport ignora HTTP status — el `ok=false` y `error.code` son suficientes.

---

## 11. Security threat model

Top 10 ataques + mitigaciones. Listadas por probabilidad x impacto. Cada item refiere al control que lo mitiga.

### T1. Operator ed25519 key leak

- **Attack**: laptop comprometida, `pass operator/ed25519` exfiltrado.
- **Impact**: atacante firma manifests + approvals — control total de devices.
- **Mitigation**:
  - GPG-encrypted at rest via `pass` (depende de GPG subkey).
  - Rotacion forzada: `!revoke-all` en `#operator-broadcast` → todos los devices reciben `manifest_revoked` con `device_id="*"` → entran en modo enroll.
  - Hardware-backed key (YubiKey, ssh-agent con touch policy) — out of scope v1, candidato a issue futuro.
  - Detection: hub registra todas las firmas (mensaje `signed_by_operator_at`); operador revisa diariamente.

### T2. Compromised device executes unauthorized capabilities

- **Attack**: device_agent comprometido, atacante quiere ejecutar capabilities fuera del manifest.
- **Impact**: limitado a las capabilities del manifest (asumiendo verify es correcto).
- **Mitigation**:
  - Manifest verify obligatorio antes de cada request (§2.5).
  - Sandbox: `firejail` (Linux) o equivalente — ver issue 0140.
  - Whitelist binarios + paths + containers (§2).
  - Audit chain replicado a hub (§7.5) — atacante no puede borrar audit.

### T3. Replay attack

- **Attack**: atacante captura request firmado valido (de un log, de Matrix federation leak), lo reenvia.
- **Impact**: capability ejecutada 2x.
- **Mitigation**: §5. Nonce TTL=300s + ts window 60s. SQLite UNIQUE constraint.

### T4. MITM despite WireGuard

- **Attack**: alguien dentro del mesh WG (otro device comprometido) intercepta requests entre bot y device.
- **Impact**: leer args/output; modificar args si firma se ignora.
- **Mitigation**:
  - HTTP intra-mesh sobre TLS (cert auto-firmado mesh-only, pinned).
  - Matrix transport: E2EE via Olm/Megolm — bot debe verificar device keys del room antes de aceptar.
  - Firma del envelope (§1.3) — args modificados → `signature_invalid`.

### T5. Container escape

- **Attack**: container con `docker.container.exec` activado escapa a host.
- **Impact**: host comprometido, no mas que T2.
- **Mitigation**:
  - `binaries_whitelist` estricta en `docker.container.exec` (sin `bash`, `sh`, `nsenter`, `unshare`).
  - Modo "deep" (container con WG-peer propio) solo para containers de propia infra (`agents_and_robots`, `registry_api`).
  - Docker socket NUNCA expuesto via capability (capability solo via `docker_container_exec_go_infra` que NO usa `--privileged` en exec).
  - Detection: container con syscalls anomalas → logged por seccomp profile (out of scope v1).

### T6. Malicious manifest with crafted globs

- **Attack**: operador firma manifest con `paths_allowed: ["/home/lucas/**"]` pero device_agent tiene bug en glob matcher que permite `..` traversal.
- **Impact**: fs.read fuera del directorio.
- **Mitigation**:
  - Implementacion glob: `filepath.Match` Go + canonicalizar path con `filepath.Clean` + verificar `strings.HasPrefix(cleaned, allowed_prefix)`.
  - Reject paths con `..` antes de glob match.
  - Test suite con corpus de path traversal (`../../etc/passwd`, `/home/lucas/../etc/passwd`, symlinks).

### T7. Enrollment token theft

- **Attack**: token QR fotografiado por tercero.
- **Impact**: tercero hace POST /enroll con su propia WG pubkey → device fantasma en la mesh.
- **Mitigation**:
  - TTL=600s.
  - Single-use (nonce consumed en hub).
  - Operador recibe alerta en `#operator-approvals` cada vez que un device hace POST /enroll exitoso — si no esperabas un enroll, `!revoke` inmediato.

### T8. Matrix homeserver compromise

- **Attack**: atacante root en `organic-machine.com` modifica eventos Matrix.
- **Impact**: si E2EE roto, todo el contenido leak. Si E2EE OK, solo metadata.
- **Mitigation**:
  - Megolm E2EE entre operador y bot — keys nunca en disco del homeserver.
  - Envelope firmado (§1.3) — atacante no puede inyectar requests sin operator key.
  - Hub WG segregado: `wg_hub` corre en mismo VPS pero NO confia en Matrix para autorizacion (solo para transport).

### T9. Clock skew abuse

- **Attack**: device con clock muy adelantado firma requests con `ts` futuro grande, los almacena, los reenvia cuando `ts` cae en ventana.
- **Impact**: replay extendido mas alla de TTL.
- **Mitigation**:
  - Ventana ts: `[now-60, now+30]` — clock skew tolerado pequeño.
  - Devices forzados a sync NTP (chrony) — el provision check verifica `chronyc tracking` reporta `Leap status: Normal`.
  - Hub alerta a `#operator-approvals` si recibe replicacion de audit con `ts` que difiere >30s del `received_at`.

### T10. Denial of service via approval flooding

- **Attack**: atacante con manifest valido pero capabilities limitadas spam `requires_approval=true` requests para inundar `#operator-approvals`.
- **Impact**: operador pierde signal en noise; legitimo approval enterrado.
- **Mitigation**:
  - Rate limit en agents_and_robots: por device_id, max 10 approval_requests / 5min.
  - Excedente → silently dropped + audit entry + `#operator-approvals` recibe resumen agregado (`device home-wsl: 47 approval requests in 5min, throttled`).
  - Si pattern repetido, operador `!revoke home-wsl`.

---

## 12. Implementation order

Las issues 0135-0143 implementan lo definido en este spec. Dependencias y orden:

| # | Issue | Que entrega | Depende de | Bloquea |
|---|---|---|---|---|
| 0135 | capability manifest sign/verify funcs | `capability_manifest_sign_go_infra`, `capability_manifest_verify_go_infra`, `enrollment_token_create_go_infra`, `enrollment_token_verify_go_infra`, `device_audit_append_go_infra`, `device_audit_verify_go_infra`, `operator_keygen_bash_infra` | 0134 (spec) | 0136, 0137, 0140, 0142 |
| 0136 | provision_wg_hub pipeline | `provision_wg_hub_bash_pipelines` que compone las 9 funciones `wg_*` (ver flow 0009 Fase C) | 0135 (audit funcs solamente; resto independiente) | 0137 |
| 0137 | wg_hub Go service | `apps/wg_hub/` con endpoints `POST /enroll`, `GET /peers`, `POST /peers/:id/revoke`, `POST /audit/replicate`, SSE `/events` | 0135, 0136 | 0138, 0139 |
| 0138 | agents_dashboard Mesh panel | Panel ImGui en `apps/agents_dashboard/` con lista de peers, last_handshake, bytes rx/tx, approval queue, boton revoke | 0137 | — |
| 0139 | enroll_device pipeline | `enroll_device_bash_pipelines` que el operador corre en su laptop para enroll un device nuevo (genera token, lo muestra como QR, hace POST /enroll en nombre del device si tiene SSH) | 0135, 0137 | 0140, 0141 |
| 0140 | device_agent Go binary | `apps/device_agent/` — Matrix client + capability dispatcher + sandbox firejail + audit chain. Cross-compile linux/amd64, linux/arm64, windows/amd64 | 0135, 0139 | 0142 |
| 0141 | Android Termux variant | `apps/device_agent_android/` — variante para Termux con WG via wg-go (userspace) y capabilities limitadas (no firejail) | 0140 | — |
| 0142 | Matrix bot dispatcher routes | Extender `apps/agents_and_robots/` con dispatcher `m.capability.*` → device, parse de comandos §9, room_devices table | 0135, 0137, 0140 | 0143 |
| 0143 | Operator approval flow | Capturar reactions en `#operator-approvals`, firmar approval tokens, enviar a device, registrar timeout. En `apps/agents_and_robots/` | 0142 | — |

### 12.1 Paralelismo

- 0135 secuencial (todo lo demas depende).
- 0136 + 0140 paralelos tras 0135.
- 0137 espera 0136 (necesita las funciones `wg_*`).
- 0138 + 0139 + 0140 paralelos tras 0137.
- 0141 tras 0140.
- 0142 + 0143 ultimo bloque.

Skill `parallel-fix-issues` puede orquestar 0136/0140 y 0138/0139 en worktrees aislados (ojo: 0140 crea sub-repo `apps/device_agent/`, requiere `git init` dentro como dice `apps_subrepo.md`).

### 12.2 Acceptance gate para cerrar 0134

- [ ] Este documento mergeado en `dev/issues/`.
- [ ] Issues 0135-0143 creados con frontmatter coherente (`dependencies` apuntando aqui, `related_flows: [0009]`).
- [ ] Capabilities groups `wireguard`, `device-agent`, `docker-agent` con stubs en `docs/capabilities/` referenciando este spec.
- [ ] No changes en wire format hasta que todos los issues 0135-0143 cierren — cambios posteriores requieren nuevo issue + bump `protocol_version`.

---

## Notas

### Wire format evolution policy

`protocol_version: mesh/1` es immutable durante el ciclo de vida de las issues 0135-0143. Cualquier cambio breaking (renombrar campo, cambiar canonical bytes, anadir campo obligatorio) requiere bump a `mesh/2` con un issue nuevo que documente migracion y compat layer.

Cambios non-breaking aceptados sin bump:
- Anadir nuevos `error.code` (clientes los manejan via fallback a `internal`).
- Anadir nuevas capabilities (devices viejos las rechazan con `capability_not_found`).
- Anadir campos opcionales con default backwards-compatible.

### Test corpus

Cada funcion de §3 y §4 entrega test fixtures en `cpp/functions/*/testdata/` o equivalente:

- `manifest_valid.json` + `manifest_valid.sig` — par validable.
- `manifest_expired.json` — para test de §2.5 paso 4.
- `manifest_tampered.json` + sig original — para test de signature_invalid.
- `enroll_token_valid.txt`, `enroll_token_expired.txt`, `enroll_token_wrong_purpose.txt`.
- `path_traversal_corpus.txt` con 50+ paths maliciosos para test T6.

### Capability groups stubs

Como parte de este issue se crean stubs minimos en:

- `docs/capabilities/wireguard.md` — lista de las 9 funciones `wg_*` (referenciadas desde flow 0009).
- `docs/capabilities/device-agent.md` — capability dispatcher + sandbox + audit chain.
- `docs/capabilities/docker-agent.md` — capabilities sobre containers.

Cada uno con seccion `## Ejemplo canonico` + `## Fronteras` segun regla `capability_groups.md`. Los stubs se llenan a medida que las funciones se crean en 0135-0142.

### Observabilidad

- Cada envelope request/response loggea en `call_monitor.calls` con `function_id = capability_<name>_<lang>_<domain>` cuando la implementacion exista. Si la capability es solo metadata (`!help`), no se loggea.
- `audit_log` (§7) es separado de `call_monitor` — el primero es tamper-evident del operator, el segundo es telemetria del agente Claude.
- Panel "Mesh" de `agents_dashboard` (issue 0138) consume:
  - `wg_hub::wg_peers` (peers vivos + last_handshake + tx/rx).
  - `wg_hub::device_audit` (replica de audit chains — para verificacion offline).
  - `agents_and_robots::room_devices` (mapping rooms ↔ devices).
  - `agents_and_robots::approvals_pending` (queue de approvals pendientes).

### Capability growth log

`v0.1.0 (2026-05-24)` — initial spec mesh/1.