@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,219 @@
+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 { sendE2E } from './api.js';
+import {
+  bytesToHex,
+  decode,
+  encodeText,
+  hexToBytes,
+  macMatches,
+  open,
+  quoted,
+  seal,
+  type Decoded,
+} from './crypto.js';
+import {
+  emitInbound,
+  emitOutbound,
+  receiptEnvelope,
+  textEnvelope,
+  type InboundMeta,
+} from './format.js';
+import { isThreemaId, MESSAGE_ID_RE, normalizeThreemaId } from './ids.js';
+
+export type { CallMsg };
+
+export const MAX_TEXT_BYTES = 3500;
+const SENT_MAX = 2000;
+
+type Args = Record<string, unknown>;
+
+const sentIds = new Set<string>();
+
+function noteSent(messageId: string): void {
+  sentIds.add(messageId);
+  while (sentIds.size > SENT_MAX) {
+    const oldest = sentIds.values().next();
+    if (oldest.done) break;
+    sentIds.delete(oldest.value);
+  }
+}
+
+const sentByUs = (messageId: string): boolean => sentIds.has(messageId);
+
+function listAccounts(id: string): void {
+  const list = [...accounts.values()].map((a) => ({
+    id: a.cfg.id,
+    handle: a.cfg.gatewayId,
+    url: null,
+    owner: a.cfg.owner ?? null,
+    gatewayId: a.cfg.gatewayId,
+    ...(a.cfg.callbackId && a.cfg.callbackToken
+      ? { callbackId: a.cfg.callbackId, callbackToken: a.cfg.callbackToken }
+      : {}),
+  }));
+  respond(id, { result: { accounts: list } });
+}
+
+interface SendArgs {
+  line: string;
+  text?: unknown;
+  replyTo?: unknown;
+  account?: string;
+}
+
+function requireText(a: SendArgs): string {
+  const text = typeof a.text === 'string' ? a.text : '';
+  if (text === '')
+    throw new TrainError(
+      'threema_text_required',
+      'threema carries text only; give some text to send',
+      { retryable: false },
+    );
+  return text;
+}
+
+function replyTargetOf(a: SendArgs): string | undefined {
+  if (a.replyTo === undefined || a.replyTo === null || a.replyTo === '') return undefined;
+  const target = typeof a.replyTo === 'string' ? a.replyTo.toLowerCase() : '';
+  if (!MESSAGE_ID_RE.test(target))
+    throw new TrainError(
+      'threema_bad_reply_target',
+      'replyTo must be a Threema message id, 16 hex characters',
+      { retryable: false },
+    );
+  return target;
+}
+
+async function send(id: string, args: Args): Promise<void> {
+  const a = args as unknown as SendArgs;
+  const text = requireText(a);
+  const replyTo = replyTargetOf(a);
+  const { acct, to } = targetOf(a.line, a.account);
+  const plain = encodeText(replyTo === undefined ? text : quoted(replyTo, text));
+  if (plain.length - 1 > MAX_TEXT_BYTES)
+    throw new TrainError(
+      'threema_message_too_long',
+      `Threema carries at most ${MAX_TEXT_BYTES} bytes of text per message; split it up`,
+      { retryable: false },
+    );
+  const { nonce, box } = seal(plain, await publicKeyFor(acct, to), acct.keys);
+  const messageId = await sendE2E(acct.cfg, to, bytesToHex(nonce), bytesToHex(box));
+  noteSent(messageId);
+  emitOutbound(acct.cfg.id, a.line, messageId, text, replyTo);
+  respond(id, { result: { messageId, account: acct.cfg.id } });
+}
+
+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 deliver(acct: Account, m: InboundMeta, decoded: Decoded): string {
+  const owner = acct.cfg.owner;
+  if (decoded.kind === 'text') {
+    emitInbound(acct.cfg.id, owner, textEnvelope(acct.cfg.id, m, decoded.text, sentByUs));
+    return 'text';
+  }
+  if (decoded.kind === 'receipt') {
+    let reactions = 0;
+    for (const target of decoded.messageIds) {
+      const env = receiptEnvelope(acct.cfg.id, m, decoded.status, target);
+      if (env === null) continue;
+      emitInbound(acct.cfg.id, owner, env);
+      reactions += 1;
+    }
+    return reactions > 0 ? 'reaction' : `receipt:${decoded.status}`;
+  }
+  if (decoded.kind === 'typing') return 'typing';
+  const type = `0x${decoded.type.toString(16)}`;
+  process.stderr.write(
+    `threema[${acct.cfg.id}]: ignored a message of type ${type} from ${m.from}\n`,
+  );
+  return `ignored:${type}`;
+}
+
+async function callback(id: string, args: Args): Promise<void> {
+  const cb = parseCallback(args);
+  const acct = accountFor(cb.account);
+  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 },
+    );
+  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 },
+    };
+  return { action, args: env };
+}
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, send, callback },
+  normalize: normalizeThreema,
+});

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

