-- SPDX-FileCopyrightText: 2026 Alexandra de Wit
--
-- SPDX-License-Identifier: MIT

{- | Textual extraction of the @host[:port]@ authority an outbound request dials.

These are comparison extractors, not an RFC 3986 parser: a value with no recognisable
authority yields the empty string or 'Nothing', which every guard treats as not-allowed. The
SSRF gates in "Ecluse.Core.Security.Host" consume the extracted 'HostPort', so the parsing
here carries no policy of its own.
-}
module Ecluse.Core.Security.Authority (
    -- * The dialled authority
    HostPort (..),

    -- * Authority extraction
    hostAddress,
    hostPortAddress,
    hostPortAddressWithDefault,
    splitHostPort,

    -- * Comparing authorities
    AuthorityText,
    authorityText,
    authorityHostPort,

    -- * Configured-URL refusal
    refuseCredentialMaterial,

    -- * Log-safe rendering
    authorityLabel,
    dialledAuthorityLabel,
    credentialFreeUrl,
    credentialFreeOrigin,
    dialledOrigin,
    credentialFreePath,
) where

import Data.Text qualified as T

import Ecluse.Core.Text (afterFirst, httpPrefix, isPrefixOfLowered, readDecimalText, registryPath, toLowerUnlessAsciiUnchanged)

