@ours.network/notifications 0.1.1 → 0.3.1-nightly.1

package/README.md

@@ -1,231 +1,128 @@
-# 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" }
-```
+# Ours Notifications
 
-## Self-hosting
+Dedicated web-push delivery and a persistent notification inbox. Fleet and
+Messenger submit events with producer credentials. Browsers register devices
+and share unread/read state through their authenticated Fleet gateway. Native
+Android/iOS transports are outside this package.
 
-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)**.
+## Run
 
-## Architecture
+Requires Node 22 or later. Build with `npm ci && npm run build`, then run
+`node dist/cli.js /absolute/path/private-config.json`. The config must have mode
+0600. The state directory must be private and backed up together with the VAPID
+keys. Generate keys once with `web-push.generateVAPIDKeys()`; rotating them
+requires each browser to subscribe again.
 
+```json
+{
+  "host": "127.0.0.1",
+  "port": 49677,
+  "stateFile": "/private/notifications/state.json",
+  "users": [{ "userId": "stable-owner-account", "token": "REPLACE_WITH_RANDOM_USER_TOKEN_AT_LEAST_32_CHARS" }],
+  "producers": [
+    { "userId": "stable-owner-account", "source": "fleet", "token": "REPLACE_WITH_RANDOM_FLEET_TOKEN_AT_LEAST_32_CHARS" },
+    { "userId": "stable-owner-account", "source": "messenger", "token": "REPLACE_WITH_RANDOM_MESSENGER_TOKEN_AT_LEAST_32_CHARS" }
+  ],
+  "vapid": { "subject": "mailto:operator@example.com", "publicKey": "GENERATED_PUBLIC_KEY", "privateKey": "GENERATED_PRIVATE_KEY" }
+}
 ```
- 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.
+Each credential fixes its user principal; each producer also fixes its source.
+User IDs and sources in producer request bodies are rejected. Keep separate
+producer and user credentials, never deliver any credential to browser code.
+Fleet's password console currently represents one owner account: all trusted
+browser sessions use the same configured stable user token. Separate user
+accounts require separate trusted gateway/account mappings; arbitrary browser
+cookies or claimed IDs cannot create one.
+
+Configure Fleet's generic prefix gateway with `/notifications`, service origin,
+`headers: { "authorization": "Bearer USER_TOKEN" }`, and
+`stripBrowserContext: true`. Fleet checks the browser session, exact origin and
+mutation CSRF before stripping cookies/browser headers and injecting its user
+credential. This user token cannot call the producer API. Expose only the
+gateway publicly; the notification listener rejects direct browser context.
+
+## API
+
+All operations require a credential in `Authorization: Bearer TOKEN`. JSON
+mutations require `Content-Type: application/json`, with a 16 KiB body limit.
+Responses are never cached. User and producer credentials have separate scopes.
+
+| Method/path | Credential | Request/result |
+| --- | --- | --- |
+| GET `/api/v1/push/config` | User | Public VAPID key |
+| POST `/api/v1/devices` | User | `{ "subscription": PushSubscriptionJSON }` → device `id` |
+| POST `/api/v1/devices/delete` | User | `{ "id": "device-id" }`, only that user's device |
+| GET `/api/v1/devices/status?id=...` | User | `{ "active": true }` |
+| GET `/api/v1/inbox?limit=50&before=...` | User | Items, shared unread count, revision, next cursor |
+| GET `/api/v1/summary` | User | Shared unread count, revision, and per-chat source/identity/count |
+| POST `/api/v1/read-target` | User | `{ "url": "/fleet/chats?chat=agent", "revision": OBSERVED_REVISION }`, reads only this chat up to the revision captured before its history load |
+| POST `/api/v1/read` | User | `{ "ids": ["notification-id"] }`, idempotent shared read |
+| POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "url": "/fleet/chats?chat=agent&detail=1" }` |
+
+Inbox admission and queued delivery are one fsynced atomic snapshot. The service
+deduplicates by user/source/event ID; replay must retain identical title/body/URL
+or it receives 409. Inbox entries survive failed pushes and service restart.
+Reading stops remaining queued deliveries. Device endpoints cannot transfer
+between users, and only supported HTTPS push-provider hosts and valid P-256
+subscription keys are accepted. Navigation stays within `/fleet`.
+
+The service holds an exclusive state-file lock. Run one writer per state file.
+After a crash, inspect the lock PID and prove no service is using this state
+before manually removing its `.lock`; no automatic stale-lock deletion occurs.
+Malformed state fails closed. Restore a known backup rather than resetting it.
+Provider 404/410 removes the expired binding; other failures retry with capped
+exponential backoff (eight attempts). The inbox remains after delivery exhaustion.
+Limits are 32 devices/user, 10,000 inbox entries/user, 20,000 queued deliveries,
+180 user API requests/minute and 600 producer requests/minute. Capacity failure
+returns 503 so durable producers can retain/retry events. This first version
+requires operator archival/reset after inbox capacity is reached.
+
+## Producers and PWA
+
+Fleet web and Messenger use `OURS_NOTIFICATIONS_ORIGIN` and their distinct
+`OURS_NOTIFICATIONS_PRODUCER_TOKEN`. Fleet web observes durable supervisor
+ledgers incrementally without restarting agents or attaching a controller.
+Owner browser/channel prompt completions notify; monitor/startup turns do not.
+Existing history is skipped at first install. Persist Fleet web state to retain
+offsets and pending prompt correlation. Messenger uses its canonical incoming
+message/file watcher and persists payloads before sending. Both outboxes retry
+without requiring a locally registered push binding.
+
+In ours-app, open Settings → Notifications → Enable notifications. Permission
+is requested from that click. The service worker subscribes this device, repairs
+its registration on login/focus when enabled, and opens in-app targets. Disable
+or sign out revokes this device only. The Notifications launcher opens the
+backend inbox; marking a record read synchronizes with other sessions on their
+next visible refresh (five seconds). Inbox polling is paginated and does not
+load chat transcripts.
+
+On iPhone/iPad, install the HTTPS app on the Home Screen and open the installed
+app before enabling push; WebKit documents this requirement and the explicit
+interaction for permission in its [Web Push announcement](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/).
+Automated browser permission/subscription fixtures cannot establish physical
+phone push delivery; test a real installed device separately.
+
+## Release channels
+
+Repository history is preserved. The legacy MUFL implementation is replaced by
+this service, with community/legal files from `ours-shared`. Version 0.2.0 marks
+the new service API; the previous package API is incompatible.
+
+CI gates typecheck, build, tests and pack on PRs to `main`/`prerelease`. Only a
+push to `main` may bump a stable version using conventional commit subjects and
+publish `latest`. Only a push to `prerelease` may calculate an ephemeral
+patch-base `-nightly.N` version and publish `nightly`; the nightly version is
+never committed. Guard scripts refuse branch/version/tag mismatches. Publication
+needs the same NPM/version-bump app secrets as sibling repositories. Opening a
+feature PR performs no publication or merge. Run `npm test` for local gates.
+
+Foreground presence uses the authenticated gateway WebSocket at
+`/api/v1/presence`. Its first frame is `{type:"hello",id,endpoint,auth}`;
+`id` must be an active device owned by the credential's user, with matching
+subscription endpoint and auth key. Visible clients send `{type:"heartbeat"}`
+every 15 seconds. Transport ping/pong and a 45-second application freshness
+limit remove frozen/disconnected clients. Only that foreground device's push
+is suppressed; its inbox item remains unread until explicitly marked read.
+Other devices still receive push. `inbox.changed` invalidates account-wide inbox
+views after producer admission or reads. Presence is ephemeral across restart.

package/dist/chat-target.d.ts

@@ -0,0 +1,9 @@
+/** Stable conversation identity, independent of list filters and mobile detail state. */
+export declare function chatTarget(path: string): {
+    source: 'work' | 'messenger';
+    chat: string;
+} | null;
+export declare function chatKey(value: {
+    source: string;
+    chat: string;
+}): string;

package/dist/chat-target.js

@@ -0,0 +1,12 @@
+/** Stable conversation identity, independent of list filters and mobile detail state. */
+export function chatTarget(path) {
+    const url = new URL(path, 'https://ours.invalid');
+    if (url.pathname === '/fleet/chats') {
+        const chat = url.searchParams.get('chat');
+        if (!chat || chat.length > 512)
+            return null;
+        return { source: url.searchParams.get('source') === 'messenger' ? 'messenger' : 'work', chat };
+    }
+    return null;
+}
+export function chatKey(value) { return JSON.stringify([value.source, value.chat]); }

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};