@@ -0,0 +1,130 @@
+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}`, {
+      ...init,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } 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,
+): Promise<string> {
+  const body = new URLSearchParams({
+    from: c.gatewayId,
+    to,
+    nonce: nonceHex,
+    box: boxHex,
+    secret: c.secret,
+  });
+  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;
+}

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

@@ -0,0 +1,132 @@
+import { createHmac, randomInt, timingSafeEqual } from 'node:crypto';
+import nacl from 'tweetnacl';
+
+export const MSG_TEXT = 0x01;
+export const MSG_DELIVERY_RECEIPT = 0x80;
+export const MSG_TYPING = 0x90;
+
+export const RECEIPT_ACK = 0x03;
+export const RECEIPT_DECLINE = 0x04;
+
+const MESSAGE_ID_BYTES = 8;
+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 function encodeText(text: string): Uint8Array {
+  const utf8 = Buffer.from(text, 'utf8');
+  const out = new Uint8Array(1 + utf8.length);
+  out[0] = MSG_TEXT;
+  out.set(utf8, 1);
+  return out;
+}
+
+export type Decoded =
+  | { kind: 'text'; text: string }
+  | { kind: 'receipt'; status: number; messageIds: string[] }
+  | { kind: 'typing' }
+  | { kind: 'other'; type: number };
+
+function receiptIds(body: Uint8Array): string[] {
+  const ids: string[] = [];
+  for (let at = 1; at + MESSAGE_ID_BYTES <= body.length; at += MESSAGE_ID_BYTES)
+    ids.push(bytesToHex(body.subarray(at, at + MESSAGE_ID_BYTES)));
+  return ids;
+}
+
+export function decode(plain: Uint8Array): Decoded {
+  const type = plain[0];
+  const body = plain.subarray(1);
+  if (type === MSG_TEXT)
+    return { kind: 'text', text: Buffer.from(body).toString('utf8') };
+  if (type === MSG_DELIVERY_RECEIPT)
+    return { kind: 'receipt', status: body[0] ?? 0, messageIds: receiptIds(body) };
+  if (type === MSG_TYPING) return { kind: 'typing' };
+  return { kind: 'other', type: type ?? -1 };
+}
+
+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 };
+}

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

@@ -0,0 +1,123 @@
+import { emit, mintId } from '@metro-labs/core/stations/station-runtime';
+import { RECEIPT_ACK, RECEIPT_DECLINE, unquote } from './crypto.js';
+
+const SELF_URI = process.env.METRO_SELF_URI ?? '';
+
+const REACTION_OF: Record<number, string> = {
+  [RECEIPT_ACK]: '👍',
+  [RECEIPT_DECLINE]: '👎',
+};
+
+export const lineOf = (accountId: string, threemaId: string): string =>
+  `metro://threema/${accountId}/${threemaId}`;
+
+const userOf = (accountId: string, threemaId: string): string =>
+  `metro://threema/${accountId}/user/${threemaId}`;
+
+export interface InboundMeta {
+  from: string;
+  to: string;
+  messageId: string;
+  date: string;
+  nickname?: string;
+}
+
+function tsOf(date: string): string {
+  const seconds = Number(date);
+  return Number.isFinite(seconds) && seconds > 0
+    ? new Date(seconds * 1000).toISOString()
+    : new Date().toISOString();
+}
+
+function base(
+  accountId: string,
+  m: InboundMeta,
+  type: string,
+): Record<string, unknown> {
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: tsOf(m.date),
+    station: 'threema',
+    line: lineOf(accountId, m.from),
+    line_name: m.nickname ?? m.from,
+    from: userOf(accountId, m.from),
+    from_name: m.nickname,
+    from_display_name: m.nickname,
+    is_private: true,
+    payload: { from: m.from, to: m.to, nickname: m.nickname ?? null, type },
+  };
+}
+
+export function textEnvelope(
+  accountId: string,
+  m: InboundMeta,
+  raw: string,
+  sentByUs: (messageId: string) => boolean,
+): Record<string, unknown> {
+  const { replyTo, text } = unquote(raw);
+  return {
+    ...base(accountId, m, 'text'),
+    message_id: m.messageId,
+    text,
+    ...(replyTo === undefined
+      ? {}
+      : {
+          reply_to: replyTo,
+          event: { type: 'reply', replyTo },
+          reply_to_self: sentByUs(replyTo),
+        }),
+  };
+}
+
+export function receiptEnvelope(
+  accountId: string,
+  m: InboundMeta,
+  status: number,
+  targetId: string,
+): Record<string, unknown> | null {
+  const emoji = REACTION_OF[status];
+  if (emoji === undefined) return null;
+  return {
+    ...base(accountId, m, 'receipt'),
+    message_id: `${m.messageId}:${targetId}`,
+    emoji,
+    event: { type: 'react', emoji, targetId },
+  };
+}
+
+export function emitInbound(
+  accountId: string,
+  owner: string | undefined,
+  env: Record<string, unknown>,
+): void {
+  const payload = {
+    ...(env.payload as Record<string, unknown> | undefined),
+    account: accountId,
+  };
+  emit({ ...env, ...(owner ? { to: owner } : {}), account: accountId, payload });
+}
+
+export function emitOutbound(
+  accountId: string,
+  line: string,
+  messageId: string,
+  text: string,
+  replyTo?: string,
+): void {
+  emit({
+    kind: 'outbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: 'threema',
+    line,
+    from: SELF_URI,
+    to: line,
+    message_id: messageId,
+    text,
+    reply_to: replyTo,
+    ...(replyTo ? { event: { type: 'reply', replyTo } } : {}),
+    account: accountId,
+    payload: { account: accountId },
+  });
+}

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

