satchel-reader 0.1.0__py3-none-any.whl

satchel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

satchel/capture.py

@@ -0,0 +1,44 @@
+"""The one place "fetch, extract, store" happens -- used by both the CLI's
+`add` command and the local capture listener (`serve.py`), so there is
+exactly one add pipeline, not two that can drift apart.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from . import db
+from .extract import extract
+from .fetch import fetch, normalize_url
+
+
+def add_article(conn: sqlite3.Connection, raw_url: str, *, restrict_private_network: bool = False) -> dict:
+    """Fetch, extract, and store one article.
+
+    Returns {"ok": bool, "message": str, "id": int | None}.
+
+    restrict_private_network is False for direct CLI use (a human typing a
+    URL into their own terminal isn't a threat to themselves) and True for
+    the capture listener (see serve.py) -- there, the URL comes from
+    whatever page happened to be open in the browser, not from the person
+    running satchel, and that's exactly the boundary an SSRF guard exists
+    for.
+    """
+    url = normalize_url(raw_url)
+    try:
+        html, final_url = fetch(url, restrict_private_network=restrict_private_network)
+    except Exception as exc:  # noqa: BLE001 - a bad/unsafe fetch is a clear result, not a crash
+        return {"ok": False, "message": f"could not fetch {url}: {exc}", "id": None}
+    # Normalize again after following redirects -- the URL actually served
+    # (past a shortener, or an http->https upgrade) is the real dedup key.
+    url = normalize_url(final_url)
+
+    article = extract(html, url=url)
+    if article is None:
+        return {"ok": False, "message": f"could not extract article text from {url}", "id": None}
+
+    try:
+        article_id = db.add(conn, url, article["title"], article["author"], article["text"])
+    except sqlite3.IntegrityError:
+        return {"ok": False, "message": f"already saved: {url}", "id": None}
+
+    return {"ok": True, "message": f"saved #{article_id}: {article['title'] or url}", "id": article_id}

satchel/cli.py

@@ -0,0 +1,99 @@
+"""satchel add <url> | search <query> | list | read <id> | serve"""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+
+from . import db
+from .capture import add_article
+from .serve import DEFAULT_PORT, serve
+
+
+def _do_add(args) -> int:
+    conn = db.connect(args.db)
+    result = add_article(conn, args.url)
+    print(result["message"], file=sys.stdout if result["ok"] else sys.stderr)
+    return 0 if result["ok"] else 1
+
+
+def _do_search(args) -> int:
+    conn = db.connect(args.db)
+    try:
+        rows = db.search(conn, args.query)
+    except sqlite3.OperationalError:
+        # FTS5's MATCH syntax (quotes, AND/OR/NOT, prefix *, column filters)
+        # is real query syntax a user can get wrong -- an unbalanced quote or
+        # a bare operator shouldn't surface as a Python traceback.
+        print(f"error: couldn't parse that search query: {args.query!r}", file=sys.stderr)
+        print("tip: quotes must be balanced; AND/OR/NOT/* are reserved words in FTS5 syntax", file=sys.stderr)
+        return 1
+    if not rows:
+        print("no matches")
+        return 0
+    for row in rows:
+        print(f"#{row['id']:<4} {row['title'] or row['url']}  ({row['url']})")
+    return 0
+
+
+def _do_list(args) -> int:
+    conn = db.connect(args.db)
+    rows = db.list_all(conn)
+    if not rows:
+        print(f"nothing saved yet — try: satchel add <url>  (db: {args.db})")
+        return 0
+    for row in rows:
+        print(f"#{row['id']:<4} {row['title'] or row['url']}  ({row['added_at']})")
+    return 0
+
+
+def _do_read(args) -> int:
+    conn = db.connect(args.db)
+    row = db.get(conn, args.id)
+    if row is None:
+        print(f"error: no article #{args.id}", file=sys.stderr)
+        return 1
+    print(row["title"] or row["url"])
+    if row["author"]:
+        print(f"by {row['author']}")
+    print()
+    print(row["text"])
+    return 0
+
+
+def _do_serve(args) -> int:
+    return serve(args.db, port=args.port)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="satchel")
+    parser.add_argument("--db", default=db.default_db_path(),
+                         help=f"path to the sqlite db (default: {db.default_db_path()})")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    add_p = sub.add_parser("add", help="fetch a URL, extract the article, save it")
+    add_p.add_argument("url")
+    add_p.set_defaults(func=_do_add)
+
+    search_p = sub.add_parser("search", help="full-text search saved articles")
+    search_p.add_argument("query")
+    search_p.set_defaults(func=_do_search)
+
+    list_p = sub.add_parser("list", help="list everything saved")
+    list_p.set_defaults(func=_do_list)
+
+    read_p = sub.add_parser("read", help="print a saved article's full text")
+    read_p.add_argument("id", type=int)
+    read_p.set_defaults(func=_do_read)
+
+    serve_p = sub.add_parser("serve", help="run a local listener + bookmarklet for one-click capture")
+    serve_p.add_argument("--port", type=int, default=DEFAULT_PORT,
+                          help=f"port to listen on (default: {DEFAULT_PORT})")
+    serve_p.set_defaults(func=_do_serve)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

satchel/db.py

@@ -0,0 +1,101 @@
+"""SQLite storage with full-text search (FTS5), local-first: one file, no
+server, no network dependency to search what you've already saved.
+
+The FTS5 table is external-content (`content='articles'`): the searchable
+copy of the text isn't duplicated as the source of truth, and triggers keep
+it in sync on insert/update/delete so the two can't drift apart.
+"""
+from __future__ import annotations
+
+import os
+import pathlib
+import sqlite3
+import time
+
+
+def default_db_path() -> str:
+    """Where satchel.db lives if --db isn't given: one stable, per-user
+    location instead of "whatever directory you happened to run the
+    command from" -- the latter means `satchel add` from ~/Downloads and
+    `satchel list` from ~ silently look at two different, disconnected
+    databases, which is indistinguishable from data loss to a new user.
+    Respects XDG_DATA_HOME; falls back to the XDG default location.
+    """
+    data_home = os.environ.get("XDG_DATA_HOME") or str(pathlib.Path.home() / ".local" / "share")
+    return str(pathlib.Path(data_home) / "satchel" / "satchel.db")
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS articles (
+    id INTEGER PRIMARY KEY,
+    url TEXT UNIQUE NOT NULL,
+    title TEXT,
+    author TEXT,
+    text TEXT NOT NULL,
+    added_at TEXT NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS articles_fts USING fts5(
+    title, author, text, content='articles', content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS articles_ai AFTER INSERT ON articles BEGIN
+    INSERT INTO articles_fts(rowid, title, author, text)
+    VALUES (new.id, new.title, new.author, new.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS articles_ad AFTER DELETE ON articles BEGIN
+    INSERT INTO articles_fts(articles_fts, rowid, title, author, text)
+    VALUES ('delete', old.id, old.title, old.author, old.text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS articles_au AFTER UPDATE ON articles BEGIN
+    INSERT INTO articles_fts(articles_fts, rowid, title, author, text)
+    VALUES ('delete', old.id, old.title, old.author, old.text);
+    INSERT INTO articles_fts(rowid, title, author, text)
+    VALUES (new.id, new.title, new.author, new.text);
+END;
+"""
+
+
+def connect(path: str) -> sqlite3.Connection:
+    parent = pathlib.Path(path).parent
+    if str(parent) not in ("", "."):
+        parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.executescript(SCHEMA)
+    return conn
+
+
+def add(conn: sqlite3.Connection, url: str, title: str | None, author: str | None, text: str) -> int:
+    """Returns the article's id. Raises sqlite3.IntegrityError if the url
+    is already saved -- the caller decides what "already have this" means
+    to them (skip, re-fetch, update), this layer doesn't guess."""
+    cur = conn.execute(
+        "INSERT INTO articles (url, title, author, text, added_at) VALUES (?, ?, ?, ?, ?)",
+        (url, title, author, text, time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())),
+    )
+    conn.commit()
+    return cur.lastrowid
+
+
+def get(conn: sqlite3.Connection, article_id: int) -> sqlite3.Row | None:
+    return conn.execute("SELECT * FROM articles WHERE id = ?", (article_id,)).fetchone()
+
+
+def list_all(conn: sqlite3.Connection) -> list[sqlite3.Row]:
+    return conn.execute("SELECT id, url, title, author, added_at FROM articles ORDER BY added_at DESC").fetchall()
+
+
+def search(conn: sqlite3.Connection, query: str) -> list[sqlite3.Row]:
+    return conn.execute(
+        """
+        SELECT articles.id, articles.url, articles.title, articles.author, articles.added_at
+        FROM articles_fts
+        JOIN articles ON articles.id = articles_fts.rowid
+        WHERE articles_fts MATCH ?
+        ORDER BY rank
+        """,
+        (query,),
+    ).fetchall()

