Macaw.Layers.Url.Policy (macaw_layers v0.5.0)

Copy Markdown View Source

A host's URL policy (spec/01 §8.3): which URLs a document read on this host may use. The host knows where its documents come from and what its pages may load, so the policy is its intent, built once and passed as a value to the reads it makes (Macaw.Layers.Form.read/3's urls:). It is never application config, and never part of a document's value: a document is well formed everywhere (Macaw.Layers.Url), and allowed or not by the host that reads it.

Closed by default. new([]) allows nothing; each scheme, host and data type is allowed only by being named.

iex> {:ok, policy} = Macaw.Layers.Url.Policy.new(schemes: ["https"], hosts: ["tiles.example"])
iex> {:ok, url} = Macaw.Layers.Url.new("https://tiles.example/{z}/{x}/{y}.png")
iex> Macaw.Layers.Url.Policy.allows(policy, url)
:ok
iex> {:ok, url} = Macaw.Layers.Url.new("javascript:alert(1)")
iex> Macaw.Layers.Url.Policy.allows(policy, url)
{:error, :scheme}

Bounded. Only https, http and data can be allowed, and data only as an image of image/png, image/jpeg or image/webp: image/svg+xml can carry script. Naming any other is a fault, so the loosest policy a host can write is "https and http to any host, and those images".

Ported from visualize's Visualize.Chart.Urls (its spec/14 §10.3), whose default (https to any host) a host now writes out if it wants it.

Summary

Types

Why a policy refuses a URL: :scheme, a scheme it does not allow; :http, http: where it allows only https:; :data_type, a data: URL of a type it does not allow; :host, a host (or, for a {s} host, any of its subdomains' hosts) it does not list.

t()

The schemes, the hosts (:any, or hosts and *.domain) and the data types allowed.

Functions

Whether the policy allows the URL: :ok, or {:error, reason}. A URL is read as Macaw.Layers.Url reads it, from its text, so a struct built around Url.new/2 is judged as its text is.

Every URL the value holds that the policy refuses, {path, {:url, reason}} by path from the value, ordered: its maps, lists, tuples and structs are walked, so a URL is found wherever any type holds one. A fault names the reason and never the URL.

The policy made stricter by opts, written as new/1 takes them: each key given keeps only what both allow, and a key not given keeps the policy's. A read can be stricter than its host, never looser: a host the policy does not cover, or a scheme it does not allow, is dropped, never added. {:ok, policy}, or opts' faults as new/1 gives them.

narrow/2, or an ArgumentError naming every fault.

The policy that allows exactly what it names

new/1, or an ArgumentError naming every fault: a host's policy written in code.

Types

reason()

@type reason() :: :scheme | :http | :data_type | :host

Why a policy refuses a URL: :scheme, a scheme it does not allow; :http, http: where it allows only https:; :data_type, a data: URL of a type it does not allow; :host, a host (or, for a {s} host, any of its subdomains' hosts) it does not list.

t()

@type t() :: %Macaw.Layers.Url.Policy{
  data: [String.t()],
  hosts: :any | [String.t()],
  schemes: [String.t()]
}

The schemes, the hosts (:any, or hosts and *.domain) and the data types allowed.

Functions

allows(policy, url)

@spec allows(t(), Macaw.Layers.Url.t()) :: :ok | {:error, reason()}

Whether the policy allows the URL: :ok, or {:error, reason}. A URL is read as Macaw.Layers.Url reads it, from its text, so a struct built around Url.new/2 is judged as its text is.

check(value, policy)

@spec check(term(), t()) :: [Macaw.Layers.Fault.t()]

Every URL the value holds that the policy refuses, {path, {:url, reason}} by path from the value, ordered: its maps, lists, tuples and structs are walked, so a URL is found wherever any type holds one. A fault names the reason and never the URL.

iex> {:ok, url} = Macaw.Layers.Url.new("http://a.example/")
iex> Macaw.Layers.Url.Policy.check(%{marks: [%{url: url}]}, Macaw.Layers.Url.Policy.new!(schemes: ["https"], hosts: :any))
[{[:marks, 0, :url], {:url, :http}}]

narrow(policy, opts)

@spec narrow(t(), keyword()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The policy made stricter by opts, written as new/1 takes them: each key given keeps only what both allow, and a key not given keeps the policy's. A read can be stricter than its host, never looser: a host the policy does not cover, or a scheme it does not allow, is dropped, never added. {:ok, policy}, or opts' faults as new/1 gives them.

iex> host = Macaw.Layers.Url.Policy.new!(schemes: ["https", "http"], hosts: ["*.example"])
iex> Macaw.Layers.Url.Policy.narrow(host, schemes: ["https", "data"], hosts: ["a.example", "b.test"])
{:ok, %Macaw.Layers.Url.Policy{schemes: ["https"], hosts: ["a.example"], data: []}}

narrow!(policy, opts)

@spec narrow!(t(), keyword()) :: t()

narrow/2, or an ArgumentError naming every fault.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The policy that allows exactly what it names:

  • schemes: a list drawn from "https", "http" and "data";
  • hosts: :any, or a list of hosts ("tiles.example", an IPv6 literal in brackets) and "*.domain", any host under the domain, matched without regard to case;
  • data: a list drawn from "image/png", "image/jpeg" and "image/webp", the types a data: URL may have. It needs "data" among the schemes, and "data" needs it.

Each defaults to []. The answer is {:ok, policy}, or every fault of opts by its key: an unknown key, :unknown_key; a scheme or a data type outside its set, {:enum, allowed} at its index; a host that is not one, {:type, :host} at its index; a key's value of the wrong shape, {:type, …}; data: types without the data scheme, :needs_data_scheme at [:data], and the reverse, :needs_data_types at [:schemes].

iex> Macaw.Layers.Url.Policy.new([])
{:ok, %Macaw.Layers.Url.Policy{schemes: [], hosts: [], data: []}}
iex> Macaw.Layers.Url.Policy.new(schemes: ["https"], data: ["image/svg+xml"])
{:error, [{[:data], :needs_data_scheme}, {[:data, 0], {:enum, ["image/png", "image/jpeg", "image/webp"]}}]}

new!(opts)

@spec new!(keyword()) :: t()

new/1, or an ArgumentError naming every fault: a host's policy written in code.