rootme-sdk 0.3.0__tar.gz

rootme_sdk-0.3.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+coverage.xml
+dist/
+.direnv/
+.secrets/
+.env
+.env.*
+!.env.example
+.pypirc
+.audit-requirements.txt
+build/
+*.log
+*.egg-info/

rootme_sdk-0.3.0/AGENTS.md

@@ -0,0 +1,134 @@
+# Agent guidelines — rootme-sdk
+
+## Scope and language
+
+Build the Python library described in [REQUIREMENTS.md](REQUIREMENTS.md). Keep it
+small; do not add a server, solver or unrelated application. Choose implementation
+details from verified platform behavior rather than guessed endpoints. Scope is
+accounts and challenges, with password/session authentication; do not add API-key
+authentication, messaging, community or virtual-environment management.
+
+Write repository content in English: code, comments, documentation, commits and
+PRs. Speak French with the maintainer. Never add `Co-Authored-By` or other
+authorship trailers to commits.
+
+## Python code and architecture
+
+- Use `src/rootme_sdk/`. Start with focused modules and create subpackages only
+  when a concern needs multiple modules. Functions stay at most 30 lines; modules
+  stay below 1000 lines. Prefer shallow, coherent packages over speculative layers.
+- DRY, one concern per module, one intent per code path. Keep code linear and
+  avoid abstractions or compatibility branches without a current requirement.
+- State responsibility in names. Avoid `utils`, `helpers`, `misc`, `shared`,
+  `core`, `base` and `tools` as catch-all module/package names. Shared logic has
+  a named owner; do not create a generic `common` tree in advance.
+- Define and preserve import direction. Lower-level transport, parsing and
+  authentication mechanisms must not depend on the public client orchestrating
+  them. No circular imports or unrelated cross-feature dependencies; promote
+  genuinely shared logic to its proper owner instead of duplicating it.
+- `__init__.py` contains public re-exports and `__all__` only: no logic or
+  import-time side effects. Re-export intentional public APIs through the package
+  boundary so consumers do not depend on deep implementation imports.
+- Type the SDK fully and run `mypy --strict`. Validate caller input and external
+  responses at their boundaries, then trust validated data internally. Do not
+  hide unexpected defects with broad `try/except`. Expected network, authentication
+  and platform failures must become explicit SDK outcomes or documented errors.
+- In production code, use `assert` only for type narrowing, never for runtime
+  validation or control flow.
+- Keep the public interface deliberate and simple. Unlike the source SaaS,
+  this library has external consumers: preserve published contracts or make
+  breaking changes explicit in the version and migration guidance. Update all
+  internal callers and tests in the same change; no speculative legacy paths.
+- Keep runtime dependencies minimal. Password authentication manages JavaScript
+  assistance and headed browser setup automatically; callers supply only credentials.
+  Require a working graphical display. Do not reintroduce headless, HTTP-only or
+  manual login paths. Await native redirects/AJAX completion and verify account-only
+  access before reporting authentication success; a cookie alone is insufficient.
+  Browser support is installed by default, but its runtime starts only when
+  needed. Do not configure the consuming application's logging or emit secrets.
+
+## Tooling and quality gates
+
+- `pyproject.toml` owns package metadata, the release version, Python support,
+  dependencies and tool configuration. Use `uv` and commit `uv.lock`.
+- `flake.nix` and `flake.lock` provide a reproducible devShell with Python, `uv`,
+  `task`, `gh` and required development tools. Add missing tools there. Do not
+  copy Nix package, NixOS/Home Manager module or binary-distribution machinery.
+- Provide a small `Taskfile.yml`: formatting, lint, typecheck, docstrings, unit
+  tests, package build and an aggregate `task ci`. CI runs the same checks.
+- Ruff handles lint and format; line length is 100. Enforce `ruff check` and
+  `ruff format --check`, strict mypy, and `interrogate --fail-under=100` for
+  applicable SDK docstrings. Use one documented docstring convention.
+- Enforce **100% unit-test coverage of the complete SDK** with pytest/pytest-cov
+  and `--cov-fail-under=100`, locally and in CI. Broader tests cannot compensate
+  for missing unit coverage. Never lower, bypass or remove a quality gate.
+- No `pragma: no cover`, `type: ignore`, `noqa`, blanket missing-import ignores,
+  coverage exclusions or equivalent escapes without an unavoidable, documented
+  constraint. An exception must be narrow and explained beside the suppression.
+- Install a `.githooks/` pre-commit hook running `task ci` once tooling exists;
+  never bypass it with `--no-verify`. Documentation-only bootstrapping does not
+  require implementing the SDK just to validate these initial documents.
+
+## Tests
+
+- Mirror `src/rootme_sdk/` in `tests/unit/`, with one `test_<module>.py` for each
+  executable source module. Keep module ownership explicit; delete matching
+  tests when deleting a module. Re-export-only files need no artificial tests.
+- Test observable behavior and failure cases, including denied access and
+  ambiguous submission outcomes. Mock external boundaries rather than the logic
+  under test. Fixtures contain no credentials, cookies or real submitted answers.
+- All automated tests are offline and independent of a real Root-Me account.
+  Add multi-module scenarios or a local fake service when useful, without live
+  platform integration. Keep scenarios deterministic, isolated and free of fixed
+  sleeps. Do not skip or retry failing tests to obtain green CI.
+- Verify built wheels/source distributions install and expose the typed public
+  interface without contacting Root-Me. Ship typing information (`py.typed`).
+- Keep packaging verification tests offline too. Run dependency advisories and
+  redacted Git history scans separately with `task audit` and `task secrets`.
+
+## Git workflow
+
+- Once a remote `main` exists, fetch it and branch from its current state using
+  `feat/`, `fix/` or `chore/`. Rebase on `main`; do not merge it into the branch.
+  Preserve uncommitted user work. An empty repository needs its initial baseline
+  established before the ordinary PR workflow is possible.
+- Changes land through PRs targeting `main`; no direct pushes to established
+  `main`, force-pushes to `main`, or protection bypasses. Use Conventional Commit
+  PR titles and squash merges: `git log main` is the release history; no separate
+  generated changelog is required.
+- Run `task ci` before committing. Use `gh` to inspect PRs and CI failures; verify
+  an old branch has not already merged before adding commits to it. Watch checks
+  and fix failures. An ordinary PR may merge once required checks pass, subject
+  to the protected-path rule below; monitor the resulting `main` CI run too.
+- Use `.github/CODEOWNERS` for `.github/`, `flake.nix`, `AGENTS.md` and
+  `SECURITY.md`. Merging changes to listed paths requires explicit human approval
+  in the conversation. Prepare and validate the complete change before requesting
+  that approval. Live GitHub protection/governance changes also need explicit
+  approval; missing permissions are reported rather than worked around.
+
+## Releases
+
+- Distribution is a wheel and source archive attached to a GitHub
+  Release. PyPI publication is deferred and disabled unless explicitly enabled
+  with publisher permissions. Merging to `main` does not publish a release.
+  Do not add PyInstaller binaries or Nix packaging.
+- Bump `[project].version` in `pyproject.toml` through a normal PR **before**
+  tagging. Tag the corresponding validated commit on `main` as `vX.Y.Z`; the
+  tag, package metadata and artifact versions must agree.
+- **Never push a release tag or publish a version without explicit human opt-in
+  in the current conversation.** Approval of a release tag authorizes both
+  all currently enabled publication destinations, without a second approval.
+  Never move or delete an existing release tag.
+- The tag-triggered workflow builds and checks the wheel/source archive from
+  that commit, then publishes those artifacts to enabled destinations. Configure
+  authentication securely; never commit tokens. Confirm PyPI ownership/name
+  availability and permissions before enabling its first publication.
+- Watch the workflow to completion. Verify both GitHub assets and clean artifact
+  installation/import, plus the PyPI version/install when publishing is enabled;
+  a successful tag push is not completion.
+- Fix failed releases through the normal workflow. Roll forward with a new
+  version and tag; consumers can pin a previous known-good version. Never rewrite
+  release history. A corrective release still needs explicit tag approval.
+
+These guidelines are self-contained; deployment, frontend, database and Nix
+packaging rules from other applications do not apply to this SDK.

