@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/state/bindings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The binding store (spec §8.3): one row per chat, key → the
+ * conversation the chat is bound to. Persisted at
+ * `<stateDir>/gateway/bindings.json` through {@link JsonFile} (0600,
+ * atomic, serialized updates).
+ *
+ * `account` is always `default` in v1 (the multi-account slot the key
+ * reserves so keys never need migrating); a thread rides its own key
+ * segment. `previous` records every conversation the chat was bound to
+ * before the current one (`/new` and rebinds append) — the outbound
+ * side never reads it today, but `/status` (Task 7) shows it and the
+ * array is the honest history a rebind loses otherwise.
+ */
+import type { ChatRef } from "@sigrun/sigrun/extension";
+/** One live binding: the chat → conversation edge. */
+export interface Binding {
+    readonly conversationId: number;
+    readonly chat: ChatRef;
+    /** Clock ms when the CURRENT conversation was bound. */
+    readonly boundAt: number;
+    /** Earlier conversation ids this chat was bound to, oldest first. */
+    readonly previous: readonly number[];
+    /** Set when delivery classified the chat gone (`chat_gone`). */
+    readonly dead?: boolean;
+}
+/** The binding key (§8.3): `<channel>:default:<chatType>:<chatId>[:threadId]`. */
+export declare function bindingKey(channel: string, chat: ChatRef): string;
+/**
+ * The chat → conversation bindings, one instance per engine. `bind` is
+ * the only mutator that grows `previous`; every method persists through
+ * the serialized JsonFile queue, so concurrent receives on the same
+ * chat never lose a rebind.
+ */
+export declare class BindingStore {
+    private readonly file;
+    /** The write-side clock (tests inject a fake; default real). */
+    private readonly now;
+    constructor(path: string, opts?: {
+        readonly now?: () => number;
+    });
+    /** The live binding for `key`, or undefined when unbound. */
+    get(key: string): Binding | undefined;
+    /** One file read's binding rows, keyed for target authorization. */
+    entries(): Readonly<Record<string, Binding>>;
+    /** Every live key bound to `conversationId` (the delivery fan-out read). */
+    keysOf(conversationId: number): readonly string[];
+    /** Bind `key` to `conversationId`, recording any prior binding in `previous`. */
+    bind(key: string, conversationId: number, chat: ChatRef): Promise<void>;
+    /** Remove the binding entirely (the access-revoked path). */
+    unbind(key: string): Promise<void>;
+    /** Mark the binding dead (`chat_gone` delivery): kept, never delivered to. */
+    markDead(key: string): Promise<void>;
+    /** Clear the dead flag (a new inbound event proves the chat alive). */
+    clearDead(key: string): Promise<void>;
+}

package/dist/state/bindings.js

