Repository Public
1// Clés d'API : catalogue des portées (docs/API.md §3), profils prêts à l'emploi, formulaire de l'assistant → charge utile2// de l'API (validation comprise), différence pour une modification, filtres du journal d'utilisation.3// Logique pure (testée sans navigateur) : aucune dépendance à l'interface ni au réseau.45export const SCOPES = [6 "mail.send", "mail.read", "mail.search", "mail.modify", "mail.delete", "mail.drafts", "mail.attachments.read", "mail.attachments.write",7 "mail.addresses.read", "mail.addresses.manage", "mail.aliases.manage", "mail.webhooks.manage", "mail.admin",8] as const9export type Scope = (typeof SCOPES)[number]10export const isScope = (s: string): s is Scope => (SCOPES as readonly string[]).includes(s)11export const ADMIN_SCOPE: Scope = "mail.admin"1213/** Clés i18n (fr.adm.keys) du nom courant et de l'explication en langage clair d'une portée. */14export const scopeLabelKey = <S extends Scope>(s: S) => `adm.keys.scope.${s}` as const15export const scopeDescKey = <S extends Scope>(s: S) => `adm.keys.scopeDesc.${s}` as const1617/** Regroupement d'affichage : du moins au plus puissant. */18export const SCOPE_GROUPS = [19 { id: "send", scopes: ["mail.send", "mail.drafts", "mail.attachments.write"] },20 { id: "read", scopes: ["mail.read", "mail.search", "mail.attachments.read"] },21 { id: "modify", scopes: ["mail.modify", "mail.delete"] },22 { id: "manage", scopes: ["mail.addresses.read", "mail.addresses.manage", "mail.aliases.manage", "mail.webhooks.manage"] },23 { id: "admin", scopes: ["mail.admin"] },24] as const satisfies readonly { id: string; scopes: readonly Scope[] }[]25export type ScopeGroupId = (typeof SCOPE_GROUPS)[number]["id"]26export const scopeGroupKey = <G extends ScopeGroupId>(g: G) => `adm.keys.group.${g}` as const2728/** Portées qui détruisent ou administrent : signalées dans l'assistant et le récapitulatif. */29export const POWERFUL: readonly Scope[] = ["mail.delete", "mail.addresses.manage", "mail.aliases.manage", "mail.admin"]3031export type ExternalPolicy = "allow" | "approval" | "deny"32export const POLICIES: readonly ExternalPolicy[] = ["approval", "deny", "allow"]3334// ---------------------------------------------------------------- profils35export const PRESET_IDS = ["send_only", "read_only", "agent_drafts", "agent_send_approval", "admin"] as const36export type PresetId = (typeof PRESET_IDS)[number]37export interface Preset {38 id: PresetId39 scopes: readonly Scope[]40 /** politique d'envoi externe proposée avec ce profil (modifiable à l'étape suivante) */41 policy: ExternalPolicy42}43const READ: readonly Scope[] = ["mail.read", "mail.search", "mail.attachments.read", "mail.addresses.read"]44export const PRESETS: readonly Preset[] = [45 { id: "send_only", scopes: ["mail.send"], policy: "approval" },46 { id: "read_only", scopes: READ, policy: "deny" },47 { id: "agent_drafts", scopes: [...READ, "mail.drafts"], policy: "deny" },48 { id: "agent_send_approval", scopes: [...READ, "mail.drafts", "mail.send", "mail.attachments.write"], policy: "approval" },49 { id: "admin", scopes: ["mail.admin"], policy: "approval" },50]51export const presetById = (id: PresetId): Preset => PRESETS.find((p) => p.id === id) as Preset52export const presetLabelKey = <P extends PresetId>(p: P) => `adm.keys.preset.${p}` as const53export const presetDescKey = <P extends PresetId>(p: P) => `adm.keys.presetDesc.${p}` as const5455/** Portées connues, sans doublon, dans l'ordre du catalogue. */56export function normalizeScopes(list: readonly string[]): Scope[] {57 const set = new Set(list)58 return SCOPES.filter((s) => set.has(s))59}6061/** Profil correspondant exactement à cette liste de portées (ordre et doublons indifférents) ; sinon « custom ». */62export function detectPreset(scopes: readonly string[]): PresetId | "custom" {63 const mine = normalizeScopes(scopes)64 if (mine.length !== new Set(scopes).size) return "custom" // une portée inconnue ne correspond à aucun profil65 for (const p of PRESETS) if (p.scopes.length === mine.length && p.scopes.every((s) => mine.includes(s))) return p.id66 return "custom"67}6869/** La clé peut-elle envoyer (la politique d'envoi externe la concerne-t-elle) ? */70export const canSend = (scopes: readonly string[]): boolean => scopes.includes("mail.send") || scopes.includes(ADMIN_SCOPE)71export const hasAdmin = (scopes: readonly string[]): boolean => scopes.includes(ADMIN_SCOPE)7273// ---------------------------------------------------------------- formulaire74export const LIMITS = { name: 80, description: 500, rateMin: 1, rateMax: 6000, dailyMin: 0, dailyMax: 100000, domains: 100, addresses: 500, graceMax: 7 * 86400 } as const75export const DEFAULTS = { rate: 60, daily: 200, policy: "approval" as ExternalPolicy }7677/** `keep` : conserver l'échéance actuelle (modification d'une clé qui en a une). */78export type ExpiryMode = "never" | "30" | "90" | "365" | "date" | "keep"79export interface KeyForm {80 name: string81 description: string82 scopes: Scope[]83 addressIds: string[]84 /** choix explicite « toutes les adresses » — réservé aux clés qui portent mail.admin */85 allAddresses: boolean86 policy: ExternalPolicy87 /** domaines de destinataires permis, saisis librement (virgules, espaces ou retours à la ligne) */88 domains: string89 rate: string90 daily: string91 expiry: ExpiryMode92 /** AAAA-MM-JJ (mode « date ») */93 expiryDate: string94 /** échéance actuelle de la clé modifiée (mode « keep ») */95 currentExpiry: string | null96}97export const emptyForm = (): KeyForm => ({98 name: "", description: "", scopes: [], addressIds: [], allAddresses: false, policy: DEFAULTS.policy, domains: "",99 rate: String(DEFAULTS.rate), daily: String(DEFAULTS.daily), expiry: "never", expiryDate: "", currentExpiry: null,100})101102/** Forme d'une clé rendue par l'API (champs utiles au formulaire). */103export interface KeyLike {104 name: string105 description: string106 scopes: readonly string[]107 address_ids: readonly string[]108 all_addresses: boolean109 rate_per_minute: number110 daily_send_limit: number111 external_send_policy: ExternalPolicy112 allowed_recipient_domains: readonly string[]113 expires_at: string | null114}115export const formFromKey = (k: KeyLike): KeyForm => ({116 name: k.name, description: k.description, scopes: normalizeScopes(k.scopes), addressIds: [...k.address_ids], allAddresses: k.all_addresses && hasAdmin(k.scopes),117 policy: k.external_send_policy, domains: k.allowed_recipient_domains.join(", "), rate: String(k.rate_per_minute), daily: String(k.daily_send_limit),118 expiry: k.expires_at ? "keep" : "never", expiryDate: "", currentExpiry: k.expires_at,119})120121/** Applique un profil : portées et politique proposée ; « toutes les adresses » tombe si le profil n'est pas administrateur. */122export function applyPreset(form: KeyForm, id: PresetId): KeyForm {123 const p = presetById(id)124 return { ...form, scopes: [...p.scopes], policy: p.policy, allAddresses: form.allAddresses && hasAdmin(p.scopes) }125}126/** Coche ou décoche une portée ; retirer mail.admin retire aussi « toutes les adresses » (jamais de « toutes » implicite). */127export function toggleScope(form: KeyForm, scope: Scope, on: boolean): KeyForm {128 const scopes = normalizeScopes(on ? [...form.scopes, scope] : form.scopes.filter((s) => s !== scope))129 return { ...form, scopes, allAddresses: form.allAddresses && hasAdmin(scopes) }130}131132const DOMAIN_RE = /^[a-z0-9.-]{3,253}$/133/** Domaines saisis → liste normalisée (minuscules, « @ » initial toléré, sans doublon) + entrées refusées. */134export function parseDomains(text: string): { domains: string[]; invalid: string[] } {135 const domains: string[] = []136 const invalid: string[] = []137 for (const raw of text.split(/[\s,;]+/)) {138 const d = raw.trim().toLowerCase().replace(/^@/, "")139 if (!d) continue140 if (!DOMAIN_RE.test(d) || !d.includes(".") || d.startsWith(".") || d.endsWith(".")) invalid.push(raw.trim())141 else if (!domains.includes(d)) domains.push(d)142 }143 return { domains, invalid }144}145146/** Entier strict dans [min, max] ; sinon null (ni décimales, ni signe, ni texte). */147export function parseIntIn(text: string, min: number, max: number): number | null {148 const s = text.trim()149 if (!/^\d{1,9}$/.test(s)) return null150 const n = Number(s)151 return n >= min && n <= max ? n : null152}153154export type ExpiryResult = { ok: true; iso: string | null } | { ok: false; error: "expiry_invalid" | "expiry_past" }155/** Échéance choisie → ISO (ou null : sans échéance). Une date s'entend jusqu'à la fin de cette journée, heure locale. */156export function expiryToIso(form: Pick<KeyForm, "expiry" | "expiryDate" | "currentExpiry">, now: Date = new Date()): ExpiryResult {157 switch (form.expiry) {158 case "never":159 return { ok: true, iso: null }160 case "keep":161 return form.currentExpiry ? { ok: true, iso: form.currentExpiry } : { ok: true, iso: null }162 case "30":163 case "90":164 case "365":165 return { ok: true, iso: new Date(now.getTime() + Number(form.expiry) * 86_400_000).toISOString() }166 case "date": {167 const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(form.expiryDate.trim())168 if (!m) return { ok: false, error: "expiry_invalid" }169 const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), 23, 59, 59)170 if (Number.isNaN(d.getTime()) || d.getMonth() !== Number(m[2]) - 1 || d.getDate() !== Number(m[3])) return { ok: false, error: "expiry_invalid" }171 if (d.getTime() <= now.getTime()) return { ok: false, error: "expiry_past" }172 return { ok: true, iso: d.toISOString() }173 }174 }175}176177// ---------------------------------------------------------------- validation par étape178export const STEPS = ["identity", "scopes", "addresses", "policy", "limits", "review"] as const179export type Step = (typeof STEPS)[number]180export type FormError =181 | "name_required" | "name_too_long" | "description_too_long" | "scopes_required" | "addresses_required" | "too_many_addresses" | "all_requires_admin"182 | "domains_invalid" | "too_many_domains" | "rate_invalid" | "daily_invalid" | "expiry_invalid" | "expiry_past"183export const formErrorKey = <E extends FormError>(e: E) => `adm.keys.err.${e}` as const184185export interface ValidateOptions {186 now?: Date187 /** modification d'une clé existante : une liste d'adresses vide reste permise (la clé ne voit alors rien) */188 allowEmptyAddresses?: boolean189}190export function validateStep(step: Step, f: KeyForm, o: ValidateOptions = {}): FormError[] {191 const errors: FormError[] = []192 switch (step) {193 case "identity":194 if (!f.name.trim()) errors.push("name_required")195 else if (f.name.trim().length > LIMITS.name) errors.push("name_too_long")196 if (f.description.length > LIMITS.description) errors.push("description_too_long")197 break198 case "scopes":199 if (normalizeScopes(f.scopes).length === 0) errors.push("scopes_required")200 break201 case "addresses":202 if (f.allAddresses && !hasAdmin(f.scopes)) errors.push("all_requires_admin")203 else if (!f.allAddresses && f.addressIds.length === 0 && !o.allowEmptyAddresses) errors.push("addresses_required")204 if (f.addressIds.length > LIMITS.addresses) errors.push("too_many_addresses")205 break206 case "policy": {207 const d = parseDomains(f.domains)208 if (d.invalid.length) errors.push("domains_invalid")209 if (d.domains.length > LIMITS.domains) errors.push("too_many_domains")210 break211 }212 case "limits": {213 if (parseIntIn(f.rate, LIMITS.rateMin, LIMITS.rateMax) === null) errors.push("rate_invalid")214 if (parseIntIn(f.daily, LIMITS.dailyMin, LIMITS.dailyMax) === null) errors.push("daily_invalid")215 const e = expiryToIso(f, o.now)216 if (!e.ok) errors.push(e.error)217 break218 }219 case "review":220 break221 }222 return errors223}224export const validateForm = (f: KeyForm, o: ValidateOptions = {}): FormError[] => STEPS.flatMap((s) => validateStep(s, f, o))225/** Première étape qui porte une erreur (pour y ramener la personne), ou null. */226export const firstInvalidStep = (f: KeyForm, o: ValidateOptions = {}): Step | null => STEPS.find((s) => validateStep(s, f, o).length > 0) ?? null227228// ---------------------------------------------------------------- charge utile229/** Corps de `POST /api/admin/api-keys` (docs/API.md §13) — toujours complet et explicite, aucun défaut implicite du serveur. */230export interface KeyPayload {231 name: string232 description: string233 scopes: Scope[]234 address_ids: string[]235 all_addresses: boolean236 rate_per_minute: number237 daily_send_limit: number238 external_send_policy: ExternalPolicy239 allowed_recipient_domains: string[]240 expires_at: string | null241}242export class FormInvalid extends Error {243 constructor(readonly errors: FormError[]) {244 super(`invalid key form: ${errors.join(", ")}`)245 this.name = "FormInvalid"246 }247}248/** Formulaire validé → charge utile. Lève `FormInvalid` s'il reste une erreur : rien n'est envoyé à moitié. */249export function toPayload(f: KeyForm, o: ValidateOptions = {}): KeyPayload {250 const errors = validateForm(f, o)251 if (errors.length) throw new FormInvalid(errors)252 const scopes = normalizeScopes(f.scopes)253 const all = f.allAddresses && hasAdmin(scopes)254 const expiry = expiryToIso(f, o.now) as { ok: true; iso: string | null }255 return {256 name: f.name.trim(), description: f.description.trim(), scopes,257 // « toutes les adresses » est un choix explicite : la liste nominative est alors vidée, pas conservée en double258 address_ids: all ? [] : [...new Set(f.addressIds)], all_addresses: all,259 rate_per_minute: parseIntIn(f.rate, LIMITS.rateMin, LIMITS.rateMax) as number, daily_send_limit: parseIntIn(f.daily, LIMITS.dailyMin, LIMITS.dailyMax) as number,260 external_send_policy: f.policy, allowed_recipient_domains: parseDomains(f.domains).domains, expires_at: expiry.iso,261 }262}263264const sameSet = (a: readonly string[], b: readonly string[]) => a.length === b.length && new Set(a).size === new Set([...a, ...b]).size265const sameInstant = (a: string | null, b: string | null) => a === b || (a !== null && b !== null && Date.parse(a) === Date.parse(b))266/** Champs réellement changés par rapport à la clé actuelle : c'est le corps de `PATCH …/{id}` (vide = rien à enregistrer). */267export function diffPayload(current: KeyLike, next: KeyPayload): Partial<KeyPayload> {268 const out: Partial<KeyPayload> = {}269 if (next.name !== current.name) out.name = next.name270 if (next.description !== current.description) out.description = next.description271 if (!sameSet(next.scopes, current.scopes)) out.scopes = next.scopes272 if (!sameSet(next.address_ids, current.address_ids)) out.address_ids = next.address_ids273 if (next.all_addresses !== current.all_addresses) out.all_addresses = next.all_addresses274 if (next.rate_per_minute !== current.rate_per_minute) out.rate_per_minute = next.rate_per_minute275 if (next.daily_send_limit !== current.daily_send_limit) out.daily_send_limit = next.daily_send_limit276 if (next.external_send_policy !== current.external_send_policy) out.external_send_policy = next.external_send_policy277 if (!sameSet(next.allowed_recipient_domains, current.allowed_recipient_domains)) out.allowed_recipient_domains = next.allowed_recipient_domains278 if (!sameInstant(next.expires_at, current.expires_at)) out.expires_at = next.expires_at279 return out280}281282/** Délais de grâce proposés à la rotation, en secondes (0 = l'ancienne clé cesse tout de suite ; 7 jours au plus côté serveur). */283export const GRACE_CHOICES = [0, 3600, 86400, 604800] as const284export type Grace = (typeof GRACE_CHOICES)[number]285export const isGrace = (n: number): n is Grace => (GRACE_CHOICES as readonly number[]).includes(n)286287// ---------------------------------------------------------------- journal d'utilisation288export interface UsageCall {289 at: string290 method: string291 route: string292 status: number293 duration_ms: number | null294 ip: string | null295 error_code: string | null296 explorer: boolean297}298export type StatusClass = "all" | "2xx" | "3xx" | "4xx" | "5xx"299export const STATUS_CLASSES: readonly StatusClass[] = ["all", "2xx", "4xx", "5xx"]300export const statusClass = (status: number): Exclude<StatusClass, "all"> => (status >= 500 ? "5xx" : status >= 400 ? "4xx" : status >= 300 ? "3xx" : "2xx")301export interface CallFilter {302 /** jours : seuls les appels plus récents sont gardés */303 days: number304 status: StatusClass305 /** « all » ou une méthode HTTP */306 method: string307 explorer: "all" | "only" | "without"308}309export const defaultCallFilter = (days = 7): CallFilter => ({ days, status: "all", method: "all", explorer: "all" })310export function filterCalls<T extends UsageCall>(calls: readonly T[], f: CallFilter, now: Date = new Date()): T[] {311 const since = now.getTime() - f.days * 86_400_000312 return calls.filter((c) => {313 const at = Date.parse(c.at)314 if (!Number.isNaN(at) && at < since) return false315 if (f.status !== "all" && statusClass(c.status) !== f.status) return false316 if (f.method !== "all" && c.method.toUpperCase() !== f.method.toUpperCase()) return false317 if (f.explorer === "only" && !c.explorer) return false318 if (f.explorer === "without" && c.explorer) return false319 return true320 })321}322/** Méthodes présentes dans le journal (pour le filtre), triées. */323export const methodsOf = (calls: readonly UsageCall[]): string[] => [...new Set(calls.map((c) => c.method.toUpperCase()))].sort()324325// ---------------------------------------------------------------- approbations326/** Un destinataire est-il « externe » d'après la liste rendue par l'API (comparaison insensible à la casse) ? */327export const isExternal = (recipient: string, external: readonly string[]): boolean => external.some((x) => x.toLowerCase() === recipient.toLowerCase())328