hstsheader 0.2.0__py3-none-any.whl

hstsheader/__init__.py

@@ -0,0 +1,24 @@
+"""Parse, check and build the HTTP Strict-Transport-Security header, typed and zero-dependency."""
+
+from __future__ import annotations
+
+from ._build import build
+from ._lint import lint
+from ._model import DELTA_SECONDS_MAX, PRELOAD_MIN_MAX_AGE, Hsts, HstsError, Issue
+from ._parse import parse
+from ._preload import is_preloadable, preload_issues
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DELTA_SECONDS_MAX",
+    "PRELOAD_MIN_MAX_AGE",
+    "Hsts",
+    "HstsError",
+    "Issue",
+    "build",
+    "is_preloadable",
+    "lint",
+    "parse",
+    "preload_issues",
+]

hstsheader/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m hstsheader``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

hstsheader/_build.py

@@ -0,0 +1,78 @@
+"""Render a Strict-Transport-Security header value that cannot carry an injection."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ._chars import ascii_lower, is_sendable, is_token, quote
+from ._model import Hsts, HstsError
+
+_KNOWN = frozenset({"max-age", "includesubdomains", "preload"})
+
+
+def _extension(name: object, value: object, seen: set[str]) -> str:
+    if not isinstance(name, str):
+        raise HstsError(f"extension name {name!r} is not an HTTP token", code="build.name")
+    # Check and write plain str copies: a str subclass could lie in __iter__ or __format__.
+    name = str.__str__(name)
+    if not is_token(name):
+        raise HstsError(f"extension name {name!r} is not an HTTP token", code="build.name")
+    key = ascii_lower(name)
+    if key in _KNOWN:
+        raise HstsError(
+            f"{name} is set by its own argument, not as an extension", code="build.name"
+        )
+    if key in seen:
+        raise HstsError(f"extension {name} is given twice", code="duplicate")
+    seen.add(key)
+    if value is None:
+        return name
+    if not isinstance(value, str):
+        raise HstsError(f"extension {name} needs a str value or None", code="type")
+    value = str.__str__(value)
+    if is_token(value):
+        return f"{name}={value}"
+    if not is_sendable(value):
+        message = f"extension {name} has a control or non-ASCII character in its value"
+        raise HstsError(message, code="build.value")
+    return f"{name}={quote(value)}"
+
+
+def build(
+    max_age: int | Hsts,
+    *,
+    include_subdomains: bool | None = None,
+    preload: bool | None = None,
+    extensions: Mapping[str, str | None] | None = None,
+) -> str:
+    """Build a Strict-Transport-Security header value.
+
+    Pass an :class:`Hsts`, or ``max_age`` (an ``int`` from 0 to
+    :data:`DELTA_SECONDS_MAX`) with the ``include_subdomains`` and ``preload`` flags.
+    ``extensions`` maps further directive names (HTTP tokens other than the three known
+    ones) to a value, or to ``None`` for a valueless directive; values that are not
+    tokens are written as quoted strings, and control or non-ASCII characters are
+    refused, so the result is always one well-formed field value. Directives come out
+    in a fixed order: max-age, includeSubDomains, preload, then the extensions.
+    """
+    if isinstance(max_age, Hsts):
+        if include_subdomains is not None or preload is not None:
+            raise TypeError("pass the flags on the Hsts object, not as arguments")
+        policy = max_age
+    else:
+        policy = Hsts(
+            max_age,
+            False if include_subdomains is None else include_subdomains,
+            False if preload is None else preload,
+        )
+    parts = [f"max-age={policy.max_age}"]
+    if policy.include_subdomains:
+        parts.append("includeSubDomains")
+    if policy.preload:
+        parts.append("preload")
+    if extensions is not None and not isinstance(extensions, Mapping):
+        raise HstsError("extensions must be a mapping of name to value", code="type")
+    seen: set[str] = set()
+    for name, value in (extensions or {}).items():
+        parts.append(_extension(name, value, seen))
+    return "; ".join(parts)

hstsheader/_chars.py

@@ -0,0 +1,49 @@
+"""Character classes from RFC 9110 section 5.6 and RFC 2616 section 2.2."""
+
+from __future__ import annotations
+
+import string
+
+# tchar: any visible US-ASCII character except the delimiters.
+TCHAR = frozenset(string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~")
+DIGITS = frozenset(string.digits)
+OWS = " \t"
+
+# Upper-case ASCII only: str.lower() would also fold non-ASCII letters (the Kelvin sign
+# becomes "k"), which must never turn into a directive name.
+_ASCII_LOWER = str.maketrans(string.ascii_uppercase, string.ascii_lowercase)
+
+
+def ascii_lower(text: str) -> str:
+    return text.translate(_ASCII_LOWER)
+
+
+def is_token(text: str) -> bool:
+    return bool(text) and all(char in TCHAR for char in text)
+
+
+def is_qdtext(char: str) -> bool:
+    code = ord(char)
+    return (
+        char in OWS
+        or code == 0x21
+        or 0x23 <= code <= 0x5B
+        or 0x5D <= code <= 0x7E
+        or 0x80 <= code <= 0xFF
+    )
+
+
+def is_pair_char(char: str) -> bool:
+    """The octet allowed after a backslash in a quoted-pair."""
+    code = ord(char)
+    return char in OWS or 0x21 <= code <= 0x7E or 0x80 <= code <= 0xFF
+
+
+def is_sendable(text: str) -> bool:
+    """True when a sender may put the text in a quoted string: HTAB, SP and VCHAR only."""
+    return all(char in OWS or 0x21 <= ord(char) <= 0x7E for char in text)
+
+
+def quote(text: str) -> str:
+    """Write a quoted-string, escaping only the backslash and the double quote."""
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'

hstsheader/_cli.py

@@ -0,0 +1,79 @@
+"""Command line: check a Strict-Transport-Security value or a response head, print JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from ._head import field_lines
+from ._lint import analyse
+from ._model import Issue
+from ._preload import preload_issues
+
+EXIT_REJECTED = 1
+EXIT_USAGE = 2
+
+
+def _issue(issue: Issue) -> dict[str, object]:
+    return {
+        "code": issue.code,
+        "severity": issue.severity,
+        "offset": issue.offset,
+        "message": issue.message,
+    }
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line; returns the process exit code."""
+    parser = argparse.ArgumentParser(
+        prog="hstsheader",
+        description="Check a Strict-Transport-Security value, or the response head read from "
+        "standard input (for example the output of curl -sI). Prints the policy and the "
+        "findings as JSON. Exit status 0 means a user agent that follows RFC 6797 honours "
+        "the header (with --preload: that it meets the preload list rules), 1 that it does "
+        "not, 2 a usage error such as input without the field.",
+    )
+    parser.add_argument("value", nargs="?", help="a Strict-Transport-Security field value")
+    parser.add_argument(
+        "--preload", action="store_true", help="also check the hstspreload.org requirements"
+    )
+    args = parser.parse_args(argv)
+    if args.value is None and sys.stdin.isatty():
+        parser.error("give a value, or pipe a response head (curl -sI URL | hstsheader)")
+    # Latin-1 keeps every octet of a raw head, obs-text included.
+    text = args.value if args.value is not None else sys.stdin.buffer.read().decode("latin-1")
+    fields = field_lines(text)
+    if fields is None:
+        bare = text.strip(" \t\r\n")
+        # An empty argument is a value to check; empty standard input is a usage error.
+        fields = [bare] if bare or args.value is not None else []
+    if not fields:
+        print("hstsheader: no Strict-Transport-Security field in the input", file=sys.stderr)
+        return EXIT_USAGE
+    analysis = analyse(fields)
+    policy = None
+    if analysis.max_age is not None:
+        policy = {
+            "max_age": analysis.max_age,
+            "include_subdomains": analysis.include_subdomains,
+            "preload": analysis.preload,
+        }
+    report: dict[str, object] = {
+        "field": fields[0],
+        "honoured": not analysis.errors,
+        "policy": policy,
+        "issues": [_issue(issue) for issue in analysis.issues],
+    }
+    ok = not analysis.errors
+    if args.preload:
+        every = preload_issues(fields)
+        found = [i for i in every if i.code.startswith("preload.")]
+        preloadable = not any(i.severity == "error" for i in every)
+        report["preloadable"] = preloadable
+        report["preload_issues"] = [_issue(issue) for issue in found]
+        ok = preloadable
+    json.dump(report, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0 if ok else EXIT_REJECTED

hstsheader/_head.py

@@ -0,0 +1,59 @@
+"""Find the Strict-Transport-Security field lines in a response head such as curl -sI prints."""
+
+from __future__ import annotations
+
+import re
+
+_FIELD = "strict-transport-security"
+_FIELD_LINE = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+:")
+
+
+def _responses(lines: list[str]) -> list[list[str]]:
+    """Split lines into heads: each starts at a status line and ends at a blank line."""
+    heads: list[list[str]] = []
+    current: list[str] | None = None
+    for line in lines:
+        if line.startswith("HTTP/"):
+            current = []
+            heads.append(current)
+        elif not line.strip(" \t"):
+            current = None  # the head is over; a body may follow
+        elif current is not None:
+            current.append(line)
+    return heads
+
+
+def _unfold(lines: list[str]) -> list[str]:
+    """Join obsolete folded lines (starting with SP or HTAB) onto the line before."""
+    out: list[str] = []
+    for line in lines:
+        if line[:1] in (" ", "\t") and out:
+            out[-1] += " " + line.strip(" \t")
+        else:
+            out.append(line)
+    return out
+
+
+def field_lines(text: str) -> list[str] | None:
+    """Return the STS values of the last response in ``text``, or None for a bare value.
+
+    Input counts as a head when its first non-empty line is a status line or a field
+    line (``name: value``). With several responses (``curl -sIL`` follows redirects) the
+    last one is used, because that is the response the browser ends up keeping.
+    """
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    while lines and not lines[0].strip(" \t"):
+        lines.pop(0)
+    if not lines:
+        return None
+    if not lines[0].startswith("HTTP/"):
+        if not _FIELD_LINE.match(lines[0]):
+            return None
+        lines.insert(0, "HTTP/")  # pasted fields without a status line
+    heads = _responses(lines)
+    values: list[str] = []
+    for line in _unfold(heads[-1]):
+        name, sep, value = line.partition(":")
+        if sep and name.lower() == _FIELD:
+            values.append(value.strip(" \t"))
+    return values

hstsheader/_lint.py

@@ -0,0 +1,166 @@
+"""Check a header value against RFC 6797 and collect what a reader can recover from it."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+from ._chars import DIGITS
+from ._model import DELTA_SECONDS_MAX, Issue
+from ._scan import Directive, scan
+
+_VALUELESS = {"includesubdomains": "includeSubDomains", "preload": "preload"}
+# Chromium refuses a header only when these repeat; the preload checker only warns otherwise.
+_HARD_REPEATS = frozenset({"max-age", "includesubdomains"})
+# The hstspreload.org checker reads max-age as a 64-bit unsigned integer.
+_UINT64_MAX = 2**64 - 1
+
+
+@dataclass(frozen=True, slots=True)
+class Analysis:
+    """Everything known about one header: findings plus the tolerant reading.
+
+    The ``max_age_*`` flags describe the max-age directive that was used.
+    ``soft_repeats`` holds the offsets of repeated directives other than max-age and
+    includeSubDomains: errors for RFC 6797, tolerated by Chromium and the preload checker.
+    """
+
+    issues: tuple[Issue, ...]
+    max_age: int | None = None
+    include_subdomains: bool = False
+    preload: bool = False
+    max_age_quoted: bool = False
+    max_age_spaced: bool = False
+    max_age_beyond_uint64: bool = False
+    soft_repeats: frozenset[int] = frozenset()
+
+    @property
+    def errors(self) -> tuple[Issue, ...]:
+        return tuple(issue for issue in self.issues if issue.severity == "error")
+
+
+def delta_seconds(digits: str) -> tuple[int, bool]:
+    """Read ASCII digits as seconds; values past 2^31 become 2^31 (flag set)."""
+    significant = digits.lstrip("0") or "0"
+    # Never convert a long digit string: int() refuses more than 4300 digits.
+    if len(significant) > len(str(DELTA_SECONDS_MAX)):
+        return DELTA_SECONDS_MAX, True
+    value = int(significant)
+    return (DELTA_SECONDS_MAX, True) if value > DELTA_SECONDS_MAX else (value, False)
+
+
+def _beyond_uint64(digits: str) -> bool:
+    significant = digits.lstrip("0")
+    return len(significant) > len(str(_UINT64_MAX)) or int(significant or "0") > _UINT64_MAX
+
+
+def _max_age(directive: Directive, issues: list[Issue]) -> int | None:
+    value, offset = directive.value, directive.value_offset
+    if value is None:
+        issues.append(Issue("max-age.no-value", "max-age needs a value", "error", directive.offset))
+        return None
+    if not value or not all(char in DIGITS for char in value):
+        message = f"max-age must be ASCII digits, got {value!r}"
+        issues.append(Issue("max-age.not-digits", message, "error", offset))
+        return None
+    seconds, capped = delta_seconds(value)
+    if len(value) > 1 and value[0] == "0":
+        issues.append(
+            Issue("max-age.leading-zero", "max-age has a leading zero", "warning", offset)
+        )
+    if capped:
+        message = f"max-age is larger than {DELTA_SECONDS_MAX} and is read as that value"
+        issues.append(Issue("max-age.capped", message, "warning", offset))
+    if directive.quoted:
+        message = "max-age is quoted; valid, but the hstspreload.org checker refuses it"
+        issues.append(Issue("max-age.quoted", message, "warning", offset))
+    if directive.spaced:
+        message = "space around '=' in max-age; valid, but the hstspreload.org checker refuses it"
+        issues.append(Issue("max-age.spaced", message, "warning", directive.offset))
+    return seconds
+
+
+def _first_field(value: str | Iterable[str]) -> tuple[str | None, int]:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        raise TypeError("pass the header as str; decode bytes with latin-1 first")
+    if isinstance(value, str):
+        return value, 1
+    if isinstance(value, Mapping) or not isinstance(value, Iterable):
+        raise TypeError(f"pass a str or a list of str, got {type(value).__name__}")
+    fields = list(value)
+    for item in fields:
+        if not isinstance(item, str):
+            raise TypeError(f"field lines must be str, got {type(item).__name__}")
+    return (fields[0] if fields else None), len(fields)
+
+
+def analyse(value: str | Iterable[str]) -> Analysis:
+    """Scan the first field line of ``value`` and judge each directive."""
+    text, count = _first_field(value)
+    if text is None:
+        return Analysis((Issue("field.missing", "no Strict-Transport-Security field", "error"),))
+    found = scan(text)
+    issues = list(found.issues)
+    if count > 1:
+        message = f"{count} field lines; a user agent processes only the first (RFC 6797 8.1)"
+        issues.append(Issue("multiple-fields", message, "warning"))
+    # Broken directives count for repeats too, in the order they appear.
+    order: list[tuple[int, str, Directive | None]] = [
+        (d.offset, d.key, d) for d in found.directives
+    ]
+    order += [(offset, key, None) for offset, key in found.broken]
+    seen: set[str] = set()
+    soft: set[int] = set()
+    used: Directive | None = None
+    max_age: int | None = None
+    flags = {key: False for key in _VALUELESS}
+    for offset, key, directive in sorted(order, key=lambda item: item[0]):
+        if key in seen:
+            name = directive.name if directive else key
+            message = f"{name} appears more than once; every directive must be unique"
+            issues.append(Issue("duplicate", message, "error", offset))
+            if key not in _HARD_REPEATS:
+                soft.add(offset)
+        seen.add(key)
+        if directive is None:
+            continue
+        if key == "max-age":
+            seconds = _max_age(directive, issues)
+            if max_age is None and seconds is not None:
+                max_age, used = seconds, directive
+        elif key in _VALUELESS:
+            if directive.value is not None:
+                message = f"{_VALUELESS[key]} takes no value"
+                issues.append(Issue("value-not-allowed", message, "error", offset))
+            else:
+                flags[key] = True
+        else:
+            message = f"unknown directive {directive.name} is ignored"
+            issues.append(Issue("unknown-directive", message, "warning", offset))
+    if "max-age" not in seen:
+        issues.append(Issue("max-age.missing", "max-age is required", "error"))
+    if max_age == 0 and flags["includesubdomains"]:
+        message = "max-age=0 removes the policy; includeSubDomains has no effect"
+        issues.append(Issue("max-age.zero-subdomains", message, "warning"))
+    issues.sort(key=lambda issue: (issue.offset is None, issue.offset or 0))
+    return Analysis(
+        tuple(issues),
+        max_age,
+        flags["includesubdomains"],
+        flags["preload"],
+        used is not None and used.quoted,
+        used is not None and used.spaced,
+        used is not None and _beyond_uint64(used.value or ""),
+        frozenset(soft),
+    )
+
+
+def lint(value: str | Iterable[str]) -> tuple[Issue, ...]:
+    """List every finding about a Strict-Transport-Security value, in field order.
+
+    Pass one field value, or every field line of a response (only the first is
+    processed, as RFC 6797 section 8.1 requires). Findings with severity ``error`` mean a
+    user agent that follows RFC 6797 ignores the header; an empty tuple means a clean
+    header. Chromium is more lenient in places (see the README).
+    """
+    return analyse(value).issues