satchel/extract.py

@@ -0,0 +1,30 @@
+"""Turn raw HTML into (title, author, text). Wraps trafilatura rather than
+reimplementing boilerplate-stripping -- a naive "grab the biggest <div>"
+approach is exactly the kind of thing that looks fine on one test page and
+breaks on the next real site's markup.
+
+Deliberately takes HTML directly (bytes or str), not a URL -- fetching is a
+separate, network-dependent step (see fetch.py), and keeping extraction pure
+means it can be tested offline against fixture HTML with no network
+involved. Bytes are preferred: trafilatura's own charset detection is
+better than trusting the HTTP header.
+"""
+from __future__ import annotations
+
+import json
+
+import trafilatura
+
+
+def extract(html: bytes | str, url: str | None = None) -> dict | None:
+    """Returns {"title", "author", "text"}, or None if trafilatura couldn't
+    find a main content block at all (a login wall, an empty page, a page
+    that's entirely JavaScript-rendered with nothing in the raw HTML)."""
+    raw = trafilatura.extract(html, url=url, output_format="json", with_metadata=True)
+    if not raw:
+        return None
+    data = json.loads(raw)
+    text = data.get("text") or ""
+    if not text.strip():
+        return None
+    return {"title": data.get("title"), "author": data.get("author"), "text": text}