@@ -0,0 +1,128 @@
+/**
+ * The binding store (spec §8.3): one row per chat, key → the
+ * conversation the chat is bound to. Persisted at
+ * `<stateDir>/gateway/bindings.json` through {@link JsonFile} (0600,
+ * atomic, serialized updates).
+ *
+ * `account` is always `default` in v1 (the multi-account slot the key
+ * reserves so keys never need migrating); a thread rides its own key
+ * segment. `previous` records every conversation the chat was bound to
+ * before the current one (`/new` and rebinds append) — the outbound
+ * side never reads it today, but `/status` (Task 7) shows it and the
+ * array is the honest history a rebind loses otherwise.
+ */
+import { JsonFile } from "./json-file.js";
+/** The binding key (§8.3): `<channel>:default:<chatType>:<chatId>[:threadId]`. */
+export function bindingKey(channel, chat) {
+    const base = `${channel}:default:${chat.chatType}:${chat.chatId}`;
+    return chat.threadId === undefined
+        ? base
+        : `${base}:${chat.threadId}`;
+}
+/**
+ * The chat → conversation bindings, one instance per engine. `bind` is
+ * the only mutator that grows `previous`; every method persists through
+ * the serialized JsonFile queue, so concurrent receives on the same
+ * chat never lose a rebind.
+ */
+export class BindingStore {
+    file;
+    /** The write-side clock (tests inject a fake; default real). */
+    now;
+    constructor(path, opts = {}) {
+        this.file = new JsonFile(path, () => ({
+            bindings: {},
+        }));
+        this.now = opts.now ?? Date.now;
+    }
+    /** The live binding for `key`, or undefined when unbound. */
+    get(key) {
+        // Read the file synchronously per call. ONE instance is threaded
+        // engine-wide now, so a construction-time mirror COULD suffice — but
+        // the reads are cheap local JSON and the per-call read keeps the
+        // store honest against EXTERNAL writers (a crash-recovery e2e or an
+        // operator repairing bindings.json between calls) and against any
+        // future second instance. The mirror was REMOVED precisely because
+        // it went stale across instances; readSync is the fix that stays.
+        return toBinding(this.file.readSync().bindings[key]);
+    }
+    /** One file read's binding rows, keyed for target authorization. */
+    entries() {
+        return Object.fromEntries(Object.entries(this.file.readSync().bindings).map(([key, row]) => [
+            key,
+            toBinding(row),
+        ]));
+    }
+    /** Every live key bound to `conversationId` (the delivery fan-out read). */
+    keysOf(conversationId) {
+        const keys = [];
+        for (const [key, row] of Object.entries(this.file.readSync().bindings)) {
+            if (row.conversationId === conversationId)
+                keys.push(key);
+        }
+        return keys;
+    }
+    /** Bind `key` to `conversationId`, recording any prior binding in `previous`. */
+    async bind(key, conversationId, chat) {
+        await this.file.update((draft) => {
+            const prior = draft.bindings[key];
+            if (prior === undefined) {
+                draft.bindings[key] = {
+                    conversationId,
+                    chat,
+                    boundAt: this.now(),
+                    previous: [],
+                };
+            }
+            else {
+                draft.bindings[key] = {
+                    conversationId,
+                    chat,
+                    boundAt: this.now(),
+                    previous: [
+                        ...prior.previous.filter((id) => id !== conversationId),
+                        prior.conversationId,
+                    ],
+                    ...(prior.dead === undefined ? {} : { dead: prior.dead }),
+                };
+            }
+        });
+    }
+    /** Remove the binding entirely (the access-revoked path). */
+    async unbind(key) {
+        await this.file.update((draft) => {
+            delete draft.bindings[key];
+        });
+    }
+    /** Mark the binding dead (`chat_gone` delivery): kept, never delivered to. */
+    async markDead(key) {
+        await this.file.update((draft) => {
+            const row = draft.bindings[key];
+            if (row === undefined)
+                return;
+            draft.bindings[key] = { ...row, dead: true };
+        });
+    }
+    /** Clear the dead flag (a new inbound event proves the chat alive). */
+    async clearDead(key) {
+        await this.file.update((draft) => {
+            const row = draft.bindings[key];
+            if (row === undefined || row.dead === undefined)
+                return;
+            const { dead: _dead, ...rest } = row;
+            draft.bindings[key] = rest;
+        });
+    }
+}
+/** Narrow a stored row to the public binding shape. */
+function toBinding(row) {
+    if (row === undefined)
+        return undefined;
+    return {
+        conversationId: row.conversationId,
+        chat: row.chat,
+        boundAt: row.boundAt,
+        previous: [...row.previous],
+        ...(row.dead === undefined ? {} : { dead: row.dead }),
+    };
+}