hstsheader/_model.py

@@ -0,0 +1,79 @@
+"""The parsed form of a Strict-Transport-Security header, its findings and its error type."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+# RFC 9111 section 1.2.2: a delta-seconds value too large to represent is read as 2^31.
+DELTA_SECONDS_MAX = 2147483648
+
+# hstspreload.org: the header on the base domain needs a max-age of at least one year.
+PRELOAD_MIN_MAX_AGE = 31536000
+
+Severity = Literal["error", "warning"]
+
+
+class HstsError(ValueError):
+    """Raised when a header cannot be read or a value is not valid.
+
+    ``code`` names the rule that failed (the same codes as :class:`Issue`) and
+    ``offset`` is the index in the field value where it failed, when there is one.
+    """
+
+    def __init__(self, message: str, *, code: str = "invalid", offset: int | None = None) -> None:
+        super().__init__(message if offset is None else f"{message} (at offset {offset})")
+        self.code = code
+        self.offset = offset
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One finding about a header value.
+
+    An ``error`` means a conforming user agent ignores the whole header; a ``warning``
+    marks something legal that is likely a mistake or is refused by some checkers.
+    """
+
+    code: str
+    message: str
+    severity: Severity
+    offset: int | None = None
+
+
+def _check_flag(name: str, value: object) -> None:
+    if not isinstance(value, bool):
+        raise HstsError(f"{name} must be a bool, got {type(value).__name__}", code="type")
+
+
+def check_max_age(value: object) -> int:
+    """Return ``value`` when it is a valid max-age for a sender, else raise."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise HstsError("max_age must be an integer number of seconds", code="type")
+    if value < 0:
+        raise HstsError("max_age must not be negative", code="max-age.negative")
+    if value > DELTA_SECONDS_MAX:
+        raise HstsError(
+            f"max_age must not exceed {DELTA_SECONDS_MAX}; recipients read larger values as that",
+            code="max-age.too-large",
+        )
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class Hsts:
+    """A Strict-Transport-Security policy: a max-age and two optional flags.
+
+    The fields are checked on creation: ``max_age`` is an ``int`` from 0 to
+    :data:`DELTA_SECONDS_MAX` and both flags are ``bool``.
+    """
+
+    max_age: int
+    include_subdomains: bool = False
+    preload: bool = False
+
+    def __post_init__(self) -> None:
+        # Keep a plain int: an int subclass could render itself as anything in a header.
+        object.__setattr__(self, "max_age", int.__index__(check_max_age(self.max_age)))
+        _check_flag("include_subdomains", self.include_subdomains)
+        _check_flag("preload", self.preload)

hstsheader/_parse.py

@@ -0,0 +1,36 @@
+"""Read a Strict-Transport-Security header value into an :class:`Hsts`."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ._lint import analyse
+from ._model import Hsts, HstsError
+
+
+def parse(header: str | Iterable[str], *, strict: bool = False) -> Hsts:
+    """Parse a Strict-Transport-Security header value.
+
+    ``header`` is one field value, or the field lines of a response in order (only the
+    first is read, RFC 6797 section 8.1). Directive names match ASCII case-insensitively,
+    whitespace around ``;`` and ``=`` is allowed, unknown directives are ignored and
+    ``max-age`` may be quoted. Values above :data:`DELTA_SECONDS_MAX` are read as it.
+
+    With ``strict=True`` the header must be one a conforming user agent honours: any
+    finding of severity ``error`` from :func:`lint` raises :class:`HstsError` with its
+    code and offset. By default the reader is tolerant: it skips broken directives, keeps
+    the first valid ``max-age`` and raises only when no valid ``max-age`` is left.
+    """
+    analysis = analyse(header)
+    if strict and analysis.errors:
+        first = analysis.errors[0]
+        raise HstsError(first.message, code=first.code, offset=first.offset)
+    if analysis.max_age is None:
+        # analyse() always records an error when no max-age is usable: a max-age finding,
+        # or the syntax error that made the max-age directive unreadable.
+        reason = next(
+            (i for i in analysis.errors if i.code.startswith(("max-age", "field"))),
+            analysis.errors[0],
+        )
+        raise HstsError(reason.message, code=reason.code, offset=reason.offset)
+    return Hsts(analysis.max_age, analysis.include_subdomains, analysis.preload)

