neorelay/README.md

# NeoRelay Generic Source Kit

The release version is recorded in `VERSION`. Existing operators should follow
`UPGRADING.md` and deploy the full compatible component set rather than copying
individual changed files.

This archive contains sanitized application source templates for NeoBear,
NeoDrop, NeoGuard, and the encrypted NeoDrop manager. It is intentionally not a
turnkey infrastructure deployment and cannot run until every `{{PLACEHOLDER}}`
has been resolved.

The operator owns the deployment topology, domains, DNS records, TLS
certificates, reverse proxies, routing, firewalls, service supervision, users,
filesystem layout, and secret distribution. Nothing in this kit assumes how
those responsibilities are implemented.

## Security Boundary

The kit includes only reviewed application source and frontend customization
files. It deliberately excludes:

- live deployment and provisioning scripts;
- DNS mutation or authoritative-server configuration;
- certificate issuance and renewal automation;
- nginx configuration and TLS/key paths;
- SSH hosts, jump hosts, identities, and copy commands;
- private or public network diagrams, addresses, and routes;
- systemd units tied to a particular filesystem layout;
- operator identities, IRC accounts, domains, and personal branding images;
- keys, credentials, catalogs, databases, capability URLs, and Git history.

The NeoBear assets include OpenDyslexic WOFF2 web fonts and their `OFL.txt`
license. Keep the license with the font files in rendered distributions.

`MANIFEST.sha256` records the checksum of each regular file in the extracted archive.
The archive itself uses normalized root ownership and timestamps, so it does
not disclose the build workstation account.

## Placeholders

The published generic kit intentionally retains this exact documented
placeholder set. Resolve all placeholders consistently before running or
compiling anything. A rendered deployment artifact must contain no unresolved
placeholders.
Several occur in multiple protocol implementations and must have identical
values everywhere.

### Public Identity

- `{{RELAY_ORIGIN}}`: complete HTTPS origin for the web IRC client.
- `{{RELAY_HOST}}`: hostname only for the web IRC client.
- `{{DROPS_ORIGIN}}`: complete HTTPS origin for NeoDrop.
- `{{DROPS_HOST}}`: hostname only for NeoDrop.
- `{{DROPS_HOST_REGEX}}`: regex-escaped NeoDrop hostname.
- `{{RELAY_TITLE_HTML}}`, `{{DROPS_TITLE_HTML}}`: trusted static heading HTML.
- `{{RELAY_GATEWAY_LABEL}}`, `{{OPERATOR_LABEL}}`: plain display labels.
- `{{PRODUCT_NAME}}`: product/author label used by the frontend and plugins.
- `{{NODE_LABEL}}`, `{{DROP_NODE_LABEL}}`, `{{DROP_TAGLINE}}`: plain branding text.

### Trust And Networking

- `{{NEODROP_BIND_ADDRESS}}`, `{{NEOGUARD_BIND_ADDRESS}}`: component binds.
- `{{TRUSTED_PROXY_ADDRESS}}`: the only peer allowed to supply client IPs.
- `{{UPLOAD_CIDR_1}}`, `{{UPLOAD_CIDR_2}}`, `{{UPLOAD_CIDR_3}}`: upload source networks.
- `{{MANAGEMENT_CIDR_1}}`, `{{MANAGEMENT_CIDR_2}}`, `{{MANAGEMENT_CIDR_3}}`: manager networks.
- `{{NEOGUARD_INTERNAL_URL}}`: private NeoGuard attempt-report endpoint.
- `{{BLOCKED_REDIRECT_URL}}`: operator-selected blocked-client destination.

Use a deliberately non-routable CIDR for unused slots. Never broaden a trust
list merely to make a request succeed. Preserve the trusted-proxy check before
accepting forwarded client addresses.

### Storage And Credentials

- `{{NEODROP_DATA_ROOT}}`, `{{NEOGUARD_DATA_ROOT}}`: persistent state roots.
- `{{NEODROP_MANAGER_TOKEN_HASH_PATH}}`: manager-token hash location.
- `{{NEOGUARD_KEY_PATH}}`: shared NeoGuard key location.
- `{{CATALOG_KEY_PATH}}`, `{{MANAGER_API_TOKEN_PATH}}`: manager credentials.
- `{{MANAGER_CATALOG_PATH}}`, `{{MANAGER_DOWNLOAD_ROOT}}`: manager state.
- `{{MANAGER_CONTROL_SOCKET_PATH}}`, `{{MANAGER_HTTP_SOCKET_PATH}}`: manager sockets.
- `{{NEOGUARD_CONTROL_SOCKET_PATH}}`: NeoGuard agent socket.

### Protocol Compatibility

- `{{NEODROP_CRYPTO_CONTEXT}}`: immutable HKDF salt/context for one deployment.

Choose the crypto context once, record it in protected operator documentation,
and use the exact same byte string in all browser and manager components.
Changing it invalidates existing capability links.

## Branding Assets

Personal image files are not included. Before using
`scripts/customize-glowing-bear.pl`, provide reviewed JPEG and PNG assets at
the filenames expected by that script or adapt the customizer to your asset
pipeline. Strip image metadata before distribution.

## Integration Contracts

NeoDrop stores ciphertext and exposes its upload/object HTTP API. NeoGuard
receives abuse-attempt reports from trusted components. The manager holds
encrypted catalog state and deletion capabilities. NeoBear connects to a
WeeChat relay and uses the NeoDrop public origin for browser uploads.

The supplied Python, C, JavaScript, HTML, CSS, and Perl files are source
components, not proof that a particular deployment is secure. Review process
ownership, socket permissions, state backups, request-size limits, proxy
headers, origin checks, and network policy in the target environment.

## Adaptation Workflow

1. Read `AGENTS.md` before asking a coding agent to modify the kit.
2. Design the target topology and trust boundaries outside this source tree.
3. Resolve every placeholder from explicit operator decisions.
4. Supply neutral branding assets and deployment-specific integration files.
5. Run syntax, protocol, leakage, and archive-integrity checks.
6. Deploy to a staging environment and test encrypted upload/download/delete.
7. Publish only an artifact produced from the reviewed, rendered tree.

Useful pre-deployment checks include:

```sh
test -z "$(rg -l '\{\{[A-Z0-9_]+\}\}' files scripts)"
sha256sum -c MANIFEST.sha256
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
```

Recreate `MANIFEST.sha256` after rendering because placeholder resolution
necessarily changes file contents.