# Network Security and Tokens

The genesis network has three orthogonal layers of cryptographic enforcement:

1. **Identity** — every peer has a stable Ed25519 identity. Every message is signed.
2. **Authority** — server-signed tokens grant a peer the right to do specific things in a specific mesh/session.
3. **Trust** — cross-mesh interactions require a `MeshTrustToken` that establishes one mesh's willingness to accept envelopes from another.

This document is the reference for all three.

## Layer 1 — Message-level integrity (NET-27, NET-30)

`network-plugin-crypto-messages` is the layer.

### Per-message Ed25519 signatures (NET-27)

Every outbound `MessageEnvelope` from a host (Tier 0 or Tier 1) carries an Ed25519 signature in its headers. Inbound signatures are verified using peer public keys from the registry. Invalid signatures cause the message to be **dropped silently** (and the sender's reputation in `HostHistory` to take a hit).

The key material is the same drive-identity key used by the chunks plugin — one Ed25519 keypair per peer, used at multiple layers. Generated and stored by `@suaveplan/crypto-vault` (BIP39 mnemonic + Argon2id KDF + zeroize on lock).

### Peer identity challenge-response (NET-30)

When two peers handshake, they perform a challenge-response to verify identity:

```text
A → B: peerA_pubkey, nonceA
B → A: peerB_pubkey, nonceB, sigB(peerA_pubkey ‖ nonceA)
A → B: sigA(peerB_pubkey ‖ nonceB)
```

Any peer claiming `peerB_pubkey` who can't produce `sigB(...)` is rejected. This catches spoofed peer-IDs at handshake before they make it into the registry.

## Layer 2 — Authority tokens (NET-28, NET-29, NET-106..NET-109)

Three token shapes, all server-signed (in models with a server):

### `MeshToken` (NET-29)

```ts
interface MeshToken {
  meshId: string;
  maxCapacity: number;
  allowedTiers: ('tier-0' | 'tier-1' | 'tier-2')[];
  hostingModel: 'PURE_CLIENT' | 'SERVER_BASED' | 'SERVER_TO_CLIENT_FAILOVER' | 'CLIENT_WITH_SERVER_BACKUP';
  expiresAt: number;
  serverSignature: Uint8Array;  // Ed25519 over canonicalSerialize(this without the sig)
}
```

Required for mesh creation. The mesh's hosting model lives here. Long expiry (days/weeks).

### `SessionToken` (NET-28)

```ts
interface SessionToken {
  sessionId: string;
  parentSessionId: string | null;
  capacity: number;
  rulesHash: string;       // hash of the session's policy doc
  expiresAt: number;
  serverSignature: Uint8Array;
}
```

Required for session creation. Sessions can nest (NET-19) up to depth 4. The `rulesHash` pins the session's policy at issuance time so it can't be silently mutated.

### `CapabilityToken` (NET-108, NET-109)

```ts
interface CapabilityToken {
  peerId: string;
  meshId: string;
  tier: 'tier-0' | 'tier-1' | 'tier-2';
  capabilities: string[];  // e.g. ['relay', 'vote', 'admit-peer']
  issuedAt: number;
  expiresAt: number;
  serverSignature: Uint8Array;
}
```

Issued when a peer joins. The `capabilities` array constrains what the peer is *authorised* to do regardless of what the protocol allows it to *attempt*. A Tier-0 capability token includes `admit-peer`; a Tier-2 doesn't. Cross-tier escalation is blocked at the verifier (NET-48).

`network-plugin-auth` (NET-106..NET-109) is the enforcement plugin. `MeshMembershipVerifier` checks the `authToken` on join against `@suaveplan/auth`. `CapabilityTokenIssuer` mints them. `CrossMeshTrustValidator` (NET-110..NET-112) handles inter-mesh acceptance.

### Tier-specific security policies (NET-48)

```text
Tier 0 — full authority. Can issue tokens (when server isn't available, with grace-period restrictions).
Tier 1 — relay + voting authority. Cannot issue tokens.
Tier 2 — read-only for sensitive operations.
```

`SecurityManager.processTierSecurity(tierId, operation, data)` enforces this on every operation. Cross-tier delegation requires explicit credential transfer from the higher tier.

## Layer 3 — Cross-mesh trust (NET-110..NET-112)

`MeshTrustToken` is what one mesh hands another mesh to say "I'll accept your relay traffic":

```ts
interface MeshTrustToken {
  fromMeshId: string;
  toMeshId: string;
  allowedOperations: string[];   // e.g. ['relay-message', 'cd:request']
  bandwidthQuotaPerHour?: number;
  expiresAt: number;
  bothServerSignatures: [Uint8Array, Uint8Array];  // signed by both meshes' Tier 0
}
```

`CrossMeshTrustValidator` rejects relay envelopes from untrusted mesh ids (NET-110). Tier 0 hosts verify trust tokens before accepting backbone connections (NET-112). Trust decisions are cached with configurable TTL (NET-111) so we don't re-verify on every envelope.

This means a phone-mesh and a corporate-mesh don't automatically interoperate. Two Tier 0 hosts must explicitly establish trust (out of band: typically via a co-signed token issued by both servers, or via a bilateral capability exchange in `PURE_CLIENT` mode).

## Plugin security verifier (NET-47)

`network-plugin-crypto-messages` also validates plugins themselves:

```ts
class PluginSecurityVerifier {
  verifyPlugin(pluginId: string, pluginData: Uint8Array): Promise<boolean>;
  authorizePluginOperation(pluginId, operation, context?): Promise<boolean>;
  monitorPluginActivity(pluginId): void;
  setPluginSecurityPolicy(policy): void;
}
```

The intent is plugin-code signing: a deployment may want to allow only plugins signed by a known publisher key. Plugins requesting capabilities they didn't declare are rejected. Anomalous plugin activity (excessive broadcast, unauthorised operations) is detected and reported.

The old planning corpus admits (`PHASE_6_README.md`) that the resource-monitoring side of this is "currently simulated and would need real metrics in a production environment." Genesis treats it as a hardening backlog item — install the plugin, get signature verification today; resource accounting follows.

## What about the model where the server is gone?

Tokens issued before the server vanished remain valid until their `expiresAt`. `network-plugin-server-bridge` (NET-32) extends grace periods so existing tokens don't expire mid-outage. New tokens cannot be issued — operations that require a fresh token (admit a brand-new peer, create a new session) are queued until the server returns. Existing peers, with valid `CapabilityToken`s, keep operating with full authority.

When the server returns:

1. Buffered signed-log entries replay (NET-33).
2. The server validates each entry's Ed25519 signature against the issuing peer's pubkey.
3. Conflicts are detected (e.g., two peers both claimed Tier-0 in different partitions). Resolution depends on the partition merge strategy (NET-80).
4. The server broadcasts the reconciled state.
5. Queued token-issuance operations execute.

The cryptographic chain — every message signed, every token signed, every audit-log entry signed — is what makes this replay possible. There's no ambiguity about who did what; every action is provenance-stamped.

## Audit log (NET-37..NET-39)

`network-plugin-audit-mesh` keeps an append-only log where each entry includes:

```text
{ seq, prevHash, payload, hostSignature }
```

- `seq` is monotonic.
- `prevHash` makes the log a hash chain — break detection on any tampering.
- `hostSignature` is the issuing host's Ed25519 over `(seq, prevHash, payload)`.

Logs are replicated to at least R sibling hosts (NET-38). CRITICAL events replicate synchronously. Old logs are compacted into signed checkpoints (NET-39) — a snapshot at a given seq, signed by the host, that downstream replicas use to skip the prefix.

This is what gives you a verifiable audit trail across the entire mesh, surviving partitions and server outages.

## Where keys live, end to end

| Key | Owner | Storage | Used for |
| --- | --- | --- | --- |
| Per-peer Ed25519 (drive identity) | The peer | `@suaveplan/crypto-vault` | Signing every message, every chunk, every audit entry |
| Per-mesh server Ed25519 | Central server | Server HSM / `@suaveplan/keys` (when available) | Signing `MeshToken`, `SessionToken`, `CapabilityToken` |
| Cross-mesh trust signing | Both meshes' servers | As above | Co-signing `MeshTrustToken` |
| Per-file `fileKey` (AEAD) | Drive | Wrapped by partition KEK; lives next to manifest | Encrypting chunks |
| Per-partition KEK | `drive-sharing` | Wrapped per-grantee with X25519 sealed-box | Wrapping `fileKey`s |

Keys never cross trust boundaries unwrapped. Wrapping is the only mechanism for delegation.

## Reading further

- [`architecture.md`](./architecture.md) — `MessageEnvelope` and `NetworkBus`.
- [`topology-and-failover.md`](./topology-and-failover.md) — when token issuance is paused.
- [`offline-and-reintegration.md`](./offline-and-reintegration.md) — buffered log replay.
- [`../drive/encryption.md`](../drive/encryption.md) — the drive layer's use of the per-peer Ed25519 key.