atproto_core/remote

Remote-supplied URLs, parsed once at the boundary. Every hop of the OAuth discovery chain (DID documents, protected-resource and authorization-server metadata) hands us URLs an attacker may control, so the kernel only ever requests an Origin or a Url from this module: https only, no userinfo or fragment, and a host that is a public DNS name rather than an IP literal, localhost, a single-label name, or a local-only suffix (.local, .internal, .arpa, …).

That is the only behaviour of parse_origin and parse_url. Local development against a devnet (http://localhost:3000) is a separate, explicit act: parse_origin_with and parse_url_with with AllowLocalDevelopment. An origin accepted that way remembers it (policy_of), and the discovery code parses every URL a document names under the policy of the origin it fetched that document from. A strict origin therefore can never lead to a local one.

What cannot be decided at parse time is left to the transport: a public name can still resolve to a private address (DNS rebinding), so a server-side send must also refuse private, loopback, link-local and unique-local destinations after resolution, must not follow redirects, and must cap response size and request time.

Types

HostRejection

pub type HostRejection {
  MissingHost
  MalformedHost
  IpLiteral
  LocalName
  BadPort
}

Constructors

```
MissingHost
```
```
MalformedHost
```
```
IpLiteral
```
```
LocalName
```
```
BadPort
```

Origin

opaque

An origin: scheme, lowercased host, and a port. On a public host the scheme is https and the port is omitted when it is 443; on a local host (only under AllowLocalDevelopment) the port is always explicit. Compare with ==; the representation is canonical.

pub opaque type Origin

Policy

Which origins a parse accepts. PublicOnly is what every function that does not take a policy uses.

pub type Policy {
  PublicOnly
  AllowLocalDevelopment
}

Constructors

```
PublicOnly
```
```
AllowLocalDevelopment
```
Also accepts http and https on localhost, loopback and private addresses, IP literals and local-only names, each with an explicit port. For devnets and tests only. Never enable this in production: it lets whoever controls a document redirect requests to hosts on your own network.

Url

opaque

A URL on an Origin, with a path and optional query but never userinfo or a fragment.

pub opaque type Url

UrlError

pub type UrlError {
  Unparsable(url: String)
  NotHttps(url: String)
  HasUserinfo(url: String)
  HasFragment(url: String)
  NotAnOrigin(url: String)
  ForbiddenHost(url: String, reason: HostRejection)
}

Constructors

```
Unparsable(url: String)
```
```
NotHttps(url: String)
```
```
HasUserinfo(url: String)
```
```
HasFragment(url: String)
```
```
NotAnOrigin(url: String)
```
A path or query on a URL that must be a bare origin (PDS, issuer).

ForbiddenHost(url: String, reason: HostRejection)

Values

endpoint

pub fn endpoint(origin: Origin, path: String) -> Url

A URL on origin at an absolute path, built structurally rather than by string concatenation, so a path can never move the request to another host.

origin

pub fn origin(url: Url) -> Origin

origin_to_string

pub fn origin_to_string(origin: Origin) -> String

parse_origin

pub fn parse_origin(url: String) -> Result(Origin, UrlError)

Parse a bare origin under PublicOnly. A single trailing / is accepted and dropped; any other path, a query, or a fragment is rejected.

parse_origin_with

pub fn parse_origin_with(
  url: String,
  policy: Policy,
) -> Result(Origin, UrlError)

parse_origin under an explicit policy.

parse_url

pub fn parse_url(url: String) -> Result(Url, UrlError)

Parse an endpoint URL (authorization, token, PAR, revocation endpoints) under PublicOnly.

parse_url_with

pub fn parse_url_with(
  url: String,
  policy: Policy,
) -> Result(Url, UrlError)

parse_url under an explicit policy.

policy_of

pub fn policy_of(origin: Origin) -> Policy

The policy a parsed origin falls under: AllowLocalDevelopment when it is http or on a non-public host (so it can only have come from a parse that allowed it), PublicOnly otherwise. Discovery uses this to parse the URLs a document names under the policy of the origin that served it.

request_matches_origin

pub fn request_matches_origin(
  req: request.Request(body),
  origin: Origin,
) -> Bool

Whether req targets exactly origin (scheme, host, and port).

to_request

pub fn to_request(url: Url) -> request.Request(String)

A bodiless GET for url. Total: the parts were validated on parse.

url_error_to_string

pub fn url_error_to_string(error: UrlError) -> String

url_to_string

pub fn url_to_string(url: Url) -> String

with_query

pub fn with_query(
  url: Url,
  params: List(#(String, String)),
) -> Url

Append query parameters, keeping any the URL already carries.