satchel/fetch.py

@@ -0,0 +1,115 @@
+"""Fetch a URL's HTML. stdlib only -- a plain GET is not worth a dependency
+when extraction (the actually hard part) already needs one.
+"""
+from __future__ import annotations
+
+import ipaddress
+import socket
+import urllib.request
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+_USER_AGENT = "satchel/0.1 (personal reading queue; +https://github.com/MaXiMo000/satchel)"
+
+_ALLOWED_SCHEMES = {"http", "https"}
+
+
+class UnsafeURLError(ValueError):
+    """A URL failed safety validation before satchel would fetch it: an
+    unsupported scheme, or -- when restrict_private_network=True -- an
+    address that isn't reachable on the public internet."""
+
+
+def _check_scheme(url: str) -> None:
+    scheme = urlsplit(url).scheme.lower()
+    if scheme not in _ALLOWED_SCHEMES:
+        raise UnsafeURLError(f"unsupported URL scheme {scheme!r} (only http/https)")
+
+
+def _check_not_private(url: str) -> None:
+    """Refuses a URL whose host resolves to loopback, private, link-local,
+    reserved, multicast, or unspecified address space -- the exact ranges
+    an SSRF payload targets (localhost services, 169.254.169.254-style
+    cloud metadata endpoints, other hosts on the local network).
+
+    This validates the hostname's *current* DNS answer, at the moment it's
+    checked -- it does not pin the connection to that exact resolved
+    address. A sufficiently motivated attacker who controls DNS for a
+    domain (a near-zero TTL, answering differently a moment later) could
+    still slip a private address past this check and have urllib re-
+    resolve to it at actual connect time -- classic DNS rebinding. Fully
+    closing that needs connecting to the pinned IP directly rather than by
+    hostname, which is real added complexity for a personal tool's local
+    capture endpoint; this is a deliberate, documented partial mitigation,
+    not a claim of a hard guarantee against a determined network attacker.
+    """
+    host = urlsplit(url).hostname
+    if not host:
+        raise UnsafeURLError("URL has no host")
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror as exc:
+        raise UnsafeURLError(f"could not resolve {host}: {exc}") from exc
+    for info in infos:
+        addr = ipaddress.ip_address(info[4][0])
+        if (addr.is_private or addr.is_loopback or addr.is_link_local
+                or addr.is_reserved or addr.is_multicast or addr.is_unspecified):
+            raise UnsafeURLError(f"{host} resolves to a non-public address ({addr}) -- refusing")
+
+
+class _RestrictedRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Re-validates every redirect target before following it. Without
+    this, a URL that passes validation up front could still redirect
+    somewhere private, and urllib would follow it anyway -- the initial
+    check alone only guards the first hop."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        _check_scheme(newurl)
+        _check_not_private(newurl)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+# The same article shared twice almost always differs only in tracking junk
+# or a trailing slash -- strip that before it's used as the dedup key, or
+# the one duplicate guard this tool has never actually fires in practice.
+_TRACKING_PARAMS = {
+    "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content",
+    "fbclid", "gclid", "ref", "ref_src", "source",
+}
+
+
+def normalize_url(url: str) -> str:
+    parts = urlsplit(url)
+    query = urlencode([(k, v) for k, v in parse_qsl(parts.query) if k not in _TRACKING_PARAMS])
+    path = parts.path.rstrip("/") or "/"
+    return urlunsplit((parts.scheme, parts.netloc, path, query, ""))
+
+
+def fetch(url: str, timeout: float = 15.0, restrict_private_network: bool = False) -> tuple[bytes, str]:
+    """Returns (raw bytes, the final URL after any redirects).
+
+    Raw bytes, not a decoded string -- trafilatura does its own charset
+    detection (via cchardet) and does it better than trusting the HTTP
+    header alone, which many sites omit or get wrong.
+
+    The final URL matters for dedup: a shortened link (bit.ly, t.co) or a
+    plain http:// URL a site 301-redirects to https:// both resolve to the
+    same real address the server actually served, and *that* address --
+    not whatever the user happened to type or click -- is what two saves
+    of "the same" article should be compared against. This is also the
+    right way to answer "should http:// and https:// count as the same
+    URL": defer to what the server says by following the redirect, rather
+    than guessing.
+
+    Only http/https are ever accepted, always. restrict_private_network
+    additionally refuses a URL (or a redirect to one) that resolves to
+    loopback/private/link-local/reserved address space -- pass True when
+    the URL didn't come from the person running satchel (see serve.py).
+    """
+    _check_scheme(url)
+    if restrict_private_network:
+        _check_not_private(url)
+        opener = urllib.request.build_opener(_RestrictedRedirectHandler)
+    else:
+        opener = urllib.request.build_opener()
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    with opener.open(req, timeout=timeout) as resp:
+        return resp.read(), resp.geturl()

