@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,130 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import {
+  makeStation,
+  respond,
+  type CallMsg,
+} from '@metro-labs/core/stations/station-runtime';
+import { messagingAliases } 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 { listChannels } from './channels.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 const handleCall = makeStation({
+  handlers: {
+    accounts: listAccounts, send, react, callback, listMembers,
+    async listChannels(id, args) {
+      respond(id, { result: await listChannels(args) });
+    },
+  },
+  normalize: messagingAliases({ action: 'removed' }),
+});

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

@@ -0,0 +1,152 @@
+import { errMsg } from '@metro-labs/core/log';
+import { TrainError } from '@metro-labs/core/train-error';
+import { GATEWAY_API, MESSAGE_ID_RE } from './ids.js';
+
+const TIMEOUT_MS = 15_000;
+const PUBLIC_KEY_RE = /^[0-9a-f]{64}$/;
+
+export interface GatewayCreds {
+  gatewayId: string;
+  secret: string;
+}
+
+async function call(
+  path: string,
+  init: RequestInit,
+  label: string,
+): Promise<Response> {
+  try {
+    return await fetch(`${GATEWAY_API}${path}`, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      ...init,
+    });
+  } catch (err) {
+    throw new TrainError(
+      'threema_unreachable',
+      `${label}: could not reach the Threema Gateway (${errMsg(err)})`,
+      { retryable: true },
+    );
+  }
+}
+
+const authQuery = (c: GatewayCreds): string =>
+  new URLSearchParams({ from: c.gatewayId, secret: c.secret }).toString();
+
+function refusal(status: number, what: string): TrainError {
+  if (status === 401)
+    return new TrainError(
+      'threema_unauthorized',
+      'the Threema Gateway rejected this account credentials; check the Gateway ID and API secret',
+      { retryable: false },
+    );
+  if (status === 402)
+    return new TrainError(
+      'threema_no_credits',
+      'this Threema Gateway ID has no credits left; top it up at gateway.threema.ch',
+      { retryable: false },
+    );
+  if (status === 404)
+    return new TrainError('threema_unknown_id', `Threema does not know the ID ${what}`, {
+      retryable: false,
+    });
+  if (status === 413)
+    return new TrainError(
+      'threema_message_too_long',
+      'Threema refused the message as too long',
+      { retryable: false },
+    );
+  if (status === 400)
+    return new TrainError('threema_bad_recipient', `Threema refused the recipient ${what}`, {
+      retryable: false,
+    });
+  return new TrainError(
+    'threema_gateway_error',
+    `the Threema Gateway answered ${status}`,
+    { retryable: status >= 500 },
+  );
+}
+
+export async function fetchPublicKey(
+  c: GatewayCreds,
+  threemaId: string,
+): Promise<string> {
+  const res = await call(
+    `/pubkeys/${encodeURIComponent(threemaId)}?${authQuery(c)}`,
+    {},
+    'pubkeys',
+  );
+  if (!res.ok) throw refusal(res.status, threemaId);
+  const hex = (await res.text()).trim().toLowerCase();
+  if (!PUBLIC_KEY_RE.test(hex))
+    throw new TrainError(
+      'threema_gateway_error',
+      `pubkeys: the Threema Gateway gave an unexpected answer for ${threemaId}`,
+    );
+  return hex;
+}
+
+export async function fetchCredits(c: GatewayCreds): Promise<number> {
+  const res = await call(`/credits?${authQuery(c)}`, {}, 'credits');
+  if (!res.ok) throw refusal(res.status, c.gatewayId);
+  const credits = Number((await res.text()).trim());
+  if (!Number.isInteger(credits))
+    throw new TrainError(
+      'threema_gateway_error',
+      'credits: the Threema Gateway gave an unexpected answer',
+    );
+  return credits;
+}
+
+export async function sendE2E(
+  c: GatewayCreds,
+  to: string,
+  nonceHex: string,
+  boxHex: string,
+  group = false,
+): Promise<string> {
+  const body = new URLSearchParams({
+    from: c.gatewayId,
+    to,
+    nonce: nonceHex,
+    box: boxHex,
+    secret: c.secret,
+    ...(group ? { group: '1' } : {}),
+  });
+  const res = await call(
+    '/send_e2e',
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    },
+    'send_e2e',
+  );
+  if (!res.ok) throw refusal(res.status, to);
+  const messageId = (await res.text()).trim().toLowerCase();
+  if (!MESSAGE_ID_RE.test(messageId))
+    throw new TrainError(
+      'threema_gateway_error',
+      'send_e2e: the Threema Gateway answered without a message id',
+    );
+  return messageId;
+}
+
+const BLOB_ID_RE = /^[0-9a-f]{32}$/;
+const BLOB_TIMEOUT_MS = 120_000;
+
+export async function uploadBlob(c: GatewayCreds, data: Uint8Array): Promise<string> {
+  const form = new FormData();
+  form.append('blob', new Blob([Buffer.from(data)]), 'blob');
+  const res = await call(`/upload_blob?${authQuery(c)}`, { method: 'POST', body: form, signal: AbortSignal.timeout(BLOB_TIMEOUT_MS) }, 'upload_blob');
+  if (!res.ok) throw refusal(res.status, 'blob');
+  const blobId = (await res.text()).trim().toLowerCase();
+  if (!BLOB_ID_RE.test(blobId)) throw new TrainError('threema_gateway_error', 'upload_blob: the Threema Gateway answered without a blob id');
+  return blobId;
+}
+
+export async function downloadBlob(c: GatewayCreds, blobId: string): Promise<Uint8Array> {
+  if (!BLOB_ID_RE.test(blobId)) throw new TrainError('threema_bad_blob', `'${blobId}' is not a blob id`, { retryable: false });
+  const res = await call(`/blobs/${blobId}?${authQuery(c)}`, { signal: AbortSignal.timeout(BLOB_TIMEOUT_MS) }, 'blob download');
+  if (!res.ok) throw refusal(res.status, `blob ${blobId}`);
+  return new Uint8Array(await res.arrayBuffer());
+}

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