-- | The authority an outbound fetch dials: a bare host with its effective port. The gate authorises the pair, so an allowlisted host at an attacker-chosen port is not authorised.
data HostPort = HostPort
    { HostPort -> Text
hpHost :: Text
    -- ^ The bare host: no brackets, no port, lower-cased by both extractors.
    , HostPort -> Word16
hpPort :: Word16
    -- ^ The effective port: the explicit @:port@, or the caller's portless default.
    }
    deriving stock (HostPort -> HostPort -> Bool
(HostPort -> HostPort -> Bool)
-> (HostPort -> HostPort -> Bool) -> Eq HostPort
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: HostPort -> HostPort -> Bool
== :: HostPort -> HostPort -> Bool
$c/= :: HostPort -> HostPort -> Bool
/= :: HostPort -> HostPort -> Bool
Eq, Eq HostPort
Eq HostPort =>
(HostPort -> HostPort -> Ordering)
-> (HostPort -> HostPort -> Bool)
-> (HostPort -> HostPort -> Bool)
-> (HostPort -> HostPort -> Bool)
-> (HostPort -> HostPort -> Bool)
-> (HostPort -> HostPort -> HostPort)
-> (HostPort -> HostPort -> HostPort)
-> Ord HostPort
HostPort -> HostPort -> Bool
HostPort -> HostPort -> Ordering
HostPort -> HostPort -> HostPort
forall a.
Eq a =>
(a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
$ccompare :: HostPort -> HostPort -> Ordering
compare :: HostPort -> HostPort -> Ordering
$c< :: HostPort -> HostPort -> Bool
< :: HostPort -> HostPort -> Bool
$c<= :: HostPort -> HostPort -> Bool
<= :: HostPort -> HostPort -> Bool
$c> :: HostPort -> HostPort -> Bool
> :: HostPort -> HostPort -> Bool
$c>= :: HostPort -> HostPort -> Bool
>= :: HostPort -> HostPort -> Bool
$cmax :: HostPort -> HostPort -> HostPort
max :: HostPort -> HostPort -> HostPort
$cmin :: HostPort -> HostPort -> HostPort
min :: HostPort -> HostPort -> HostPort
Ord, Int -> HostPort -> ShowS
[HostPort] -> ShowS
HostPort -> String
(Int -> HostPort -> ShowS)
-> (HostPort -> String) -> ([HostPort] -> ShowS) -> Show HostPort
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> HostPort -> ShowS
showsPrec :: Int -> HostPort -> ShowS
$cshow :: HostPort -> String
show :: HostPort -> String
$cshowList :: [HostPort] -> ShowS
showList :: [HostPort] -> ShowS
Show)

-- | The bare host of a URI or @host[:port]@ authority, lower-cased and unbracketed. A value with no recognisable host yields the empty string, which the guards treat as not-allowed.
hostAddress :: Text -> Text
hostAddress :: Text -> Text
hostAddress Text
raw = Text -> Text
toLowerUnlessAsciiUnchanged (Text -> ((Text, Text) -> Text) -> Maybe (Text, Text) -> Text
forall b a. b -> (a -> b) -> Maybe a -> b
maybe Text
"" (Text, Text) -> Text
forall a b. (a, b) -> a
fst (Text -> Maybe (Text, Text)
splitHostPort (Text -> Text
authorityOf Text
raw)))

-- | Extract the host and effective port, defaulting to 443. Refuse absent hosts and malformed ports.
hostPortAddress :: Text -> Maybe HostPort
hostPortAddress :: Text -> Maybe HostPort
hostPortAddress = AuthorityText -> Maybe HostPort
authorityHostPort (AuthorityText -> Maybe HostPort)
-> (Text -> AuthorityText) -> Text -> Maybe HostPort
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> AuthorityText
authorityText

-- | 'hostPortAddress' with the caller's own port for a URL that writes none, for a scheme whose portless default is not the gate's 443. The authority split and the port grammar do not change.
hostPortAddressWithDefault :: Word16 -> Text -> Maybe HostPort
hostPortAddressWithDefault :: Word16 -> Text -> Maybe HostPort
hostPortAddressWithDefault Word16
portless = Word16 -> Text -> Maybe HostPort
hostPortOf Word16
portless (Text -> Maybe HostPort)
-> (Text -> Text) -> Text -> Maybe HostPort
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> Text
authorityOf

-- | The only text of a URL that 'hostPortAddress' reads. Equal texts give equal results, so a caller may reuse one's result for the other.
newtype AuthorityText = AuthorityText Text
    deriving stock (AuthorityText -> AuthorityText -> Bool
(AuthorityText -> AuthorityText -> Bool)
-> (AuthorityText -> AuthorityText -> Bool) -> Eq AuthorityText
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: AuthorityText -> AuthorityText -> Bool
== :: AuthorityText -> AuthorityText -> Bool
$c/= :: AuthorityText -> AuthorityText -> Bool
/= :: AuthorityText -> AuthorityText -> Bool
Eq)

-- | The authority of a URI or bare @host[:port]@ value, without userinfo.
authorityText :: Text -> AuthorityText
authorityText :: Text -> AuthorityText
authorityText = Text -> AuthorityText
AuthorityText (Text -> AuthorityText) -> (Text -> Text) -> Text -> AuthorityText
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> Text
authorityOf

-- | 'hostPortAddress' from the authority text alone: @hostPortAddress = authorityHostPort . authorityText@.
authorityHostPort :: AuthorityText -> Maybe HostPort
authorityHostPort :: AuthorityText -> Maybe HostPort
authorityHostPort (AuthorityText Text
authority) = Word16 -> Text -> Maybe HostPort
hostPortOf Word16
443 Text
authority

hostPortOf :: Word16 -> Text -> Maybe HostPort
hostPortOf :: Word16 -> Text -> Maybe HostPort
hostPortOf Word16
portless Text
authority = do
    (host, rest) <- Text -> Maybe (Text, Text)
splitHostPort Text
authority
    guard (not (T.null host))
    port <- effectivePort portless authority rest
    pure (HostPort (toLowerUnlessAsciiUnchanged host) port)

-- | A host and effective port label without credential carriers, or @\<unresolved\>@ for an invalid authority.
authorityLabel :: Text -> Text
authorityLabel :: Text -> Text
authorityLabel = Word16 -> Text -> Text
authorityLabelWithDefault Word16
443

-- | A credential-free authority label using port 80 for a portless @http://@ URL, otherwise 443.
dialledAuthorityLabel :: Text -> Text
dialledAuthorityLabel :: Text -> Text
dialledAuthorityLabel Text
raw = Word16 -> Text -> Text
authorityLabelWithDefault Word16
portless Text
raw
  where
    portless :: Word16
portless = if LowerPrefix -> Text -> Bool
isPrefixOfLowered LowerPrefix
httpPrefix Text
raw then Word16
80 else Word16
443

authorityLabelWithDefault :: Word16 -> Text -> Text
authorityLabelWithDefault :: Word16 -> Text -> Text
authorityLabelWithDefault Word16
portless = Text -> (HostPort -> Text) -> Maybe HostPort -> Text
forall b a. b -> (a -> b) -> Maybe a -> b
maybe Text
unresolvedAuthority HostPort -> Text
renderHostPort (Maybe HostPort -> Text)
-> (Text -> Maybe HostPort) -> Text -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Word16 -> Text -> Maybe HostPort
hostPortAddressWithDefault Word16
portless

-- | Remove userinfo, query and fragment while retaining the fetched URL's scheme, authority and path.
credentialFreeUrl :: Text -> Text
credentialFreeUrl :: Text -> Text
credentialFreeUrl Text
raw = Text -> Text
credentialFreeOrigin Text
raw Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
credentialFreePath Text
raw

-- | The scheme and the authority as written, without userinfo.
credentialFreeOrigin :: Text -> Text
credentialFreeOrigin :: Text -> Text
credentialFreeOrigin Text
raw = Text -> Text
schemePrefix Text
raw Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
authorityOf Text
raw

-- | The scheme and the dialled @host:port@, the part of a URL that names where it was fetched from.
dialledOrigin :: Text -> Text
dialledOrigin :: Text -> Text
dialledOrigin Text
raw = Text -> Text
schemePrefix Text
raw Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
dialledAuthorityLabel Text
raw

-- | The path a URL fetches. The query and fragment are cut first, so a slash inside them is never read as the path.
credentialFreePath :: Text -> Text
credentialFreePath :: Text -> Text
credentialFreePath = Text -> Text
registryPath (Text -> Text) -> (Text -> Text) -> Text -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Char -> Bool) -> Text -> Text
T.takeWhile (Char -> String -> Bool
forall (f :: * -> *) a.
(Foldable f, DisallowElem f, Eq a) =>
a -> f a -> Bool
`notElem` [Char
'?', Char
'#'])

