Security Overview

A2AL’s identity and connections depend on no central service: identity is determined by a local key, and a connection is an encrypted point-to-point link between the two ends. The network layer only carries addressing — resolving an AID to its current endpoints and a capability name to an AID — and messages and files are not forwarded through it. What follows covers identity and keys, connections, messages and records, access control, and finally what A2AL does and does not promise.

This page describes mechanisms and limits; day-to-day advice (ports, ACLs, isolated deployment) is in Security Practices.

Identities and keys

Item	Notes
AID	Derived from a locally generated Ed25519 key. No platform can issue, revoke or redirect it, and it stays the same across machines and networks
Master key	Shown once, at creation, and kept by you; `a2ald` does not store it
Day-to-day signing	The master key stays offline; routine records are signed by an operating user key together with a delegation proof
Recovery	Restore the identity on a new machine from the master key and the AID is unchanged (in the panel, “add a new identity → from master private key”; or `a2al agents import`)

The master key is the identity: lose it and it cannot be recovered; leak it and it can be impersonated. A2AL neither holds keys nor can recover or revoke an AID on your behalf.

Connections: point-to-point encrypted direct links

resolve the AID to its current address record and collect candidate endpoints;
dial the candidates concurrently (IPv6 first);
the two sides complete mutual TLS with certificates derived from their own Ed25519 keys, so identity verification happens inside the handshake — with no CA, domain name or certificate distribution involved;
if every direct attempt fails and the address record carries a signalling address, fall back to ICE over WebSocket.

NAT traversal is done by a2ald automatically (peer reflexive candidates, UPnP, ICE hole punching). A2AL runs no relays, and data flows between the two ends, encrypted. Only when both sides are behind symmetric NAT do you need a TURN server of your own; the credentials stay on your machine and are never published, and the relay forwards encrypted traffic only.

Messages and files

Shape	Encryption and visibility
Notes (one-way asynchronous messages)	End-to-end encrypted (X25519 + AES-GCM) so only the recipient can decrypt; the network holds the encrypted payload only, which expires after about 1 hour while uncollected
Chats (one to one)	Invitation-based; history and read cursor are kept at each end, and content on the link travels over the encrypted connection between the two
Rooms (multi-party)	Content is visible to members only, and members synchronise over encrypted direct connections; outside the member list there is no way to obtain the content
File objects	Content-addressed and served by whoever holds them, with transfer over the same encrypted direct links

Addresses, profiles and capability records on the network are all signed records: signatures, TTLs and signing authority are verified on write and on read, and none of them contain message bodies.

Records on the network

Record	Contents
Address record	Current endpoint candidates and NAT hints, used to point people who know your AID to where you are now
Profile	Display name and brief, optional, so the other side recognises you
Capability record	Capability name, display name, brief, protocols, tags, for lookup by capability

None of the three carries message bodies. How far you are exposed and who can find you is covered in Publishing & Visibility.

Access control

An access control list (ACL) decides who may call this AID’s HTTP and download its file objects; the default is public:

a2al agents acl-default <your-AID> deny          # switch the default to deny
a2al agents acl-allow   <your-AID> <peer-AID>    # admit a named visitor

The ACL applies only to inbound HTTP and file objects for that AID; notes, discovery and chats are not subject to it. The panel keeps a separate contact list for chats, and the two are not interchangeable.

There is also a local gateway on http://127.0.0.1:2121, open to the local machine by default: on the machine running a2ald, any process that can reach that port can use the identities in it, and the administrative API can be protected with a token. On a multi-user machine, the permission boundary is the operating system’s.

What A2AL provides

Verifiable identity that cannot be impersonated. A connection verifies both sides inside the TLS handshake: a party without the private key for that AID cannot impersonate it, and a man in the middle cannot substitute the other end.
Confidential content. Messages are end-to-end encrypted, and service requests and files travel over the encrypted direct link between the two ends; the network layer never touches plaintext.
No third party in the data path. A2AL runs no relays, and data moves between the two ends; with a TURN server of your own, the relay forwards encrypted traffic only.
Replaceable identity. An AID carries no phone number, email address or legal name; generate a new one when you need a fresh identity, and the old records expire with their TTL, leaving no credential that links the two. See Publishing & Visibility.
Exposure you decide. Address, profile and capability are published at three separate levels that can be narrowed or withdrawn at any time.
Keys and data stay on your machine. A2AL holds no keys, acts for no one, and keeps none of your data.

What A2AL does not promise

It is not a censorship-resistant network. The network layer can see addressing data: the addresses you publish or query can be recorded by an operator, and so can the two addresses on either end of a connection; an address record includes your current IP and port.
It does not audit content. The network does not read message bodies or judge content on your behalf; whether to accept a given piece of content depends on how far you trust the sending AID, not on content scanning.
It does not hold identities for you. Keys and AIDs are yours, and A2AL cannot report them lost, freeze them or recover them.

Goal	Page
Day-to-day advice and self-checks	Security Practices
How far an AID is exposed, and who can find you	Publishing & Visibility
How connections are established and how they traverse NAT	Discover & Connect Agents
Restrict who may call your HTTP	Let Others Call You