@stage-labs/metro 0.1.0-beta.23 → 0.1.0-beta.231

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/view.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { agentsDir } from '../agents/files.js';
+import { removeHome, writeHomeText } from './home-fs.js';
+import { agentUser, agentViewDir, type AgentUser } from './user.js';
+
+const COPIED = ['policy.json', 'claude-setup.json', 'system-prompt.md'] as const;
+const SYNC_MS = 5_000;
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const readRecord = (path: string): Record<string, unknown> | null => {
+  const text = readText(path);
+  if (text === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+function agentFile(dir: string): string | null {
+  const file = readRecord(join(dir, 'agent.json'));
+  if (file === null || typeof file.id !== 'string' || typeof file.key !== 'string') return null;
+  return json({ version: 1, id: file.id, key: file.key });
+}
+
+function modelFile(dir: string): string | null {
+  const cfg = readRecord(join(dir, 'model.json'));
+  if (cfg === null || !Array.isArray(cfg.connections)) return null;
+  const connections = cfg.connections.filter(isRecord).map((c) => ({ id: c.id, provider: c.provider, model: c.model }));
+  return json({ version: 2, route: cfg.route, connections });
+}
+
+export function viewFiles(dir = agentsDir()): Map<string, string | null> {
+  const files = new Map<string, string | null>([
+    ['agent.json', agentFile(dir)],
+    ['model.json', modelFile(dir)],
+  ]);
+  for (const name of COPIED) files.set(name, existsSync(join(dir, name)) ? readText(join(dir, name)) : null);
+  return files;
+}
+
+const written = new Map<string, string | null>();
+
+function syncAgentView(user: AgentUser | null = agentUser(), dir = agentsDir()): number {
+  if (user === null) return 0;
+  const target = agentViewDir(user);
+  let changed = 0;
+  for (const [name, text] of viewFiles(dir)) {
+    const path = join(target, name);
+    if (written.has(path) && written.get(path) === text) continue;
+    if (text === null) removeHome(path, false, user);
+    else writeHomeText(path, text, 0o600, undefined, user);
+    written.set(path, text);
+    changed += 1;
+  }
+  return changed;
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+export function watchAgentView(everyMs = SYNC_MS): void {
+  if (timer !== null) return;
+  const tick = (): void => {
+    try {
+      const changed = syncAgentView();
+      if (changed > 0) log.info({ changed }, 'agent-user: refreshed the Metro files the agent may read');
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'agent-user: could not refresh the Metro files the agent may read');
+    }
+  };
+  tick();
+  timer = setInterval(tick, everyMs);
+  timer.unref();
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/account-attach.ts

@@ -0,0 +1,19 @@
+import { STATIONS, type StationName } from '@metro-labs/core/station-names';
+
+const ACCOUNT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+export interface AccountRef {
+  agentId: string;
+  station: StationName;
+  accountId: string;
+}
+
+export function isStationName(raw: unknown): raw is StationName {
+  return (
+    typeof raw === 'string' && (STATIONS as readonly string[]).includes(raw)
+  );
+}
+
+export function parseAccountId(raw: string): string | null {
+  return ACCOUNT_ID_RE.test(raw) ? raw : null;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/account-lookups.ts

@@ -0,0 +1,55 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StationName } from '@metro-labs/core/station-names';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { stationByName } from '../stations/registry.js';
+import type { AccountRoute } from './account-routes.js';
+import { handleSenderCards, type SenderCardDeps } from './sender-cards.js';
+
+interface Target {
+  station: StationName;
+  accountId: string;
+}
+
+interface LookupDeps extends SenderCardDeps {
+  resolveSender: (station: StationName, accountId: string, query: string) => Promise<unknown>;
+}
+
+type Lookup = (req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target) => Promise<void>;
+
+function lookupQuery(req: IncomingMessage): string {
+  const params = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  return (params.get('q') ?? '').trim();
+}
+
+async function handleResolve(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  if (stationByName(target.station)?.resolvesSenders !== true)
+    throw new ApiError(`metro cannot look a sender up on ${target.station}`, 400);
+  const query = lookupQuery(req);
+  if (query === '') throw new ApiError('something to look up is required', 400);
+  sendJson(req, res, 200, await deps.resolveSender(target.station, target.accountId, query));
+}
+
+async function handleName(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  if (stationByName(target.station)?.claimsName !== true)
+    throw new ApiError(`${target.station} accounts have no name to claim`, 400);
+  if (req.method === 'GET') {
+    sendJson(req, res, 200, await deps.accountCall(target.station, 'name', { account: target.accountId }));
+    return;
+  }
+  const label = bodyField(await readJsonBody(req), 'label');
+  if (typeof label !== 'string' || label.trim() === '') throw new ApiError('a label is required', 400);
+  sendJson(req, res, 200, await deps.accountCall(target.station, 'claim_name', { account: target.accountId, label }));
+}
+
+function handleRecent(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  sendJson(req, res, 200, { senders: deps.recentSenders(target.station, target.accountId) });
+  return Promise.resolve();
+}
+
+export const LOOKUPS: Partial<Record<AccountRoute['kind'], Lookup>> = {
+  profiles: handleSenderCards,
+  resolve: handleResolve,
+  name: handleName,
+  senders: handleRecent,
+};

package/runtime/node_modules/@metro-labs/daemon/src/agents/account-routes.ts

@@ -0,0 +1,76 @@
+import { isStationName, parseAccountId } from './account-attach.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import { ATTACH_ID_RE } from '../stations/attach-session.js';
+
+export type AccountRoute =
+  | { kind: 'start' }
+  | { kind: 'session'; attachId: string }
+  | { kind: 'step'; attachId: string }
+  | { kind: 'account'; station: StationName; accountId: string }
+  | { kind: 'allowlist'; station: StationName; accountId: string }
+  | { kind: 'senders'; station: StationName; accountId: string }
+  | { kind: 'resolve'; station: StationName; accountId: string }
+  | { kind: 'enabled'; station: StationName; accountId: string }
+  | { kind: 'policy'; station: StationName; accountId: string }
+  | { kind: 'profiles'; station: StationName; accountId: string }
+  | { kind: 'name'; station: StationName; accountId: string };
+
+const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
+  start: ['POST'],
+  session: ['GET', 'DELETE'],
+  step: ['POST'],
+  account: ['DELETE'],
+  allowlist: ['PUT'],
+  senders: ['GET'],
+  resolve: ['GET'],
+  enabled: ['PUT'],
+  policy: ['PUT'],
+  profiles: ['GET'],
+  name: ['GET', 'POST'],
+};
+
+const SUB_ROUTES = ['allowlist', 'senders', 'resolve', 'enabled', 'name', 'policy', 'profiles'] as const;
+
+type SubRoute = (typeof SUB_ROUTES)[number];
+
+const isSubRoute = (value: string | undefined): value is SubRoute =>
+  SUB_ROUTES.some((sub) => sub === value);
+
+function twoSegmentRoute(head: string, tail: string): AccountRoute | null {
+  if (ATTACH_ID_RE.test(head))
+    return tail === 'step' ? { kind: 'step', attachId: head } : null;
+  if (!isStationName(head)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: 'account', station: head, accountId };
+}
+
+function accountSubRoute(
+  head: string,
+  tail: string,
+  sub: string | undefined,
+): AccountRoute | null {
+  if (!isStationName(head) || !isSubRoute(sub)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: sub, station: head, accountId };
+}
+
+export function accountRoute(rest: string[]): AccountRoute | null {
+  const [head, tail] = rest;
+  if (head === undefined) return null;
+  if (rest.length === 1)
+    return head === 'start'
+      ? { kind: 'start' }
+      : ATTACH_ID_RE.test(head)
+        ? { kind: 'session', attachId: head }
+        : null;
+  if (rest.length === 3 && tail !== undefined) return accountSubRoute(head, tail, rest[2]);
+  if (rest.length !== 2 || tail === undefined) return null;
+  return twoSegmentRoute(head, tail);
+}
+
+export function accountRouteAllows(
+  route: AccountRoute,
+  method: string | undefined,
+): boolean {
+  return ROUTE_METHODS[route.kind].includes(method ?? '');
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/accounts-api.ts

@@ -0,0 +1,357 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { normalizeAllowlist, normalizeApprovers } from './allowlist.js';
+import { approversForAccount } from './map.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { RecentSender } from './senders.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiFailure, bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { type AccountRef } from './account-attach.js';
+import { type AccountRoute } from './account-routes.js';
+import { handlePolicy, type SetPolicy } from './policy-route.js';
+import { LOOKUPS } from './account-lookups.js';
+import { unconfirmedSenders } from './sender-cards.js';
+import { stationByName } from '../stations/registry.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import {
+  ATTACHABLE_STATIONS,
+  attachInputOf,
+  isAttachStation,
+  type AttachInput,
+  type OneTimeSecret,
+  type PreparedAccount,
+} from '../stations/attach.js';
+import {
+  INTERACTIVE_STATIONS,
+  isInteractiveStation,
+  type InteractiveStation,
+} from '../stations/attach-interactive.js';
+import type { StepInput } from '../stations/attach-driver.js';
+import {
+  type AttachOwner,
+  type AttachView,
+} from '../stations/attach-session.js';
+
+interface AttachSessionApi {
+  start: (
+    owner: AttachOwner,
+    station: InteractiveStation,
+    input: Record<string, unknown>,
+  ) => Promise<AttachView>;
+  view: (owner: AttachOwner, attachId: string) => AttachView;
+  submit: (
+    owner: AttachOwner,
+    attachId: string,
+    input: StepInput,
+  ) => Promise<AttachView>;
+  cancel: (owner: AttachOwner, attachId: string) => Promise<void>;
+}
+
+export interface AccountApiDeps {
+  attachSessions: AttachSessionApi;
+  prepareAccount: (input: AttachInput) => Promise<PreparedAccount>;
+  attachAccount: (
+    agentId: string,
+    station: StationName,
+    config: Record<string, unknown>,
+  ) => Promise<AccountRef>;
+  detachAccount: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+  ) => Promise<AccountRef>;
+  syncStations: (station: StationName) => Promise<void>;
+  reloadAgents: () => Promise<void>;
+  setAllowlist: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+    allowlist: string[],
+    approvers?: string[],
+  ) => Promise<string[]>;
+  setPolicy: SetPolicy;
+  recentSenders: (station: StationName, accountId: string) => RecentSender[];
+  resolveSender: (
+    station: StationName,
+    accountId: string,
+    query: string,
+  ) => Promise<unknown>;
+  accountCall: (
+    station: StationName,
+    action: string,
+    args: Record<string, unknown>,
+  ) => Promise<unknown>;
+  setAccountEnabled: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+    enabled: boolean,
+  ) => Promise<boolean>;
+}
+
+export const ATTACHABLE: string[] = [...ATTACHABLE_STATIONS, ...INTERACTIVE_STATIONS];
+
+async function activate(
+  deps: AccountApiDeps,
+  station: StationName,
+): Promise<boolean> {
+  try {
+    await deps.syncStations(station);
+    return true;
+  } catch (err) {
+    log.warn(
+      { station, err: errMsg(err) },
+      'account-api: station reload failed, the change lands at the next boot',
+    );
+    return false;
+  }
+}
+
+interface AttachPayload {
+  status: 'done';
+  agentId: string;
+  station: string;
+  accountId: string;
+  identity: Record<string, string>;
+  activated: boolean;
+  secret?: OneTimeSecret;
+}
+
+async function storeAccount(
+  deps: AccountApiDeps,
+  agentId: string,
+  station: StationName,
+  prepared: PreparedAccount,
+): Promise<AccountRef> {
+  try {
+    return await deps.attachAccount(
+      agentId,
+      station,
+      prepared.config,
+    );
+  } catch (err) {
+    prepared.discard?.();
+    throw err;
+  }
+}
+
+
+function asInput(body: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiId', 'apiHash', 'phone', 'mailbox', 'clientId', 'clientSecret'])
+    out[key] = bodyField(body, key);
+  return out;
+}
+
+async function handleStart(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const station = bodyField(body, 'station');
+  if (isInteractiveStation(station)) {
+    const view = await deps.attachSessions.start(
+      { agentId },
+      station,
+      asInput(body),
+    );
+    sendJson(req, res, 201, view);
+    return;
+  }
+  if (!isAttachStation(station))
+    throw new ApiError(`station must be one of ${ATTACHABLE.join(', ')}`, 400);
+  const prepared = await deps.prepareAccount(attachInputOf(station, body));
+  const ref = await storeAccount(deps, agentId, station, prepared);
+  log.info(
+    { agentId: ref.agentId, station, account: ref.accountId },
+    'account-api: attached a station account',
+  );
+  const payload: AttachPayload = {
+    status: 'done',
+    agentId: ref.agentId,
+    station,
+    accountId: ref.accountId,
+    identity: prepared.identity,
+    activated: await activate(deps, station),
+  };
+  sendJson(
+    req,
+    res,
+    201,
+    prepared.secret === undefined
+      ? payload
+      : { ...payload, secret: prepared.secret },
+  );
+}
+
+async function handleDetach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const ref = await deps.detachAccount(
+    agentId,
+    target.station,
+    target.accountId,
+  );
+  log.info(
+    { agentId: ref.agentId, station: ref.station, account: ref.accountId },
+    'account-api: detached a station account',
+  );
+  sendJson(req, res, 200, {
+    agentId: ref.agentId,
+    station: ref.station,
+    accountId: ref.accountId,
+    detached: true,
+    activated: await activate(deps, ref.station),
+  });
+  forgetAccount(ref.station, ref.accountId);
+}
+
+function forgetAccount(station: StationName, accountId: string): void {
+  try {
+    stationByName(station)?.forget?.(accountId);
+  } catch (err) {
+    log.warn(
+      { station, account: accountId, err: errMsg(err) },
+      'account-api: could not remove the files of a detached account',
+    );
+  }
+}
+
+async function applied(deps: AccountApiDeps): Promise<boolean> {
+  try {
+    await deps.reloadAgents();
+    return true;
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'account-api: reload failed, the change lands at the next boot');
+    return false;
+  }
+}
+
+async function handleAllowlist(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const wanted = normalizeAllowlist(bodyField(body, 'allowlist'));
+  const asked = isRecord(body) && 'approvers' in body ? body.approvers : approversForAccount(target.station, target.accountId);
+  const approvers = normalizeApprovers(asked, wanted);
+  const before = new Set(approversForAccount(target.station, target.accountId).map((a) => a.toLowerCase()));
+  const unknown = await unconfirmedSenders(deps, target.station, target.accountId, approvers.filter((a) => !before.has(a.toLowerCase())));
+  if (unknown.length > 0) throw new ApiError(`${target.station} does not know ${unknown.join(', ')}. Check the id, or have them write to the agent once, then try again.`, 400);
+  const allowlist = await deps.setAllowlist(agentId, target.station, target.accountId, wanted, approvers);
+  log.info({ agentId, station: target.station, account: target.accountId, senders: allowlist.length }, 'account-api: allowlist set');
+  sendJson(req, res, 200, {
+    agentId,
+    station: target.station,
+    accountId: target.accountId,
+    allowlist,
+    approvers,
+    activated: await applied(deps),
+  });
+}
+
+async function handleEnabled(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const wanted = bodyField(await readJsonBody(req), 'enabled');
+  if (typeof wanted !== 'boolean') throw new ApiError('enabled must be true or false', 400);
+  const enabled = await deps.setAccountEnabled(agentId, target.station, target.accountId, wanted);
+  log.info({ agentId, station: target.station, account: target.accountId, enabled }, 'account-api: account enabled flag set');
+  sendJson(req, res, 200, {
+    agentId,
+    station: target.station,
+    accountId: target.accountId,
+    enabled,
+    activated: await applied(deps),
+  });
+}
+
+async function handleSession(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  if (req.method === 'DELETE') {
+    await deps.attachSessions.cancel(owner, attachId);
+    sendJson(req, res, 200, { attachId, cancelled: true });
+    return;
+  }
+  sendJson(req, res, 200, deps.attachSessions.view(owner, attachId));
+}
+
+async function handleStep(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const field = (key: string): unknown => bodyField(body, key);
+  const view = await deps.attachSessions.submit(owner, attachId, {
+    code: field('code'),
+    password: field('password'),
+    state: field('state'),
+    mode: field('mode'),
+    error: field('error'),
+    errorDescription: field('errorDescription'),
+  });
+  sendJson(req, res, 200, view);
+}
+
+async function dispatchAttach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: Extract<AccountRoute, { kind: 'start' | 'session' | 'step' }>,
+): Promise<void> {
+  if (route.kind === 'start') return handleStart(req, res, deps, agentId);
+  if (route.kind === 'session') return handleSession(req, res, deps, { agentId }, route.attachId);
+  return handleStep(req, res, deps, { agentId }, route.attachId);
+}
+
+async function dispatchRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  if (route.kind === 'start' || route.kind === 'session' || route.kind === 'step') return dispatchAttach(req, res, deps, agentId, route);
+  if (route.kind === 'allowlist') return handleAllowlist(req, res, deps, agentId, route);
+  if (route.kind === 'enabled') return handleEnabled(req, res, deps, agentId, route);
+  if (route.kind === 'policy') return handlePolicy(req, res, deps, agentId, route);
+  const lookup = LOOKUPS[route.kind];
+  if (lookup !== undefined && 'station' in route) return lookup(req, res, deps, route);
+  return handleDetach(req, res, deps, agentId, route);
+}
+
+export async function handleAccountRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  try {
+    await dispatchRoute(req, res, deps, agentId, route);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/admin.ts

@@ -0,0 +1,30 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError } from '@metro-labs/http/api-error';
+import { AGENT_NAME_RE } from '@metro-labs/core/ids';
+
+export class AgentAdminError extends ApiError {}
+
+export interface AgentSummary {
+  id: string;
+  name: string | null;
+}
+
+export interface CreatedAgent {
+  id: string;
+  name: string | null;
+  key: string;
+}
+
+export function normalizeAgentName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim() : '';
+  if (!AGENT_NAME_RE.test(name))
+    throw new AgentAdminError(
+      'name must be 2-32 characters of A-Z, a-z, 0-9, - or _, starting with a letter or digit',
+      400,
+    );
+  return name;
+}
+
+export function newApiKey(): string {
+  return `mk_${randomBytes(32).toString('base64url')}`;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/allowlist.ts

@@ -0,0 +1,59 @@
+import { ApiError } from '@metro-labs/http/api-error';
+
+const EVERYONE = '*';
+const MAX_ENTRIES = 500;
+const MAX_LENGTH = 200;
+
+function hasControlChar(value: string): boolean {
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+const DOMAIN_ENTRY_RE = /^@[a-z0-9-]+(\.[a-z0-9-]+)+$/;
+
+function domainEntry(value: string): string {
+  const domain = value.toLowerCase();
+  if (!DOMAIN_ENTRY_RE.test(domain))
+    throw new ApiError(`'${value}' is not a domain; write it as @example.com`, 400);
+  return domain;
+}
+
+function senderId(entry: unknown): string {
+  if (typeof entry !== 'string') throw new ApiError('allowlist must be a list of sender ids', 400);
+  const value = entry.trim();
+  if (value.length > MAX_LENGTH || hasControlChar(value))
+    throw new ApiError(`a sender id is at most ${String(MAX_LENGTH)} plain characters`, 400);
+  return value.startsWith('@') ? domainEntry(value) : value;
+}
+
+export function normalizeApprovers(raw: unknown, allowlist: string[]): string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new ApiError('approvers must be a list of sender ids', 400);
+  const listed = new Set(allowlist.map((entry) => entry.toLowerCase()));
+  const seen = new Set<string>();
+  return raw.map(senderId).filter((value) => {
+    const key = value.toLowerCase();
+    if (!listed.has(key) || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function normalizeAllowlist(raw: unknown): string[] {
+  if (!Array.isArray(raw)) throw new ApiError('allowlist must be a list of sender ids', 400);
+  if (raw.length > MAX_ENTRIES) throw new ApiError(`allowlist holds at most ${String(MAX_ENTRIES)} senders`, 400);
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of raw) {
+    const value = senderId(entry);
+    if (value === EVERYONE) return [EVERYONE];
+    const key = value.toLowerCase();
+    if (key === '' || seen.has(key)) continue;
+    seen.add(key);
+    out.push(value);
+  }
+  return out.length === 0 ? [EVERYONE] : out;
+}