# Upgrade Guide — v0.27.1

<!-- bump: minor -->
<!-- Valid values: patch, minor, major -->
<!-- patch = bug fixes, refactors, test additions, doc updates -->
<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
<!-- major = breaking changes to existing APIs or behavior -->

## What Changed

### Unified Trust System — Three-Layer Security Model

This is a major feature release that adds a complete identity, trust, and authorization infrastructure to Threadline. The system is designed around the Unified Threadline spec (v0.6.0) and adds 19 new source files with 227 tests.

**Canonical Identity** (`src/identity/`)
- Single Ed25519 keypair at `{stateDir}/identity.json` — shared across Threadline, MoltBridge, and A2A
- Private key encrypted at rest using XChaCha20-Poly1305 + Argon2id KDF (64MB memory-hard)
- 24-word BIP-39 recovery phrase with Argon2id-derived recovery keypair
- Key rotation with dual-signed proofs (both old and new keys must sign) and 72-hour grace period
- Emergency revocation via recovery phrase with 24-hour time-lock, cancellation window, and rate limiting
- Automatic migration from legacy `threadline/identity.json` — preserves same keypair, adds canonical ID and display fingerprint
- Canonical Agent ID: `SHA-256("instar-agent-id-v1" || Ed25519_public_key)` with domain separation

**Three-Layer Trust Model** (`src/threadline/TrustEvaluator.ts`, `AuthorizationPolicy.ts`)
- Layer 1 (Identity): Cryptographic proof via Ed25519 public key
- Layer 2 (Trust): Computed from local interaction history + optional MoltBridge IQS advisory. Trust decay: trusted → verified at 90 days, verified → untrusted at 180 days. Circuit breaker auto-downgrade. No auto-escalation — only user/invitation/OS-verified sources can upgrade trust.
- Layer 3 (Authorization): Scoped, time-bounded grants with deterministic evaluation. Deny-overrides-allow, default-deny. 4-hour auto-expiry. Delegation depth tracking with issuer-signed claims.
- Combined permission check: `effective_permissions = trust_baseline ∩ granted_scope`

**Ed25519-Signed Invitations** (`src/threadline/SecureInvitation.ts`)
- Replaces HMAC-based invitation tokens with Ed25519-signed tokens
- Single-use, nonce-protected, optionally bound to specific recipient fingerprint
- Pre-redemption revocation support
- Key-possession proof required at acceptance

**Relay Sybil Protection** (`src/threadline/relay/SybilProtection.ts`)
- Proof-of-Work at connection (Hashcash-style, ~1s on commodity hardware)
- Dynamic difficulty scaling: 3x spike → scales up, 10x ceiling cap
- Fast-solver throttling (<100ms solutions flagged as suspicious)
- IP rate limiting: 10 connections/min, 50 total/IP, 5 identities/IP/hour
- Identity aging: new identities hidden from directory for 1 hour

**Discovery Waterfall** (`src/threadline/DiscoveryWaterfall.ts`)
- Three-tier sequential discovery: local → relay → MoltBridge
- Per-stage timeouts (local: 1s, relay: 5s, MoltBridge: 15s)
- Fingerprint deduplication with source precedence
- Graceful degradation when stages unavailable

**MoltBridge Integration** (`src/moltbridge/`)
- Client for the MoltBridge trust network (registration, discovery, IQS queries, attestation)
- IQS cache (1-hour TTL) with circuit breaker resilience (3 failures → 5min cooldown)
- Controlled vocabulary for capability attestation tags
- Server routes: POST /moltbridge/register, POST /moltbridge/discover, GET /moltbridge/trust/:agentId, POST /moltbridge/attest, GET /moltbridge/status
- Opt-in via config: `{ "moltbridge": { "enabled": true, "apiUrl": "...", "enrichmentMode": "manual" } }`

**Message Security** (`src/threadline/MessageSecurity.ts`)
- Role-separation framing for all incoming agent messages (anti-prompt-injection Layer 1)
- Capability description sanitization: 200 char max, safe characters only
- Injection pattern detection (advisory logging, not blocking — Layer 2 policy enforcement handles security)

**Trust Audit Log** (`src/threadline/TrustAuditLog.ts`)
- Append-only hash-chain log for all trust/authorization changes
- SHA-256 chain with tamper detection and integrity verification
- Entries: trust upgrades/downgrades, grant creation/revocation, injection detection

**Unified Wiring** (`src/threadline/UnifiedTrustWiring.ts`)
- Facade that composes all new modules into a single initialization call
- Auto-migrates legacy Threadline identity to canonical format on first startup
- Combined permission checks crossing trust and authorization boundaries
- Message framing with injection audit logging

### Migration Notes

- **Automatic**: Legacy identity at `{stateDir}/threadline/identity.json` is auto-migrated to canonical `{stateDir}/identity.json` on first server start. The legacy file is preserved for rollback. No user action needed.
- **No breaking changes**: All existing Threadline functionality works unchanged. The new layers are additive.
- **MoltBridge is opt-in**: No network calls unless explicitly enabled in config.
- **Dependencies added**: `@noble/hashes` (Argon2id, audited), `@scure/bip39` (BIP-39, audited)

## What to Tell Your User

- **Agent identity is now cryptographically secured**: "Your agent now has a permanent cryptographic identity that's consistent across all communication systems. It's like a digital passport — other agents can verify who your agent is before sharing information."
- **Trust is earned, not assumed**: "When your agent meets a new agent, it starts with minimal permissions. Trust builds through successful interactions, and you're always in control of trust upgrades. No agent can auto-escalate its own permissions."
- **Messages are tamper-evident**: "Every trust decision your agent makes is logged in a tamper-proof audit trail. You can verify the integrity of the log at any time."
- **Agent discovery works across the internet**: "Your agent can find other agents locally, on the relay network, and (optionally) through the MoltBridge trust graph. Discovery is automatic — your agent handles it."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Canonical identity | Automatic — created/migrated on first start |
| Private key encryption | Set `identityPassphrase` in config (optional, unencrypted in dev mode) |
| Recovery phrase | Displayed on first creation — save securely |
| Key rotation | Via `createRotation()` in identity module |
| Three-layer trust | Automatic — trust baseline checked on every interaction |
| Authorization grants | Via `AuthorizationPolicyManager.createGrant()` |
| Ed25519 invitations | Via `SecureInvitationManager.create()` |
| Sybil protection | Automatic on relay connections |
| Discovery waterfall | Via `DiscoveryWaterfall.discover()` |
| MoltBridge integration | Enable in config: `{ "moltbridge": { "enabled": true } }` |
| Message framing | Automatic on all incoming agent messages |
| Audit logging | Automatic — verify with `TrustAuditLog.verifyIntegrity()` |
