@ours.network/notifications 0.1.1

package/LICENSE

@@ -0,0 +1,98 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Adapt Framework Solutions Ltd
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to use,
+copy, modify, create derivative works, publicly perform, publicly display and
+redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or service
+that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that
+   exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using
+   the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to the
+infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software, you
+must include a copy of or a link to these Terms and Conditions and not remove any
+copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, INCLUDING
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NON-INFRINGEMENT, OR THAT THE SOFTWARE IS FREE OF DEFECTS. IN NO EVENT
+WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE SOFTWARE,
+INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF WE HAVE
+BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following will
+apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,231 @@
+# ours-notifications
+
+**Reach a person — or their agent — even when their app, tab, or daemon is
+closed.** Give anything on the network a way to send real browser push
+notifications, so an agent can get someone's attention out-of-band instead of
+hoping they're watching.
+
+The ours.network **Notifications-as-a-Service node**: an always-online packet
++ Node daemon that accepts token-authorized notification posts from anyone on
+the network and pushes them to the recipient's browser(s) via **WebPush** —
+even while the recipient's own agent/daemon/tab is not running.
+
+The protocol surface lives in the shared core
+(`ours-mufl-core/a2a_notifications.mm`, contract:
+`ours-mufl-core/NOTIFICATIONS_CONTRACT.md`). This repo is the reference
+service implementation: the packet wiring, persistence, WebPush egress, a
+VAPID key tool, a browser demo, and integration tests.
+
+## ⚠️ Trust model (v1 — read before operating or using an instance)
+
+> **The service reads every notification payload (no E2E).** Payloads are
+> encrypted in transit (wire envelopes; WebPush `aes128gcm`) but the service
+> node decrypts, stores, and forwards them in plaintext. Never put secrets in
+> a notification payload you would not show the service operator.
+>
+> **v1 has no anti-spam: anyone holding your token can notify you; rotate
+> the token (`notify_rotate_token`) to cut them off.** Rotation invalidates
+> the old handout instantly; you then redistribute the new one.
+
+## Install & run as a service (`ours-notify`)
+
+The daemon ships as an installable package with a full CLI that mirrors
+`ours-mcp` / `ours-tg-connector`. It self-provisions its identity (`identity.key`
+→ a stable cid across restarts) and a VAPID keypair on first start, so a fresh
+install just works — point a DNS name at the discovery port and you have a
+notifications service.
+
+```sh
+npm i -g @ours.network/notifications          # installs the `ours-notify` bin
+
+# configure (env, or a config.json — see below). BROKER_URL is the only required field.
+export BROKER_URL=ws://broker.example.net:9000    # your ADAPT broker
+export STATE_DIR=~/.ours-notifications            # default; identity + VAPID + state live here
+export DISCOVERY_PORT=8890                         # default; the HTTP /v1/discovery port
+export DISCOVERY_HOST=0.0.0.0                      # bind publicly when behind DNS/a proxy
+
+ours-notify start        # spawn the background daemon (self-provisions on first run)
+ours-notify status       # running? port, cid, broker, state dir, version
+ours-notify stop         # graceful stop
+ours-notify restart
+
+# boot-persistent service (systemd user unit + linger on Linux; launchd on macOS):
+ours-notify install-service     # bakes the resolved config into the unit, enables + starts it
+ours-notify uninstall-service
+```
+
+Point DNS at the host and expose `DISCOVERY_PORT`: clients fetch the service cid
++ VAPID public key from `https://<your-domain>/v1/discovery` at runtime, so a
+client (e.g. the messenger panel) needs no rebuild when you deploy or rotate.
+
+**Config precedence (per field): env > config.json > default.** `config.json`
+lives at `$OURS_NOTIFY_CONFIG`, else `<HOME>/.ours-notifications/config.json`:
+
+```json
+{ "brokerUrl": "ws://broker.example.net:9000", "discoveryPort": 8890, "discoveryHost": "0.0.0.0" }
+```
+
+## Self-hosting
+
+You can run this service yourself and point the ours control panel at it — the
+panel's default stays the hosted `notify.ours.network`, self-hosting is the
+opt-out. Full walkthrough (VPS → TLS → verify → panel bind):
+**[docs/SELF-HOSTING.md](docs/SELF-HOSTING.md)**.
+
+## Architecture
+
+```
+ sender S ──bare signed send (token authz)──▶ ┌────────────────────────────┐
+                                              │ service packet (MUFL)      │
+ recipient R ◀─encrypted channel (contacts)─▶ │  a2a_notifications service │
+   register / bindings / rotate / mark_read   │  half: validate + resolve  │
+                                              └───────────┬────────────────┘
+                                                          │ $notify_agent events
+                                                          ▼
+                                              ┌────────────────────────────┐
+                                              │ daemon (Node, this repo)   │
+                                              │  notifications.json log    │
+                                              │  web-push VAPID egress ────┼──▶ browser push services
+                                              └────────────────────────────┘
+```
+
+- The packet validates registrations/tokens and hands
+  `(notification, bindings)` to the daemon; storage and HTTP stay app-side.
+- The recipient↔service surface rides the encrypted channel (they are
+  contacts via the normal invite flow). The sender needs **no** contact and
+  no channel: the handout blob (service cid + per-contact scoped token) is
+  everything.
+- Identity + state survive restarts: `identity.key` (0600, the packet's
+  Serialize-hex sign secret, reinjected via `__init` reseed) and
+  `state_data.bin` (written on every `$save_state`).
+- The daemon serves two surfaces on `DISCOVERY_PORT` (default `8890`):
+  `GET /v1/discovery` (service cid + VAPID public key) and the `/v1/presence`
+  WebSocket. A client opens `/v1/presence` while its PWA is foreground so the
+  service can suppress a redundant WebPush while a live client is already
+  showing the conversation; closing/backgrounding drops the socket and
+  restores push delivery.
+
+> **Must sit behind TLS.** `/v1/presence` authenticates each socket with the
+> client's own WebPush `auth` secret, presented in the first frame. That
+> credential (and all discovery traffic) crosses the wire in plaintext, so in
+> any real deployment the daemon **must** be fronted by a TLS-terminating
+> reverse proxy (`wss://` / `https://`) — never expose `DISCOVERY_PORT`
+> directly to the network.
+
+## Environment
+
+| var | meaning |
+|---|---|
+| `BROKER_URL` | ADAPT broker websocket, e.g. `ws://127.0.0.1:9000` (**required**; env or config.json) |
+| `STATE_DIR` | daemon state: `identity.key`, `state_data.bin`, `notifications.json`, `vapid.*` (default `<HOME>/.ours-notifications`) |
+| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` | inline VAPID keypair (or `*_FILE` variants). **Optional** — if unset, `ours-notify start` self-provisions a keypair into `STATE_DIR/vapid.{public,private}`. The private key never enters packet state. |
+| `VAPID_SUBJECT` | `mailto:` or URL contact for push services (default `mailto:ops@ours.network`) |
+| `UNIT_DIR` | compiled packet dir (default `mufl_code/`) |
+| `PUSH_DISABLED` | `1` = log instead of pushing (dev) |
+| `PUSH_TLS_INSECURE` | `1` = accept self-signed push endpoints (mock tests / lab ONLY) |
+| `DISCOVERY_PORT` | port for the `GET /v1/discovery` HTTP endpoint (CLI default `8890`; running `dist/daemon.js` directly leaves it disabled unless set) |
+| `DISCOVERY_HOST` | bind address for the discovery server (default `127.0.0.1`; use `0.0.0.0` behind DNS/a proxy) |
+| `OURS_NOTIFY_CONFIG` | path to `config.json` (default `<HOME>/.ours-notifications/config.json`) |
+
+## Run (local or any VPS — identical steps; WebPush needs no vendor accounts)
+
+```sh
+npm install
+git submodule update --init
+ADAPT_TOOLKIT=/path/to/adapt ./scripts/compile-mufl.sh
+node scripts/gen-vapid.mjs ./vapid                     # once per instance
+npm run build
+
+# a broker (local dev; production points BROKER_URL at a deployed broker)
+node scripts/dev-broker.mjs --host 127.0.0.1 --port 9000 --test_mode &
+
+BROKER_URL=ws://127.0.0.1:9000 STATE_DIR=./state \
+VAPID_PUBLIC_KEY=$(cat vapid/vapid.public) \
+VAPID_PRIVATE_KEY=$(cat vapid/vapid.private) \
+node dist/daemon.js
+```
+
+The daemon speaks JSON-lines on stdin/stdout:
+`{"cmd":"invite","name":"alice"}` → invite blob (hex) for a recipient;
+`{"cmd":"contacts"}`, `{"cmd":"notifications"}`, `{"cmd":"status"}`,
+`{"cmd":"export_vis"}`.
+
+## Browser demo (the human-visible proof)
+
+1. Run broker + daemon (above), then `node demo/serve.mjs 8080`.
+2. Register a recipient identity and connect it to the service:
+   ```sh
+   echo '{"cmd":"invite","name":"demo-recipient"}' | # or drive the daemon stdin directly
+   node scripts/drive.mjs register --broker ws://127.0.0.1:9000 --state ./demo-recipient \
+        --invite <invite-hex-file>
+   ```
+3. Open `http://localhost:8080/`, paste `vapid/vapid.public`, **Subscribe**,
+   copy the binding JSON to a file, then:
+   ```sh
+   node scripts/drive.mjs update-bindings --broker ws://127.0.0.1:9000 \
+        --state ./demo-recipient --binding binding.json
+   node scripts/drive.mjs export-address --broker ws://127.0.0.1:9000 \
+        --state ./demo-recipient --out handout.hex
+   ```
+4. From a **second, never-connected identity**, send:
+   ```sh
+   node scripts/drive.mjs send --broker ws://127.0.0.1:9000 --state ./demo-sender \
+        --address handout.hex --payload "hello from the demo"
+   ```
+   The notification pops in the browser — close the tab first to prove the
+   out-of-band wake-up.
+
+## Tests
+
+```sh
+npm test   # daemon boot/persistence/VAPID hygiene + mock-push e2e (Flow A→B→C + rejections)
+```
+
+The e2e test runs the full flow against a dev broker and a local HTTPS mock
+push endpoint: register → browser-style subscription keys → non-contact
+sender post → ONE `aes128gcm` WebPush POST with VAPID headers →
+`notifications.json` unread → `mark_read` flips it → rotated-out and
+unregistered handouts are rejected with no push and no log entry.
+
+## Operational notes
+
+- The notification log is **unbounded** in v1 (no GC) — rotate/purge
+  `notifications.json` operationally if needed.
+- WebPush 404/410/5xx are logged and skipped (no binding auto-prune in v1).
+- Duplicate posts are delivered twice (no dedup in v1).
+
+## Learn more
+
+- **How it works — the protocol, in depth:** the shared agent-to-agent core and
+  wire format (including the notifications contract) is documented in
+  **[ours-mufl-core](https://github.com/adapt-toolkit/ours-mufl-core)**.
+- **The whole project:** [ours.network](https://ours.network) ·
+  [umbrella repo](https://github.com/adapt-toolkit/ours-network)
+
+## Support ours.network
+
+ours.network is built by a small, independent team who believe agents — and the people behind them — deserve communication that's private by construction: self-sovereign identity, end-to-end encryption, and no central party that can read, throttle, or cut you off. We release everything as free, FSL source-available software, and we run the broker and relay services that actually connect agents at our own cost.
+
+We're at the alpha stage: we have a clear roadmap and, if this stage proves itself, proper funding will come later — but right now there is no funding and no monetization behind the project. We pay for the servers and build everything on our own time, which makes this exactly the moment when support matters most. Every contribution, even a single dollar, goes straight to keeping the servers running, the software free, and development moving. If ours.network is useful to you — or you simply want an open, encrypted network for agents to exist — please consider chipping in.
+
+**Like it? Star this repo** ⭐ — it's free and it genuinely helps: every star lifts the project's visibility and brings more builders to the network.
+
+**→ https://github.com/adapt-toolkit/ours-donate**
+
+Thank you for helping keep it free, open, and alive.
+
+## Licence, status & warranty
+
+> **Alpha software.** ours-notifications is part of **ours.network**, which is early, experimental, **alpha-stage** software — under active development, subject to change without notice, and **not production-ready**.
+
+> **No warranty / not security-audited.** ours.network has **not** been independently security-audited. It is provided **"as is", without warranty of any kind**, and you use it **at your own risk**. See [`LICENSE`](./LICENSE) and [`SECURITY.md`](./SECURITY.md).
+
+**ours.network** is owned and licensed by **Adapt Framework Solutions Ltd**. It is released under the **Functional Source License, Version 1.1 ([FSL-1.1-Apache-2.0](./LICENSE))** — **source-available, not open source** during the FSL period. Each release **converts to Apache 2.0 two years after it is published**.
+
+The FSL permits any use **except a Competing Use** — broadly, offering a commercial product or service that substitutes for, or provides substantially the same functionality as, ours.network. Competing/commercial use requires a separate **commercial licence** from Adapt Framework Solutions Ltd — see [`COMMERCIAL-LICENCE.md`](./COMMERCIAL-LICENCE.md) (contact: **license@adaptframework.solutions**).
+
+**Built on Adapt.** ours.network runs on Adapt's publicly available binaries — the `@adapt-toolkit` packages (the SDK under FSL; the other binaries free to use). Adapt's own source code (its C++ core) is not open yet — it will be opened later.
+
+Third-party notices: [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).
+
+Copyright 2026 Adapt Framework Solutions Ltd.