neorelay/AGENTS.md

AGENTS.md

Scope

This source kit contains application components and frontend customization templates. The operator owns domains, DNS, TLS, routing, hosts, firewalls, service supervision, filesystem layout, users, credentials, and deployment tooling.

Do not turn this kit into a copy of an example or inferred architecture. Ask the operator for every missing trust, origin, address, path, and lifecycle decision.

Non-Negotiable Invariants

• Never infer or reuse example domains, addresses, accounts, paths, or topology.
• Never add DNS mutation, certificate issuance, SSH fan-out, or static routing without explicit operator instructions.
• Never disable TLS verification or SSH host-key verification.
• Never trust forwarded client-address headers from an unverified proxy peer.
• Never broaden upload, management, or trusted-proxy networks implicitly.
• Never package credentials, keys, certificates, capability URLs, catalogs, databases, logs, local configuration, or personal images.
• Keep the generic source kit's documented placeholders intact; never publish a rendered deployment artifact containing unresolved placeholders.
• Treat {{NEODROP_CRYPTO_CONTEXT}} as immutable after the first uploaded drop.
• Keep the same crypto context and protocol framing in every NeoDrop client and manager implementation.

Source Of Truth

Resolve the placeholders in source templates or generate deployment-specific configuration from a separately protected operator configuration. Do not edit rendered deployment files as the only source of truth.

When introducing generated files, include a generated-file header and a digest of the non-secret configuration that produced them. Keep secret values out of that digest and out of repository history.

Render values with context-appropriate validation and escaping. HTML text, HTML fragments, regular expressions, JavaScript, Python, C strings, CSS, and Perl substitutions are different contexts; a value safe in one may be unsafe in another.

Deployment Adaptation

Before writing deployment automation, obtain explicit operator decisions for:

• public relay and drop origins;
• product, operator, node, and drop display labels;
• component placement and bind addresses;
• reverse-proxy peers and forwarded-header behavior;
• upload and management source CIDRs;
• state, socket, credential, and backup paths;
• process identities and file ownership;
• TLS termination and certificate lifecycle;
• DNS publication and update lifecycle;
• firewall rules, health checks, monitoring, rollback, and recovery;
• IRC server, account, certificate authentication, and channel policy.

Treat nginx, systemd, containers, orchestration, and configuration-management systems as operator choices. Add only the integration files needed for the confirmed target environment.

Component Contracts

NeoBear requires a WeeChat relay endpoint and a NeoDrop public origin. NeoDrop requires persistent ciphertext storage, a trusted proxy definition, explicit upload/management networks, and the shared crypto context. NeoGuard requires a protected shared key and authenticated internal reporting path. The manager requires protected catalog/token credentials, private state, restricted Unix sockets, and access to the NeoDrop object API.

Preserve origin validation, source-IP validation, authenticated encryption, metadata authentication, capability secrecy, request-size limits, and socket permission checks when adapting components.

Required Workflow

1. Inventory all unresolved {{PLACEHOLDER}} values.
2. Ask for missing operator decisions instead of selecting convenient defaults.
3. Render into a temporary directory, never over the pristine source kit.
4. Run syntax and protocol tests for every changed language/component.
5. Scan all paths, file bytes, and archive metadata for private information.
6. Verify no secret-like file types or key headers are present.
7. Verify archive ownership, modes, timestamps, member types, and checksums.
8. Test encrypted upload, authenticated metadata, download, checksum, expiry, catalog registration, and deletion in staging.
9. Review the final manifest before publication.

Release Checks

After rendering an operator tree, at minimum run:

test -z "$(rg -l '\{\{[A-Z0-9_]+\}\}' files scripts)"
python3 -m py_compile files/neodrop/*.py files/neodrop-manager/*.py files/neoguard/*.py
node --check files/neodrop/app.js
node --check files/glowing-bear/neodrop-crypto.js
perl -c scripts/customize-glowing-bear.pl

Also run the repository's NeoDrop protocol tests when working from the full source repository. A deployment-specific release process must add leakage, reproducibility, integration, and archive-metadata tests appropriate to its toolchain.

Do not add a file to a release allowlist merely to make a test pass. Every file must have a documented source-distribution or runtime purpose.