hstsheader/_preload.py

@@ -0,0 +1,74 @@
+"""Check a header against the hstspreload.org submission requirements."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ._lint import Analysis, analyse
+from ._model import PRELOAD_MIN_MAX_AGE, Hsts, Issue
+
+# hstspreload.org warns above ten years of 365 days.
+_TEN_YEARS = 10 * 365 * 86400
+
+
+def _form_issues(analysis: Analysis) -> list[Issue]:
+    """RFC errors, with repeats the site tolerates turned into warnings, plus its own rules."""
+    issues = [
+        Issue(i.code, i.message, "warning", i.offset)
+        if i.code == "duplicate" and i.offset in analysis.soft_repeats
+        else i
+        for i in analysis.errors
+    ]
+    if analysis.max_age_quoted:
+        message = "hstspreload.org does not accept a quoted max-age"
+        issues.append(Issue("preload.max-age-quoted", message, "error"))
+    if analysis.max_age_spaced:
+        message = "hstspreload.org does not accept space around '=' in max-age"
+        issues.append(Issue("preload.max-age-spaced", message, "error"))
+    if analysis.max_age_beyond_uint64:
+        message = "hstspreload.org cannot read a max-age above 2^64 - 1"
+        issues.append(Issue("preload.max-age-unreadable", message, "error"))
+    return issues
+
+
+def preload_issues(header: Hsts | str | Iterable[str]) -> tuple[Issue, ...]:
+    """List what keeps a header from the HSTS preload list.
+
+    A header value is first checked against RFC 6797: its errors are included, except a
+    repeated directive other than max-age and includeSubDomains, which Chromium and the
+    site's checker tolerate and which comes back as a warning. An :class:`Hsts` is taken
+    as already valid. Then the hstspreload.org rules apply: ``includeSubDomains`` and
+    ``preload`` present, and a ``max-age`` of at least :data:`PRELOAD_MIN_MAX_AGE`,
+    written the way the site's checker reads it (unquoted, no space around ``=``, at most
+    2^64 - 1). A ``max-age`` above ten years is a warning. An empty tuple or warnings only
+    means the header qualifies.
+    """
+    if isinstance(header, Hsts):
+        issues: list[Issue] = []
+        max_age: int | None = header.max_age
+        subdomains, preload = header.include_subdomains, header.preload
+    else:
+        analysis = analyse(header)
+        issues = _form_issues(analysis)
+        max_age = analysis.max_age
+        subdomains, preload = analysis.include_subdomains, analysis.preload
+    if not subdomains:
+        message = "the includeSubDomains directive is required"
+        issues.append(Issue("preload.subdomains-missing", message, "error"))
+    if not preload:
+        issues.append(Issue("preload.missing", "the preload directive is required", "error"))
+    if max_age == 0:
+        message = "max-age=0 asks for removal; use the hstspreload.org removal form instead"
+        issues.append(Issue("preload.max-age-zero", message, "error"))
+    elif max_age is not None and max_age < PRELOAD_MIN_MAX_AGE:
+        message = f"max-age must be at least {PRELOAD_MIN_MAX_AGE} seconds (one year)"
+        issues.append(Issue("preload.max-age-too-short", message, "error"))
+    elif max_age is not None and max_age > _TEN_YEARS:
+        message = "max-age is longer than ten years, an unusually long value"
+        issues.append(Issue("preload.max-age-over-ten-years", message, "warning"))
+    return tuple(issues)
+
+
+def is_preloadable(header: Hsts | str | Iterable[str]) -> bool:
+    """True when :func:`preload_issues` finds no error."""
+    return not any(issue.severity == "error" for issue in preload_issues(header))

hstsheader/_scan.py

@@ -0,0 +1,180 @@
+"""Split a field value into directives following the RFC 6797 section 6.1 grammar.
+
+    Strict-Transport-Security = [ directive ] *( ";" [ directive ] )
+    directive                 = directive-name [ "=" directive-value ]
+    directive-name            = token
+    directive-value           = token | quoted-string
+
+Whitespace may appear between any two words and separators (RFC 2616 section 2.2,
+"implied *LWS"), and a folded line (CRLF followed by SP or HTAB) counts as whitespace, as
+RFC 2616 LWS and RFC 9112 section 5.2 allow. A quoted-pair follows RFC 9110 section 5.6.4
+(HTAB, SP, VCHAR or obs-text after the backslash), stricter on purpose than RFC 2616, which
+let any US-ASCII character follow. A directive that breaks the grammar is reported and
+skipped up to the next semicolon that is not inside a quoted string, so the rest can still
+be read.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from ._chars import OWS, TCHAR, ascii_lower, is_pair_char, is_qdtext
+from ._model import Issue
+
+# RFC 9110 section 5.5: CR, LF and NUL are invalid; a recipient may replace them with SP.
+_REPLACED = str.maketrans({"\r": " ", "\n": " ", "\0": " "})
+_FOLD = re.compile(r"\r?\n(?=[ \t])")
+
+
+@dataclass(frozen=True, slots=True)
+class Directive:
+    name: str
+    key: str
+    value: str | None
+    quoted: bool
+    offset: int
+    value_offset: int
+    # Whitespace around "=": legal, but the hstspreload.org checker refuses it for max-age.
+    spaced: bool = False
+
+
+@dataclass(slots=True)
+class Scan:
+    directives: list[Directive] = field(default_factory=list)
+    issues: list[Issue] = field(default_factory=list)
+    # (offset, lower-cased name) of directives skipped because they broke the grammar.
+    broken: list[tuple[int, str]] = field(default_factory=list)
+
+
+class _Broken(Exception):
+    def __init__(self, message: str, offset: int, name: str = "") -> None:
+        super().__init__(message)
+        self.message = message
+        self.offset = offset
+        self.name = name
+
+
+def _skip_ows(text: str, i: int) -> int:
+    while i < len(text) and text[i] in OWS:
+        i += 1
+    return i
+
+
+def _quoted(text: str, start: int) -> tuple[str, int]:
+    """Read the quoted-string opening at ``start``; return its value and the end index."""
+    out: list[str] = []
+    i = start + 1
+    while i < len(text):
+        char = text[i]
+        if char == '"':
+            return "".join(out), i + 1
+        if char == "\\":
+            if i + 1 >= len(text):
+                break
+            if not is_pair_char(text[i + 1]):
+                raise _Broken(f"{_show(text[i + 1])} cannot follow a backslash", i + 1)
+            out.append(text[i + 1])
+            i += 2
+            continue
+        if not is_qdtext(char):
+            raise _Broken(f"{_show(char)} is not allowed in a quoted string", i)
+        out.append(char)
+        i += 1
+    raise _Broken("unterminated quoted string", start)
+
+
+def _show(char: str) -> str:
+    return f"U+{ord(char):04X}" if not char.isprintable() or not char.isascii() else repr(char)
+
+
+def _token(text: str, i: int) -> int:
+    while i < len(text) and text[i] in TCHAR:
+        i += 1
+    return i
+
+
+def _directive(text: str, i: int) -> tuple[Directive, int]:
+    start, end = i, _token(text, i)
+    if end == i:
+        raise _Broken(f"{_show(text[i])} cannot start a directive name", i)
+    name, i = text[i:end], _skip_ows(text, end)
+    try:
+        return _rest(text, i, name, start)
+    except _Broken as broken:
+        broken.name = name
+        raise
+
+
+def _rest(text: str, i: int, name: str, start: int) -> tuple[Directive, int]:
+    value: str | None = None
+    quoted = spaced = False
+    value_offset = i
+    if i < len(text) and text[i] == "=":
+        i = value_offset = _skip_ows(text, i + 1)
+        spaced = text[start + len(name)] != "=" or text[i - 1] != "="
+        if i < len(text) and text[i] == '"':
+            value, i = _quoted(text, i)
+            quoted = True
+        else:
+            end = _token(text, i)
+            if end == i:
+                found = "the end" if i == len(text) else _show(text[i])
+                raise _Broken(f"expected a value for {name}, found {found}", i)
+            value, i = text[i:end], end
+        i = _skip_ows(text, i)
+    if i < len(text) and text[i] != ";":
+        raise _Broken(f"unexpected {_show(text[i])} after {name}; directives end at ';'", i)
+    key = ascii_lower(name)
+    return Directive(name, key, value, quoted, start, value_offset, spaced), i
+
+
+def _resync(text: str, i: int) -> int:
+    """Index of the next ';' outside a quoted string, or the end of the text."""
+    while i < len(text) and text[i] != ";":
+        if text[i] == '"':
+            try:
+                i = _quoted(text, i)[1]
+                continue
+            except _Broken:
+                # A quote that never closes would swallow everything after it; give up on
+                # it and resume at the next plain semicolon instead.
+                nxt = text.find(";", i)
+                return len(text) if nxt < 0 else nxt
+        i += 1
+    return i
+
+
+def scan(text: str) -> Scan:
+    """Split ``text`` into directives, recording every syntax problem as an :class:`Issue`."""
+    result = Scan()
+    for fold in _FOLD.finditer(text):
+        message = "folded line (obsolete line folding), read as whitespace"
+        result.issues.append(Issue("obs-fold", message, "warning", fold.start()))
+        text = text[: fold.start()] + " " * len(fold.group()) + text[fold.end() :]
+    for index, char in enumerate(text):
+        if char in "\r\n\0":
+            message = f"{_show(char)} is not allowed in a field value"
+            result.issues.append(Issue("control-character", message, "error", index))
+    text = text.translate(_REPLACED)
+    if not text.strip(OWS):
+        return result
+    i = 0
+    while True:
+        start = i = _skip_ows(text, i)
+        if i == len(text) or text[i] == ";":
+            # Point at a semicolon: the one closing this empty element, or the last one.
+            where = i if i < len(text) else text.rindex(";")
+            message = "empty directive (an extra ';')"
+            result.issues.append(Issue("empty-directive", message, "warning", where))
+        else:
+            try:
+                directive, i = _directive(text, i)
+                result.directives.append(directive)
+            except _Broken as broken:
+                result.issues.append(Issue("syntax", broken.message, "error", broken.offset))
+                result.broken.append((start, ascii_lower(broken.name)))
+                i = _resync(text, start)
+        if i >= len(text):
+            return result
+        i += 1

