pi-roundtable-line 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-14
+
+### Added
+
+- `LINE.health().webhooks.rejected.signatureForBot` counts the requests that failed the signature check and whose body names this bot's user id as its `destination`; they are still counted in `rejected.signature` as well. A scanner does not know the bot's id, so this counter rising while `accepted` stays flat means a wrong channel secret or URL. The body is read only within the existing size limit and is neither logged nor kept; before the plugin knows the bot's id the count stays zero.
+
+### Changed
+
+- `WebhookHealth.rejected` has the new required field `signatureForBot`, so a caller that built a `WebhookHealth` or a `LineBridgePort` of its own must add it.
+- Release in lockstep with pi-roundtable 0.14.0. The core peer range moves to `>=0.14.0 <0.15.0`.
+
+## [0.13.0] - 2026-10-13
+
+### Added
+
+- `LINE.health()` gains `webhooks: WebhookHealth` (new type, exported): `{ accepted, rejected: { signature, destination, malformed }, lastAcceptedAt?, lastRejectedAt? }`, the counts and times of what the webhook has answered since the plugin was set up. `signature` is a missing or wrong signature (401), `destination` a signed webhook for another bot (403), `malformed` a body over the cap or not an events object (413, 400). Nothing of a request but its count is kept.
+
+### Changed
+
+- `LineBridgePort.health()` returns the new `webhooks` field, so a caller that built a `LineBridgePort` of its own, to test a plugin that reads `LINE`, must add it.
+- Release in lockstep with pi-roundtable 0.13.0. The core peer range moves to `>=0.13.0 <0.14.0`.
+
 ## [0.12.1] - 2026-10-13
 
 - Release in lockstep with pi-roundtable 0.12.1; no package-specific behavior changes. The core peer range stays `>=0.12.0 <0.13.0`.

package/README.md

