caplinks 0.0.2__tar.gz

caplinks-0.0.2/.gitignore

@@ -0,0 +1,119 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

caplinks-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.

caplinks-0.0.2/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: caplinks
+Version: 0.0.2
+Summary: Capability links: an unguessable token, an optional password gate, expiry, revocation and attempt limits. Standard library only.
+Project-URL: Homepage, https://github.com/i2mint/caplinks
+Project-URL: Repository, https://github.com/i2mint/caplinks
+Project-URL: Documentation, https://i2mint.github.io/caplinks
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: capability,expiry,password,rate limit,scrypt,share link,token
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# caplinks
+
+Capability links: hand someone a link to one thing, with no account. The token is the permission; a password may gate it; it expires; it can be revoked; password attempts are limited. Standard library only, no web framework.
+
+```
+pip install caplinks
+```
+
+```python
+from caplinks import CapabilityLinks
+
+links = CapabilityLinks()  # records in a dict; pass any MutableMapping to persist them
+rec = links.create({"doc": "report-1"}, password="open sesame", expires="7d")
+url = f"https://example.com/s/{rec['token']}/"
+
+state, stored = links.status(rec["token"])   # "ok", "expired" or "missing"
+links.check_password(stored, "open sesame")  # True
+cookie = links.unlock_value(stored)          # what a correct password earns
+links.unlocked(stored, cookie, max_age_s=3600)  # True, until the password changes or the link is revoked
+links.revoke(rec["token"])                   # now "missing"
+```
+
+## What is in it
+
+- `CapabilityLinks`: create, read, list and revoke links, and gate them on a password. Records are plain dicts in any `MutableMapping` keyed by token: the generic fields are `token`, `created`, `expires`, `password` (a hash) and `revoked`; your own fields (what the link reaches) sit beside them.
+- `ScryptHasher` (stdlib scrypt) behind the `PasswordHasher` protocol (`hash`, `verify -> bool`): pass `hasher=` for argon2 or anything else.
+- `parse_expires` reads what people write (`30m`, `12h`, `7d`, `2w`, `2026-11-01` meaning the end of that day UTC, an ISO timestamp, `never`) and refuses the past; `is_expired` fails closed.
+- `SlidingWindowLimiter` behind the `RateLimiter` protocol (`allow(key) -> bool`): count password attempts per client, per link, or both. It is per process; a shared limiter of the same shape (Redis, say) fits where several workers serve the links.
+
+The unlock value is an HMAC keyed by the stored password hash, so changing the password or revoking the link (which clears the hash) ends every open session at once.
+
+## What stays with your app
+
+What a link reaches (its scope), how it is served (routes, cookie name, headers), and the attempt policy. `annals` (share links) is the first host.
+
+## Seams
+
+| keyword | default | for |
+|---|---|---|
+| `store` | `dict` | persistence: a dol store, a file-backed mapping, S3 |
+| `hasher` | `ScryptHasher()` | argon2id or another scheme |
+| `clock` | `now_utc` | tests that pin the time |
+| `min_password_len` | 8 | a stricter or laxer gate |
+
+A store that cannot vouch for a record raises `KeyError`, `ValueError` or `OSError` when it is read, and the link is then missing; so is a record whose generic fields have the wrong types. Every failure closes the link.

caplinks-0.0.2/README.md

@@ -0,0 +1,45 @@
+# caplinks
+
+Capability links: hand someone a link to one thing, with no account. The token is the permission; a password may gate it; it expires; it can be revoked; password attempts are limited. Standard library only, no web framework.
+
+```
+pip install caplinks
+```
+
+```python
+from caplinks import CapabilityLinks
+
+links = CapabilityLinks()  # records in a dict; pass any MutableMapping to persist them
+rec = links.create({"doc": "report-1"}, password="open sesame", expires="7d")
+url = f"https://example.com/s/{rec['token']}/"
+
+state, stored = links.status(rec["token"])   # "ok", "expired" or "missing"
+links.check_password(stored, "open sesame")  # True
+cookie = links.unlock_value(stored)          # what a correct password earns
+links.unlocked(stored, cookie, max_age_s=3600)  # True, until the password changes or the link is revoked
+links.revoke(rec["token"])                   # now "missing"
+```
+
+## What is in it
+
+- `CapabilityLinks`: create, read, list and revoke links, and gate them on a password. Records are plain dicts in any `MutableMapping` keyed by token: the generic fields are `token`, `created`, `expires`, `password` (a hash) and `revoked`; your own fields (what the link reaches) sit beside them.
+- `ScryptHasher` (stdlib scrypt) behind the `PasswordHasher` protocol (`hash`, `verify -> bool`): pass `hasher=` for argon2 or anything else.
+- `parse_expires` reads what people write (`30m`, `12h`, `7d`, `2w`, `2026-11-01` meaning the end of that day UTC, an ISO timestamp, `never`) and refuses the past; `is_expired` fails closed.
+- `SlidingWindowLimiter` behind the `RateLimiter` protocol (`allow(key) -> bool`): count password attempts per client, per link, or both. It is per process; a shared limiter of the same shape (Redis, say) fits where several workers serve the links.
+
+The unlock value is an HMAC keyed by the stored password hash, so changing the password or revoking the link (which clears the hash) ends every open session at once.
+
+## What stays with your app
+
+What a link reaches (its scope), how it is served (routes, cookie name, headers), and the attempt policy. `annals` (share links) is the first host.
+
+## Seams
+
+| keyword | default | for |
+|---|---|---|
+| `store` | `dict` | persistence: a dol store, a file-backed mapping, S3 |
+| `hasher` | `ScryptHasher()` | argon2id or another scheme |
+| `clock` | `now_utc` | tests that pin the time |
+| `min_password_len` | 8 | a stricter or laxer gate |
+
+A store that cannot vouch for a record raises `KeyError`, `ValueError` or `OSError` when it is read, and the link is then missing; so is a record whose generic fields have the wrong types. Every failure closes the link.

