@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.200

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

@@ -0,0 +1,95 @@
+import { tgForm, targetOf } from './accounts.js';
+import { selfUri } from '@metro-labs/core/stations/train-events';
+import { emit, mintId, respond } from './wire.js';
+import { appendFile } from '@metro-labs/core/stations/attachments';
+
+export function emitOutbound(
+  accountId: string,
+  line: string,
+  messageId: string,
+  text: string,
+  replyTo?: string,
+): void {
+  emit({
+    kind: 'outbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: 'telegram-bot',
+    line,
+    from: selfUri('telegram-bot', accountId),
+    to: line,
+    message_id: messageId,
+    text,
+    reply_to: replyTo,
+    ...(replyTo ? { event: { type: 'reply', replyTo } } : {}),
+    account: accountId,
+    payload: { account: accountId },
+  });
+}
+
+export function finishSend(
+  id: string,
+  accountId: string,
+  line: string,
+  messageId: string,
+  label: string,
+  replyTo?: string,
+  extra?: Record<string, unknown>,
+): void {
+  emitOutbound(accountId, line, messageId, label, replyTo);
+  respond(id, {
+    result: { messageId, account: accountId, ...extra },
+  });
+}
+
+interface MediaArgs {
+  line: string;
+  path: string;
+  caption?: string;
+  replyTo?: string;
+  parseMode?: string;
+  account?: string;
+  name?: string;
+}
+
+export async function sendMedia(
+  method: string,
+  fieldName: string,
+  args: Record<string, unknown>,
+): Promise<{ accountId: string; message_id: number }> {
+  const {
+    line,
+    path,
+    caption,
+    replyTo,
+    parseMode,
+    account,
+    name: fileName,
+  } = args as unknown as MediaArgs;
+  const { accountId, chatId, topicId } = targetOf(line, account);
+  const form = new FormData();
+  form.append('chat_id', String(chatId));
+  if (topicId !== undefined) form.append('message_thread_id', String(topicId));
+  if (caption) form.append('caption', caption);
+  if (parseMode) form.append('parse_mode', parseMode);
+  if (replyTo)
+    form.append(
+      'reply_parameters',
+      JSON.stringify({ message_id: Number(replyTo) }),
+    );
+  const name = fileName ?? path.split('/').pop() ?? fieldName;
+  await appendFile(form, fieldName, path, name);
+  const r = await tgForm<{ message_id: number }>(accountId, method, form);
+  return { accountId, message_id: r.message_id };
+}
+
+export const MEDIA_METHOD_FIELD: Record<
+  string,
+  { method: string; field: string }
+> = {
+  image: { method: 'sendPhoto', field: 'photo' },
+  voice: { method: 'sendVoice', field: 'voice' },
+  audio: { method: 'sendAudio', field: 'audio' },
+  video: { method: 'sendVideo', field: 'video' },
+  document: { method: 'sendDocument', field: 'document' },
+};

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

@@ -0,0 +1,47 @@
+import type { MemberList, MetroMember } from '@metro-labs/core/stations/types';
+
+export interface TgUser {
+  id: number;
+  username?: string;
+  first_name?: string;
+  last_name?: string;
+  is_bot?: boolean;
+}
+
+export interface TgChatMember {
+  user: TgUser;
+  status: string;
+}
+
+export function mapTgMember(m: TgChatMember): MetroMember {
+  const u = m.user;
+  const member: MetroMember = { id: String(u.id) };
+  if (u.username) member.name = u.username;
+  const display = [u.first_name, u.last_name].filter(Boolean).join(' ');
+  if (display) member.display_name = display;
+  member.is_admin = m.status === 'creator' || m.status === 'administrator';
+  member.is_bot = Boolean(u.is_bot);
+  return member;
+}
+
+const BOT_LIMIT_REASON =
+  'Telegram Bot API cannot enumerate full membership; returning administrators only.';
+
+export function adminMemberList(
+  admins: TgChatMember[],
+  total: number | null,
+): MemberList {
+  return {
+    members: admins.map(mapTgMember),
+    capability: {
+      supported: true,
+      complete: false,
+      reason: BOT_LIMIT_REASON,
+      ...(total != null ? { total } : {}),
+    },
+  };
+}
+
+export function inaccessibleMemberList(reason: string): MemberList {
+  return { members: [], capability: { supported: false, complete: false, reason } };
+}

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

