Merge pull request #35 from pullboxapp/develop

release: promote LibGen 1.0.0 and Anna's Archive 1.0.2

Author: DeusExTaco

.github/scripts/resolve-provider-release.py

@@ -16,7 +16,7 @@
     r"(?:(?:a|b|rc)(?:0|[1-9][0-9]*))?"
 )
 TAG = re.compile(
-    rf"(?P<provider>getcomics|annas-archive|synthetic)-v"
+    rf"(?P<provider>getcomics|annas-archive|libgen|synthetic)-v"
     rf"(?P<version>{RELEASE_VERSION.pattern})"
 )
 OWNER = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?")
@@ -59,6 +59,13 @@ class ProviderRelease(NamedTuple):
         title="Pullbox Anna's Archive Direct Download Provider",
         description="Optional Anna's Archive discovery provider for Pullbox direct downloads",
     ),
+    "libgen": ProviderDefinition(
+        dockerfile="docker/Dockerfile.libgen",
+        version_file="providers/libgen/pyproject.toml",
+        image_name="pullbox-provider-libgen",
+        title="Pullbox Library Genesis Direct Download Provider",
+        description="Optional LibGen discovery provider for Pullbox direct downloads",
+    ),
     "synthetic": ProviderDefinition(
         dockerfile="docker/Dockerfile.synthetic",
         version_file="pyproject.toml",

.github/scripts/select-latest-provider-release.py

@@ -8,7 +8,7 @@
 import re
 from pathlib import Path
 
-PROVIDERS = {"getcomics", "annas-archive", "synthetic"}
+PROVIDERS = {"getcomics", "annas-archive", "libgen", "synthetic"}
 STABLE_VERSION = r"(?P<major>0|[1-9][0-9]*)\.(?P<minor>0|[1-9][0-9]*)\.(?P<patch>0|[1-9][0-9]*)"
 
 

.github/security/container-vulnerability-baseline.json

@@ -1,12 +1,13 @@
 {
   "schema_version": 1,
-  "reviewed_on": "2026-08-23",
-  "expires_on": "2026-11-01",
-  "base_image": "python:3.14-slim@sha256:cea0e6040540fb2b965b6e7fb5ffa00871e632eef63719f0ea54bca189ce14a6",
+  "reviewed_on": "2026-08-26",
+  "expires_on": "2026-11-26",
+  "base_image": "python:3.14-slim@sha256:83ff1d245a3d57d04152252d3ef9cb361494d0b3395abd65a5ebe91c401c8e83",
   "images": {
     "synthetic": "python-3.14-slim",
     "getcomics": "python-3.14-slim",
-    "annas-archive": "python-3.14-slim"
+    "annas-archive": "python-3.14-slim",
+    "libgen": "python-3.14-slim"
   },
   "profiles": {
     "python-3.14-slim": [
@@ -88,24 +89,6 @@
         "severity": "High",
         "rationale": "Inherited from the pinned Python 3.14 Debian base; no supported-line fix is currently available."
       },
-      {
-        "id": "CVE-2026-11940",
-        "package": "python",
-        "severity": "High",
-        "rationale": "Inherited from Python 3.14; the available fix is outside the supported Python line."
-      },
-      {
-        "id": "CVE-2026-11972",
-        "package": "python",
-        "severity": "High",
-        "rationale": "Inherited from Python 3.14; the available fix is outside the supported Python line."
-      },
-      {
-        "id": "CVE-2026-15308",
-        "package": "python",
-        "severity": "High",
-        "rationale": "Inherited from Python 3.14; the available fix is outside the supported Python line."
-      },
       {
         "id": "CVE-2026-41992",
         "package": "gzip",
@@ -189,24 +172,6 @@
         "package": "perl-base",
         "severity": "High",
         "rationale": "Inherited from the pinned Python 3.14 Debian base; no supported-line fix is currently available."
-      },
-      {
-        "id": "CVE-2026-14456",
-        "package": "libssl3t64",
-        "severity": "High",
-        "rationale": "Inherited from the pinned Python 3.14 Debian base. The affected QUIC listener code is not enabled or used by these HTTP-only provider images, and no supported-line upstream fix is currently available."
-      },
-      {
-        "id": "CVE-2026-14456",
-        "package": "openssl",
-        "severity": "High",
-        "rationale": "Inherited from the pinned Python 3.14 Debian base. The affected QUIC listener code is not enabled or used by these HTTP-only provider images, and no supported-line upstream fix is currently available."
-      },
-      {
-        "id": "CVE-2026-14456",
-        "package": "openssl-provider-legacy",
-        "severity": "High",
-        "rationale": "Inherited from the pinned Python 3.14 Debian base. The affected QUIC listener code is not enabled or used by these HTTP-only provider images, and no supported-line upstream fix is currently available."
       }
     ]
   }

.github/workflows/container-security.yml

@@ -49,13 +49,16 @@ jobs:
           - synthetic
           - getcomics
           - annas-archive
+          - libgen
         include:
           - provider: synthetic
             dockerfile: docker/Dockerfile.synthetic
           - provider: getcomics
             dockerfile: docker/Dockerfile.getcomics
           - provider: annas-archive
             dockerfile: docker/Dockerfile.annas-archive
+          - provider: libgen
+            dockerfile: docker/Dockerfile.libgen
     env:
       IMAGE: pullbox-provider-${{ matrix.provider }}:security-${{ github.run_id }}
     steps:
@@ -133,13 +136,16 @@ jobs:
           - synthetic
           - getcomics
           - annas-archive
+          - libgen
         include:
           - provider: synthetic
             dockerfile: docker/Dockerfile.synthetic
           - provider: getcomics
             dockerfile: docker/Dockerfile.getcomics
           - provider: annas-archive
             dockerfile: docker/Dockerfile.annas-archive
+          - provider: libgen
+            dockerfile: docker/Dockerfile.libgen
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up QEMU

.github/workflows/provider-latest.yml

@@ -17,6 +17,7 @@ on:
         options:
           - getcomics
           - annas-archive
+          - libgen
           - synthetic
 
 permissions:
@@ -46,7 +47,7 @@ jobs:
           REQUESTED_PROVIDER: ${{ github.event.client_payload.provider || inputs.provider }}
         run: |
           case "${REQUESTED_PROVIDER}" in
-            getcomics|annas-archive|synthetic) ;;
+            getcomics|annas-archive|libgen|synthetic) ;;
             *)
               echo "::error::Unsupported provider reconciliation request: ${REQUESTED_PROVIDER}"
               exit 1

