1. What pairing is

Pairing identifies a channel+sender, not a physical person. The same family member writing to Metnos via Telegram and via Signal are two distinct, independent pairings, each with its own autonomy level. This naturally enables pairing the same person at different levels depending on the channel (Telegram = Full because the phone is always with them; mail = ReadOnly because it might have been read by someone else).

Architecture ch. 12 treats pairing as a branch of the «identity and perimeter» node: Metnos does not know who you are in any registry sense, it only knows that the pair (channel, sender_id) was associated, once, with an autonomy level, and works on that.

Three autonomy levels, one single dimension (see Architecture chapter 4 for the rationale):

• ReadOnly — the sender can write, Metnos acknowledges but does not execute. Designed for occasional family members or sensitive channels.
• Supervised — the sender gets a complete turn, but actions with external side effects fall under control (reserved for v1.2+; today it behaves like Full as far as run_turn is concerned, but the level is already persisted).
• Full — the sender has full authority: Metnos executes the turn and replies.

2. Types and constants

The whole module lives in /opt/myclaw/runtime/pairing.py (354 lines). The two public types are a dataclass and an exception:

@dataclass
class Pairing:
    channel: str
    sender_id: str
    autonomy_level: str
    paired_at: str
    paired_by: str
    last_seen: str | None = None
    revoked_at: str | None = None


class PairingError(Exception):
    pass

Pairing is what queries return and what the caller inspects. PairingError wraps every error in the module (code format, signature, expiry, double consume) so that the caller can handle them with a single except. See pairing.py:64-76.

Relevant constants, in pairing.py:36-40:

3. Code format

The code is a printable string, copyable by hand if needed. The shape:

PAIR.<base64url(payload_json)>.<base64url(signature)>

The payload is a deterministic JSON (sorted keys, separators with no spaces) with five fields:

{
  "v": 1,
  "id": "<uuid12>",
  "autonomy": "<ReadOnly|Supervised|Full>",
  "exp": <unix epoch in seconds>,
  "iss": "author"
}

The signature is Ed25519 over the bytes of the serialised JSON, produced with the author key in ~/.config/metnos/keys/ (see sign.py:28-29, 58-60). Verification scans every trusted public key in that same directory (list_trusted_publics in sign.py:66-76) and accepts the code if at least one verification passes. This way an older Metnos remains able to accept codes signed by a new key as long as the new public is added to the directory.

Example of a real code (TTL 5 minutes, ReadOnly level):

PAIR.eyJhdXRvbm9teSI6IlJlYWRPbmx5IiwiZXhwIjoxNzA5OTk4ODg4LCJpZCI6IjA0YzNhYThiYjFiNCIsImlzcyI6ImF1dGhvciIsInYiOjF9.5xV3M7T...kWQ

Typical length: ~180 characters. You can copy-paste it, send it via iMessage, or read out the last eight syllables aloud.

4. SQLite schema

Two tables, defined in pairing.py:43-61:

CREATE TABLE IF NOT EXISTS pairings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    channel TEXT NOT NULL,
    sender_id TEXT NOT NULL,
    autonomy_level TEXT NOT NULL,
    paired_at TEXT NOT NULL,
    paired_by TEXT NOT NULL,
    last_seen TEXT,
    revoked_at TEXT,
    UNIQUE(channel, sender_id)
);
CREATE TABLE IF NOT EXISTS consumed_codes (
    code_id TEXT PRIMARY KEY,
    consumed_at TEXT NOT NULL,
    channel TEXT NOT NULL,
    sender_id TEXT NOT NULL
);

The default file lives in ~/.local/state/metnos/pairings.db; the directory is created on first access (pairing.py:94-100). For tests we set METNOS_PAIRINGS_DB to a temporary path, getting an isolated database per test case.

5. Python API

Every function accepts an optional keyword-only db_path, so the caller can point at a different registry (useful for tests and for hypothetical registry-per-tenant scenarios). Without db_path, METNOS_PAIRINGS_DB is used, or the default.

6. CLI

The module is directly executable. Commands (pairing.py:317-350):

python3 -m pairing generate <ReadOnly|Supervised|Full> [ttl=5m]
python3 -m pairing consume <code> <channel> <sender_id>
python3 -m pairing list [--include-revoked]
python3 -m pairing revoke <channel> <sender_id>

TTL accepts three suffixes (pairing.py:306-314): 60s, 5m, 1h. Without a suffix, the value is interpreted as seconds.

# 1. Roberto generates a 10-minute ReadOnly code
$ python3 -m pairing generate ReadOnly 10m
PAIR.eyJhdXRvbm9teSI6IlJlYWRPbmx5IiwiZXhwIjox...

