SHA256

Files

docs: split context into layered, agent-oriented files

Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.

Layers:
- architecture/  stable structural reference (overview, source-map,
                 test-map, data-flow)
- patterns/      memory, commands, autocomplete, events, xmpp,
                 encryption, ui, plugins
- testing/       unit-tests, stubs, functional-tests, bench
- build/         local, docker, ci
- playbooks/     add-command, add-test, add-autocomplete,
                 add-event-handler, add-encryption
- gotchas.md     append-only dated entries (seven seed entries)
- wip/           branch-specific notes; deleted on merge to master

Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.

INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.

2026-04-30 20:52:06 +03:00

2.5 KiB

Raw Permalink Blame History

Encryption

Three independent stacks, all optional at build time (./configure flags):

Module	Backend	XMPP bridge
`src/omemo/`	libsignal-protocol-c	`src/xmpp/omemo.c`
`src/otr/`	libotr v4	(in-stream, no separate xmpp bridge)
`src/pgp/`	gpgme	`src/xmpp/ox.c` (for OX/XEP-0373)

Module layouts

OMEMO (`src/omemo/`)

File	Role
`omemo.c/h`	Public surface: session setup, encrypt/decrypt, key publish/fetch.
`crypto.c/h`	AES-GCM payload encryption; libsignal-protocol crypto provider.
`store.c/h`	Persistent identity / pre-key / signed pre-key / session storage.

src/xmpp/omemo.c is the bridge — it talks to src/omemo/omemo.c and to libstrophe stanza building.

OTR (`src/otr/`)

File	Role
`otr.c/h`	Public surface: start/end/secure messaging, fingerprint mgmt.
`otrlib.h`	Compatibility shim across libotr versions.
`otrlibv4.c`	libotr v4-specific implementation.

OTR runs in-band on the message stream, no separate XMPP bridge file.

PGP / OX (`src/pgp/`)

File	Role
`gpg.c/h`	Classic PGP signing/encrypting via gpgme.
`ox.c/h`	XEP-0373 / XEP-0374 (OX): OpenPGP for XMPP.

src/xmpp/ox.c is the OX bridge; gpg.c is invoked directly from message handlers.

Conditional compilation

Each module is gated by HAVE_OMEMO, HAVE_LIBOTR, HAVE_LIBGPGME (set by configure.ac). Code that calls into a module guards with #ifdef HAVE_<X> and supplies a graceful fallback. When editing:

Search for the existing #ifdef use of the symbol you are touching to confirm the gating macro.
Stubs in tests/unittests/{omemo,otr,pgp}/stub_*.c exist regardless — they satisfy the test linker even when the feature is "off" at runtime.

Encryption-aware tests

tests/unittests/test_forced_encryption.{c,h} exercises the policy where sending plain text is refused if a session is OMEMO/OTR/PGP-locked. Touching encryption-policy code → check this test does not regress.

Adding or modifying calls into encryption

Locate the bridge: outgoing call → typically src/xmpp/omemo.c / src/xmpp/ox.c / src/otr/otr.c.
Confirm the #ifdef HAVE_* guard at the call site.
If the module's public surface (header) changes, update the corresponding stub in tests/unittests/{omemo,otr,pgp}/stub_*.c.
Run the relevant unit tests (test_forced_encryption, plus anything in test_cmd_otr.c, test_cmd_pgp.c).

See playbooks/add-encryption.md.

2.5 KiB Raw Permalink Blame History