using System.Collections.Frozen; namespace Febe.Browser.Cdp; /// /// The CDP commands Febe may send (spec §6.1). Everything else is refused before it reaches the browser. /// Adding a command requires a line in docs/decisioni.md with the reason. /// public static class CdpCommandPolicy { /// The allowlist of spec §6.1, grouped by purpose. public static FrozenSet Allowed { get; } = FrozenSet.Create( StringComparer.Ordinal, // Navigate and read the state (Runtime.evaluate read-only only, see ReadOnlyScriptGuard). "Page.enable", "Page.navigate", "Page.getFrameTree", "Runtime.evaluate", // Capture responses. "Network.enable", "Network.getResponseBody", // Gestures. "Input.dispatchMouseEvent", "Input.dispatchKeyEvent", // Download files. "Network.loadNetworkResource", "IO.read", "IO.close", // Remote view and preview. "Page.startScreencast", "Page.screencastFrameAck", "Page.stopScreencast", "Page.captureScreenshot", // Check the session: existence of the session cookie only. "Network.getCookies"); /// Commands explicitly forbidden by spec §2 rule 2 and §6.1, refused with a specific message. public static FrozenSet ForbiddenCommands { get; } = FrozenSet.Create( StringComparer.Ordinal, "Network.setUserAgentOverride", "Network.setExtraHTTPHeaders", "Page.addScriptToEvaluateOnNewDocument"); /// Whole domains that are forbidden (spec §6.1). public static IReadOnlyList ForbiddenDomains { get; } = ["Emulation", "Fetch"]; public static bool IsAllowed(string method) => method is not null && Allowed.Contains(method); public static bool IsExplicitlyForbidden(string method) { if (string.IsNullOrEmpty(method)) { return false; } if (ForbiddenCommands.Contains(method)) { return true; } var dot = method.IndexOf('.', StringComparison.Ordinal); var domain = dot < 0 ? method : method[..dot]; return ForbiddenDomains.Contains(domain, StringComparer.Ordinal); } /// Throws unless is on the allowlist. public static void EnsureAllowed(string method) { if (IsExplicitlyForbidden(method)) { throw new CdpCommandNotAllowedException( method, $"Il comando CDP «{method}» è vietato: altera ciò che il browser dichiara o le richieste che invia (specifica §2, regola 2; §6.1)."); } if (!IsAllowed(method)) { throw new CdpCommandNotAllowedException( method, $"Il comando CDP «{method}» non è nell'elenco dei comandi ammessi (specifica §6.1). Ogni aggiunta va motivata in docs/decisioni.md."); } } } /// A CDP command was refused by and never sent. public sealed class CdpCommandNotAllowedException(string method, string message) : InvalidOperationException(message) { public string Method { get; } = method; } /// The browser answered a command with an error. The message never contains parameters. public sealed class CdpCommandException(string method, int code, string browserMessage) : Exception($"Il comando CDP «{method}» è fallito: {browserMessage} (codice {code}).") { public string Method { get; } = method; public int Code { get; } = code; public string BrowserMessage { get; } = browserMessage; } /// The connection to the browser is closed (browser exited, crashed or is restarting). public sealed class CdpDisconnectedException : Exception { public CdpDisconnectedException() : base("Il collegamento con il browser è chiuso.") { } public CdpDisconnectedException(string message) : base(message) { } public CdpDisconnectedException(string message, Exception? inner) : base(message, inner) { } }