@@ -0,0 +1,65 @@
+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, tg, tgForm } from './accounts.js';
+import { respond } from './wire.js';
+
+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 tgForm(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;
+}
+
+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(' '));
+    return {
+      id: user,
+      ...(handle === undefined ? {} : { name: `@${handle}` }),
+      ...(display === undefined ? {} : { display_name: display }),
+      ...(nonEmpty(chat.bio) === undefined ? {} : { about: nonEmpty(chat.bio) }),
+    };
+  },
+  { 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,20 @@
+import type { Station, Verb } from '@metro-labs/core/stations/types';
+import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
+
+export const telegramBotStation: Station = {
+  name: 'telegram-bot',
+  hasAccounts: true,
+  hasTrain: true,
+  messageVerbs: new Set<Verb>([
+    'send',
+    'reply',
+    'react',
+    'unreact',
+    'edit',
+    'delete',
+  ]),
+  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,56 @@
+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 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: { id: number; type: string; title?: string; first_name?: string };
+  from?: TgUser;
+  text?: string;
+  caption?: string;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  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: { id: number; type: string };
+  message_id: number;
+  user?: TgUser;
+  date: number;
+  old_reaction: { type: string; emoji?: string }[];
+  new_reaction: { type: string; emoji?: string }[];
+}
+
+export interface TgReactionCount {
+  chat: { id: number; type: string };
+  message_id: number;
+  date: number;
+  reactions: {
+    type: { type: string; emoji?: string };
+    total_count: number;
+  }[];
+}

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/telegram-bot/src/wire.ts

@@ -0,0 +1 @@
+export { emit, respond, mintId } from '@metro-labs/core/stations/station-runtime';

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.2",
+    "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,106 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  makeAccountStore,
+  resolveAccountId,
+  type Die,
+} from '@metro-labs/core/stations/account-store';
+import { Line } from '@metro-labs/core/lines';
+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';
+
+const ACCOUNTS_FILE =
+  process.env.THREEMA_ACCOUNTS_FILE ??
+  join(homedir(), '.metro', 'threema-accounts.json');
+
+export interface AccountConfig {
+  id: string;
+  gatewayId: string;
+  secret: string;
+  privateKey: string;
+  callbackId?: string;
+  callbackToken?: string;
+}
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (!a.id) die('account missing id');
+  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',
+  file: ACCOUNTS_FILE,
+  validate(raw, die) {
+    const seenId = new Set<string>();
+    const seenGateway = new Set<string>();
+    for (const a of raw) {
+      checkAccount(a, die);
+      if (seenId.has(a.id)) die(`duplicate account id '${a.id}'`);
+      if (seenGateway.has(a.gatewayId))
+        die(`account '${a.id}' reuses the Gateway ID of another account`);
+      seenId.add(a.id);
+      seenGateway.add(a.gatewayId);
+    }
+  },
+});
+
+export interface Account {
+  cfg: AccountConfig;
+  keys: KeyPair;
+  publicKeys: Map<string, Uint8Array>;
+  groups: GroupStore;
+}
+
+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(), groups: new GroupStore(cfg.id, cfg.gatewayId) };
+}
+
+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;
+}

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