# 2. he passes it via iMessage to the family member

# 3. the family member writes on Telegram:  /pair PAIR.eyJ...
# the daemon consumes it and replies "Paired as ReadOnly. Welcome."

# 4. Roberto verifies
$ python3 -m pairing list
{"channel": "telegram", "sender_id": "12345678", "autonomy_level": "ReadOnly", ...}
{"channel": "telegram", "sender_id": "99887766", "autonomy_level": "Full", ...}

# 5. one week later, revoke
$ python3 -m pairing revoke telegram 12345678
revoked

7. Integration with the Telegram daemon

The daemon lives in /opt/myclaw/runtime/channels/daemon.py. The handle_message function (daemon.py:121-165) is where pairing and runtime meet. The decision sequence:

1. If the message text starts with /pair (see the PAIR_COMMAND constant in daemon.py:36), the daemon goes into _handle_pair_command (daemon.py:108-119): consumes the code, replies "Paired as <level>. Welcome." on success, "Pairing failed: <reason>" otherwise. No runtime turn starts here, even if pairing succeeded: the user must send a second message to activate Metnos.
2. Otherwise, pairing.get_pairing(channel.name, sender_id) is consulted. If it returns None, the daemon attempts the bootstrap (see below). If the bootstrap also fails, it replies with UNPAIRED_REPLY (daemon.py:37-40) and ends the turn.
3. If the pairing exists, touch_last_seen is called for audit.
4. If the level is in LEVEL_BLOCKS_RUN = {"ReadOnly"} (daemon.py:41): polite reply (LEVEL_REPLY_BLOCKED, daemon.py:42-45), no run_turn.
5. Otherwise, run_turn(msg.text) is called, the result is formatted, and the reply is sent on the channel.

Default-chat bootstrap

The _try_bootstrap function (daemon.py:93-106) handles the case «Roberto installs Metnos on his new phone and writes to himself»: with no prior pairing, the first message from default_chat_id (read from credentials.env via the TelegramChannel) is auto-paired as Full. Three conditions must all be true:

1. the daemon's bootstrap_default_sender flag is True (default; disabled with --no-bootstrap);
2. the message's sender_id matches the default_chat_id declared by the channel;
3. no pairing exists on that channel (bootstrap_default_chat_id refuses otherwise, see pairing.py:283-287).

This way the bootstrap is safe: once a single pairing exists on the channel, further calls fail and the bootstrap loses its effect. Even Roberto, after pairing himself the first time, can no longer use the bootstrap to pair anybody else: family members must receive an explicit code.

Errors in run_turn

If run_turn raises, the daemon does not die: it catches the exception, logs the stack trace, replies to the sender with the message "(internal error: <type>: <text>)" and continues the loop with the next message (daemon.py:153-155). The pairing is not touched: the same user on the next message is still paired, still authorised to request more turns.

8. Security

Five guarantees, each existing for a concrete threat:

Deliberately missing: rate-limit on failed /pair attempts (an attacker could spam made-up codes hoping for collisions, but with the Ed25519 signature space success is cosmologically improbable and every attempt leaves a log). See limits.

9. Tests

Cluster pairing: 9 cases, all green. They cover the nominal flows and the explicit breaks of the model.

channels module (daemon): 9/9 with a sub-cluster of 5 cases that explicitly exercises the pairing flow between daemon and module:

• D1: default bootstrap + run_turn on the next message, Full level obtained automatically;
• D2: unpaired sender (and not the default) receives UNPAIRED_REPLY, no run_turn;
• D3: /pair <valid code> → reply "Paired as <level>. Welcome.", pairing written in DB, no run_turn;
• D4: /pair <expired/tampered code> → reply "Pairing failed: <cause>", no pairing written;
• D5: sender paired as ReadOnly receives the polite reply, no run_turn; last_seen is not touched (the update only fires after the level check).

All tests run in isolation with their own METNOS_PAIRINGS_DB in /tmp, and with an ad-hoc test keypair, so neither the registry nor the author's development keys are touched.

10. v1.1 limits

Five declared limits, some by deliberate design, others deferred to v1.2+:

Closing notes

The module is deliberately small (354 lines in a single file, one external dependency beyond the standard library: cryptography via sign.py). There is no interchangeable «store» abstraction layer, there is no formal protocol for the code other than JSON+base64+signature. The choices are guided by the simplicity principle (see memory feedback_simplicity_first): complexity is added when the problem demands it, not before.

Pairing is the first piece of the «perimeter» node that becomes executable: anything that relies on identifying the sender (rate-limit per level, scope of executors permitted per level, audit of who started what) rests on this primitive.