caplinks 0.0.2__tar.gz → 0.0.4__tar.gz

{caplinks-0.0.2 → caplinks-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: caplinks
-Version: 0.0.2
+Version: 0.0.4
 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
@@ -44,6 +44,9 @@ 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.
+- Gating an id you already have: `create(..., token=existing_id)` keeps the id; `set_password(token, pw_or_None)` and `set_expires(token, when)` change a live link later (a new password ends every open unlock).
+- `AttemptGuard`: the per-link lock-out. `allow(link, client)` before checking a password, `failed(link)` after a wrong one; one client is limited on its own, and a link that takes too many wrong passwords from everyone is locked for a while.
+- `JsonRecords(texts)` and `FileTexts(folder)`: a ready `store` for `CapabilityLinks`, records as `<token>.json` in a text mapping (a local folder: atomic, mode 0600). Pass `valid=` to check your own fields and `deletable=False` to keep revoked links as tombstones.
 - `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.

{caplinks-0.0.2 → caplinks-0.0.4}/README.md

@@ -23,6 +23,9 @@ 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.
+- Gating an id you already have: `create(..., token=existing_id)` keeps the id; `set_password(token, pw_or_None)` and `set_expires(token, when)` change a live link later (a new password ends every open unlock).
+- `AttemptGuard`: the per-link lock-out. `allow(link, client)` before checking a password, `failed(link)` after a wrong one; one client is limited on its own, and a link that takes too many wrong passwords from everyone is locked for a while.
+- `JsonRecords(texts)` and `FileTexts(folder)`: a ready `store` for `CapabilityLinks`, records as `<token>.json` in a text mapping (a local folder: atomic, mode 0600). Pass `valid=` to check your own fields and `deletable=False` to keep revoked links as tombstones.
 - `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.

{caplinks-0.0.2 → caplinks-0.0.4}/caplinks/__init__.py

@@ -16,6 +16,7 @@ True
 """
 
 from caplinks.expiry import is_expired, now_utc, parse_expires
+from caplinks.guard import DFLT_MAX_ATTEMPTS, DFLT_MAX_LINK_FAILURES, AttemptGuard
 from caplinks.limits import RateLimiter, SlidingWindowLimiter
 from caplinks.links import (
     DFLT_EXPIRES,
@@ -27,8 +28,14 @@ from caplinks.links import (
     public_record,
 )
 from caplinks.passwords import PasswordHasher, ScryptHasher
+from caplinks.records import FileTexts, JsonRecords
 
 __all__ = [
+    "AttemptGuard",
+    "DFLT_MAX_ATTEMPTS",
+    "DFLT_MAX_LINK_FAILURES",
+    "FileTexts",
+    "JsonRecords",
     "CapabilityLinks",
     "DFLT_EXPIRES",
     "MIN_PASSWORD_LEN",

caplinks-0.0.4/caplinks/guard.py

@@ -0,0 +1,87 @@
+"""The per-link lock-out: limit password tries, and lock a link that takes too many.
+
+Two counts, because they defend against different things. Tries of one client on one
+link are limited so that a guesser locks out only itself; the wrong passwords a link
+takes from *everyone* are limited too, and past that the link's unlock is closed for a
+while (a distributed guess). A host calls :meth:`AttemptGuard.allow` before it checks a
+password and :meth:`AttemptGuard.failed` after a wrong one.
+
+>>> t = [0.0]
+>>> guard = AttemptGuard(
+...     client_limiter=SlidingWindowLimiter(max_per_window=5, clock=lambda: t[0]),
+...     link_limiter=SlidingWindowLimiter(max_per_window=1, clock=lambda: t[0]),
+...     lock_s=60, clock=lambda: t[0])
+>>> guard.allow("link", "1.2.3.4")
+True
+>>> guard.failed("link"); guard.failed("link")  # the second one locks the link
+>>> guard.allow("link", "5.6.7.8")
+False
+>>> t[0] = 61.0; guard.allow("link", "5.6.7.8")
+True
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+
+from caplinks.limits import (
+    DFLT_WINDOW_S,
+    RateLimiter,
+    SlidingWindowLimiter,
+)
+
+#: tries one client gets on one link per window
+DFLT_MAX_ATTEMPTS = 10
+#: wrong passwords one link takes from everyone per window before it locks
+DFLT_MAX_LINK_FAILURES = 100
+
+
+class AttemptGuard:
+    """Decide whether a password try may be made, and lock a link that is being guessed.
+
+    ``client_limiter`` counts every try of one client on one link; ``link_limiter``
+    counts the wrong passwords a link takes from everyone and, past its limit, locks the
+    link for ``lock_s`` seconds. Both are anything with ``allow(key) -> bool`` (a Redis
+    one shares the count between workers); the lock itself is per process. ``clock``
+    returns a monotonic time in seconds (tests pin it; the default limiters use it too).
+    Keep ``lock_s`` at least the limiter's window, or the first failure after a lock ends
+    locks the link again at once.
+    """
+
+    def __init__(
+        self,
+        *,
+        client_limiter: RateLimiter | None = None,
+        link_limiter: RateLimiter | None = None,
+        lock_s: float = DFLT_WINDOW_S,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        self.client_limiter = client_limiter or SlidingWindowLimiter(
+            max_per_window=DFLT_MAX_ATTEMPTS, window_s=DFLT_WINDOW_S, clock=clock
+        )
+        self.link_limiter = link_limiter or SlidingWindowLimiter(
+            max_per_window=DFLT_MAX_LINK_FAILURES, window_s=DFLT_WINDOW_S, clock=clock
+        )
+        self.lock_s = lock_s
+        self._clock = clock
+        self._locked: dict[str, float] = {}  # link -> when its lock ends
+        self._lock = threading.Lock()
+
+    def allow(self, link: str, client: str) -> bool:
+        """Whether ``client`` may try a password on ``link`` now (counts the try)."""
+        with self._lock:
+            ends = self._locked.get(link, 0.0)
+            if ends > self._clock():
+                return False
+            if ends:
+                del self._locked[link]  # expired: do not keep it
+        return self.client_limiter.allow(f"{link}:{client}")
+
+    def failed(self, link: str) -> None:
+        """Record a wrong password on ``link``; lock the link if it takes too many."""
+        if self.link_limiter.allow(link):
+            return
+        with self._lock:
+            self._locked[link] = self._clock() + self.lock_s

{caplinks-0.0.2 → caplinks-0.0.4}/caplinks/links.py

@@ -105,28 +105,32 @@ class CapabilityLinks:
         *,
         password: str | None = None,
         expires=DFLT_EXPIRES,
+        token: str | None = None,
     ) -> 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.
+        default (``"never"`` for none); ``password`` gates the link. ``token`` gates an
+        id that already exists (a host whose links must not change): it must look like
+        a token (:func:`check_token`) and be unused; leave it out for a fresh one. The
+        caller then owns the id's randomness: use 128 random bits, as :func:`new_token`.
         """
         fields = dict(fields or {})
+        if token is not None:
+            check_token(token)
+            if token in self.store:  # even a damaged record is not free to overwrite
+                raise ValueError("a link with this token already exists")
         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"
-            )
+        hashed = self._hash_password(password)
         now = self.clock()
         record = {
-            "token": new_token(),
+            "token": token or new_token(),
             "created": now.isoformat(),
             **fields,
             "expires": parse_expires(expires, now=now),
-            "password": self.hasher.hash(password) if password else None,
+            "password": hashed,
             "revoked": None,
         }
         self.store[record["token"]] = record
@@ -169,6 +173,47 @@ class CapabilityLinks:
                 out.append(rec)
         return sorted(out, key=lambda r: r["created"], reverse=True)
 
+    def set_password(self, token: str, password: str | None) -> dict:
+        """Give an unrevoked link a new password, or ``None`` to open it.
+
+        A new password ends every open unlock at once. A revoked link stays revoked
+        (``KeyError``).
+        """
+        return self._update(token, password=self._hash_password(password))
+
+    def set_expires(self, token: str, expires) -> dict:
+        """Move an unrevoked link's expiry (anything :func:`parse_expires` reads;
+        ``"never"`` for none). An expired link may be given a later one; a revoked link
+        stays revoked (``KeyError``).
+        """
+        return self._update(token, expires=parse_expires(expires, now=self.clock()))
+
+    def _update(self, token: str, **changes) -> dict:
+        # The store has no compare-and-set: the record is read just before the write (the
+        # slow hashing is done by the caller) so a revoke that landed meanwhile is not
+        # undone. Hosts with several workers writing the
+        # same link still need to serialise writes per token.
+        rec = self._unrevoked(token)
+        if rec is None:
+            raise KeyError(token)
+        rec.update(changes)
+        self.store[token] = rec
+        return public_record(rec)
+
+    def _unrevoked(self, token: str) -> dict | None:
+        rec = self.record(token)
+        return None if rec is None or rec.get("revoked") else rec
+
+    def _hash_password(self, password: str | None) -> str | None:
+        if password is None:
+            return None
+        if 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"
+            )
+        return self.hasher.hash(password)
+
     def revoke(self, token: str) -> dict:
         """End a link now (idempotent). The record stays, as a tombstone."""
         rec = self.record(token)

caplinks-0.0.4/caplinks/records.py

@@ -0,0 +1,158 @@
+"""Link records as JSON text in a store of text: a mapping from token to dict.
+
+:class:`CapabilityLinks` keeps its records in any ``MutableMapping`` of token to dict.
+:class:`JsonRecords` makes one from a mapping of *text* (``<token>.json`` to the JSON of
+the record), and :class:`FileTexts` is that text mapping over a local folder, written
+atomically and readable by the owner only (a record holds a password hash). A host whose
+text lives elsewhere (ssh, S3) passes its own mapping of text.
+
+>>> import tempfile
+>>> from caplinks import CapabilityLinks
+>>> links = CapabilityLinks(JsonRecords(FileTexts(tempfile.mkdtemp())))
+>>> token = links.create({"doc": "d1"})["token"]
+>>> links.status(token)[1]["doc"]
+'d1'
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Callable, Iterator, MutableMapping
+from pathlib import Path
+
+from caplinks.links import TOKEN_RE, check_token
+
+SUFFIX = ".json"
+
+
+class JsonRecords(MutableMapping):
+    """``{token: dict}`` over a mapping of text, ``<token>.json`` to its JSON.
+
+    A record that cannot be read, is not a JSON object, or fails ``valid`` raises
+    ``KeyError``: the link is then missing (every failure closes the link). ``valid``
+    takes the host's own check of its fields. ``deletable=False`` refuses ``del``: a
+    host that keeps a revoked link as a tombstone says so. ``indent`` pretty-prints.
+
+    The contract of ``texts``: reading a missing name raises ``KeyError``.
+    """
+
+    def __init__(
+        self,
+        texts: MutableMapping[str, str],
+        *,
+        valid: Callable[[dict], bool] | None = None,
+        deletable: bool = True,
+        indent: int | None = None,
+    ):
+        self.texts = texts
+        self.valid = valid
+        self.deletable = deletable
+        self.indent = indent
+
+    @staticmethod
+    def _name(token: str) -> str:
+        try:
+            return check_token(token) + SUFFIX
+        except ValueError:
+            raise KeyError(token) from None
+
+    def __getitem__(self, token: str) -> dict:
+        try:
+            rec = json.loads(self.texts[self._name(token)])
+        except (ValueError, KeyError, OSError, RuntimeError, TypeError):
+            raise KeyError(token) from None
+        if not isinstance(rec, dict) or (self.valid and not self.valid(rec)):
+            raise KeyError(token)
+        return rec
+
+    def __setitem__(self, token: str, record: dict) -> None:
+        self.texts[self._name(token)] = json.dumps(record, indent=self.indent)
+
+    def __delitem__(self, token: str) -> None:
+        if not self.deletable:
+            raise TypeError("link records are never deleted; revoke the link instead")
+        del self.texts[self._name(token)]
+
+    def __iter__(self) -> Iterator[str]:
+        for name in self.texts:
+            token = name[: -len(SUFFIX)]
+            if name.endswith(SUFFIX) and TOKEN_RE.match(token):
+                yield token
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __contains__(self, token) -> bool:
+        try:
+            return self._name(token) in self.texts
+        except (KeyError, TypeError):
+            return False
+
+
+class FileTexts(MutableMapping):
+    """``{name: text}`` over the files of one local folder (created on first write).
+
+    Names are plain file names (no path separator, no leading dot, no NUL); a name whose
+    file is a symlink out of the folder is missing. The folder is private (mode 0700:
+    the names are link tokens) and a write goes to a hidden temporary file (mode 0600)
+    that replaces the target, so a reader never sees half a record.
+    """
+
+    def __init__(self, folder: str | os.PathLike):
+        self.folder = Path(folder).expanduser()
+
+    def _path(self, name: str) -> Path:
+        if (
+            not isinstance(name, str)
+            or not name
+            or name.startswith(".")
+            or any(c in name for c in "/\\\0")
+        ):
+            raise KeyError(name)
+        path = self.folder / name
+        if path.is_symlink():
+            raise KeyError(name)
+        return path
+
+    def __getitem__(self, name: str) -> str:
+        try:
+            return self._path(name).read_text(encoding="utf-8")
+        except (FileNotFoundError, IsADirectoryError):
+            raise KeyError(name) from None
+
+    def __setitem__(self, name: str, text: str) -> None:
+        path = self._path(name)
+        self.folder.mkdir(mode=0o700, parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.folder, prefix=".", suffix=".tmp")  # 0600
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(text)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+    def __delitem__(self, name: str) -> None:
+        try:
+            self._path(name).unlink()
+        except FileNotFoundError:
+            raise KeyError(name) from None
+
+    def __iter__(self) -> Iterator[str]:
+        if self.folder.is_dir():
+            for p in self.folder.iterdir():
+                if p.is_file() and not p.is_symlink() and not p.name.startswith("."):
+                    yield p.name
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __contains__(self, name) -> bool:
+        try:
+            return self._path(name).is_file()
+        except (KeyError, TypeError):
+            return False

