queryapigate 0.5.0__py3-none-any.whl

queryapigate/__init__.py

@@ -0,0 +1,6 @@
+"""QueryAPIGate - expose SQL databases as a REST API."""
+__version__ = '0.5.0'
+
+from .app import create_app  # noqa: E402  (app imports __version__)
+
+__all__ = ['create_app', '__version__']

queryapigate/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

queryapigate/apikeys.py

@@ -0,0 +1,535 @@
+"""Per-key API permissions, layered on top of ``QUERYAPIGATE_API_KEY``.
+
+``QUERYAPIGATE_API_KEY`` (if set) stays a full-access, unrestricted admin key, unchanged from before this
+module existed. Scoped keys are additive: each is limited to a list of connection names (or every
+connection) and can be denied write access even when the server otherwise allows it. Only the admin key can
+create, change or delete a scoped key, list connections, or manage saved queries - a scoped key can only
+run queries against the connections it was granted.
+
+A key also gets an independent ``queries`` grant: a list of saved-query names it may run regardless of
+``connections`` - so an external-client key can be scoped to exactly ``monthly_revenue`` and nothing else,
+with no connection access of its own at all, while an internal key keeps the coarser connection-level grant
+unchanged. The two are additive, not nested: a saved query listed by name is runnable whether or not its
+connection is also in ``connections``, and being granted a connection still allows *every* saved query on
+it as before - ``queries`` only ever adds reach, on top of what ``connections`` already grants, never
+narrows it. A ``queries`` grant covers only that named saved query, never ad-hoc SQL (``POST
+/execute_sql``) against whatever connection sits behind it - a key with no ``connections`` grant of its own
+still cannot run arbitrary SQL, only the specific queries it was named for. See ``can_use_query()`` and
+``app.run_saved()``.
+
+A key's *secret* is never stored - only its SHA-256 hash, in ``api_keys.json`` (``QUERYAPIGATE_HOME``). The
+plaintext value is generated by the server and returned exactly once, when the key is created; there is no
+way to recover it afterwards, only to revoke it (``DELETE``) and create a new one.
+
+A key can also carry an ``expires_at`` date (YYYY-MM-DD, day granularity - see ``_validate_expiry()``), for
+time-boxed access (a trial integration, a partner engagement with a known end date) that expires on its own
+without anyone having to remember to come back and revoke it. Checked live on every ``authenticate()`` call
+- see ``is_expired()`` - not swept by a background job, so there is nothing to schedule or fail silently.
+
+Every successful ``authenticate()`` match also records ``last_used_at`` on the key's stored entry, so an
+admin can tell a stale key that has never actually been called apart from one that just hasn't been used
+today - visibility, not a permission of its own. Throttled to once per ``_USE_RECORD_INTERVAL`` (see
+``_record_use()``) rather than written on every single request, which for a busy key would turn every API
+call into a disk write for no benefit - "was this key used in roughly the last minute" answers the actual
+question ("is this key still alive") just as well as an exact timestamp would.
+
+A key can also carry its own ``rate_limit`` (the same ``N/period`` grammar as ``QUERYAPIGATE_RATE_LIMIT`` - see
+``config.parse_rate_limit()``), checked *in addition to* the server-wide, IP-based limit, never instead of
+it - a per-key limit narrows what one caller may do, it is never a way to escape the ceiling every caller
+already sits under. Unset means "no limit of this key's own, just the server-wide one" - the server-wide
+limit being off does not imply a per-key one is pointless, since throttling one specific external caller is
+a reasonable ask on its own. See ``app.check_key_rate_limit()`` and ``ratelimit.KeyRateLimiters``.
+
+A key can also be pinned to an ``allowed_ips`` list of IP addresses or CIDR ranges (IPv4 or IPv6, mixed
+freely) - real defense in depth for a key handed to an external party with known, stable infrastructure,
+since even a leaked key then only authenticates from an expected address. Checked in ``authenticate()``
+against the same client address ``QUERYAPIGATE_TRUST_PROXY``/``ProxyFix`` already establish as trustworthy for
+rate limiting (see ``app.resolve_permission()``), not re-derived here. Unset (``None``) means no
+restriction - today's behaviour, unchanged. This is about *who* may use a key at all, independent of
+``rate_limit`` (#15, how much a caller who is allowed may do).
+
+A key with write access can also be narrowed to specific ``allowed_write_ops`` - a list of SQL statement
+keywords (``insert``, ``update``, ``delete``, ...) it may actually perform, rather than "any write" once
+``allow_writes`` is on. Unset (``None``, the default) keeps today's behaviour: every write keyword equally
+permitted. Checked in ``sqltools.validate_sql()`` alongside the existing read-only check - a read-only
+statement is always allowed regardless of this list, since it only ever narrows *write* access, never reach
+that already didn't exist. See ``engine.execute_sql()``.
+
+A named **role** (``create_role()``/``update_role()``/``delete_role()``, stored separately in
+``roles.json``) is a reusable *template* for the grant fields above (``connections``, ``allow_writes``,
+``queries``, ``rate_limit``, ``allowed_ips``, ``allowed_write_ops``) - not a fourth kind of permission
+object a key references at authentication time. ``create_key(..., role="reporting")`` copies that role's
+fields onto the new key once, at creation; the key's own stored entry is the source of truth for every
+authenticate() call from then on, exactly as if an admin had typed the same fields directly. Editing or
+deleting a role afterward never touches a key already created from it - deliberately, so a role change
+never has a blast radius across keys an admin cannot see without checking each one. A key still records
+which role (if any) it was created from, in ``created_from_role`` - purely informational, never consulted
+by ``authenticate()`` or any permission check. Combining ``role`` with an explicit grant field in the same
+``create_key()`` call is rejected: create from the role, then ``update_key()`` afterward to customize.
+"""
+import hashlib
+import hmac
+import ipaddress
+import json
+import re
+import secrets
+import time
+from collections import namedtuple
+from datetime import datetime
+
+from . import config, store
+from .errors import ApiError
+
+ALL_CONNECTIONS = '*'
+ALL_QUERIES = '*'
+_NAME_RE = re.compile(r'^[\w .\-]{1,100}$')
+_DATE_RE = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+_UNSET = object()  # distinguishes "not passed to update_key()" from an explicit expires_at=None (clear it)
+_USE_RECORD_INTERVAL = 60.0  # seconds between last_used_at writes for the same key - see _record_use()
+_last_recorded_use: dict[str, float] = {}  # key name -> time.monotonic() of the last last_used_at write
+
+Permission = namedtuple('Permission', ['name', 'admin', 'connections', 'allow_writes', 'queries', 'rate_limit',
+                                       'allowed_write_ops'])
+
+# The unrestricted caller used when the server has no key configured at all (QUERYAPIGATE_API_KEY unset and no
+# scoped keys stored) - today's "open by design" behaviour, unchanged by this module. Its name is None (there
+# is no key to name), unlike the admin key match below, which is named 'admin' so logs and /metrics can tell
+# "no auth configured" apart from "authenticated as the admin key".
+OPEN = Permission(name=None, admin=True, connections=ALL_CONNECTIONS, allow_writes=True, queries=ALL_QUERIES,
+                  rate_limit=None, allowed_write_ops=None)
+
+
+def can_use(permission, connection_name):
+    return permission.admin or permission.connections == ALL_CONNECTIONS or connection_name in permission.connections
+
+
+def can_use_query(permission, query_name):
+    """Whether ``permission`` may run the saved query named ``query_name`` by virtue of its own ``queries``
+    grant specifically - independent of (and additive with) whatever ``connections`` already allows; see
+    the module docstring. A caller should still fall back to ``can_use()`` against the query's actual
+    connection when this returns False, exactly as for a query with no ``queries`` grant at all."""
+    return permission.admin or permission.queries == ALL_QUERIES or query_name in permission.queries
+
+
+def can_write_query(permission, query_name):
+    """Whether ``permission``'s own ``queries`` grant specifically allows a *write* through ``query_name`` -
+    independent of (and additive with) ``allow_writes``/``connections``, the same way ``can_use_query()``
+    already is for read reach. Never true for the ``"*"`` wildcard, by design (see ``_normalize_queries()``):
+    a write grant must always be spelled out for the specific query it covers, never implied by a broader
+    read-access wildcard picked for unrelated reasons. A caller still has to OR this with the key's own
+    ``allow_writes`` - this only ever adds reach for one named query, it never takes away the blanket grant
+    a key might already have."""
+    if permission.admin:
+        return True
+    if permission.queries == ALL_QUERIES:
+        return False
+    return bool(permission.queries.get(query_name))
+
+
+def _hash(secret):
+    return hashlib.sha256(secret.encode('utf-8')).hexdigest()
+
+
+def _read():
+    try:
+        with open(config.api_keys_file(), 'r') as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return {}
+    return data.get('keys', {})
+
+
+def _write(keys):
+    config.home().mkdir(parents=True, exist_ok=True)
+    store.write_json_atomic(config.api_keys_file(), {'keys': keys})
+
+
+def _normalize_connections(connections):
+    if connections in (None, ALL_CONNECTIONS):
+        return ALL_CONNECTIONS
+    if not isinstance(connections, list) or not all(isinstance(c, str) for c in connections):
+        raise ApiError(f'connections must be a list of connection names, or "{ALL_CONNECTIONS}" for all')
+    return sorted(set(connections))
+
+
+def _normalize_queries(queries):
+    """Unlike connections, an *unspecified* value here (None - nothing supplied) normalises to no extra
+    grant at all (an empty list), not "every query": a freshly created key with no queries named should
+    not gain reach through this field, and a key stored before this field existed has nothing recorded for
+    it either - reading that back as [] leaves such a key's behaviour exactly as it was (queries are
+    additive on top of connections, so granting none here takes nothing away). An *explicit* "*"
+    is a real, different, deliberately broader grant an admin can still choose - "any saved query by name,
+    but never ad-hoc SQL" - and is preserved as such, not collapsed into the empty-list default. See the
+    module docstring and can_use_query().
+
+    A list entry is either a plain name (read access, the original shape - untouched, so an existing key's
+    stored file needs no migration) or ``{"name": ..., "allow_writes": true}`` (write access to that one
+    query specifically - see can_write_query()). There is deliberately no way to combine "*" with a write
+    grant: wanting write access to a specific query means enumerating the whole list explicitly, the same
+    explicit-opt-in shape ``allow_writes`` already has everywhere else in this project - resolved this way
+    precisely so a write grant can never hide behind a wildcard an admin picked for unrelated read access.
+    """
+    if queries is None:
+        return []
+    if queries == ALL_QUERIES:
+        return ALL_QUERIES
+    if not isinstance(queries, list):
+        raise ApiError(f'queries must be a list of saved-query names, or "{ALL_QUERIES}" for all')
+    seen = set()
+    normalized = []
+    for entry in queries:
+        if isinstance(entry, str):
+            name, allow_writes = entry, False
+        elif isinstance(entry, dict):
+            name = entry.get('name')
+            if not isinstance(name, str):
+                raise ApiError('Each queries entry must be a saved-query name, or an object like '
+                               '{"name": "...", "allow_writes": true}')
+            extra = set(entry) - {'name', 'allow_writes'}
+            if extra:
+                raise ApiError(f'Unexpected field(s) in a queries entry: {", ".join(sorted(extra))}')
+            allow_writes = bool(entry.get('allow_writes', False))
+        else:
+            raise ApiError('Each queries entry must be a saved-query name, or an object like '
+                           '{"name": "...", "allow_writes": true}')
+        if name in seen:
+            raise ApiError(f'queries lists "{name}" more than once')
+        seen.add(name)
+        normalized.append({'name': name, 'allow_writes': True} if allow_writes else name)
+    normalized.sort(key=lambda e: e if isinstance(e, str) else e['name'])
+    return normalized
+
+
+def _queries_map(queries):
+    """The stored ``queries`` list (plain names and/or ``{"name", "allow_writes"}`` objects - see
+    _normalize_queries()) as a ``{name: allow_writes}`` dict for a resolved Permission - a plain-name entry
+    absent from a key stored before write curation existed reads back as ``allow_writes=False``, exactly its
+    original read-only-only meaning. Dict membership (``name in permission.queries``) behaves identically to
+    the frozenset this replaces for every existing read-only check (can_use_query()); can_write_query() is
+    the only caller that needs the value, not just the key."""
+    return {(e if isinstance(e, str) else e['name']): (False if isinstance(e, str) else e['allow_writes'])
+            for e in queries}
+
+
+def _validate_expiry(expires_at):
+    """None means no expiry. Date-only (YYYY-MM-DD), not a full timestamp - the use case (a time-boxed
+    trial or partner engagement) only ever needs day granularity, and a bare date is what an admin picks
+    from a plain HTML date input with no timezone-conversion surprises to get wrong."""
+    if expires_at is None:
+        return None
+    if not isinstance(expires_at, str) or not _DATE_RE.match(expires_at):
+        raise ApiError('expires_at must be a date in YYYY-MM-DD format, or null for no expiry')
+    try:
+        datetime.strptime(expires_at, '%Y-%m-%d')
+    except ValueError:
+        raise ApiError('expires_at must be a valid calendar date') from None
+    return expires_at
+
+
+def _validate_rate_limit(rate_limit):
+    """None means no per-key limit of its own (still subject to the server-wide one, unaffected). Reuses
+    config.parse_rate_limit()'s "N/period" grammar - one syntax to learn and validate, shared with
+    QUERYAPIGATE_RATE_LIMIT - rather than inventing a second format for the same concept."""
+    if rate_limit is None:
+        return None
+    if not isinstance(rate_limit, str):
+        raise ApiError("rate_limit must be a string like '100/minute', or null for none")
+    try:
+        config.parse_rate_limit(rate_limit, label='rate_limit')
+    except ValueError as error:
+        raise ApiError(str(error)) from None
+    return rate_limit
+
+
+def _validate_allowed_ips(allowed_ips):
+    """None means no restriction - a key matches from any client address (today's behaviour). Otherwise a
+    list of IP addresses or CIDR ranges (IPv4 or IPv6, mixed); the stdlib ipaddress module does the parsing
+    and later the containment check (_ip_allowed()), rather than a hand-rolled CIDR matcher - easy to get
+    subtly wrong by hand, and this needs no new dependency."""
+    if allowed_ips is None:
+        return None
+    if not isinstance(allowed_ips, list) or not all(isinstance(v, str) for v in allowed_ips):
+        raise ApiError('allowed_ips must be a list of IP addresses or CIDR ranges, or null for no restriction')
+    for value in allowed_ips:
+        try:
+            ipaddress.ip_network(value, strict=False)
+        except ValueError:
+            raise ApiError(f"'{value}' is not a valid IP address or CIDR range") from None
+    return sorted(set(allowed_ips))
+
+
+def _ip_allowed(entry, client_ip):
+    """Whether client_ip satisfies entry's allowed_ips restriction - True when the key carries no
+    restriction at all (the common case), or when client_ip falls inside one of its listed addresses/CIDR
+    ranges. A missing or unparseable client_ip fails a *restricted* key closed rather than open: an address
+    QueryAPIGate could not resolve should not be treated as trusted just because it's unusual."""
+    allowed = entry.get('allowed_ips')
+    if not allowed:
+        return True
+    if not client_ip:
+        return False
+    try:
+        address = ipaddress.ip_address(client_ip)
+    except ValueError:
+        return False
+    return any(address in ipaddress.ip_network(value, strict=False) for value in allowed)
+
+
+def _validate_allowed_write_ops(allowed_write_ops):
+    """None means no restriction - once allow_writes is on, any write keyword is permitted (today's
+    behaviour). Otherwise a list of SQL statement keywords (normalised to lowercase, e.g. "insert",
+    "delete"), checked against a write statement's own leading keyword by sqltools.validate_sql() - never
+    against a read-only one, which this never restricts. No fixed enum of valid keywords: the write-keyword
+    space is open-ended (INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, MERGE, ...), so a name is
+    accepted as given rather than validated against a closed list."""
+    if allowed_write_ops is None:
+        return None
+    if not isinstance(allowed_write_ops, list) or not all(isinstance(v, str) and v for v in allowed_write_ops):
+        raise ApiError('allowed_write_ops must be a list of SQL keywords (e.g. "insert", "update"), or null '
+                       'for no restriction')
+    return sorted({v.lower() for v in allowed_write_ops})
+
+
+def is_expired(entry):
+    """Whether a stored key entry's expires_at date has passed - checked live on every authenticate() call,
+    not swept by a background job: an expired key simply stops matching, the same way flipping `active` to
+    false already does, just automatic. Valid through the end of its expiry date (23:59:59), not the start
+    of it - "expires 2026-10-15" should keep working during the 15th, not from midnight that day."""
+    expires_at = entry.get('expires_at')
+    if not expires_at:
+        return False
+    try:
+        deadline = datetime.strptime(expires_at, '%Y-%m-%d').replace(hour=23, minute=59, second=59)
+    except ValueError:
+        return False  # a malformed stored value should not itself lock the key out
+    return datetime.now() > deadline
+
+
+def _record_use(name):
+    """Persist last_used_at for the key named ``name``, throttled to once per _USE_RECORD_INTERVAL - see
+    the module docstring. Re-reads under the lock immediately before writing, rather than reusing the
+    entry authenticate() already had in hand, so this never clobbers a concurrent admin change (a
+    connections/queries update, a revoke) with stale data - same discipline update_key()/delete_key()
+    already use. _last_recorded_use is in-process only: it resets on restart, which just means the first
+    request after one writes immediately - never a correctness problem, only ever slightly more eager."""
+    now = time.monotonic()
+    if now - _last_recorded_use.get(name, 0.0) < _USE_RECORD_INTERVAL:
+        return
+    _last_recorded_use[name] = now
+    with store.lock:
+        keys = _read()
+        if name in keys:
+            keys[name]['last_used_at'] = store.now()
+            _write(keys)
+
+
+def any_configured():
+    """True once at least one scoped key exists - QUERYAPIGATE_API_KEY is checked separately."""
+    return bool(_read())
+
+
+def auth_required():
+    return config.api_key() is not None or any_configured()
+
+
+def list_keys():
+    """Metadata only (name, connections, allow_writes, active, created_at) - never the hash."""
+    return {name: {k: v for k, v in entry.items() if k != 'hash'} for name, entry in _read().items()}
+
+
+def create_key(name, connections=None, allow_writes=None, queries=None, expires_at=None, rate_limit=None,
+               allowed_ips=None, allowed_write_ops=None, role=None):
+    if not isinstance(name, str) or not _NAME_RE.match(name):
+        raise ApiError("API key name may only contain letters, digits, spaces, '.', '_' and '-'")
+    if role is not None:
+        given = [field for field, value in (('connections', connections), ('allow_writes', allow_writes),
+                                            ('queries', queries), ('rate_limit', rate_limit),
+                                            ('allowed_ips', allowed_ips),
+                                            ('allowed_write_ops', allowed_write_ops)) if value is not None]
+        if given:
+            raise ApiError(f"Cannot combine 'role' with explicit {', '.join(given)} - create the key from "
+                           "the role, then update it afterward to customize.")
+        role_entry = _get_role_or_404(role)
+        connections = role_entry['connections']
+        allow_writes = role_entry['allow_writes']
+        queries = role_entry['queries']
+        rate_limit = role_entry['rate_limit']
+        allowed_ips = role_entry['allowed_ips']
+        allowed_write_ops = role_entry['allowed_write_ops']
+    secret = 'sk_' + secrets.token_urlsafe(32)
+    with store.lock:
+        keys = _read()
+        if name in keys:
+            raise ApiError(f"An API key named '{name}' already exists")
+        keys[name] = {
+            'hash': _hash(secret),
+            'connections': _normalize_connections(connections),
+            'allow_writes': bool(allow_writes),
+            'queries': _normalize_queries(queries),
+            'expires_at': _validate_expiry(expires_at),
+            'rate_limit': _validate_rate_limit(rate_limit),
+            'allowed_ips': _validate_allowed_ips(allowed_ips),
+            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
+            'created_from_role': role,
+            'active': True,
+            'created_at': store.now(),
+        }
+        _write(keys)
+    return secret
+
+
+def update_key(name, connections=None, allow_writes=None, active=None, queries=None, expires_at=_UNSET,
+               rate_limit=_UNSET, allowed_ips=_UNSET, allowed_write_ops=_UNSET):
+    with store.lock:
+        keys = _read()
+        if name not in keys:
+            raise ApiError(f"API key '{name}' not found", 404)
+        entry = keys[name]
+        if connections is not None:
+            entry['connections'] = _normalize_connections(connections)
+        if allow_writes is not None:
+            entry['allow_writes'] = bool(allow_writes)
+        if active is not None:
+            entry['active'] = bool(active)
+        if queries is not None:
+            entry['queries'] = _normalize_queries(queries)
+        if expires_at is not _UNSET:  # None here is an explicit "clear the expiry", not "leave unchanged"
+            entry['expires_at'] = _validate_expiry(expires_at)
+        if rate_limit is not _UNSET:  # same as expires_at: None here explicitly clears it
+            entry['rate_limit'] = _validate_rate_limit(rate_limit)
+        if allowed_ips is not _UNSET:  # same as expires_at/rate_limit: None here explicitly clears it
+            entry['allowed_ips'] = _validate_allowed_ips(allowed_ips)
+        if allowed_write_ops is not _UNSET:  # same as the others: None here explicitly clears it
+            entry['allowed_write_ops'] = _validate_allowed_write_ops(allowed_write_ops)
+        _write(keys)
+
+
+def delete_key(name):
+    with store.lock:
+        keys = _read()
+        if name not in keys:
+            raise ApiError(f"API key '{name}' not found", 404)
+        del keys[name]
+        _write(keys)
+
+
+# --------------------------------------------------------------------------------------
+# Roles: reusable *templates* for the grant fields above, copied onto a key once at
+# create_key(..., role=...) time - never consulted again afterward. See the module docstring.
+# --------------------------------------------------------------------------------------
+
+def _read_roles():
+    try:
+        with open(config.roles_file(), 'r') as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return {}
+    return data.get('roles', {})
+
+
+def _write_roles(roles):
+    config.home().mkdir(parents=True, exist_ok=True)
+    store.write_json_atomic(config.roles_file(), {'roles': roles})
+
+
+def _get_role_or_404(name):
+    roles = _read_roles()
+    if name not in roles:
+        raise ApiError(f"Role '{name}' not found", 404)
+    return roles[name]
+
+
+def list_roles():
+    return _read_roles()
+
+
+def create_role(name, connections=None, allow_writes=False, queries=None, rate_limit=None, allowed_ips=None,
+                allowed_write_ops=None):
+    if not isinstance(name, str) or not _NAME_RE.match(name):
+        raise ApiError("Role name may only contain letters, digits, spaces, '.', '_' and '-'")
+    with store.lock:
+        roles = _read_roles()
+        if name in roles:
+            raise ApiError(f"A role named '{name}' already exists")
+        roles[name] = {
+            'connections': _normalize_connections(connections),
+            'allow_writes': bool(allow_writes),
+            'queries': _normalize_queries(queries),
+            'rate_limit': _validate_rate_limit(rate_limit),
+            'allowed_ips': _validate_allowed_ips(allowed_ips),
+            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
+            'created_at': store.now(),
+        }
+        _write_roles(roles)
+
+
+def update_role(name, connections=None, allow_writes=None, queries=None, rate_limit=_UNSET, allowed_ips=_UNSET,
+                allowed_write_ops=_UNSET):
+    with store.lock:
+        roles = _read_roles()
+        if name not in roles:
+            raise ApiError(f"Role '{name}' not found", 404)
+        entry = roles[name]
+        if connections is not None:
+            entry['connections'] = _normalize_connections(connections)
+        if allow_writes is not None:
+            entry['allow_writes'] = bool(allow_writes)
+        if queries is not None:
+            entry['queries'] = _normalize_queries(queries)
+        if rate_limit is not _UNSET:
+            entry['rate_limit'] = _validate_rate_limit(rate_limit)
+        if allowed_ips is not _UNSET:
+            entry['allowed_ips'] = _validate_allowed_ips(allowed_ips)
+        if allowed_write_ops is not _UNSET:
+            entry['allowed_write_ops'] = _validate_allowed_write_ops(allowed_write_ops)
+        _write_roles(roles)
+
+
+def delete_role(name):
+    with store.lock:
+        roles = _read_roles()
+        if name not in roles:
+            raise ApiError(f"Role '{name}' not found", 404)
+        del roles[name]
+        _write_roles(roles)
+
+
+def _parsed_rate_limit(entry):
+    """The stored rate_limit string, parsed to (count, period) once here rather than re-parsed by every
+    caller - or None, for no per-key limit (unset) or a malformed stored value, which should not itself
+    break authentication any more than a malformed expires_at should (see is_expired())."""
+    raw = entry.get('rate_limit')
+    if not raw:
+        return None
+    try:
+        return config.parse_rate_limit(raw, label='rate_limit')
+    except ValueError:
+        return None
+
+
+def authenticate(supplied, client_ip=None):
+    """Resolve the ``X-API-Key`` header value to a Permission, or None if it matches no key at all (wrong
+    secret, or a right one that's inactive, expired, or used from outside its allowed_ips - all three fail
+    the same way as a plain wrong key, not a distinct error, so a caller learns nothing about *why* a
+    supplied key didn't work). ``client_ip`` is only used to check a scoped key's own allowed_ips
+    restriction, if it has one; the admin key is never restricted by it."""
+    if not supplied:
+        return None
+    expected = config.api_key()
+    if expected and hmac.compare_digest(supplied.encode('utf-8', 'replace'), expected.encode('utf-8')):
+        return Permission(name='admin', admin=True, connections=ALL_CONNECTIONS, allow_writes=True,
+                          queries=ALL_QUERIES, rate_limit=None, allowed_write_ops=None)
+    supplied_hash = _hash(supplied)
+    for name, entry in _read().items():
+        if entry.get('active', True) and not is_expired(entry) and _ip_allowed(entry, client_ip) \
+                and hmac.compare_digest(supplied_hash, entry['hash']):
+            _record_use(name)
+            connections = entry['connections']
+            queries = entry.get('queries', [])  # absent on a key stored before this field existed
+            return Permission(name=name, admin=False,
+                              connections=connections if connections == ALL_CONNECTIONS else frozenset(connections),
+                              allow_writes=bool(entry.get('allow_writes', False)),
+                              queries=queries if queries == ALL_QUERIES else _queries_map(queries),
+                              rate_limit=_parsed_rate_limit(entry),
+                              allowed_write_ops=entry.get('allowed_write_ops'))
+    return None