SPB Git

Repository Public

scopes.ts 17.3 KB 328 lines typescript

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
Files main
Menu

Theme