caplinks-0.0.2/caplinks/__init__.py

@@ -0,0 +1,46 @@
+"""Capability links: an unguessable token, an optional password gate, expiry, attempt limits.
+
+The parts every app needs to hand someone a link to one thing, with no account: the
+token is the permission, a password may gate it, it expires, it can be revoked, and
+password attempts are limited. Standard library only; no web framework. What a link
+reaches (its scope) and how it is served stay with the app.
+
+>>> links = CapabilityLinks()  # records in a dict; pass any MutableMapping to persist
+>>> rec = links.create({"doc": "report-1"}, password="open sesame", expires="7d")
+>>> state, stored = links.status(rec["token"])
+>>> state, links.check_password(stored, "open sesame")
+('ok', True)
+>>> cookie = links.unlock_value(stored)
+>>> links.unlocked(stored, cookie, max_age_s=3600)
+True
+"""
+
+from caplinks.expiry import is_expired, now_utc, parse_expires
+from caplinks.limits import RateLimiter, SlidingWindowLimiter
+from caplinks.links import (
+    DFLT_EXPIRES,
+    MIN_PASSWORD_LEN,
+    RECORD_FIELDS,
+    CapabilityLinks,
+    check_token,
+    new_token,
+    public_record,
+)
+from caplinks.passwords import PasswordHasher, ScryptHasher
+
+__all__ = [
+    "CapabilityLinks",
+    "DFLT_EXPIRES",
+    "MIN_PASSWORD_LEN",
+    "PasswordHasher",
+    "RECORD_FIELDS",
+    "RateLimiter",
+    "ScryptHasher",
+    "SlidingWindowLimiter",
+    "check_token",
+    "is_expired",
+    "new_token",
+    "now_utc",
+    "parse_expires",
+    "public_record",
+]

caplinks-0.0.2/caplinks/expiry.py