rootme_sdk-0.3.0/API.md

@@ -0,0 +1,87 @@
+# Public API
+
+Import supported names from `rootme_sdk`, not its internal submodules. This is a
+synchronous SDK. Use one client in one thread and close it with a `with` block.
+Its synchronous Playwright browser cannot run in a thread with an active asyncio
+event loop; call the whole client lifecycle from a separate synchronous worker
+when embedding it in an asynchronous application.
+
+## Connection
+
+```python
+from rootme_sdk import RootMeClient
+
+with RootMeClient("your-login", "your-password") as client:
+    page = client.list_challenges(language="en", score=5)
+    for challenge in page.items:
+        print(challenge.id, challenge.title)
+```
+
+Alternatively, `RootMeClient(credentials_file=".secrets/credentials.json")` reads
+`{"login": "...", "password": "..."}` as UTF-8. Supply exactly one credential
+source. An anonymous `RootMeClient()` can read website challenge URLs and categories;
+an ID must first resolve through the authenticated API. Anonymous reads may still
+open a graphical browser for JavaScript verification.
+
+The constructor's optional keyword arguments are `timeout=30` (HTTP seconds),
+`read_retries=1`, `max_retry_delay=5`, and `transport` (an HTTPX transport, useful
+for offline tests). Managed browser login has a separate 180-second timeout;
+`login(..., timeout=180)` can change it. Read retries are bounded and respect
+eligible waiting intervals; authentication and writes are never replayed.
+
+Advanced session reuse accepts `session=Session.load(path)` or
+`spip_session="..."` instead of login credentials. These contain account secrets,
+do not renew expired sessions and do not eliminate later JavaScript verification.
+Ordinary users need only credentials. `client.session.save(path)` is opt-in.
+
+## Account and challenges
+
+| Method | Result and behavior |
+| --- | --- |
+| `login(username, password)` or `login(credentials_file=...)` | `Session`; authenticate/reconnect using the graphical browser |
+| `logout()` | `None`; request server logout, clear local state and close the browser |
+| `close()` | `None`; release browser and HTTP resources |
+| `get_user(identifier)` | `UserProfile`; `id`, `name`, `score`, `position`, additional JSON in `data` |
+| `preferences(language="en")` | `WebPage`; current editable controls in `forms` |
+| `update_preferences(changes, files=None)` | `WebPage`; send selected editable fields once, refreshing hidden tokens |
+| `get_challenge(id)` | `Challenge`; authenticated API metadata, often without a statement |
+| `get_challenge(url)` / `read_challenge(id_or_url)` | `Challenge`; full website statement and resources |
+| `list_challenges(title=None, subtitle=None, language=None, score=None, author_ids=())` | `Collection[Challenge]`; one API page, with `items` and `next_url`; all filters are keyword-only |
+| `iter_challenges(**filters)` | `Iterator[Challenge]`; lazy pagination with native API filter names, such as `lang="en"`, `score=5`, `titre="..."` |
+| `list_categories(language="en")` | `tuple[Category, ...]`; category `title` and `url` |
+| `submit_answer(id_or_url, answer)` | `SubmissionResult`; status, sanitized feedback and optional retry interval |
+| `download(resource_or_https_url, destination=None)` | `bytes`; optionally write to the supplied path; external hosts receive no account cookies |
+
+Language arguments on website methods are keyword-only and accept `en` or `fr`.
+API IDs must be positive integers. `Challenge` exposes `id`, `title`, `score`,
+`category_id`, `url`, `statement`, `statement_html`, `resources` and `data`.
+API fields absent from a response remain `None`; `.data` preserves extra JSON.
+Resources contain a `url` and `label`, including links to services and documentation;
+choose downloadable attachments rather than passing arbitrary service links.
+
+`WebPage` contains `url`, `title`, `text`, `html`, `links` and `forms`.
+Each `WebForm` exposes its name and typed `FormField` controls. Account updates
+support one string per editable control and `Upload(filename, content, content_type)`
+for observed upload controls. Hidden tokens cannot be overridden.
+
+`SubmissionStatus` values are `ACCEPTED`, `REJECTED`, `ALREADY_SOLVED`, `BLOCKED`
+and `INDETERMINATE`. After an indeterminate outcome, inspect account/challenge state
+before deliberately submitting again. Never turn it into an automatic retry loop.
+
+## Errors
+
+All SDK operational exceptions inherit from `RootMeError`. Invalid caller input
+raises `ValueError`; local destination/session file failures can raise `OSError`.
+
+| Exception | Meaning |
+| --- | --- |
+| `AuthenticationRequiredError` | Login required or rejected; `reason` is `missing`, `expired` or `rejected` |
+| `BrowserUnavailableError` | Missing graphical display or browser startup failure |
+| `HumanInterventionRequiredError` | Platform verification unresolved; includes `url` |
+| `RateLimitedError` | Platform rate limit; `retry_after` can be absent |
+| `PermissionDeniedError` | Access denied |
+| `NotFoundError` | Requested resource absent |
+| `NetworkError` | Network operation failed |
+| `UnexpectedResponseError` | Unrecognized or invalid platform response |
+
+See [CAPABILITIES.md](CAPABILITIES.md) for live observations and unresolved limits.