hstsheader-0.2.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.5
+Name: hstsheader
+Version: 0.2.0
+Summary: Parse, check and build the HTTP Strict-Transport-Security header, typed and zero-dependency.
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/hstsheader
+Project-URL: Issues, https://github.com/JaviLianes8/hstsheader/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/hstsheader/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: headers,hsts,http,parser,preload,rfc6797,security,strict-transport-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hstsheader
+
+Parse, check and build the HTTP Strict-Transport-Security header, typed and zero-dependency.
+
+- Reads the header the way RFC 6797 says a user agent must, or tolerantly for logs and
+  scanners.
+- Lists every problem with a stable code and the offset where it starts.
+- Checks the hstspreload.org header requirements before you submit a domain.
+- Builds header values that cannot carry an injected line.
+- Ships a command line that checks the output of `curl -sI`.
+
+## Install
+
+```
+pip install hstsheader
+```
+
+Python 3.10 or newer, no dependencies.
+
+## Read a header
+
+```python
+from hstsheader import parse
+
+policy = parse("max-age=31536000; includeSubDomains; preload")
+print(policy)
+# Hsts(max_age=31536000, include_subdomains=True, preload=True)
+print(parse(' MAX-AGE = "600" ; unknown=1'))
+# Hsts(max_age=600, include_subdomains=False, preload=False)
+```
+
+Directive names match without regard to ASCII case, whitespace may surround `;` and `=`,
+unknown directives are ignored and `max-age` may be quoted, as RFC 6797 section 6.1
+allows. A folded line counts as whitespace. Inside a quoted string, a backslash may be
+followed by HTAB, SP, a visible ASCII character or obs-text (RFC 9110 section 5.6.4,
+stricter on purpose than the RFC 2616 rule, which allowed any ASCII character there).
+`max-age` must be ASCII digits; a value above 2147483648 (2^31, the ceiling RFC
+9111 section 1.2.2 sets for delta-seconds) is read as 2147483648.
+
+## Strict or tolerant
+
+By default `parse` is tolerant: it skips directives it cannot read, keeps the first valid
+`max-age`, and raises `HstsError` only when no valid `max-age` is left. With
+`strict=True` it accepts only a header that a user agent following RFC 6797 honours, and
+the error names the rule and the offset.
+
+```python
+from hstsheader import HstsError, parse
+
+header = "max-age=600; max-age=5; includeSubDomains"
+print(parse(header).max_age)
+# 600
+try:
+    parse(header, strict=True)
+except HstsError as error:
+    print(error.code, error.offset)
+# duplicate 13
+```
+
+Strict mode refuses a missing or non-numeric `max-age`, a directive that appears twice, a
+value on `includeSubDomains` or `preload`, anything outside the token and quoted-string
+grammar, and CR, LF or NUL. Both modes take the field lines of a response as a list and
+read only the first one, as RFC 6797 section 8.1 requires.
+
+## Lint a header
+
+```python
+from hstsheader import lint
+
+for issue in lint('max-age="031536000"; includeSubDomains=yes;'):
+    print(issue.severity, issue.code, issue.offset)
+# warning max-age.leading-zero 8
+# warning max-age.quoted 8
+# error value-not-allowed 21
+# warning empty-directive 42
+```
+
+An `error` means a user agent that follows RFC 6797 ignores the whole header. A
+`warning` marks something legal that is likely a mistake or that some checkers refuse.
+Offsets index the field value; an empty directive points at its semicolon.
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `syntax` | error | outside the directive grammar (offset of the first bad character) |
+| `control-character` | error | CR, LF or NUL in the value |
+| `max-age.missing` | error | no `max-age` directive |
+| `max-age.no-value` | error | `max-age` without `=` |
+| `max-age.not-digits` | error | the value is not ASCII digits |
+| `duplicate` | error | a directive appears more than once |
+| `value-not-allowed` | error | `includeSubDomains` or `preload` with a value |
+| `field.missing` | error | an empty list of field lines |
+| `max-age.leading-zero` | warning | the value starts with 0 |
+| `max-age.capped` | warning | the value is above 2147483648 and is read as that |
+| `max-age.quoted` | warning | valid, but hstspreload.org refuses it |
+| `max-age.spaced` | warning | space around `=` in max-age: valid, but hstspreload.org refuses it |
+| `obs-fold` | warning | a folded line, read as whitespace |
+| `max-age.zero-subdomains` | warning | `max-age=0` makes `includeSubDomains` pointless |
+| `empty-directive` | warning | an extra `;` |
+| `unknown-directive` | warning | a directive this library does not know is ignored |
+| `multiple-fields` | warning | more than one field line; only the first counts |
+
+## Check preload eligibility
+
+```python
+from hstsheader import is_preloadable, preload_issues
+
+print(is_preloadable("max-age=63072000; includeSubDomains; preload"))
+# True
+for issue in preload_issues("max-age=10886400; preload"):
+    print(issue.code)
+# preload.subdomains-missing
+# preload.max-age-too-short
+```
+
+The rules are the header requirements on hstspreload.org: `includeSubDomains` and
+`preload` present and a `max-age` of at least 31536000 seconds. The site's checker also
+refuses a quoted `max-age`, space around its `=` and a value above 2^64 - 1, treats
+`max-age=0` as a removal request and warns above ten years; the same findings come back
+as `preload.max-age-quoted`, `preload.max-age-spaced`, `preload.max-age-unreadable`,
+`preload.max-age-zero` and the warning `preload.max-age-over-ten-years`. RFC errors are
+included, except a repeated directive other than `max-age` and `includeSubDomains`, which
+the site only warns about and which comes back as a warning. The site also checks redirects, certificates and
+subdomains over the network; that part is out of scope here.
+
+## Build a header
+
+```python
+from hstsheader import Hsts, build
+
+print(build(31536000, include_subdomains=True))
+# max-age=31536000; includeSubDomains
+print(build(Hsts(600, preload=True), extensions={"report-uri": "https://example.com/r;1"}))
+# max-age=600; preload; report-uri="https://example.com/r;1"
+```
+
+Flags must be `bool`, `max_age` an `int` from 0 to 2147483648. Extension names must be
+HTTP tokens and cannot repeat or shadow the three known directives; values that are not
+tokens are quoted, and control or non-ASCII characters raise `HstsError`, so a value
+cannot smuggle a second header line. For every valid policy,
+`parse(build(policy), strict=True) == policy`.
+
+## Command line
+
+```
+$ hstsheader "max-age=600; includeSubDomains"
+$ curl -sI https://example.com | hstsheader --preload
+$ python -m hstsheader "max-age=600"
+```
+
+It prints the policy and the findings as JSON. The exit status is 0 when a user agent
+following RFC 6797 honours the header (with `--preload`: when it meets the preload
+rules), 1 when it does not, and 2 when the input has no Strict-Transport-Security field
+(empty input included). A head ends at its blank line, folded lines are joined, pasted
+fields without a status line are accepted, and with several responses (`curl -sIL`) the
+last one is checked, since that is the one the browser keeps.
+
+## Where Chromium differs
+
+This library follows RFC 6797. Chromium's parser is more lenient in two ways and stricter
+in one: it accepts a repeated directive other than `max-age` and `includeSubDomains`
+(so a repeated `preload` still works there), it does not treat `preload` as special, and
+it stores at most one year of `max-age` whatever the header says.
+
+## API
+
+| Name | What it is |
+| --- | --- |
+| `parse(header, *, strict=False)` | read a value or a list of field lines into an `Hsts` |
+| `lint(header)` | every finding as a tuple of `Issue` |
+| `preload_issues(header)` | findings against the hstspreload.org rules (value or `Hsts`) |
+| `is_preloadable(header)` | `True` when `preload_issues` has no error |
+| `build(max_age, *, include_subdomains, preload, extensions)` | write a header value |
+| `Hsts` | frozen dataclass: `max_age`, `include_subdomains`, `preload`, checked on creation |
+| `Issue` | frozen dataclass: `code`, `message`, `severity`, `offset` |
+| `HstsError` | a `ValueError` with `code` and `offset` |
+| `DELTA_SECONDS_MAX` | 2147483648, the ceiling for `max-age` |
+| `PRELOAD_MIN_MAX_AGE` | 31536000, the shortest `max-age` the preload list takes |
+
+## Sources
+
+RFC 6797 (the header and the browser processing model), RFC 2616 (the grammar it builds
+on), RFC 9110 (token, quoted-string, field values), RFC 9111 (delta-seconds), the
+hstspreload.org requirements and its header checker, and Chromium's header parser. The
+tests check the library against copies of these files; `python scripts/fetch_upstream.py`
+fetches them and `tests/upstream/MANIFEST.json` pins each one by URL, revision and sha256.
+Those tests skip until the files are fetched.
+
+## Why
+
+RFC 6797 defines a tiny header, yet Python has no standalone, typed, zero-dependency
+codec for it. The existing options are all tied to something larger: `apifrom` buries
+the logic in a framework utility, `pyramid_hsts` only writes the header, and
+PyGObject's `Soup.HSTSPolicy` pulls in the libsoup and GObject stack. This library is a
+single-purpose reader, checker and writer with full type hints and nothing to install
+alongside it.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