package/dist/state/identities.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Sender identity resolution (spec §8.2): core owns the link table;
+ * this store owns only per-user home chats in `identities.json`.
+ *
+ * Resolution order for `userFor`: the channel's ALLOWLIST first, then
+ * `host.accounts.lookup("chat:<channel>", senderId)`. An allowlist hit
+ * deliberately performs no core lookup: it is the operator's pinned
+ * mapping, and any disagreeing core link remains inert.
+ */
+import type { ChatRef, SigrunHost } from "@sigrun/sigrun/extension";
+import type { ChannelConfig } from "../config.js";
+import type { EngineLog } from "../log.js";
+/** How a chat link came to be. */
+export type LinkVia = "pairing" | "self";
+/** Core's one provider-key convention for platform senders. */
+export declare function chatProviderOf(channel: string): string;
+/**
+ * Core admits only this channel-id shape inside a chat provider. This
+ * matches the loader's grammar exactly: every binding-key and target
+ * parse splits on ":", so a wider alphabet would mis-attribute chats.
+ */
+export declare const CHANNEL_ID_PATTERN: RegExp;
+/** The result of a `userFor` resolution. */
+export interface ResolvedUser {
+    readonly user: string;
+    /** Whether the allowlist (not a link) produced the user. */
+    readonly via: "allow" | "link";
+}
+/** The result of a core-backed link attempt. */
+export type LinkResult = {
+    readonly linked: true;
+} | {
+    readonly linked: false;
+    readonly reason: "conflict";
+};
+/** Core-backed sender resolution and engine-owned home-chat persistence. */
+export declare class IdentityStore {
+    private readonly host;
+    private readonly file;
+    private homes;
+    constructor(host: SigrunHost, path: string, opts?: {
+        readonly log?: EngineLog;
+    });
+    /** Resolve the allowlist first; only an unlisted sender reads core. */
+    userFor(config: ChannelConfig, channel: string, senderId: string): Promise<ResolvedUser | undefined>;
+    /** Link through core; only core's conflict refusal maps to a result. */
+    link(channel: string, senderId: string, user: string, via: LinkVia, dmChat: ChatRef): Promise<LinkResult>;
+    /** Core removes links before userDeleted; the engine clears homes only. */
+    forgetHomes(user: string): Promise<void>;
+    /** The user's home chats, one per channel. */
+    homesOf(user: string): readonly {
+        channel: string;
+        chat: ChatRef;
+    }[];
+    /** Install an absent home without an await before the mirror update,
+     * preserving admission order. The durable write is queued behind the
+     * synchronous in-memory update; the caller owns its completion/error. */
+    ensureHome(user: string, channel: string, chat: ChatRef): Promise<void>;
+    /** Set (move) the user's home chat on `channel`. */
+    setHome(user: string, channel: string, chat: ChatRef): Promise<void>;
+    /** Refresh the home mirror from the written state (post-mutation). */
+    private reload;
+    /** Preserve an absent home without touching its durable file. */
+    private rememberHome;
+}

package/dist/state/identities.js

