@ours.network/notifications 0.3.1-nightly.4 → 0.3.1-nightly.6

package/README.md

@@ -56,20 +56,20 @@ Responses are never cached. User and producer credentials have separate scopes.
 | 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, per-chat source/identity/count, and `sections: {chats, tasks}` |
-| POST `/api/v1/read-target` | User | `{ "url": "/fleet/chats/agents/agent", "revision": OBSERVED_REVISION }`, reads only this chat up to the revision captured before its history load |
+| POST `/api/v1/read-target` | User | `{ "target": { "kind": "agent", "agentId": "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/delete` | User | `{ "ids": ["notification-id"] }` → `{ "removed": COUNT }`; persistently removes only this user’s entries and queued deliveries after the client has confirmed target absence |
-| POST `/api/v1/delete-target` | Producer | `{ "url": "/fleet/chats/agents/agent" }` → `{ "removed": COUNT }`; only its credential’s user/source and exact canonical conversation, including filter/anchor variants |
-| POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "url": "/fleet/chats/agents/agent" }` |
+| POST `/api/v1/delete-target` | Producer | `{ "target": { "kind": "agent", "agentId": "agent" } }` → `{ "removed": COUNT }`; only its credential’s user/source and exact canonical conversation, ignoring message anchors |
+| POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "target": { "kind": "agent", "agentId": "agent" } }` |
 
 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
+deduplicates by user/source/event ID; replay must retain identical title/body, typed target/anchor and task association
 or it receives 409. Inbox entries survive failed pushes and service restart.
 Producer send payloads may include `taskId`: a stable task ID for an associated
 ACP agent, or `null` for an explicitly standalone agent. Omission remains supported.
 The association is persisted and cannot change when replaying the same event ID.
-Summary section counts are independent of browser inventories: task-page URLs,
-encoded work task rooms and explicit task associations count under Tasks. An explicit
+Summary section counts are independent of browser inventories: task/task-deleted targets,
+room targets and explicit task associations count under Tasks. An explicit
 task association takes precedence over the source. Messenger destinations, including
 room CIDs that open in Messenger, and explicit standalone agents count under Chats.
 Legacy ACP notifications without association
