@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/node_modules/@metro-labs/telegram-bot/src/observed-chats.ts

@@ -0,0 +1,172 @@
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import {
+  DIRECTORY_LIMIT,
+  type ChannelEntry,
+  type ChannelSnapshot,
+} from '@metro-labs/core/stations/channel-directory';
+import { lineOf } from './accounts.js';
+import type { TgChat, TgMsg, TgMyChatMember, TgUpdate } from './types.js';
+
+type Metadata = Omit<ChannelEntry, 'line'>;
+
+const kinds = new Set(['direct', 'group', 'channel', 'thread']);
+const chatId = (id: number): boolean => Number.isSafeInteger(id) && id !== 0;
+const cleanName = (name: string | undefined): string | undefined =>
+  name?.trim() ? Array.from(name.trim()).slice(0, 256).join('') : undefined;
+
+function kindOf(chat: TgChat): Metadata['kind'] | undefined {
+  if (chat.type === 'private') return 'direct';
+  if (chat.type === 'group' || chat.type === 'supergroup') return 'group';
+  if (chat.type === 'channel') return 'channel';
+  return undefined;
+}
+
+function metadataOf(raw: unknown): Metadata | undefined {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || typeof raw.kind !== 'string') return undefined;
+  if (!/^-?[1-9]\d*(\/[1-9]\d*)?$/.test(raw.id) || !kinds.has(raw.kind)) return undefined;
+  const parts = raw.id.split('/').map(Number);
+  if (!parts.every(chatId) || (raw.kind === 'thread') !== (parts.length === 2)) return undefined;
+  const name = typeof raw.name === 'string' ? cleanName(raw.name) : undefined;
+  return { id: raw.id, kind: raw.kind as Metadata['kind'], ...(name ? { name } : {}) };
+}
+
+function savedMetadata(account: string, file: string): unknown[] {
+  const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  if (!isRecord(raw) || raw.version !== 1 || raw.account !== account || !Array.isArray(raw.channels))
+    throw new Error('invalid observed chat metadata');
+  return raw.channels.slice(-DIRECTORY_LIMIT);
+}
+
+function topicIdOf(message: TgMsg): number | undefined {
+  if (!message.is_topic_message || message.chat.type !== 'supergroup' || !chatId(message.chat.id)) return undefined;
+  const id = message.message_thread_id;
+  return id !== undefined && Number.isSafeInteger(id) && id > 0 ? id : undefined;
+}
+
+function loaded(account: string, file: string | undefined): Map<string, Metadata> {
+  const entries = new Map<string, Metadata>();
+  if (file === undefined) return entries;
+  try {
+    for (const value of savedMetadata(account, file)) {
+      const entry = metadataOf(value);
+      if (entry) entries.set(entry.id, entry);
+    }
+  } catch (err) {
+    if (!isRecord(err) || err.code !== 'ENOENT')
+      log.warn({ account, err: errMsg(err) }, 'telegram-bot: could not load observed chats');
+  }
+  return entries;
+}
+
+export class ObservedChats {
+  private readonly entries: Map<string, Metadata>;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(private readonly account: string, private readonly file?: string) {
+    this.entries = loaded(account, file);
+  }
+
+  snapshot(): ChannelSnapshot {
+    const channels = [...this.entries.values()].map((entry) => {
+      const [chat, topic] = entry.id.split('/');
+      return { ...entry, line: lineOf(this.account, chat ?? '', topic === undefined ? undefined : Number(topic)) };
+    });
+    return {
+      channels,
+      capability: {
+        supported: true,
+        complete: false,
+        source: 'local',
+        reason: `Telegram Bot API has no all-chats API. Only chat and topic metadata observed in updates on this box is available, up to ${DIRECTORY_LIMIT} entries; unobserved chats and missed updates are not included.`,
+      },
+    };
+  }
+
+  observe(update: TgUpdate): void {
+    for (const message of [update.message, update.channel_post])
+      if (message) this.message(message);
+    for (const event of [update.message_reaction, update.message_reaction_count])
+      if (event) this.chat(event.chat);
+    if (update.my_chat_member) this.membership(update.my_chat_member);
+  }
+
+  flush(): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = undefined;
+    if (this.file === undefined) return;
+    writeSecure(this.file, JSON.stringify({ version: 1, account: this.account, channels: [...this.entries.values()] }));
+  }
+
+  private changed(): void {
+    if (this.file === undefined || this.timer !== undefined) return;
+    this.timer = setTimeout(() => {
+      try {
+        this.flush();
+      } catch (err) {
+        log.warn({ account: this.account, err: errMsg(err) }, 'telegram-bot: could not save observed chats');
+      }
+    }, 2000);
+    this.timer.unref();
+  }
+
+  private note(entry: Metadata): void {
+    const previous = this.entries.get(entry.id);
+    const name = entry.name ?? previous?.name;
+    this.entries.delete(entry.id);
+    this.entries.set(entry.id, { id: entry.id, kind: entry.kind, ...(name ? { name } : {}) });
+    if (this.entries.size > DIRECTORY_LIMIT) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined) this.entries.delete(oldest);
+    }
+    if (!previous || previous.name !== name || previous.kind !== entry.kind) this.changed();
+  }
+
+  private remove(id: number): void {
+    for (const key of this.entries.keys()) {
+      if (key === String(id) || key.startsWith(`${id}/`)) {
+        this.entries.delete(key);
+        this.changed();
+      }
+    }
+  }
+
+  private chat(chat: TgChat): void {
+    const kind = kindOf(chat);
+    if (!chatId(chat.id) || kind === undefined) return;
+    const name = cleanName(kind === 'direct'
+      ? [chat.first_name, chat.last_name].map((part) => part?.trim()).filter(Boolean).join(' ') || (chat.username ? `@${chat.username}` : undefined)
+      : chat.title);
+    this.note({ id: String(chat.id), kind, ...(name ? { name } : {}) });
+  }
+
+  private message(message: TgMsg): void {
+    if (message.migrate_to_chat_id !== undefined && chatId(message.migrate_to_chat_id)) {
+      this.remove(message.chat.id);
+      this.chat({ ...message.chat, id: message.migrate_to_chat_id, type: 'supergroup' });
+      return;
+    }
+    if (message.migrate_from_chat_id !== undefined && chatId(message.migrate_from_chat_id))
+      this.remove(message.migrate_from_chat_id);
+    this.chat(message.chat);
+    this.topic(message);
+  }
+
+  private topic(message: TgMsg): void {
+    const topic = topicIdOf(message);
+    if (topic === undefined) return;
+    const name = cleanName(message.forum_topic_edited?.name ?? message.forum_topic_created?.name);
+    this.note({ id: `${message.chat.id}/${topic}`, kind: 'thread', ...(name ? { name } : {}) });
+  }
+
+  private membership(update: TgMyChatMember): void {
+    const { status, is_member: isMember } = update.new_chat_member;
+    if (status === 'left' || status === 'kicked' || (status === 'restricted' && isMember === false))
+      this.remove(update.chat.id);
+    else if (status === 'creator' || status === 'administrator' || status === 'member'
+      || (status === 'restricted' && isMember === true))
+      this.chat(update.chat);
+  }
+}