rootme_sdk-0.3.0/CAPABILITIES.md

@@ -0,0 +1,50 @@
+# Capabilities
+
+Authentication uses username/password and reusable web sessions. Official API
+reads reuse the login cookie. Website JavaScript gates can affect public reads.
+
+| Client method | Purpose | Access | Evidence |
+| --- | --- | --- | --- |
+| `RootMeClient(login, password)` / `RootMeClient(credentials_file=...)` | Connect from credentials and manage browser/session internally | Existing account | Both modes observed without human input, including preferences and challenge reads |
+| `login` | Connect/reconnect an existing client, with automatic JS assistance | Existing account | Same managed authentication flow |
+| `logout` | Server logout and local credential erasure | Session for server logout | Route observed; behavior tested offline |
+| `get_challenge(id)` | Metadata and additional API fields | Login session | Detail response observed |
+| `get_challenge(url)`, `read_challenge` | Full statement, resources and access instructions | Website access | Challenge pages observed |
+| `list_challenges`, `iter_challenges` | Filters and pagination | Login session | Documented API; response shapes observed |
+| `list_categories` | Catalogue categories | Website access | 11 categories observed |
+| `get_user` | Account profile, score and available progression data | Login session | Authenticated profile response observed; validations hold solved entries |
+| `preferences` | Editable account field inventory | Web session | modifier_auteur form observed |
+| `update_preferences` | Selected profile changes and file uploads | Web session | Controls observed; tested offline |
+| `submit_answer` | One answer submission and structured result | Web session | Live already-solved response observed; other outcomes tested offline |
+| `download` | Attachments with scoped credentials | Public or same-host session | Tested offline |
+
+## Limits
+
+Password authentication uses only graphical Chrome/Chromium. The SDK finds or
+prepares Chromium automatically, submits credentials once, waits for native login
+completion and verifies the account preferences page before returning a connected
+client. A graphical display and Chromium's system dependencies are prerequisites;
+missing Linux `DISPLAY` is rejected before browser startup. Headless and HTTP-only
+login are not supported. Platform verification, network and rate-limit failures
+are explicit errors; rejected credentials are never silently resubmitted.
+
+Authentication is still at alpha maturity. Both credential sources produced
+successful account/API/challenge reads, but some fresh sessions still returned a
+login page during account verification after positive login feedback. The cause
+is unresolved. Further live checks stopped after an HTTP 429 response. Automated
+unit and packaging checks cannot establish reliable live platform authentication.
+No guarantee of unattended login success is made. Account preference mutations
+also lack live validation; use deliberate, minimal updates.
+
+Submission feedback is read only inside the challenge validation form, using
+observed success/error and SPIP feedback classes. Explicit English/French
+already-solved messages are recognized. HTTP 429 is blocked; ambiguous failures
+and unknown feedback remain indeterminate. Writes are never automatically replayed.
+
+Account updates support one value per control and one file per upload control.
+Preference mutations have not been manually exercised. The SDK exposes account
+and challenge operations only; generic forms are private implementation details.
+
+Source: [official API documentation](https://api.www.root-me.org/?lang=en) and
+manual observations on 2026-10-04. No real answer, credential or account snapshot
+is committed in fixtures.

rootme_sdk-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Use `nix develop`, `uv sync --locked`, and `task ci`. Enable the
+pre-commit hook with `git config core.hooksPath .githooks`. Automated tests are
+offline and independent of Root-Me accounts. Distribution checks prepare locked
+runtime dependencies from the local uv cache, install each artifact in a clean
+environment and verify public exports, version and typing information.
+
+Branch from current main, open a Conventional Commit PR and squash merge after
+checks pass. Required checks are quality (3.13), quality (3.14) and lint-pr-title.
+Also wait for Windows/macOS portability, dependency audit and secret scan checks.
+Governance changes and merges touching CODEOWNERS paths require explicit approval
+in the conversation, as defined in AGENTS.md.
+
+## Without Nix
+
+Install Python 3.13 or 3.14, [uv](https://docs.astral.sh/uv/getting-started/installation/)
+and [Task](https://taskfile.dev/docs/installation), then run the same `uv sync --locked`
+and `task ci` commands. Nix is only a development environment, never a runtime
+requirement. Use Google-style docstrings and the self-contained [AGENTS.md](AGENTS.md)
+coding rules. The public API reference is [API.md](API.md).
+
+`task ci` includes offline packaging guard tests. Run `task audit` separately to
+check the locked runtime dependencies against published vulnerability advisories
+(network access required). Run `task secrets` with Gitleaks installed to scan the
+complete local Git history with redacted findings. Both tools are in the devShell;
+security CI repeats these checks weekly and on changes. Dependency updates arrive
+as ordinary Dependabot PRs and must pass the same checks.
+
+## Releases
+
+The repository and GitHub releases are public. PyPI publication is deferred:
+the release workflow skips it unless the repository variable PUBLISH_PYPI is true.
+
+1. Set the version in pyproject.toml through a validated PR and merge.
+2. Wait for successful CI on that exact main commit.
+3. Obtain explicit release approval, then tag that commit as vX.Y.Z and push.
+4. Watch release.yml: it verifies version/main CI, checks and builds artifacts,
+   then attaches the wheel and source archive to the GitHub release.
+5. Verify assets and install/import each distribution from a clean environment.
+
+Never rewrite release tags or published versions. Correct failures with a normal
+PR and a newly approved version/tag.
+
+## Future PyPI setup
+
+Enable PyPI only after explicit authorization and project ownership checks.
+Configure a [Pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/):
+
+- Project: rootme-sdk; confirm name availability and ownership.
+- GitHub owner/repository: Thomas97460/rootme-sdk.
+- Workflow: release.yml; GitHub environment: pypi.
+
+After the decision to open the repository, create that environment and set
+PUBLISH_PYPI=true. The workflow uses OIDC without
+stored long-lived tokens and publishes the same artifacts as GitHub. Once enabled,
+release verification also checks the PyPI version and a clean installation from
+PyPI. This repository's workflow also requires public repository visibility.
+See [PUBLISHING.md](PUBLISHING.md) for the remaining owner actions and release procedure.

rootme_sdk-0.3.0/LICENSE

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

rootme_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: rootme-sdk
+Version: 0.3.0
+Summary: Unofficial typed Python SDK for Root-Me accounts and challenges
+Project-URL: Repository, https://github.com/Thomas97460/rootme-sdk
+Project-URL: Documentation, https://github.com/Thomas97460/rootme-sdk/blob/main/API.md
+Project-URL: Issues, https://github.com/Thomas97460/rootme-sdk/issues
+Project-URL: Changelog, https://github.com/Thomas97460/rootme-sdk/releases
+Author: Thomas Collet
+License-Expression: MIT
+License-File: LICENSE
+Keywords: challenges,ctf,root-me,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: beautifulsoup4<5,>=4.13
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: playwright<2,>=1.55
+Provides-Extra: browser
+Description-Content-Type: text/markdown
+
+# rootme-sdk
+
+An unofficial, typed Python SDK for [Root-Me](https://www.root-me.org/): automated login, session reuse, profile and challenge exploration, and answer submission.
+
+> [!NOTE]
+> This library is alpha software and is not affiliated with Root-Me. Respect Root-Me's terms of service and rate limits.
+
+## Installation
+
+Clone the repository and install the package with pip (Python >= 3.13 required):
+
+```bash
+git clone https://github.com/Thomas97460/rootme-sdk.git
+cd rootme-sdk
+pip install .
+```
+
+Playwright is included. On first use, it automatically uses your local Chrome/Chromium or downloads a managed Chromium browser.
+
+## Quickstart
+
+### 1. Login and read challenges
+
+```python
+from rootme_sdk import RootMeClient
+
+# Connect with credentials directly
+with RootMeClient("your-username", "your-password") as client:
+    # Read a challenge statement
+    challenge = client.read_challenge(5)
+    print(f"Title: {challenge.title}")
+    print(f"Statement: {challenge.statement}")
+
+    # Browse challenges
+    for item in client.iter_challenges(lang="en", score=5):
+        print(f"[{item.id}] {item.title} ({item.score} pts)")
+```
+
+Alternatively, pass credentials via a JSON file:
+
+```json
+{"login": "your-username", "password": "your-password"}
+```
+
+```python
+with RootMeClient(credentials_file=".secrets/credentials.json") as client:
+    user = client.get_user(12345)
+    print(f"User: {user.nom}, Score: {user.score}")
+```
+
+### 2. Submit an answer
+
+```python
+from rootme_sdk import RootMeClient, SubmissionStatus
+
+with RootMeClient("your-username", "your-password") as client:
+    result = client.submit_answer(5, "flag{your_flag_here}")
+
+    if result.status == SubmissionStatus.ACCEPTED:
+        print("Flag validated!")
+    elif result.status == SubmissionStatus.ALREADY_SOLVED:
+        print("Challenge already solved.")
+    elif result.status == SubmissionStatus.REJECTED:
+        print("Incorrect flag.")
+    elif result.status == SubmissionStatus.INDETERMINATE:
+        print(f"Ambiguous response: {result.message}")
+```
+
+### 3. Session reuse
+
+Save the session to avoid re-authenticating on every run:
+
+```python
+from rootme_sdk import RootMeClient, Session
+
+with RootMeClient("your-username", "your-password") as client:
+    client.session.save(".secrets/session.json")
+
+# Later: reload the saved session
+with RootMeClient(session=Session.load(".secrets/session.json")) as client:
+    challenge = client.read_challenge(5)
+```
+
+## Important Notes
+
+- **Graphical Display**: Password login uses an isolated, headed Chromium browser to handle Root-Me's native login flow. A working graphical display is required (`DISPLAY` on Linux).
+- **Security**: Never commit your passwords or `.secrets/` directory. Saved sessions contain cookies and should be restricted to your user account.
+- **Documentation**:
+  - [API Reference](API.md) — Exhaustive methods and types documentation.
+  - [Capabilities & Limits](CAPABILITIES.md) — Observed platform behaviors and known limitations.
+  - [Contributing](CONTRIBUTING.md) — Development workflow, quality gates, and testing guidelines.
+  - [Security Policy](SECURITY.md) — Vulnerability reporting and security practices.
+
+## Development
+
+```bash
+nix develop         # or install uv + task manually
+uv sync --locked
+git config core.hooksPath .githooks
+task ci
+```

rootme_sdk-0.3.0/PUBLISHING.md

@@ -0,0 +1,69 @@
+# Public GitHub and PyPI preparation
+
+The repository is public and `PUBLISH_PYPI=false`. No publication or
+visibility change follows from merging the preparation work. The current package
+version is 0.3.0; its tag has not been published.
+
+## Prepared in the repository
+
+- MIT license and SPDX metadata, author, Python support, alpha maturity, typing,
+  project links and a README suitable for PyPI rendering.
+- Account/challenge API reference, graphical-runtime requirements, migration
+  guidance, contribution instructions and a private security contact.
+- Offline tests with 100% SDK unit coverage, package guard tests, and wheel/source
+  installation checks on Python 3.13/3.14 across Linux, macOS and Windows.
+- Runtime dependency advisory checks, redacted secret scanning and weekly updates.
+  GitHub Actions are pinned to commits, with minimal job permissions.
+- Tag/version/exact-main-CI and security checks, a single validated build shared by GitHub/PyPI,
+  OIDC publishing and post-publication hash/clean-install verification.
+
+Before opening, run `task ci`, `task audit` and `task secrets` on the final commit.
+Gitleaks covers common secret formats; also compare historical blobs, package
+contents and old release assets against locally stored account secrets without
+printing them. Changing current files does not remove historical data. Commit
+author identities, old docs and release notes become public with the repository;
+review those intentionally. Fixtures contain synthetic examples, never copied
+challenge statements or real answers.
+
+Preparation audit on 2026-10-04: Gitleaks found no leaks in the existing 10 local
+commits; 110 reachable historical blobs and four v0.1.0/v0.2.0 release artifacts
+contained no locally known passwords, submitted answer or session cookie values.
+The locked runtime dependency audit reported no known vulnerabilities. PyPI's
+project API returned 404 for `rootme-sdk`; this is not a name reservation.
+These checks are a dated result, not a guarantee about future changes.
+
+## Product maturity decision
+
+Publishing an **alpha** is possible with the current documented limits. Publishing
+as a reliable unattended-login SDK is not yet justified: some fresh sessions fail
+account verification after positive login feedback, for an unresolved reason.
+Preference mutations also have not been tested on a real account. Offline coverage
+does not resolve these platform-level limits. Further live tests are intentionally
+deferred; do not run repeated logins merely to obtain one successful result.
+
+## Owner actions after deciding to publish
+
+1. Confirm the alpha positioning and choose whether to open the repository.
+   Enable GitHub private vulnerability reporting after it becomes public; the
+   email contact already works independently. Review main protection rules for
+   the quality, portability and security checks before accepting outside changes.
+2. In the maintainer's PyPI account, confirm project name availability/ownership
+   and create a [Pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/):
+   project **rootme-sdk**, GitHub owner **Thomas97460**, repository **rootme-sdk**,
+   workflow **release.yml**, environment **pypi**. A pending publisher does not
+   reserve the project name; first successful publication creates the project.
+3. Create the GitHub `pypi` environment and explicitly set `PUBLISH_PYPI=true`.
+   The workflow skips PyPI while the repository is private, even with that variable
+   enabled. No password/token is needed in GitHub for this OIDC publisher.
+4. Adjust the README install status through a normal PR. Wait for green CI and
+   security checks on its exact main commit. Obtain explicit tag approval, then
+   create/push `v0.3.0` on that commit, provided the version remains untagged.
+5. Watch the release workflow. It attaches wheel/source assets on GitHub and, when
+   enabled, publishes to PyPI. It checks PyPI's exact version file hashes against
+   the build and installs that version into a clean environment outside the repo.
+   Review both destinations; a successful tag push alone is insufficient.
+
+Never move a tag or replace a published version. If the GitHub publication succeeds
+but PyPI fails, repair the workflow through a PR and release a new approved version
+instead of blindly replaying all publication jobs. Already uploaded files cannot
+be replaced. Never upload credentials or session files as release assets.