@@ -79,7 +79,7 @@ counts with the same durable revision as the total.
 
 Reading stops remaining queued deliveries. Deleting confirmed stale inbox records updates the shared revision, unread summary and presence subscribers atomically. Generic loading, permission or network failures do not establish target absence; callers must validate absence through the owning service. 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`.
+subscription keys are accepted. Only typed domain targets are accepted; browser address construction belongs to the App.
 
 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
@@ -172,4 +172,12 @@ admitted as receipts on load. The existing inbox/job caps remain; a separate cap
 100,000 receipts per account rejects new events explicitly rather than evicting
 dedupe evidence. Upgrades must preserve the service's state file and scoped credentials.
 
-Conversation notification links use canonical contact (`/fleet/chats/contacts/:id`), agent (`/fleet/chats/agents/:id`), and task room (`/fleet/tasks/:taskId/room` or `/fleet/tasks/:taskId/rooms/:key`) paths. Deploy producers, this service, and the app together. Summary rows retain `source`/`chat` and include `kind` (`contact`, `agent`, or `room`) to distinguish colliding IDs. Filters and message anchors do not change target identity. Old query-based conversation URLs are intentionally unsupported; stored payload URLs are neither converted nor deleted by this change. Existing navigation-target security restrictions still apply.
+Notifications carry domain identifiers, never frontend URLs. `target` is one of `{kind:"contact",contactId}`, `{kind:"agent",agentId}`, `{kind:"room",taskId,roomKey?}`, `{kind:"task",taskId}` or `{kind:"task-deleted",taskId}`. Omit `roomKey` for the keyless room. Optional `anchor` is `{kind:"messenger-message",wireId}` for contact/room targets or `{kind:"fleet-message",messageId}` for agents. IDs are raw strings, not URI-encoded by producers. Contact IDs are at most 512 characters, exclude controls, slashes/backslashes and dot segments; agent/task IDs are 1–120 ASCII letters/digits/underscores/hyphens. Room keys start with an ASCII letter, continue with letters/digits/underscores/hyphens up to 120 characters and exclude constructor/prototype/__proto__. Message IDs are nonempty opaque strings up to 1024 characters without controls. Object fields are closed; URL fields and mismatched anchors are rejected. Existing optional `taskId` task association remains and must agree with room/task targets when supplied.
+
+Deploy producers, service, and App/worker together. Summary `chats` contains `{target,count}` conversation rows; anchors do not affect identity, 64-hex contact CIDs compare case-insensitively, and agent/task/room identities remain distinct. The App supplies its trusted workspace binding and encodes browser addresses. Send/read-target/delete-target accept only the typed contract; no old URL decoding or conversion is provided.
+
+The state file records its format version. This release reads only its own version 2 state: a state file from an earlier release, or one with any record outside the typed contract, is refused at startup and left unchanged. A missing state file starts empty.
+
+## Full-resource qualification
+
+The matching App integration fixture exercises actual producer commits through the authenticated Fleet gateway into Chromium, including remote read/deletion and a retained two-page inbox. Healthy delivery applies canonical payloads without content GETs after events; explicit and attended read/read-target/read-all POST conditions remain unchanged. Neutral observation does not enter foreground presence. Set `RESOURCE_QUALIFY_IDLE_MS=60000` for a sixty-second idle qualification. Backend service tests cover bounded chunks/output, per-user/epoch ownership and slow consumers; they do not establish every hosted deployment. Existing provider retry scheduling remains pending-work authority, independently of resource streams.

package/dist/chat-target.d.ts

@@ -1,8 +1,5 @@
-export interface ChatTarget {
-    kind: 'contact' | 'agent' | 'room';
-    source: 'work' | 'messenger';
-    chat: string;
-}
-/** Stable conversation identity, independent of list filters and message anchors. */
-export declare function chatTarget(path: string): ChatTarget | null;
+import { type ConversationTarget } from './validation.js';
+export type ChatTarget = ConversationTarget;
+/** Stable conversation identity, independent of message anchors. */
+export declare function chatTarget(value: unknown): ChatTarget | null;
 export declare function chatKey(value: ChatTarget): string;

package/dist/chat-target.js

@@ -1,34 +1,19 @@
-import { target as navigationTarget } from './validation.js';
-/** Stable conversation identity, independent of list filters and message anchors. */
-export function chatTarget(path) {
+import { conversationTarget } from './validation.js';
+/** Stable conversation identity, independent of message anchors. */
+export function chatTarget(value) {
     try {
-        navigationTarget(path);
-        const url = new URL(path, 'https://ours.invalid');
-        if (['source', 'chat', 'task', 'detail'].some(key => url.searchParams.has(key)))
-            return null;
-        // Match the original path: URL normalization must not turn malformed arity into a target.
-        const parts = path.split(/[?#]/, 1)[0].split('/').slice(1).map(decodeURIComponent);
-        if (parts.some(part => !part || /[\x00-\x1f\x7f]/.test(part) || part === '.' || part === '..'))
-            return null;
-        if (parts.length === 4 && parts[0] === 'fleet' && parts[1] === 'chats') {
-            if (parts[2] === 'contacts')
-                return { kind: 'contact', source: 'messenger', chat: parts[3] };
-            if (parts[2] === 'agents')
-                return { kind: 'agent', source: 'work', chat: parts[3] };
-        }
-        if (parts[0] === 'fleet' && parts[1] === 'tasks' && /^[A-Za-z0-9_-]{1,120}$/.test(parts[2] ?? '')) {
-            if (parts.length === 4 && parts[3] === 'room')
-                return { kind: 'room', source: 'work', chat: `room-${parts[2]}` };
-            if (parts.length === 5 && parts[3] === 'rooms' && /^[A-Za-z][A-Za-z0-9_-]*$/.test(parts[4])
-                && !['constructor', 'prototype', '__proto__'].includes(parts[4])) {
-                return { kind: 'room', source: 'work', chat: `room-${parts[2]}:${parts[4]}` };
-            }
-        }
+        return conversationTarget(value);
+    }
+    catch {
+        return null;
     }
-    catch { /* Unsupported persisted input is unknown, never a missing target. */ }
-    return null;
 }
 export function chatKey(value) {
-    const chat = value.kind === 'contact' && /^[a-f0-9]{64}$/i.test(value.chat) ? value.chat.toUpperCase() : value.chat;
-    return JSON.stringify([value.kind, value.source, chat]);
+    if (value.kind === 'contact') {
+        const id = /^[a-f0-9]{64}$/i.test(value.contactId) ? value.contactId.toUpperCase() : value.contactId;
+        return JSON.stringify(['contact', id]);
+    }
+    if (value.kind === 'agent')
+        return JSON.stringify(['agent', value.agentId]);
+    return JSON.stringify(['room', value.taskId, value.roomKey ?? null]);
 }

package/dist/resource-views.d.ts

@@ -0,0 +1,25 @@
+import type { ServerResponse } from 'node:http';
+import type { Store } from './store.js';
+/** Ephemeral user/credential-bound views; unrelated to foreground presence or acknowledgement. */
+export declare class NotificationViews {
+    private readonly store;
+    readonly producerGeneration: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly connections;
+    constructor(store: Store);
+    open(user: string, principal: string, response: ServerResponse): void;
+    private source;
+    private get;
+    private project;
+    private emit;
+    register(principal: string, input: Record<string, unknown>): {
+        subscriptionEpoch: number;
+        baselineId: string;
+    };
+    remove(principal: string, input: Record<string, unknown>): void;
+    bound(principal: string, connectionId: string, viewId: string, epoch: string, baselineId: string, resource: 'inbox' | 'summary'): {
+        producerGeneration: `${string}-${string}-${string}-${string}-${string}`;
+        payload: any;
+        revision: number;
+    };
+    close(): void;
+}

package/dist/resource-views.js

@@ -0,0 +1,224 @@
+import { randomUUID } from 'node:crypto';
+import { HttpError } from './validation.js';
+const FRAME = 512 * 1024, PENDING = 8 * 1024 * 1024, ASSEMBLY = 16 * 1024 * 1024, CHUNK = 256 * 1024;
+function descriptor(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new HttpError(400, 'invalid resource descriptor');
+    const value = input;
+    if (Object.keys(value).some(k => !['viewId', 'resource', 'window'].includes(k)) || typeof value.viewId !== 'string' || !/^[A-Za-z0-9_-]{1,100}$/.test(value.viewId)
+        || !['summary', 'inbox'].includes(value.resource))
+        throw new HttpError(400, 'invalid resource descriptor');
+    if (value.resource === 'summary') {
+        if (value.window !== undefined)
+            throw new HttpError(400, 'summary has no window');
+        return { viewId: value.viewId, resource: value.resource };
+    }
+    const window = value.window;
+    if (!window || Object.keys(window).some(k => !['limit', 'retainedPages'].includes(k))
+        || !Number.isInteger(window.limit) || window.limit < 1 || window.limit > 100
+        || !Number.isInteger(window.retainedPages) || window.retainedPages < 1 || window.retainedPages > 200)
+        throw new HttpError(400, 'invalid inbox window');
+    return { viewId: value.viewId, resource: value.resource, window: { limit: window.limit, retainedPages: window.retainedPages } };
+}
+/** One active assembly is streamed lazily; waiting complete records share the smaller pending budget. */
+class Output {
+    response;
+    failed;
+    active = false;
+    pending = [];
+    bytes = 0;
+    closed = false;
+    release;
+    constructor(response, failed) {
+        this.response = response;
+        this.failed = failed;
+    }
+    send(envelope) {
+        if (this.closed)
+            return;
+        const bytes = Buffer.byteLength(JSON.stringify(envelope));
+        if (bytes > ASSEMBLY || (this.active && this.bytes + bytes > PENDING)) {
+            this.failed();
+            return;
+        }
+        this.pending.push({ envelope, bytes });
+        this.bytes += bytes;
+        if (!this.active)
+            void this.pump();
+    }
+    close() { this.closed = true; this.pending = []; this.bytes = 0; this.release?.(); }
+    async write(event, data) {
+        if (this.closed)
+            return;
+        const text = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        if (Buffer.byteLength(text) > FRAME)
+            throw Error('resource frame limit');
+        if (!this.response.write(text))
+            await new Promise(resolve => {
+                const release = () => { this.response.removeListener('drain', release); this.release = undefined; resolve(); };
+                this.release = release;
+                this.response.once('drain', release);
+            });
+    }
+    async pump() {
+        this.active = true;
+        try {
+            while (!this.closed && this.pending.length) {
+                const { envelope, bytes } = this.pending.shift();
+                this.bytes -= bytes;
+                const encoded = Buffer.from(JSON.stringify(envelope));
+                if (encoded.length + 32 <= FRAME)
+                    await this.write('resource', envelope);
+                else {
+                    const binding = { protocolVersion: 1, id: `${envelope.viewId}:${envelope.subscriptionEpoch}:${envelope.sequence}`,
+                        producerGeneration: envelope.producerGeneration, viewId: envelope.viewId, subscriptionEpoch: envelope.subscriptionEpoch,
+                        revision: envelope.revision, sequence: envelope.sequence };
+                    await this.write('resource-chunk', { ...binding, type: 'start', totalBytes: encoded.length, parts: Math.ceil(encoded.length / CHUNK) });
+                    for (let offset = 0, index = 0; offset < encoded.length && !this.closed; offset += CHUNK, index++)
+                        await this.write('resource-chunk', { ...binding, type: 'chunk', index, data: encoded.subarray(offset, offset + CHUNK).toString('base64') });
+                    await this.write('resource-chunk', { ...binding, type: 'commit', totalBytes: encoded.length });
+                }
+            }
+        }
+        catch {
+            this.failed();
+        }
+        finally {
+            this.active = false;
+        }
+    }
+}
+// The global store revision is a read-command watermark, not user content.
+// Keep it in published payloads, but do not emit another account's commit.
+function contentKey(payload) {
+    return JSON.stringify({ ...payload, revision: undefined,
+        ...(payload.summary ? { summary: { ...payload.summary, revision: undefined } } : {}) });
+}
+/** Ephemeral user/credential-bound views; unrelated to foreground presence or acknowledgement. */
+export class NotificationViews {
+    store;
+    producerGeneration = randomUUID();
+    connections = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    open(user, principal, response) {
+        if (this.connections.size >= 128 || [...this.connections.values()].filter(c => c.principal === principal).length >= 16)
+            throw new HttpError(503, 'resource capacity');
+        const id = randomUUID(), controller = new AbortController();
+        const close = () => {
+            if (controller.signal.aborted)
+                return;
+            controller.abort();
+            clearInterval(connection.timer);
+            connection.output.close();
+            connection.views.clear();
+            this.connections.delete(id);
+            response.removeListener('close', close);
+            response.end();
+        };
+        const output = new Output(response, close);
+        const timer = setInterval(() => {
+            for (const view of connection.views.values())
+                this.emit(connection, view, 'coverage', { source: this.source(view.revision) });
+        }, 2000);
+        timer.unref();
+        const connection = { id, principal, user, response, output, controller, views: new Map(), epochs: new Map(), timer, close };
+        this.connections.set(id, connection);
+        let scheduled = false;
+        this.store.subscribe(() => {
+            if (scheduled)
+                return;
+            scheduled = true;
+            queueMicrotask(() => {
+                scheduled = false;
+                if (controller.signal.aborted)
+                    return;
+                try {
+                    for (const view of connection.views.values()) {
+                        const captured = this.project(user, view.descriptor), payload = contentKey(captured.payload);
+                        if (payload === view.payload)
+                            continue;
+                        view.payload = payload;
+                        view.revision = captured.revision;
+                        this.emit(connection, view, 'snapshot', captured.payload);
+                        this.emit(connection, view, 'coverage', { source: this.source(captured.revision) });
+                    }
+                }
+                catch {
+                    close();
+                }
+            });
+        }, controller.signal);
+        response.once('close', close);
+        response.setHeader('content-type', 'text/event-stream');
+        response.flushHeaders();
+        response.write(`event: resource-connection\ndata: ${JSON.stringify({ protocolVersion: 1, connectionId: id, producerGeneration: this.producerGeneration, baselineRequired: true, continuity: 'reset' })}\n\n`);
+    }
+    source(position) { return { protocolVersion: 1, producerGeneration: this.producerGeneration, position }; }
+    get(id, principal) {
+        const connection = this.connections.get(id);
+        if (!connection || connection.principal !== principal)
+            throw new HttpError(409, 'unknown resource connection');
+        return connection;
+    }
+    project(user, value) {
+        const summary = this.store.summary(user);
+        if (value.resource === 'summary')
+            return { payload: structuredClone(summary), revision: summary.revision };
+        const items = [];
+        let nextCursor = null;
+        for (let page = 0; page < value.window.retainedPages; page++) {
+            const next = this.store.inbox(user, nextCursor ?? undefined, value.window.limit);
+            items.push(...next.items);
+            nextCursor = next.nextCursor ?? null;
+            if (!nextCursor)
+                break;
+        }
+        return { payload: structuredClone({ items, unread: summary.unread, revision: summary.revision, nextCursor,
+                summary, delivery: this.store.deliveryStatus(user) }), revision: summary.revision };
+    }
+    emit(connection, view, kind, payload) {
+        connection.output.send({ protocolVersion: 1, producerGeneration: this.producerGeneration, viewId: view.descriptor.viewId,
+            subscriptionEpoch: view.epoch, sequence: ++view.sequence, revision: view.revision, baselineId: view.baselineId, kind, payload });
+    }
+    register(principal, input) {
+        const connection = this.get(String(input.connectionId), principal), value = descriptor(input.descriptor), epoch = input.subscriptionEpoch;
+        if (input.viewId !== value.viewId || !Number.isSafeInteger(epoch) || epoch < 1)
+            throw new HttpError(400, 'invalid subscription epoch');
+        if ((connection.epochs.get(value.viewId) ?? 0) >= epoch)
+            throw new HttpError(409, 'obsolete subscription epoch');
+        if ((!connection.views.has(value.viewId) && connection.views.size >= 32) || (!connection.epochs.has(value.viewId) && connection.epochs.size >= 128))
+            throw new HttpError(503, 'resource view capacity');
+        const baseline = this.project(connection.user, value);
+        const view = { descriptor: value, epoch: epoch, baselineId: randomUUID(), sequence: 0, revision: baseline.revision,
+            baseline, payload: contentKey(baseline.payload) };
+        connection.views.set(value.viewId, view);
+        connection.epochs.set(value.viewId, view.epoch);
+        this.emit(connection, view, 'snapshot', baseline.payload);
+        this.emit(connection, view, 'ready', { baselineId: view.baselineId, source: this.source(baseline.revision) });
+        return { subscriptionEpoch: view.epoch, baselineId: view.baselineId };
+    }
+    remove(principal, input) {
+        const connection = this.get(String(input.connectionId), principal), viewId = input.viewId, epoch = input.subscriptionEpoch;
+        if (typeof viewId !== 'string' || !/^[A-Za-z0-9_-]{1,100}$/.test(viewId)
+            || !Number.isSafeInteger(epoch) || epoch < 1)
+            throw new HttpError(400, 'invalid subscription epoch');
+        if (!connection.epochs.has(viewId) && connection.epochs.size >= 128)
+            throw new HttpError(503, 'resource view capacity');
+        // DELETE can beat an aborted registration POST over independent HTTP requests.
+        // Retain its fence even when the candidate has not been installed yet.
+        connection.epochs.set(viewId, Math.max(connection.epochs.get(viewId) ?? 0, epoch));
+        const view = connection.views.get(viewId);
+        if (view && epoch >= view.epoch)
+            connection.views.delete(viewId);
+    }
+    bound(principal, connectionId, viewId, epoch, baselineId, resource) {
+        const connection = this.get(connectionId, principal), view = connection.views.get(viewId);
+        if (!view || String(view.epoch) !== epoch || view.baselineId !== baselineId || view.descriptor.resource !== resource)
+            throw new HttpError(409, 'resource binding mismatch');
+        return { ...view.baseline, producerGeneration: this.producerGeneration };
+    }
+    close() { for (const connection of [...this.connections.values()])
+        connection.close(); }
+}

package/dist/server.js

@@ -3,7 +3,8 @@ import { timingSafeEqual } from 'node:crypto';
 import webpush from 'web-push';
 import { attachPresence } from './presence.js';
 import { Store } from './store.js';
-import { HttpError, object, subscription, target, text } from './validation.js';
+import { NotificationViews } from './resource-views.js';
+import { HttpError, object, subscription, target, anchor, conversationTarget, fields, text } from './validation.js';
 const same = (a, b) => {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -31,6 +32,7 @@ export function createNotificationService(config, send) {
         throw new Error('invalid scoped credentials');
     webpush.setVapidDetails(config.vapid.subject, config.vapid.publicKey, config.vapid.privateKey);
     const store = new Store(config.stateFile);
+    const views = new NotificationViews(store);
     const deliver = send ?? ((sub, payload) => webpush.sendNotification(sub, payload, { TTL: 3600, timeout: 10_000,
         vapidDetails: config.vapid, contentEncoding: 'aes128gcm' }));
     const rates = new Map();
@@ -58,6 +60,38 @@ export function createNotificationService(config, send) {
             if (++rate.count > (producerRoute ? 600 : 180))
                 throw new HttpError(429, 'rate limit exceeded');
             const user = credential.userId;
+            if (req.method === 'GET' && url.pathname === '/api/v1/events' && url.searchParams.get('resources') === '1') {
+                views.open(user, credential.token, res);
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/api/v1/resource-subscriptions') {
+                const value = await body(req);
+                if (res.destroyed)
+                    return;
+                res.end(JSON.stringify(views.register(credential.token, value)));
+                return;
+            }
+            if (req.method === 'DELETE' && url.pathname === '/api/v1/resource-subscriptions') {
+                const value = await body(req);
+                views.remove(credential.token, value);
+                res.end(JSON.stringify({ ok: true }));
+                return;
+            }
+            const binding = ['x-resource-connection', 'x-resource-view', 'x-resource-epoch', 'x-resource-baseline'].map(name => req.headers[name]);
+            if (binding.some(value => value !== undefined)) {
+                if (req.method !== 'GET' || !['/api/v1/summary', '/api/v1/inbox'].includes(url.pathname)
+                    || binding.some(value => typeof value !== 'string') || url.searchParams.has('before'))
+                    throw new HttpError(409, 'resource binding mismatch');
+                const baseline = views.bound(credential.token, binding[0], binding[1], binding[2], binding[3], url.pathname === '/api/v1/inbox' ? 'inbox' : 'summary');
+                for (const [index, name] of ['X-Resource-Connection', 'X-Resource-View', 'X-Resource-Epoch', 'X-Resource-Baseline'].entries())
+                    res.setHeader(name, binding[index]);
+                res.setHeader('X-Resource-Producer', baseline.producerGeneration);
+                res.setHeader('X-Resource-Revision', String(baseline.revision));
+                res.setHeader('X-Resource-Source-Generation', baseline.producerGeneration);
+                res.setHeader('X-Resource-Source-Position', String(baseline.revision));
+                res.end(JSON.stringify(baseline.payload));
+                return;
+            }
             let result;
             if (req.method === 'GET' && url.pathname === '/api/v1/push/config')
                 result = { publicKey: config.vapid.publicKey };
@@ -80,7 +114,8 @@ export function createNotificationService(config, send) {
                 result = { removed: store.deleteDevice(user, text((await body(req)).id, 100)) };
             else if (req.method === 'POST' && url.pathname === '/api/v1/read-target') {
                 const value = await body(req);
-                store.readTarget(user, target(value.url), value.revision);
+                fields(value, ['target', 'revision']);
+                store.readTarget(user, conversationTarget(value.target), value.revision);
                 result = { ok: true };
             }
             else if (req.method === 'POST' && url.pathname === '/api/v1/read') {
@@ -100,17 +135,21 @@ export function createNotificationService(config, send) {
                 const value = await body(req);
                 if ('userId' in value || 'source' in value)
                     throw new HttpError(400, 'recipient and source are credential scoped');
-                result = { removed: store.deleteTarget(user, credential.source, target(value.url)) };
+                fields(value, ['target']);
+                result = { removed: store.deleteTarget(user, credential.source, conversationTarget(value.target)) };
             }
             else if (req.method === 'POST' && url.pathname === '/api/v1/send') {
                 const value = await body(req);
                 if ('userId' in value || 'source' in value)
                     throw new HttpError(400, 'recipient and source are credential scoped');
+                fields(value, ['eventId', 'title', 'body', 'target', 'anchor', 'taskId']);
+                const destination = target(value.target);
+                const messageAnchor = value.anchor === undefined ? undefined : anchor(value.anchor, destination);
                 const taskId = value.taskId === undefined ? undefined : value.taskId === null ? null : text(value.taskId, 120);
                 if (typeof taskId === 'string' && !/^[A-Za-z0-9_-]+$/.test(taskId))
                     throw new HttpError(400, 'invalid task identity');
                 result = store.produce({ ...(taskId === undefined ? {} : { taskId }), userId: user, source: credential.source, eventId: text(value.eventId, 512),
-                    title: text(value.title, 160), body: text(value.body, 512), url: target(value.url) });
+                    title: text(value.title, 160), body: text(value.body, 512), target: destination, ...(messageAnchor === undefined ? {} : { anchor: messageAnchor }) });
             }
             else
                 throw new HttpError(404, 'route not found');
@@ -133,13 +172,13 @@ export function createNotificationService(config, send) {
                 store.finish(j.id, 'sent', Date.now(), j.notification?.readAt ? 'read_cancelled' : 'missing_target');
                 continue;
             }
-            if (!/^\/fleet\/tasks(?:\/[^/]+)?\/?$/.test(new URL(j.notification.url, 'https://ours.invalid').pathname) && presence.online(j.device.userId, j.device.id)) {
+            if (j.notification.target?.kind !== 'task' && j.notification.target?.kind !== 'task-deleted' && presence.online(j.device.userId, j.device.id)) {
                 store.finish(j.id, 'sent', Date.now(), 'foreground_suppressed');
                 continue;
             }
             try {
                 const result = await deliver(j.device.subscription, JSON.stringify({ v: 1, kind: 'notification', title: j.notification.title,
-                    body: j.notification.body, url: j.notification.url, notification_id: j.notification.id, tag: j.notification.id }));
+                    body: j.notification.body, target: j.notification.target, ...(j.notification.anchor === undefined ? {} : { anchor: j.notification.anchor }), notification_id: j.notification.id, tag: j.notification.id }));
                 store.finish(j.id, 'sent', Date.now(), 'provider_accepted', result?.statusCode);
             }
             catch (error) {
@@ -152,6 +191,7 @@ export function createNotificationService(config, send) {
     timer.unref();
     return { server, store, drain, async close() {
             clearInterval(timer);
+            views.close();
             presence.close();
             await draining;
             server.closeAllConnections();

package/dist/store.d.ts

@@ -1,5 +1,6 @@
 import { type ChatTarget } from './chat-target.js';
 import type { PushSubscription } from 'web-push';
+import { type NotificationTarget, type NotificationAnchor } from './validation.js';
 export interface Notification {
     id: string;
     userId: string;
@@ -7,7 +8,8 @@ export interface Notification {
     eventId: string;
     title: string;
     body: string;
-    url: string;
+    target: NotificationTarget;
+    anchor?: NotificationAnchor;
     createdAt: string;
     createdRevision?: number;
     readAt: string | null;
@@ -28,12 +30,18 @@ interface Delivery {
     attempt: number;
     statusCode?: number;
 }
+type Input = Omit<Notification, 'id' | 'createdAt' | 'readAt'>;
+/** The receipt fingerprint of a typed notification, as stored with it. */
+export declare const fingerprint: (value: Input) => string;
 /** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
 export declare class Store {
     private readonly file;
     private state;
     private readonly lockToken;
     private closed;
+    private readonly observers;
+    /** Neutral committed observation; never enrolls a device or changes read state. */
+    subscribe(committed: () => void, signal: AbortSignal): () => void;
     constructor(file: string);
     close(): void;
     private commit;
@@ -52,21 +60,22 @@ export declare class Store {
     summary(userId: string): {
         unread: number;
         revision: number;
-        chats: (ChatTarget & {
+        chats: {
+            target: ChatTarget;
             count: number;
-        })[];
+        }[];
         sections: {
             chats: number;
             tasks: number;
         };
     };
-    readTarget(userId: string, url: string, revision: number): void;
+    readTarget(userId: string, value: unknown, revision: number): void;
     read(userId: string, ids: string[]): void;
     /** Delete only this user's confirmed stale entries and their pending deliveries. */
     deleteNotifications(userId: string, ids: string[]): number;
     /** A producer may retire only its own notifications for the canonical conversation. */
-    deleteTarget(userId: string, source: string, url: string): number;
-    produce(value: Omit<Notification, 'id' | 'createdAt' | 'readAt'>): Notification | {
+    deleteTarget(userId: string, source: string, value: unknown): number;
+    produce(value: Input): Notification | {
         id: string;
         duplicate: true;
     };

package/dist/store.js

@@ -2,15 +2,115 @@ import { chatTarget, chatKey } from './chat-target.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { HttpError } from './validation.js';
-const fingerprint = (value) => createHash('sha256')
-    .update(JSON.stringify([value.userId, value.source, value.eventId, value.title, value.body, value.url, value.taskId === undefined ? [] : [value.taskId]])).digest('hex');
+import { HttpError, target, anchor, conversationTarget, subscription } from './validation.js';
+/** The receipt fingerprint of a typed notification, as stored with it. */
+export const fingerprint = (value) => createHash('sha256').update(JSON.stringify([
+    'domain-target-v1', value.userId, value.source, value.eventId, value.title, value.body,
+    target(value.target), value.anchor === undefined ? null : anchor(value.anchor, value.target),
+    value.taskId === undefined ? [] : [value.taskId],
+])).digest('hex');
+const outcomes = ['provider_accepted', 'foreground_suppressed', 'endpoint_expired', 'retry_scheduled', 'read_cancelled', 'missing_target', 'no_device'];
+const record = (value, keys) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !Object.keys(value).every(key => keys.includes(key)))
+        throw new Error();
+    return value;
+};
+const string = (value) => { if (typeof value !== 'string' || !value)
+    throw new Error(); return value; };
+const count = (value) => { if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error(); return value; };
+/** Accepts only this release's persisted format: every record typed, consistent and closed. */
+function validState(value) {
+    try {
+        const state = record(value, ['version', 'revision', 'devices', 'notifications', 'jobs', 'receipts', 'deliveries']);
+        if (state.version !== 2)
+            throw new Error();
+        count(state.revision);
+        for (const key of ['devices', 'notifications', 'jobs', 'receipts', 'deliveries'])
+            if (!Array.isArray(state[key]))
+                throw new Error();
+        const devices = new Map(), notifications = new Map(), receipts = new Map();
+        for (const item of state.devices) {
+            const d = record(item, ['id', 'userId', 'subscription']);
+            subscription(d.subscription);
+            if (devices.has(string(d.id)))
+                throw new Error();
+            devices.set(d.id, string(d.userId));
+        }
+        for (const item of state.receipts) {
+            const r = record(item, ['userId', 'source', 'eventId', 'id', 'fingerprint']);
+            const key = JSON.stringify([string(r.userId), string(r.source), string(r.eventId)]);
+            string(r.id);
+            if (receipts.has(key) || !/^[a-f0-9]{64}$/.test(string(r.fingerprint)))
+                throw new Error();
+            receipts.set(key, r);
+        }
+        for (const item of state.notifications) {
+            const n = record(item, ['id', 'userId', 'source', 'eventId', 'title', 'body', 'target', 'anchor', 'createdAt', 'createdRevision', 'readAt', 'taskId']);
+            for (const key of ['id', 'userId', 'source', 'eventId', 'title', 'body', 'createdAt'])
+                string(n[key]);
+            const destination = target(n.target);
+            if (n.anchor !== undefined)
+                anchor(n.anchor, destination);
+            if (n.createdRevision !== undefined)
+                count(n.createdRevision);
+            if (n.readAt !== null)
+                string(n.readAt);
+            // Task association has the same rules as produce: a valid string identity that agrees with task and room targets.
+            if (n.taskId !== undefined && n.taskId !== null && (typeof n.taskId !== 'string' || !/^[A-Za-z0-9_-]{1,120}$/.test(n.taskId)))
+                throw new Error();
+            if ((destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room') && n.taskId !== undefined && n.taskId !== destination.taskId)
+                throw new Error();
+            // Each notification's own receipt carries its typed fingerprint.
+            const own = receipts.get(JSON.stringify([n.userId, n.source, n.eventId]));
+            if (!own || own.id !== n.id || own.fingerprint !== fingerprint(n) || notifications.has(n.id))
+                throw new Error();
+            notifications.set(n.id, n.userId);
+        }
+        for (const item of state.jobs) {
+            const j = record(item, ['id', 'notificationId', 'deviceId', 'attempts', 'due']);
+            string(j.id);
+            count(j.attempts);
+            count(j.due);
+            const owner = notifications.get(string(j.notificationId));
+            if (owner === undefined || devices.get(string(j.deviceId)) !== owner)
+                throw new Error();
+        }
+        for (const item of state.deliveries) {
+            const d = record(item, ['userId', 'notificationId', 'deviceId', 'at', 'outcome', 'attempt', 'statusCode']);
+            string(d.userId);
+            string(d.notificationId);
+            string(d.at);
+            count(d.attempt);
+            if (d.deviceId !== undefined)
+                string(d.deviceId);
+            if (d.statusCode !== undefined)
+                count(d.statusCode);
+            if (!outcomes.includes(d.outcome))
+                throw new Error();
+        }
+        return state;
+    }
+    catch {
+        throw new Error('unsupported notification state: this release reads only its own version 2 state file');
+    }
+}
 /** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
 export class Store {
     file;
     state;
     lockToken = `${process.pid}:${randomUUID()}`;
     closed = false;
+    observers = new Set();
+    /** Neutral committed observation; never enrolls a device or changes read state. */
+    subscribe(committed, signal) {
+        const dispose = () => { this.observers.delete(committed); signal.removeEventListener('abort', dispose); };
+        if (!signal.aborted && !this.closed) {
+            this.observers.add(committed);
+            signal.addEventListener('abort', dispose, { once: true });
+        }
+        return dispose;
+    }
     constructor(file) {
         this.file = file;
         mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
@@ -30,11 +130,9 @@ export class Store {
             closeSync(lockFd);
         }
         try {
-            this.state = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { version: 1, revision: 0, devices: [], notifications: [], jobs: [] };
-            this.state.receipts ??= this.state.notifications.map(n => ({ userId: n.userId, source: n.source, eventId: n.eventId, id: n.id, fingerprint: fingerprint(n) }));
-            this.state.deliveries ??= [];
-            if (this.state.version !== 1 || !Array.isArray(this.state.notifications) || !Array.isArray(this.state.devices) || !Array.isArray(this.state.jobs))
-                throw new Error('invalid notification state');
+            // A missing state file starts empty; an existing one must be this release's format and is never rewritten to fit.
+            this.state = existsSync(file) ? validState(JSON.parse(readFileSync(file, 'utf8')))
+                : { version: 2, revision: 0, devices: [], notifications: [], jobs: [], receipts: [], deliveries: [] };
         }
         catch (error) {
             this.close();
@@ -48,6 +146,7 @@ export class Store {
             throw new Error('notification lock ownership changed');
         unlinkSync(this.file + '.lock');
         this.closed = true;
+        this.observers.clear();
     }
     commit(change) {
         const draft = structuredClone(this.state);
@@ -71,6 +170,13 @@ export class Store {
             closeSync(dir);
         }
         this.state = draft;
+        for (const committed of [...this.observers]) {
+            if (this.observers.has(committed))
+                try {
+                    committed();
+                }
+                catch { /* committed persistence cannot be undone by observation */ }
+        }
     }
     ensureDevice(userId, subscription) {
         const existing = this.state.devices.find(d => d.subscription.endpoint === subscription.endpoint);
@@ -110,36 +216,26 @@ export class Store {
         const groups = new Map();
         const sections = { chats: 0, tasks: 0 };
         for (const n of unread) {
-            const url = new URL(n.url, 'https://ours.invalid'), targetForSection = chatTarget(n.url);
-            if (/^\/fleet\/tasks(?:\/[^/]+)?\/?$/.test(url.pathname))
+            const destination = n.target;
+            if (destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room' || typeof n.taskId === 'string')
                 sections.tasks++;
-            else if (targetForSection) {
-                if (typeof n.taskId === 'string' || targetForSection.kind === 'room')
-                    sections.tasks++;
-                else if (targetForSection.source === 'messenger')
-                    sections.chats++;
-                else if (n.taskId === null)
-                    sections.chats++;
-                // Older ACP records carry no association: leave them in the total only.
-            }
-            const target = chatTarget(n.url);
-            if (!target)
+            else if (destination.kind === 'contact' || n.taskId === null)
+                sections.chats++;
+            const conversation = chatTarget(destination);
+            if (!conversation)
                 continue;
-            const key = chatKey(target), group = groups.get(key) ?? { ...target, count: 0 };
+            const key = chatKey(conversation), group = groups.get(key) ?? { target: conversation, count: 0 };
             group.count++;
             groups.set(key, group);
         }
         return { unread: unread.length, revision: this.state.revision, chats: [...groups.values()], sections };
     }
-    readTarget(userId, url, revision) {
+    readTarget(userId, value, revision) {
         if (!Number.isSafeInteger(revision) || revision < 0 || revision > this.state.revision)
             throw new HttpError(400, 'invalid observed revision');
-        const target = chatTarget(url);
-        if (!target)
-            throw new HttpError(400, 'expected chat target');
-        const key = chatKey(target);
+        const key = chatKey(conversationTarget(value));
         const ids = this.state.notifications.filter(n => n.userId === userId && !n.readAt && (n.createdRevision ?? 0) <= revision && (() => {
-            const other = chatTarget(n.url);
+            const other = chatTarget(n.target);
             return other && chatKey(other) === key;
         })()).map(n => n.id);
         if (ids.length)
@@ -168,24 +264,29 @@ export class Store {
         return removed.size;
     }
     /** A producer may retire only its own notifications for the canonical conversation. */
-    deleteTarget(userId, source, url) {
-        const target = chatTarget(url);
-        if (!target)
-            throw new HttpError(400, 'expected chat target');
-        const key = chatKey(target);
+    deleteTarget(userId, source, value) {
+        const key = chatKey(conversationTarget(value));
         const ids = this.state.notifications.filter(n => n.userId === userId && n.source === source && (() => {
-            const other = chatTarget(n.url);
+            const other = chatTarget(n.target);
             return other && chatKey(other) === key;
         })()).map(n => n.id);
         return this.deleteNotifications(userId, ids);
     }
     produce(value) {
+        const destination = target(value.target);
+        if ('url' in value)
+            throw new HttpError(400, 'unexpected field');
+        value = { ...value, target: destination, ...(value.anchor === undefined ? {} : { anchor: anchor(value.anchor, destination) }) };
+        if (value.taskId !== undefined && value.taskId !== null && !/^[A-Za-z0-9_-]{1,120}$/.test(value.taskId))
+            throw new HttpError(400, 'invalid task identity');
+        if ((destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room') && value.taskId !== undefined && value.taskId !== destination.taskId)
+            throw new HttpError(400, 'conflicting task identity');
         const receipt = this.state.receipts.find(r => r.userId === value.userId && r.source === value.source && r.eventId === value.eventId);
         if (receipt && receipt.fingerprint !== fingerprint(value))
             throw new HttpError(409, 'event id reused');
         const previous = this.state.notifications.find(n => n.userId === value.userId && n.source === value.source && n.eventId === value.eventId);
         if (previous) {
-            if (previous.title !== value.title || previous.body !== value.body || previous.url !== value.url || previous.taskId !== value.taskId)
+            if (fingerprint(previous) !== fingerprint(value))
                 throw new HttpError(409, 'event id reused');
             return previous;
         }

package/dist/validation.d.ts

@@ -5,5 +5,33 @@ export declare class HttpError extends Error {
 }
 export declare function text(value: unknown, max: number): string;
 export declare function object(value: unknown): Record<string, unknown>;
-export declare function target(value: unknown): string;
+export type ConversationTarget = {
+    kind: 'contact';
+    contactId: string;
+} | {
+    kind: 'agent';
+    agentId: string;
+} | {
+    kind: 'room';
+    taskId: string;
+    roomKey?: string;
+};
+export type NotificationTarget = ConversationTarget | {
+    kind: 'task';
+    taskId: string;
+} | {
+    kind: 'task-deleted';
+    taskId: string;
+};
+export type NotificationAnchor = {
+    kind: 'messenger-message';
+    wireId: string;
+} | {
+    kind: 'fleet-message';
+    messageId: string;
+};
+export declare function fields(value: Record<string, unknown>, allowed: readonly string[]): void;
+export declare function target(value: unknown): NotificationTarget;
+export declare function conversationTarget(value: unknown): ConversationTarget;
+export declare function anchor(value: unknown, destination: NotificationTarget): NotificationAnchor;
 export declare function subscription(value: unknown): PushSubscription;

package/dist/validation.js

@@ -16,16 +16,69 @@ export function object(value) {
         throw new HttpError(400, 'expected object');
     return value;
 }
+export function fields(value, allowed) {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        throw new HttpError(400, 'unexpected field');
+}
+function identifier(value, max) {
+    const id = text(value, max);
+    if (/[\x00-\x1f\x7f]/.test(id))
+        throw new HttpError(400, 'invalid identifier');
+    return id;
+}
+function taskIdentity(value) {
+    const id = identifier(value, 120);
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new HttpError(400, 'invalid task identity');
+    return id;
+}
 export function target(value) {
-    const path = text(value, 2048);
-    // Only first-party Fleet pages. No scheme-relative URLs, encoded slashes,
-    // backslashes or control characters which browsers could normalize elsewhere.
-    if (!/^\/fleet(?:\/|\?|$)/.test(path) || /[\\\x00-\x20]|%(?:2f|5c|00|0[ad])/i.test(path))
-        throw new HttpError(400, 'invalid navigation target');
-    const url = new URL(path, 'https://ours.invalid');
-    if (url.origin !== 'https://ours.invalid' || !/^\/fleet(?:\/|$)/.test(url.pathname))
-        throw new HttpError(400, 'invalid navigation target');
-    return path;
+    const item = object(value);
+    if (item.kind === 'contact') {
+        fields(item, ['kind', 'contactId']);
+        const contactId = identifier(item.contactId, 512);
+        if (/[\/\\]/.test(contactId) || contactId === '.' || contactId === '..')
+            throw new HttpError(400, 'invalid contact identity');
+        return { kind: 'contact', contactId };
+    }
+    if (item.kind === 'agent') {
+        fields(item, ['kind', 'agentId']);
+        const agentId = taskIdentity(item.agentId);
+        return { kind: 'agent', agentId };
+    }
+    if (item.kind === 'room') {
+        fields(item, ['kind', 'taskId', 'roomKey']);
+        const taskId = taskIdentity(item.taskId);
+        if (item.roomKey === undefined)
+            return { kind: 'room', taskId };
+        const roomKey = identifier(item.roomKey, 120);
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(roomKey) || ['constructor', 'prototype', '__proto__'].includes(roomKey))
+            throw new HttpError(400, 'invalid room key');
+        return { kind: 'room', taskId, roomKey };
+    }
+    if (item.kind === 'task' || item.kind === 'task-deleted') {
+        fields(item, ['kind', 'taskId']);
+        return { kind: item.kind, taskId: taskIdentity(item.taskId) };
+    }
+    throw new HttpError(400, 'invalid notification target');
+}
+export function conversationTarget(value) {
+    const result = target(value);
+    if (result.kind === 'task' || result.kind === 'task-deleted')
+        throw new HttpError(400, 'expected conversation target');
+    return result;
+}
+export function anchor(value, destination) {
+    const item = object(value);
+    if (item.kind === 'messenger-message' && (destination.kind === 'contact' || destination.kind === 'room')) {
+        fields(item, ['kind', 'wireId']);
+        return { kind: 'messenger-message', wireId: identifier(item.wireId, 1024) };
+    }
+    if (item.kind === 'fleet-message' && destination.kind === 'agent') {
+        fields(item, ['kind', 'messageId']);
+        return { kind: 'fleet-message', messageId: identifier(item.messageId, 1024) };
+    }
+    throw new HttpError(400, 'invalid notification anchor');
 }
 export function subscription(value) {
     const item = object(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/notifications",
-  "version": "0.3.1-nightly.4",
+  "version": "0.3.1-nightly.6",
   "description": "Authenticated web push delivery and shared notification inbox",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",