hstsheader-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+hstsheader/__init__.py,sha256=HqzzFBjlIqTeW-ES21kEnw386B8JJBH46cTFSk085ls,562
+hstsheader/__main__.py,sha256=5LX8XY5PKQ3VeZZc5B1WtmsTbJlRtdJRE6wSiFr_71Y,128
+hstsheader/_build.py,sha256=67sJ7f01LueQGcxv1TRVMh6xdiocMP4v43iDiKXCdYE,3212
+hstsheader/_chars.py,sha256=BoUp1f4w72cKDFYWVgme7dzulKiEBsrlRklpZPlFF7A,1512
+hstsheader/_cli.py,sha256=DKDJRHOyGVc1EIuZ08ECu3X6WMPOOBTlMIV_YowahZc,3050
+hstsheader/_head.py,sha256=unLwjGSyfW9hSV6M2iLIkpNGAb6vpwg-52zH6tM9ih8,2094
+hstsheader/_lint.py,sha256=PGIF7br11PIm9owHLfLVffmroO9QUK95CBaf00NXOns,7290
+hstsheader/_model.py,sha256=zQNBoUuFnG0ZMr4_VeF8HbF-_VHzLbCnv2AIJ-JGdk0,2793
+hstsheader/_parse.py,sha256=jddOmywRhh-miRob0xF99uttQiuZvScQgz71OMooGKc,1732
+hstsheader/_preload.py,sha256=ibdbrfPlByQ6G2JOVDvtMJLGOo7rhTcOjX6rFMYsw6g,3547
+hstsheader/_scan.py,sha256=JF6FJlGfhB5dhxOn0ZD4jvS7ylzMpEh6b0Q3T602-3c,6693
+hstsheader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hstsheader-0.2.0.dist-info/METADATA,sha256=jS31jUbpuRc44dfmyK-MwwseJoMsEz5_fft96PMJNS4,10480
+hstsheader-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+hstsheader-0.2.0.dist-info/entry_points.txt,sha256=aFYACtPg_V9h7d05UkP-zqYns4b9yIW65LHilkJjK3c,52
+hstsheader-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+hstsheader-0.2.0.dist-info/RECORD,,

hstsheader-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

hstsheader-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hstsheader = hstsheader._cli:main

hstsheader-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.