.github/workflows/provider-release.yml

@@ -10,6 +10,7 @@ on:
     tags:
       - "getcomics-v*"
       - "annas-archive-v*"
+      - "libgen-v*"
       - "synthetic-v*"
   workflow_dispatch:
     inputs:
@@ -20,6 +21,7 @@ on:
         options:
           - getcomics
           - annas-archive
+          - libgen
           - synthetic
 
 permissions:

.github/workflows/release.yml

@@ -81,6 +81,7 @@ jobs:
           case "${PROVIDER}" in
             getcomics) RELEASE_NAME="GetComics Provider" ;;
             annas-archive) RELEASE_NAME="Anna's Archive Provider" ;;
+            libgen) RELEASE_NAME="Library Genesis Provider" ;;
             synthetic) RELEASE_NAME="Synthetic Provider" ;;
             *)
               echo "::error::Unexpected provider in trusted release metadata: ${PROVIDER}"

.gitignore

@@ -94,11 +94,8 @@ ipython_config.py
 #   install all needed dependencies.
 # Pipfile.lock
 
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-# uv.lock
+# This repository uses pip and pyproject metadata; local uv resolution is not a build input.
+uv.lock
 
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.

README.md

@@ -7,15 +7,19 @@ Optional, separately deployed direct-download discovery providers for
 
 This repository provides the version-one Pullbox direct-download protocol,
 Python DTO package, compatibility policy, conformance runner, synthetic
-reference provider, and the official GetComics and Anna's Archive providers.
-Production images are independently versioned, multi-architecture, scanned,
-signed, and published to GHCR and Docker Hub.
+reference provider, the official GetComics and Anna's Archive providers, and a
+release-gated LibGen community provider. Published production images are
+independently versioned, multi-architecture, scanned, signed, and available
+from GHCR and Docker Hub.
 
 ## Source Providers
 
 - GetComics: metadata discovery and stateless artifact-route normalization.
 - Anna's Archive: metadata discovery with opt-in member fast-download
   resolution; a member secret is required only by the resolve operation.
