hf-auth-helper 0.1.0__tar.gz

hf_auth_helper-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff format --check .
+      - run: ruff check .
+      - run: ty check src tests
+      - run: pytest --cov=src/hf_auth_helper --cov-fail-under=85
+      - name: Mutation testing behind the kill-rate floor
+        run: python scripts/check-mutation.py --min-kill-rate 80
+      - name: Audit dependencies
+        run: |
+          python -m pip freeze --exclude-editable > /tmp/requirements.txt
+          uvx pip-audit -r /tmp/requirements.txt --disable-pip --no-deps
+      - run: uvx slophammer-py@0.4.0 dry .
+      - run: uvx slophammer-py@0.4.0 check .

hf_auth_helper-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,139 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: publish-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    # PyPI trusted publishing requires a GitHub-hosted runner.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Validate release tag
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin main --depth=1
+
+          uv run --python 3.12 python - <<'PY'
+          import os
+          import re
+          import subprocess
+          import sys
+          import tomllib
+
+          release_tag = os.environ.get("RELEASE_TAG", "")
+          release_sha = os.environ.get("RELEASE_SHA", "")
+
+          if not re.fullmatch(r"v\d+\.\d+\.\d+", release_tag):
+              sys.exit(f"Release tags must match vX.Y.Z; received {release_tag or '<missing>'}.")
+
+          with open("pyproject.toml", "rb") as handle:
+              version = tomllib.load(handle)["project"]["version"]
+          expected = f"v{version}"
+          if release_tag != expected:
+              sys.exit(
+                  f"Release tag {release_tag} does not match pyproject version {version}; "
+                  f"expected {expected}."
+              )
+
+          ancestor = subprocess.run(
+              ["git", "merge-base", "--is-ancestor", release_sha, "origin/main"],
+              check=False,
+          )
+          if ancestor.returncode != 0:
+              sys.exit(f"Tagged commit {release_sha} is not contained in origin/main.")
+
+          print(f"Release tag {release_tag} matches pyproject.toml and points to origin/main.")
+          PY
+
+      - name: Ensure version is not already published
+        run: |
+          set -euo pipefail
+          version="$(uv run --python 3.12 python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          status="$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/hf-auth-helper/$version/json")"
+          if [ "$status" = "200" ]; then
+            echo "hf-auth-helper@$version is already published on PyPI."
+            exit 1
+          fi
+          echo "Publishing hf-auth-helper@$version"
+
+      - name: Validate package
+        run: |
+          uv run --python 3.12 --extra dev ruff format --check .
+          uv run --python 3.12 --extra dev ruff check .
+          uv run --python 3.12 --extra dev ty check src tests
+          uv run --python 3.12 --extra dev pytest --cov=src/hf_auth_helper --cov-fail-under=85
+          uv run --python 3.12 --extra dev python scripts/check-mutation.py --min-kill-rate 80
+          uv export --python 3.12 --extra dev --format requirements.txt --no-emit-project --no-hashes --output-file /tmp/requirements.txt
+          uvx pip-audit -r /tmp/requirements.txt --disable-pip --no-deps
+          uvx slophammer-py@0.4.0 dry .
+          uvx slophammer-py@0.4.0 check .
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          tag="${GITHUB_REF_NAME}"
+          version="${tag#v}"
+          notes_file="$(mktemp)"
+
+          cat > "$notes_file" <<EOF
+          Published hf-auth-helper to PyPI.
+
+          Install with:
+
+          \`\`\`sh
+          uvx hf-auth-helper==$version agent login
+          \`\`\`
+
+          Package: https://pypi.org/project/hf-auth-helper/$version/
+          EOF
+
+          if gh release view "$tag" >/dev/null 2>&1; then
+            gh release edit "$tag" \
+              --title "hf-auth-helper v$version" \
+              --notes-file "$notes_file" \
+              --draft=false \
+              --prerelease=false \
+              --verify-tag
+          else
+            gh release create "$tag" \
+              --title "hf-auth-helper v$version" \
+              --notes-file "$notes_file" \
+              --verify-tag
+          fi

hf_auth_helper-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.venv/
+uv.lock
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+mutants/
+*.env

hf_auth_helper-0.1.0/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md
+
+These instructions apply to this repository.
+
+## Commands To Run Before Finishing
+
+```sh
+ruff format --check .
+ruff check .
+ty check src tests
+pytest --cov=src/hf_auth_helper --cov-fail-under=85
+python scripts/check-mutation.py --min-kill-rate 80
+uvx slophammer-py@0.4.0 check .
+```
+
+CI runs the same gates; do not finish with any of them red.
+
+## Rules
+
+- Python 3.12+, standard library only in `src/` — this tool must stay
+  runnable as a dependency-free single install. Dev tooling may use
+  dependencies; shipped code may not.
+- Type annotations on all public functions and meaningful helpers. No
+  explicit `Any`; dynamic JSON is narrowed at the boundary
+  (see `scopes.py` for the pattern).
+- Security invariant: scope classification fails closed. Unknown permissions
+  are violations. Never widen `SAFE_PERMISSIONS` without a test proving the
+  permission cannot mutate or delete Hub content.
+- Never print, log, or persist token values except where the user explicitly
+  chose to store them.
+- Keep domain logic (scope evaluation, URL building) free of IO. Network and
+  filesystem access belong in the CLI layer only.
+- Add or update tests for every behavior change.
+
+## Slophammer
+
+Quality gates are enforced with Slophammer standards:
+https://raw.githubusercontent.com/dutifuldev/slophammer/refs/heads/main/docs/AGENT_ENTRYPOINT.md

hf_auth_helper-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Onur Solmaz
+
+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.
+

hf_auth_helper-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: hf-auth-helper
+Version: 0.1.0
+Summary: Set up safe, scoped Hugging Face authentication for agents: propose-only tokens, verification, and profiles.
+Project-URL: Repository, https://github.com/osolmaz/hf-auth-helper
+Author-email: Onur Solmaz <onur@solmaz.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,huggingface,propose-only,security,token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mutmut>=3.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: ty>=0.0.9; extra == 'dev'
+Requires-Dist: typeguard>=4.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hf-auth-helper
+
+Set up safe, scoped Hugging Face authentication for agents.
+
+Coding agents that read untrusted content (web pages, issues, datasets) can be
+prompt-injected. If such an agent holds a normal `write` token, one injection
+can delete your datasets, Spaces, and buckets. `hf-auth-helper` sets up
+**propose-only** access instead: the agent can read and open pull requests,
+but a human has to merge — nothing the agent does is irreversible.
+
+## Usage
+
+```sh
+uvx hf-auth-helper agent login
+```
+
+One interactive command:
+
+1. **Recommended or customize** — accept the field-tested access settings,
+   or answer plain-language yes/no questions ("Read gated models?", "Read
+   your billing usage?", …) to narrow them. Reading repo contents and
+   opening pull requests are always included; write access never is.
+2. **Organizations** — if you're already logged into the `hf` CLI, your orgs
+   are detected and offered as a checklist; otherwise enter names manually.
+3. **Token form** — a summary of what the token will be able to do, then the
+   Hugging Face token page URL with your scopes preselected. Open it on any
+   device (the tool assumes you may be SSH'd into a remote box and only
+   opens a local browser if you say yes); name the token and click create.
+4. **Verification** — paste the token (input stays hidden) and it is checked
+   against the Hub: if its scopes allow anything beyond reading and opening
+   pull requests, it is **refused** with the violating permissions named,
+   and nothing is stored. Differences from what you configured are reported.
+5. **Storage** — keep it as a named `hf` CLI profile (activate with
+   `hf auth switch`), make it the primary token (your current login is
+   preserved as a named profile, never destroyed), or write an `HF_TOKEN=`
+   line into an env file for a single agent process.
+
+Scripting (no prompts when not a TTY; flags select resources and
+destinations, never scopes):
+
+```sh
+uvx hf-auth-helper agent login --org my-org --profile my-agent
+uvx hf-auth-helper agent login --env /path/to/agent/.env
+uvx hf-auth-helper agent login --url-only        # just print the prefill URL
+```
+
+Whatever you select, write capability is limited to opening PRs and
+discussions. A token created this way cannot push to main, merge PRs, modify
+buckets, change settings, or delete anything. What it can still do is *read*
+everything you granted it — see the threat model in
+[docs/SPECIFICATION.md](docs/SPECIFICATION.md) for why "nothing irreversible"
+is the guarantee, not "nothing leaks".
+
+The full behavior contract, threat model, and design rationale live in
+[docs/SPECIFICATION.md](docs/SPECIFICATION.md).
+
+## License
+
+[MIT](LICENSE)

hf_auth_helper-0.1.0/README.md

@@ -0,0 +1,59 @@
+# hf-auth-helper
+
+Set up safe, scoped Hugging Face authentication for agents.
+
+Coding agents that read untrusted content (web pages, issues, datasets) can be
+prompt-injected. If such an agent holds a normal `write` token, one injection
+can delete your datasets, Spaces, and buckets. `hf-auth-helper` sets up
+**propose-only** access instead: the agent can read and open pull requests,
+but a human has to merge — nothing the agent does is irreversible.
+
+## Usage
+
+```sh
+uvx hf-auth-helper agent login
+```
+
+One interactive command:
+
+1. **Recommended or customize** — accept the field-tested access settings,
+   or answer plain-language yes/no questions ("Read gated models?", "Read
+   your billing usage?", …) to narrow them. Reading repo contents and
+   opening pull requests are always included; write access never is.
+2. **Organizations** — if you're already logged into the `hf` CLI, your orgs
+   are detected and offered as a checklist; otherwise enter names manually.
+3. **Token form** — a summary of what the token will be able to do, then the
+   Hugging Face token page URL with your scopes preselected. Open it on any
+   device (the tool assumes you may be SSH'd into a remote box and only
+   opens a local browser if you say yes); name the token and click create.
+4. **Verification** — paste the token (input stays hidden) and it is checked
+   against the Hub: if its scopes allow anything beyond reading and opening
+   pull requests, it is **refused** with the violating permissions named,
+   and nothing is stored. Differences from what you configured are reported.
+5. **Storage** — keep it as a named `hf` CLI profile (activate with
+   `hf auth switch`), make it the primary token (your current login is
+   preserved as a named profile, never destroyed), or write an `HF_TOKEN=`
+   line into an env file for a single agent process.
+
+Scripting (no prompts when not a TTY; flags select resources and
+destinations, never scopes):
+
+```sh
+uvx hf-auth-helper agent login --org my-org --profile my-agent
+uvx hf-auth-helper agent login --env /path/to/agent/.env
+uvx hf-auth-helper agent login --url-only        # just print the prefill URL
+```
+
+Whatever you select, write capability is limited to opening PRs and
+discussions. A token created this way cannot push to main, merge PRs, modify
+buckets, change settings, or delete anything. What it can still do is *read*
+everything you granted it — see the threat model in
+[docs/SPECIFICATION.md](docs/SPECIFICATION.md) for why "nothing irreversible"
+is the guarantee, not "nothing leaks".
+
+The full behavior contract, threat model, and design rationale live in
+[docs/SPECIFICATION.md](docs/SPECIFICATION.md).
+
+## License
+
+[MIT](LICENSE)