@sympoies/dsh-telegram 0.0.0-bootstrap.0 → 0.6.1

package/lib/access.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Who is allowed to drive the agent.
+ *
+ * This is the plugin's most security-sensitive decision. A Telegram bot is
+ * reachable by anyone who knows its handle, and the agent behind it can run
+ * shell commands on the operator's machine. So the default is closed: an
+ * unconfigured bot answers nobody until it is claimed once, with a code that
+ * is printed to the operator's own console and never sent over Telegram.
+ *
+ * Ownership is durable and single-shot. Once claimed, a later claim — even
+ * with the right code — is refused, so a code that leaks after the fact grants
+ * nothing.
+ */
+/** The three answers to "may this user talk to the agent?". */
+export type AccessDecision = 
+/** On the allowlist, or the recorded owner. */
+'allowed'
+/** Someone else owns this bot, or an allowlist excludes this user. */
+ | 'denied'
+/** Nobody owns the bot yet; this user may claim it with the code. */
+ | 'unclaimed';
+/** Construction options. */
+export interface AccessPolicyOptions {
+    /** Telegram user ids admitted without claiming. Empty enables the claim flow. */
+    readonly allowFrom: readonly number[];
+    /** The one-time code that transfers ownership; printed to the operator's console. */
+    readonly claimCode: string;
+    /**
+     * Where to also drop the claim code while the bot is unowned.
+     *
+     * The console is not always readable — a harness started detached, or a
+     * profile whose logger has no console sink, swallows it — and a claim code
+     * nobody can read makes the bot permanently unusable. The file is written
+     * owner-only and removed the moment the bot is claimed.
+     */
+    readonly claimCodeFile?: string;
+}
+export declare class AccessPolicy {
+    private readonly file;
+    private readonly options;
+    private ownerId;
+    private constructor();
+    /**
+     * Load recorded ownership, or start unowned.
+     *
+     * @param file - absolute path to the ownership record.
+     * @param options - allowlist and this process's claim code.
+     */
+    static open(file: string, options: AccessPolicyOptions): Promise<AccessPolicy>;
+    /**
+     * Decide whether a user may drive the agent.
+     *
+     * @param userId - the Telegram user id from the update.
+     */
+    check(userId: number): AccessDecision;
+    /** The recorded owner, when the bot has been claimed. */
+    owner(): number | undefined;
+    /**
+     * Take ownership of an unowned bot.
+     *
+     * @param userId - the claiming Telegram user.
+     * @param code - the code they supplied, from an untrusted message.
+     * @returns whether ownership was transferred.
+     */
+    claim(userId: number, code: string): Promise<boolean>;
+    /**
+     * Drop the claim code where the operator can read it, while it is still
+     * needed. Owner-only permissions: anyone who can read it can take the bot.
+     */
+    private publishClaimCode;
+    /** Remove the published code; it grants nothing now and should not linger. */
+    private retractClaimCode;
+    /** Record ownership atomically. */
+    private persist;
+}
+//# sourceMappingURL=access.d.ts.map

package/lib/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,+DAA+D;AAC/D,MAAM,MAAM,cAAc;AACxB,+CAA+C;AAC7C,SAAS;AACX,sEAAsE;GACpE,QAAQ;AACV,qEAAqE;GACnE,WAAW,CAAA;AAEf,4BAA4B;AAC5B,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,OAAO,CAAoB;IAEnC,OAAO;IAKP;;;;;OAKG;WACU,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IAOpF;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;IAQrC,yDAAyD;IACzD,KAAK,IAAI,MAAM,GAAG,SAAS;IAI3B;;;;;;OAMG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW3D;;;OAGG;YACW,gBAAgB;IAoB9B,8EAA8E;YAChE,gBAAgB;IAM9B,mCAAmC;YACrB,OAAO;CAQtB"}

package/lib/access.js