@@ -0,0 +1,134 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import {
+  makeStation,
+  respond,
+  type CallMsg,
+} from '@metro-labs/core/stations/station-runtime';
+import type { Normalized } from '@metro-labs/core/stations/messaging-normalize';
+import { accountFor, accounts, publicKeyFor, targetOf, type Account } from './accounts.js';
+import { hexToBytes, macMatches, open } from './crypto.js';
+import { groupLineOf, type InboundMeta } from './format.js';
+import { groupKey } from './groups.js';
+import { deliver } from './inbound.js';
+import { isThreemaId, normalizeThreemaId } from './ids.js';
+import { decode } from './messages.js';
+import { react, send } from './outbound.js';
+
+export type { CallMsg };
+export { MAX_TEXT_BYTES } from './outbound.js';
+
+type Args = Record<string, unknown>;
+
+const WEB_CHAT = 'https://web.threema.com/#!/messenger/conversation/contact/';
+
+export const chatUrl = (gatewayId: string): string => `${WEB_CHAT}${encodeURIComponent(gatewayId)}`;
+
+function listAccounts(id: string): void {
+  const list = [...accounts.values()].map((a) => ({
+    id: a.cfg.id,
+    handle: a.cfg.gatewayId,
+    url: chatUrl(a.cfg.gatewayId),
+    gatewayId: a.cfg.gatewayId,
+    groups: a.groups.list().map((g) => ({ line: groupLineOf(a.cfg.id, g), name: g.name, members: g.members.length })),
+    ...(a.cfg.callbackId && a.cfg.callbackToken
+      ? { callbackId: a.cfg.callbackId, callbackToken: a.cfg.callbackToken }
+      : {}),
+  }));
+  respond(id, { result: { accounts: list } });
+}
+
+function listMembers(id: string, args: Args): void {
+  const line = typeof args.line === 'string' ? args.line : '';
+  const { acct, target } = targetOf(line, typeof args.account === 'string' ? args.account : undefined);
+  if (target.kind !== 'group') {
+    respond(id, { result: { members: [], capability: { supported: false, complete: false, reason: 'a Threema 1:1 chat has no roster' } } });
+    return;
+  }
+  const roster = acct.groups.get(target.group);
+  if (roster === undefined) {
+    respond(id, { result: { members: [], capability: { supported: true, complete: false, reason: `no member list yet for ${groupKey(target.group)}` } } });
+    return;
+  }
+  const members = roster.members.map((m) => ({ id: m, name: m, is_admin: m === roster.creator, is_bot: m === acct.cfg.gatewayId }));
+  respond(id, { result: { members, capability: { supported: true, complete: true, total: members.length } } });
+}
+
+interface CallbackArgs {
+  account: string;
+  from: string;
+  to: string;
+  messageId: string;
+  date: string;
+  nonce: string;
+  box: string;
+  mac: string;
+  nickname?: string;
+}
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+function parseCallback(args: Args): CallbackArgs {
+  const fields = {
+    account: str(args.account),
+    from: str(args.from),
+    to: str(args.to),
+    messageId: str(args.messageId),
+    date: str(args.date),
+    nonce: str(args.nonce),
+    box: str(args.box),
+    mac: str(args.mac),
+  };
+  for (const [key, value] of Object.entries(fields))
+    if (value === '')
+      throw new TrainError('threema_bad_callback', `callback is missing ${key}`, {
+        retryable: false,
+      });
+  const nickname = str(args.nickname);
+  return nickname === '' ? fields : { ...fields, nickname };
+}
+
+function checkedSender(acct: Account, cb: CallbackArgs): string {
+  if (!macMatches(acct.cfg.secret, cb, cb.mac))
+    throw new TrainError('threema_bad_mac', 'the callback MAC does not match this account API secret', { retryable: false });
+  const from = normalizeThreemaId(cb.from);
+  if (!isThreemaId(from))
+    throw new TrainError('threema_bad_callback', `'${cb.from}' is not a Threema ID`, { retryable: false });
+  if (normalizeThreemaId(cb.to) !== acct.cfg.gatewayId)
+    throw new TrainError('threema_wrong_recipient', `callback addressed to ${cb.to}, not to ${acct.cfg.gatewayId}`, { retryable: false });
+  return from;
+}
+
+async function callback(id: string, args: Args): Promise<void> {
+  const cb = parseCallback(args);
+  const acct = accountFor(cb.account);
+  const from = checkedSender(acct, cb);
+  const plain = open(
+    hexToBytes(cb.box, 'box'),
+    hexToBytes(cb.nonce, 'nonce'),
+    await publicKeyFor(acct, from),
+    acct.keys,
+  );
+  if (plain === null)
+    throw new TrainError(
+      'threema_undecryptable',
+      `could not decrypt a message from ${from}; the private key may not match the Gateway ID`,
+      { retryable: false },
+    );
+  const meta: InboundMeta = { ...cb, from, messageId: cb.messageId.toLowerCase() };
+  respond(id, { result: { ok: true, kind: deliver(acct, meta, decode(plain)) } });
+}
+
+export function normalizeThreema(action: string, env: Args): Normalized {
+  if (action === 'reply')
+    return {
+      action: 'send',
+      args: { line: env.line, text: env.text, replyTo: env.replyTo, account: env.account },
+    };
+  if (action === 'unreact') return { action: 'react', args: { ...env, action: 'removed' } };
+  return { action, args: env };
+}
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, send, react, callback, listMembers },
+  normalize: normalizeThreema,
+});