@@ -0,0 +1,135 @@
+/**
+ * Sender identity resolution (spec §8.2): core owns the link table;
+ * this store owns only per-user home chats in `identities.json`.
+ *
+ * Resolution order for `userFor`: the channel's ALLOWLIST first, then
+ * `host.accounts.lookup("chat:<channel>", senderId)`. An allowlist hit
+ * deliberately performs no core lookup: it is the operator's pinned
+ * mapping, and any disagreeing core link remains inert.
+ */
+import { JsonFile } from "./json-file.js";
+/** Core's one provider-key convention for platform senders. */
+export function chatProviderOf(channel) {
+    return `chat:${channel}`;
+}
+/**
+ * Core admits only this channel-id shape inside a chat provider. This
+ * matches the loader's grammar exactly: every binding-key and target
+ * parse splits on ":", so a wider alphabet would mis-attribute chats.
+ */
+export const CHANNEL_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Core-backed sender resolution and engine-owned home-chat persistence. */
+export class IdentityStore {
+    host;
+    file;
+    homes = {};
+    constructor(host, path, opts = {}) {
+        this.host = host;
+        this.file = new JsonFile(path, () => ({ homes: {} }));
+        // Home reads are synchronous by contract; load the mirror before
+        // admitting work, as the other engine-owned JsonFile stores do.
+        const state = this.file.readSync();
+        this.homes = state.homes;
+        const legacyCount = Object.keys(state.links ?? {}).length;
+        if (legacyCount > 0) {
+            opts.log?.warn(`identities.json contains ${legacyCount} legacy links; those senders must pair or self-link again`);
+        }
+    }
+    /** Resolve the allowlist first; only an unlisted sender reads core. */
+    async userFor(config, channel, senderId) {
+        const allowed = config.allow.find((entry) => entry.sender === senderId)?.user;
+        if (allowed !== undefined)
+            return { user: allowed, via: "allow" };
+        const linked = await this.host.accounts.lookup(chatProviderOf(channel), senderId);
+        return linked === undefined ? undefined : { user: linked.user, via: "link" };
+    }
+    /** Link through core; only core's conflict refusal maps to a result. */
+    async link(channel, senderId, user, via, dmChat) {
+        try {
+            await this.host.accounts.link(chatProviderOf(channel), senderId, user, via);
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.startsWith("account_link_conflict:")) {
+                return { linked: false, reason: "conflict" };
+            }
+            throw error;
+        }
+        try {
+            await this.file.update((draft) => {
+                delete draft.links;
+                // First link sets the home chat (a later /home moves it).
+                if (draft.homes[user]?.[channel] === undefined) {
+                    const perChannel = draft.homes[user] ?? {};
+                    perChannel[channel] = { chat: dmChat };
+                    draft.homes[user] = perChannel;
+                }
+            }).then((state) => this.reload(state));
+        }
+        catch (error) {
+            // Core has already durably linked the sender. Preserve this
+            // absent home in memory before rethrowing so homesOf and a
+            // same-user retry do not pretend the first link never happened;
+            // the next successful write persists it.
+            this.rememberHome(user, channel, dmChat);
+            throw error;
+        }
+        return { linked: true };
+    }
+    /** Core removes links before userDeleted; the engine clears homes only. */
+    async forgetHomes(user) {
+        await this.file.update((draft) => {
+            delete draft.links;
+            delete draft.homes[user];
+        }).then((state) => this.reload(state));
+    }
+    /** The user's home chats, one per channel. */
+    homesOf(user) {
+        const perChannel = this.homes[user];
+        if (perChannel === undefined)
+            return [];
+        return Object.entries(perChannel).map(([channel, row]) => ({
+            channel,
+            chat: row.chat,
+        }));
+    }
+    /** Install an absent home without an await before the mirror update,
+     * preserving admission order. The durable write is queued behind the
+     * synchronous in-memory update; the caller owns its completion/error. */
+    ensureHome(user, channel, chat) {
+        if (this.homes[user]?.[channel] !== undefined)
+            return Promise.resolve();
+        const perChannel = this.homes[user] ?? {};
+        perChannel[channel] = { chat };
+        this.homes[user] = perChannel;
+        return this.file.update((draft) => {
+            delete draft.links;
+            if (draft.homes[user]?.[channel] !== undefined)
+                return;
+            const stored = draft.homes[user] ?? {};
+            stored[channel] = { chat };
+            draft.homes[user] = stored;
+        }).then(() => undefined);
+    }
+    /** Set (move) the user's home chat on `channel`. */
+    async setHome(user, channel, chat) {
+        await this.file.update((draft) => {
+            delete draft.links;
+            const perChannel = draft.homes[user] ?? {};
+            perChannel[channel] = { chat };
+            draft.homes[user] = perChannel;
+        }).then((state) => this.reload(state));
+    }
+    /** Refresh the home mirror from the written state (post-mutation). */
+    reload(state) {
+        this.homes = state.homes;
+    }
+    /** Preserve an absent home without touching its durable file. */
+    rememberHome(user, channel, chat) {
+        if (this.homes[user]?.[channel] !== undefined)
+            return;
+        const perChannel = this.homes[user] ?? {};
+        perChannel[channel] = { chat };
+        this.homes[user] = perChannel;
+    }
+}

