@sigrun/sigrun 0.7.0 → 0.9.0

package/dist/notices/service.js

@@ -0,0 +1,297 @@
+/**
+ * The notices service (notices Task 3, spec §2/§4): the one mediation
+ * point between the store files and every caller — the extension-facing
+ * `host.notices` surface (via the host bridge), the HTTP routes (Task
+ * 4), and the user-removal path (`removeUser`).
+ *
+ * Responsibilities the store deliberately does NOT own:
+ *
+ *  - access: a post's recipient must exist, and every conversation the
+ *    notice names (`conversationId`, plus any `navigate` action's
+ *    conversation target) must be visible to that user — the service's
+ *    `visible` dep answers for an ARBITRARY directory user
+ *    (`visibleToUser`), because the posting extension is never the
+ *    recipient;
+ *  - the declared-handler gate: an `extension` action's `name` must be
+ *    declared in the posting extension's `noticeActions` (the loader's
+ *    bindings are the registry);
+ *  - the `notice.changed` feed: the store's `NoticeChange` becomes the
+ *    hub event (`NoticeChangedInternal` — the wire shape plus the user);
+ *  - visibility pruning on the user read: `listForUser` re-checks every
+ *    conversation notice against the CURRENT share state and removes the
+ *    ones the user can no longer see (a revoked share never leaves the
+ *    name behind — spec §3 "Lost access");
+ *  - action dispatch (`runAction`): the surface-action primitives
+ *    (per-principal rate limit, requestId dedup, the 10 s timeout),
+ *    the notice lookup, and the clear-on-ok rule.
+ *
+ * The per-user store cache (`stores` map) exists because constructing a
+ * `NoticeStore` is closure-allocation over ONE user area; the store
+ * itself caches nothing (every op reads the file under the area mutex),
+ * so a stale cache entry can never serve stale data. `removeUser` both
+ * evicts the entry and removes the file (spec §3.2 rule 8: the user
+ * area stays for the workspace's recipient, so the notices file —
+ * personal, never transferred — goes on its own).
+ */
+import { ACTION_TIMEOUT_MS } from "../server/surfaces/service.js";
+import { ActionDedup } from "../server/surfaces/dedup.js";
+import { ActionRateLimit } from "../server/surfaces/rate-limit.js";
+import { NoticeStore } from "./store.js";
+import { validateNoticeInput } from "./validate.js";
+export class NoticesService {
+    deps;
+    stores = new Map();
+    dedup = new ActionDedup();
+    rateLimit = new ActionRateLimit();
+    actionTimeoutMs;
+    constructor(deps, options) {
+        this.deps = deps;
+        this.actionTimeoutMs = options?.actionTimeoutMs ?? ACTION_TIMEOUT_MS;
+    }
+    /**
+     * Post one notice as `owner` (the calling extension's slug): shape
+     * validation plus the declared-handler gate, then the access checks
+     * (unknown user; an invisible conversation or navigate target), then
+     * the store write. Throws `Error("<field>: <message>")` on any
+     * rejection — the fail-loud posture.
+     */
+    async post(owner, input) {
+        const declared = this.declaredHandlers(owner);
+        const validation = validateNoticeInput(input, declared);
+        if (!validation.ok) {
+            throw new Error(`${validation.field}: ${validation.message}`);
+        }
+        const notice = validation.value;
+        const record = this.deps.opened.identity.users.get(notice.user);
+        if (record === undefined) {
+            throw new Error(`user: unknown user "${notice.user}"`);
+        }
+        if (notice.conversationId !== undefined &&
+            !(await this.deps.visible(notice.conversationId, notice.user))) {
+            throw new Error(`conversationId: conversation ${notice.conversationId} not visible to user "${notice.user}"`);
+        }
+        for (const [index, action] of (notice.actions ?? []).entries()) {
+            if (action.kind !== "navigate" || !("conversation" in action.target)) {
+                continue;
+            }
+            const target = action.target.conversation;
+            if (!(await this.deps.visible(target, notice.user))) {
+                throw new Error(`actions[${index}].target: conversation ${target} not visible to user "${notice.user}"`);
+            }
+        }
+        const posted = await this.storeFor(notice.user).post(owner, notice);
+        return { id: posted.id };
+    }
+    /**
+     * The calling extension's own clear: by (user, key) or (user, id),
+     * always owner-scoped — another extension's notice is never touched.
+     */
+    async clear(owner, selector) {
+        const store = this.storeFor(selector.user);
+        if ("key" in selector) {
+            await store.clearByKey(owner, selector.key);
+        }
+        else {
+            await store.clearById(owner, selector.id);
+        }
+    }
+    /** The calling extension's own notices for `user` (owner-scoped read). */
+    async listForExtension(owner, user) {
+        const notices = await this.storeFor(user).list();
+        return notices.filter((notice) => notice.owner === owner);
+    }
+    /**
+     * The user's own read (the GET route's source): every notice, minus
+     * any conversation notice whose conversation the user can no longer
+     * see — those are removed from the file on the same read (spec §3).
+     */
+    async listForUser(user) {
+        const store = this.storeFor(user);
+        const notices = await store.list();
+        const lost = [];
+        for (const notice of notices) {
+            if (notice.conversationId === undefined)
+                continue;
+            if (!(await this.deps.visible(notice.conversationId, user))) {
+                lost.push(notice.id);
+            }
+        }
+        if (lost.length === 0)
+            return notices;
+        for (const id of lost)
+            await store.dismiss(id);
+        const lostSet = new Set(lost);
+        return notices.filter((notice) => !lostSet.has(notice.id));
+    }
+    /** Dismiss one of the user's notices; `false` when absent. */
+    async dismiss(user, id) {
+        return await this.storeFor(user).dismiss(id);
+    }
+    /** Dismiss everything of the user's. */
+    async dismissAll(user) {
+        await this.storeFor(user).dismissAll();
+    }
+    /** Remove one conversation's notices for `user` (app-wide ones stay). */
+    async clearConversationFor(user, conversationId) {
+        await this.storeFor(user).clearConversation(conversationId);
+    }
+    /**
+     * Run one notice's `extension` action (spec §4). The notice must
+     * belong to the principal's user (404 otherwise — a foreign id never
+     * reveals existence); the action must be a declared `extension`
+     * action on it (400); the handler must be loaded right now (409);
+     * per-principal rate limit (429). The handler runs under the 10 s
+     * action timeout; on `ok` the notice clears unless `keep: true`.
+     */
+    async runAction(principal, id, actionId, requestId) {
+        const user = principal.user;
+        // 1. Rate-limit: per PRINCIPAL across all notices (spec §4). A
+        //    user-less principal's bucket is the empty string — a
+        //    service-token caller gets rate-limited like any other.
+        if (!this.rateLimit.take("notices", "actions", user ?? "")) {
+            return { status: 429, body: { error: "rate_limited" } };
+        }
+        // 2. Dedup BEFORE the notice lookup (an ok:true handler dismisses
+        //    the notice, so a retry must still replay the FIRST result).
+        //    The composite carries the user: one user's requestId never
+        //    replays another user's result.
+        const composite = `notice\u0001${user ?? ""}\u0001${id}\u0001${actionId}`;
+        if (requestId !== undefined) {
+            const hit = this.dedup.check(requestId, composite, actionId);
+            if (hit !== undefined && hit !== null) {
+                return { status: 200, body: hit.result };
+            }
+        }
+        // 3. The notice lookup (foreign / unknown / user-less → 404, never
+        //    403 — a foreign id never reveals existence).
+        if (user === undefined) {
+            return { status: 404, body: { error: "notice_not_found" } };
+        }
+        const notice = await this.storeFor(user).get(id);
+        if (notice === undefined) {
+            return { status: 404, body: { error: "notice_not_found" } };
+        }
+        // 4. The action find: missing or not kind:"extension" → 400.
+        const action = notice.actions?.find((entry) => entry.id === actionId && entry.kind === "extension");
+        if (action === undefined) {
+            return { status: 400, body: { error: "unknown_action" } };
+        }
+        // 5. The binding find (the owning extension's declared handlers).
+        const handler = this.deps.opened.noticeActionBindings.find((binding) => binding.extension === notice.owner)?.actions[action.name];
+        if (handler === undefined) {
+            return { status: 409, body: { error: "notice_action_unavailable" } };
+        }
+        // 6. The handler call, racing the action timeout.
+        const payload = action.payload ?? {};
+        const controller = new AbortController();
+        const result = await this.invokeWithTimeout(() => handler({ principal, notice, signal: controller.signal }, payload), controller);
+        if (result.ok && result.keep !== true) {
+            await this.storeFor(user).dismiss(notice.id);
+        }
+        const body = result.ok === true
+            ? {
+                ok: true,
+                ...(result.message === undefined ? {} : { message: result.message }),
+                ...(result.navigate === undefined
+                    ? {}
+                    : { navigate: result.navigate }),
+            }
+            : result;
+        if (requestId !== undefined) {
+            this.dedup.record(requestId, composite, actionId, body);
+        }
+        return { status: 200, body };
+    }
+    /**
+     * User deletion: remove the user's notices file, then evict the cached
+     * store (spec §3.2 rule 8). No change event — the user the events
+     * would address is gone.
+     */
+    async removeUser(user) {
+        // The cached store when present, else a throwaway one: the removal
+        // needs only the file path, and caching a store for a user who no
+        // longer exists would be waste.
+        const store = this.stores.get(user) ?? this.createStore(user);
+        await store.removeFile();
+        this.stores.delete(user);
+    }
+    /** Test seam: disable (or re-enable) the action rate limiter. */
+    setRateLimitDisabled(disabled) {
+        this.rateLimit.setDisabled(disabled);
+    }
+    /** The handler names `owner` declared in its `noticeActions`. */
+    declaredHandlers(owner) {
+        const binding = this.deps.opened.noticeActionBindings.find((entry) => entry.extension === owner);
+        return new Set(Object.keys(binding?.actions ?? {}));
+    }
+    /** The cached per-user store, constructed on first use. */
+    storeFor(user) {
+        const cached = this.stores.get(user);
+        if (cached !== undefined)
+            return cached;
+        const store = this.createStore(user);
+        this.stores.set(user, store);
+        return store;
+    }
+    /** One fresh per-user store (never cached — `storeFor` caches). */
+    createStore(user) {
+        return new NoticeStore({
+            userArea: this.deps.userArea(user),
+            user,
+            userCreatedAt: () => this.deps.opened.identity.users.get(user)?.createdAt,
+            now: this.deps.now,
+            onChange: (change) => {
+                // The hub copy carries the user (NoticeChangedInternal); the
+                // events route strips it before delivery (spec §4).
+                const event = {
+                    type: "notice.changed",
+                    user: change.user,
+                    ids: change.ids,
+                    change: change.change,
+                };
+                this.deps.publish(event);
+            },
+            log: this.deps.log,
+        });
+    }
+    /**
+     * Race the handler against the 10 s action timeout (spec §4): on a
+     * timeout the handler is abandoned (its late settlement is dropped)
+     * and the action answers the `timed out` failure, the notice stays.
+     */
+    async invokeWithTimeout(invoke, controller) {
+        let timer;
+        try {
+            const outcome = await Promise.race([
+                invoke().then((result) => ({
+                    kind: "done",
+                    result,
+                }), (cause) => ({
+                    kind: "threw",
+                    cause,
+                })),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve({ kind: "timedout" }), this.actionTimeoutMs);
+                }),
+            ]);
+            if (outcome.kind === "timedout") {
+                return { ok: false, error: { message: "timed out" } };
+            }
+            if (outcome.kind === "threw") {
+                const cause = outcome.cause;
+                return {
+                    ok: false,
+                    error: {
+                        message: cause instanceof Error ? cause.message : String(cause),
+                    },
+                };
+            }
+            return outcome.result;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            controller.abort();
+        }
+    }
+}