-- The scheme with its separator, or empty for a URL that writes none.
schemePrefix :: Text -> Text
schemePrefix :: Text -> Text
schemePrefix Text
raw = case HasCallStack => Text -> Text -> (Text, Text)
Text -> Text -> (Text, Text)
T.breakOn Text
"://" Text
raw of
    (Text
written, Text
separator) | Bool -> Bool
not (Text -> Bool
T.null Text
separator) -> Text
written Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
"://"
    (Text, Text)
_ -> Text
""

-- The angle brackets match what the resolved-configuration provenance lines use for a
-- withheld value.
unresolvedAuthority :: Text
unresolvedAuthority :: Text
unresolvedAuthority = Text
"<unresolved>"

{- Render a 'HostPort' back to a @host:port@ authority. An IPv6 host must be re-bracketed, since
@2606:4700::1111:8443@ is neither the host nor a parseable authority. -}
renderHostPort :: HostPort -> Text
renderHostPort :: HostPort -> Text
renderHostPort (HostPort Text
host Word16
port)
    | Text
":" Text -> Text -> Bool
`T.isInfixOf` Text
host = Text
"[" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
host Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
"]:" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Word16 -> Text
forall b a. (Show a, IsString b) => a -> b
show Word16
port
    | Bool
otherwise = Text
host Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
":" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Word16 -> Text
forall b a. (Show a, IsString b) => a -> b
show Word16
port

