@timqi/pier 0.0.29 → 0.1.1

package/dist/web/push.js

@@ -1,71 +1,73 @@
-// Notifications for the workbench that is not on screen: which browsers asked
-// to be told, and the one rule that decides a push — a turn that finished and
-// that nobody looked at. The wire format is webpush.ts.
-//
-// The rule is deliberately the same one the sidebar's unread dot uses, read a
-// few seconds late: a client with that session visible acks immediately, so
-// "still unread when the dust settled" is precisely "nobody saw it". One rule,
-// one place — a second notion of attention would drift from the dot within a
-// release.
+// Notifications for the workbench that is not on screen. The rule is the
+// sidebar's unread dot, read a few seconds late: a client with the session
+// visible acks immediately, so "still unread" is precisely "nobody saw it".
+// The wire format is webpush.ts.
 import { readableTitle } from "../core/identity.js";
 import { pierDb } from "../db.js";
 import { logger } from "../log.js";
+import { isSealed } from "../secrets.js";
 import { sessionIdOf } from "./auth.js";
 import { generateVapidKeys, sendPush, } from "./webpush.js";
 const log = logger("push");
-/** Devices kept at once. A browser mints a new subscription whenever the old
- *  one expires, so the table grows by itself; the oldest rows are the ones
- *  already dead. */
+/** A browser mints a new subscription whenever the old one expires, so the
+ *  table grows by itself; the oldest rows are the dead ones. */
 const MAX_SUBSCRIPTIONS = 20;
-/** How long a finished turn waits for a client to say it was seen. Long enough
- *  to cross a heartbeat and a slow phone, short enough to still be a
- *  notification about something that just happened. */
+/** Long enough to cross a heartbeat and a slow phone. */
 const SETTLE_MS = 6_000;
 const MAX_BODY_CHARS = 160;
-/** What to call the session where there is room for one line. The title is put
- *  through the same reader the sidebar uses — untouched, a session titled by
- *  its first prompt announces itself on the lock screen as
- *  `[operator<web> 12:01]`. Falls back to the project directory, then to the
- *  fact that it is a session at all: a notification with no title reads as a
- *  browser bug rather than as an unnamed session — and a listing that could
- *  not answer must not silence the push. */
+/** Untouched, a session titled by its first prompt announces itself as
+ *  `[operator<web> 12:01]`. Never empty: a notification with no title reads as
+ *  a browser bug, and a listing that could not answer must not silence the push. */
 const label = (s) => readableTitle(s?.title) || s?.cwd.split("/").filter(Boolean).at(-1) || "Pier session";
-/** SQLite's "that parent row does not exist" — the session ended. Anything
- *  else that goes wrong here is a broken database, not a signed-out browser. */
+/** SQLite's "that parent row does not exist": the session ended. */
 const FOREIGN_KEY_VIOLATION = 787;
 const sessionGone = (err) => err.errcode === FOREIGN_KEY_VIOLATION;
