@devdogsuga/devtools 0.1.0 → 0.1.1

package/dist/newsletter/imap.d.ts

@@ -1,17 +0,0 @@
-/** RFC 7628's SASL initial response: user and bearer token, ^A-delimited. */
-export declare function xoauth2(user: string, accessToken: string): string;
-/**
- * The Drafts folder's real name out of `LIST` output, for mailboxes whose
- * folders are not in English. The `\Drafts` attribute is the label Exchange
- * puts on the folder regardless of what it is called.
- */
-export declare function draftsFromList(lines: readonly string[]): string | null;
-/** Folder names go back out quoted, so quote-significant bytes get escaped. */
-export declare function quoteMailbox(name: string): string;
-export declare function appendDraft(options: {
-    user: string;
-    accessToken: string;
-    /** The full MIME message, CRLF line endings. */
-    message: string;
-    host?: string;
-}): Promise<void>;

package/dist/newsletter/imap.js

@@ -1,127 +0,0 @@
-/**
- * One-shot IMAP APPEND: place a finished MIME message in a mailbox's Drafts
- * folder, where every Outlook — new, web, Mac, classic — offers it as an
- * editable draft. This is the whole reason for speaking IMAP at all: the
- * mailbox is the one place all the clients agree on, and APPEND is the one
- * verb this workflow needs, so a dependency-free sliver of the protocol beats
- * a client library that models the rest of it.
- */
-import { connect } from "node:tls";
-const DEFAULT_HOST = "outlook.office365.com";
-const TIMEOUT_MS = 30_000;
-/** RFC 7628's SASL initial response: user and bearer token, ^A-delimited. */
-export function xoauth2(user, accessToken) {
-    return Buffer.from(`user=${user}\x01auth=Bearer ${accessToken}\x01\x01`, "utf8").toString("base64");
-}
-/**
- * The Drafts folder's real name out of `LIST` output, for mailboxes whose
- * folders are not in English. The `\Drafts` attribute is the label Exchange
- * puts on the folder regardless of what it is called.
- */
-export function draftsFromList(lines) {
-    for (const line of lines) {
-        const match = /^\* LIST \(([^)]*)\) (?:"[^"]*"|NIL) (.+)$/.exec(line);
-        if (!match || !/\\Drafts\b/i.test(match[1]))
-            continue;
-        const raw = match[2].trim();
-        return raw.startsWith('"') && raw.endsWith('"')
-            ? raw.slice(1, -1).replace(/\\(["\\])/g, "$1")
-            : raw;
-    }
-    return null;
-}
-/** Folder names go back out quoted, so quote-significant bytes get escaped. */
-export function quoteMailbox(name) {
-    return `"${name.replace(/([\\"])/g, "\\$1")}"`;
-}
-export async function appendDraft(options) {
-    const host = options.host ?? DEFAULT_HOST;
-    const socket = connect({ host, port: 993, servername: host });
-    socket.setTimeout(TIMEOUT_MS);
-    let buffer = "";
-    let sequence = 0;
-    const pending = [];
-    let wake = null;
-    let failure = null;
-    socket.on("data", (chunk) => {
-        buffer += chunk.toString("utf8");
-        let index;
-        while ((index = buffer.indexOf("\r\n")) !== -1) {
-            pending.push(buffer.slice(0, index));
-            buffer = buffer.slice(index + 2);
-        }
-        wake?.();
-    });
-    const fail = (err) => {
-        failure ??= err;
-        socket.destroy();
-        wake?.();
-    };
-    socket.on("error", (err) => fail(err));
-    socket.on("timeout", () => fail(new Error(`${host} stopped answering.`)));
-    socket.on("close", () => fail(new Error(`${host} closed the connection.`)));
-    const nextLine = async () => {
-        for (;;) {
-            if (pending.length)
-                return pending.shift();
-            if (failure)
-                throw failure;
-            await new Promise((resolvePromise) => {
-                wake = resolvePromise;
-            });
-            wake = null;
-        }
-    };
-    /**
-     * Sends one command and reads to its tagged reply. A `+ ` continuation
-     * hands control back via `onContinue` — APPEND pushes the literal there,
-     * and a failed AUTHENTICATE wants a bare CRLF to surface its tagged NO.
-     */
-    const command = async (line, onContinue) => {
-        const tag = `T${++sequence}`;
-        socket.write(`${tag} ${line}\r\n`);
-        const untagged = [];
-        for (;;) {
-            const reply = await nextLine();
-            if (reply.startsWith("+ ") || reply === "+") {
-                (onContinue ?? (() => socket.write("\r\n")))();
-                continue;
-            }
-            if (reply.startsWith(`${tag} `)) {
-                const [status = "", ...rest] = reply.slice(tag.length + 1).split(" ");
-                return { status: status.toUpperCase(), text: rest.join(" "), untagged };
-            }
-            if (reply.startsWith("* "))
-                untagged.push(reply);
-        }
-    };
-    try {
-        await nextLine(); // The server greets first; nothing in it matters here.
-        const auth = await command(`AUTHENTICATE XOAUTH2 ${xoauth2(options.user, options.accessToken)}`);
-        if (auth.status !== "OK") {
-            throw new Error(`${options.user} was refused: ${auth.text || auth.status}. ` +
-                "Sign in again if the stored grant has been revoked.");
-        }
-        const literal = Buffer.from(options.message, "utf8");
-        const append = (folder) => command(`APPEND ${quoteMailbox(folder)} (\\Draft \\Seen) {${literal.length}}`, () => {
-            socket.write(literal);
-            socket.write("\r\n");
-        });
-        let placed = await append("Drafts");
-        if (placed.status !== "OK") {
-            // Exchange names the folder in the mailbox's own language; the
-            // attribute in LIST is the stable way to find it.
-            const list = await command('LIST "" "*"');
-            const drafts = draftsFromList(list.untagged);
-            if (drafts && drafts !== "Drafts")
-                placed = await append(drafts);
-            if (placed.status !== "OK") {
-                throw new Error(`APPEND was refused: ${placed.text || placed.status}`);
-            }
-        }
-        await command("LOGOUT");
-    }
-    finally {
-        socket.destroy();
-    }
-}

package/dist/newsletter/loopback.d.ts

@@ -1,24 +0,0 @@
-/**
- * What one request to the listener means. `null` is a stray — a favicon
- * probe, a health check — and the server keeps waiting; a wrong or missing
- * state is also a stray, because rejecting the whole sign-in over a request
- * an attacker could send unauthenticated would hand them a denial of
- * service instead.
- */
-export declare function parseCallback(requestUrl: string, state: string): {
-    code: string;
-} | Error | null;
-export interface Loopback {
-    port: number;
-    /** Resolves with the code, or rejects with what the identity page said. */
-    code: Promise<string>;
-    close(): void;
-}
-/** Throws when it cannot bind, which is the caller's cue to fall back. */
-export declare function startLoopback(state: string): Promise<Loopback>;
-/**
- * Best effort only: the URL is always printed too, so a machine with no
- * opener — SSH, a container, a WSL distro without wslview — costs one click
- * on the printed line instead of a failure.
- */
-export declare function openInBrowser(url: string): void;

package/dist/newsletter/loopback.js

@@ -1,100 +0,0 @@
-/**
- * A throwaway HTTP server that catches one OAuth redirect and dies.
- *
- * Entra ignores the port when matching a localhost redirect URI, so the
- * sign-in can come home to `http://localhost:{ephemeral}/` even though
- * Thunderbird registered no port. Bound to 127.0.0.1 only — the redirect
- * never leaves the machine, and nothing off it should reach the listener.
- * The `state` nonce ties the callback to this run: any other process that
- * finds the port cannot feed the flow a code it did not mint.
- */
-import { createServer } from "node:http";
-import { spawn } from "node:child_process";
-/**
- * What one request to the listener means. `null` is a stray — a favicon
- * probe, a health check — and the server keeps waiting; a wrong or missing
- * state is also a stray, because rejecting the whole sign-in over a request
- * an attacker could send unauthenticated would hand them a denial of
- * service instead.
- */
-export function parseCallback(requestUrl, state) {
-    const url = new URL(requestUrl, "http://localhost");
-    if (url.pathname !== "/")
-        return null;
-    if (url.searchParams.get("state") !== state)
-        return null;
-    const error = url.searchParams.get("error");
-    if (error) {
-        return new Error(url.searchParams.get("error_description") ?? error);
-    }
-    const code = url.searchParams.get("code");
-    return code ? { code } : null;
-}
-const LANDING = `<!doctype html>
-<meta charset="utf-8">
-<title>DevDogs devtools</title>
-<body style="font-family: system-ui; display: grid; place-items: center; min-height: 90vh; background: #13121b; color: #f3f1f6">
-<p style="max-width: 36rem; text-align: center">%MESSAGE% You can close this tab; the rest happens in the terminal.</p>
-`;
-/** Throws when it cannot bind, which is the caller's cue to fall back. */
-export function startLoopback(state) {
-    return new Promise((resolve, reject) => {
-        // Assigned synchronously by the executor below, which TS cannot see.
-        let settle;
-        const code = new Promise((resolveCode, rejectCode) => {
-            settle = { resolve: resolveCode, reject: rejectCode };
-        });
-        // A rejection can land in the gap before the caller awaits; this extra
-        // no-op handler marks it handled without eating it for the real awaiter.
-        code.catch(() => { });
-        const server = createServer((request, response) => {
-            const result = parseCallback(request.url ?? "/", state);
-            if (result === null) {
-                response.writeHead(404).end();
-                return;
-            }
-            const failed = result instanceof Error;
-            response
-                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
-                .end(LANDING.replace("%MESSAGE%", failed ? "The sign-in did not go through." : "Signed in."));
-            if (failed)
-                settle.reject(result);
-            else
-                settle.resolve(result.code);
-        });
-        server.on("error", reject);
-        server.listen(0, "127.0.0.1", () => {
-            const address = server.address();
-            if (!address || typeof address === "string") {
-                server.close();
-                reject(new Error("The loopback server bound without a port."));
-                return;
-            }
-            resolve({
-                port: address.port,
-                code,
-                close: () => server.close(),
-            });
-        });
-    });
-}
-/**
- * Best effort only: the URL is always printed too, so a machine with no
- * opener — SSH, a container, a WSL distro without wslview — costs one click
- * on the printed line instead of a failure.
- */
-export function openInBrowser(url) {
-    const [command, args] = process.platform === "win32"
-        ? ["cmd", ["/c", "start", "", url]]
-        : process.platform === "darwin"
-            ? ["open", [url]]
-            : ["xdg-open", [url]];
-    try {
-        spawn(command, args, { stdio: "ignore", detached: true })
-            .on("error", () => { })
-            .unref();
-    }
-    catch {
-        // The printed URL is the real interface; this was only a convenience.
-    }
-}

package/dist/newsletter/oauth.d.ts

@@ -1,26 +0,0 @@
-/** The fallback redirect when no loopback server could bind. */
-export declare const PASTE_REDIRECT_URI = "https://localhost";
-export declare function authorizeUrl(mailbox: string, redirectUri: string, state?: string): string;
-/**
- * The code out of whatever the officer pastes: the whole `https://localhost/?
- * code=…` address (the intended gesture — the browser shows a dead page and
- * they copy its location) or the bare code itself.
- */
-export declare function codeFromRedirect(pasted: string): string | Error;
-export interface MailboxTokens {
-    accessToken: string;
-    refreshToken: string;
-}
-export declare function redeemCode(code: string, redirectUri: string): Promise<MailboxTokens>;
-export declare function refreshTokens(refreshToken: string): Promise<MailboxTokens>;
-export interface StoredGrant {
-    mailbox: string;
-    refreshToken: string;
-}
-/**
- * Outside the repo on purpose: the refresh token opens the club mailbox, and
- * nothing that opens the club mailbox belongs anywhere `git add` can reach.
- */
-export declare function grantPath(): string;
-export declare function readGrant(): Promise<StoredGrant | null>;
-export declare function writeGrant(grant: StoredGrant): Promise<void>;

package/dist/newsletter/oauth.js

@@ -1,130 +0,0 @@
-/**
- * Sign-in for the club mailbox, borrowing Thunderbird's app registration.
- *
- * UGA's tenant blocks user consent for every Microsoft Graph mail scope (the
- * Microsoft-managed default policy), so the clean path — a Graph-created
- * draft — needs an EITS-approved app registration. The same policy, though,
- * allowlists a handful of mail clients by application ID for the legacy
- * IMAP/SMTP scopes, Thunderbird among them. This module runs the standard
- * authorization-code flow as that client: the officer signs in as the mailbox
- * in a browser, and the refresh token is theirs — the same grant Thunderbird
- * itself would hold. Presenting another client's ID is a documented
- * convention in open-source mail tooling (mbsync, OfflineIMAP, DavMail), but
- * it is Microsoft's allowlist, and this stops working the day they prune it.
- *
- * The redirect comes back two ways. Entra ignores the port when matching a
- * localhost redirect URI, so the ordinary path is `loopback.ts`: a throwaway
- * server on an ephemeral port that catches the code itself. When that server
- * cannot bind, the flow falls back to Thunderbird's registered
- * `https://localhost` — a dead page whose address bar holds the code, pasted
- * back by hand.
- *
- * No PKCE and no client secret: Thunderbird is registered as a public client,
- * and the code exchange happens entirely on this machine.
- */
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-const CLIENT_ID = "9e5f94bc-e8a4-4e73-b8be-63364c29d753";
-/** The fallback redirect when no loopback server could bind. */
-export const PASTE_REDIRECT_URI = "https://localhost";
-// IMAP places drafts; SMTP.Send is `--send`. Both are on the same consent
-// allowlist for the borrowed client, so one grant covers both, and a stored
-// IMAP-only grant upgrades silently on its next refresh.
-const SCOPE = "https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access";
-const AUTHORITY = "https://login.microsoftonline.com/organizations/oauth2/v2.0";
-export function authorizeUrl(mailbox, redirectUri, state) {
-    const query = new URLSearchParams({
-        client_id: CLIENT_ID,
-        response_type: "code",
-        redirect_uri: redirectUri,
-        scope: SCOPE,
-        login_hint: mailbox,
-        ...(state ? { state } : {}),
-    });
-    return `${AUTHORITY}/authorize?${query}`;
-}
-/**
- * The code out of whatever the officer pastes: the whole `https://localhost/?
- * code=…` address (the intended gesture — the browser shows a dead page and
- * they copy its location) or the bare code itself.
- */
-export function codeFromRedirect(pasted) {
-    const input = pasted.trim();
-    const error = /[?&#]error=([^&\s]+)/.exec(input);
-    if (error) {
-        const description = /[?&#]error_description=([^&\s]+)/.exec(input);
-        return new Error(description
-            ? decodeURIComponent(description[1].replace(/\+/g, " "))
-            : decodeURIComponent(error[1]));
-    }
-    const inUrl = /[?&#]code=([^&\s]+)/.exec(input);
-    if (inUrl)
-        return decodeURIComponent(inUrl[1]);
-    // Bare codes are opaque but never contain URL structure or whitespace.
-    if (input && !/[\s/?&=]/.test(input))
-        return input;
-    return new Error("That has no ?code= in it. Paste the whole address bar of the localhost page.");
-}
-async function tokenRequest(grant) {
-    const response = await fetch(`${AUTHORITY}/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({
-            client_id: CLIENT_ID,
-            scope: SCOPE,
-            ...grant,
-        }),
-    });
-    const body = (await response.json());
-    if (!response.ok || !body.access_token || !body.refresh_token) {
-        throw new Error(body.error_description ??
-            body.error ??
-            `Token endpoint answered ${response.status}.`);
-    }
-    return { accessToken: body.access_token, refreshToken: body.refresh_token };
-}
-export function redeemCode(code, redirectUri) {
-    return tokenRequest({
-        grant_type: "authorization_code",
-        code,
-        // Must be byte-for-byte the redirect the code was issued against.
-        redirect_uri: redirectUri,
-    });
-}
-export function refreshTokens(refreshToken) {
-    return tokenRequest({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-    });
-}
-/**
- * Outside the repo on purpose: the refresh token opens the club mailbox, and
- * nothing that opens the club mailbox belongs anywhere `git add` can reach.
- */
-export function grantPath() {
-    const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-    return join(configHome, "devdogsuga", "newsletter-mailbox.json");
-}
-export async function readGrant() {
-    try {
-        const parsed = JSON.parse(await readFile(grantPath(), "utf8"));
-        return typeof parsed.mailbox === "string" &&
-            typeof parsed.refreshToken === "string"
-            ? { mailbox: parsed.mailbox, refreshToken: parsed.refreshToken }
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeGrant(grant) {
-    const path = grantPath();
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(grant, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    // writeFile's mode only applies on create; an existing file keeps its old
-    // bits, so tighten explicitly on the rotation path too.
-    await chmod(path, 0o600);
-}

package/dist/newsletter/smtp.d.ts

@@ -1,23 +0,0 @@
-/**
- * RFC 5322 origination headers for a message built as a draft. `buildEml`
- * deliberately emits none of these — draft-ness is their absence — so the
- * send path prepends them. The submission server stamps `Message-ID`.
- */
-export declare function originationHeaders(from: string, to: readonly string[], date?: Date): string;
-/** RFC 5321 §4.5.2 transparency: a line-leading `.` doubles inside DATA. */
-export declare function dotStuff(message: string): string;
-/**
- * `true` when an SMTP reply line ends its reply: `250 done` rather than the
- * `250-more coming` continuation form (RFC 5321 §4.2.1).
- */
-export declare function endsReply(line: string): boolean;
-export declare function submitMessage(options: {
-    user: string;
-    accessToken: string;
-    /** The envelope sender — must be the authenticated mailbox on Exchange. */
-    from: string;
-    recipients: readonly string[];
-    /** The full MIME message, origination headers included, CRLF endings. */
-    message: string;
-    host?: string;
-}): Promise<void>;

package/dist/newsletter/smtp.js

@@ -1,133 +0,0 @@
-/**
- * One-shot SMTP submission: send a finished MIME message byte-for-byte.
- *
- * This exists because a draft cannot survive being sent from Outlook. The
- * web Outlook composer is a rich-text editor with a style whitelist, and
- * sending a pushed draft re-serializes whatever that editor kept: forensics
- * on a received copy showed the head `<style>` replaced with Outlook's own,
- * every `background-image` and `bgcolor` gone, and most class attributes
- * dropped — all of the newsletter's dark-mode defenses, stripped in transit.
- * (Classic Outlook mangles differently, into Word HTML, but just as surely.)
- * Submitting over SMTP bypasses every composer: recipients get the authored
- * document, stylesheet and all. Like `imap.ts`, this speaks just the sliver
- * of the protocol the workflow needs — EHLO, STARTTLS, AUTH, one message.
- */
-import { createConnection } from "node:net";
-import { connect as connectTls } from "node:tls";
-import { xoauth2 } from "./imap.js";
-const DEFAULT_HOST = "smtp.office365.com";
-const TIMEOUT_MS = 30_000;
-/**
- * RFC 5322 origination headers for a message built as a draft. `buildEml`
- * deliberately emits none of these — draft-ness is their absence — so the
- * send path prepends them. The submission server stamps `Message-ID`.
- */
-export function originationHeaders(from, to, date = new Date()) {
-    return [
-        `From: <${from}>`,
-        `To: ${to.map((address) => `<${address}>`).join(", ")}`,
-        // toUTCString is RFC 5322's fixed-length date form, save the zone name.
-        `Date: ${date.toUTCString().replace(/GMT$/, "+0000")}`,
-        "",
-    ].join("\r\n");
-}
-/** RFC 5321 §4.5.2 transparency: a line-leading `.` doubles inside DATA. */
-export function dotStuff(message) {
-    return message.replace(/(^|\r\n)\./g, "$1..");
-}
-/**
- * `true` when an SMTP reply line ends its reply: `250 done` rather than the
- * `250-more coming` continuation form (RFC 5321 §4.2.1).
- */
-export function endsReply(line) {
-    return /^\d{3}(?: |$)/.test(line);
-}
-export async function submitMessage(options) {
-    const host = options.host ?? DEFAULT_HOST;
-    if (!options.recipients.length)
-        throw new Error("No recipients.");
-    let buffer = "";
-    const pending = [];
-    let wake = null;
-    let failure = null;
-    const fail = (err) => {
-        failure ??= err;
-        socket.destroy();
-        wake?.();
-    };
-    /** (Re)binds the line reader — once to the TCP socket, again after TLS. */
-    const adopt = (next) => {
-        next.setTimeout(TIMEOUT_MS);
-        next.on("data", (chunk) => {
-            buffer += chunk.toString("utf8");
-            let index;
-            while ((index = buffer.indexOf("\r\n")) !== -1) {
-                pending.push(buffer.slice(0, index));
-                buffer = buffer.slice(index + 2);
-            }
-            wake?.();
-        });
-        next.on("error", (err) => fail(err));
-        next.on("timeout", () => fail(new Error(`${host} stopped answering.`)));
-        next.on("close", () => fail(new Error(`${host} closed the connection.`)));
-        return next;
-    };
-    let socket = adopt(createConnection({ host, port: 587 }));
-    const nextLine = async () => {
-        for (;;) {
-            if (pending.length)
-                return pending.shift();
-            if (failure)
-                throw failure;
-            await new Promise((resolvePromise) => {
-                wake = resolvePromise;
-            });
-            wake = null;
-        }
-    };
-    /** Reads one full reply; throws unless its code is in `expect`. */
-    const reply = async (expect, doing) => {
-        let line;
-        do {
-            line = await nextLine();
-        } while (!endsReply(line));
-        const code = Number(line.slice(0, 3));
-        if (!expect.includes(code)) {
-            throw new Error(`${doing}: ${line}`);
-        }
-        return line;
-    };
-    const command = (line, expect, doing) => {
-        socket.write(`${line}\r\n`);
-        return reply(expect, doing);
-    };
-    try {
-        await reply([220], `${host} refused the connection`);
-        await command(`EHLO [127.0.0.1]`, [250], "EHLO was refused");
-        await command("STARTTLS", [220], "STARTTLS was refused");
-        // The server speaks next only after the handshake, so nothing is in
-        // flight — but the plaintext socket's reader has to come off before the
-        // wrap, or it would keep pushing what is now ciphertext into the line
-        // buffer (and its close fires only when the whole connection does).
-        for (const event of ["data", "timeout", "close"]) {
-            socket.removeAllListeners(event);
-        }
-        socket.setTimeout(0);
-        socket = adopt(connectTls({ socket, servername: host }));
-        await command(`EHLO [127.0.0.1]`, [250], "EHLO after STARTTLS was refused");
-        await command(`AUTH XOAUTH2 ${xoauth2(options.user, options.accessToken)}`, [235], `${options.user} was refused. Sign in again if the stored grant lacks ` +
-            "SMTP.Send — grants from before --send existed only asked for IMAP");
-        await command(`MAIL FROM:<${options.from}>`, [250], `The sender ${options.from} was refused`);
-        for (const recipient of options.recipients) {
-            await command(`RCPT TO:<${recipient}>`, [250, 251], `The recipient ${recipient} was refused`);
-        }
-        await command("DATA", [354], "DATA was refused");
-        const body = dotStuff(options.message);
-        socket.write(body.endsWith("\r\n") ? body : `${body}\r\n`);
-        await command(".", [250], "The message was refused");
-        socket.write("QUIT\r\n");
-    }
-    finally {
-        socket.destroy();
-    }
-}