@@ -11,7 +11,7 @@ It covers intake (the credentials and token source, the webhook, the allowlist o
 
 ## Requirements
 
-- Bun 1.3 or later, and pi-roundtable `>=0.12.0 <0.13.0` as a peer dependency.
+- Bun 1.3 or later, and pi-roundtable `>=0.14.0 <0.15.0` as a peer dependency.
 - PostgreSQL, which the host already needs.
 - An HTTP listener on the host that LINE can reach over HTTPS (the webhook URL is set in the channel's settings).
 - A Messaging API channel: its channel id and channel secret.
@@ -81,6 +81,30 @@ An event with a `webhookEventId` already stored is not stored again, so LINE's r
 The bot's user id comes from `GET /v2/bot/info` when the host starts.
 If LINE cannot be reached then, the plugin logs a warning with a code and keeps trying (at most every 30 seconds, when a webhook arrives); until it knows the id a webhook is vouched for by its signature alone.
 
+### Webhook counters
+
+`LINE.health()` returns `{ tokensIssued, tokenFailure, webhooks }`, where `webhooks` is what the webhook has answered since the plugin was set up (it starts at zero with each process):
+
+```ts
+webhooks: {
+	accepted: number; // answered 200, a Verify included
+	rejected: {
+		signature: number; // 401: the signature is missing or wrong
+		signatureForBot: number; // of those, the body names this bot as its destination
+		destination: number; // 403: signed, but for another bot
+		malformed: number; // 400 and 413: not a LINE events object, or over 1 MiB
+	};
+	lastAcceptedAt?: string; // ISO time; left out until there was one
+	lastRejectedAt?: string;
+};
+```
+
+They are counts and times only: no body, address or signature is kept, and a request adds one to a counter and nothing else.
+A `405` and a `500` (the database could not store the events) are in no counter.
+A host that watches for a channel whose webhook URL or secret has drifted can alarm on `rejected.signatureForBot` growing while `accepted` does not: a scanner that finds the URL does not know the bot's user id, so a request that fails its signature yet names this bot as its `destination` is far more likely LINE with a wrong channel secret (or a rotated one) than noise.
+To tell, the handler reads the `destination` of a body that failed its signature, only within the 1 MiB limit, and never logs or keeps it; `signatureForBot` also counts in `signature`.
+Until the plugin knows the bot's user id it cannot tell, and `signatureForBot` stays at zero.
+
 ## Chats and the allowlist
 
 The first event from a chat the bot has not seen records it as `pending`: its key, when it was first and last seen, and counts.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-line",
-	"version": "0.12.1",
+	"version": "0.14.0",
 	"description": "A LINE Messaging API transport for pi-roundtable: a signed webhook that persists events before it answers, a durable inbox worker, and an allowlist of the groups and chats it mirrors",
 	"type": "module",
 	"license": "MIT",
@@ -33,14 +33,14 @@
 		"test": "bun test"
 	},
 	"peerDependencies": {
-		"pi-roundtable": ">=0.12.0 <0.13.0"
+		"pi-roundtable": ">=0.14.0 <0.15.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
 		"@earendil-works/pi-ai": ">=1.0.0 <2",
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.12.1",
+		"pi-roundtable": "0.14.0",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/index.ts

@@ -52,4 +52,5 @@ export type {
 } from "./sources.ts";
 export { LineSurface } from "./surface.ts";
 export type { LineCredentials, TokenMode } from "./token.ts";
+export type { WebhookHealth } from "./webhook.ts";
 export { WEBHOOK_MAX_BYTES } from "./webhook.ts";

package/src/plugin.ts

@@ -21,7 +21,7 @@ import { RetentionSweeper } from "./retention.ts";
 import { PgSources } from "./sources.ts";
 import { LineSurface } from "./surface.ts";
 import { TokenSource } from "./token.ts";
-import { webhookHandler } from "./webhook.ts";
+import { WebhookStats, webhookHandler } from "./webhook.ts";
 
 /**
  * The LINE transport: a webhook on the host's HTTP listener that stores every signed event before
@@ -44,6 +44,7 @@ export function line(options: LineOptions): RoundtablePlugin {
 		setup: (context: PluginContext) => {
 			const sql = context.database();
 			const now = () => context.env.now();
+			const webhooks = new WebhookStats();
 			const api = new LineApi({
 				tokens,
 				...(options.fetch ? { fetch: options.fetch } : {}),
@@ -143,6 +144,7 @@ export function line(options: LineOptions): RoundtablePlugin {
 					return {
 						tokensIssued: health.issued,
 						tokenFailure: health.lastFailure,
+						webhooks: webhooks.health(),
 					};
 				},
 				subscribe: (handler) => {
@@ -212,6 +214,7 @@ export function line(options: LineOptions): RoundtablePlugin {
 							now,
 							botUserId: () => bot.current(),
 							stored: () => worker.kick(),
+							stats: webhooks,
 						}),
 					},
 				],

package/src/port.ts

@@ -3,6 +3,7 @@ import type { LineContentRequest, LineContentResult } from "./content.ts";
 import type { LineSubscriber } from "./messages.ts";
 import type { LineOutbox } from "./outbox.ts";
 import type { LineSources } from "./sources.ts";
+import type { WebhookHealth } from "./webhook.ts";
 
 /** What other plugins read from this one, through the `LINE` service key. */
 export interface LineBridgePort {
@@ -12,8 +13,16 @@ export interface LineBridgePort {
 	readonly outbox: LineOutbox;
 	/** The bot's user id once LINE has told it, else undefined. */
 	botUserId(): string | undefined;
-	/** The token source's health: how many tokens were issued and why the last attempt failed, if it did. */
-	health(): { tokensIssued: number; tokenFailure: string | undefined };
+	/**
+	 * The plugin's health: how many tokens were issued and why the last attempt failed, if it did, and
+	 * what the webhook has answered since the plugin was set up (`webhooks`: counts and times only,
+	 * never a body, an address or a signature).
+	 */
+	health(): {
+		tokensIssued: number;
+		tokenFailure: string | undefined;
+		webhooks: WebhookHealth;
+	};
 	/**
 	 * Becomes the one consumer of the package: from now on each stored event of an allowed chat, the
 	 * `join` and `leave` of any chat that is not blocked, and an `unsend` stored while its chat was

package/src/webhook.ts

@@ -8,6 +8,70 @@ 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;
 
+/** What the webhook has answered since the plugin was set up: counts and times only, never a body, address or signature. */
+export interface WebhookHealth {
+	/** Requests with a valid signature for this bot that were answered `200` (an empty Verify included). */
+	accepted: number;
+	/**
+	 * Requests turned away: `signature` is a missing or wrong `x-line-signature`, `signatureForBot`
+	 * is the part of those whose body names this bot as its `destination` (a scanner does not know
+	 * the bot's id, so it rising while `accepted` stays flat means a wrong channel secret or URL),
+	 * `destination` is a signed webhook for another bot, `malformed` is a body that is too large or
+	 * not a webhook.
+	 */
+	rejected: {
+		signature: number;
+		signatureForBot: number;
+		destination: number;
+		malformed: number;
+	};
+	/** When the last request was accepted, as an ISO time; left out until one was. */
+	lastAcceptedAt?: string;
+	/** When the last request was rejected, as an ISO time; left out until one was. */
+	lastRejectedAt?: string;
+}
+
+/** The webhook's counters: each request adds to one of them and nothing else is kept. */
+export class WebhookStats {
+	#accepted = 0;
+	#rejected = {
+		signature: 0,
+		signatureForBot: 0,
+		destination: 0,
+		malformed: 0,
+	};
+	#acceptedAt: string | undefined;
+	#rejectedAt: string | undefined;
+
+	accept(at: Date): void {
+		this.#accepted++;
+		this.#acceptedAt = at.toISOString();
+	}
+
+	reject(
+		reason: Exclude<keyof WebhookHealth["rejected"], "signatureForBot">,
+		at: Date,
+	): void {
+		this.#rejected[reason]++;
+		this.#rejectedAt = at.toISOString();
+	}
+
+	/** A refused signature; `forBot` when the body names this bot, which counts in `signatureForBot` too. */
+	rejectSignature(forBot: boolean, at: Date): void {
+		this.reject("signature", at);
+		if (forBot) this.#rejected.signatureForBot++;
+	}
+
+	health(): WebhookHealth {
+		return {
+			accepted: this.#accepted,
+			rejected: { ...this.#rejected },
+			...(this.#acceptedAt ? { lastAcceptedAt: this.#acceptedAt } : {}),
+			...(this.#rejectedAt ? { lastRejectedAt: this.#rejectedAt } : {}),
+		};
+	}
+}
+
 export interface WebhookOptions {
 	sql: SQL;
 	tokens: TokenSource;
@@ -17,6 +81,8 @@ export interface WebhookOptions {
 	botUserId: () => string | undefined;
 	/** Called after events were stored, so the worker looks at the inbox now rather than at its next poll. */
 	stored: () => void;
+	/** Counts what the webhook answers; the plugin reads it for `LINE.health()`. */
+	stats: WebhookStats;
 	maxBytes?: number;
 }
 
@@ -56,22 +122,50 @@ async function readCapped(
 	return body;
 }
 
+/**
+ * The `destination` a body that failed its signature claims, only to tell a request meant for this
+ * bot from a scan. The body is already within the size limit; it is neither logged nor kept, and a
+ * body that is not JSON, or has no text `destination`, names nobody.
+ */
+function claimedDestination(body: Uint8Array): string | undefined {
+	try {
+		const value: unknown = JSON.parse(
+			new TextDecoder("utf-8", { fatal: true }).decode(body),
+		);
+		if (typeof value !== "object" || value === null) return undefined;
+		const destination = (value as { destination?: unknown }).destination;
+		return typeof destination === "string" ? destination : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /**
  * 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.
+ * An empty `events` array (LINE's Verify button) is a `200` that stores nothing. Each answer adds
+ * to `options.stats`, which keeps counts and times only.
  */
 export function webhookHandler(
 	options: WebhookOptions,
 ): (request: Request) => Promise<Response> {
 	const max = options.maxBytes ?? WEBHOOK_MAX_BYTES;
+	const { stats } = options;
 	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");
+		if (!body) {
+			stats.reject("malformed", options.now());
+			return reply(413, "Payload Too Large");
+		}
 		const signature = request.headers.get("x-line-signature");
 		if (!signature || !options.tokens.verifies(body, signature)) {
+			const bot = options.botUserId();
+			stats.rejectSignature(
+				bot !== undefined && claimedDestination(body) === bot,
+				options.now(),
+			);
 			options.logger.warn("a LINE webhook was refused: bad signature");
 			return reply(401, "Unauthorized");
 		}
@@ -80,15 +174,20 @@ export function webhookHandler(
 			parsed = await parseWebhook(body);
 		} catch (error) {
 			if (!(error instanceof LineError)) throw error;
+			stats.reject("malformed", options.now());
 			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) {
+			stats.reject("destination", options.now());
 			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");
+		if (parsed.events.length === 0) {
+			stats.accept(options.now());
+			return reply(200, "OK");
+		}
 		try {
 			const result = await persistEvents(
 				options.sql,
@@ -105,6 +204,7 @@ export function webhookHandler(
 			);
 			return reply(500, "Internal Server Error");
 		}
+		stats.accept(options.now());
 		return reply(200, "OK");
 	};
 }