package/dist/state/json-file.d.ts

@@ -0,0 +1,64 @@
+/**
+ * JsonFile<T> — the engine's state-file primitive (spec §8.0: state
+ * lives in `<stateDir>/gateway/`, core never reads or writes it).
+ *
+ * - serialized updates: every `update` runs read → mutate → write inside
+ *   ONE queue position, so concurrent updates interleave never (a
+ *   lost-update on a state file would silently drop links/bindings);
+ * - atomic write: staged temp + rename in the same directory (a crash or
+ *   concurrent reader sees the old complete file or the new complete
+ *   file, never a half-written one);
+ * - mode 0600: state carries identity links, so group/other read is off;
+ * - malformed file THROWS naming the path — a corrupt state file is
+ *   never silently reset by the next write (the sigrun stores contract).
+ */
+/** A serialized JSON state file at `path`. */
+export declare class JsonFile<T> {
+    private readonly path;
+    private readonly initial;
+    private queue;
+    constructor(path: string, initial: () => T);
+    /** Read the file (absent → the initial value; malformed → throws naming the path). */
+    read(): Promise<T>;
+    /**
+     * The synchronous read: the same semantics as {@link read} (absent →
+     * the initial value; malformed → throws naming the path) without the
+     * queue. Stores whose READ API is synchronous (the binding/identity
+     * reads the plan pins) load at construction this way — the queue is
+     * empty then, so nothing can interleave; a queued write's own state
+     * tracking refreshes the store's mirror afterward.
+     */
+    readSync(): T;
+    /**
+     * Read-modify-write under the serialization queue: the mutator runs
+     * on the CURRENT state, the result is written atomically, and the new
+     * state returns. A throwing mutator leaves the file untouched.
+     */
+    update(mutate: (draft: T) => void | Promise<void>): Promise<T>;
+    /**
+     * The SYNCHRONOUS read-modify-write, mirroring {@link readSync}'s
+     * contract for stores whose mutation API is synchronous by interface
+     * (the pairing queue: `request` returns its verdict immediately, so
+     * the durable write must land before the verdict — a crash between
+     * them would silently lose a pending request). The queue is bypassed
+     * (the callers own the ordering: sync mutations cannot interleave).
+     */
+    updateSync(mutate: (draft: T) => void): T;
+    /** Run `work` after every earlier queued operation (the serialization). */
+    private enqueue;
+    private readNow;
+    /**
+     * Atomic replace: stage to a fresh temp file in the target's directory
+     * (rename is same-filesystem atomic), stamp 0600 on the temp BEFORE
+     * the rename (chmod beats `writeFile`'s umask-masked `mode`), then
+     * rename over the target. The parent dir is created when absent —
+     * the engine's start creates the state dir, but a JsonFile handed a
+     * deeper path stays usable on a fresh deployment.
+     */
+    private writeNow;
+    /**
+     * The sync twin of {@link writeNow}: the SAME atomic staging (temp +
+     * rename, 0600 before the swap) through the blocking fs calls.
+     */
+    private writeNowSync;
+}

package/dist/state/json-file.js