@@ -0,0 +1,37 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import { DIRECTORY_LIMIT, type ChannelList, type ChannelSnapshot } from '@metro-labs/core/stations/channel-directory';
+import { accountFor, type Account } from './accounts.js';
+import { groupLineOf, lineOf } from './format.js';
+import { groupKey, parseGroupKey } from './groups.js';
+
+function snapshot(acct: Account): ChannelSnapshot {
+  return {
+    channels: [
+      ...acct.groups.list().slice(0, DIRECTORY_LIMIT + 1).filter((group) => parseGroupKey(groupKey(group)) !== null).map((group) => ({
+        id: groupKey(group),
+        line: groupLineOf(acct.cfg.id, group),
+        kind: 'group' as const,
+        ...(group.name ? { name: Array.from(group.name).slice(0, 256).join('') } : {}),
+      })),
+      ...acct.chats.list().map((chat) => ({
+        id: chat.id,
+        line: lineOf(acct.cfg.id, chat.id),
+        kind: 'direct' as const,
+        ...(chat.name ? { name: chat.name } : {}),
+      })),
+    ],
+    capability: {
+      supported: true,
+      complete: false,
+      source: 'local',
+      reason: `Threema Gateway has no remote conversation-list or history endpoint. Only locally stored groups and up to ${DIRECTORY_LIMIT} observed direct chats are listed; conversations not observed by this Metro are unavailable.`,
+    },
+  };
+}
+
+export function listChannels(args: Record<string, unknown>): Promise<ChannelList> {
+  if (typeof args.account !== 'string' || !args.account.trim())
+    throw new TrainError('bad_request', 'listChannels requires an explicit Threema account');
+  const acct = accountFor(args.account);
+  return acct.directory.list(acct.cfg.id, args, () => Promise.resolve(snapshot(acct)));
+}

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

