Synet Root

Overview

synet-root is the authoritative IP registry and allocation service for the Synet network. It functions as the root of trust for:

Fixed IP issuance to agents or services.
Delegation of subnet ranges to trusted gateways.
Verifying ownership of fixed IP claims.

Every trusted gateway and DNS server in Synet syncs with this service to ensure consistency and security across the mesh.

Core Responsibilities

Responsibility	Description
Fixed IP Registry	Stores and signs assignments for permanent `fd00::/16` addresses.
Gateway Pool Delegation	Allocates subnet blocks to gateways for dynamic DHCP assignment.
Ownership Verification	Allows agents to prove that an IP was assigned to them via cryptographic signatures.
Gateway Sync API	Gateways fetch latest pool state, validations, and delegation list.
Admin Interface (future)	Manual approvals, revocation, metrics.

Address Structure

Type	Format	Example
Fixed	`fd00:0000::1/112`	Reserved by `synet-root`, assigned per-agent.
Gateway Pools	`fd00:1000::/64`	Delegated to a specific `synet-gateway`.
Special Networks	`fd00:ffff::/48`	Reserved for Synet-wide services or experimental routing.

Agent Fixed IP Request Flow

Agent uses synet-dns to request a static IP:

synet-dns request-static-ip --name agent.sy --pubkey 0xABC123...

synet-dns sends a request to synet-root API:

POST /request-ip
{
  "pubkey": "0xABC123...",
  "requested_name": "agent.sy"
}

synet-root checks for conflicts and responds:

{
  "assigned_ip": "fd00::1234",
  "signature": "0xSYNROOTSIG"
}

Agent stores the assignment + signature.

Proving IP Ownership to Gateway

When connecting via synet-gateway, agent submits:

{
  "pubkey": "0xABC123...",
  "requested_ip": "fd00::1234",
  "synroot_signature": "0xSYNROOTSIG"
}

Gateway Flow:

Verifies:
- That IP was assigned to pubkey
- That signature is valid
- That IP is in allowed fixed IP range
Accepts and provisions the tunnel

API Design (REST or gRPC)

Endpoint	Method	Description
`/request-ip`	POST	Request new fixed IP
`/verify-ip`	POST	Return true/false for IP+signature
`/gateway-pools`	GET	List gateway IP blocks and current assignment state
`/assign-pool`	POST (admin)	Allocate subnet to gateway
`/revoke-ip`	POST (admin)	Revoke or recycle IP

Data Model

{
  "ip": "fd00::1234",
  "assigned_to": "0xABC123...",
  "signature": "0xSYNROOTSIG",
  "issued_at": "2025-04-28T00:00:00Z",
  "expires_at": "never"
}

Signed using Synet Root private key
Contains public key of agent
May have an expiry (if future policies change)

CLI Interaction (Future)

We may expose a CLI (synet-rootctl) for:

synet-rootctl assign --to 0xPUBKEY --ip fd00::1
synet-rootctl revoke --ip fd00::1

For now, most access is via the synet-dns or synet-gateway.

Security Principles

Synet Root must remain minimal, deterministic, and signed.
All records can be cached/read-only by gateways.
Full public audit of IP assignment map possible.
No mutable records without signature trace.

Contributions Welcome

Build a simple key-signed ledger for IPs (SQLite or Redis backend)
Expose /verify-ip as a standalone lib
Add admin approval queue
Build gateway-sync helper script
CLI tooling for issuing/revoking IPs (CLI-as-daemon?)

:: synet-root