jev-secrets 1.0.0__py3-none-any.whl

jev_secrets/__init__.py

@@ -0,0 +1,18 @@
+"""Pseudonymises names, keys and other secrets in Jev queries before they are sent, and restores them in the answers."""
+
+from ._config import Config
+from ._pseudonymiser import Pseudonymised
+from ._secrets import Secrets
+from ._vault import Vault
+from .errors import CollisionError, ConfigError, LeakError, SecretsError
+
+__all__ = [
+    'CollisionError',
+    'Config',
+    'ConfigError',
+    'LeakError',
+    'Pseudonymised',
+    'Secrets',
+    'SecretsError',
+    'Vault',
+]

jev_secrets/_catalogue.py

@@ -0,0 +1,44 @@
+"""
+The data files in catalogue/, which the PHP, JavaScript and Python implementations all read.
+
+A wheel carries them inside the package; a clone has them at the repository root.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from pathlib import Path
+from typing import Any
+
+
+def directory() -> Path:
+    here = Path(__file__).resolve().parent
+    bundled = here / 'catalogue'
+
+    return bundled if bundled.is_dir() else here.parents[2] / 'catalogue'
+
+
+@cache
+def _load(name: str) -> dict[str, Any]:
+    path = directory() / name
+
+    try:
+        data = json.loads(path.read_text(encoding='utf-8'))
+    except OSError as error:
+        raise RuntimeError(f'Cannot read {path}.') from error
+    except json.JSONDecodeError as error:
+        raise RuntimeError(f'{path} is not valid JSON: {error}') from error
+
+    if not isinstance(data, dict):
+        raise RuntimeError(f'{path} does not hold an object.')
+
+    return data
+
+
+def patterns() -> dict[str, Any]:
+    return _load('patterns.json')
+
+
+def alphabets() -> dict[str, Any]:
+    return _load('alphabets.json')

jev_secrets/_config.py

@@ -0,0 +1,290 @@
+"""
+What to pseudonymise and how. spec/config.schema.json describes the same shape, which the PHP
+and JavaScript implementations also accept, refusing the same mistakes with the same messages.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from . import _catalogue
+from ._detection import Pattern
+from ._text import has_word_char, nfc, trim
+from .errors import ConfigError
+
+OPTIONS = (
+    'terms', 'patterns', 'fields', 'allow', 'defaults', 'disable', 'secretKeys', 'scope',
+    'letters', 'digits', 'dates', 'minLength', 'key',
+)
+DEFAULTS: dict[str, Any] = {'defaults': True, 'secretKeys': True, 'letters': 'shape', 'digits': 'lower', 'minLength': 2}
+SCOPE_DEFAULTS = {'state': True, 'questions': True, 'keys': False}
+DATES_DEFAULTS: dict[str, Any] = {'mode': 'shift', 'order': 'dmy', 'detect': False}
+
+KEY_ENV = 'JEV_SECRETS_KEY'
+"""The environment variable read for the key when the config names none."""
+
+# Options whose object value an override merges into, one entry at a time, instead of replacing.
+_NESTED = ('scope', 'dates')
+
+
+@dataclass(frozen=True)
+class Config:
+    terms: list[str]
+    patterns: list[Pattern]
+    defaults: list[Pattern]
+    fields: list[list[str]]
+    allow: list[str]
+    secret_keys: frozenset[str]
+    scope_state: bool
+    scope_questions: bool
+    scope_keys: bool
+    letters: str
+    digits: str
+    dates_mode: str
+    dates_order: str
+    dates_detect: bool
+    min_length: int
+    key_setting: str | Literal[False] | None
+    """A key, False for a random key every call, or None to read KEY_ENV."""
+    raw: Mapping[str, Any] = field(repr=False)
+    """The options as given, which with_() merges overrides into."""
+
+    def with_(self, overrides: Mapping[str, Any] | None) -> Config:
+        """This config with some options replaced for one call. `scope` and `dates` merge entry
+        by entry; every other option given replaces the configured one."""
+        if not overrides:
+            return self
+
+        merged = dict(self.raw)
+
+        for name, value in overrides.items():
+            if name in _NESTED and isinstance(value, Mapping) and isinstance(merged.get(name), Mapping):
+                merged[name] = {**merged[name], **value}
+            else:
+                merged[name] = value
+
+        return Config.from_mapping(merged)
+
+    def key(self) -> str | None:
+        """The key for a call: the configured one, or the environment's when none is configured,
+        or None for a random one. Read on every call, so a rotated environment key takes effect
+        without rebuilding the config."""
+        if isinstance(self.key_setting, str):
+            return self.key_setting
+
+        if self.key_setting is False:
+            return None
+
+        return os.environ.get(KEY_ENV) or None
+
+    @classmethod
+    def from_mapping(cls, config: Mapping[str, Any]) -> Config:
+        raw = dict(config)
+
+        for name in config:
+            if name not in OPTIONS:
+                raise ConfigError(f'Unknown config option "{name}". Known options: {", ".join(OPTIONS)}.')
+
+        config = {**DEFAULTS, **config}
+
+        if not isinstance(config['defaults'], bool):
+            raise ConfigError('defaults must be true or false.')
+
+        min_length = config['minLength']
+
+        if not isinstance(min_length, int) or isinstance(min_length, bool) or min_length < 1:
+            raise ConfigError('minLength must be a positive integer.')
+
+        letters, digits = config['letters'], config['digits']
+
+        if letters not in ('shape', 'strict'):
+            raise ConfigError('letters must be "shape" or "strict".')
+
+        if digits not in ('lower', 'any'):
+            raise ConfigError('digits must be "lower" or "any".')
+
+        key = config.get('key')
+
+        if key is not None and key is not False and (not isinstance(key, str) or key == ''):
+            raise ConfigError('key must be a non-empty string, or false for a random key on every call.')
+
+        dates = {**DATES_DEFAULTS, **_map(config, 'dates')}
+
+        for name in dates:
+            if name not in DATES_DEFAULTS:
+                raise ConfigError(f'Unknown dates option "{name}". Known options: mode, order, detect.')
+
+        if dates['mode'] not in ('shift', 'digits'):
+            raise ConfigError('dates.mode must be "shift" or "digits".')
+
+        if dates['order'] not in ('dmy', 'mdy'):
+            raise ConfigError('dates.order must be "dmy" or "mdy".')
+
+        if not isinstance(dates['detect'], bool):
+            raise ConfigError('dates.detect must be true or false.')
+
+        scope = _map(config, 'scope')
+
+        for name in scope:
+            if name not in SCOPE_DEFAULTS:
+                raise ConfigError(f'Unknown scope "{name}". Known scopes: state, questions, keys.')
+
+        catalogue = _catalogue.patterns()
+        disable = _strings(config, 'disable')
+        ids = [entry['id'] for entry in catalogue['patterns']]
+
+        for pattern_id in disable:
+            if pattern_id not in ids:
+                raise ConfigError(
+                    f'disable names "{pattern_id}", which is not a default pattern. Default patterns: {", ".join(ids)}.'
+                )
+
+        defaults = [
+            Pattern(entry['id'], entry['pattern'], entry.get('flags', ''), entry.get('validator'))
+            for entry in catalogue['patterns']
+            if config['defaults'] and entry['id'] not in disable
+        ]
+
+        patterns = []
+
+        for i, entry in enumerate(_list(config, 'patterns')):
+            if not isinstance(entry, Mapping) or not isinstance(entry.get('pattern'), str):
+                raise ConfigError(f'patterns[{i}] must be an object with a string "pattern".')
+
+            flags = entry.get('flags') if entry.get('flags') is not None else ''
+            validator = entry.get('validator')
+            pattern_id = entry.get('id') if entry.get('id') is not None else f'patterns[{i}]'
+
+            valid = isinstance(flags, str) and isinstance(pattern_id, str) and isinstance(validator, (str, type(None)))
+
+            if not valid:
+                raise ConfigError(f'patterns[{i}] has an id, flags or validator that is not a string.')
+
+            patterns.append(Pattern(pattern_id, entry['pattern'], flags, validator))
+
+        secret_keys = _secret_keys(config['secretKeys'], catalogue['secretKeys'])
+
+        return cls(
+            terms=normalise_values(_strings(config, 'terms'), 'terms', min_length),
+            patterns=patterns,
+            defaults=defaults,
+            fields=[_path(p) for p in _strings(config, 'fields')],
+            allow=[s for s in (trim(nfc(s)) for s in _strings(config, 'allow')) if s != ''],
+            secret_keys=secret_keys,
+            scope_state=_flag(scope, 'state'),
+            scope_questions=_flag(scope, 'questions'),
+            scope_keys=_flag(scope, 'keys'),
+            letters=letters,
+            digits=digits,
+            dates_mode=dates['mode'],
+            dates_order=dates['order'],
+            dates_detect=dates['detect'],
+            min_length=min_length,
+            key_setting=key,
+            raw=raw,
+        )
+
+
+def _secret_keys(setting: Any, catalogue: list[str]) -> frozenset[str]:
+    """True for the catalogue's names, False for none, a list for exactly those names, or
+    {add, remove} to change the catalogue's list."""
+    if setting is True:
+        names = catalogue
+    elif setting is False:
+        names = []
+    elif isinstance(setting, (list, tuple)):
+        names = _strings({'secretKeys': setting}, 'secretKeys')
+    elif isinstance(setting, Mapping) and set(setting) <= {'add', 'remove'}:
+        remove = [normalise_key(name) for name in _strings(setting, 'remove')]
+        names = [name for name in [*catalogue, *map(normalise_key, _strings(setting, 'add'))] if name not in remove]
+    else:
+        raise ConfigError(
+            'secretKeys must be true, false, a list of key names, or an object with add and remove lists.'
+        )
+
+    return frozenset(normalise_key(name) for name in names)
+
+
+def normalise_values(values: Sequence[str], name: str, min_length: int) -> list[str]:
+    """Normalises values passed to a call or listed as terms, and rejects the ones that cannot
+    be matched safely."""
+    out: list[str] = []
+
+    for i, value in enumerate(values):
+        if not isinstance(value, str):
+            raise ConfigError(f'{name}[{i}] must be a string.')
+
+        value = trim(nfc(value))
+
+        if not has_word_char(value):
+            raise ConfigError(f'{name}[{i}] has no letter or digit, so there is nothing to match or replace.')
+
+        if len(value) < min_length:
+            raise ConfigError(f'{name}[{i}] is shorter than minLength ({min_length}). Lower minLength to allow it.')
+
+        if value not in out:
+            out.append(value)
+
+    return out
+
+
+def normalise_key(key: str) -> str:
+    """Normalises a key the way the catalogue's secretKeys are written: lowercase, with spaces,
+    hyphens and underscores removed."""
+    return key.lower().replace(' ', '').replace('-', '').replace('_', '')
+
+
+def _path(path: str) -> list[str]:
+    segments = path.split('.')
+
+    if path == '' or '' in segments or segments[0] not in ('state', 'questions', '*'):
+        raise ConfigError(f'The field path "{path}" must start with state or questions and have no empty segments.')
+
+    return segments
+
+
+def _strings(config: Mapping[str, Any], name: str) -> list[str]:
+    items = _list(config, name)
+
+    for i, item in enumerate(items):
+        if not isinstance(item, str):
+            raise ConfigError(f'{name}[{i}] must be a string.')
+
+    return items
+
+
+def _list(config: Mapping[str, Any], name: str) -> list[Any]:
+    value = config.get(name)
+
+    if value is None:
+        return []
+
+    if not isinstance(value, (list, tuple)):
+        raise ConfigError(f'{name} must be a list.')
+
+    return list(value)
+
+
+def _map(config: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    value = config.get(name)
+
+    if value is None or value == []:
+        return {}
+
+    if not isinstance(value, Mapping):
+        raise ConfigError(f'{name} must be an object.')
+
+    return value
+
+
+def _flag(scope: Mapping[str, Any], name: str) -> bool:
+    value = scope.get(name)
+    value = SCOPE_DEFAULTS[name] if value is None else value
+
+    if not isinstance(value, bool):
+        raise ConfigError(f'scope.{name} must be true or false.')
+
+    return value

jev_secrets/_dates.py

@@ -0,0 +1,333 @@
+"""
+Dates, times and datetimes: finding them in text and moving every one in a request by the
+same offset, so their order and the intervals between them survive.
+
+Dates move by a whole number of weeks, so a weekday written beside a date stays right. Times
+move by a number of minutes chosen so no time in the request crosses midnight, and the move
+never carries into the date, so a date written alone and the same date in a datetime stay
+equal. docs/dates.md lists the formats.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ._generation import ATTEMPTS, Stream
+
+MONTHS = (
+    'january', 'february', 'march', 'april', 'may', 'june',
+    'july', 'august', 'september', 'october', 'november', 'december',
+)
+ABBREVIATIONS = ('jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec')
+
+WEEKS = 52
+"""Weeks a date can move, either way."""
+
+_BEFORE = '(?<![0-9A-Za-z])'
+_AFTER = '(?![0-9A-Za-z])'
+_MONTH_NAMES = (
+    'january|february|march|april|may|june|july|august|september|october|november|december'
+    '|sept|jan|feb|mar|apr|jun|jul|aug|sep|oct|nov|dec'
+)
+_TIME = (
+    r'(?P<h>[0-9]{1,2}):(?P<mi>[0-9]{2})(?::(?P<sec>[0-9]{2})(?P<frac>\.[0-9]{1,9})?)?'
+    r'(?:(?P<aps> ?)(?P<ap>[AaPp]\.?[Mm]\.?))?'
+)
+_DATES = {
+    'ymd': r'(?P<y>[0-9]{4})(?P<s1>[-/.])(?P<m>[0-9]{1,2})(?P=s1)(?P<d>[0-9]{1,2})',
+    'numeric': r'(?P<a>[0-9]{1,2})(?P<s1>[-/.])(?P<b>[0-9]{1,2})(?P=s1)(?P<y>[0-9]{4}|[0-9]{2})',
+    'day-month': (
+        r'(?P<d>[0-9]{1,2})(?P<o>st|nd|rd|th|ST|ND|RD|TH)?(?P<s1> +|-)(?P<mon>(?i:' + _MONTH_NAMES + r'))'
+        r'(?P<dot>\.)?(?P<s2>,? +|-)(?P<y>[0-9]{4})'
+    ),
+    'month-day': (
+        r'(?P<mon>(?i:' + _MONTH_NAMES + r'))(?P<dot>\.)?(?P<s1> +)(?P<d>[0-9]{1,2})'
+        r'(?P<o>st|nd|rd|th|ST|ND|RD|TH)?(?P<s2>,? +)(?P<y>[0-9]{4})'
+    ),
+}
+_DATE_REGEXES = {
+    name: re.compile(
+        _BEFORE + date + r'(?:(?P<j>T| |, | at )' + _TIME + r'(?P<tz>Z|[+-][0-9]{2}:?[0-9]{2})?)?' + _AFTER
+    )
+    for name, date in _DATES.items()
+}
+_TIME_REGEX = re.compile(_BEFORE + _TIME + _AFTER)
+
+
+def _intdiv(a: int, b: int) -> int:
+    """PHP's intdiv, which truncates toward zero where // floors."""
+    quotient = abs(a) // abs(b)
+    return quotient if (a >= 0) == (b > 0) else -quotient
+
+
+def to_days(year: int, month: int, day: int) -> int:
+    """Days from 1970-01-01 in the proleptic Gregorian calendar, by Howard Hinnant's days_from_civil."""
+    y = year - 1 if month <= 2 else year
+    era = _intdiv(y if y >= 0 else y - 399, 400)
+    yoe = y - era * 400
+    doy = _intdiv(153 * (month + (-3 if month > 2 else 9)) + 2, 5) + day - 1
+    doe = yoe * 365 + _intdiv(yoe, 4) - _intdiv(yoe, 100) + doy
+
+    return era * 146097 + doe - 719468
+
+
+def from_days(days: int) -> tuple[int, int, int]:
+    """Year, month and day, by Howard Hinnant's civil_from_days."""
+    z = days + 719468
+    era = _intdiv(z if z >= 0 else z - 146096, 146097)
+    doe = z - era * 146097
+    yoe = _intdiv(doe - _intdiv(doe, 1460) + _intdiv(doe, 36524) - _intdiv(doe, 146096), 365)
+    doy = doe - (365 * yoe + _intdiv(yoe, 4) - _intdiv(yoe, 100))
+    mp = _intdiv(5 * doy + 2, 153)
+    day = doy - _intdiv(153 * mp + 2, 5) + 1
+    month = mp + 3 if mp < 10 else mp - 9
+
+    return yoe + era * 400 + (1 if month <= 2 else 0), month, day
+
+
+def days_in_month(year: int, month: int) -> int:
+    if month == 2:
+        return 29 if (year % 4 == 0 and year % 100 != 0) or year % 400 == 0 else 28
+
+    return 30 if month in (4, 6, 9, 11) else 31
+
+
+class Shifter:
+    def __init__(self, order: str) -> None:
+        """`order` is how a numeric date with the year last is read: `dmy` or `mdy`."""
+        self._order = order
+        self._days = 0
+        self._minutes = 0
+        self._original_days: set[int] = set()
+        self._original_minutes: set[int] = set()
+
+    def find(self, text: str) -> list[dict[str, Any]]:
+        """Every date, time and datetime in the text, longest first where two overlap."""
+        found: list[dict[str, Any]] = []
+
+        for fmt, regex in (*_DATE_REGEXES.items(), ('time', _TIME_REGEX)):
+            for m in regex.finditer(text):
+                match = {name: value for name, value in m.groupdict().items() if value is not None}
+                parsed = self._parse(fmt, match)
+
+                if parsed is not None:
+                    found.append({'start': m.start(), 'end': m.end(), 'match': match, 'format': fmt, **parsed})
+
+        found.sort(key=lambda f: (-(f['end'] - f['start']), f['start']))
+        kept: list[dict[str, Any]] = []
+
+        for candidate in found:
+            if not any(candidate['start'] < taken['end'] and taken['start'] < candidate['end'] for taken in kept):
+                kept.append(candidate)
+
+        return sorted(kept, key=lambda f: f['start'])
+
+    def prepare(self, key: bytes, texts: list[str]) -> None:
+        """
+        Picks this request's offsets from every date and time it holds.
+
+        The minute offset keeps every time between 00:00 and 23:59. Offsets are drawn again, up
+        to ATTEMPTS times, until no moved date or time equals one already in the request; after
+        that the draw with the fewest such collisions is kept, and shift() returns None for a
+        colliding value, which the caller leaves to the character generator.
+        """
+        # Sets suffice: only membership and the earliest and latest minute are read.
+        for text in texts:
+            for found in self.find(text):
+                if found['day'] is not None:
+                    self._original_days.add(found['day'])
+
+                if found['minute'] is not None:
+                    self._original_minutes.add(found['minute'])
+
+        low = -min(self._original_minutes) if self._original_minutes else 0
+        high = 1439 - max(self._original_minutes) if self._original_minutes else 0
+        best: tuple[int, int, int] | None = None
+
+        for attempt in range(ATTEMPTS):
+            stream = Stream(key, f'jev-secrets/v1\0dates\0{attempt}'.encode())
+            week = stream.below(2 * WEEKS)
+            days = 7 * (week - WEEKS if week < WEEKS else week - WEEKS + 1)
+            minutes = 0
+
+            if high - low >= 1:
+                minutes = low + stream.below(high - low)
+                minutes += 1 if minutes >= 0 else 0
+
+            collisions = sum(1 for day in self._original_days if day + days in self._original_days)
+
+            if minutes != 0:
+                collisions += sum(1 for minute in self._original_minutes if minute + minutes in self._original_minutes)
+
+            if best is None or collisions < best[0]:
+                best = (collisions, days, minutes)
+
+            if collisions == 0:
+                break
+
+        assert best is not None
+        _, self._days, self._minutes = best
+
+    def shift(self, found: dict[str, Any]) -> str | None:
+        """The moved text of a match from find(), or None when it cannot move: its time would
+        leave the day, or it would land on a date or time already in the request."""
+        m = found['match']
+        out = ''
+
+        if found['day'] is not None:
+            day = found['day'] + self._days
+
+            if day in self._original_days:
+                return None
+
+            out = self._format_date(found['format'], m, *from_days(day))
+
+        if found['minute'] is not None:
+            minute = found['minute'] + self._minutes
+
+            if minute < 0 or minute > 1439 or (self._minutes != 0 and minute in self._original_minutes):
+                return None
+
+            out += m.get('j', '') + _format_time(m, minute) + m.get('tz', '')
+
+        return out
+
+    def _parse(self, fmt: str, m: dict[str, str]) -> dict[str, int | None] | None:
+        minute = None
+
+        if 'h' in m:
+            minute = _minute(m)
+
+            if minute is None:
+                return None
+
+        if fmt == 'time':
+            return {'day': None, 'minute': minute}
+
+        year = int(m['y'])
+
+        if len(m['y']) == 2:
+            year += 2000 if year < 70 else 1900
+
+        if fmt == 'numeric':
+            month, day = (int(m['b']), int(m['a'])) if self._order == 'dmy' else (int(m['a']), int(m['b']))
+        elif fmt in ('day-month', 'month-day'):
+            month, day = _month_number(m['mon']), int(m['d'])
+        else:
+            month, day = int(m['m']), int(m['d'])
+
+        if month < 1 or month > 12 or day < 1 or day > days_in_month(year, month):
+            return None
+
+        return {'day': to_days(year, month, day), 'minute': minute}
+
+    def _format_date(self, fmt: str, m: dict[str, str], year: int, month: int, day: int) -> str:
+        def pad(value: int, like: str) -> str:
+            return f'{value:02d}' if len(like) >= 2 else str(value)
+
+        y = f'{year % 100:02d}' if len(m['y']) == 2 else _php_04d(year)
+
+        if fmt == 'ymd':
+            return y + m['s1'] + pad(month, m['m']) + m['s1'] + pad(day, m['d'])
+
+        if fmt == 'numeric':
+            if self._order == 'dmy':
+                return pad(day, m['a']) + m['s1'] + pad(month, m['b']) + m['s1'] + y
+
+            return pad(month, m['a']) + m['s1'] + pad(day, m['b']) + m['s1'] + y
+
+        if fmt == 'day-month':
+            return (
+                pad(day, m['d']) + _ordinal(day, m.get('o')) + m['s1'] + _month_name(month, m['mon'])
+                + m.get('dot', '') + m['s2'] + y
+            )
+
+        return (
+            _month_name(month, m['mon']) + m.get('dot', '') + m['s1'] + pad(day, m['d'])
+            + _ordinal(day, m.get('o')) + m['s2'] + y
+        )
+
+
+def _php_04d(value: int) -> str:
+    """sprintf('%04d') as PHP writes it: a negative year pads to four characters including the sign."""
+    return f'{value:04d}' if value >= 0 else '-' + f'{-value:03d}'
+
+
+def _minute(m: dict[str, str]) -> int | None:
+    hour = int(m['h'])
+    minute = int(m['mi'])
+
+    if minute > 59 or ('sec' in m and int(m['sec']) > 59):
+        return None
+
+    if 'ap' in m:
+        if hour < 1 or hour > 12:
+            return None
+
+        hour = hour % 12 + (12 if m['ap'][0].lower() == 'p' else 0)
+    elif hour > 23:
+        return None
+
+    return hour * 60 + minute
+
+
+def _format_time(m: dict[str, str], minute: int) -> str:
+    hour = minute // 60
+    out = f'{minute % 60:02d}'
+
+    if 'sec' in m:
+        out += ':' + m['sec'] + m.get('frac', '')
+
+    if 'ap' in m:
+        twelve = 12 if hour % 12 == 0 else hour % 12
+        letter = 'a' if hour < 12 else 'p'
+        ap = (letter.upper() if m['ap'][0].isupper() else letter) + m['ap'][1:]
+        hours = f'{twelve:02d}' if len(m['h']) >= 2 else str(twelve)
+
+        return hours + ':' + out + m.get('aps', '') + ap
+
+    return (f'{hour:02d}' if len(m['h']) >= 2 else str(hour)) + ':' + out
+
+
+def _month_number(name: str) -> int:
+    lower = name.lower()
+    lower = 'sep' if lower == 'sept' else lower
+
+    if lower in ABBREVIATIONS:
+        return ABBREVIATIONS.index(lower) + 1
+
+    return MONTHS.index(lower) + 1 if lower in MONTHS else 0
+
+
+def _month_name(month: int, like: str) -> str:
+    """The month's name written the way the original was: full or abbreviated, and in the same
+    case. "Sept" stays four letters when the month lands on September."""
+    lower = like.lower()
+    full = lower in MONTHS and lower not in ABBREVIATIONS
+
+    # "May" is both a full name and an abbreviation; a date written with it gets the moved
+    # month's full name.
+    if full or lower == 'may':
+        name = MONTHS[month - 1]
+    elif lower == 'sept' and month == 9:
+        name = 'sept'
+    else:
+        name = ABBREVIATIONS[month - 1]
+
+    if like.upper() == like:
+        return name.upper()
+
+    if lower[:1].upper() + lower[1:] == like:
+        return name[:1].upper() + name[1:]
+
+    return name
+
+
+def _ordinal(day: int, like: str | None) -> str:
+    if like is None:
+        return ''
+
+    suffix = 'th' if 11 <= day % 100 <= 13 else {1: 'st', 2: 'nd', 3: 'rd'}.get(day % 10, 'th')
+
+    return suffix.upper() if like.isupper() else suffix