Security & Obambu nodes

1. Overview: what is an Obambu node?

An Obambu node is a small server (laptop, mini-PC, RPi, etc.) playing three roles:

• content server (documents, broadcasts, structured messages),
• local registry of what exists (index of documents and metadata),
• relay for bundles (LuckyBlocks) moving between zones.

Technically it’s a FastAPI app with SQLite, some folders, and an admin security layer.

2. Storage: files + metadata

The storage code (storage.py) organizes data simply:

• storage/docs/: binary files (.bin) of documents,
• storage/meta/: metadata in JSON,
• storage/obambu.sqlite: SQLite DB tracking devices, content plans, station profiles.

When a document is saved via the admin API (/api/v1/admin/docs), the node:

• decodes the received file (base64) and writes it to storage/docs/<doc_id>.bin,
• computes a hash and size,
• updates the full metadata of the document in SQLite and in a .json file.

For boxes or phones, the “device-side” API lets them simply:

• say hello to the node (/api/v1/device/hello);
• request a config or content plan depending on station type (S, H, K);
• request documents they need (/api/v1/device/content or .../content_stream).

3. Admin security: token & ed25519 signatures

Sensitive operations (add documents, manage station profiles, import bundles) are protected by two mechanisms:

• a simple admin token (X-Admin-Token) for early tests,
• a stronger digital signature based on ed25519.

3.1. How admin signatures work

The admin_sign.py tool generates a key pair (private + public) and signs admin requests:

• the private key stays on the admin’s machine (never on the node),
• the public key is recorded in the node config (ADMIN_PUBKEYS).

For each sensitive request, we sign:

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

The headers sent are then:

• X-Admin-Id: admin ID,
• X-Timestamp: timestamp (seconds),
• X-Signature: ed25519 signature in base64.

The node checks that:

• the admin exists (known public key),
• the timestamp is not too old or too far in the future (clock skew bounded),
• the signature is valid for that method/path/body.

4. “LuckyBlock” bundles: secure opportunistic transport

To cross areas without permanent network, Obambu uses bundles, aka LuckyBlocks: compressed, signed packets of documents carried physically (USB) or by couriers (phones, laptops, S/H boxes).

4.1. Bundle contents

The /api/v1/bundles/export API builds a bundle from the node’s documents:

• select documents (limited list, priority, region, etc.),
• build a JSON “blob” {docs: [...]} then gzip it,
• encode in base64 to travel in a text file,
• create a manifest with:
  • destinations (country, region, mayor, nearest K/H station, optional proxies),
  • priority (P0..P3),
  • doc count / size,
  • global hash of the blob (integrity).

The bundle_carrier.py tool makes it simple to:

• export: fetch a bundle from node A and write it to a file (bundle.json);
• import: send that bundle to node B, which decompresses and reinjects documents.

4.2. Role of the K-station agent

The station_k_agent.py script acts as a minimal agent for a K station (town hall/relay) on laptop or RPi:

• init: records its identity (station_id, region, commune), local API, and token,
• ingest: reads a bundle, checks the manifest, and decides:
  • “it’s for me” → import via /api/v1/bundles/import,
  • “it’s for elsewhere” → place the bundle in outbox/ for later relay.
• export: request a bundle from its local node to a region/mayor and write it to file.