@@ -0,0 +1,21 @@
+export const GATEWAY_API = (
+  process.env.THREEMA_GATEWAY_URL ?? 'https://msgapi.threema.ch'
+).replace(/\/+$/, '');
+
+const THREEMA_ID_RE = /^(?:[A-Z0-9]{8}|\*[A-Z0-9]{7})$/;
+const KEY_HEX_RE = /^[0-9a-f]{64}$/;
+
+export const MESSAGE_ID_RE = /^[0-9a-f]{16}$/;
+
+export const isThreemaId = (raw: string): boolean => THREEMA_ID_RE.test(raw);
+
+export const isGatewayId = (raw: string): boolean =>
+  raw.startsWith('*') && isThreemaId(raw);
+
+export const normalizeThreemaId = (raw: string): string =>
+  raw.trim().toUpperCase();
+
+export function parsePrivateKey(raw: string): string | null {
+  const text = raw.trim().replace(/^private:/i, '').trim().toLowerCase();
+  return KEY_HEX_RE.test(text) ? text : null;
+}

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

@@ -0,0 +1,29 @@
+import { errMsg } from '@metro-labs/core/log';
+import { readCalls } from '@metro-labs/core/trains/protocol';
+import { accounts, bootAccount, loadAccounts } from './accounts.js';
+import { handleCall } from './actions.js';
+import { fetchCredits } from './api.js';
+
+readCalls('threema', handleCall);
+
+for (const cfg of loadAccounts()) accounts.set(cfg.id, bootAccount(cfg));
+if (accounts.size === 0) {
+  process.stderr.write('threema: no accounts booted, exiting\n');
+  process.exit(2);
+}
+process.stderr.write(
+  `threema train ready — ${accounts.size} account(s): ${[...accounts.keys()].join(', ')}\n`,
+);
+
+for (const acct of accounts.values())
+  fetchCredits(acct.cfg)
+    .then((credits) => {
+      process.stderr.write(
+        `threema[${acct.cfg.id}] ${acct.cfg.gatewayId}: ${credits} credits left\n`,
+      );
+    })
+    .catch((err: unknown) => {
+      process.stderr.write(
+        `threema[${acct.cfg.id}] credits check failed: ${errMsg(err)}\n`,
+      );
+    });

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

@@ -0,0 +1,10 @@
+import type { Station, Verb } from '@metro-labs/core/stations/types';
+
+export const threemaStation: Station = {
+  name: 'threema',
+  hasAccounts: true,
+  hasTrain: true,
+  messageVerbs: new Set<Verb>(['send', 'reply']),
+  attachmentMode: 'none',
+  tools: [],
+};