+- LibGen: bounded HTML discovery, keyed metadata enrichment, and same-source
+  generic HTTPS resolution with an editable validated source origin. Its image
+  remains independently gated until the LibGen release decision is approved.
 
 Each provider will run as an independent, stateless OCI service and implement a
 versioned, language-neutral Pullbox provider contract.
@@ -38,6 +42,7 @@ providers/
   synthetic/
   getcomics/
   annas_archive/
+  libgen/
 tests/
   conformance/
   fixtures/
@@ -66,7 +71,7 @@ coverage gate. `make docker-conformance` builds the digest-pinned synthetic
 image and proves the protocol over an internal-only Docker network.
 `make security-check` runs Bandit and a strict dependency audit.
 
-The source-provider Compose harness builds both providers, waits for
+The source-provider Compose harness builds all source providers, waits for
 process-only socket healthchecks, and validates authenticated manifests over an
 internal-only network. Process healthchecks intentionally do not call upstream
 sources. The harness uses generated test credentials and performs no live
@@ -80,7 +85,7 @@ Pull requests run four stable aggregate checks: `CI Required`,
 default permissions. The security gate includes Gitleaks, strict Python
 dependency auditing, Bandit, dependency review, and CodeQL's extended security
 queries scoped to shipped provider code. Container checks build and smoke-test
-all three runtime images, scan them with Grype, and prove Linux AMD64 and ARM64
+all four runtime images, scan them with Grype, and prove Linux AMD64 and ARM64
 builds without publishing.
 
 High and Critical findings inherited from the pinned public Python base image
@@ -126,6 +131,29 @@ the allowlisted native control types in the contract. Pullbox validates those
 controls, renders its own settings UI, and rejects provider-supplied HTML,
 JavaScript, or unknown configuration fields.
 
+### Native Provider Configuration
+
+Provider settings use a closed, documented vocabulary:
+
+- `enum` declares closed choices. The configured value must be one of the
+  declared values.
+- `x-pullbox-suggestions` declares editable HTTPS origin suggestions. A user may
+  enter another safe public HTTPS origin because the list is not an allowlist.
+- `x-pullbox-source-origin` marks a field as the provider's effective source
+  origin for provider-scoped link and browser-resolver policy.
+
+Suggestions and source-origin marking are independent controls. A provider may
+offer editable suggestions without changing its source origin, or allow a custom
+source origin without supplying suggestions. Pullbox validates suggested and
+default origins before rendering or saving them and validates the selected
+origin again before use.
+
+Search candidates may include an optional content fingerprint formatted as
+`md5:<32 lowercase hexadecimal characters>`. It must remain stable only while
+the candidate bytes are identical; changed bytes require a new fingerprint.
+Pullbox uses it only for deduplication and fallback grouping, never as a security
+or authenticity checksum, and does not treat it as durable library metadata.
+
 ## Source Provider Behavior
 
 ### GetComics
@@ -141,8 +169,8 @@ after a recognized challenge. It never downloads or proxies artifact bytes.
 The Anna's Archive provider is an explicit opt-in integration. Its configurable
 official URL accepts only `https://annas-archive.gl`,
 `https://annas-archive.pk`, or `https://annas-archive.gd`. Pullbox renders the
-field as an editable URL input with those exact choices suggested; lookalike and
-arbitrary domains remain rejected. Unattended resolution requires the user's
+field as a closed selector with those exact choices; lookalike and arbitrary
+domains remain rejected. Unattended resolution requires the user's
 member fast-download secret; free slow-download automation, CAPTCHA bypass,
 unofficial domains, and payload proxying are not supported.
 
@@ -153,6 +181,22 @@ quota, source availability, and malformed responses remain distinct failures.
 Opening search-result details must not call resolve because a fast-link request
 may consume source quota.
 
+Search attempts the selected official Anna's Archive page first. When that page
+is blocked by a browser challenge, is temporarily unavailable, or returns no
+candidates, the provider performs a bounded fallback against the LibGen comics
+catalog. Only candidates with a matching lowercase LibGen ID and MD5 content
+fingerprint are considered for Anna's Archive discovery, with canonical files
+listed before mobile derivatives. Catalog presence does not guarantee that Anna
+offers a member fast-download route, so availability is verified only when the
+user grabs the result. Catalog-derived candidates intentionally do not expose a
+cross-provider fingerprint to Pullbox: if Anna cannot resolve the record,
+Pullbox reports that failure instead of silently downloading it from LibGen.
+Resolution still uses the official member fast-download JSON API, and the member
+secret is never sent to LibGen. This fallback covers only Anna's Archive records
+sourced from LibGen and does not claim parity with Anna's Archive's complete
+catalog. The Anna's Archive image includes the catalog-discovery dependency and
+does not require a separate LibGen provider container.
+
 Successful resolves may report provider-generic remaining/limit/window quota
 telemetry. The response intentionally excludes account identity and download
 history. Pullbox stores only the latest capacity observation, applies its
