tapline-host 1.6.2 → 1.7.0

package/dist/otpclient.js

@@ -0,0 +1,362 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { looseScrubber } from "./accounts.js";
+/**
+ * AGENT-TOOLS 1.14 §18.11 and §20.4: the one-time code client. A sign-in code arrives where only Tapwright can read it, so
+ * Tapline's host asks Tapwright's daemon for it on loopback:
+ *
+ * 1. read `serve.json` (`port`, `token`) afresh, and keep the token only for this request;
+ * 2. open ONE connection to the literal `127.0.0.1:<port>` and have the daemon prove it holds the token (`POST /api/prove`,
+ *    no token sent), checking the proof for the address and port actually dialled, in constant time;
+ * 3. only then, on that same connection, `POST /otp` with the token. A connection the daemon closed gets nothing, and the
+ *    token never goes to a second connection.
+ *
+ * This is a raw `net.Socket` with a small HTTP/1.1 reader, so that "one socket" is a fact of the code and not a setting of an
+ * agent pool. Nothing here prints a token or a code; a failure says why in words.
+ */
+/** The address that is dialled, always as this literal (no name, no fallback). */
+export const LOOPBACK = "127.0.0.1";
+const PROOF_LABEL = "tapwright-proof-v2";
+/** How a code is shown wherever it could be seen (§20.3). */
+export const OTP_PLACEHOLDER = "<one-time code>";
+const MAX_RESPONSE = 64 * 1024;
+/** How many codes the redaction keeps for the session. */
+/** A session never forgets a code; past this many distinct codes a new one is refused rather than an old one dropped. */
+const MAX_CODES = 1000;
+/** `${otp.<app>}` as the whole text of a step: the app's id (reverse-domain names, so letters, digits, '.', '_' and '-'). */
+const OTP_WHOLE = /^\$\{otp\.([A-Za-z0-9._-]+)\}$/;
+/** The app id a text names when it is exactly `${otp.<app>}`; null for any other text. */
+export function otpReference(text) {
+    return OTP_WHOLE.exec(text)?.[1] ?? null;
+}
+const fail = (reason, message) => ({ ok: false, reason, message });
+/** The words for a step that has no code. They name no token and no code. */
+export function noCodeMessage(app) {
+    return `no one-time code for ${app}: Tapwright has none waiting. It needs Tapwright 1.7's daemon running, with this app's code setting turned on, and the code must come within 2 minutes after the app showed a code field.`;
+}
+function tapwrightHome(deps) {
+    if (deps.home !== undefined)
+        return deps.home;
+    const override = (deps.env ?? process.env)["TAPWRIGHT_HOME"];
+    return override !== undefined && override.length > 0 ? override : join((deps.homeDir ?? homedir)(), ".tapwright");
+}
+/** `serve.json`, read now. The token is returned to the one request that asked and kept nowhere else. */
+function readServe(deps) {
+    let text;
+    try {
+        text = readFileSync(join(tapwrightHome(deps), "serve.json"), "utf8");
+    }
+    catch {
+        return fail("no_file", "Tapwright's daemon file (serve.json) isn't there; start Tapwright's daemon (Tapwright 1.7) and try again.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Node's own message would quote part of the text, which holds a token.
+        return fail("bad_file", "Tapwright's daemon file (serve.json) isn't valid JSON.");
+    }
+    const top = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    const port = top?.port;
+    const token = top?.token;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535 || typeof token !== "string" || token === "") {
+        return fail("bad_file", "Tapwright's daemon file (serve.json) has no usable port and token.");
+    }
+    return { port, token };
+}
+/** HMAC-SHA256(token, "tapwright-proof-v2" NUL challenge-bytes NUL "127.0.0.1" NUL port), as hex. */
+export function proofFor(token, challenge, address, port) {
+    const nul = Buffer.from([0]);
+    const message = Buffer.concat([Buffer.from(PROOF_LABEL, "utf8"), nul, challenge, nul, Buffer.from(address, "utf8"), nul, Buffer.from(String(port), "ascii")]);
+    return createHmac("sha256", token).update(message).digest("hex");
+}
+function sameProof(given, wanted) {
+    if (typeof given !== "string")
+        return false;
+    const a = Buffer.from(given.toLowerCase(), "utf8");
+    const b = Buffer.from(wanted, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+class Closed extends Error {
+}
+/** A parsed response, or null while more bytes are needed. Throws on anything that isn't a plain HTTP/1.1 answer. */
+function parseReply(buffer) {
+    const end = buffer.indexOf("\r\n\r\n");
+    if (end < 0) {
+        if (buffer.length > MAX_RESPONSE)
+            throw new Error("too long");
+        return null;
+    }
+    const lines = buffer.subarray(0, end).toString("latin1").split("\r\n");
+    const match = /^HTTP\/1\.1 (\d{3})(?: |$)/.exec(lines[0] ?? "");
+    if (match === null)
+        throw new Error("not HTTP/1.1");
+    const headers = {};
+    for (const line of lines.slice(1)) {
+        const colon = line.indexOf(":");
+        if (colon > 0)
+            headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    const status = Number(match[1]);
+    const rest = buffer.subarray(end + 4);
+    if ((headers["transfer-encoding"] ?? "").toLowerCase() === "chunked") {
+        const parts = [];
+        let at = 0;
+        for (;;) {
+            const lineEnd = rest.indexOf("\r\n", at);
+            if (lineEnd < 0)
+                return null;
+            const size = Number.parseInt(rest.subarray(at, lineEnd).toString("latin1").split(";")[0] ?? "", 16);
+            if (!Number.isInteger(size) || size < 0)
+                throw new Error("bad chunk");
+            if (size === 0) {
+                // The trailer's end: an empty line.
+                return rest.length >= lineEnd + 4 ? { status, headers, body: Buffer.concat(parts).toString("utf8") } : null;
+            }
+            if (rest.length < lineEnd + 2 + size + 2)
+                return null;
+            parts.push(rest.subarray(lineEnd + 2, lineEnd + 2 + size));
+            at = lineEnd + 2 + size + 2;
+        }
+    }
+    const lengthText = headers["content-length"];
+    if (lengthText === undefined) {
+        if (status === 204 || status === 304)
+            return { status, headers, body: "" };
+        throw new Error("no length");
+    }
+    const length = Number(lengthText);
+    if (!Number.isInteger(length) || length < 0 || length > MAX_RESPONSE)
+        throw new Error("bad length");
+    return rest.length >= length ? { status, headers, body: rest.subarray(0, length).toString("utf8") } : null;
+}
+class Wire {
+    socket;
+    buffer = Buffer.alloc(0);
+    wake;
+    /** The peer ended the connection, or it failed. */
+    gone = false;
+    constructor(socket) {
+        this.socket = socket;
+        socket.on("data", (chunk) => {
+            this.buffer = Buffer.concat([this.buffer, chunk]);
+            this.wake?.();
+        });
+        const end = () => {
+            this.gone = true;
+            this.wake?.();
+        };
+        socket.on("end", end);
+        socket.on("close", end);
+        socket.on("error", end);
+    }
+    /** Whether another request may still go on this connection. */
+    usable() {
+        return !this.gone && !this.socket.destroyed && this.socket.writable;
+    }
+    async request(path, port, body, authorization) {
+        const head = [
+            `POST ${path} HTTP/1.1`,
+            `Host: ${LOOPBACK}:${port}`,
+            "Content-Type: application/json",
+            `Content-Length: ${Buffer.byteLength(body)}`,
+            "Connection: keep-alive",
+            ...(authorization !== undefined ? [`Authorization: ${authorization}`] : []),
+            "",
+            "",
+        ].join("\r\n");
+        this.buffer = Buffer.alloc(0);
+        await new Promise((resolve, reject) => {
+            this.socket.write(head + body, (error) => (error ? reject(new Closed("write failed")) : resolve()));
+        });
+        for (;;) {
+            let reply;
+            try {
+                reply = parseReply(this.buffer);
+            }
+            catch {
+                throw new Error("bad reply");
+            }
+            if (reply !== null)
+                return reply;
+            if (this.gone)
+                throw new Closed("closed before an answer");
+            await new Promise((resolve) => {
+                this.wake = () => {
+                    this.wake = undefined;
+                    resolve();
+                };
+            });
+        }
+    }
+}
+function dial(port) {
+    return new Promise((resolve, reject) => {
+        // The literal address, IPv4 only: no name lookup, no fallback to localhost.
+        const socket = connect({ host: LOOPBACK, port, family: 4 });
+        socket.setNoDelay(true);
+        socket.once("connect", () => {
+            socket.removeListener("error", reject);
+            resolve(socket);
+        });
+        socket.once("error", reject);
+    });
+}
+function parseJson(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Asks Tapwright's daemon for the code of an app (§18.11). The caller has already checked that a step is typing
+ * `${otp.<that app>}` for the connected app; this is the only way a code comes in.
+ */
+export async function fetchOtp(app, deps = {}) {
+    const serve = readServe(deps);
+    if ("ok" in serve)
+        return serve;
+    const { port, token } = serve;
+    const random = deps.random ?? randomBytes;
+    const now = deps.now ?? Date.now;
+    const challenge = random(32);
+    let wire;
+    let timer;
+    // Set when the time is up: after that nothing more is sent, and a connection that completes late is closed.
+    let aborted = false;
+    const timedOut = () => fail("timeout", "Tapwright's daemon didn't answer in time.");
+    const run = async () => {
+        let socket;
+        try {
+            socket = await (deps.dial ?? dial)(port);
+        }
+        catch {
+            return fail("unreachable", "Tapwright's daemon didn't answer on this computer; start it (Tapwright 1.7) and try again.");
+        }
+        if (aborted) {
+            socket.destroy();
+            return timedOut();
+        }
+        const opened = new Wire(socket);
+        wire = opened;
+        // Only the socket's own answer about where it is connected counts: the address and port the proof is made for.
+        if (socket.remoteAddress !== LOOPBACK || socket.remotePort !== port)
+            return fail("unreachable", "Tapwright's daemon didn't answer on this computer.");
+        let proved;
+        try {
+            proved = await opened.request("/api/prove", port, JSON.stringify({ challenge: challenge.toString("hex") }), undefined);
+        }
+        catch (error) {
+            return error instanceof Closed ? fail("no_proof", "Tapwright's daemon closed the connection before it proved itself; nothing was sent to it.") : fail("bad_reply", "Tapwright's daemon answered in a form this Tapline doesn't know.");
+        }
+        const proof = proved.status === 200 ? parseJson(proved.body)?.["proof"] : undefined;
+        if (!sameProof(proof, proofFor(token, challenge, LOOPBACK, port))) {
+            return fail("no_proof", "Whatever answers on Tapwright's daemon port didn't prove it holds Tapwright's token, so nothing was sent to it.");
+        }
+        // A daemon that closes its connection after the proof gets nothing: the token never goes to a second connection.
+        const settle = deps.settleMs ?? 15;
+        if (settle > 0)
+            await new Promise((done) => setTimeout(done, settle));
+        if (aborted)
+            return timedOut();
+        if (!opened.usable() || (proved.headers["connection"] ?? "").toLowerCase().includes("close")) {
+            return fail("closed", "Tapwright's daemon closed the connection after it proved itself; nothing was sent, and the token is never sent on a new connection.");
+        }
+        if (aborted)
+            return timedOut();
+        let answer;
+        try {
+            answer = await opened.request("/otp", port, JSON.stringify({ app }), `Bearer ${token}`);
+        }
+        catch (error) {
+            return error instanceof Closed ? fail("closed", "Tapwright's daemon closed the connection before it answered.") : fail("bad_reply", "Tapwright's daemon answered in a form this Tapline doesn't know.");
+        }
+        if (answer.status === 404)
+            return fail("none", noCodeMessage(app));
+        if (answer.status !== 200)
+            return fail("refused", `Tapwright's daemon refused the request for a one-time code for ${app} (status ${answer.status}).`);
+        const body = parseJson(answer.body);
+        const code = body?.["code"];
+        const expires = body?.["expires"];
+        const from = body?.["source"];
+        if (typeof code !== "string" || !/^[0-9]{4,12}$/.test(code) || typeof expires !== "number" || !Number.isFinite(expires)) {
+            return fail("bad_reply", "Tapwright's daemon sent a one-time code in a form this Tapline doesn't know.");
+        }
+        if (expires <= now())
+            return fail("expired", `the one-time code for ${app} had already expired when it arrived; ask the app for a new one.`);
+        // The source is Tapwright's own word for where the code came from; it is a name, never the code.
+        const source = typeof from === "string" && /^[A-Za-z0-9._-]{1,100}$/.test(from) && from !== code ? from : undefined;
+        return { ok: true, code, expires, source };
+    };
+    try {
+        const limit = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                aborted = true;
+                wire?.socket.destroy();
+                resolve(timedOut());
+            }, deps.timeoutMs ?? 5000);
+        });
+        return await Promise.race([run(), limit]);
+    }
+    catch {
+        return fail("unreachable", "Tapwright's daemon couldn't be asked.");
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        wire?.socket.destroy();
+    }
+}
+// -- what the codes of a session are scrubbed from
+/** The codes this session typed. Each one is scrubbed from everything shown or kept, for the rest of the session (§20.3). */
+export class OtpCodes {
+    codes = [];
+    /** Built on first use after a code is added, so a burst of codes compiles once. */
+    scrub = null;
+    /**
+     * Keeps scrubbing a code for the rest of the session: none is ever dropped (§20.3). Codes are short-lived and few; past a
+     * large cap a new code is refused (false) instead of an old one being forgotten.
+     */
+    register(code) {
+        if (this.codes.includes(code))
+            return true;
+        if (this.codes.length >= MAX_CODES)
+            return false;
+        this.codes = [...this.codes, code];
+        this.scrub = null;
+        return true;
+    }
+    token = OTP_PLACEHOLDER;
+    /** The codes so far: the same array until a code is added. */
+    values() {
+        return this.codes;
+    }
+    /** Arrow, so it can be handed on as a plain function. */
+    redact = (text) => {
+        if (this.codes.length === 0)
+            return text;
+        this.scrub ??= looseScrubber(this.codes, OTP_PLACEHOLDER);
+        return this.scrub(text);
+    };
+}
+export function createOtpService(deps = {}, codes = new OtpCodes()) {
+    return {
+        codes,
+        async fetch(app) {
+            const result = await fetchOtp(app, deps);
+            if (result.ok && !codes.register(result.code)) {
+                // Never hand on a code that couldn't be registered for scrubbing.
+                return { ok: false, reason: "refused", message: "this session has used too many one-time codes to scrub them all; restart Tapline to type another." };
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=otpclient.js.map

package/dist/otpclient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otpclient.js","sourceRoot":"","sources":["../src/otpclient.ts"],"names":[],"mappings":"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"}

package/dist/pidlock.d.ts

@@ -0,0 +1,99 @@
+/**
+ * AGENT-TOOLS 1.14.1 §22.3 and §19.5: the pid-liveness lock shared by the run lock (`<schedule>.lock`) and the policy file's edit lock
+ * (`<policy file>.edit.lock`). A lock is a file that holds its holder's owner token, process id and the process's start time. It
+ * is published whole and atomically: the full JSON goes to a unique temp file, which is hard-linked to the lock's name (`link` is an
+ * exclusive create on NTFS, APFS and ext4: EEXIST when the lock exists), then the temp file is unlinked. A lock is therefore never
+ * seen empty or half written. Where hard links aren't available the lock is created with `wx` and written in place; a lock that can't
+ * be read as a holder is then a run that is still writing it.
+ *
+ * A lock is a leftover only on PROOF of its holder's death: its process doesn't run, or the process with that id started at another
+ * time. An empty, cut-short or garbage lock is never a leftover (there is no age rule): it is waited out, which fails closed.
+ * A leftover is taken over under `<lock>.takeover`, published the same way.
+ */
+/** What the lock needs from the process and the system. Everything is injectable so a test can pause at any point. */
+export interface PidLockDeps {
+    pid: number;
+    alive: (pid: number) => boolean;
+    /** When a process started, as text that is the same each time for one process (null: unknown). A lock keeps it so a reused process id is not taken for the holder. */
+    startOf?: (pid: number) => string | null;
+    /** For tests: runs after a run found a leftover lock and before it takes the lock over (another run may get in between). */
+    beforeReclaim?: () => void;
+    /** For tests: runs after the temp file is written and before it is linked to the lock's name. */
+    beforePublish?: (path: string) => void;
+    /** For tests: the hard link (default `fs.linkSync`); a throw of EPERM stands for a file system without hard links. */
+    link?: (existing: string, path: string) => void;
+    /** For tests: runs in the no-hard-link fallback, after the exclusive create and before the content is written. */
+    afterCreate?: (path: string) => void;
+    /** For tests: runs in an unlock after a file was judged stuck and before it is removed (a new holder may get in between). */
+    beforeRemove?: (path: string) => void;
+}
+/** What runs a program and answers its output; throws when it fails. Injectable, so the start time of a process can be tested. */
+export type RunProgram = (file: string, args: string[]) => string;
+/**
+ * When a process started, as text that is the same each time it is asked for the same process; null when it can't be told. A lock
+ * keeps it beside the process id, so a process id that was reused by another program is not mistaken for the holder. Windows asks
+ * PowerShell (`Get-Process -Id N`, about half a second, asked only for a lock's own holder and when a lock is found), elsewhere `ps`.
+ */
+export declare function processStartTime(pid: number, platform?: string, run?: RunProgram): string | null;
+/** Whether a process runs (signal 0); a process we may not signal still runs. */
+export declare function processAlive(pid: number): boolean;
+/** The deps of this process for a lock of its own (this process's start time is asked once and kept). */
+export declare function ownLockDeps(): PidLockDeps;
+/**
+ * Creates `path` with `text`, whole, only if it doesn't exist: "published", or "exists" (someone's file stands there), or "error".
+ * The text is written to a unique temp file first and hard-linked into place, so `path` is never seen empty.
+ */
+export declare function publishNew(deps: PidLockDeps, path: string, text: string): "published" | "exists" | "error";
+/**
+ * Takes the lock at `path` (its folder must exist): the owner token, or null when a live holder has it. A live holder is never
+ * displaced, however long it takes. A leftover (holder provably dead) is taken over under `<path>.takeover`, published the same way:
+ * under it the lock is read again, and only if it is unchanged and its holder is still dead is it deleted and replaced by the taker's.
+ * A `.takeover` whose own process is dead is cleared the same way.
+ */
+export declare function takePidLock(deps: PidLockDeps, path: string): string | null;
+/** Releases the lock only while its content is still the holder's own (`token`); another's lock is never removed. */
+export declare function dropPidLock(path: string, token: string): void;
+/** Whether the lock's holder is `token` right now (for a holder that wants to know it still has it). */
+export declare function holdsPidLock(path: string, token: string): boolean;
+/**
+ * What a lock file is right now. `stuck` is a lock no run will ever clear by itself and a person has to see: empty, unreadable, or
+ * held by a process that is provably dead. `live` is a holder that is proven alive (never displaced).
+ */
+export type StuckState = {
+    state: "stuck";
+    why: "empty" | "unreadable" | "dead";
+    pid?: number;
+};
+export type PidLockState = {
+    state: "absent";
+} | {
+    state: "live";
+    pid: number;
+} | StuckState;
+/** Looks at the lock at `path` without changing it. */
+export declare function inspectPidLock(deps: PidLockDeps, path: string): PidLockState;
+/** The words for a stuck lock's cause. */
+export declare function stuckWords(state: StuckState): string;
+export interface UnlockResult {
+    /** `none`: no lock file; `live`: a live holder is proven, nothing removed; `removed`: stuck files removed; `failed`: a stuck file couldn't be removed. */
+    status: "none" | "live" | "removed" | "failed";
+    /** The live holder's process id when `status` is `live`. */
+    pid?: number;
+    /** Every file removed, with why. */
+    removed: Array<{
+        path: string;
+        why: string;
+    }>;
+    /** The file of a `live` or `failed` answer. */
+    path?: string;
+}
+/**
+ * Removes the lock at `path` and its `.takeover`, but only when no holder is proven alive: an empty or unreadable file, or one whose
+ * holder is dead (its process is gone, or has another start time). A live holder in either file refuses and removes nothing.
+ *
+ * It runs under the lock's own `.takeover` (published whole, as a takeover is), so it never overlaps a takeover, and acquisition
+ * honours `.takeover` too. Under it the exact bytes of the lock are read once, THAT snapshot's holder is judged, and the file is
+ * removed only if it still holds exactly those bytes (moved to a tombstone and compared; a different file is linked back).
+ * A `.takeover` that is itself stuck is cleared the same way first.
+ */
+export declare function unlockPidLock(deps: PidLockDeps, path: string): UnlockResult;