{caplinks-0.0.2 → caplinks-0.0.4}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "caplinks"
-version = "0.0.2"
+version = "0.0.4"
 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"

{caplinks-0.0.2 → caplinks-0.0.4}/tests/test_caplinks.py

@@ -266,3 +266,223 @@ def test_parse_expires_far_future_is_a_value_error(value):
 def test_limiter_refuses_settings_that_disable_it(kw):
     with pytest.raises(ValueError):
         SlidingWindowLimiter(**kw)
+
+
+def test_create_gates_an_existing_id():
+    links = CapabilityLinks()
+    tid = "A" * 22
+    rec = links.create({"x": 1}, password=PW, expires="never", token=tid)
+    assert rec["token"] == tid and rec["protected"]
+    assert links.status(tid)[0] == "ok"
+    with pytest.raises(ValueError, match="already exists"):
+        links.create(token=tid)
+    with pytest.raises(ValueError, match="not a link token"):
+        links.create(token="../x")
+
+
+def test_set_password_ends_open_unlocks():
+    links = CapabilityLinks()
+    tok = links.create(password=PW)["token"]
+    cookie = links.unlock_value(links.record(tok))
+    assert links.unlocked(links.record(tok), cookie, max_age_s=3600)
+    assert links.set_password(tok, "another pass")["protected"]
+    assert not links.unlocked(links.record(tok), cookie, max_age_s=3600)
+    assert not links.set_password(tok, None)["protected"]
+    with pytest.raises(ValueError):
+        links.set_password(tok, "short")
+
+
+def test_set_expires_revives_an_expired_link_but_not_a_revoked_one():
+    clock = Clock()
+    links = CapabilityLinks(clock=clock)
+    tok = links.create(expires="1d")["token"]
+    clock.t = T0 + timedelta(days=2)
+    assert links.status(tok)[0] == "expired"
+    links.set_expires(tok, "3d")
+    assert links.status(tok)[0] == "ok"
+    assert links.set_expires(tok, "never")["expires"] is None
+    links.revoke(tok)
+    for call in (lambda: links.set_expires(tok, "3d"), lambda: links.set_password(tok, PW)):
+        with pytest.raises(KeyError):
+            call()
+
+
+def test_set_password_new_one_opens_old_one_does_not():
+    links = CapabilityLinks(hasher=ScryptHasher(n=2**4))
+    tok = links.create(password=PW)["token"]
+    links.set_password(tok, "another pass")
+    rec = links.record(tok)
+    assert links.check_password(rec, "another pass") and not links.check_password(rec, PW)
+    links.set_password(tok, None)
+    assert links.unlocked(links.record(tok), None, max_age_s=60)
+
+
+def test_setters_refuse_the_past_and_the_missing():
+    links = CapabilityLinks()
+    tok = links.create()["token"]
+    with pytest.raises(ValueError, match="past"):
+        links.set_expires(tok, "2000-01-01")
+    for call in (lambda: links.set_expires("B" * 22, "1d"), lambda: links.set_password("B" * 22, PW)):
+        with pytest.raises(KeyError):
+            call()
+
+
+def test_a_revoked_id_cannot_be_gated_again():
+    links = CapabilityLinks()
+    tid = "C" * 22
+    links.create(token=tid)
+    links.revoke(tid)
+    with pytest.raises(ValueError, match="already exists"):
+        links.create(token=tid)
+    assert links.status(tid)[0] == "missing"
+
+
+def test_create_token_does_not_overwrite_a_damaged_record():
+    store = {"D" * 22: {"junk": 1}}
+    links = CapabilityLinks(store)
+    with pytest.raises(ValueError, match="already exists"):
+        links.create(token="D" * 22)
+    assert store["D" * 22] == {"junk": 1}
+
+
+
+# -- AttemptGuard, JsonRecords, FileTexts --
+
+
+def test_guard_limits_one_client_without_locking_the_link():
+    from caplinks import AttemptGuard
+
+    guard = AttemptGuard(client_limiter=SlidingWindowLimiter(max_per_window=2))
+    assert [guard.allow("L", "a") for _ in range(3)] == [True, True, False]
+    assert guard.allow("L", "b")  # another client is not affected
+
+
+def test_guard_locks_a_link_taking_many_failures_then_reopens():
+    from caplinks import AttemptGuard
+
+    t = [0.0]
+    guard = AttemptGuard(
+        link_limiter=SlidingWindowLimiter(max_per_window=2, clock=lambda: t[0]),
+        lock_s=60,
+        clock=lambda: t[0],
+    )
+    for _ in range(2):
+        guard.failed("L")
+    assert guard.allow("L", "a")  # at the limit, not past it
+    guard.failed("L")
+    assert not guard.allow("L", "a") and not guard.allow("L", "b")
+    assert guard.allow("other", "a")
+    t[0] = 60.0
+    assert guard.allow("L", "a")
+    assert "L" not in guard._locked  # pruned
+
+
+def test_json_records_roundtrip_and_fail_closed(tmp_path):
+    from caplinks import FileTexts, JsonRecords
+
+    recs = JsonRecords(FileTexts(tmp_path / "r"), valid=lambda r: "scope" in r)
+    links = CapabilityLinks(recs)
+    tok = links.create({"scope": 1}, password=PW)["token"]
+    assert links.status(tok)[0] == "ok" and tok in recs and list(recs) == [tok]
+    (tmp_path / "r" / f"{tok}.json").write_text("{not json")
+    assert links.status(tok)[0] == "missing" and tok in recs
+    (tmp_path / "r" / f"{tok}.json").write_text('{"token": "%s"}' % tok)
+    assert links.status(tok)[0] == "missing"  # fails the host's check
+    assert "../x" not in recs
+    with pytest.raises(KeyError):
+        recs["../x"]
+
+
+def test_json_records_can_refuse_deletes(tmp_path):
+    from caplinks import FileTexts, JsonRecords
+
+    recs = JsonRecords(FileTexts(tmp_path), deletable=False)
+    tok = CapabilityLinks(recs).create()["token"]
+    with pytest.raises(TypeError):
+        del recs[tok]
+
+
+def test_file_texts_are_private_atomic_and_confined(tmp_path):
+    import os
+
+    from caplinks import FileTexts
+
+    texts = FileTexts(tmp_path / "t")
+    texts["a.json"] = "one"
+    texts["a.json"] = "two"
+    assert texts["a.json"] == "two" and list(texts) == ["a.json"]
+    assert os.stat(tmp_path / "t" / "a.json").st_mode & 0o777 == 0o600
+    assert os.stat(tmp_path / "t").st_mode & 0o777 == 0o700
+    assert sorted(p.name for p in (tmp_path / "t").iterdir()) == ["a.json"]  # no temp
+    for bad in ("../a", ".hidden", "x/y", "", "a\0b"):
+        assert bad not in texts
+        with pytest.raises(KeyError):
+            texts[bad]
+    del texts["a.json"]
+    with pytest.raises(KeyError):
+        del texts["a.json"]
+
+
+def test_a_failed_write_leaves_the_old_text_and_no_temp_file(tmp_path):
+    from caplinks import FileTexts
+
+    texts = FileTexts(tmp_path)
+    texts["a.json"] = "old"
+    with pytest.raises(TypeError):
+        texts["a.json"] = 5  # not text: the write fails midway
+    assert texts["a.json"] == "old"
+    assert [p.name for p in tmp_path.iterdir()] == ["a.json"]
+
+
+def test_stray_files_and_symlinks_do_not_break_listing_or_escape(tmp_path):
+    from caplinks import FileTexts, JsonRecords
+
+    outside = tmp_path / "secret.json"
+    outside.write_text("{}")
+    folder = tmp_path / "r"
+    recs = JsonRecords(FileTexts(folder))
+    tok = CapabilityLinks(recs).create()["token"]
+    (folder / ".DS_Store").write_text("x")
+    (folder / "README.json").write_text("{}")
+    (folder / ("S" * 22 + ".json")).symlink_to(outside)
+    assert list(recs) == [tok]
+    assert set(dict(recs.items())) == {tok}
+    assert "S" * 22 not in recs
+
+
+def test_texts_returning_none_is_a_missing_link(tmp_path):
+    from caplinks import JsonRecords
+
+    class Nones(dict):
+        def __getitem__(self, k):
+            return None
+
+    recs = JsonRecords(Nones())
+    with pytest.raises(KeyError):
+        recs["N" * 22]
+
+
+def test_guard_default_limiters_follow_the_pinned_clock():
+    from caplinks import AttemptGuard
+
+    t = [0.0]
+    guard = AttemptGuard(clock=lambda: t[0])
+    assert all(guard.allow("L", "a") for _ in range(10)) and not guard.allow("L", "a")
+    t[0] = 301.0
+    assert guard.allow("L", "a")
+
+
+def test_guard_is_safe_under_threads():
+    import threading
+
+    from caplinks import AttemptGuard
+
+    guard = AttemptGuard(client_limiter=SlidingWindowLimiter(max_per_window=50))
+    results = []
+    threads = [
+        threading.Thread(target=lambda: results.append(guard.allow("L", "a")))
+        for _ in range(200)
+    ]
+    [th.start() for th in threads]
+    [th.join() for th in threads]
+    assert sum(results) == 50