satchel/serve.py

@@ -0,0 +1,109 @@
+"""Local capture listener: click a bookmarklet on any page, and its URL
+goes through the same fetch/extract/store pipeline the CLI uses -- no
+terminal required for the one action that happens most often.
+
+Loopback-only and token-gated. Why the token matters: while `serve` is
+running, *any* tab open in the browser can send a request to
+http://127.0.0.1:<port> -- a browser's same-origin policy stops a page
+from reading a cross-origin response it didn't get permission for, but it
+does not stop the page from sending the request in the first place. With
+no shared secret, that's an open invitation for any site you happen to
+have open to make this process fetch (and store) an arbitrary URL on your
+behalf. The token is generated fresh each time `serve` starts and only
+ever appears in the bookmarklet printed below -- it isn't the request
+itself that's protected, it's that a request without the right token gets
+nothing.
+"""
+from __future__ import annotations
+
+import http.server
+import json
+import secrets
+import sys
+import urllib.parse
+
+from . import db
+from .capture import add_article
+
+DEFAULT_PORT = 8765
+
+
+def _bookmarklet(port: int, token: str) -> str:
+    return (
+        "javascript:fetch('http://127.0.0.1:%d/add?token=%s&url='"
+        "+encodeURIComponent(location.href))"
+        ".then(r=>r.json()).then(j=>alert(j.message))"
+        ".catch(e=>alert('satchel: could not reach the local listener -- is `satchel serve` still running?'))"
+    ) % (port, urllib.parse.quote(token))
+
+
+def _make_handler(db_path: str, token: str) -> type[http.server.BaseHTTPRequestHandler]:
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, fmt: str, *args) -> None:  # noqa: A003 - stdlib's name
+            pass  # quiet by default; every response already carries the result
+
+        def _reply(self, status: int, payload: dict) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            # The token is the real access control here, not CORS -- once a
+            # request has the right token it's allowed to succeed, so there's
+            # nothing extra protected by hiding the response from whatever
+            # page's bookmarklet sent it.
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:
+            parsed = urllib.parse.urlsplit(self.path)
+            if parsed.path != "/add":
+                self._reply(404, {"ok": False, "message": "not found"})
+                return
+
+            qs = urllib.parse.parse_qs(parsed.query)
+            given_token = qs.get("token", [""])[0]
+            if not secrets.compare_digest(given_token, token):
+                self._reply(403, {"ok": False, "message": "bad or missing token"})
+                return
+
+            url = qs.get("url", [""])[0]
+            if not url:
+                self._reply(400, {"ok": False, "message": "no url given"})
+                return
+
+            conn = db.connect(db_path)
+            try:
+                result = add_article(conn, url, restrict_private_network=True)
+            finally:
+                conn.close()
+            self._reply(200 if result["ok"] else 400, result)
+
+    return Handler
+
+
+def serve(db_path: str, port: int = DEFAULT_PORT) -> int:
+    token = secrets.token_urlsafe(16)
+    try:
+        httpd = http.server.HTTPServer(("127.0.0.1", port), _make_handler(db_path, token))
+    except OSError as exc:
+        print(f"error: could not listen on 127.0.0.1:{port}: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"satchel capture listening on http://127.0.0.1:{port}  (db: {db_path})")
+    print()
+    print("Drag this to your bookmarks bar, then click it on any page to save it:")
+    print()
+    print(f"  {_bookmarklet(port, token)}")
+    print()
+    print("Only this machine can reach it, and only with the token above -- restart")
+    print("`serve` and re-drag the bookmarklet if you ever want a fresh one.")
+    print()
+    print("^C to stop.")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nstopped.")
+    finally:
+        httpd.server_close()
+    return 0

satchel_reader-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: satchel-reader
+Version: 0.1.0
+Summary: A local-first reading queue: saves the real article text, not just the link, and makes it genuinely offline-searchable.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/satchel
+Project-URL: Source, https://github.com/MaXiMo000/satchel
+Project-URL: Issues, https://github.com/MaXiMo000/satchel/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/satchel/releases
+Keywords: reading,offline,full-text-search,sqlite,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: trafilatura>=2.0
+Dynamic: license-file
+
+# satchel
+
+**A tiny local archive of the actual things you read.**
+
+[![ci](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/satchel/actions/workflows/ci.yml)
+
+Most "read later" tools save a URL. The link rots, the site adds a
+paywall, or you're offline — and the thing you saved is gone. `satchel`
+fetches the page once, extracts the actual article text (not the nav, not
+the related-links box, not the footer), and stores it in one local SQLite
+file with real full-text search. No server, no account, no network needed
+to search what you've already saved.
+
+```
+$ satchel add https://example.com/some-article
+saved #4: Why Local-First Software Is Worth the Extra Effort
+
+$ satchel search "FTS5"
+#4    Why Local-First Software Is Worth the Extra Effort  (https://example.com/some-article)
+
+$ satchel read 4
+Why Local-First Software Is Worth the Extra Effort
+by Jordan Rivers
+
+Most reading tools save a link and call it done...
+```
+
+Save with one click instead of a terminal: `satchel serve` runs a local
+listener and prints a bookmarklet — click it on any page and that page is
+saved through the exact same pipeline `add` uses. See "Capture" below.
+
+## How
+
+- `fetch.py` — plain `urllib` GET. Stdlib, no dependency for the easy
+  part. Always rejects non-http(s) schemes; a URL that didn't come from
+  the person running satchel (see "Capture") is additionally checked
+  against loopback/private/link-local address space before and after
+  every redirect hop, not just the first one.
+- `capture.py` — fetch → extract → store, in one place. Both `add` and the
+  capture listener call this; there is exactly one add pipeline.
+- `extract.py` — wraps [trafilatura](https://github.com/adbar/trafilatura)
+  to pull title/author/main-text out of real HTML, correctly skipping
+  navigation, ads, and related-links boilerplate. Boilerplate-stripping is
+  exactly the kind of thing that looks fine on a hand-rolled test page and
+  breaks on the next real site's markup — not worth reimplementing.
+- `db.py` — one SQLite file, an FTS5 virtual table kept in sync with the
+  real table via triggers (external-content FTS5: the searchable index
+  isn't a second copy of the truth that can drift from the first).
+- `serve.py` — the local capture listener (below).
+
+## Install
+
+```bash
+pip install satchel-reader        # the command it installs is `satchel`
+```
+
+Or from a checkout, for development:
+
+```bash
+pip install -e .
+```
+
+## Use
+
+```bash
+satchel add <url>          # fetch, extract, save
+satchel list                # everything saved
+satchel search <query>      # full-text search
+satchel read <id>           # print an article's full text
+satchel serve                # one-click capture -- see below
+```
+
+All commands take `--db path/to/file.db`. The default, if you don't pass
+one, is `~/.local/share/satchel/satchel.db` (respecting `XDG_DATA_HOME`) —
+one stable location regardless of which directory you happen to run the
+command from, not `./satchel.db` in the current directory. Run
+`satchel --help` to see the exact resolved path on your machine.
+
+Saving the same article twice — via a tracking link, a shortener, or a
+plain `http://` URL the site itself upgrades to `https://` — is one
+duplicate, not two. `add` normalizes the URL it's given, follows
+redirects, and normalizes the *actual* address the server served before
+checking for a duplicate: it defers to what the server says, rather than
+guessing at a scheme policy.
+
+## Capture
+
+```bash
+$ satchel serve
+satchel capture listening on http://127.0.0.1:8765  (db: ~/.local/share/satchel/satchel.db)
+
+Drag this to your bookmarks bar, then click it on any page to save it:
+
+  javascript:fetch('http://127.0.0.1:8765/add?token=...&url='+encodeURIComponent(location.href))...
+
+^C to stop.
+```
+
+Drag the printed link to your bookmarks bar. Click it on any page while
+`serve` is running, and that page goes through the same fetch/extract/save
+pipeline as `satchel add` — no terminal required for the thing you do most
+often.
+
+**This changes the threat model, and it's handled, not ignored.** While
+`serve` is running, any tab open in your browser can send it a request —
+a browser's same-origin policy stops a page from *reading* a
+cross-origin response it wasn't granted, but not from *sending* the
+request in the first place. Without a shared secret, that would be an
+open invitation for any open tab to make satchel fetch an arbitrary URL.
+So: the listener only binds to `127.0.0.1`, a fresh token is generated
+every time you run `serve` and only ever appears in the bookmarklet you
+just dragged, and every captured URL is checked against loopback,
+private (RFC1918), link-local (this is what closes off
+`169.254.169.254`-style cloud metadata endpoints), reserved, and
+multicast address space — before the first request, and again on every
+redirect hop, since checking only the first hop would let a URL redirect
+somewhere private after passing the initial check.
+
+What that guard does *not* claim: it validates a hostname's DNS answer at
+the moment it's checked, it doesn't pin the connection to that exact
+resolved address. A DNS-rebinding attacker with a fast-expiring record
+could in principle still slip a private address past the check and have
+the actual connection re-resolve to it. Closing that fully means
+connecting to a pinned IP rather than by hostname — real added complexity
+for a personal tool's local listener. This is a deliberate, documented
+partial mitigation, not a claim that it's unbreakable.
+
+Direct `satchel add <url>` from your own terminal is **not** restricted
+this way — typing your own local dev server's URL to save a draft you're
+writing is a legitimate thing to do, and you are not a threat to
+yourself.
+
+## Test
+
+```bash
+python tests/test_satchel.py
+```
+
+Extraction is tested against a fixture HTML file (`tests/fixtures/`), not
+the network — a real bug was caught this way during development: an
+ambiguous byline (`"By Jordan Rivers · September 2026"` in one text node)
+made trafilatura fold part of the date into the author field. Fixed by
+making the fixture look like well-structured real markup (byline and date
+as separate elements) rather than loosening the assertion.
+
+The capture listener is tested the same way it's actually used: a real
+`http.server.HTTPServer` runs in a background thread and gets real HTTP
+requests, including SSRF attempts against loopback and link-local
+addresses — checked with the *correct* token, since the interesting
+question is whether the guard holds once someone's past the door, not
+whether the door itself works.
+
+## What's deliberately not here yet
+
+No tagging, no folders, no read/unread state — a flat list plus full-text
+search covers the actual workflow (encounter → capture → search → read);
+add these when a flat list genuinely stops being enough, not before. No
+multi-device sync — one local file is the whole pitch, and sync is a
+separate, harder problem this project isn't trying to solve. No AI
+summarization, no embeddings, no recommendation engine: this is an
+archive of what you actually read, not a platform.
+
+MIT licensed.

satchel_reader-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+satchel/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+satchel/capture.py,sha256=ZRxgqhjSeOqTTlPLN8qWj7FG_RUv9O9b8lir6Bq6fzI,1923
+satchel/cli.py,sha256=AKX34cOC0fCy7zxBcT1UCsYLtOwnOr_oFeC66b0A_-I,3253
+satchel/db.py,sha256=mSorGNBIFGVD7ZmklVRon_N6klXADzX9Y-ozBzu-Qkk,3729
+satchel/extract.py,sha256=H11cT9e3gTPRNzpeES5nn3TRLGwSClNbktkKdCcPlQo,1274
+satchel/fetch.py,sha256=72oYJKMJx677kjaEWfutkowQxyMPsNPlVlApDvrZWMM,5290
+satchel/serve.py,sha256=RWbFMiotHI7OPGcb3szcBZFkHzCvcsljjQJojUTHvm4,4355
+satchel_reader-0.1.0.dist-info/licenses/LICENSE,sha256=b3BQUid5-O27uBJjQzkF_jTy6vX5FMSPTuFoTlCZyI0,1069
+satchel_reader-0.1.0.dist-info/METADATA,sha256=NF2-SGBAvbfUTvBECT7kJ2dqwZtYjk9KGEugb56PlhU,8103
+satchel_reader-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+satchel_reader-0.1.0.dist-info/entry_points.txt,sha256=wUJy_vkKRfDDqfdLi1LLNAYuPmYb2mOc7GgCzSnPIXs,45
+satchel_reader-0.1.0.dist-info/top_level.txt,sha256=LHfrnlGwK0nEpa7n3HPfFT55Dxfxzi9B1iKw2Qo7PzU,8
+satchel_reader-0.1.0.dist-info/RECORD,,

satchel_reader-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

satchel_reader-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+satchel = satchel.cli:main

satchel_reader-0.1.0.dist-info/licenses/LICENSE

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

satchel_reader-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+satchel