parsimony/admin/src/lib/api.ts
tgiachi eb9e915805 fix(security): hold posts whose From header does not match the sender
- Judge membership on the envelope sender and require the From header to name the same address
- Hold mismatches (and missing, unparsable or multiple From addresses) for the admin instead of delivering
- Record why a message was held: new held.reason column, migrated, shown in the API, CLI and UI
- Accept an empty message in the held queue
- Document who may post
2026-11-09 20:23:07 +01:00

177 lines
5 KiB
TypeScript

// Typed client for the Parsimony admin REST API (/api/v1).
export type PostPolicy = 'members' | 'moderated'
export type JoinPolicy = 'open' | 'closed'
export type ArchivePolicy = 'public' | 'private' | 'off'
export interface List {
id: number
name: string
domain: string
title: string
address: string
post_policy: PostPolicy
join_policy: JoinPolicy
archive_policy: ArchivePolicy
}
export interface Member {
address: string
display_name: string
disabled: boolean
bounce_count: number
}
export interface Held {
id: number
sender: string
subject: string
size: number
created_at: string
/** Why the message was held, for the admin. */
reason: string
}
export interface Message {
id: number
thread_id: number
message_id: string
in_reply_to?: string
subject: string
sender: string
date: string
size: number
body?: string
}
export interface ImportSummary {
imported: number
duplicates: number
failed: number
errors: string[]
}
export interface ArchivePage {
total: number
messages: Message[]
}
export interface QueueItem {
id: number
recipient: string
attempts: number
last_error: string
next_attempt: string
created_at: string
}
export interface Queue {
pending: number
retrying: number
oldest: string | null
items: QueueItem[]
}
export class ApiError extends Error {
readonly status: number
constructor(status: number, message: string) {
super(message)
this.name = 'ApiError'
this.status = status
}
}
const TOKEN_KEY = 'parsimony.token'
let unauthorizedHandler: (() => void) | null = null
/** The bearer token lives in sessionStorage: it dies with the tab. */
export const session = {
get: (): string | null => sessionStorage.getItem(TOKEN_KEY),
set: (token: string) => sessionStorage.setItem(TOKEN_KEY, token),
clear: () => sessionStorage.removeItem(TOKEN_KEY),
/** Called after any 401, once the token has been cleared. */
onUnauthorized: (fn: (() => void) | null) => {
unauthorizedHandler = fn
},
}
async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
const headers: Record<string, string> = {}
const token = session.get()
if (token) headers.Authorization = `Bearer ${token}`
// A file is streamed as is; everything else is JSON.
const raw = body instanceof Blob
if (body !== undefined) headers['Content-Type'] = raw ? 'application/mbox' : 'application/json'
let res: Response
try {
res = await fetch(`/api/v1${path}`, {
method,
headers,
body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
})
} catch {
throw new ApiError(0, 'Cannot reach the server')
}
if (res.status === 401) {
session.clear()
unauthorizedHandler?.()
}
if (!res.ok) {
let message = `Request failed (${res.status})`
try {
const data = await res.json()
if (typeof data?.error === 'string') message = data.error
} catch {
// not JSON: keep the generic message
}
throw new ApiError(res.status, message)
}
if (res.status === 204) return undefined as T
return (await res.json()) as T
}
const enc = encodeURIComponent
export const api = {
lists: {
list: () => request<List[]>('GET', '/lists'),
get: (id: number) => request<List>('GET', `/lists/${id}`),
create: (b: { name: string; domain: string; title?: string }) => request<List>('POST', '/lists', b),
update: (
id: number,
b: Partial<Pick<List, 'title' | 'post_policy' | 'join_policy' | 'archive_policy'>>,
) => request<List>('PATCH', `/lists/${id}`, b),
remove: (id: number) => request<void>('DELETE', `/lists/${id}`),
},
members: {
list: (listId: number) => request<Member[]>('GET', `/lists/${listId}/members`),
add: (listId: number, b: { address: string; display_name?: string }) =>
request<Member>('POST', `/lists/${listId}/members`, b),
remove: (listId: number, address: string) =>
request<void>('DELETE', `/lists/${listId}/members/${enc(address)}`),
},
held: {
list: (listId: number) => request<Held[]>('GET', `/lists/${listId}/held`),
approve: (id: number) => request<void>('POST', `/held/${id}/approve`),
discard: (id: number) => request<void>('DELETE', `/held/${id}`),
},
queue: {
get: () => request<Queue>('GET', '/queue'),
discard: (id: number) => request<void>('DELETE', `/queue/${id}`),
},
archive: {
list: (listId: number, p: { q?: string; limit?: number; offset?: number } = {}) => {
const qs = new URLSearchParams()
if (p.q) qs.set('q', p.q)
if (p.limit !== undefined) qs.set('limit', String(p.limit))
if (p.offset !== undefined) qs.set('offset', String(p.offset))
const s = qs.toString()
return request<ArchivePage>('GET', `/lists/${listId}/archive${s ? `?${s}` : ''}`)
},
import: (listId: number, file: Blob) => request<ImportSummary>('POST', `/lists/${listId}/archive/import`, file),
get: (id: number) => request<Message>('GET', `/archive/${id}`),
remove: (id: number) => request<void>('DELETE', `/archive/${id}`),
},
}