@@ -0,0 +1,137 @@
+/**
+ * Who is allowed to drive the agent.
+ *
+ * This is the plugin's most security-sensitive decision. A Telegram bot is
+ * reachable by anyone who knows its handle, and the agent behind it can run
+ * shell commands on the operator's machine. So the default is closed: an
+ * unconfigured bot answers nobody until it is claimed once, with a code that
+ * is printed to the operator's own console and never sent over Telegram.
+ *
+ * Ownership is durable and single-shot. Once claimed, a later claim — even
+ * with the right code — is refused, so a code that leaks after the fact grants
+ * nothing.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class AccessPolicy {
+    file;
+    options;
+    ownerId;
+    constructor(file, options) {
+        this.file = file;
+        this.options = options;
+    }
+    /**
+     * Load recorded ownership, or start unowned.
+     *
+     * @param file - absolute path to the ownership record.
+     * @param options - allowlist and this process's claim code.
+     */
+    static async open(file, options) {
+        const policy = new AccessPolicy(file, options);
+        policy.ownerId = await readOwner(file);
+        await policy.publishClaimCode();
+        return policy;
+    }
+    /**
+     * Decide whether a user may drive the agent.
+     *
+     * @param userId - the Telegram user id from the update.
+     */
+    check(userId) {
+        if (this.options.allowFrom.includes(userId))
+            return 'allowed';
+        if (this.ownerId === userId)
+            return 'allowed';
+        if (this.ownerId !== undefined)
+            return 'denied';
+        if (this.options.allowFrom.length > 0)
+            return 'denied';
+        return 'unclaimed';
+    }
+    /** The recorded owner, when the bot has been claimed. */
+    owner() {
+        return this.ownerId;
+    }
+    /**
+     * Take ownership of an unowned bot.
+     *
+     * @param userId - the claiming Telegram user.
+     * @param code - the code they supplied, from an untrusted message.
+     * @returns whether ownership was transferred.
+     */
+    async claim(userId, code) {
+        if (this.ownerId !== undefined)
+            return false;
+        if (this.options.allowFrom.length > 0)
+            return false;
+        if (!matches(code, this.options.claimCode))
+            return false;
+        this.ownerId = userId;
+        await this.persist();
+        await this.retractClaimCode();
+        return true;
+    }
+    /**
+     * Drop the claim code where the operator can read it, while it is still
+     * needed. Owner-only permissions: anyone who can read it can take the bot.
+     */
+    async publishClaimCode() {
+        const path = this.options.claimCodeFile;
+        if (path === undefined)
+            return;
+        if (this.ownerId !== undefined || this.options.allowFrom.length > 0) {
+            return await this.retractClaimCode();
+        }
+        try {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, `Send this to your bot to take ownership of it:\n\n    /claim ${this.options.claimCode}\n\n` +
+                `It changes on every restart, and this file disappears once the bot is claimed.\n`, { encoding: 'utf8', mode: 0o600 });
+        }
+        catch {
+            // Best effort: the log still carries the code.
+        }
+    }
+    /** Remove the published code; it grants nothing now and should not linger. */
+    async retractClaimCode() {
+        const path = this.options.claimCodeFile;
+        if (path === undefined)
+            return;
+        await rm(path, { force: true }).catch(() => undefined);
+    }
+    /** Record ownership atomically. */
+    async persist() {
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        const document = { ownerId: this.ownerId, claimedAt: Date.now() };
+        await mkdir(dirname(this.file), { recursive: true });
+        await writeFile(temporary, `${JSON.stringify(document, undefined, 2)}\n`, 'utf8');
+        await rename(temporary, this.file);
+    }
+}
+/**
+ * Constant-time comparison of a supplied code against the expected one.
+ * Lengths are compared through the same path so a wrong length leaks no more
+ * than a wrong byte does.
+ */
+function matches(supplied, expected) {
+    const a = Buffer.from(supplied);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) {
+        // Still do the work, so timing does not distinguish "wrong length".
+        timingSafeEqual(b, b);
+        return false;
+    }
+    return timingSafeEqual(a, b);
+}
+/** Read the recorded owner, treating anything unreadable as unowned. */
+async function readOwner(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8'));
+        return typeof parsed.ownerId === 'number' ? parsed.ownerId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=access.js.map

package/lib/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA4BnC,MAAM,OAAO,YAAY;IAIJ;IACA;IAJX,OAAO,CAAoB;IAEnC,YACmB,IAAY,EACZ,OAA4B;QAD5B,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAqB;IAC5C,CAAC;IAEJ;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,OAA4B;QAC1D,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAC9C,MAAM,CAAC,OAAO,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAA;QACtC,MAAM,MAAM,CAAC,gBAAgB,EAAE,CAAA;QAC/B,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAc;QAClB,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,SAAS,CAAA;QAC7D,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM;YAAE,OAAO,SAAS,CAAA;QAC7C,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QAC/C,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,QAAQ,CAAA;QACtD,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,yDAAyD;IACzD,KAAK;QACH,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,IAAY;QACtC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QAC5C,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAA;QACnD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAA;QAExD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QACpB,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAA;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,gBAAgB;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAA;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAM;QAC9B,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAA;QACtC,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAC/C,MAAM,SAAS,CACb,IAAI,EACJ,gEAAgE,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM;gBAC1F,kFAAkF,EACpF,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAClC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;QACjD,CAAC;IACH,CAAC;IAED,8EAA8E;IACtE,KAAK,CAAC,gBAAgB;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAA;QACvC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAM;QAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACxD,CAAC;IAED,mCAAmC;IAC3B,KAAK,CAAC,OAAO;QACnB,MAAM,SAAS,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAA;QACnD,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;QAEjE,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACpD,MAAM,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACjF,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,QAAgB,EAAE,QAAgB;IACjD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC/B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,oEAAoE;QACpE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACrB,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAC9B,CAAC;AAED,wEAAwE;AACxE,KAAK,UAAU,SAAS,CAAC,IAAY;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAA0B,CAAA;QAChF,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}