{- The port an authority dials: an explicit @":port"@, or @portless@ when it writes none. A
written-but-empty port is malformed, and the authority's trailing colon is what catches it. -}
effectivePort :: Word16 -> Text -> Text -> Maybe Word16
effectivePort :: Word16 -> Text -> Text -> Maybe Word16
effectivePort Word16
portless Text
authority Text
rest = case Text -> Text -> Maybe Text
T.stripPrefix Text
":" Text
rest of
    Just Text
written -> Text -> Maybe Word16
parsePort Text
written
    Maybe Text
Nothing
        | Bool -> Bool
not (Text -> Bool
T.null Text
rest) -> Maybe Word16
forall a. Maybe a
Nothing
        | Text
":" Text -> Text -> Bool
`T.isSuffixOf` Text
authority -> Maybe Word16
forall a. Maybe a
Nothing
        | Bool
otherwise -> Word16 -> Maybe Word16
forall a. a -> Maybe a
Just Word16
portless

{- A dialled port in the one spelling the gate accepts: decimal digits, no leading zero, 1..65535.
No crafted spelling may alias a canonical port, so 'readDecimalText' bars the other spellings. -}
parsePort :: Text -> Maybe Word16
parsePort :: Text -> Maybe Word16
parsePort Text
t = do
    Bool -> Maybe ()
forall (f :: * -> *). Alternative f => Bool -> f ()
guard (Int -> Text -> Text
T.take Int
1 Text
t Text -> Text -> Bool
forall a. Eq a => a -> a -> Bool
/= Text
"0")
    n <- Text -> Maybe Integer
forall a. Integral a => Text -> Maybe a
readDecimalText Text
t :: Maybe Integer
    guard (n >= 1 && n <= 65535)
    pure (fromInteger n)

-- Returns the answer alone, never the credential-bearing span it read.
carriesUserinfo :: Text -> Bool
carriesUserinfo :: Text -> Bool
carriesUserinfo = Text -> Text -> Bool
T.isInfixOf Text
"@" (Text -> Bool) -> (Text -> Text) -> Text -> Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> Text
authoritySpan

-- | Refuse configured URLs with userinfo, query or fragment before any check quotes the URL. Reasons never quote credentials.
refuseCredentialMaterial :: Text -> Text -> Either Text ()
refuseCredentialMaterial :: Text -> Text -> Either Text ()
refuseCredentialMaterial Text
subject Text
url
    | Text -> Bool
carriesUserinfo Text
url =
        Text -> Either Text ()
forall a b. a -> Either a b
Left (Text
subject Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
" must not carry userinfo (a credential belongs in its own configuration key)")
    | Text
"?" Text -> Text -> Bool
`T.isInfixOf` Text
url = Text -> Either Text ()
forall a b. a -> Either a b
Left (Text
subject Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
" must not carry a query string")
    | Text
"#" Text -> Text -> Bool
`T.isInfixOf` Text
url = Text -> Either Text ()
forall a b. a -> Either a b
Left (Text
subject Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
" must not carry a fragment")
    | Bool
otherwise = () -> Either Text ()
forall a b. b -> Either a b
Right ()

{- The authority component, userinfo intact, truncated at the first path, query, or fragment
delimiter. Kept private: a caller holding the credential-bearing span is the exposure to prevent. -}
authoritySpan :: Text -> Text
authoritySpan :: Text -> Text
authoritySpan Text
raw = (Char -> Bool) -> Text -> Text
T.takeWhile Char -> Bool
inAuthority (Text -> Text -> Text
afterFirst Text
"://" Text
raw)

inAuthority :: Char -> Bool
inAuthority :: Char -> Bool
inAuthority Char
c = Char
c Char -> Char -> Bool
forall a. Eq a => a -> a -> Bool
/= Char
'/' Bool -> Bool -> Bool
&& Char
c Char -> Char -> Bool
forall a. Eq a => a -> a -> Bool
/= Char
'?' Bool -> Bool -> Bool
&& Char
c Char -> Char -> Bool
forall a. Eq a => a -> a -> Bool
/= Char
'#'

{- The authority of a URI or bare @host[:port]@ value, with any userinfo dropped. 'hostAddress' and
'hostPortAddress' share it, so the two extractions cannot drift on an authority edge case. -}
authorityOf :: Text -> Text
authorityOf :: Text -> Text
authorityOf = Text -> Text -> Text
afterLast Text
"@" (Text -> Text) -> (Text -> Text) -> Text -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Text -> Text
authoritySpan

-- The text after @needle@'s last occurrence, or all of @hay@ if absent. The last "@" is the
-- userinfo boundary, matching what URL parsers do.
afterLast :: Text -> Text -> Text
afterLast :: Text -> Text -> Text
afterLast Text
needle Text
hay =
    let (Text
pre, Text
post) = HasCallStack => Text -> Text -> (Text, Text)
Text -> Text -> (Text, Text)
T.breakOnEnd Text
needle Text
hay
     in if Text -> Bool
T.null Text
pre then Text
hay else Text
post

-- | Split a @host[:port]@ authority into its bare host and the raw @":port"@ remainder, empty when no port is present. The split is bracket-aware, and an unclosed opening bracket yields 'Nothing'.
splitHostPort :: Text -> Maybe (Text, Text)
splitHostPort :: Text -> Maybe (Text, Text)
splitHostPort Text
authority
    | Text -> Bool
T.null Text
authority = Maybe (Text, Text)
forall a. Maybe a
Nothing
    | Bool
otherwise = case Text -> Text -> Maybe Text
T.stripPrefix Text
"[" Text
authority of
        Just Text
rest -> case HasCallStack => Text -> Text -> (Text, Text)
Text -> Text -> (Text, Text)
T.breakOn Text
"]" Text
rest of
            (Text
_, Text
"") -> Maybe (Text, Text)
forall a. Maybe a
Nothing -- an opening bracket with no close: malformed
            (Text
inner, Text
afterBracket) -> (Text, Text) -> Maybe (Text, Text)
forall a. a -> Maybe a
Just (Text
inner, Int -> Text -> Text
T.drop Int
1 Text
afterBracket)
        Maybe Text
Nothing -> case HasCallStack => Text -> Text -> (Text, Text)
Text -> Text -> (Text, Text)
T.breakOn Text
":" Text
authority of
            (Text
"", Text
_) -> Maybe (Text, Text)
forall a. Maybe a
Nothing
            (Text
h, Text
"") -> (Text, Text) -> Maybe (Text, Text)
forall a. a -> Maybe a
Just (Text
h, Text
"")
            (Text
h, Text
p) -> if Text
p Text -> Text -> Bool
forall a. Eq a => a -> a -> Bool
== Text
":" then (Text, Text) -> Maybe (Text, Text)
forall a. a -> Maybe a
Just (Text
h, Text
"") else (Text, Text) -> Maybe (Text, Text)
forall a. a -> Maybe a
Just (Text
h, Text
p)