package/runtime/node_modules/@metro-labs/telegram-bot/src/profile.ts

@@ -0,0 +1,85 @@
+import { appendFile } from '@metro-labs/core/stations/attachments';
+import {
+  assertImage,
+  fieldsOf,
+  parseProfileChange,
+  type ProfileApplied,
+  type ProfileAvatar,
+  type ProfileChange,
+} from '@metro-labs/core/stations/profile';
+import { makeProfileCache, nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountFor, accounts, tg } from './accounts.js';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+
+async function setPhoto(accountId: string, avatar: ProfileAvatar): Promise<void> {
+  assertImage(avatar);
+  const form = new FormData();
+  form.append('photo', JSON.stringify({ type: 'static', photo: 'attach://avatar' }));
+  await appendFile(form, 'avatar', avatar.path, avatar.name);
+  await tg(accountId, 'setMyProfilePhoto', form);
+}
+
+export async function applyProfile(accountId: string, change: ProfileChange): Promise<void> {
+  if (change.name !== undefined) await tg(accountId, 'setMyName', { name: change.name });
+  if (change.bio !== undefined) await tg(accountId, 'setMyDescription', { description: change.bio });
+  if (change.avatar !== undefined) await setPhoto(accountId, change.avatar);
+}
+
+export async function setProfile(id: string, args: Record<string, unknown>): Promise<void> {
+  const accountId = accountFor({ account: args.account as string | undefined });
+  const change = parseProfileChange(args);
+  await applyProfile(accountId, change);
+  const result: ProfileApplied = { account: accountId, applied: fieldsOf(change) };
+  respond(id, { result });
+}
+
+interface TgChat {
+  username?: unknown;
+  first_name?: unknown;
+  last_name?: unknown;
+  bio?: unknown;
+  photo?: { small_file_id?: unknown };
+}
+
+const PHOTO_MAX = 64 * 1024;
+
+async function photoData(accountId: string, fileId: unknown): Promise<string | undefined> {
+  if (typeof fileId !== 'string' || fileId === '') return undefined;
+  try {
+    const file = await tg<{ file_path?: string }>(accountId, 'getFile', { file_id: fileId }, 10_000);
+    const acct = accounts.get(accountId);
+    if (acct === undefined || typeof file.file_path !== 'string') return undefined;
+    const res = await fetch(`${acct.fileApi}/${file.file_path}`, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return undefined;
+    const bytes = Buffer.from(await res.arrayBuffer());
+    return bytes.length === 0 || bytes.length > PHOTO_MAX ? undefined : `data:image/jpeg;base64,${bytes.toString('base64')}`;
+  } catch {
+    return undefined;
+  }
+}
+
+const senders = makeProfileCache<SenderProfile>(
+  async (key) => {
+    const [accountId, user] = key.split(':', 2) as [string, string];
+    const chat = await tg<TgChat>(accountId, 'getChat', { chat_id: Number(user) }, 10_000);
+    const handle = nonEmpty(chat.username);
+    const display = nonEmpty([chat.first_name, chat.last_name].filter((part) => typeof part === 'string').join(' '));
+    const avatar = await photoData(accountId, chat.photo?.small_file_id);
+    return {
+      id: user,
+      ...(handle === undefined ? {} : { name: `@${handle}` }),
+      ...(display === undefined ? {} : { display_name: display }),
+      ...(nonEmpty(chat.bio) === undefined ? {} : { about: nonEmpty(chat.bio) }),
+      ...(avatar === undefined ? {} : { avatar }),
+    };
+  },
+  { onError: (key, err) => process.stderr.write(`telegram-bot: could not read the profile of ${key}: ${err instanceof Error ? err.message : String(err)}\n`) },
+);
+
+export async function readProfile(id: string, args: Record<string, unknown>): Promise<void> {
+  const accountId = accountFor({ account: args.account as string | undefined });
+  const user = typeof args.user === 'string' ? args.user.trim() : '';
+  if (!/^\d+$/.test(user)) throw new TrainError('telegram_user_required', 'profile needs the numeric Telegram id of the person', { retryable: false });
+  respond(id, { result: (await senders.get(`${accountId}:${user}`)) ?? { id: user } });
+}

package/runtime/node_modules/@metro-labs/telegram-bot/src/station.ts

@@ -0,0 +1,25 @@
+import type { Station, Verb } from '@metro-labs/core/stations/types';
+import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
+import { channelFiles } from './channel-files.js';
+
+export const telegramBotStation: Station = {
+  name: 'telegram-bot',
+  hasAccounts: true,
+  hasTrain: true,
+  discoversChannels: true,
+  forget: channelFiles.forget,
+  forgetExcept: channelFiles.forgetExcept,
+  messageVerbs: new Set<Verb>([
+    'send',
+    'reply',
+    'react',
+    'unreact',
+    'edit',
+    'delete',
+    'typing',
+  ]),
+  attachmentMode: 'canonical',
+  profileFields: new Set<ProfileField>(PROFILE_FIELDS),
+  readsProfiles: true,
+  tools: [],
+};

package/runtime/node_modules/@metro-labs/telegram-bot/src/types.ts

@@ -0,0 +1,83 @@
+export interface TgEntity {
+  type: string;
+  offset: number;
+  length: number;
+  user?: { id: number };
+}
+
+export interface TgUser {
+  id: number;
+  username?: string;
+  first_name?: string;
+  last_name?: string;
+  is_bot?: boolean;
+}
+
+export interface TgChat {
+  id: number;
+  type: string;
+  title?: string;
+  first_name?: string;
+  last_name?: string;
+  username?: string;
+}
+
+export interface TgMyChatMember {
+  chat: TgChat;
+  new_chat_member: { status: string; is_member?: boolean };
+}
+
+export interface TgUpdate {
+  update_id: number;
+  message?: TgMsg;
+  channel_post?: TgMsg;
+  my_chat_member?: TgMyChatMember;
+  message_reaction?: TgReaction;
+  message_reaction_count?: TgReactionCount;
+}
+
+export interface TgMsg {
+  entities?: TgEntity[];
+  caption_entities?: TgEntity[];
+  reply_to_message?: { message_id: number; from?: { id: number; username?: string; is_bot?: boolean } };
+  message_id: number;
+  date: number;
+  chat: TgChat;
+  from?: TgUser;
+  text?: string;
+  caption?: string;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  forum_topic_created?: { name: string };
+  forum_topic_edited?: { name?: string };
+  migrate_to_chat_id?: number;
+  migrate_from_chat_id?: number;
+  photo?: { file_id: string; file_size?: number }[];
+  document?: { file_name?: string; file_id?: string; mime_type?: string };
+  voice?: { file_id?: string; duration?: number; mime_type?: string };
+  audio?: { file_id?: string; file_name?: string; mime_type?: string };
+  video?: { file_id?: string; file_name?: string; mime_type?: string };
+  animation?: { file_id?: string; file_name?: string; mime_type?: string };
+  sticker?: { file_id?: string; emoji?: string; set_name?: string };
+  location?: { latitude: number; longitude: number };
+  dice?: { emoji: string; value: number };
+}
+
+export interface TgReaction {
+  chat: TgChat;
+  message_id: number;
+  user?: TgUser;
+  date: number;
+  old_reaction: { type: string; emoji?: string }[];
+  new_reaction: { type: string; emoji?: string }[];
+}
+
+export interface TgReactionCount {
+  chat: TgChat;
+  message_id: number;
+  date: number;
+  reactions: {
+    type: { type: string; emoji?: string };
+    total_count: number;
+  }[];
+}

package/runtime/node_modules/@metro-labs/telegram-bot/src/updates.ts

@@ -0,0 +1,26 @@
+import { emitInbound } from '@metro-labs/core/stations/train-events';
+import { observeChannels } from './channels.js';
+import {
+  envelope,
+  reactionCountEnvelope,
+  reactionEnvelope,
+  saveMediaAndEmit,
+} from './format.js';
+import type { TgUpdate } from './types.js';
+
+export function handleUpdate(id: string, update: TgUpdate): void {
+  observeChannels(id, update);
+  if (update.message && !update.message.from?.is_bot) {
+    const env = envelope(id, update.message);
+    emitInbound(id, env);
+    saveMediaAndEmit(id, update.message, env.id as string);
+  }
+  if (update.message_reaction) {
+    const env = reactionEnvelope(id, update.message_reaction);
+    if (env) emitInbound(id, env);
+  }
+  if (update.message_reaction_count) {
+    const env = reactionCountEnvelope(id, update.message_reaction_count);
+    if (env) emitInbound(id, env);
+  }
+}

package/runtime/node_modules/@metro-labs/telegram-bot/src/verify.ts

@@ -0,0 +1,38 @@
+export class TelegramTokenError extends Error {}
+
+export interface TelegramBotIdentity {
+  botId: number;
+  username: string;
+}
+
+const API = 'https://api.telegram.org';
+const TIMEOUT_MS = 10_000;
+
+interface GetMe {
+  ok?: unknown;
+  result?: { id?: unknown; username?: unknown; is_bot?: unknown };
+}
+
+export async function verifyTelegramBotToken(
+  token: string,
+): Promise<TelegramBotIdentity> {
+  let res: Response;
+  try {
+    res = await fetch(`${API}/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    throw new TelegramTokenError(
+      'could not reach the Telegram API to check that bot token',
+    );
+  }
+  const body = (await res.json().catch(() => null)) as GetMe | null;
+  const me = body?.ok === true ? body.result : undefined;
+  if (!me) throw new TelegramTokenError('Telegram rejected that bot token');
+  if (typeof me.id !== 'number' || me.is_bot !== true)
+    throw new TelegramTokenError('that token does not belong to a Telegram bot');
+  return {
+    botId: me.id,
+    username: typeof me.username === 'string' ? me.username : '',
+  };
+}

package/runtime/node_modules/@metro-labs/threema/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@metro-labs/threema",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./verify": "./src/verify.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/core": "workspace:*",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.3",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/node_modules/@metro-labs/threema/src/accounts.ts

@@ -0,0 +1,108 @@
+import {
+  makeAccountStore,
+  resolveAccountId,
+  type Die,
+} from '@metro-labs/core/stations/account-store';
+import { Line } from '@metro-labs/core/lines';
+import { ChannelDirectory } from '@metro-labs/core/stations/channel-directory';
+import { DirectStore } from './chats.js';
+import { fetchPublicKey } from './api.js';
+import { hexToBytes, keyPairFrom, type KeyPair } from './crypto.js';
+import { isGatewayId, normalizeThreemaId, parsePrivateKey } from './ids.js';
+import { GroupStore, parseGroupKey } from './groups.js';
+import type { GroupRef } from './messages.js';
+
+export interface AccountConfig {
+  id: string;
+  gatewayId: string;
+  secret: string;
+  privateKey: string;
+  callbackId?: string;
+  callbackToken?: string;
+}
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (typeof a.gatewayId !== 'string' || !isGatewayId(a.gatewayId))
+    die(`account '${a.id}' has no Gateway ID`);
+  if (typeof a.secret !== 'string' || a.secret === '')
+    die(`account '${a.id}' missing secret`);
+  if (typeof a.privateKey !== 'string' || parsePrivateKey(a.privateKey) === null)
+    die(`account '${a.id}' has no usable private key`);
+}
+
+export const { loadAccounts } = makeAccountStore<AccountConfig>({
+  prefix: 'threema',
+  validate(raw, die) {
+    const seenGateway = new Set<string>();
+    for (const a of raw) {
+      checkAccount(a, die);
+      if (seenGateway.has(a.gatewayId))
+        die(`account '${a.id}' reuses the Gateway ID of another account`);
+      seenGateway.add(a.gatewayId);
+    }
+  },
+});
+
+export interface Account {
+  cfg: AccountConfig;
+  keys: KeyPair;
+  publicKeys: Map<string, Uint8Array>;
+  requestedRosters: Set<string>;
+  groups: GroupStore;
+  chats: DirectStore;
+  directory: ChannelDirectory;
+}
+
+export type Target = { kind: 'user'; id: string } | { kind: 'group'; group: GroupRef };
+
+export const accounts = new Map<string, Account>();
+
+export function bootAccount(cfg: AccountConfig): Account {
+  const key = parsePrivateKey(cfg.privateKey);
+  if (key === null) throw new Error(`account '${cfg.id}' has no usable private key`);
+  return {
+    cfg,
+    keys: keyPairFrom(key),
+    publicKeys: new Map(),
+    requestedRosters: new Set(),
+    groups: new GroupStore(cfg.id, cfg.gatewayId),
+    chats: new DirectStore(cfg.id),
+    directory: new ChannelDirectory(),
+  };
+}
+
+export function accountFor(id: string): Account {
+  const acct = accounts.get(id);
+  if (!acct)
+    throw new Error(
+      `unknown account '${id}' (have: ${[...accounts.keys()].join(', ')})`,
+    );
+  return acct;
+}
+
+export function targetOf(
+  line: string,
+  account?: string,
+): { acct: Account; target: Target } {
+  const parsed = Line.parseThreema(line);
+  if (parsed === null) throw new Error(`not a threema line: ${line}`);
+  const id = resolveAccountId(
+    accounts,
+    { account, line },
+    (l) => Line.parseThreema(l)?.accountId,
+  );
+  const group = parseGroupKey(parsed.resource);
+  const target: Target = group === null ? { kind: 'user', id: normalizeThreemaId(parsed.resource) } : { kind: 'group', group };
+  return { acct: accountFor(id), target };
+}
+
+export async function publicKeyFor(
+  acct: Account,
+  threemaId: string,
+): Promise<Uint8Array> {
+  const cached = acct.publicKeys.get(threemaId);
+  if (cached) return cached;
+  const key = hexToBytes(await fetchPublicKey(acct.cfg, threemaId), 'public key');
+  acct.publicKeys.set(threemaId, key);
+  return key;
+}