Sanitized public release v1.0.3

Source-Tag: v1.0.3 Manifest-SHA256: b7b09bf48f9e092ed8ad82f99c0319d6c3837d0a1549bd0cc4a374276c0f3896
2026-07-20 22:35:36 +00:00
commit 7141326ea0
41 changed files with 6397 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 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:
+
+```sh
+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.