@@ -0,0 +1,107 @@
+"""When a link stops working: reading an expiry the way a person writes one.
+
+An expiry is stored as an ISO UTC timestamp (or ``None`` for never). :func:`parse_expires`
+reads what a person types (``7d``, ``2026-11-01``, an ISO timestamp, ``never``);
+:func:`is_expired` checks a record against the clock and fails closed on a value it
+cannot read.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+#: duration suffixes accepted by :func:`parse_expires` (``30m``, ``12h``, ``7d``, ``2w``)
+DURATION_UNITS = {"m": "minutes", "h": "hours", "d": "days", "w": "weeks"}
+_DURATION_RE = re.compile(r"^(\d+)\s*([mhdw])$", re.I)
+_DATE_RE = re.compile(r"\d{4}-\d{2}-\d{2}")
+#: words that mean "no expiry"
+NEVER = frozenset({"never", "none", "no", ""})
+
+
+def now_utc() -> datetime:
+    """The current time, UTC, second precision (the clock every default reads)."""
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def _as_utc(when: datetime) -> datetime:
+    when = when if when.tzinfo else when.replace(tzinfo=timezone.utc)
+    return when.astimezone(timezone.utc).replace(microsecond=0)
+
+
+def parse_expires(value, *, now: datetime | None = None) -> str | None:
+    """An expiry as an ISO UTC timestamp, or ``None`` for never.
+
+    ``None``, ``""`` and ``"never"`` mean never. Accepts a duration (``30m``, ``12h``,
+    ``7d``, ``2w``), a date (``2026-11-01``: the END of that day, UTC, so the link works
+    through the day named), an ISO timestamp (a naive one is UTC), or a ``datetime``.
+    A moment already past is refused.
+
+    >>> t0 = datetime(2026, 1, 1, tzinfo=timezone.utc)
+    >>> parse_expires("2d", now=t0)
+    '2026-01-03T00:00:00+00:00'
+    >>> parse_expires("2026-01-05", now=t0)
+    '2026-01-05T23:59:59+00:00'
+    >>> parse_expires("never") is None
+    True
+    """
+    now = now or now_utc()
+    if value is None or (isinstance(value, str) and value.strip().lower() in NEVER):
+        return None
+    if isinstance(value, datetime):
+        when = value
+    else:
+        s = str(value).strip()
+        m = _DURATION_RE.match(s)
+        if m:
+            n, unit = int(m.group(1)), DURATION_UNITS[m.group(2).lower()]
+            try:
+                when = now + timedelta(**{unit: n})
+            except OverflowError:
+                raise ValueError(f"expiry {value!r} is too far away") from None
+        elif _DATE_RE.fullmatch(s):
+            when = datetime.fromisoformat(s).replace(
+                hour=23, minute=59, second=59, tzinfo=timezone.utc
+            )
+        else:
+            try:
+                when = datetime.fromisoformat(s.replace("Z", "+00:00"))
+            except ValueError:
+                raise ValueError(
+                    f"not an expiry: {value!r}; give a duration (7d, 12h), a date "
+                    "(2026-11-01) or an ISO timestamp"
+                ) from None
+    try:
+        when = _as_utc(when)
+    except OverflowError:
+        raise ValueError(f"expiry {value!r} is too far away") from None
+    if when <= now:
+        raise ValueError(f"expiry {when.isoformat()} is already past")
+    return when.isoformat()
+
+
+def expires_at(record: dict) -> datetime | None:
+    """The record's expiry as a UTC ``datetime``, ``None`` for never.
+
+    Raises ``ValueError`` on a value that is not a timestamp.
+    """
+    exp = record.get("expires")
+    if exp is None:
+        return None
+    try:
+        return _as_utc(datetime.fromisoformat(exp))
+    except (TypeError, OverflowError):
+        raise ValueError(f"not a timestamp: {exp!r}") from None
+
+
+def is_expired(record: dict, *, now: datetime | None = None) -> bool:
+    """True when the record has an expiry and it is reached (a bad one counts as reached).
+
+    >>> is_expired({"expires": None}), is_expired({"expires": "garbage"})
+    (False, True)
+    """
+    try:
+        when = expires_at(record)
+    except ValueError:
+        return True  # fail closed
+    return when is not None and (now or now_utc()) >= when

caplinks-0.0.2/caplinks/limits.py

@@ -0,0 +1,74 @@
+"""Limiting password attempts: the ``allow(key) -> bool`` protocol and an in-memory default.
+
+A host decides what to count (one client on one link, every wrong password a link
+takes, ...) and keys the limiter accordingly. The protocol is the shape of
+``heed.security``'s limiters, so its ``RedisRateLimiter`` (one count shared by every
+worker) fits wherever a :class:`RateLimiter` is asked for.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict, deque
+from typing import Callable, Protocol, runtime_checkable
+
+#: attempts one key may make in each window, by default
+DFLT_MAX_PER_WINDOW = 10
+DFLT_WINDOW_S = 300.0
+#: keys tracked at most, so a flood of addresses cannot exhaust memory
+DFLT_MAX_KEYS = 50_000
+
+
+@runtime_checkable
+class RateLimiter(Protocol):
+    """Decide whether one more attempt keyed by ``key`` is allowed now."""
+
+    def allow(self, key: str) -> bool: ...
+
+
+class SlidingWindowLimiter:
+    """At most ``max_per_window`` hits per key per window; in memory, per process.
+
+    Each worker counts alone (two workers allow twice the attempts); pass a shared
+    limiter when that matters. The least recently seen keys are dropped past
+    ``max_keys``.
+
+    >>> t = [0.0]
+    >>> lim = SlidingWindowLimiter(max_per_window=2, window_s=10, clock=lambda: t[0])
+    >>> [lim.allow("a"), lim.allow("a"), lim.allow("a"), lim.allow("b")]
+    [True, True, False, True]
+    >>> t[0] = 10.0; lim.allow("a")
+    True
+    """
+
+    def __init__(
+        self,
+        *,
+        max_per_window: int = DFLT_MAX_PER_WINDOW,
+        window_s: float = DFLT_WINDOW_S,
+        max_keys: int = DFLT_MAX_KEYS,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        if max_per_window < 1 or max_keys < 1:
+            raise ValueError("max_per_window and max_keys must be at least 1")
+        self.max_per_window = max_per_window
+        self.window_s = window_s
+        self.max_keys = max_keys
+        self._clock = clock
+        self._hits: OrderedDict[str, deque] = OrderedDict()
+        self._lock = threading.Lock()  # web hosts call limiters from a threadpool
+
+    def allow(self, key: str) -> bool:
+        with self._lock:
+            now = self._clock()
+            hits = self._hits.setdefault(key, deque())
+            self._hits.move_to_end(key)
+            while len(self._hits) > self.max_keys:
+                self._hits.popitem(last=False)
+            while hits and hits[0] <= now - self.window_s:
+                hits.popleft()
+            if len(hits) >= self.max_per_window:
+                return False
+            hits.append(now)
+            return True

caplinks-0.0.2/caplinks/links.py

@@ -0,0 +1,244 @@
+"""Capability links: a record behind an unguessable token, with an optional password gate.
+
+Knowing the token is the permission. A record is a plain dict, stored in any
+``MutableMapping`` keyed by token; the generic fields are :data:`RECORD_FIELDS`, and a
+host puts what the link reaches (its scope) in fields of its own beside them::
+
+    {"token": "<22 url-safe chars, 128 random bits>",
+     "created": "<iso>", "expires": "<iso>" | None,
+     "password": "scrypt$..." | None,     # a hash; the password is never stored
+     "revoked": "<iso>" | None,           # a tombstone: a revoked link is missing
+     ...the host's fields...}
+
+A correct password earns an unlock value (a cookie, for a web host): an HMAC keyed by
+the stored hash, so a new password, or a revoke, which clears the hash, ends every open
+session at once.
+
+The store contract: a store that cannot vouch for a record (unreadable, damaged, or
+missing the host's own fields) raises ``KeyError``, ``ValueError`` or ``OSError`` when
+it is read, and the link is then missing. A record whose generic fields have the wrong
+types is missing too: every failure closes the link.
+
+>>> links = CapabilityLinks()
+>>> rec = links.create({"what": "report-1"}, password="open sesame", expires="7d")
+>>> links.status(rec["token"])[0], rec["protected"], "password" in rec
+('ok', True, False)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import secrets
+from collections.abc import Callable, Mapping, MutableMapping
+from datetime import datetime
+
+from caplinks.expiry import expires_at, is_expired, now_utc, parse_expires
+from caplinks.passwords import PasswordHasher, ScryptHasher
+
+TOKEN_BYTES = 16  # 128 bits
+TOKEN_RE = re.compile(r"^[A-Za-z0-9_-]{20,64}$")
+#: the fields every record has; a host's own fields may not reuse these names
+RECORD_FIELDS = ("token", "created", "expires", "password", "revoked")
+#: fields the owner's view of a record adds (:func:`public_record`, ``list``)
+_VIEW_FIELDS = ("protected", "active")
+#: a link lasts this long unless told otherwise (``"never"`` for no expiry)
+DFLT_EXPIRES = "7d"
+#: the shortest link password accepted (a gate tried from anywhere must not be guessable)
+MIN_PASSWORD_LEN = 8
+#: an unlock value issued this far in the future still counts (clock skew between workers)
+_UNLOCK_SKEW_S = 60
+
+
+def new_token() -> str:
+    """A fresh link token: 128 random bits, url-safe."""
+    return secrets.token_urlsafe(TOKEN_BYTES)
+
+
+def check_token(token: str) -> str:
+    """Return ``token``; raise ``ValueError`` on anything that could not be one.
+
+    >>> check_token("../../etc/passwd")
+    Traceback (most recent call last):
+    ...
+    ValueError: not a link token
+    """
+    if not isinstance(token, str) or not TOKEN_RE.match(token):
+        raise ValueError("not a link token")
+    return token
+
+
+def public_record(record: dict) -> dict:
+    """A record without its password hash; ``protected`` says whether it has one."""
+    out = {k: v for k, v in record.items() if k != "password"}
+    out["protected"] = bool(record.get("password"))
+    return out
+
+
+class CapabilityLinks:
+    """Create, read, list and revoke capability links, and gate them on a password.
+
+    ``store`` maps token to record (a ``dict`` by default, in process); ``hasher``
+    hashes link passwords (stdlib scrypt by default); ``clock`` returns the current UTC
+    ``datetime`` (tests pin it); ``min_password_len`` is the shortest password accepted.
+    """
+
+    def __init__(
+        self,
+        store: MutableMapping[str, dict] | None = None,
+        *,
+        hasher: PasswordHasher | None = None,
+        clock: Callable[[], datetime] = now_utc,
+        min_password_len: int = MIN_PASSWORD_LEN,
+    ):
+        self.store = {} if store is None else store
+        self.hasher = hasher or ScryptHasher()
+        self.clock = clock
+        self.min_password_len = min_password_len
+
+    # -- create / read / list / revoke --
+
+    def create(
+        self,
+        fields: Mapping | None = None,
+        *,
+        password: str | None = None,
+        expires=DFLT_EXPIRES,
+    ) -> dict:
+        """Make a link carrying the host's ``fields``; return its record without the hash.
+
+        ``expires`` is anything :func:`caplinks.expiry.parse_expires` reads, 7 days by
+        default (``"never"`` for none); ``password`` gates the link.
+        """
+        fields = dict(fields or {})
+        clash = sorted(set(fields) & {*RECORD_FIELDS, *_VIEW_FIELDS})
+        if clash:
+            raise ValueError(f"fields {clash} are the link's own; name yours otherwise")
+        if password is not None and len(password) < self.min_password_len:
+            raise ValueError(
+                f"a link password needs at least {self.min_password_len} characters "
+                "(anyone can try it); omit it for no password"
+            )
+        now = self.clock()
+        record = {
+            "token": new_token(),
+            "created": now.isoformat(),
+            **fields,
+            "expires": parse_expires(expires, now=now),
+            "password": self.hasher.hash(password) if password else None,
+            "revoked": None,
+        }
+        self.store[record["token"]] = record
+        return public_record(record)
+
+    def record(self, token: str) -> dict | None:
+        """A copy of the stored record (hash included), revoked or not; ``None`` if none."""
+        try:
+            rec = self.store[check_token(token)]
+        except (KeyError, ValueError, OSError):
+            return None
+        if not _well_formed(rec, token):
+            return None  # damaged, or filed under another name: grants nothing
+        return dict(rec)
+
+    def status(self, token: str) -> tuple[str, dict | None]:
+        """``("ok" | "expired" | "missing", record)``; a revoked link is ``missing``."""
+        rec = self.record(token)
+        if rec is None or rec.get("revoked"):
+            return "missing", None
+        if is_expired(rec, now=self.clock()):
+            return "expired", rec
+        return "ok", rec
+
+    def list(self, *, include_inactive: bool = False) -> list[dict]:
+        """Every live link, newest first, without hashes; ``include_inactive`` adds
+        revoked and expired ones.
+
+        Each record gains ``active`` (neither revoked nor expired).
+        """
+        now = self.clock()
+        out = []
+        for token in list(self.store):
+            rec = self.record(token)
+            if rec is None:
+                continue
+            rec = public_record(rec)
+            rec["active"] = not rec.get("revoked") and not is_expired(rec, now=now)
+            if include_inactive or rec["active"]:
+                out.append(rec)
+        return sorted(out, key=lambda r: r["created"], reverse=True)
+
+    def revoke(self, token: str) -> dict:
+        """End a link now (idempotent). The record stays, as a tombstone."""
+        rec = self.record(token)
+        if rec is None:
+            raise KeyError(token)
+        if not rec.get("revoked"):
+            rec = {**rec, "revoked": self.clock().isoformat(), "password": None}
+            self.store[token] = rec  # no hash left: nothing to guess, no session lives
+        return public_record(rec)
+
+    # -- the password gate --
+
+    def check_password(self, record: dict, password: str) -> bool:
+        """Whether ``password`` opens ``record`` (constant time inside the hasher)."""
+        hashed = record.get("password")
+        return bool(hashed) and self.hasher.verify(hashed, password)
+
+    def unlock_value(self, record: dict) -> str:
+        """What a correct password earns, to send back on later requests: ``<epoch>.<mac>``."""
+        issued = int(self.clock().timestamp())
+        return f"{issued}.{_unlock_mac(record, issued)}"
+
+    def unlocked(self, record: dict, value: str | None, *, max_age_s: int) -> bool:
+        """Whether ``value`` is a live unlock of ``record`` (no password: always).
+
+        A revoked record is never unlocked, whatever the caller checked before.
+        """
+        if record.get("revoked"):
+            return False
+        if not record.get("password"):
+            return True
+        if not value or "." not in value:
+            return False
+        issued_s, _, mac = value.partition(".")
+        try:
+            issued = int(issued_s)
+        except ValueError:
+            return False
+        now = int(self.clock().timestamp())
+        if not (now - max_age_s <= issued <= now + _UNLOCK_SKEW_S):
+            return False
+        expected = _unlock_mac(record, issued)
+        return hmac.compare_digest(mac.encode("utf-8"), expected.encode("ascii"))
+
+    def unlock_max_age(self, record: dict, *, max_age_s: int) -> int:
+        """How long an unlock should last, in seconds: ``max_age_s``, never past expiry."""
+        try:
+            ends = expires_at(record)
+        except ValueError:
+            return 1
+        if ends is None:
+            return max_age_s
+        left = int((ends - self.clock()).total_seconds())
+        return max(1, min(max_age_s, left))
+
+
+def _well_formed(rec, token: str) -> bool:
+    """The generic fields have the types every method relies on."""
+    optional_str = lambda v: v is None or isinstance(v, str)  # noqa: E731
+    return (
+        isinstance(rec, dict)
+        and rec.get("token") == token
+        and isinstance(rec.get("created"), str)
+        and all(optional_str(rec.get(k)) for k in ("expires", "password", "revoked"))
+    )
+
+
+def _unlock_mac(record: dict, issued: int) -> str:
+    # Keyed by the password hash: it holds a random salt and never leaves the server, and
+    # a new password (or a revoke, which clears it) invalidates every unlock at once.
+    key = (record.get("password") or "").encode("utf-8")
+    msg = f"{record['token']}:{issued}".encode("ascii")
+    return hmac.new(key, msg, hashlib.sha256).hexdigest()

caplinks-0.0.2/caplinks/passwords.py

@@ -0,0 +1,74 @@
+"""Password hashing for a link's password gate: a protocol and a stdlib default.
+
+A link password is a gate, not an account: it is hashed once when the link is made and
+checked on each unlock. :class:`ScryptHasher` needs nothing beyond the standard library;
+anything with the same two methods (an argon2id adapter, say) fits the ``hasher`` seam
+of :class:`caplinks.CapabilityLinks`.
+
+>>> h = ScryptHasher(n=2**4)  # tiny cost, for the example only
+>>> stored = h.hash("correct horse")
+>>> stored.startswith("scrypt$"), h.verify(stored, "correct horse"), h.verify(stored, "x")
+(True, True, False)
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import secrets
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PasswordHasher(Protocol):
+    """What a link needs to gate on a password: ``verify`` returns a bool, never raises."""
+
+    def hash(self, password: str) -> str: ...
+
+    def verify(self, hashed: str, password: str) -> bool: ...
+
+
+@dataclass(frozen=True)
+class ScryptHasher:
+    """Stdlib ``hashlib.scrypt``, stored as ``scrypt$n$r$p$salt$hash`` (base64).
+
+    The parameters travel with the hash, so raising ``n`` later still verifies old
+    hashes. ``n=2**14, r=8`` costs ~16 MB and tens of ms per check, which a host's
+    attempt limit (:mod:`caplinks.limits`) bounds.
+    """
+
+    n: int = 2**14
+    r: int = 8
+    p: int = 1
+    salt_bytes: int = 16
+    dklen: int = 32
+
+    def _derive(self, password: str, salt: bytes, n: int, r: int, p: int) -> bytes:
+        return hashlib.scrypt(
+            password.encode("utf-8"),
+            salt=salt,
+            n=n,
+            r=r,
+            p=p,
+            dklen=self.dklen,
+            maxmem=2 * 128 * r * n + 2**20,
+        )
+
+    def hash(self, password: str) -> str:
+        salt = secrets.token_bytes(self.salt_bytes)
+        dk = self._derive(password, salt, self.n, self.r, self.p)
+        b64 = lambda b: base64.b64encode(b).decode("ascii")  # noqa: E731
+        return f"scrypt${self.n}${self.r}${self.p}${b64(salt)}${b64(dk)}"
+
+    def verify(self, hashed: str, password: str) -> bool:
+        try:
+            scheme, n, r, p, salt, dk = hashed.split("$")
+            if scheme != "scrypt":
+                return False
+            expected = base64.b64decode(dk)
+            got = self._derive(password, base64.b64decode(salt), int(n), int(r), int(p))
+        except (ValueError, TypeError, AttributeError):
+            return False
+        return hmac.compare_digest(got, expected)

caplinks-0.0.2/pyproject.toml

@@ -0,0 +1,174 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "caplinks"
+version = "0.0.2"
+description = "Capability links: an unguessable token, an optional password gate, expiry, revocation and attempt limits. Standard library only."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["capability", "share link", "token", "password", "expiry", "rate limit", "scrypt"]
+authors = [
+    { name = "Thor Whalen" },
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/i2mint/caplinks"
+Repository = "https://github.com/i2mint/caplinks"
+Documentation = "https://i2mint.github.io/caplinks"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+docs = [
+    "sphinx>=6.0",
+    "sphinx-rtd-theme>=1.0",
+]
+
+[tool.hatch.build]
+skip-excluded-dirs = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["caplinks"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    ".claude",
+    ".github",
+    "scrap",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+exclude = [
+    "**/*.ipynb",
+    "**/*.md",
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+    "tests",
+    "examples",
+    "scrap",
+]
+
+[tool.ruff.lint]
+select = [
+    "D100",
+]
+ignore = [
+    "D203",
+    "E501",
+    "B905",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = [
+    "D",
+]
+"**/examples/*" = [
+    "D",
+]
+"**/scrap/*" = [
+    "D",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "caplinks",
+    "tests",
+]
+addopts = "--doctest-modules"
+doctest_optionflags = [
+    "NORMALIZE_WHITESPACE",
+    "ELLIPSIS",
+]
+
+[tool.wads.ci]
+project_name = ""
+
+[tool.wads.ci.install]
+extras = "dev"
+
+[tool.wads.ci.commands]
+pre_test = []
+test = []
+post_test = []
+lint = []
+format = []
+
+[tool.wads.ci.env]
+required_envvars = []
+test_envvars = []
+extra_envvars = []
+
+[tool.wads.ci.env.defaults]
+
+[tool.wads.ci.quality.ruff]
+enabled = true
+
+[tool.wads.ci.quality.black]
+enabled = false
+
+[tool.wads.ci.quality.mypy]
+enabled = false
+
+[tool.wads.ci.testing]
+enabled = true
+python_versions = [
+    "3.10",
+    "3.12",
+]
+pytest_args = [
+    "-v",
+    "--tb=short",
+]
+coverage_enabled = true
+coverage_threshold = 0
+coverage_report_format = [
+    "term",
+    "xml",
+]
+exclude_paths = [
+    "examples",
+    "scrap",
+]
+test_on_windows = false
+
+[tool.wads.ci.metrics]
+enabled = true
+config_path = ".github/umpyre-config.yml"
+storage_branch = "code-metrics"
+python_version = "3.11"
+force_run = false
+
+[tool.wads.ci.build]
+sdist = true
+wheel = true
+
+[tool.wads.ci.publish]
+enabled = true
+skip_ci_marker = "[skip ci]"
+publish_marker = "[publish]"
+
+[tool.wads.ci.docs]
+enabled = true
+builder = "epythet"
+ignore_paths = [
+    "tests/",
+    "scrap/",
+    "examples/",
+]

caplinks-0.0.2/tests/test_caplinks.py

@@ -0,0 +1,268 @@
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from caplinks import (
+    CapabilityLinks,
+    RateLimiter,
+    ScryptHasher,
+    SlidingWindowLimiter,
+    is_expired,
+    parse_expires,
+)
+
+T0 = datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)
+PW = "correct horse"
+
+
+class Clock:
+    def __init__(self, t=T0):
+        self.t = t
+
+    def __call__(self):
+        return self.t
+
+
+@pytest.fixture
+def clock():
+    return Clock()
+
+
+@pytest.fixture
+def links(clock):
+    return CapabilityLinks(hasher=ScryptHasher(n=2**4), clock=clock)
+
+
+def test_smoke_create_open_unlock_revoke():
+    """The one-command path, every seam on its default."""
+    links = CapabilityLinks()
+    rec = links.create({"doc": "d1"}, password=PW)
+    state, stored = links.status(rec["token"])
+    assert state == "ok" and stored["doc"] == "d1"
+    assert links.check_password(stored, PW)
+    cookie = links.unlock_value(stored)
+    assert links.unlocked(stored, cookie, max_age_s=60)
+    links.revoke(rec["token"])
+    assert links.status(rec["token"]) == ("missing", None)
+
+
+def test_create_keeps_host_fields_and_never_returns_the_hash(links):
+    rec = links.create({"root": {"id": "x"}, "docs": {"x": ["a.md"]}}, password=PW)
+    assert rec["root"] == {"id": "x"} and rec["protected"] is True
+    assert "password" not in rec
+    stored = links.store[rec["token"]]
+    assert stored["password"].startswith("scrypt$") and PW not in stored["password"]
+    assert stored["expires"] == (T0 + timedelta(days=7)).isoformat()
+
+
+def test_create_refuses_reserved_fields_and_short_passwords(links):
+    with pytest.raises(ValueError, match="link's own"):
+        links.create({"expires": "never"})
+    with pytest.raises(ValueError, match="at least 8"):
+        links.create(password="short")
+    assert links.create(password=None)["protected"] is False
+
+
+def test_status_ok_expired_missing(links, clock):
+    tok = links.create(expires="1h")["token"]
+    assert links.status(tok)[0] == "ok"
+    clock.t = T0 + timedelta(hours=1)
+    assert links.status(tok)[0] == "expired"
+    assert links.status("A" * 22) == ("missing", None)
+    assert links.status("../etc") == ("missing", None)
+
+
+def test_a_record_the_store_cannot_vouch_for_is_missing(clock):
+    class Picky(dict):
+        def __getitem__(self, k):
+            raise ValueError("damaged")
+
+    links = CapabilityLinks(Picky(), clock=clock)
+    links.store["A" * 22] = {"token": "A" * 22}
+    assert links.record("A" * 22) is None
+
+
+def test_a_record_filed_under_another_token_grants_nothing(links):
+    rec = links.create()
+    other = "B" * 22
+    links.store[other] = dict(links.store[rec["token"]])
+    assert links.record(other) is None and links.status(other)[0] == "missing"
+
+
+def test_list_newest_first_and_all_adds_inactive(links, clock):
+    a = links.create(expires="1h")["token"]
+    clock.t = T0 + timedelta(minutes=1)
+    b = links.create()["token"]
+    c = links.create()["token"]
+    links.revoke(c)
+    assert [r["token"] for r in links.list()] == [b, a]
+    clock.t = T0 + timedelta(hours=2)
+    assert [r["token"] for r in links.list()] == [b]
+    everything = links.list(include_inactive=True)
+    assert {r["token"] for r in everything} == {a, b, c}
+    assert all("password" not in r for r in everything)
+    assert {r["token"]: r["active"] for r in everything} == {
+        a: False,
+        b: True,
+        c: False,
+    }
+
+
+def test_revoke_is_idempotent_clears_the_hash_and_raises_on_unknown(links, clock):
+    tok = links.create(password=PW)["token"]
+    first = links.revoke(tok)
+    clock.t = T0 + timedelta(hours=1)
+    assert links.revoke(tok)["revoked"] == first["revoked"]
+    assert links.store[tok]["password"] is None
+    with pytest.raises(KeyError):
+        links.revoke("C" * 22)
+
+
+def test_unlock_value_lifecycle(links, clock):
+    rec = links.store[links.create(password=PW)["token"]]
+    value = links.unlock_value(rec)
+    assert links.unlocked(rec, value, max_age_s=3600)
+    assert not links.unlocked(
+        rec, value[:-1] + ("1" if value[-1] == "0" else "0"), max_age_s=3600
+    )
+    assert not links.unlocked(rec, None, max_age_s=3600)
+    assert not links.unlocked(rec, "nonsense", max_age_s=3600)
+    clock.t = T0 + timedelta(hours=2)
+    assert not links.unlocked(rec, value, max_age_s=3600)  # too old
+
+
+def test_a_new_password_ends_every_unlock(links):
+    rec = links.store[links.create(password=PW)["token"]]
+    value = links.unlock_value(rec)
+    rec = {**rec, "password": links.hasher.hash("another one")}
+    assert not links.unlocked(rec, value, max_age_s=3600)
+
+
+def test_an_open_link_is_always_unlocked(links):
+    rec = links.store[links.create()["token"]]
+    assert links.unlocked(rec, None, max_age_s=1)
+    assert not links.check_password(rec, "anything")
+
+
+def test_unlock_max_age_never_outlives_the_link(links, clock):
+    rec = links.store[links.create(expires="1h")["token"]]
+    assert links.unlock_max_age(rec, max_age_s=7 * 86400) == 3600
+    assert links.unlock_max_age(rec, max_age_s=60) == 60
+    never = links.store[links.create(expires="never")["token"]]
+    assert links.unlock_max_age(never, max_age_s=60) == 60
+    clock.t = T0 + timedelta(hours=3)
+    assert links.unlock_max_age(rec, max_age_s=60) == 1
+
+
+def test_hasher_rejects_foreign_or_broken_hashes():
+    h = ScryptHasher(n=2**4)
+    assert not h.verify("argon2$whatever", PW)
+    assert not h.verify("scrypt$not$enough", PW)
+    assert not h.verify(None, PW)
+    assert h.hash(PW) != h.hash(PW)  # salted
+
+
+@pytest.mark.parametrize(
+    "value, expected",
+    [
+        ("30m", T0 + timedelta(minutes=30)),
+        ("12H", T0 + timedelta(hours=12)),
+        ("2w", T0 + timedelta(weeks=2)),
+        ("2026-01-02", datetime(2026, 1, 2, 23, 59, 59, tzinfo=timezone.utc)),
+        ("2026-01-02T10:00:00Z", datetime(2026, 1, 2, 10, tzinfo=timezone.utc)),
+        ("2026-01-02T10:00:00", datetime(2026, 1, 2, 10, tzinfo=timezone.utc)),
+        (
+            datetime(2026, 2, 1, tzinfo=timezone.utc),
+            datetime(2026, 2, 1, tzinfo=timezone.utc),
+        ),
+    ],
+)
+def test_parse_expires_reads_what_people_write(value, expected):
+    assert parse_expires(value, now=T0) == expected.isoformat()
+
+
+@pytest.mark.parametrize("value", [None, "", "never", " None "])
+def test_parse_expires_never(value):
+    assert parse_expires(value, now=T0) is None
+
+
+@pytest.mark.parametrize("value", ["2025-12-31", "yesterday", "0d"])
+def test_parse_expires_refuses_the_past_and_nonsense(value):
+    with pytest.raises(ValueError):
+        parse_expires(value, now=T0)
+
+
+def test_is_expired_fails_closed():
+    assert is_expired({"expires": 12345})
+    assert is_expired({"expires": "not a date"})
+    assert not is_expired({})
+
+
+def test_limiter_bounds_its_keys_and_fits_the_protocol():
+    lim = SlidingWindowLimiter(max_per_window=1, max_keys=2, clock=lambda: 0.0)
+    assert lim.allow("a") and not lim.allow("a")
+    lim.allow("b"), lim.allow("c")  # "a" is evicted
+    assert lim.allow("a")
+    assert isinstance(lim, RateLimiter)
+
+    class Redisish:  # heed.security.RedisRateLimiter's shape
+        def allow(self, key):
+            return True
+
+    assert isinstance(Redisish(), RateLimiter)
+
+
+def test_view_fields_are_reserved_too(links):
+    for name in ("protected", "active"):
+        with pytest.raises(ValueError, match="link's own"):
+            links.create({name: 1})
+
+
+def test_a_hostile_unlock_value_is_refused_not_raised(links, clock):
+    rec = links.record(links.create(password=PW)["token"])
+    now = int(clock().timestamp())
+    assert not links.unlocked(rec, f"{now}.é", max_age_s=60)
+
+
+def test_a_revoked_record_is_never_unlocked(links):
+    tok = links.create(password=PW)["token"]
+    links.revoke(tok)
+    assert not links.unlocked(links.record(tok), None, max_age_s=60)
+
+
+@pytest.mark.parametrize(
+    "damage",
+    [{"password": 123}, {"created": 5}, {"expires": 7}, {"revoked": []}],
+)
+def test_a_record_with_mistyped_fields_is_missing_and_spares_the_list(links, damage):
+    good = links.create()["token"]
+    bad = links.create()["token"]
+    links.store[bad] = {**links.store[bad], **damage}
+    assert links.record(bad) is None and links.status(bad)[0] == "missing"
+    assert [r["token"] for r in links.list(include_inactive=True)] == [good]
+
+
+def test_a_store_raising_oserror_closes_the_link(clock):
+    class Flaky(dict):
+        def __getitem__(self, k):
+            raise OSError("ssh dropped")
+
+    assert CapabilityLinks(Flaky(), clock=clock).record("A" * 22) is None
+
+
+def test_record_is_a_copy(links):
+    tok = links.create(password=PW)["token"]
+    links.record(tok).pop("password")
+    assert links.record(tok)["password"]
+
+
+@pytest.mark.parametrize("value", ["99999999d", "9999-12-31T23:59:59-05:00"])
+def test_parse_expires_far_future_is_a_value_error(value):
+    with pytest.raises(ValueError, match="too far"):
+        parse_expires(value, now=T0)
+
+
+@pytest.mark.parametrize("kw", [{"max_keys": 0}, {"max_per_window": 0}])
+def test_limiter_refuses_settings_that_disable_it(kw):
+    with pytest.raises(ValueError):
+        SlidingWindowLimiter(**kw)