@@ -161,6 +205,22 @@ accepted source when Anna's Archive is unavailable. Manual grabs may use the
 reserved slots. Quota errors may include a bounded `retry_after_seconds` hint
 so Pullbox can recover automatically even without an earlier capacity report.
 
+### LibGen
+
+The LibGen provider is a separately packaged community integration. It accepts
+the documented LibGen origins as editable suggestions, validates the selected
+public HTTPS origin before every operation, and attempts ordinary HTTP before
+using a request-scoped browser resolver for a recognized source gate. Search is
+bounded to three query variants and keyed metadata enrichment; positive and
+negative caches are process-local and bounded.
+
+Candidate and artifact identity are revalidated by lowercase MD5, keyed file
+metadata, and edition relationships before a same-source public HTTPS artifact
+is returned. The MD5 is content identity and deduplication evidence, not a
+security guarantee. The provider does not proxy payload bytes, retain resolver
+cookies, expose full artifact URLs in logs, or reuse Anna's Archive links.
+Known-source failover is bounded to one alternate origin per operation.
+
 ## Deployment And Registration
 
 Provider services are deployed separately from Pullbox. An operator creates a
@@ -187,8 +247,11 @@ either registry; both names resolve to the same signed digest.
 
 | Provider | GHCR | Docker Hub |
 | --- | --- | --- |
-| GetComics | `ghcr.io/pullboxapp/pullbox-provider-getcomics:1.0.0` | `docker.io/pullbox/pullbox-provider-getcomics:1.0.0` |
-| Anna's Archive | `ghcr.io/pullboxapp/pullbox-provider-annas-archive:1.0.0` | `docker.io/pullbox/pullbox-provider-annas-archive:1.0.0` |
+| GetComics | `ghcr.io/pullboxapp/pullbox-provider-getcomics:1.0.2` | `docker.io/pullbox/pullbox-provider-getcomics:1.0.2` |
+| Anna's Archive | `ghcr.io/pullboxapp/pullbox-provider-annas-archive:1.0.1` | `docker.io/pullbox/pullbox-provider-annas-archive:1.0.1` |
+
+LibGen image publication is intentionally omitted from this table until its
+independent release gate is approved and a numbered provider release exists.
 
 Pin a numbered version or the immutable digest in production. `latest` tracks
 only the newest stable provider release; prerelease and manual `edge` builds do

docker/Dockerfile.annas-archive

@@ -1,19 +1,30 @@
-ARG PYTHON_BASE=python:3.14-slim@sha256:cea0e6040540fb2b965b6e7fb5ffa00871e632eef63719f0ea54bca189ce14a6
+ARG PYTHON_BASE=python:3.14-slim@sha256:83ff1d245a3d57d04152252d3ef9cb361494d0b3395abd65a5ebe91c401c8e83
 
-FROM ${PYTHON_BASE} AS build
+FROM ${PYTHON_BASE} AS security-patched
+
+RUN apt-get update && \
+    apt-get install --yes --no-install-recommends \
+        libssl3t64=3.5.7-1~deb13u2 \
+        openssl=3.5.7-1~deb13u2 \
+        openssl-provider-legacy=3.5.7-1~deb13u2 && \
+    rm -rf /var/lib/apt/lists/*
+
+FROM security-patched AS build
 
 ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
     PIP_NO_CACHE_DIR=1
 
 WORKDIR /build
 
 COPY packages/provider_contract packages/provider_contract
+COPY providers/libgen providers/libgen
 COPY providers/annas_archive providers/annas_archive
 
 RUN python -m pip wheel --wheel-dir /wheels ./packages/provider_contract && \
+    python -m pip wheel --find-links /wheels --wheel-dir /wheels ./providers/libgen && \
     python -m pip wheel --find-links /wheels --wheel-dir /wheels ./providers/annas_archive
 
-FROM ${PYTHON_BASE} AS runtime
+FROM security-patched AS runtime
 
 ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
     PIP_NO_CACHE_DIR=1 \