@@ -0,0 +1,88 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { log } from '@metro-labs/core/log';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { DIRECTORY_LIMIT } from '@metro-labs/core/stations/channel-directory';
+import { isThreemaId, normalizeThreemaId } from './ids.js';
+
+interface DirectChat {
+  id: string;
+  name?: string;
+}
+
+export const chatFiles = accountFiles('THREEMA_GROUPS_DIR', 'threema-chats-');
+
+const nameOf = (name: unknown): string | undefined =>
+  typeof name === 'string' ? Array.from(name.trim()).slice(0, 256).join('') || undefined : undefined;
+
+function directChat(entry: unknown): DirectChat | undefined {
+  if (!entry || typeof entry !== 'object' || !('id' in entry) || typeof entry.id !== 'string') return undefined;
+  const id = normalizeThreemaId(entry.id);
+  if (!isThreemaId(id)) return undefined;
+  const name = nameOf('name' in entry ? entry.name : undefined);
+  return { id, ...(name ? { name } : {}) };
+}
+
+function readChats(path: string): Map<string, DirectChat> {
+  try {
+    if (statSync(path).size > DIRECTORY_LIMIT * 2048) throw new Error('Threema chat metadata is too large');
+    const raw: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    const chats = new Map<string, DirectChat>();
+    if (!Array.isArray(raw)) throw new Error('Threema chat metadata must be an array');
+    for (const entry of raw.slice(-DIRECTORY_LIMIT)) {
+      const chat = directChat(entry);
+      if (chat) chats.set(chat.id, chat);
+    }
+    return chats;
+  } catch (err) {
+    if (!(err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT'))
+      log.warn({ err, path }, 'threema: could not load chat metadata');
+    return new Map();
+  }
+}
+
+export class DirectStore {
+  private readonly path: string;
+  private readonly chats: Map<string, DirectChat>;
+
+  constructor(accountId: string) {
+    this.path = chatFiles.path(accountId);
+    this.chats = readChats(this.path);
+  }
+
+  list(): DirectChat[] {
+    return [...this.chats.values()].map((chat) => ({ ...chat }));
+  }
+
+  note(rawId: string, rawName?: string): void {
+    const id = normalizeThreemaId(rawId);
+    if (!isThreemaId(id)) return;
+    const previous = this.chats.get(id);
+    const name = nameOf(rawName) ?? previous?.name;
+    if (previous && name === previous.name) return;
+    this.chats.delete(id);
+    this.chats.set(id, { id, ...(name ? { name } : {}) });
+    while (this.chats.size > DIRECTORY_LIMIT) {
+      const oldest = this.chats.keys().next();
+      if (oldest.done) break;
+      this.chats.delete(oldest.value);
+    }
+    this.save();
+  }
+
+  private save(): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(tmp, JSON.stringify(this.list()), { mode: 0o600, flag: 'wx' });
+        renameSync(tmp, this.path);
+      } finally {
+        rmSync(tmp, { force: true });
+      }
+    } catch (err) {
+      log.warn({ err, path: this.path }, 'threema: could not save chat metadata');
+    }
+  }
+}

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