-/** Subscriptions and the instance's VAPID identity. Both are per-instance
- *  facts nobody edits by hand, so they live beside every other one. */
 export class PushStore {
+    secrets;
     #db;
-    constructor(db = pierDb()) {
+    /** Without `secrets` (tests), the private key persists as given. A locked
+     *  store throws rather than serving a key it cannot read. */
+    constructor(db = pierDb(), secrets) {
+        this.secrets = secrets;
         this.#db = db;
     }
-    /** The key pair every push is signed with, minted on first use. Losing it
-     *  would invalidate every subscription made with it, so it is created once
-     *  and never rotated on its own. */
+    /** Rotating it would invalidate every subscription made with it. */
     identity() {
         const row = this.#db
             .prepare("SELECT public_key AS publicKey, private_key AS privateKey FROM push_identity WHERE id = 1")
             .get();
         if (row)
-            return row;
+            return { ...row, privateKey: this.#unsealed(row.privateKey) };
         const keys = generateVapidKeys();
         this.#db
             .prepare("INSERT INTO push_identity(id, public_key, private_key, created_at) VALUES (1, ?, ?, ?)")
-            .run(keys.publicKey, keys.privateKey, Date.now());
+            .run(keys.publicKey, this.#sealed(keys.privateKey), Date.now());
         log.info("minted this instance's VAPID key pair");
         return keys;
     }
+    /** A key minted before sealing is honored once and sealed in place — the pair
+     *  cannot be replaced without invalidating every subscription. */
+    #unsealed(stored) {
+        if (!this.secrets)
+            return stored;
+        if (isSealed(stored))
+            return this.secrets.decrypt(stored);
+        this.#db.prepare("UPDATE push_identity SET private_key = ? WHERE id = 1")
+            .run(this.secrets.encrypt(stored));
+        log.info("sealed this instance's VAPID private key");
+        return stored;
+    }
+    #sealed(privateKey) {
+        return this.secrets ? this.secrets.encrypt(privateKey) : privateKey;
+    }
     list() {
         return this.#db
             .prepare(`SELECT endpoint, p256dh, auth, label, created_at AS createdAt
          FROM push_subscriptions ORDER BY created_at DESC`)
             .all();
     }
-    /** Upsert: a browser re-posts the same subscription on every load, which is
-     *  what repairs a row this instance lost — and what re-attaches one to the
-     *  session that is signed in now. */
+    /** Upsert: a browser re-posts on every load, which repairs a lost row and
+     *  re-attaches one to the session signed in now. */
     save(target, label, sessionId) {
         this.#db
             .prepare(`INSERT INTO push_subscriptions(endpoint, p256dh, auth, label, created_at, session_id)
@@ -84,13 +86,11 @@ export class PushStore {
             .run(endpoint).changes > 0;
     }
 }
-/** One line of what the agent said, for a notification shade. */
 const preview = (text) => {
     const line = text.replace(/```[\s\S]*?```/g, "…").replace(/\s+/g, " ").trim();
     return line.length > MAX_BODY_CHARS ? `${line.slice(0, MAX_BODY_CHARS - 1)}…` : line;
 };
-/** A subscription is only accepted in the exact shape the Push API produces;
- *  a half-valid one would fail later, inside a background send nobody watches. */
+/** A half-valid subscription would fail later, inside a send nobody watches. */
 function parseTarget(body) {
     const { endpoint, keys } = (body ?? {});
     const p256dh = keys?.p256dh;
@@ -117,15 +117,12 @@ function parseTarget(body) {
 }
 export function registerPushRoutes(app, deps) {
     const { store, hub, unread, channelOf, summary, publicUrl, settleMs = SETTLE_MS } = deps;
-    /** Who a push service should complain to. It has to be a mailto: or https:
-     *  URL or Apple rejects the token outright, so an instance that never had
-     *  its public URL set still needs an answer. */
+    /** Must be a mailto: or https: URL or Apple rejects the token outright. */
     const subject = () => {
         const url = publicUrl();
         return url.startsWith("https://") ? url : "mailto:pier@localhost";
     };
-    /** Send to every device, and prune the ones the service says are gone. A
-     *  failure is logged with what the service said — a notification that never
+    /** A failure is logged with what the service said: a notification that never
      *  arrives is otherwise indistinguishable from one nobody tapped. */
     async function deliver(payload) {
         const targets = store.list();
@@ -143,8 +140,7 @@ export function registerPushRoutes(app, deps) {
                 return;
             }
             failed += 1;
-            // 404/410 is the push service saying this subscription is dead for good
-            // — the only status that may cost a row.
+            // 404/410 is "dead for good", the only status that may cost a row.
             if (status === 404 || status === 410) {
                 store.remove(target.endpoint);
                 log.info(`dropped an expired subscription (${target.label})`);
@@ -155,12 +151,8 @@ export function registerPushRoutes(app, deps) {
         return { sent, failed };
     }
     // --- the trigger ----------------------------------------------------------------
-    // A session is watched only while it streams: the ring buffer of a session
-    // nobody watches is released on eviction (core/hub.ts), and a permanent
-    // subscriber would keep every one of them alive.
-    /** Per streaming session: stop watching, and hand back what the turn said.
-     *  The text lives in the watcher's own closure, so it cannot outlive the
-     *  subscription that collected it. */
+    // Watched only while streaming: a permanent subscriber would keep every
+    // session's ring buffer alive (core/hub.ts).
     const watching = new Map();
     hub.subscribeWorkspace((e) => {
         if (e.type !== "session-state")
@@ -169,9 +161,11 @@ export function registerPushRoutes(app, deps) {
             if (watching.has(e.sessionId))
                 return;
             let text = "";
+            // The last turn that said something: a run ends one turn per answer, and
+            // a silence after the answer would replace it with "Turn finished."
             const stop = hub.subscribe(e.sessionId, (ev) => {
                 if (ev.type === "turn-end")
-                    text = ev.text;
+                    text = ev.text || text;
             });
             watching.set(e.sessionId, () => {
                 stop();
@@ -179,20 +173,14 @@ export function registerPushRoutes(app, deps) {
             });
             return;
         }
-        // No start witnessed → a session that booted idle, not a finished turn.
         const finish = watching.get(e.sessionId);
         if (!finish)
             return;
         watching.delete(e.sessionId);
         const text = finish();
-        // The workbench's own sessions only. A turn that came from Slack, Telegram
-        // or Lark was already delivered to the chat it came from — the person has
-        // it, and their phone buzzing twice for one answer is what a notification
-        // budget gets spent on. Read now, not in the timer: this is the state that
-        // produced the turn.
-        // Every outcome says which one it was: a push that was never sent and one
-        // that arrived look identical from here otherwise, and "why did my phone
-        // stay quiet" is the only question this feature is ever asked (§5b).
+        // An IM turn was already delivered to its chat. Read now, not in the
+        // timer: this is the state that produced the turn. Every outcome is logged:
+        // "why did my phone stay quiet" is the only question this is asked (§5).
         const channel = channelOf(e.sessionId);
         if (channel !== "web") {
             log.debug(`no push for ${e.sessionId}: answering ${channel ?? "nothing"}, not the workbench`);
@@ -203,10 +191,7 @@ export function registerPushRoutes(app, deps) {
                 log.debug(`no push for ${e.sessionId}: a client reported the turn as seen`);
                 return; // somebody has it on screen
             }
-            // One async step before the send, so a failure in *either* half is
-            // reported: a notification nobody received and one nobody sent look
-            // identical from here, and "why did my phone stay quiet" is the only
-            // question this feature is ever asked (§5b).
+            // One async step before the send, so a failure in either half is reported.
             void (async () => {
                 await deliver({
                     title: label(await summary(e.sessionId)),
@@ -220,8 +205,6 @@ export function registerPushRoutes(app, deps) {
         timer.unref?.();
     });
     // --- routes ---------------------------------------------------------------------
-    // The key a browser subscribes with. Public by nature — it is what a push
-    // service checks our signature against.
     app.get("/api/push", (c) => c.json({ publicKey: store.identity().publicKey }));
     app.post("/api/push/subscribe", async (c) => {
         const body = await c.req.json().catch(() => null);
@@ -229,18 +212,14 @@ export function registerPushRoutes(app, deps) {
         if (!target)
             return c.json({ error: "not a push subscription" }, 400);
         const label = String(body.label ?? "a browser").slice(0, 80);
-        // The session that is asking owns the subscription, and the foreign key is
-        // what makes signing this browser out take the subscription with it. It can
-        // refuse: the boundary let this request in and the browser was signed out
-        // while its body was still arriving. Say so rather than 500 — the browser
-        // is about to be sent to the login form by its next request anyway.
+        // The foreign key can refuse: the browser was signed out while its body
+        // was still arriving. Say so rather than 500.
         try {
             store.save(target, label, sessionIdOf(c));
         }
         catch (err) {
-            // Only that. A full or read-only database answering 401 would send a
-            // signed-in browser to the login form, where the password it types will
-            // not help either.
+            // Only that: a full database answering 401 would send a signed-in browser
+            // to the login form.
             if (!sessionGone(err))
                 throw err;
             log.warn(`subscription refused for a session that ended: ${String(err)}`);
@@ -255,8 +234,7 @@ export function registerPushRoutes(app, deps) {
             return c.json({ error: "endpoint required" }, 400);
         return c.json({ removed: store.remove(endpoint) });
     });
-    // "Did that actually work?" — the only way to answer it on a phone, where a
-    // permission granted to the wrong context looks exactly like a granted one.
+    // On a phone, a permission granted to the wrong context looks like a granted one.
     app.post("/api/push/test", async (c) => {
         const { sent, failed } = await deliver({
             title: "Pier",

package/dist/web/route.js

@@ -1,10 +1,6 @@
-// A route body that throws answers as JSON — the one shape every view's
-// fetch helper already knows how to read, with the status the route owns.
-// It lives alone because all three route families use it and none of them is
-// where the other two would look for it.
-/** Register a route whose body may throw: the error becomes the JSON shape
- *  the UI expects, with the status the route owns. Takes the literal path so
- *  `c.req.param()` keeps its typed keys. */
+// A route body that throws answers as JSON, the shape every view's fetch
+// helper reads, with the status the route owns.
+/** Takes the literal path so `c.req.param()` keeps its typed keys. */
 export function guarded(app, method, path, status, fn) {
     app.on(method, path, async (c) => {
         try {