@graygate/bot-sdk 0.1.0

package/dist/wire/webhook.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Generated from protocol/src/rest.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.botWebhookBody = exports.botWebhookItem = void 0;
+const constants_1 = require("./constants");
+const events_1 = require("./events");
+const zod_1 = require("zod");
+const uuid = zod_1.z.string().uuid();
+/**
+ * The webhook body a bot receives. Each item has **the same shape** as the payload the WebSocket
+ * pushes to a phone.
+ *
+ * What leaves is ciphertext, so a webhook delivered to the wrong address leaks the metadata around
+ * a message — room id, sender id, timestamp — and not what was said.
+ */
+exports.botWebhookItem = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({ type: zod_1.z.literal('msg.new'), payload: events_1.msgNewPayload }),
+    zod_1.z.object({ type: zod_1.z.literal('envelope.new'), payload: events_1.envelopeNewPayload }),
+    zod_1.z.object({ type: zod_1.z.literal('member.joined'), payload: zod_1.z.object({ roomId: uuid, userId: uuid }) }),
+    zod_1.z.object({ type: zod_1.z.literal('member.left'), payload: zod_1.z.object({ roomId: uuid, userId: uuid }) }),
+    zod_1.z.object({
+        type: zod_1.z.literal('member.key_changed'),
+        payload: zod_1.z.object({ roomId: uuid, userId: uuid, keyUpdatedAt: zod_1.z.string().datetime() }),
+    }),
+    zod_1.z.object({ type: zod_1.z.literal('room.deleted'), payload: zod_1.z.object({ roomId: uuid }) }),
+]);
+exports.botWebhookBody = zod_1.z.object({
+    botId: uuid,
+    items: zod_1.z.array(exports.botWebhookItem).max(constants_1.BOT_WEBHOOK_BATCH_MAX),
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@graygate/bot-sdk",
+  "version": "0.1.0",
+  "description": "Runtime SDK for graygate bots — webhook receiver, signature verification, end-to-end encryption.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/graygate/bot-sdk.git"
+  },
+  "homepage": "https://graygate.app/bots/",
+  "bugs": {
+    "url": "https://github.com/graygate/bot-sdk/issues"
+  },
+  "keywords": [
+    "graygate",
+    "bot",
+    "sdk",
+    "webhook",
+    "end-to-end-encryption",
+    "messaging"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0",
+    "graygate-cypher": "^1.0.4",
+    "node-forge": "^1.3.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^22.0.0",
+    "@types/node-forge": "^1.3.11",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,111 @@
+import { BOT_CLIENT_TOKEN } from './wire';
+
+/**
+ * The REST client between a bot runtime and the graygate server.
+ *
+ * Access tokens last fifteen minutes and are kept **in memory only**; when one is close to expiring
+ * it is traded for another using the bot token. There is no refresh token because the bot token is
+ * itself the long-lived credential. That token never leaves this object — not into a log, not into
+ * the state directory.
+ */
+
+export class BotApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string,
+    message?: string,
+  ) {
+    super(message ?? code);
+    this.name = 'BotApiError';
+  }
+}
+
+/** Renew this long before expiry (ms), so a token cannot die between the check and the request. */
+const REFRESH_MARGIN_MS = 60_000;
+
+export class BotApi {
+  private accessToken: string | null = null;
+  private expiresAt = 0;
+  private botId: string | null = null;
+  private userId: string | null = null;
+
+  constructor(
+    private readonly origin: string,
+    private readonly token: string,
+  ) {}
+
+  get ids(): { botId: string | null; userId: string | null } {
+    return { botId: this.botId, userId: this.userId };
+  }
+
+  private async ensureAuth(): Promise<string> {
+    if (this.accessToken && Date.now() < this.expiresAt - REFRESH_MARGIN_MS) return this.accessToken;
+    const res = await this.raw('POST', '/bot/auth', { token: this.token }, null);
+    this.accessToken = res.accessToken as string;
+    this.botId = res.botId as string;
+    this.userId = (res.userId as string | null) ?? null;
+    // The lifetime is fixed at BOT_ACCESS_TOKEN_TTL_MIN; there is nothing to recompute here.
+    this.expiresAt = Date.now() + 15 * 60_000;
+    return this.accessToken;
+  }
+
+  private async raw(
+    method: string,
+    path: string,
+    body: unknown,
+    access: string | null,
+  ): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.origin}${path}`, {
+      method,
+      headers: {
+        ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        // Client header for the edge in front of the server. Not a secret; see BOT_CLIENT_TOKEN.
+        'x-graygate-client': BOT_CLIENT_TOKEN,
+        ...(access ? { authorization: `Bearer ${access}` } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const json = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+    if (!res.ok) {
+      const err = (json.error ?? {}) as { code?: string; message?: string };
+      throw new BotApiError(res.status, err.code ?? 'error', err.message);
+    }
+    return json;
+  }
+
+  async call(method: string, path: string, body?: unknown): Promise<Record<string, unknown>> {
+    const access = await this.ensureAuth();
+    try {
+      return await this.raw(method, path, body, access);
+    } catch (err) {
+      // The access token expired early — trade for another one and retry, once.
+      if (err instanceof BotApiError && err.status === 401) {
+        this.accessToken = null;
+        return this.raw(method, path, body, await this.ensureAuth());
+      }
+      throw err;
+    }
+  }
+
+  /** For endpoints that answer with an array (`GET /invites`, member lists). */
+  async callList(method: string, path: string, body?: unknown): Promise<unknown[]> {
+    const access = await this.ensureAuth();
+    const res = await fetch(`${this.origin}${path}`, {
+      method,
+      headers: {
+        ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        'x-graygate-client': BOT_CLIENT_TOKEN,
+        authorization: `Bearer ${access}`,
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : [];
+    if (!res.ok) {
+      const err = (json.error ?? {}) as { code?: string; message?: string };
+      throw new BotApiError(res.status, err.code ?? 'error', err.message);
+    }
+    return Array.isArray(json) ? json : [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,369 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import {
+  COMMENT_TEXT_MAX,
+  botWebhookBody,
+  messageBodySchema,
+  type BotWebhookItem,
+  type MessageBody,
+} from './wire';
+import {
+  decryptMessage,
+  encryptMessage,
+  generateRsaKeyPair,
+  unwrapRoomKey,
+  type EncryptedMessage,
+} from './wire';
+import { BotApi, BotApiError } from './api';
+import { BotState } from './state';
+import { tokenSecret, verifyWebhookSignature } from './signature';
+
+export { BotApiError } from './api';
+export { verifyWebhookSignature, webhookSigningKey } from './signature';
+
+/**
+ * The graygate bot runtime.
+ *
+ * Four things happen here: it authenticates with the bot token and, on a first run, generates a key
+ * pair and activates the account; it receives webhooks, **verifies the signature before anything
+ * else**, and consumes envelopes to learn room keys; it decrypts messages and hands them to your
+ * handlers; and it encrypts replies and posts them back.
+ *
+ * Every cryptographic operation goes through the wire module — no hand-rolled crypto here.
+ *
+ * **Media handed to a handler is unverified.** This runtime is not a renderer, and what you do with
+ * those bytes is yours to decide: do not pass them straight to an image decoder or a file path.
+ */
+
+export interface BotOptions {
+  /** `gg1.<botId>.<secret>`. Read it from the environment; never write it to a file. */
+  token: string;
+  /** Server origin. Bots do not use the app's fallback-domain logic — you choose the address. */
+  origin?: string;
+  /** Where the private key, the room keys and the handled ids live. **Back this up.** */
+  stateDir: string;
+  webhook: {
+    port: number;
+    /** Defaults to `/hook`. */
+    path?: string;
+    /** The public https address to register. Private and loopback addresses are refused. */
+    publicUrl: string;
+    /** Bind to one interface only — `127.0.0.1` when a reverse proxy sits in front. */
+    host?: string;
+  };
+  /** Defaults to true; set false to decide inside `bot.on('invite')`. */
+  autoAcceptInvites?: boolean;
+}
+
+export interface MessageContext {
+  roomId: string;
+  messageId: string;
+  senderId: string;
+  body: MessageBody;
+  /** The text, when `body.t === 'text'`. */
+  text: string | null;
+  reply(text: string): Promise<void>;
+}
+
+export interface JoinContext {
+  roomId: string;
+  userId: string;
+  reply(text: string): Promise<void>;
+}
+
+export interface InviteContext {
+  inviteId: string;
+  roomId: string;
+  accept(): Promise<void>;
+  decline(): Promise<void>;
+}
+
+export interface CommandContext extends MessageContext {
+  command: string;
+  args: string;
+}
+
+type MessageHandler = (ctx: MessageContext) => void | Promise<void>;
+type JoinHandler = (ctx: JoinContext) => void | Promise<void>;
+type InviteHandler = (ctx: InviteContext) => void | Promise<void>;
+type CommandHandler = (ctx: CommandContext) => void | Promise<void>;
+
+export class Bot {
+  private readonly api: BotApi;
+  private readonly state: BotState;
+  private readonly secret: string;
+  private readonly path: string;
+  private server: Server | null = null;
+  private username = '';
+
+  private messageHandlers: MessageHandler[] = [];
+  private joinHandlers: JoinHandler[] = [];
+  private inviteHandlers: InviteHandler[] = [];
+  private commandHandlers = new Map<string, CommandHandler>();
+
+  constructor(private readonly options: BotOptions) {
+    this.api = new BotApi(options.origin ?? 'https://server.graygate.app', options.token);
+    this.state = new BotState(options.stateDir);
+    this.secret = tokenSecret(options.token);
+    this.path = options.webhook.path ?? '/hook';
+  }
+
+  on(event: 'message', handler: MessageHandler): void;
+  on(event: 'join', handler: JoinHandler): void;
+  on(event: 'invite', handler: InviteHandler): void;
+  on(event: 'message' | 'join' | 'invite', handler: MessageHandler | JoinHandler | InviteHandler): void {
+    if (event === 'message') this.messageHandlers.push(handler as MessageHandler);
+    else if (event === 'join') this.joinHandlers.push(handler as JoinHandler);
+    else this.inviteHandlers.push(handler as InviteHandler);
+  }
+
+  /** A command such as `/start`. Names are ASCII lowercase, digits and underscores. */
+  command(name: string, handler: CommandHandler): void {
+    this.commandHandlers.set(name, handler);
+  }
+
+  /**
+   * Starts the bot: activates it (generating a key pair on a first run), serves the webhook, and
+   * registers it. **Registering is also the request for a backfill** — there is no polling, so this
+   * is when everything that piled up while the bot was down comes in.
+   */
+  async start(): Promise<void> {
+    await this.ensureActivated();
+    await this.listen();
+    await this.api.call('PUT', '/bot/webhook', { url: this.options.webhook.publicUrl });
+  }
+
+  async stop(): Promise<void> {
+    const server = this.server;
+    this.server = null;
+    if (!server) return;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+
+  private async ensureActivated(): Promise<void> {
+    const me = await this.api.call('POST', '/bot/auth', undefined).catch(() => null);
+    void me; // The client handles authentication; all this decides is whether we are active.
+    const profile = await this.api.call('GET', '/bot/me');
+    this.username = String(profile.username ?? '');
+    if (profile.active === true) {
+      if (!this.state.readPrivateKey()) {
+        throw new Error(
+          'This bot is active but the state directory has no private key, so its old room keys are ' +
+            'gone. Replace the key with PUT /bot/public-key and ask each room admin to invite it again.',
+        );
+      }
+      return;
+    }
+    const pair = await generateRsaKeyPair();
+    this.state.writePrivateKey(pair.privateKeyPem);
+    await this.api.call('POST', '/bot/activate', { rsaPublicKey: pair.publicKeyPem });
+  }
+
+  private listen(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => {
+        void this.handleRequest(req, res).catch(() => {
+          // A throwing handler answers non-2xx, and the server sends the batch again.
+          if (!res.headersSent) res.writeHead(500);
+          res.end();
+        });
+      });
+      server.on('error', reject);
+      server.listen(this.options.webhook.port, this.options.webhook.host, () => {
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (req.method !== 'POST' || (req.url ?? '').split('?')[0] !== this.path) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    const raw = await readBody(req);
+    const signature = req.headers['x-graygate-signature'];
+    if (!verifyWebhookSignature(this.secret, Array.isArray(signature) ? signature[0] : signature, raw)) {
+      // A request with a bad signature is not even parsed.
+      res.writeHead(401);
+      res.end();
+      return;
+    }
+
+    const parsed = botWebhookBody.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+      res.writeHead(400);
+      res.end();
+      return;
+    }
+
+    /**
+     * 2xx goes back only once every handler has finished without throwing. A 2xx **is** the
+     * acknowledgement: answer it after a failure and the message is dropped from the server's queue
+     * for good. Anything else and the server retries after a backoff.
+     */
+    for (const item of parsed.data.items) await this.handleItem(item);
+    res.writeHead(200);
+    res.end();
+  }
+
+  private async handleItem(item: BotWebhookItem): Promise<void> {
+    switch (item.type) {
+      case 'envelope.new': {
+        const privateKey = this.state.readPrivateKey();
+        if (!privateKey) return;
+        const roomKey = await unwrapRoomKey(item.payload.ciphertext, privateKey);
+        this.state.putRoomKey(item.payload.roomId, item.payload.keyVersion, roomKey);
+        if (item.payload.purpose === 'invite') await this.onInvite(item.payload.roomId);
+        return;
+      }
+      case 'msg.new': {
+        // At-least-once delivery: the same item can arrive twice.
+        if (this.state.markSeen(item.payload.id)) return;
+        const roomKey = this.state.roomKey(item.payload.roomId, item.payload.keyVersion);
+        // No key, no way to open it. **Acknowledge anyway** — refusing would replay it for 14 days.
+        if (!roomKey) return;
+        let body: unknown;
+        try {
+          body = await decryptMessage(roomKey, item.payload.ciphertext as unknown as EncryptedMessage);
+        } catch {
+          return; // Integrity check failed — dropped quietly, exactly as a phone would.
+        }
+        const parsed = messageBodySchema.safeParse(body);
+        if (!parsed.success) return;
+        await this.dispatchMessage(item.payload.roomId, item.payload.id, item.payload.senderId, parsed.data);
+        return;
+      }
+      case 'member.joined': {
+        for (const handler of this.joinHandlers) {
+          await handler({
+            roomId: item.payload.roomId,
+            userId: item.payload.userId,
+            reply: (text) => this.send(item.payload.roomId, text),
+          });
+        }
+        return;
+      }
+      case 'room.deleted': {
+        this.state.forgetRoom(item.payload.roomId);
+        return;
+      }
+      case 'member.left':
+      case 'member.key_changed':
+        return;
+    }
+  }
+
+  private async dispatchMessage(
+    roomId: string,
+    messageId: string,
+    senderId: string,
+    body: MessageBody,
+  ): Promise<void> {
+    const text = body.t === 'text' ? body.text : null;
+    const ctx: MessageContext = {
+      roomId,
+      messageId,
+      senderId,
+      body,
+      text,
+      reply: (value) => this.send(roomId, value),
+    };
+
+    if (text?.startsWith('/')) {
+      const [head, ...rest] = text.slice(1).split(/\s+/);
+      // With more than one bot in a room people write `/start@some_bot`; ignore other bots' commands.
+      const [name, target] = (head ?? '').split('@');
+      if (!target || target === this.username) {
+        const handler = this.commandHandlers.get(name ?? '');
+        if (handler) {
+          await handler({ ...ctx, command: name ?? '', args: rest.join(' ') });
+          return;
+        }
+      }
+    }
+
+    for (const handler of this.messageHandlers) await handler(ctx);
+  }
+
+  private async onInvite(roomId: string): Promise<void> {
+    const invites = (await this.api.callList('GET', '/invites')) as { id: string; roomId: string }[];
+    const invite = invites.find((i) => i.roomId === roomId);
+    if (!invite) return;
+    const ctx: InviteContext = {
+      inviteId: invite.id,
+      roomId,
+      accept: async () => {
+        await this.api.call('POST', `/invites/${invite.id}/accept`, {});
+      },
+      decline: async () => {
+        await this.api.call('POST', `/invites/${invite.id}/decline`, {});
+      },
+    };
+    if (this.inviteHandlers.length === 0) {
+      if (this.options.autoAcceptInvites !== false) await ctx.accept();
+      return;
+    }
+    for (const handler of this.inviteHandlers) await handler(ctx);
+  }
+
+  /** Sends text. Does nothing when there is no room key — not invited yet, or removed. */
+  async send(roomId: string, text: string): Promise<void> {
+    const key = this.state.latestRoomKey(roomId);
+    if (!key) return;
+    // The length limit is enforced here before sending, the same place a phone enforces it.
+    const trimmed = text.slice(0, 8000);
+    const ciphertext = await encryptMessage(key.roomKey, { t: 'text', text: trimmed } satisfies MessageBody);
+    try {
+      await this.api.call('POST', '/bot/messages', {
+        id: randomUUID(),
+        roomId,
+        keyVersion: key.keyVersion,
+        kind: 'text',
+        ciphertext,
+      });
+    } catch (err) {
+      // The room key moved on; the next envelope arrives by webhook and the next send works.
+      if (err instanceof BotApiError && (err.code === 'stale_key' || err.code === 'not_member')) return;
+      throw err;
+    }
+  }
+
+  /** Comments on a post — channels only; carries the parent post's id. */
+  async replyToPost(roomId: string, parentId: string, text: string): Promise<void> {
+    const key = this.state.latestRoomKey(roomId);
+    if (!key) return;
+    const ciphertext = await encryptMessage(key.roomKey, {
+      t: 'text',
+      text: text.slice(0, COMMENT_TEXT_MAX),
+      parentId,
+    } satisfies MessageBody);
+    await this.api.call('POST', '/bot/messages', {
+      id: randomUUID(),
+      roomId,
+      keyVersion: key.keyVersion,
+      kind: 'text',
+      ciphertext,
+    });
+  }
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    let size = 0;
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      // A body far past the batch limit did not come from the graygate server.
+      if (size > 8 * 1024 * 1024) {
+        req.destroy();
+        reject(new Error('body too large'));
+        return;
+      }
+      data += chunk.toString('utf8');
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}

package/src/signature.test.ts

@@ -0,0 +1,37 @@
+/**
+ * The signature only works if **the server and the bot runtime compute the same value.**
+ *
+ * The two implementations deliberately do not import each other: the server pulling in this package
+ * would blur the line that keeps it a relay and nothing more. Instead both sides pin **the same
+ * fixed vector**, so changing the algorithm breaks both tests at once.
+ */
+import { describe, expect, it } from 'vitest';
+import { verifyWebhookSignature, webhookSigningKey } from './signature';
+import { createHmac } from 'node:crypto';
+
+const SECRET = 'test-secret';
+const T = 1_700_000_000;
+const BODY = '{"botId":"b","items":[]}';
+/** The same value the server's own signature test pins. */
+const VECTOR = '97e0c9ab16c9698d7d8b62875e857cefef01def27a5d95e38fdecda714318a52';
+
+describe('webhook signature', () => {
+  it('matches the fixed vector, so both implementations agree', () => {
+    const mac = createHmac('sha256', webhookSigningKey(SECRET)).update(`${T}.${BODY}`).digest('hex');
+    expect(mac).toBe(VECTOR);
+  });
+
+  it('accepts only a correct signature', () => {
+    expect(verifyWebhookSignature(SECRET, `t=${T},v1=${VECTOR}`, BODY, T)).toBe(true);
+    expect(verifyWebhookSignature(SECRET, `t=${T},v1=${VECTOR}`, `${BODY} `, T)).toBe(false);
+    expect(verifyWebhookSignature('other-secret', `t=${T},v1=${VECTOR}`, BODY, T)).toBe(false);
+    expect(verifyWebhookSignature(SECRET, undefined, BODY, T)).toBe(false);
+    expect(verifyWebhookSignature(SECRET, 'garbage', BODY, T)).toBe(false);
+  });
+
+  it('treats a timestamp outside the tolerance as a replay', () => {
+    expect(verifyWebhookSignature(SECRET, `t=${T},v1=${VECTOR}`, BODY, T + 299)).toBe(true);
+    expect(verifyWebhookSignature(SECRET, `t=${T},v1=${VECTOR}`, BODY, T + 301)).toBe(false);
+    expect(verifyWebhookSignature(SECRET, `t=${T},v1=${VECTOR}`, BODY, T - 301)).toBe(false);
+  });
+});

package/src/signature.ts

@@ -0,0 +1,51 @@
+import { createHash, createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+import { BOT_WEBHOOK_SIGNATURE_TOLERANCE_S } from './wire';
+
+/**
+ * Webhook signature verification — **the same computation the server performs** when it signs.
+ *
+ * The key is derived with HKDF from the sha256 of the token's secret part. The server stores only
+ * that hash and never the secret itself, so the hash is the one value both sides can arrive at.
+ *
+ * A request that fails verification is **discarded without being read.** A webhook address is a
+ * public HTTPS endpoint that anyone can POST to; without the check, a stranger's "message" would
+ * walk straight into the bot's handlers.
+ */
+
+export function webhookSigningKey(tokenSecret: string): Buffer {
+  const tokenHash = createHash('sha256').update(tokenSecret).digest('hex');
+  return Buffer.from(hkdfSync('sha256', Buffer.from(tokenHash, 'hex'), Buffer.alloc(0), 'graygate:bot-webhook-v1', 32));
+}
+
+/**
+ * True when the header reads `t=<unix seconds>,v1=<hex>` and the HMAC matches this body. A
+ * timestamp outside the tolerance is treated as a replay.
+ */
+export function verifyWebhookSignature(
+  tokenSecret: string,
+  header: string | undefined,
+  rawBody: string,
+  nowS = Math.floor(Date.now() / 1000),
+): boolean {
+  if (!header) return false;
+  const parts = Object.fromEntries(
+    header.split(',').map((piece) => {
+      const [k, v] = piece.split('=');
+      return [k?.trim() ?? '', v?.trim() ?? ''];
+    }),
+  );
+  const t = Number(parts.t);
+  const v1 = parts.v1;
+  if (!Number.isFinite(t) || !v1) return false;
+  if (Math.abs(nowS - t) > BOT_WEBHOOK_SIGNATURE_TOLERANCE_S) return false;
+
+  const expected = createHmac('sha256', webhookSigningKey(tokenSecret)).update(`${t}.${rawBody}`).digest();
+  const given = Buffer.from(v1, 'hex');
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+/** The secret part of a `gg1.<botId>.<secret>` token — the material the signing key comes from. */
+export function tokenSecret(token: string): string {
+  const parts = token.split('.');
+  return parts.length === 3 ? parts[2]! : '';
+}