@@ -0,0 +1,156 @@
+/**
+ * JsonFile<T> — the engine's state-file primitive (spec §8.0: state
+ * lives in `<stateDir>/gateway/`, core never reads or writes it).
+ *
+ * - serialized updates: every `update` runs read → mutate → write inside
+ *   ONE queue position, so concurrent updates interleave never (a
+ *   lost-update on a state file would silently drop links/bindings);
+ * - atomic write: staged temp + rename in the same directory (a crash or
+ *   concurrent reader sees the old complete file or the new complete
+ *   file, never a half-written one);
+ * - mode 0600: state carries identity links, so group/other read is off;
+ * - malformed file THROWS naming the path — a corrupt state file is
+ *   never silently reset by the next write (the sigrun stores contract).
+ */
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+/** A serialized JSON state file at `path`. */
+export class JsonFile {
+    path;
+    initial;
+    queue = Promise.resolve();
+    constructor(path, initial) {
+        this.path = path;
+        this.initial = initial;
+    }
+    /** Read the file (absent → the initial value; malformed → throws naming the path). */
+    read() {
+        return this.enqueue(async () => this.readNow());
+    }
+    /**
+     * The synchronous read: the same semantics as {@link read} (absent →
+     * the initial value; malformed → throws naming the path) without the
+     * queue. Stores whose READ API is synchronous (the binding/identity
+     * reads the plan pins) load at construction this way — the queue is
+     * empty then, so nothing can interleave; a queued write's own state
+     * tracking refreshes the store's mirror afterward.
+     */
+    readSync() {
+        let text;
+        try {
+            text = readFileSync(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return this.initial();
+            }
+            throw error;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`gateway: malformed JSON in ${this.path}: ${String(error)}`, { cause: error });
+        }
+    }
+    /**
+     * Read-modify-write under the serialization queue: the mutator runs
+     * on the CURRENT state, the result is written atomically, and the new
+     * state returns. A throwing mutator leaves the file untouched.
+     */
+    update(mutate) {
+        return this.enqueue(async () => {
+            const draft = await this.readNow();
+            await mutate(draft);
+            await this.writeNow(draft);
+            return draft;
+        });
+    }
+    /**
+     * The SYNCHRONOUS read-modify-write, mirroring {@link readSync}'s
+     * contract for stores whose mutation API is synchronous by interface
+     * (the pairing queue: `request` returns its verdict immediately, so
+     * the durable write must land before the verdict — a crash between
+     * them would silently lose a pending request). The queue is bypassed
+     * (the callers own the ordering: sync mutations cannot interleave).
+     */
+    updateSync(mutate) {
+        const draft = this.readSync();
+        mutate(draft);
+        this.writeNowSync(draft);
+        return draft;
+    }
+    /** Run `work` after every earlier queued operation (the serialization). */
+    enqueue(work) {
+        const next = this.queue.then(work, work);
+        // The queue only tracks completion order; a rejection must not
+        // poison later operations (they re-read the file for truth).
+        this.queue = next.catch(() => { });
+        return next;
+    }
+    async readNow() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return this.initial();
+            }
+            throw error;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`gateway: malformed JSON in ${this.path}: ${String(error)}`, { cause: error });
+        }
+    }
+    /**
+     * Atomic replace: stage to a fresh temp file in the target's directory
+     * (rename is same-filesystem atomic), stamp 0600 on the temp BEFORE
+     * the rename (chmod beats `writeFile`'s umask-masked `mode`), then
+     * rename over the target. The parent dir is created when absent —
+     * the engine's start creates the state dir, but a JsonFile handed a
+     * deeper path stays usable on a fresh deployment.
+     */
+    async writeNow(value) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const temp = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temp, `${JSON.stringify(value, null, "\t")}\n`, {
+                mode: 0o600,
+            });
+            await chmod(temp, 0o600);
+            await rename(temp, this.path);
+        }
+        catch (error) {
+            await rm(temp, { force: true }).catch(() => {
+                // Best-effort cleanup of the staged temp; the failure being
+                // handled is the original one.
+            });
+            throw error;
+        }
+    }
+    /**
+     * The sync twin of {@link writeNow}: the SAME atomic staging (temp +
+     * rename, 0600 before the swap) through the blocking fs calls.
+     */
+    writeNowSync(value) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const temp = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temp, `${JSON.stringify(value, null, "\t")}\n`, {
+                mode: 0o600,
+            });
+            chmodSync(temp, 0o600);
+            renameSync(temp, this.path);
+        }
+        catch (error) {
+            rmSync(temp, { force: true });
+            throw error;
+        }
+    }
+}