# Forensic Annotation

The `census annotate` command attaches metadata (notes, tags, case IDs)
to existing attestations via the CertiSigma API.  This enables forensic
case management workflows directly from the CLI.

## Usage

```bash
# Add a note to an attestation
census annotate att_123 --note "Evidence collected during Q1 audit"

# Add a tag and case identifier
census annotate att_123 --tag "case-2026-001" --case-id "FR-2026-42"

# Update the source label
census annotate att_123 --source "forensics-team-alpha"

# Soft-delete metadata (GDPR right-to-erasure)
census annotate att_123 --delete

# JSON output
census annotate att_123 --note "test" --json
```

## Zero-Knowledge Mode

When `--encrypt` is used, metadata is encrypted client-side using
AES-256-GCM (via `certisigma.crypto`) before being sent to the API.
The server stores only ciphertext and sets the `client_encrypted` flag.

```bash
# Generate an encryption key (64 hex characters)
# Store it securely in your config or pass via --encryption-key

# Encrypt metadata before sending
census annotate att_123 --note "Confidential" --encrypt --encryption-key <key>

# Read back and decrypt
census annotate att_123 --note "update" --encrypt --decrypt --json
```

### Key Management

The encryption key can be provided via:
1. `--encryption-key` CLI flag (64 hex characters)
2. `encryption_key` in census config file

Generate a key with Python:

```python
import os
print(os.urandom(32).hex())
```

## SDK Methods Used

| Operation | SDK Method | Auth Required |
|-----------|-----------|---------------|
| Update metadata | `client.update_metadata()` | Yes |
| Delete metadata | `client.delete_metadata()` | Yes |
| Encrypt payload | `certisigma.crypto.encrypt_metadata()` | No (local) |
| Decrypt payload | `certisigma.crypto.decrypt_metadata()` | No (local) |

## Error Handling

- If the API returns an error (e.g. attestation not found, auth failure),
  the error is displayed and the command exits with code 1.
- In JSON mode, the `error` field contains the error message.
- Encryption key validation happens before any API call.
