Sanitized public release v1.0.3

Source-Tag: v1.0.3
Manifest-SHA256: b7b09bf48f9e092ed8ad82f99c0319d6c3837d0a1549bd0cc4a374276c0f3896

UPGRADING.md

@@ -0,0 +1,84 @@
+# Upgrading NeoRelay
+
+This source kit is a complete, versioned application source set for upgrading
+an existing NeoRelay deployment. It is not a deployment-specific patch and it
+does not contain infrastructure configuration, credentials, or persistent
+state.
+
+## Compatibility
+
+- Upgrade NeoBear, NeoDrop, NeoGuard, and the NeoDrop manager as one tested set.
+- Preserve the existing `{{NEODROP_CRYPTO_CONTEXT}}` value exactly. Changing it
+  makes existing encrypted links unreadable.
+- Preserve the existing NeoDrop protocol framing and all operator trust
+  decisions, including origins, proxy peers, source networks, and state paths.
+- `scripts/customize-glowing-bear.pl` targets Glowing Bear revision
+  `d182657a3b882cfb54e294f9a56fbdd2954d73b0`. Test any other revision before
+  deployment.
+- Do not replace operator-managed WeeChat, IRC, proxy, service, DNS, TLS, or
+  firewall configuration with values inferred from this kit.
+
+## 1. Verify And Inventory
+
+1. Verify the archive checksum through a trusted channel.
+2. Run `sha256sum -c MANIFEST.sha256` from the extracted kit.
+3. Record the currently deployed version and hashes of its rendered runtime
+   files and integration configuration.
+4. Inventory every `{{PLACEHOLDER}}` and map it to the existing deployment's
+   protected source of truth. Do not select new values during an application
+   update unless the operator has approved a separate configuration change.
+
+## 2. Back Up
+
+Create and test a protected, application-consistent backup of:
+
+- NeoDrop's database and ciphertext object tree as one coordinated snapshot;
+- the encrypted manager catalog, catalog key, API token material, and verifier;
+- the NeoGuard database and shared authentication key;
+- WeeChat configuration, secure data, certificates, and plugin state;
+- the current rendered application files and operator integration files.
+
+Stop writers or use storage-specific atomic snapshot procedures. Preserve file
+ownership and modes. Confirm that the backup can be restored before upgrading.
+
+## 3. Render A Staging Tree
+
+1. Extract the kit into a new temporary directory, not over the live tree.
+2. Resolve placeholders from the existing protected configuration with
+   context-appropriate validation and escaping.
+3. Supply reviewed branding assets and operator-owned integration files.
+4. Recreate `MANIFEST.sha256` after rendering.
+5. Confirm the rendered tree contains no unresolved placeholders, credentials,
+   private keys, capability URLs, state, logs, or backups.
+
+The generic source kit intentionally contains documented placeholders. A
+rendered deployment artifact must not contain any unresolved placeholders.
+
+## 4. Test
+
+Run the checks listed in `README.md`, compile native plugins against the target
+WeeChat headers, and validate the operator's proxy and service configuration.
+In staging, verify:
+
+- an existing encrypted link still downloads and authenticates correctly;
+- a new upload, metadata read, download, checksum, expiry, and deletion;
+- manager catalog registration and access to existing entries;
+- NeoGuard authenticated reporting and recovery;
+- origin, source-address, and trusted-proxy enforcement;
+- startup from a restored copy of existing persistent state.
+
+## 5. Deploy
+
+Install the rendered files into a versioned directory or otherwise retain the
+complete previous runtime tree. Deploy the compatible browser, server, manager,
+and guard components as one release. Run health checks before restoring normal
+traffic or writes, then record the deployed version and rendered manifest.
+
+## 6. Roll Back
+
+If validation fails, isolate the new version and restore the previous runtime
+files and integration configuration. Preserve the original crypto context and
+credentials. Restore persistent state only if the upgrade performed
+incompatible writes; restore NeoDrop metadata and ciphertext together. Verify
+an existing encrypted link, manager catalog access, and component health after
+rollback.