package/dist/notices/store.js

@@ -0,0 +1,331 @@
+/**
+ * The per-user notice store (notices spec §3/§5): one `notices.json` per
+ * user area, `createdAt`-stamped, written atomically, and never trusted
+ * on the way back in.
+ *
+ * The store is the ONLY writer of the file, and it is deliberately
+ * stateless: every operation reads the file under the module-level
+ * per-`userArea` mutex, so two store instances (a restarted process, a
+ * second server) sharing one area cannot lose each other's posts — the
+ * mutex spans the whole read-modify-write, not just the rename. The file
+ * itself is small (at most `NOTICE_LIMITS.perUser` entries), so the read
+ * is cheaper than the bookkeeping a cache would need to stay honest.
+ *
+ * Two things the store enforces that the shared validator does not:
+ *
+ *  - the three core-assigned fields (`id`, `owner`, `at`) are checked
+ *    here (UUID, extension slug, ISO instant) because
+ *    `validateNoticeShape` deliberately rebuilds its answer from the
+ *    input's validated fields only — a stored `id` is never its input;
+ *  - the `userCreatedAt` stamp: a file written for a previous directory
+ *    record of the same name (deleted and re-created) is discarded, the
+ *    belt to the explicit removal on user deletion.
+ *
+ * Load re-validation uses `validateNoticeShape` and NOT
+ * `validateNoticeInput`: a stored notice whose extension is disabled or
+ * unloaded must stay dismissible (spec §3), so the declared-handler gate
+ * belongs to the post path only.
+ *
+ * Change events are the service's `notice.changed` feed: every mutation
+ * is ONE atomic write, and the `onChange` calls for it fire afterwards,
+ * in the order the spec names — the cleared old notice, the evicted
+ * notices, then the posted new one.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { NOTICE_LIMITS } from "@sigrun/shared/notices";
+import { writeFileAtomic } from "../harness/stores.js";
+import { validateNoticeShape } from "./validate.js";
+/** The file format version; a different `v` reads as an empty file. */
+const FILE_VERSION = 1;
+/** A `randomUUID()` id: lowercase hex, version/variant nibbles unconstrained. */
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An extension slug (`slugifyName`'s alphabet, non-empty). */
+const OWNER_RE = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+/** The instant shape `Date#toISOString` writes. */
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/**
+ * userArea → the tail of that area's mutation chain. Module-level, so
+ * every `NoticeStore` over one area serializes against every other (the
+ * brief's per-`userArea` mutex), not just against itself.
+ */
+const queues = new Map();
+/**
+ * Run `section` under the user area's mutex: it starts only after the
+ * previous section settles (either way — a failed write must not wedge
+ * the chain), and the next waiter sees this section's tail. The returned
+ * promise carries `section`'s own settlement to its caller.
+ */
+function withUserAreaLock(userArea, section) {
+    const tail = queues.get(userArea) ?? Promise.resolve();
+    const run = tail.then(section, section);
+    queues.set(userArea, run.then(() => undefined, () => undefined));
+    return run;
+}
+/**
+ * The per-user notice store. Construct one per user; instances over one
+ * `userArea` share the mutation chain and therefore see each other's
+ * writes.
+ */
+export class NoticeStore {
+    options;
+    path;
+    /** The stamp-mismatch line is logged once per instance, not per read. */
+    stampWarned = false;
+    constructor(options) {
+        this.options = options;
+        this.path = join(options.userArea, "notices.json");
+    }
+    /** This user's notices, newest first. */
+    async list() {
+        return newestFirst(await this.readFile());
+    }
+    /** One notice by id, or `undefined`. */
+    async get(id) {
+        const notices = await this.readFile();
+        return notices.find((notice) => notice.id === id);
+    }
+    /**
+     * Post one notice from `owner`: a same-(owner, key) notice is replaced
+     * (the new notice mints a NEW id, so a stale click answers 404 rather
+     * than hitting newer content), then the caps evict, then the post is
+     * announced.
+     */
+    async post(owner, input) {
+        return await this.mutate((notices) => {
+            const working = [...notices];
+            const changes = [];
+            // 1. A same-(owner, key) replace removes the old notice first.
+            if (input.key !== undefined) {
+                const index = working.findIndex((notice) => notice.owner === owner && notice.key === input.key);
+                if (index !== -1) {
+                    const [replaced] = working.splice(index, 1);
+                    changes.push(this.change("cleared", [replaced.id]));
+                }
+            }
+            // 2. The new notice is appended (`id`/`owner`/`at` win over any
+            //    same-named input field — they are core-assigned). The instant
+            //    is read INSIDE the lock, so the file order and the `at` order
+            //    agree even when two posts race.
+            const notice = {
+                ...input,
+                id: randomUUID(),
+                owner,
+                at: this.options.now().toISOString(),
+            };
+            working.push(notice);
+            // 3. The caps evict, oldest first: this owner's, then the user's
+            //    across every extension. Both ride ONE cleared event.
+            const evicted = [];
+            while (working.filter((entry) => entry.owner === owner).length >
+                NOTICE_LIMITS.perExtension) {
+                const id = evictOldest(working, (entry) => entry.owner === owner);
+                if (id !== undefined)
+                    evicted.push(id);
+            }
+            while (working.length > NOTICE_LIMITS.perUser) {
+                const id = evictOldest(working, () => true);
+                if (id !== undefined)
+                    evicted.push(id);
+            }
+            if (evicted.length > 0)
+                changes.push(this.change("cleared", evicted));
+            // 4. The post is announced last.
+            changes.push(this.change("posted", [notice.id]));
+            return { value: notice, notices: working, changes };
+        });
+    }
+    /** Remove this owner's notice carrying `key`; returns the removed ids. */
+    async clearByKey(owner, key) {
+        return await this.remove((notice) => notice.owner === owner && notice.key === key);
+    }
+    /** Remove this owner's notice by id (the extension's own clear). */
+    async clearById(owner, id) {
+        return await this.remove((notice) => notice.owner === owner && notice.id === id);
+    }
+    /** The user dismisses one notice (any extension's); false when absent. */
+    async dismiss(id) {
+        const removed = await this.remove((notice) => notice.id === id);
+        return removed.length > 0;
+    }
+    /** The user dismisses everything; returns every removed id. */
+    async dismissAll() {
+        return await this.remove(() => true);
+    }
+    /** Remove the notices tied to one conversation (app-wide ones stay). */
+    async clearConversation(conversationId) {
+        return await this.remove((notice) => notice.conversationId === conversationId);
+    }
+    /**
+     * Remove the file outright (user deletion). No change event: the user
+     * the events would address is gone.
+     */
+    async removeFile() {
+        await withUserAreaLock(this.options.userArea, async () => {
+            await rm(this.path, { force: true });
+        });
+    }
+    /**
+     * Remove every notice `predicate` accepts, as one write and one
+     * `cleared` change. Returns the removed ids, newest first; nothing
+     * matched = no write and no change.
+     */
+    async remove(predicate) {
+        return await this.mutate((notices) => {
+            const removed = notices.filter(predicate);
+            if (removed.length === 0)
+                return { value: [] };
+            const ids = newestFirst(removed).map((notice) => notice.id);
+            return {
+                value: ids,
+                notices: notices.filter((notice) => !predicate(notice)),
+                changes: [this.change("cleared", ids)],
+            };
+        });
+    }
+    /** Run one read-modify-write under the area's mutex, then emit. */
+    async mutate(step) {
+        return await withUserAreaLock(this.options.userArea, async () => {
+            const mutation = step(await this.readFile());
+            if (mutation.notices !== undefined) {
+                await this.writeFile(mutation.notices);
+                for (const change of mutation.changes ?? [])
+                    this.options.onChange(change);
+            }
+            return mutation.value;
+        });
+    }
+    /** One atomic write (stage + rename), one file. */
+    async writeFile(notices) {
+        const file = {
+            v: FILE_VERSION,
+            userCreatedAt: this.options.userCreatedAt() ?? null,
+            notices,
+        };
+        await mkdir(dirname(this.path), { recursive: true });
+        // 0600: one user's messages, never shared state — the sandbox policy
+        // keeps the agent out of the user area, this is the belt.
+        await writeFileAtomic(this.path, `${JSON.stringify(file, null, "\t")}\n`, 0o600);
+    }
+    /**
+     * Read and re-validate the file. Every failure mode reads as an empty
+     * file (a missing one is simply empty) — the file is never trusted,
+     * and a notice system must not fail closed on its own storage.
+     */
+    async readFile() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            this.options.log(`notices: cannot read ${this.path}: ${String(error)}`);
+            return [];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            this.options.log(`notices: discarding ${this.path}: unparseable JSON (${String(error)})`);
+            return [];
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed) ||
+            parsed.v !== FILE_VERSION ||
+            !Array.isArray(parsed.notices)) {
+            this.options.log(`notices: discarding ${this.path}: not a version ${FILE_VERSION} notice file`);
+            return [];
+        }
+        const file = parsed;
+        // The stamp: a file written for a previous directory record of the
+        // same name (a deleted and re-created username) is void.
+        const stamped = file.userCreatedAt ?? null;
+        const current = this.options.userCreatedAt() ?? null;
+        if (stamped !== current) {
+            if (!this.stampWarned) {
+                this.stampWarned = true;
+                this.options.log(`notices: discarding ${this.path}: stamped for directory record ${String(stamped)}, current is ${String(current)}`);
+            }
+            return [];
+        }
+        const notices = [];
+        for (const entry of file.notices) {
+            const loaded = acceptEntry(entry);
+            if (!loaded.ok) {
+                this.options.log(`notices: dropped an entry in ${this.path}: ${loaded.reason}`);
+                continue;
+            }
+            notices.push(loaded.notice);
+        }
+        return notices;
+    }
+    change(change, ids) {
+        return { user: this.options.user, ids, change };
+    }
+}
+/**
+ * Accept one stored entry: the shared shape validation (no handler
+ * check), then the three core-assigned fields the shared validator never
+ * sees.
+ */
+function acceptEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        return { ok: false, reason: "not an object" };
+    }
+    const record = entry;
+    const shape = validateNoticeShape(record);
+    if (!shape.ok) {
+        return { ok: false, reason: `${shape.field}: ${shape.message}` };
+    }
+    const id = record.id;
+    if (typeof id !== "string" || !ID_RE.test(id)) {
+        return { ok: false, reason: "id: not a UUID" };
+    }
+    const owner = record.owner;
+    if (typeof owner !== "string" || !OWNER_RE.test(owner)) {
+        return { ok: false, reason: "owner: not an extension slug" };
+    }
+    const at = record.at;
+    if (typeof at !== "string" ||
+        !ISO_RE.test(at) ||
+        !Number.isFinite(Date.parse(at))) {
+        return { ok: false, reason: "at: not an ISO timestamp" };
+    }
+    return { ok: true, notice: { ...shape.value, id, owner, at } };
+}
+/** The notices newest first: by `at`, ties by file position (later = newer). */
+function newestFirst(notices) {
+    return notices
+        .map((notice, index) => ({ notice, index }))
+        .sort((left, right) => {
+        const byAt = Date.parse(right.notice.at) - Date.parse(left.notice.at);
+        return byAt !== 0 ? byAt : right.index - left.index;
+    })
+        .map((entry) => entry.notice);
+}
+/**
+ * Remove the OLDEST notice `match` accepts, in place (earliest `at`; ties
+ * keep the earliest file position), returning its id. `undefined` when
+ * nothing matched.
+ */
+function evictOldest(notices, match) {
+    let index = -1;
+    let oldest = Number.POSITIVE_INFINITY;
+    for (let position = 0; position < notices.length; position += 1) {
+        const notice = notices[position];
+        if (!match(notice))
+            continue;
+        const time = Date.parse(notice.at);
+        if (time < oldest) {
+            oldest = time;
+            index = position;
+        }
+    }
+    if (index === -1)
+        return undefined;
+    return notices.splice(index, 1)[0].id;
+}