chore: consolidate new foundation and archive v1 (#1495)
This commit is contained in:
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"name": "@mosaicstack/appservice",
|
||||
"version": "0.0.1",
|
||||
"type": "module",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||
"directory": "packages/appservice"
|
||||
},
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"lint": "eslint src",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run --passWithNoTests"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"typescript": "^5.8.0",
|
||||
"vitest": "^2.0.0"
|
||||
},
|
||||
"publishConfig": {
|
||||
"registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
|
||||
"access": "public"
|
||||
},
|
||||
"files": [
|
||||
"dist"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import { AGENTS_ACCOUNT_DATA_TYPE, AgentTokenStore } from '../agent-store.js';
|
||||
import type { AppserviceIntent } from '../intent.js';
|
||||
|
||||
/** Fake intent: in-memory account_data, no-op user provisioning. Only the
|
||||
* surface AgentTokenStore touches is implemented. */
|
||||
const makeFakeIntent = () => {
|
||||
const store: Record<string, Record<string, unknown>> = {};
|
||||
const fake = {
|
||||
domain: 'hs.example',
|
||||
getSenderAccountData: async (type: string): Promise<Record<string, unknown> | null> =>
|
||||
store[type] ?? null,
|
||||
setSenderAccountData: async (type: string, content: Record<string, unknown>): Promise<void> => {
|
||||
store[type] = structuredClone(content);
|
||||
},
|
||||
ensureRegistered: async (agent: string): Promise<string> => `@agent-${agent}:hs.example`,
|
||||
setDisplayName: async (): Promise<void> => {},
|
||||
};
|
||||
return { intent: fake as unknown as AppserviceIntent, store };
|
||||
};
|
||||
|
||||
describe('AgentTokenStore', () => {
|
||||
it('mints a magt_ token and stores only its sha256 (never plaintext)', async () => {
|
||||
const { intent, store } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
const { agentUserId, token } = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
|
||||
expect(agentUserId).toBe('@agent-pi0-web1:hs.example');
|
||||
expect(token.startsWith('magt_')).toBe(true);
|
||||
|
||||
const raw = JSON.stringify(store[AGENTS_ACCOUNT_DATA_TYPE]);
|
||||
expect(raw).not.toContain(token);
|
||||
// The stored hash is sha256hex(token), 64 hex chars.
|
||||
const { createHash } = await import('node:crypto');
|
||||
const hash = createHash('sha256').update(token).digest('hex');
|
||||
expect(raw).toContain(hash);
|
||||
});
|
||||
|
||||
it('verifyToken returns the agentUserId for a fresh token, null otherwise', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
const { agentUserId, token } = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
|
||||
expect(await s.verifyToken(token)).toBe(agentUserId);
|
||||
expect(await s.verifyToken('magt_garbage')).toBeNull();
|
||||
expect(await s.verifyToken('not-a-token')).toBeNull();
|
||||
expect(await s.verifyToken('')).toBeNull();
|
||||
});
|
||||
|
||||
it('revoke invalidates tokens, returns count, and hides agent from list', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
const { agentUserId, token } = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
|
||||
expect((await s.list()).map((a) => a.agent_user_id)).toContain(agentUserId);
|
||||
|
||||
const count = await s.revoke(agentUserId);
|
||||
expect(count).toBe(1);
|
||||
expect(await s.verifyToken(token)).toBeNull();
|
||||
expect((await s.list()).map((a) => a.agent_user_id)).not.toContain(agentUserId);
|
||||
|
||||
// Idempotent on unknown / already-revoked.
|
||||
expect(await s.revoke(agentUserId)).toBe(0);
|
||||
expect(await s.revoke('@agent-nope:hs.example')).toBe(0);
|
||||
});
|
||||
|
||||
it('re-register after revoke yields a working token and the agent reappears', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
const { agentUserId, token: t1 } = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
await s.revoke(agentUserId);
|
||||
|
||||
const { token: t2 } = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
expect(await s.verifyToken(t1)).toBeNull();
|
||||
expect(await s.verifyToken(t2)).toBe(agentUserId);
|
||||
expect((await s.list()).map((a) => a.agent_user_id)).toContain(agentUserId);
|
||||
});
|
||||
|
||||
it('agent A token never verifies as agent B', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
const a = await s.register({ alias: 'pi0', host: 'web1' });
|
||||
const b = await s.register({ alias: 'pi1', host: 'web2' });
|
||||
|
||||
expect(await s.verifyToken(a.token)).toBe(a.agentUserId);
|
||||
expect(await s.verifyToken(b.token)).toBe(b.agentUserId);
|
||||
expect(a.agentUserId).not.toBe(b.agentUserId);
|
||||
});
|
||||
|
||||
it('rejects an ambiguous re-registration that collides on one Matrix id', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
// alias="a-b",host="c" and alias="a",host="b-c" both -> @agent-a-b-c.
|
||||
const first = await s.register({ alias: 'a-b', host: 'c' });
|
||||
expect(first.agentUserId).toBe('@agent-a-b-c:hs.example');
|
||||
|
||||
await expect(s.register({ alias: 'a', host: 'b-c' })).rejects.toThrow(/collision/);
|
||||
|
||||
// The original registration is untouched: still one active token, correct pair.
|
||||
expect(await s.verifyToken(first.token)).toBe(first.agentUserId);
|
||||
const summary = (await s.list()).find((x) => x.agent_user_id === first.agentUserId);
|
||||
expect(summary?.alias).toBe('a-b');
|
||||
expect(summary?.host).toBe('c');
|
||||
expect(summary?.active_token_count).toBe(1);
|
||||
});
|
||||
|
||||
it('display_name is stored and surfaced in list', async () => {
|
||||
const { intent } = makeFakeIntent();
|
||||
const s = new AgentTokenStore(intent);
|
||||
await s.register({ alias: 'pi0', host: 'web1', displayName: 'Pi Zero' });
|
||||
const summary = (await s.list())[0];
|
||||
expect(summary?.display_name).toBe('Pi Zero');
|
||||
expect(summary?.active_token_count).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,230 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
|
||||
import { validateBridgeMessage, validateBridgeTyping } from '../bridge.dto.js';
|
||||
import { AppserviceIntent, MatrixApiError } from '../intent.js';
|
||||
import { buildRegistration, registrationToYaml } from '../registration.js';
|
||||
import { TransactionHandler } from '../transactions.js';
|
||||
import type { AppserviceConfig, MatrixEvent } from '../types.js';
|
||||
|
||||
const cfg: AppserviceConfig = {
|
||||
homeserverUrl: 'https://hs.example',
|
||||
domain: 'hs.example',
|
||||
asToken: 'as-secret',
|
||||
hsToken: 'hs-secret',
|
||||
};
|
||||
|
||||
const jsonResponse = (status: number, body: unknown): Response =>
|
||||
new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
|
||||
|
||||
describe('TransactionHandler', () => {
|
||||
const makeHandler = (onEvent = vi.fn()) => ({
|
||||
onEvent,
|
||||
handler: new TransactionHandler({ hsToken: 'hs-secret', onEvent }),
|
||||
});
|
||||
|
||||
it('rejects a bad hs_token with M_FORBIDDEN', async () => {
|
||||
const { handler, onEvent } = makeHandler();
|
||||
const res = await handler.handle(
|
||||
't1',
|
||||
{ events: [{ type: 'm.room.message' }] },
|
||||
{ authorizationHeader: 'Bearer wrong' },
|
||||
);
|
||||
expect(res.status).toBe(403);
|
||||
expect(res.body.errcode).toBe('M_FORBIDDEN');
|
||||
expect(onEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('accepts Bearer auth and legacy access_token param', async () => {
|
||||
const { handler } = makeHandler();
|
||||
expect(
|
||||
(await handler.handle('t1', { events: [] }, { authorizationHeader: 'Bearer hs-secret' }))
|
||||
.status,
|
||||
).toBe(200);
|
||||
expect(
|
||||
(await handler.handle('t2', { events: [] }, { accessTokenParam: 'hs-secret' })).status,
|
||||
).toBe(200);
|
||||
});
|
||||
|
||||
it('processes events once per txnId (idempotent retries)', async () => {
|
||||
const { handler, onEvent } = makeHandler();
|
||||
const body = { events: [{ type: 'm.room.message', event_id: '$e1' }] };
|
||||
await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
|
||||
const retry = await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
|
||||
expect(retry.status).toBe(200);
|
||||
expect(onEvent).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('a throwing event handler does not fail the transaction', async () => {
|
||||
const onError = vi.fn();
|
||||
const handler = new TransactionHandler({
|
||||
hsToken: 'hs-secret',
|
||||
onEvent: () => {
|
||||
throw new Error('boom');
|
||||
},
|
||||
onError,
|
||||
});
|
||||
const res = await handler.handle(
|
||||
't1',
|
||||
{ events: [{ type: 'x' }, { type: 'y' }] },
|
||||
{ authorizationHeader: 'Bearer hs-secret' },
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
expect(onError).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('AppserviceIntent', () => {
|
||||
it('derives namespaced user ids and rejects bad slugs', () => {
|
||||
const intent = new AppserviceIntent(cfg);
|
||||
expect(intent.agentUserId('pi0-web1')).toBe('@agent-pi0-web1:hs.example');
|
||||
expect(intent.agentUserId('Pi0-Web1')).toBe('@agent-pi0-web1:hs.example');
|
||||
expect(() => intent.agentUserId('../evil')).toThrow();
|
||||
expect(() => intent.agentUserId('')).toThrow();
|
||||
});
|
||||
|
||||
it('uses uuid transaction ids', async () => {
|
||||
const calls: string[] = [];
|
||||
const fetchMock = vi.fn(async (input: URL | string) => {
|
||||
calls.push(new URL(String(input)).pathname);
|
||||
return jsonResponse(200, {});
|
||||
});
|
||||
const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
|
||||
await intent.sendAsAgent({ roomId: '!r:hs.example', agent: 'pi0', body: 'x' });
|
||||
const send = calls.find((p) => p.includes('/send/m.room.message/'));
|
||||
expect(send).toMatch(/mosaic-as-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
|
||||
});
|
||||
|
||||
it('registers once, impersonates via user_id, threads replies', async () => {
|
||||
const calls: Array<{ url: URL; init: RequestInit }> = [];
|
||||
const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
|
||||
calls.push({ url: new URL(String(input)), init: init ?? {} });
|
||||
return jsonResponse(200, { event_id: '$sent' });
|
||||
});
|
||||
const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
|
||||
|
||||
const eventId = await intent.sendAsAgent({
|
||||
roomId: '!room:hs.example',
|
||||
agent: 'pi0-web1',
|
||||
body: 'hello',
|
||||
threadRoot: '$req',
|
||||
});
|
||||
await intent.sendAsAgent({ roomId: '!room:hs.example', agent: 'pi0-web1', body: 'again' });
|
||||
|
||||
expect(eventId).toBe('$sent');
|
||||
const paths = calls.map((c) => c.url.pathname);
|
||||
expect(paths.filter((p) => p.endsWith('/register'))).toHaveLength(1); // cached
|
||||
expect(paths.filter((p) => p.includes('/join'))).toHaveLength(1); // cached
|
||||
|
||||
const send = calls.find((c) => c.url.pathname.includes('/send/m.room.message/'));
|
||||
expect(send).toBeDefined();
|
||||
expect(send!.url.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
|
||||
const content = JSON.parse(String(send!.init.body)) as Record<string, unknown>;
|
||||
const rel = content['m.relates_to'] as Record<string, unknown>;
|
||||
expect(rel.rel_type).toBe('m.thread');
|
||||
expect(rel.event_id).toBe('$req');
|
||||
expect(rel.is_falling_back).toBe(true);
|
||||
expect(
|
||||
calls.every(
|
||||
(c) => (c.init.headers as Record<string, string>).Authorization === 'Bearer as-secret',
|
||||
),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it('tolerates M_USER_IN_USE and surfaces other register errors', async () => {
|
||||
const inUse = vi.fn(async () =>
|
||||
jsonResponse(400, { errcode: 'M_USER_IN_USE', error: 'taken' }),
|
||||
);
|
||||
const intent = new AppserviceIntent(cfg, inUse as unknown as typeof fetch);
|
||||
await expect(intent.ensureRegistered('pi0-web1')).resolves.toBe('@agent-pi0-web1:hs.example');
|
||||
|
||||
const denied = vi.fn(async () =>
|
||||
jsonResponse(401, { errcode: 'M_UNKNOWN_TOKEN', error: 'nope' }),
|
||||
);
|
||||
const intent2 = new AppserviceIntent(cfg, denied as unknown as typeof fetch);
|
||||
await expect(intent2.ensureRegistered('pi0-web1')).rejects.toThrow(MatrixApiError);
|
||||
});
|
||||
|
||||
it('invites then joins on M_FORBIDDEN join', async () => {
|
||||
const paths: string[] = [];
|
||||
const fetchMock = vi.fn(async (input: URL | string) => {
|
||||
const url = new URL(String(input));
|
||||
paths.push(url.pathname);
|
||||
if (url.pathname.endsWith('/join') && paths.filter((p) => p.endsWith('/join')).length === 1) {
|
||||
return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'not invited' });
|
||||
}
|
||||
return jsonResponse(200, {});
|
||||
});
|
||||
const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
|
||||
await intent.ensureJoined('!room:hs.example', 'pi0-web1');
|
||||
expect(paths.filter((p) => p.endsWith('/invite'))).toHaveLength(1);
|
||||
expect(paths.filter((p) => p.endsWith('/join'))).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('registration', () => {
|
||||
it('builds an exclusive escaped user namespace', () => {
|
||||
const reg = buildRegistration(cfg, { url: 'http://mosaic-as:8008' });
|
||||
expect(reg.namespaces.users[0]).toEqual({
|
||||
regex: '@agent-.*:hs\\.example',
|
||||
exclusive: true,
|
||||
});
|
||||
expect(reg.rate_limited).toBe(false);
|
||||
const yaml = registrationToYaml(reg);
|
||||
expect(yaml).toContain("sender_localpart: 'mosaic-as'");
|
||||
expect(yaml).toContain("as_token: 'as-secret'");
|
||||
expect(yaml).toContain('exclusive: true');
|
||||
});
|
||||
});
|
||||
|
||||
describe('registration hardening', () => {
|
||||
it('rejects control characters in registration values', () => {
|
||||
const reg = buildRegistration(
|
||||
{ ...cfg, asToken: 'abc\nhttp_injected: true' },
|
||||
{ url: 'http://mosaic-as:8008' },
|
||||
);
|
||||
expect(() => registrationToYaml(reg)).toThrow(/control characters/);
|
||||
});
|
||||
|
||||
it('escapes single quotes in token values', () => {
|
||||
const reg = buildRegistration({ ...cfg, asToken: "it's" }, { url: 'http://mosaic-as:8008' });
|
||||
expect(registrationToYaml(reg)).toContain("as_token: 'it''s'");
|
||||
});
|
||||
});
|
||||
|
||||
describe('bridge DTOs', () => {
|
||||
it('validates message and typing payloads', () => {
|
||||
expect(() =>
|
||||
validateBridgeMessage({ room_id: '!r:hs', agent: 'pi0', body: 'x' }),
|
||||
).not.toThrow();
|
||||
expect(() => validateBridgeMessage({ room_id: 'bad', agent: 'pi0', body: 'x' })).toThrow();
|
||||
expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '', body: 'x' })).toThrow();
|
||||
expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '../evil', body: 'x' })).toThrow(
|
||||
/agent must match/,
|
||||
);
|
||||
expect(() =>
|
||||
validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: true }),
|
||||
).not.toThrow();
|
||||
expect(() => validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: 'yes' })).toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe('event shape', () => {
|
||||
it('transaction events flow through to the handler', async () => {
|
||||
const seen: MatrixEvent[] = [];
|
||||
const handler = new TransactionHandler({
|
||||
hsToken: 'hs-secret',
|
||||
onEvent: (e) => void seen.push(e),
|
||||
});
|
||||
await handler.handle(
|
||||
't1',
|
||||
{
|
||||
events: [
|
||||
{ type: 'm.room.message', room_id: '!r:hs', sender: '@u:hs', content: { body: 'hi' } },
|
||||
],
|
||||
},
|
||||
{ authorizationHeader: 'Bearer hs-secret' },
|
||||
);
|
||||
expect(seen).toHaveLength(1);
|
||||
expect(seen[0]!.content?.body).toBe('hi');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,63 @@
|
||||
/** DTOs for agent registration + scoped/revocable bridge tokens (US-007). */
|
||||
|
||||
export interface RegisterAgentDto {
|
||||
/** Agent alias slug, e.g. "pi0". Combined with host into the agent slug. */
|
||||
alias: string;
|
||||
/** Host slug, e.g. "web1". Combined with alias into the agent slug. */
|
||||
host: string;
|
||||
display_name?: string;
|
||||
}
|
||||
|
||||
export interface RevokeAgentDto {
|
||||
agent_user_id: string;
|
||||
}
|
||||
|
||||
export interface RegisterAgentResponse {
|
||||
agent_user_id: string;
|
||||
bridge_token: string;
|
||||
}
|
||||
|
||||
export interface AgentSummary {
|
||||
agent_user_id: string;
|
||||
alias: string;
|
||||
host: string;
|
||||
display_name?: string;
|
||||
created_at: string;
|
||||
active_token_count: number;
|
||||
}
|
||||
|
||||
const SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
|
||||
|
||||
/** Combined agent slug, e.g. alias="pi0", host="web1" -> "pi0-web1". */
|
||||
export function agentSlug(alias: string, host: string): string {
|
||||
return `${alias}-${host}`;
|
||||
}
|
||||
|
||||
const assertSlug = (value: unknown, field: string): void => {
|
||||
if (typeof value !== 'string' || value.length === 0 || !SLUG_RE.test(value)) {
|
||||
throw new Error(`${field} must match [a-z0-9][a-z0-9_.-]* (lowercase, non-empty)`);
|
||||
}
|
||||
};
|
||||
|
||||
export function validateRegisterAgent(input: unknown): asserts input is RegisterAgentDto {
|
||||
const o = input as Partial<RegisterAgentDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
assertSlug(o.alias, 'alias');
|
||||
assertSlug(o.host, 'host');
|
||||
if (o.display_name !== undefined) {
|
||||
if (typeof o.display_name !== 'string' || o.display_name.length === 0) {
|
||||
throw new Error('display_name must be a non-empty string');
|
||||
}
|
||||
if (o.display_name.length > 100) {
|
||||
throw new Error('display_name must be at most 100 chars');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function validateRevokeAgent(input: unknown): asserts input is RevokeAgentDto {
|
||||
const o = input as Partial<RevokeAgentDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
if (typeof o.agent_user_id !== 'string' || !o.agent_user_id.startsWith('@')) {
|
||||
throw new Error('agent_user_id must be a Matrix user id');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,160 @@
|
||||
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
|
||||
|
||||
import { agentSlug } from './agent-registry.dto.js';
|
||||
import type { AgentSummary } from './agent-registry.dto.js';
|
||||
import type { AppserviceIntent } from './intent.js';
|
||||
|
||||
/** account_data type holding the agent registry on the AS sender user. */
|
||||
export const AGENTS_ACCOUNT_DATA_TYPE = 'org.uscllc.mosaic_as.agents';
|
||||
|
||||
const TOKEN_PREFIX = 'magt_';
|
||||
|
||||
interface StoredAgent {
|
||||
alias: string;
|
||||
host: string;
|
||||
display_name?: string;
|
||||
created_at: string;
|
||||
/** sha256hex of each active token. Plaintext tokens are NEVER stored. */
|
||||
token_hashes: string[];
|
||||
revoked_at?: string;
|
||||
}
|
||||
|
||||
interface AgentRegistry {
|
||||
agents: Record<string, StoredAgent>;
|
||||
}
|
||||
|
||||
const sha256hex = (value: string): string => createHash('sha256').update(value).digest('hex');
|
||||
|
||||
const mintToken = (): string => `${TOKEN_PREFIX}${randomBytes(32).toString('base64url')}`;
|
||||
|
||||
/**
|
||||
* Persists scoped/revocable bridge tokens for agent virtual users in Matrix
|
||||
* account_data on the AS sender user (no new infra; survives restart).
|
||||
*
|
||||
* Tokens are stored only as sha256 hashes (the high-entropy `magt_` token makes
|
||||
* plain sha256 safe — no salt/KDF needed since brute force is infeasible).
|
||||
*
|
||||
* KNOWN v1 LIMIT: Synapse caps a single account_data object (default
|
||||
* max_account_data_size, ~100KB). Each agent + hash entry is small, so this
|
||||
* supports thousands of agents, but a very large fleet would eventually need a
|
||||
* dedicated store. Revoked agents with no active tokens are pruned of hashes
|
||||
* (kept as tombstones) to bound growth.
|
||||
*/
|
||||
export class AgentTokenStore {
|
||||
constructor(private readonly intent: AppserviceIntent) {}
|
||||
|
||||
/** Read the registry fresh from account_data (low-frequency ops favor
|
||||
* correctness over caching; verifyToken/list also read fresh). */
|
||||
private async read(): Promise<AgentRegistry> {
|
||||
const data = await this.intent.getSenderAccountData(AGENTS_ACCOUNT_DATA_TYPE);
|
||||
const agents = data?.agents;
|
||||
if (agents && typeof agents === 'object') {
|
||||
return { agents: agents as Record<string, StoredAgent> };
|
||||
}
|
||||
return { agents: {} };
|
||||
}
|
||||
|
||||
private async write(registry: AgentRegistry): Promise<void> {
|
||||
await this.intent.setSenderAccountData(AGENTS_ACCOUNT_DATA_TYPE, {
|
||||
agents: registry.agents,
|
||||
});
|
||||
}
|
||||
|
||||
/** Ensure the virtual user exists, mint a fresh token, store its hash, and
|
||||
* return the plaintext token ONCE. Clears any prior revocation. */
|
||||
async register(opts: {
|
||||
alias: string;
|
||||
host: string;
|
||||
displayName?: string;
|
||||
}): Promise<{ agentUserId: string; token: string }> {
|
||||
const slug = agentSlug(opts.alias, opts.host);
|
||||
const agentUserId = await this.intent.ensureRegistered(slug);
|
||||
if (opts.displayName !== undefined) {
|
||||
await this.intent.setDisplayName(slug, opts.displayName);
|
||||
}
|
||||
|
||||
const token = mintToken();
|
||||
const hash = sha256hex(token);
|
||||
|
||||
const registry = await this.read();
|
||||
const existing = registry.agents[agentUserId];
|
||||
if (existing) {
|
||||
// The agent slug `<alias>-<host>` joins with a `-`, which is also a legal
|
||||
// slug char, so distinct pairs can collide on one Matrix id (e.g.
|
||||
// a/b-c and a-b/c both -> @agent-a-b-c). They ARE the same Matrix user,
|
||||
// but silently overwriting the stored alias/host of a different pair
|
||||
// would conflate two logical agents into one token bucket. Reject the
|
||||
// ambiguous re-registration instead of overwriting.
|
||||
if (existing.alias !== opts.alias || existing.host !== opts.host) {
|
||||
throw new Error(
|
||||
`agent id collision: ${agentUserId} already registered as ` +
|
||||
`${existing.alias}/${existing.host}, refusing ${opts.alias}/${opts.host}`,
|
||||
);
|
||||
}
|
||||
if (opts.displayName !== undefined) existing.display_name = opts.displayName;
|
||||
existing.token_hashes = [...existing.token_hashes, hash];
|
||||
delete existing.revoked_at;
|
||||
} else {
|
||||
registry.agents[agentUserId] = {
|
||||
alias: opts.alias,
|
||||
host: opts.host,
|
||||
...(opts.displayName !== undefined ? { display_name: opts.displayName } : {}),
|
||||
created_at: new Date().toISOString(),
|
||||
token_hashes: [hash],
|
||||
};
|
||||
}
|
||||
await this.write(registry);
|
||||
return { agentUserId, token };
|
||||
}
|
||||
|
||||
/** Return the agentUserId bound to an active (non-revoked) token, else null.
|
||||
* Constant-time hash comparison; no early-out on match. */
|
||||
async verifyToken(token: string): Promise<string | null> {
|
||||
if (!token.startsWith(TOKEN_PREFIX)) return null;
|
||||
const presented = Buffer.from(sha256hex(token), 'hex');
|
||||
|
||||
const registry = await this.read();
|
||||
let matched: string | null = null;
|
||||
for (const [agentUserId, agent] of Object.entries(registry.agents)) {
|
||||
if (agent.revoked_at) continue;
|
||||
for (const stored of agent.token_hashes) {
|
||||
const candidate = Buffer.from(stored, 'hex');
|
||||
if (candidate.length === presented.length && timingSafeEqual(candidate, presented)) {
|
||||
// No early break: keep scanning so timing does not reveal match position.
|
||||
matched = agentUserId;
|
||||
}
|
||||
}
|
||||
}
|
||||
return matched;
|
||||
}
|
||||
|
||||
/** Revoke all active tokens for an agent. Idempotent; returns count revoked. */
|
||||
async revoke(agentUserId: string): Promise<number> {
|
||||
const registry = await this.read();
|
||||
const agent = registry.agents[agentUserId];
|
||||
if (!agent) return 0;
|
||||
const count = agent.token_hashes.length;
|
||||
agent.token_hashes = [];
|
||||
agent.revoked_at = new Date().toISOString();
|
||||
await this.write(registry);
|
||||
return count;
|
||||
}
|
||||
|
||||
/** List agents with at least one active token (never advertise revoked/phantom). */
|
||||
async list(): Promise<AgentSummary[]> {
|
||||
const registry = await this.read();
|
||||
const out: AgentSummary[] = [];
|
||||
for (const [agentUserId, agent] of Object.entries(registry.agents)) {
|
||||
if (agent.revoked_at || agent.token_hashes.length === 0) continue;
|
||||
out.push({
|
||||
agent_user_id: agentUserId,
|
||||
alias: agent.alias,
|
||||
host: agent.host,
|
||||
...(agent.display_name !== undefined ? { display_name: agent.display_name } : {}),
|
||||
created_at: agent.created_at,
|
||||
active_token_count: agent.token_hashes.length,
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
/** DTOs for the internal bridge API consumed by agent-comms host daemons. */
|
||||
|
||||
export interface BridgeMessageDto {
|
||||
room_id: string;
|
||||
/** Agent slug (localpart suffix), e.g. "pi0-web1". */
|
||||
agent: string;
|
||||
body: string;
|
||||
thread_root?: string;
|
||||
msgtype?: string;
|
||||
/** Optional protocol payload merged into content (e.g. org.uscllc.agent). */
|
||||
extra_content?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface BridgeTypingDto {
|
||||
room_id: string;
|
||||
agent: string;
|
||||
typing: boolean;
|
||||
}
|
||||
|
||||
const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
|
||||
|
||||
const assertAgentSlug = (agent: unknown): void => {
|
||||
if (typeof agent !== 'string' || !AGENT_SLUG_RE.test(agent.toLowerCase())) {
|
||||
throw new Error('agent must match [a-z0-9][a-z0-9_.-]*');
|
||||
}
|
||||
};
|
||||
|
||||
export function validateBridgeMessage(input: unknown): asserts input is BridgeMessageDto {
|
||||
const o = input as Partial<BridgeMessageDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
|
||||
throw new Error('room_id must be a Matrix room id');
|
||||
assertAgentSlug(o.agent);
|
||||
if (typeof o.body !== 'string') throw new Error('body must be a string');
|
||||
if (o.thread_root !== undefined && typeof o.thread_root !== 'string')
|
||||
throw new Error('thread_root must be a string');
|
||||
if (
|
||||
o.extra_content !== undefined &&
|
||||
(typeof o.extra_content !== 'object' || o.extra_content === null)
|
||||
) {
|
||||
throw new Error('extra_content must be an object');
|
||||
}
|
||||
}
|
||||
|
||||
export function validateBridgeTyping(input: unknown): asserts input is BridgeTypingDto {
|
||||
const o = input as Partial<BridgeTypingDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
|
||||
throw new Error('room_id must be a Matrix room id');
|
||||
assertAgentSlug(o.agent);
|
||||
if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
|
||||
}
|
||||
|
||||
export interface ProvisionRoomDto {
|
||||
name: string;
|
||||
alias?: string;
|
||||
topic?: string;
|
||||
invite?: string[];
|
||||
space_id?: string;
|
||||
}
|
||||
|
||||
export function validateProvisionRoom(input: unknown): asserts input is ProvisionRoomDto {
|
||||
const o = input as Partial<ProvisionRoomDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
if (typeof o.name !== 'string' || o.name.length === 0) throw new Error('name is required');
|
||||
if (o.alias !== undefined && (!/^[a-z0-9_.-]+$/.test(o.alias) || o.alias.length > 200)) {
|
||||
throw new Error('alias must match [a-z0-9_.-]+ (max 200 chars)');
|
||||
}
|
||||
if (o.invite !== undefined) {
|
||||
if (
|
||||
!Array.isArray(o.invite) ||
|
||||
o.invite.some((u) => typeof u !== 'string' || !u.startsWith('@'))
|
||||
) {
|
||||
throw new Error('invite must be a list of Matrix user ids');
|
||||
}
|
||||
if (o.invite.length > 50) {
|
||||
throw new Error('invite list exceeds maximum of 50');
|
||||
}
|
||||
}
|
||||
if (o.space_id !== undefined && (typeof o.space_id !== 'string' || !o.space_id.startsWith('!'))) {
|
||||
throw new Error('space_id must be a Matrix room id');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
export { AppserviceIntent, MatrixApiError } from './intent.js';
|
||||
export type { SendMessageOptions } from './intent.js';
|
||||
export { TransactionHandler } from './transactions.js';
|
||||
export type { TransactionHandlerOptions } from './transactions.js';
|
||||
export { buildRegistration, registrationToYaml } from './registration.js';
|
||||
export type { RegistrationOptions } from './registration.js';
|
||||
export {
|
||||
validateBridgeMessage,
|
||||
validateBridgeTyping,
|
||||
validateProvisionRoom,
|
||||
} from './bridge.dto.js';
|
||||
export type { BridgeMessageDto, BridgeTypingDto, ProvisionRoomDto } from './bridge.dto.js';
|
||||
export { agentSlug, validateRegisterAgent, validateRevokeAgent } from './agent-registry.dto.js';
|
||||
export type {
|
||||
RegisterAgentDto,
|
||||
RevokeAgentDto,
|
||||
RegisterAgentResponse,
|
||||
AgentSummary,
|
||||
} from './agent-registry.dto.js';
|
||||
export { AgentTokenStore, AGENTS_ACCOUNT_DATA_TYPE } from './agent-store.js';
|
||||
export type {
|
||||
AppserviceConfig,
|
||||
EventHandler,
|
||||
HandlerResult,
|
||||
MatrixEvent,
|
||||
Transaction,
|
||||
} from './types.js';
|
||||
@@ -0,0 +1,262 @@
|
||||
import crypto from 'node:crypto';
|
||||
|
||||
import type { AppserviceConfig } from './types.js';
|
||||
|
||||
export interface SendMessageOptions {
|
||||
roomId: string;
|
||||
/** Agent slug, e.g. "pi0-web1" -> @agent-pi0-web1:domain */
|
||||
agent: string;
|
||||
body: string;
|
||||
/** Request event id to thread off (m.thread, spec v1.4). */
|
||||
threadRoot?: string;
|
||||
msgtype?: string;
|
||||
/** Extra content keys merged into the message content (e.g. org.uscllc.agent). */
|
||||
extraContent?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export class MatrixApiError extends Error {
|
||||
constructor(
|
||||
readonly status: number,
|
||||
readonly errcode: string | undefined,
|
||||
message: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'MatrixApiError';
|
||||
}
|
||||
}
|
||||
|
||||
type FetchLike = typeof fetch;
|
||||
|
||||
/**
|
||||
* Acts on the homeserver as appservice-namespaced virtual users
|
||||
* (Application Service API: as_token auth + user_id impersonation).
|
||||
*/
|
||||
export class AppserviceIntent {
|
||||
private readonly registered = new Set<string>();
|
||||
private readonly joined = new Set<string>();
|
||||
private readonly fetchImpl: FetchLike;
|
||||
|
||||
constructor(
|
||||
private readonly cfg: AppserviceConfig,
|
||||
fetchImpl?: FetchLike,
|
||||
) {
|
||||
this.fetchImpl = fetchImpl ?? fetch;
|
||||
}
|
||||
|
||||
get userPrefix(): string {
|
||||
return this.cfg.userPrefix ?? 'agent-';
|
||||
}
|
||||
|
||||
get senderUserId(): string {
|
||||
return `@${this.cfg.senderLocalpart ?? 'mosaic-as'}:${this.cfg.domain}`;
|
||||
}
|
||||
|
||||
agentLocalpart(agent: string): string {
|
||||
const slug = agent.toLowerCase();
|
||||
if (!/^[a-z0-9][a-z0-9_.-]*$/.test(slug)) {
|
||||
throw new Error(`invalid agent slug: ${agent}`);
|
||||
}
|
||||
return `${this.userPrefix}${slug}`;
|
||||
}
|
||||
|
||||
agentUserId(agent: string): string {
|
||||
return `@${this.agentLocalpart(agent)}:${this.cfg.domain}`;
|
||||
}
|
||||
|
||||
private async request(
|
||||
method: string,
|
||||
path: string,
|
||||
options: { userId?: string; body?: unknown } = {},
|
||||
): Promise<Record<string, unknown>> {
|
||||
const url = new URL(this.cfg.homeserverUrl.replace(/\/$/, '') + path);
|
||||
if (options.userId) {
|
||||
url.searchParams.set('user_id', options.userId);
|
||||
}
|
||||
const res = await this.fetchImpl(url, {
|
||||
method,
|
||||
headers: {
|
||||
Authorization: `Bearer ${this.cfg.asToken}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: options.body === undefined ? undefined : JSON.stringify(options.body),
|
||||
});
|
||||
const text = await res.text();
|
||||
const data = (text ? JSON.parse(text) : {}) as Record<string, unknown>;
|
||||
if (!res.ok) {
|
||||
throw new MatrixApiError(
|
||||
res.status,
|
||||
typeof data.errcode === 'string' ? data.errcode : undefined,
|
||||
`${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`,
|
||||
);
|
||||
}
|
||||
return data;
|
||||
}
|
||||
|
||||
/** Register the virtual user if it does not exist yet. Idempotent. */
|
||||
async ensureRegistered(agent: string): Promise<string> {
|
||||
const localpart = this.agentLocalpart(agent);
|
||||
const userId = this.agentUserId(agent);
|
||||
if (this.registered.has(userId)) return userId;
|
||||
try {
|
||||
await this.request('POST', '/_matrix/client/v3/register', {
|
||||
body: { type: 'm.login.application_service', username: localpart },
|
||||
});
|
||||
} catch (err) {
|
||||
if (!(err instanceof MatrixApiError && err.errcode === 'M_USER_IN_USE')) {
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
this.registered.add(userId);
|
||||
return userId;
|
||||
}
|
||||
|
||||
/** Join the agent to a room; on invite-only rooms the AS sender invites first. */
|
||||
async ensureJoined(roomId: string, agent: string): Promise<void> {
|
||||
const userId = await this.ensureRegistered(agent);
|
||||
const key = `${userId} ${roomId}`;
|
||||
if (this.joined.has(key)) return;
|
||||
const room = encodeURIComponent(roomId);
|
||||
try {
|
||||
await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
|
||||
} catch (err) {
|
||||
if (!(err instanceof MatrixApiError && err.errcode === 'M_FORBIDDEN')) throw err;
|
||||
await this.request('POST', `/_matrix/client/v3/rooms/${room}/invite`, {
|
||||
userId: this.senderUserId,
|
||||
body: { user_id: userId },
|
||||
});
|
||||
await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
|
||||
}
|
||||
this.joined.add(key);
|
||||
}
|
||||
|
||||
/** Send a message AS the agent's virtual user. */
|
||||
async sendAsAgent(options: SendMessageOptions): Promise<string | undefined> {
|
||||
const userId = this.agentUserId(options.agent);
|
||||
await this.ensureJoined(options.roomId, options.agent);
|
||||
const content: Record<string, unknown> = {
|
||||
msgtype: options.msgtype ?? 'm.text',
|
||||
body: options.body,
|
||||
...options.extraContent,
|
||||
};
|
||||
if (options.threadRoot) {
|
||||
content['m.relates_to'] = {
|
||||
rel_type: 'm.thread',
|
||||
event_id: options.threadRoot,
|
||||
is_falling_back: true,
|
||||
'm.in_reply_to': { event_id: options.threadRoot },
|
||||
};
|
||||
}
|
||||
const txn = `mosaic-as-${crypto.randomUUID()}`;
|
||||
const room = encodeURIComponent(options.roomId);
|
||||
const res = await this.request(
|
||||
'PUT',
|
||||
`/_matrix/client/v3/rooms/${room}/send/m.room.message/${txn}`,
|
||||
{ userId, body: content },
|
||||
);
|
||||
return typeof res.event_id === 'string' ? res.event_id : undefined;
|
||||
}
|
||||
|
||||
/** Set the agent's typing indicator in a room. */
|
||||
async setTyping(
|
||||
roomId: string,
|
||||
agent: string,
|
||||
typing: boolean,
|
||||
timeoutMs = 30000,
|
||||
): Promise<void> {
|
||||
const userId = await this.ensureRegistered(agent);
|
||||
const room = encodeURIComponent(roomId);
|
||||
const user = encodeURIComponent(userId);
|
||||
await this.request('PUT', `/_matrix/client/v3/rooms/${room}/typing/${user}`, {
|
||||
userId,
|
||||
body: typing ? { typing: true, timeout: timeoutMs } : { typing: false },
|
||||
});
|
||||
}
|
||||
|
||||
/** Create a room as the AS sender: agents get PL 50 by namespace via the
|
||||
* sender (PL 100); humans invited at default PL. Optionally link into a
|
||||
* space (m.space.child + m.space.parent). Returns the room id. */
|
||||
async createRoom(options: {
|
||||
name: string;
|
||||
alias?: string;
|
||||
topic?: string;
|
||||
invite?: string[];
|
||||
spaceId?: string;
|
||||
}): Promise<{ roomId: string; spaceLinked: boolean; spaceError?: string }> {
|
||||
const body: Record<string, unknown> = {
|
||||
name: options.name,
|
||||
preset: 'private_chat',
|
||||
invite: options.invite ?? [],
|
||||
power_level_content_override: {
|
||||
users: { [this.senderUserId]: 100 },
|
||||
// state_default 50 stays; the AS sender can grant agents as needed.
|
||||
},
|
||||
};
|
||||
if (options.alias) body.room_alias_name = options.alias;
|
||||
if (options.topic) body.topic = options.topic;
|
||||
const res = await this.request('POST', '/_matrix/client/v3/createRoom', {
|
||||
userId: this.senderUserId,
|
||||
body,
|
||||
});
|
||||
const roomId = res.room_id;
|
||||
if (typeof roomId !== 'string') throw new Error('createRoom returned no room_id');
|
||||
if (!options.spaceId) {
|
||||
return { roomId, spaceLinked: false };
|
||||
}
|
||||
// Space-link failures must NOT throw: the room already exists, and an
|
||||
// exception would hide the room_id (orphaned room, no recovery path).
|
||||
const encodedSpaceId = encodeURIComponent(options.spaceId);
|
||||
const encodedRoomId = encodeURIComponent(roomId);
|
||||
try {
|
||||
await this.request(
|
||||
'PUT',
|
||||
`/_matrix/client/v3/rooms/${encodedSpaceId}/state/m.space.child/${encodedRoomId}`,
|
||||
{ userId: this.senderUserId, body: { via: [this.cfg.domain], suggested: true } },
|
||||
);
|
||||
await this.request(
|
||||
'PUT',
|
||||
`/_matrix/client/v3/rooms/${encodedRoomId}/state/m.space.parent/${encodedSpaceId}`,
|
||||
{ userId: this.senderUserId, body: { via: [this.cfg.domain], canonical: true } },
|
||||
);
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return { roomId, spaceLinked: false, spaceError: message };
|
||||
}
|
||||
return { roomId, spaceLinked: true };
|
||||
}
|
||||
|
||||
/** Set display name for an agent's virtual user. */
|
||||
async setDisplayName(agent: string, displayName: string): Promise<void> {
|
||||
const userId = await this.ensureRegistered(agent);
|
||||
const user = encodeURIComponent(userId);
|
||||
await this.request('PUT', `/_matrix/client/v3/profile/${user}/displayname`, {
|
||||
userId,
|
||||
body: { displayname: displayName },
|
||||
});
|
||||
}
|
||||
|
||||
/** Read an account_data object on the AS sender user. Returns null when the
|
||||
* key has never been written (M_NOT_FOUND), so callers can treat that as an
|
||||
* empty store; any other error propagates. */
|
||||
async getSenderAccountData(type: string): Promise<Record<string, unknown> | null> {
|
||||
const user = encodeURIComponent(this.senderUserId);
|
||||
const key = encodeURIComponent(type);
|
||||
try {
|
||||
return await this.request('GET', `/_matrix/client/v3/user/${user}/account_data/${key}`, {
|
||||
userId: this.senderUserId,
|
||||
});
|
||||
} catch (err) {
|
||||
if (err instanceof MatrixApiError && err.errcode === 'M_NOT_FOUND') return null;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
/** Write an account_data object on the AS sender user. */
|
||||
async setSenderAccountData(type: string, content: Record<string, unknown>): Promise<void> {
|
||||
const user = encodeURIComponent(this.senderUserId);
|
||||
const key = encodeURIComponent(type);
|
||||
await this.request('PUT', `/_matrix/client/v3/user/${user}/account_data/${key}`, {
|
||||
userId: this.senderUserId,
|
||||
body: content,
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
import type { AppserviceConfig } from './types.js';
|
||||
|
||||
export interface RegistrationOptions {
|
||||
/** Unique appservice id in Synapse. Default: "mosaic-as". */
|
||||
id?: string;
|
||||
/** URL where Synapse reaches the appservice, e.g. http://mosaic-as:8008 */
|
||||
url: string;
|
||||
/** Alias namespace regex prefix. Default: "#mosaic-". */
|
||||
aliasPrefix?: string;
|
||||
}
|
||||
|
||||
const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
|
||||
/**
|
||||
* Build the Synapse appservice registration document (mosaic-as.yaml).
|
||||
* Deployment (infrastructure repo) serializes this to YAML and mounts it via
|
||||
* app_service_config_files.
|
||||
*/
|
||||
export function buildRegistration(cfg: AppserviceConfig, options: RegistrationOptions) {
|
||||
const prefix = cfg.userPrefix ?? 'agent-';
|
||||
return {
|
||||
id: options.id ?? 'mosaic-as',
|
||||
url: options.url,
|
||||
as_token: cfg.asToken,
|
||||
hs_token: cfg.hsToken,
|
||||
sender_localpart: cfg.senderLocalpart ?? 'mosaic-as',
|
||||
rate_limited: false,
|
||||
namespaces: {
|
||||
users: [
|
||||
{
|
||||
regex: `@${escapeRegex(prefix)}.*:${escapeRegex(cfg.domain)}`,
|
||||
exclusive: true,
|
||||
},
|
||||
],
|
||||
aliases: [
|
||||
{
|
||||
regex: `${escapeRegex(options.aliasPrefix ?? '#mosaic-')}.*:${escapeRegex(cfg.domain)}`,
|
||||
exclusive: false,
|
||||
},
|
||||
],
|
||||
rooms: [],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const assertYamlSafe = (field: string, value: string): string => {
|
||||
// Tokens/urls/ids are single-line opaque strings; control characters would
|
||||
// let a crafted value terminate the scalar and inject YAML keys.
|
||||
if (/[\r\n\x00-\x08\x0b-\x1f]/.test(value)) {
|
||||
throw new Error(`registration field ${field} contains control characters`);
|
||||
}
|
||||
return value.replace(/'/g, "''");
|
||||
};
|
||||
|
||||
/** Minimal YAML serialization for the flat registration document. */
|
||||
export function registrationToYaml(registration: ReturnType<typeof buildRegistration>): string {
|
||||
const ns = registration.namespaces;
|
||||
const nsBlock = (entries: Array<{ regex: string; exclusive: boolean }>): string =>
|
||||
entries.length === 0
|
||||
? ' []'
|
||||
: '\n' +
|
||||
entries.map((e) => ` - regex: '${e.regex}'\n exclusive: ${e.exclusive}`).join('\n');
|
||||
return [
|
||||
`id: '${assertYamlSafe('id', registration.id)}'`,
|
||||
`url: '${assertYamlSafe('url', registration.url)}'`,
|
||||
`as_token: '${assertYamlSafe('as_token', registration.as_token)}'`,
|
||||
`hs_token: '${assertYamlSafe('hs_token', registration.hs_token)}'`,
|
||||
`sender_localpart: '${assertYamlSafe('sender_localpart', registration.sender_localpart)}'`,
|
||||
`rate_limited: ${registration.rate_limited}`,
|
||||
'namespaces:',
|
||||
` users:${nsBlock(ns.users)}`,
|
||||
` aliases:${nsBlock(ns.aliases)}`,
|
||||
` rooms:${nsBlock(ns.rooms)}`,
|
||||
'',
|
||||
].join('\n');
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
import { timingSafeEqual } from 'node:crypto';
|
||||
|
||||
import type { EventHandler, HandlerResult, Transaction } from './types.js';
|
||||
|
||||
const MAX_SEEN_TXN_IDS = 1000;
|
||||
|
||||
function safeTokenCompare(presented: string | undefined, expected: string): boolean {
|
||||
if (presented === undefined) return false;
|
||||
const a = Buffer.from(presented);
|
||||
const b = Buffer.from(expected);
|
||||
if (a.length !== b.length) {
|
||||
// Compare against a same-length dummy so length is not a timing oracle.
|
||||
timingSafeEqual(a, Buffer.alloc(a.length));
|
||||
return false;
|
||||
}
|
||||
return timingSafeEqual(a, b);
|
||||
}
|
||||
|
||||
export interface TransactionHandlerOptions {
|
||||
hsToken: string;
|
||||
onEvent: EventHandler;
|
||||
/** Called for handler errors; events are at-most-once, errors must not 500. */
|
||||
onError?: (error: unknown, txnId: string) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Framework-agnostic handler for the Application Service transactions API
|
||||
* (PUT /_matrix/app/v1/transactions/{txnId}). Host apps (Fastify/Nest) wrap
|
||||
* this in a route.
|
||||
*
|
||||
* Spec requirements covered: hs_token verification (Authorization: Bearer,
|
||||
* with legacy ?access_token fallback), txnId idempotency, always-200 on
|
||||
* accepted transactions (homeserver retries on any other status).
|
||||
*
|
||||
* KNOWN LIMITATION: the txnId dedupe ring is in-process memory only. After a
|
||||
* restart the homeserver may redeliver pending transactions — event handlers
|
||||
* must be idempotent (delivery is at-least-once across process lifetimes).
|
||||
*/
|
||||
export class TransactionHandler {
|
||||
private readonly seen: string[] = [];
|
||||
private readonly seenSet = new Set<string>();
|
||||
|
||||
constructor(private readonly options: TransactionHandlerOptions) {}
|
||||
|
||||
authorized(
|
||||
authorizationHeader: string | undefined,
|
||||
accessTokenParam: string | undefined,
|
||||
): boolean {
|
||||
const bearer = authorizationHeader?.startsWith('Bearer ')
|
||||
? authorizationHeader.slice('Bearer '.length)
|
||||
: undefined;
|
||||
const presented = bearer ?? accessTokenParam;
|
||||
return safeTokenCompare(presented, this.options.hsToken);
|
||||
}
|
||||
|
||||
async handle(
|
||||
txnId: string,
|
||||
body: unknown,
|
||||
auth: { authorizationHeader?: string; accessTokenParam?: string },
|
||||
): Promise<HandlerResult> {
|
||||
if (!this.authorized(auth.authorizationHeader, auth.accessTokenParam)) {
|
||||
return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad hs_token' } };
|
||||
}
|
||||
if (this.seenSet.has(txnId)) {
|
||||
return { status: 200, body: {} };
|
||||
}
|
||||
this.markSeen(txnId);
|
||||
const txn = (body ?? {}) as Partial<Transaction>;
|
||||
for (const event of txn.events ?? []) {
|
||||
try {
|
||||
await this.options.onEvent(event);
|
||||
} catch (error) {
|
||||
// A failing handler must not fail the transaction: the homeserver
|
||||
// would retry the whole batch forever.
|
||||
this.options.onError?.(error, txnId);
|
||||
}
|
||||
}
|
||||
return { status: 200, body: {} };
|
||||
}
|
||||
|
||||
private markSeen(txnId: string): void {
|
||||
this.seen.push(txnId);
|
||||
this.seenSet.add(txnId);
|
||||
while (this.seen.length > MAX_SEEN_TXN_IDS) {
|
||||
const evicted = this.seen.shift();
|
||||
if (evicted !== undefined) this.seenSet.delete(evicted);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
export interface AppserviceConfig {
|
||||
/** Homeserver client-server API base, e.g. https://chat.uscllc.com */
|
||||
homeserverUrl: string;
|
||||
/** Server name used in user IDs, e.g. chat.uscllc.com */
|
||||
domain: string;
|
||||
/** Token the appservice presents to the homeserver (as_token). */
|
||||
asToken: string;
|
||||
/** Token the homeserver presents to the appservice (hs_token). */
|
||||
hsToken: string;
|
||||
/** Localpart prefix owned by this appservice. Default: "agent-". */
|
||||
userPrefix?: string;
|
||||
/** The appservice's own sender user localpart. Default: "mosaic-as". */
|
||||
senderLocalpart?: string;
|
||||
}
|
||||
|
||||
export interface MatrixEvent {
|
||||
type: string;
|
||||
event_id?: string;
|
||||
room_id?: string;
|
||||
sender?: string;
|
||||
state_key?: string;
|
||||
content?: Record<string, unknown>;
|
||||
origin_server_ts?: number;
|
||||
}
|
||||
|
||||
export interface Transaction {
|
||||
events: MatrixEvent[];
|
||||
}
|
||||
|
||||
export type EventHandler = (event: MatrixEvent) => void | Promise<void>;
|
||||
|
||||
export interface HandlerResult {
|
||||
status: number;
|
||||
body: Record<string, unknown>;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "dist",
|
||||
"rootDir": "src"
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user