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

package/README.md

@@ -173,3 +173,7 @@ admitted as receipts on load. The existing inbox/job caps remain; a separate cap
 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.
+
+## 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/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,6 +3,7 @@ import { timingSafeEqual } from 'node:crypto';
 import webpush from 'web-push';
 import { attachPresence } from './presence.js';
 import { Store } from './store.js';
+import { NotificationViews } from './resource-views.js';
 import { HttpError, object, subscription, target, text } from './validation.js';
 const same = (a, b) => {
     const x = Buffer.from(a), y = Buffer.from(b);
@@ -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 };
@@ -152,6 +186,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

@@ -34,6 +34,9 @@ export declare class Store {
     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;

package/dist/store.js

@@ -11,6 +11,16 @@ export class Store {
     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 });
@@ -48,6 +58,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 +82,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);

package/package.json

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