@@ -0,0 +1,100 @@
+import { createHmac, randomInt, timingSafeEqual } from 'node:crypto';
+import nacl from 'tweetnacl';
+
+const HEX_RE = /^(?:[0-9a-fA-F]{2})*$/;
+
+export interface KeyPair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+export function hexToBytes(hex: string, label: string): Uint8Array {
+  if (!HEX_RE.test(hex)) throw new Error(`${label} is not hex`);
+  return new Uint8Array(Buffer.from(hex, 'hex'));
+}
+
+export const bytesToHex = (bytes: Uint8Array): string =>
+  Buffer.from(bytes).toString('hex');
+
+export const keyPairFrom = (privateKeyHex: string): KeyPair =>
+  nacl.box.keyPair.fromSecretKey(hexToBytes(privateKeyHex, 'private key'));
+
+function pad(plain: Uint8Array): Uint8Array {
+  const n = randomInt(1, 256);
+  const out = new Uint8Array(plain.length + n);
+  out.set(plain);
+  out.fill(n, plain.length);
+  return out;
+}
+
+function unpad(data: Uint8Array): Uint8Array | null {
+  const n = data[data.length - 1];
+  if (n === undefined || n < 1 || n > data.length) return null;
+  return data.subarray(0, data.length - n);
+}
+
+export function seal(
+  plain: Uint8Array,
+  theirPublicKey: Uint8Array,
+  mine: KeyPair,
+): { nonce: Uint8Array; box: Uint8Array } {
+  const nonce = nacl.randomBytes(nacl.box.nonceLength);
+  return {
+    nonce,
+    box: nacl.box(pad(plain), nonce, theirPublicKey, mine.secretKey),
+  };
+}
+
+export function open(
+  box: Uint8Array,
+  nonce: Uint8Array,
+  theirPublicKey: Uint8Array,
+  mine: KeyPair,
+): Uint8Array | null {
+  const padded = nacl.box.open(box, nonce, theirPublicKey, mine.secretKey);
+  return padded === null ? null : unpad(padded);
+}
+
+export interface CallbackFields {
+  from: string;
+  to: string;
+  messageId: string;
+  date: string;
+  nonce: string;
+  box: string;
+}
+
+export const callbackMac = (secret: string, f: CallbackFields): string =>
+  createHmac('sha256', secret)
+    .update(f.from + f.to + f.messageId + f.date + f.nonce + f.box)
+    .digest('hex');
+
+export function macMatches(
+  secret: string,
+  fields: CallbackFields,
+  mac: string,
+): boolean {
+  const want = Buffer.from(callbackMac(secret, fields), 'hex');
+  const got = Buffer.from(mac.toLowerCase(), 'hex');
+  return want.length === got.length && timingSafeEqual(want, got);
+}
+
+const QUOTE_RE = /^> quote #([0-9a-f]{16})\n\n([\s\S]*)$/;
+
+export const quoted = (replyTo: string, text: string): string =>
+  `> quote #${replyTo}\n\n${text}`;
+
+export function unquote(text: string): { replyTo?: string; text: string } {
+  const m = QUOTE_RE.exec(text);
+  const replyTo = m?.[1];
+  const body = m?.[2];
+  return replyTo === undefined || body === undefined ? { text } : { replyTo, text: body };
+}
+
+const FILE_NONCE = new Uint8Array([...new Array<number>(23).fill(0), 1]);
+
+export const newBlobKey = (): Uint8Array => nacl.randomBytes(nacl.secretbox.keyLength);
+
+export const sealBlob = (data: Uint8Array, key: Uint8Array): Uint8Array => nacl.secretbox(data, FILE_NONCE, key);
+
+export const openBlob = (data: Uint8Array, key: Uint8Array): Uint8Array | null => nacl.secretbox.open(data, FILE_NONCE, key);

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

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import { emitInbound, reportAttachment, type SavedFile } from '@metro-labs/core/stations/train-events';
+import { assertAttachmentSize, isImageMime, kindOf, saveBufferToCache } from '@metro-labs/core/stations/attachments';
+import { TrainError } from '@metro-labs/core/train-error';
+import type { Account } from './accounts.js';
+import { downloadBlob, uploadBlob } from './api.js';
+import { bytesToHex, hexToBytes, newBlobKey, openBlob, sealBlob } from './crypto.js';
+import { textEnvelope, type InboundMeta, type Room } from './format.js';
+import { encodeFile, encodeGroupFile, type FileData, type GroupRef } from './messages.js';
+
+export const MAX_BLOB_BYTES = 50 * 1024 * 1024;
+
+export interface OutgoingFile {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export async function packFile(acct: Account, file: OutgoingFile, caption: string | null): Promise<FileData> {
+  const data = await readFile(file.path);
+  assertAttachmentSize(data.length);
+  if (data.length > MAX_BLOB_BYTES) throw new TrainError('threema_file_too_big', `Threema carries files up to 50 MB; ${file.name} is bigger`, { retryable: false });
+  const key = newBlobKey();
+  const blobId = await uploadBlob(acct.cfg, sealBlob(new Uint8Array(data), key));
+  return { blobId, key: bytesToHex(key), mime: file.mime, name: file.name, size: data.length, caption, media: isImageMime(file.mime) };
+}
+
+export const encodeFileFor = (group: GroupRef | null, file: FileData): Uint8Array => (group === null ? encodeFile(file) : encodeGroupFile(group, file));
+
+export const fileLabel = (file: OutgoingFile): string => kindOf(file.mime, file.path);
+
+async function fetchFile(acct: Account, m: InboundMeta, file: FileData): Promise<SavedFile> {
+  const sealed = await downloadBlob(acct.cfg, file.blobId);
+  const plain = openBlob(sealed, hexToBytes(file.key, 'blob key'));
+  if (plain === null) throw new TrainError('threema_bad_blob', 'the file did not decrypt with the key in the message', { retryable: false });
+  return saveBufferToCache(plain, m.messageId, 0, { mime: file.mime, name: file.name });
+}
+
+export function deliverFile(acct: Account, m: InboundMeta, file: FileData, room: Room, sentByUs: (id: string) => boolean): void {
+  const env = textEnvelope(acct.cfg.id, m, file.caption ?? '', sentByUs, room);
+  const line = String(env.line);
+  const forId = String(env.id);
+  const payload = { ...(env.payload as Record<string, unknown>), attachments: [{ kind: kindOf(file.mime, file.name), name: file.name, mime: file.mime, ...(file.size === null ? {} : { size: file.size }) }] };
+  emitInbound(acct.cfg.id, { ...env, payload });
+  const kind = kindOf(file.mime, file.name);
+  reportAttachment(fetchFile(acct, m, file), { station: 'threema', account: acct.cfg.id, line, forId, index: 0 }, { saved: { kind }, failed: { kind } });
+}