pi-roundtable-line 0.0.0-stage → 0.9.13

package/src/token.ts

@@ -0,0 +1,215 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { scrubDiagnostic } from "pi-roundtable/kit";
+import { LineApiError, LineError } from "./errors.ts";
+
+/** How the package gets the channel access token it calls LINE with. */
+export type TokenMode = "stateless" | { static: string };
+
+/** The channel's credentials. The secret also verifies every webhook signature. */
+export interface LineCredentials {
+	/** The channel id, a number written as a string. It is not secret. */
+	channelId: string;
+	channelSecret: string;
+	/**
+	 * `"stateless"` (the default) asks LINE for a token of about 15 minutes with the channel id and
+	 * secret, and asks again when it lapses. `{ static: token }` uses a long-lived token a console
+	 * issued; it cannot be reissued, so a `401` is then final.
+	 */
+	token?: TokenMode;
+}
+
+export const LINE_API = "https://api.line.me";
+const TOKEN_PATH = "/oauth2/v3/token";
+/** A token is replaced this long before LINE would refuse it. */
+const EARLY_MS = 60_000;
+/** The request timeout for the token endpoint. */
+const ISSUE_TIMEOUT_MS = 15_000;
+
+export interface TokenSourceOptions {
+	credentials: LineCredentials;
+	/** Replaces `fetch`, for tests. */
+	fetch?: typeof fetch;
+	/** The current time in milliseconds, for tests. */
+	now?: () => number;
+	baseUrl?: string;
+}
+
+interface Issued {
+	token: string;
+	/** Epoch milliseconds after which the token is replaced. */
+	validUntil: number;
+}
+
+/**
+ * Hands out the channel access token. It issues stateless tokens one at a time (concurrent callers
+ * share one request), keeps a token in memory only until a minute before it lapses, and forgets
+ * one LINE rejected. The token and the secret live in private fields: they are in no log, no error
+ * message and no serialized form of this object.
+ */
+export class TokenSource {
+	readonly #id: string;
+	readonly #secret: string;
+	readonly #static: string | undefined;
+	readonly #fetch: typeof fetch;
+	readonly #now: () => number;
+	readonly #base: string;
+	#current: Issued | undefined;
+	#inflight: Promise<Issued> | undefined;
+	#issued = 0;
+	#lastFailure: string | undefined;
+
+	constructor(options: TokenSourceOptions) {
+		const {
+			channelId,
+			channelSecret,
+			token = "stateless",
+		} = options.credentials;
+		if (typeof channelId !== "string" || !/^[0-9]+$/.test(channelId))
+			throw new LineError(
+				"bad_credentials",
+				"line: credentials.channelId must be the channel id, digits written as a string",
+			);
+		if (typeof channelSecret !== "string" || channelSecret.length === 0)
+			throw new LineError(
+				"bad_credentials",
+				"line: credentials.channelSecret must be a non-empty string",
+			);
+		if (
+			token !== "stateless" &&
+			(typeof token !== "object" ||
+				token === null ||
+				typeof token.static !== "string" ||
+				token.static.length === 0)
+		)
+			throw new LineError(
+				"bad_credentials",
+				'line: credentials.token must be "stateless" or { static: <token> }',
+			);
+		this.#id = channelId;
+		this.#secret = channelSecret;
+		this.#static = token === "stateless" ? undefined : token.static;
+		this.#fetch = options.fetch ?? fetch;
+		this.#now = options.now ?? Date.now;
+		this.#base = options.baseUrl ?? LINE_API;
+	}
+
+	get channelId(): string {
+		return this.#id;
+	}
+
+	/**
+	 * Whether `signature` (the base64 `x-line-signature` header) is the HMAC-SHA256 of `body` under
+	 * the channel secret, compared in constant time. The secret itself never leaves this object.
+	 */
+	verifies(body: Uint8Array, signature: string): boolean {
+		const given = Buffer.from(signature, "base64");
+		const expected = createHmac("sha256", this.#secret).update(body).digest();
+		// A signature of another length is wrong; timingSafeEqual would throw on it.
+		return given.length === expected.length && timingSafeEqual(given, expected);
+	}
+
+	/** How many stateless tokens were issued, and the last failure's code; neither holds a secret. */
+	health(): { issued: number; lastFailure: string | undefined } {
+		return { issued: this.#issued, lastFailure: this.#lastFailure };
+	}
+
+	/** A token that is valid now, issuing one when there is none. */
+	async token(): Promise<string> {
+		if (this.#static) return this.#static;
+		const held = this.#current;
+		if (held && held.validUntil > this.#now()) return held.token;
+		this.#inflight ??= this.#issue().finally(() => {
+			this.#inflight = undefined;
+		});
+		return (await this.#inflight).token;
+	}
+
+	/**
+	 * Drops `rejected` when LINE refused it, so the next `token()` issues a new one. Returns whether
+	 * a new token can come: a static token cannot be replaced.
+	 */
+	reject(rejected: string): boolean {
+		if (this.#static) return false;
+		if (this.#current?.token === rejected) this.#current = undefined;
+		return true;
+	}
+
+	async #issue(): Promise<Issued> {
+		let response: Response;
+		try {
+			response = await this.#fetch(`${this.#base}${TOKEN_PATH}`, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({
+					grant_type: "client_credentials",
+					client_id: this.#id,
+					client_secret: this.#secret,
+				}),
+				signal: AbortSignal.timeout(ISSUE_TIMEOUT_MS),
+			});
+		} catch (error) {
+			this.#lastFailure = "token_unreachable";
+			throw new LineError(
+				"token_unreachable",
+				`line: the token endpoint did not answer (${this.redact(error instanceof Error ? error.message : String(error))})`,
+			);
+		}
+		if (!response.ok) {
+			this.#lastFailure = "token_refused";
+			// The body is not read into the message: an endpoint may echo what it was sent.
+			await response.body?.cancel().catch(() => undefined);
+			throw new LineApiError(
+				response.status,
+				"token_refused",
+				`line: the token endpoint answered ${response.status}`,
+				response.headers.get("x-line-request-id") ?? undefined,
+			);
+		}
+		const body = (await response.json().catch(() => undefined)) as
+			| { access_token?: unknown; expires_in?: unknown }
+			| undefined;
+		const token = body?.access_token;
+		const lifetime = Number(body?.expires_in);
+		if (typeof token !== "string" || token === "" || !(lifetime > 0)) {
+			this.#lastFailure = "token_malformed";
+			throw new LineError(
+				"token_malformed",
+				"line: the token endpoint answered without a usable access token",
+			);
+		}
+		this.#issued++;
+		this.#lastFailure = undefined;
+		const lifeMs = lifetime * 1000;
+		// A very short token still lives for half its life instead of being refused at once.
+		const margin = Math.min(EARLY_MS, lifeMs / 2);
+		const issued = { token, validUntil: this.#now() + lifeMs - margin };
+		this.#current = issued;
+		return issued;
+	}
+
+	/** Text safe to show: credentials are masked and the length is bounded, whatever a failing call quoted. */
+	redact(message: string, max = 200): string {
+		let text = scrubDiagnostic(message, max);
+		for (const secret of [this.#secret, this.#current?.token, this.#static])
+			if (secret)
+				// A form body spells the secret percent-encoded, a header or URL may spell it either way.
+				for (const spelling of new Set([
+					secret,
+					encodeURIComponent(secret),
+					new URLSearchParams({ s: secret }).toString().slice(2),
+				]))
+					text = text.split(spelling).join("[redacted]");
+		return text;
+	}
+
+	toJSON(): { channelId: string; token: string } {
+		return {
+			channelId: this.#id,
+			token: this.#static ? "static" : "stateless",
+		};
+	}
+
+	[Symbol.for("nodejs.util.inspect.custom")](): string {
+		return `TokenSource(${this.#id}, ${this.#static ? "static" : "stateless"})`;
+	}
+}

package/src/webhook.ts

@@ -0,0 +1,110 @@
+import type { SQL } from "bun";
+import type { Logger } from "pi-roundtable";
+import { errorCode, LineError } from "./errors.ts";
+import { parseWebhook } from "./events.ts";
+import { persistEvents } from "./intake.ts";
+import type { TokenSource } from "./token.ts";
+
+/** The most a webhook request body may hold: LINE sends far less, and anything near this is not LINE. */
+export const WEBHOOK_MAX_BYTES = 1024 * 1024;
+
+export interface WebhookOptions {
+	sql: SQL;
+	tokens: TokenSource;
+	logger: Logger;
+	now: () => Date;
+	/** The bot's user id, once known; a webhook for another bot is refused. Unknown means the signature alone vouches. */
+	botUserId: () => string | undefined;
+	/** Called after events were stored, so the worker looks at the inbox now rather than at its next poll. */
+	stored: () => void;
+	maxBytes?: number;
+}
+
+const reply = (status: number, text: string) =>
+	new Response(text, { status, headers: { "cache-control": "no-store" } });
+
+/**
+ * Reads a body of at most `max` bytes; undefined when it is larger. The declared length is
+ * checked first, and a body that lies about it is cut off as soon as it passes the limit.
+ */
+async function readCapped(
+	request: Request,
+	max: number,
+): Promise<Uint8Array | undefined> {
+	const declared = Number(request.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > max) return undefined;
+	if (!request.body) return new Uint8Array();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	const reader = request.body.getReader();
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.byteLength;
+		if (size > max) {
+			await reader.cancel().catch(() => undefined);
+			return undefined;
+		}
+		chunks.push(value);
+	}
+	const body = new Uint8Array(size);
+	let at = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, at);
+		at += chunk.byteLength;
+	}
+	return body;
+}
+
+/**
+ * LINE's webhook: the raw body is verified against `x-line-signature` before anything is parsed,
+ * every event is stored in one transaction, and only then does it answer `200`. A database that
+ * is down answers `500`, which makes LINE's redelivery (if the channel has it on) resend.
+ * An empty `events` array (LINE's Verify button) is a `200` that stores nothing.
+ */
+export function webhookHandler(
+	options: WebhookOptions,
+): (request: Request) => Promise<Response> {
+	const max = options.maxBytes ?? WEBHOOK_MAX_BYTES;
+	return async (request) => {
+		if (request.method !== "POST") return reply(405, "Method Not Allowed");
+		const body = await readCapped(request, max);
+		if (!body) return reply(413, "Payload Too Large");
+		const signature = request.headers.get("x-line-signature");
+		if (!signature || !options.tokens.verifies(body, signature)) {
+			options.logger.warn("a LINE webhook was refused: bad signature");
+			return reply(401, "Unauthorized");
+		}
+		let parsed: Awaited<ReturnType<typeof parseWebhook>>;
+		try {
+			parsed = await parseWebhook(body);
+		} catch (error) {
+			if (!(error instanceof LineError)) throw error;
+			options.logger.warn({ code: error.code }, "a LINE webhook was refused");
+			return reply(400, "Bad Request");
+		}
+		const bot = options.botUserId();
+		if (bot !== undefined && parsed.destination !== bot) {
+			options.logger.warn("a LINE webhook was refused: it is for another bot");
+			return reply(403, "Forbidden");
+		}
+		if (parsed.events.length === 0) return reply(200, "OK");
+		try {
+			const result = await persistEvents(
+				options.sql,
+				parsed.events,
+				options.now(),
+			);
+			options.logger.info(result, "LINE events stored");
+			if (result.queued > 0) options.stored();
+		} catch (error) {
+			// The code only: the message could quote a column of the event being stored.
+			options.logger.error(
+				{ code: errorCode(error) },
+				"LINE events could not be stored",
+			);
+			return reply(500, "Internal Server Error");
+		}
+		return reply(200, "OK");
+	};
+}