shieldy-sdk 1.0.2__tar.gz

shieldy_sdk-1.0.2/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: release
+
+# Publishes shieldy-sdk with PyPI trusted publishing (OIDC), no stored token.
+#   - a version tag (v1.2.3) publishes to PyPI (prod);
+#   - a manual run (Actions -> release -> Run workflow) publishes to PyPI or TestPyPI (test).
+# Register this repo + release.yml as a trusted publisher on BOTH indexes: pypi.org (GitHub
+# environment "pypi") and test.pypi.org (environment "testpypi"). The native runtime is pulled from
+# the Bunny pull zone, which has token auth on, so both BUNNY_PULL_ZONE_HOST and
+# BUNNY_PULL_ZONE_TOKEN_KEY are needed.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Index to publish to"
+        type: choice
+        options: [prod, test]
+        default: prod
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # A tag push is always prod; a manual run uses the chosen target. The environment name must
+    # match the trusted publisher configured on each index.
+    environment: ${{ (github.event_name == 'workflow_dispatch' && inputs.target == 'test') && 'testpypi' || 'pypi' }}
+    permissions:
+      id-token: write  # trusted publishing (OIDC)
+      contents: read   # checkout of this private repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Resolve the publish target
+        id: target
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.target }}" = "test" ]; then
+            echo "value=test" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=prod" >> "$GITHUB_OUTPUT"
+          fi
+      # A tag release must match the package version; a manual (possibly test) run need not.
+      - name: The tag must match pyproject.toml
+        if: github.event_name == 'push'
+        run: |
+          version="$(python3 -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          test "v$version" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} does not match version $version"; exit 1; }
+      # Pull the pinned hardened runtime (native/native.lock.json) from the Bunny pull zone (signed:
+      # the zone has token auth on) and build one platform wheel per blob (py3-none-<platform>),
+      # plus a pure sdist as the fallback for platforms with no bundled runtime.
+      - name: Fetch the pinned native runtime
+        env:
+          BUNNY_PULL_ZONE_HOST: ${{ secrets.BUNNY_PULL_ZONE_HOST }}
+          BUNNY_PULL_ZONE_TOKEN_KEY: ${{ secrets.BUNNY_PULL_ZONE_TOKEN_KEY }}
+        run: uv run python scripts/fetch_native.py
+      - name: Build platform wheels
+        run: uv run --with wheel python scripts/build_wheels.py
+      - name: Build the source distribution
+        run: uv build --sdist
+      - name: Publish to PyPI
+        if: steps.target.outputs.value == 'prod'
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Publish to TestPyPI
+        if: steps.target.outputs.value == 'test'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

shieldy_sdk-1.0.2/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+/.venv/
+/build/
+/dist/
+*.egg-info/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.idea/
+# Runtimes are build artifacts of ShieldyCore, never committed here.
+*.dll
+*.so
+# Local settings for the end-to-end tests (dashboard credentials).
+/tests/e2e/.env
+# A DEV build of the runtime writes debug logs to ./logs of the working directory.
+logs/

shieldy_sdk-1.0.2/CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+Orientation for Claude Code (and anyone new) in this repository. The full design rationale is in
+`docs/architecture.md`; the customer-facing guide is `README.md`. Read the relevant section there
+before a structural change.
+
+## What this is
+
+`shieldy-sdk` (import `shieldy`): the Python client of Shieldy's native runtime (ShieldyCore's
+`native.dll` / `native.so`), through `ctypes`. Python 3.9+, one dependency (`cryptography`).
+Module-level functions operate on the one session a process has: load the runtime, sign in with a
+license key, read license, variables, files and Protected Strings, all decrypted with a per-login
+session key.
+
+Sibling repositories implementing the same contract (ABI, wire crypto, error numbers, variable
+grammar): `../../native/ShieldyCore` (runtime, `cpp-module/shieldy_api.h`),
+`../examples/CppCmakeShieldy` (C++ SDK), `../ShieldyDotnetSdk` (.NET SDK),
+`../../services/ShieldyBackend` (server; the `python` snippet in
+`core-dashboard-api/services/string_obfuscation_service.py` must stay `shieldy.protected_string`).
+
+## Map
+
+```
+src/shieldy/
+  __init__.py      the public API, re-exported (names without underscore are public)
+  _session.py      process-wide state, one RLock, every public call (start here)
+  _abi.py          ctypes mirror of shieldy_api.h; no logic
+  _native.py       path resolution (application dir, never cwd), loading, SC_GetApi
+  _crypto.py       X25519 + SHA-256, HMAC attestation, ChaCha20-Poly1305 unwrap
+  errors.py        Error IntEnum (numbers shared with C++/.NET), ShieldyError
+  values.py        Config, License, SecureBytes, Feature
+  obf.py           SHIELDY_OBF marker + `python -m shieldy.obf check`
+tests/
+  mock_runtime.py  SC_ApiV1 of real CFUNCTYPE callbacks, scenarios of the C++ mock_native.cpp
+  test_*.py        unit tests (no server, no DLL)
+  e2e/             dashboard.py (stdlib REST client), probe_app.py (one process per scenario),
+                   conftest.py (.env), test_e2e.py; marker `e2e`, excluded by default
+examples/          basic.py, protected_strings_marker.py
+third_party/shieldy_api.h   copy of ShieldyCore's header; test_abi.py compares it
+```
+
+## Commands
+
+```bash
+uv sync                                  # creates .venv with pytest, ruff, mypy
+uv run pytest                            # unit tests, ~2 s (addopts exclude e2e)
+uv run pytest -m e2e                     # real runtime + local server, see below
+uv run ruff check src tests examples     # line length 120
+uv run mypy                              # strict, src only
+uv run --python 3.9 pytest               # the floor
+uv run python scripts/test_matrix.py     # 3.9 to 3.14 plus the oldest cryptography, in throwaway envs
+```
+
+## E2E stack (local)
+
+- Postgres + Redis containers (`shieldy-dev-postgres-1`, `shieldy-dev-redis-1`) from ShieldyDeploy.
+- `ShieldyBackend/core-auth-api`: `uv run --package core-auth-api python main.py` (127.0.0.1:8010).
+- `ShieldyBackend/core-dashboard-api`: same with `core-dashboard-api` (127.0.0.1:8020) and
+  `STRING_OBF_NATIVE_LIBRARY_PATH=../../native/ShieldyCore/cmake-builds/win-dev-x64/obfuscation-module/security.dll`.
+  Restart it after changing the backend: it does not reload.
+- Runtime: `tests/e2e/runtime/native.dll` (gitignored), a DEV ShieldyCore build with the endpoint
+  edited to `http://127.0.0.1:8010` (how to build one: `tests/e2e/README.md`). Settings in
+  `tests/e2e/.env` (gitignored).
+- Each test app gets `require_registered_native=false`, or `/initialize` refuses a local build.
+- **Offline start tests (`test_offline.py`)** skip unless both deployment switches are on. A hand-started
+  service reads `ShieldyBackend/config/<env>/<service>.toml`, NOT `ShieldyDeploy/config/dev/` (that one is
+  for dev compose) and the backend copy has no `[offline_lease]`/`[offline_start]` tables, so start with
+  env vars (they beat the TOML): `OFFLINE_LEASE_ENABLED=true` for auth-api (the signing key
+  `OFFLINE_LEASE_SIGNING_KEY` is already in `ShieldyDeploy/env/dev/auth-api.env`) and
+  `OFFLINE_START_ENABLED=true` for dashboard-api. The skip message names the missing one.
+  The dev account's plan must include offline start (dev@shieldy.local does), or the suite skips on 402.
+- Offline is simulated with `SHIELDY_DEV_FORCE_OFFLINE=1` (honored by DEV/TEST runtimes only):
+  `run_probe(..., offline=True)`. Leases go to a per-test `lease_directory=str(tmp_path)`, never the
+  machine's `%LOCALAPPDATA%\Shieldy\leases`. The runtime must be built from ShieldyCore `dev` with
+  offline start (Oct 2026+) or every offline test fails at `connection_state`.
+- **Restarting the services on Windows:** auth-api (Sanic) spawns `multiprocessing` workers that survive
+  `Stop-Process` on `main.py` and keep port 8010 bound. Kill the children too: find them with
+  `Get-CimInstance Win32_Process -Filter "ParentProcessId=<pid>"` (command line
+  `spawn_main(parent_pid=...)`), or check `Get-NetTCPConnection -State Listen -LocalPort 8010,8020`
+  until both ports are free. Start from the service dir with the venv python:
+  `UV_NO_SYNC=1 ../.venv/Scripts/python.exe main.py` (`UV_NO_SYNC` keeps uv from re-syncing the
+  locally installed protocol packages back to the GitHub pin).
+
+## Invariants (do not break)
+
+- `Error` numbers equal the C++ SDK's `shieldy::Error` and the .NET SDK's `ShieldyError`.
+- `SC_ApiV1._fields_` order = `shieldy_api.h`; append only. `test_abi.py` parses the header.
+- Wire crypto: session key = SHA-256(X25519); attestation = HMAC-SHA256(key, 16-byte nonce); values
+  = `nonce(12) || tag(16) || ciphertext`, ChaCha20-Poly1305, no AAD (the tag goes first, so
+  `_crypto.Session.decrypt` reorders it for `cryptography`).
+- `appMode = 3` (Python) in `SC_Config`.
+- A relative runtime path resolves against the application directory (frozen exe dir, then
+  `sys._MEIPASS`, else the `__main__` script dir), never the working directory.
+- Every runtime-allocated `SC_Buffer` goes back through `free_buffer` (tests assert none left).
+- Variable grammar = C++ `from_chars` (no `+`, no `_` separators, no hex).
+- Python 3.9 floor: `typing.Optional`/`List`, no `match`, no `X | Y` at runtime (ruff ignores UP006/7/35/45).
+- Never write a typographic dash (U+2013/2014/2015); `test_no_typographic_dashes.py` scans the repo.
+- English, US spelling, in code, docs and messages.
+
+## Runtime versions
+
+ShieldyCore since October 2026 (multi-session, ShieldyJavaSdk Phase 5) gives every context its own
+server session: `login()` after a refused key and `init()` after `shutdown()` work, and the e2e
+suite tests both. Older runtimes allowed one server session per process; `login()`, the README and
+the architecture doc say what that means for integrators who still ship one.
+
+## Release process
+
+Releasing this SDK (pinning the runtime in `native/native.lock.json`, `fetch_native.py`,
+`build_wheels.py`, `.github/workflows/release.yml`) is phases B and C of the process described in
+`../../release/ShieldyRelease/steps.toml` (panel: `python -m shieldy_release.cli
+serve`). A change to any of these, to where the package version lives, or to the publish targets,
+secrets or tag rules must be checked against `steps.toml`, its checks and its runbooks in the same
+piece of work. See ShieldyRelease's CLAUDE.md, "Keeping the process in sync".
+
+## Gotchas
+
+- ctypes callbacks in the mock must stay referenced (`MockRuntime._keep`), or the trampoline is
+  freed under the SDK.
+- A DEV runtime writes `./logs` into the working directory (`logs/` is gitignored).
+- The e2e `dashboard.py` carries the `__Host-` session cookie by hand: `http.cookiejar` will not
+  send a `Secure` cookie back over plain-http localhost.
+- `cryptography` before 45 has no `decrypt_into`; `_crypto` falls back to one immutable copy.

shieldy_sdk-1.0.2/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: shieldy-sdk
+Version: 1.0.2
+Summary: Python client for Shieldy's native runtime: licensing, remote variables, files and Protected Strings.
+Project-URL: Documentation, https://docs.shieldy.app
+License: Proprietary
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42
+Description-Content-Type: text/markdown
+
+# Shieldy Python SDK
+
+The Python client for Shieldy's native runtime (`native.dll` on Windows, `native.so` on Linux).
+It signs your application in with the end user's license key and reads what the dashboard
+delivers to that license: the license itself, remote variables, files and Protected Strings.
+
+```python
+import shieldy
+
+try:
+    shieldy.start(shieldy.Config("<App GUID>", "1.0"), read_license_key_from_user())
+except shieldy.ShieldyError as exc:
+    # exc.error is a shieldy.Error, e.g. Error.AUTHENTICATION_FAILED
+    raise SystemExit(f"Could not sign in: {exc.error}")
+
+lic = shieldy.license()
+if lic.level >= 20:
+    enable_pro_features()
+
+api_url = shieldy.variable_by_id("<Lookup ID>")              # str
+max_users = shieldy.variable_by_id_as("<Lookup ID>", int)    # int
+with shieldy.file_by_id("<Lookup ID>") as pak:               # SecureBytes, wiped after the block
+    load_assets(pak.view())
+token = shieldy.protected_string("<ciphertext>")             # str
+```
+
+Python 3.9 or newer, 64-bit or 32-bit to match the runtime you ship. The only dependency is
+[`cryptography`](https://cryptography.io).
+
+## Installing
+
+```powershell
+pip install shieldy-sdk                 # once published
+pip install path/to/ShieldyPythonSdk    # from a checkout
+```
+
+Ship the runtime with your application. Download it from the dashboard (your app -> Activity ->
+Runtime -> "Download the SDK"), and put it next to your entry script or your frozen executable.
+
+## Where the runtime is loaded from
+
+The SDK loads exactly one file, chosen in this order:
+
+1. `Config.native_library`, if you set it;
+2. the `SHIELDY_NATIVE_LIBRARY` environment variable;
+3. `native.dll` (`native.so` on Linux).
+
+A relative path is resolved against your application's directory, **never** the current working
+directory or `PATH`, so a library planted where the user starts your program is not picked up.
+Your application's directory is:
+
+| How the app runs | Directory |
+|---|---|
+| `python app.py` | the directory of `app.py` |
+| `python -m package` | the directory of `package/__main__.py` |
+| PyInstaller, cx_Freeze, py2exe | the directory of the executable, then PyInstaller's bundle directory (`sys._MEIPASS`) |
+| interactive interpreter, `python -c` | none: give an absolute path |
+
+`shieldy.application_directory()` shows what the SDK settled on.
+
+With PyInstaller, either copy the runtime next to the built executable, or bundle it:
+`pyinstaller --add-binary "native.dll;." app.py` (`native.so:.` on Linux).
+
+## API
+
+All calls are module-level functions on the one session the process has. They are thread-safe.
+
+| Call | Returns |
+|---|---|
+| `init(config)` | Loads the runtime and runs its protected start-up (`/initialize` on the server). |
+| `login(key)` | Signs in with the license key. |
+| `start(config, key)` | `init` then `login`. |
+| `shutdown()` | Ends the session. Also runs automatically when the interpreter exits. |
+| `is_logged_in()` | `bool` |
+| `supports(Feature.LOOKUP_IDS)` | Whether the runtime has the `*_by_id` calls (protocol 1.6.0+). |
+| `supports(Feature.OFFLINE_START)` | Whether the runtime has `connection_state()` (protocol 1.12.0+). |
+| `connection_state()` | `ConnectionState`: `offline` (`True` when this run started without a connection), `offline_until` (until when this device can start offline; `None`: it cannot). |
+| `license()` | `License`: `level`, `hwid_seats_used`, `hwid_seats_total`, `created`, `expires` (`None`: never), `is_expired()`, `days_left()`. Read once at login. |
+| `variable_by_id(id)` / `variable(name)` | `str` |
+| `variable_by_id_as(id, type)` / `variable_as(name, type)` | `int`, `float`, `bool` or `str` |
+| `file_by_id(id)` / `file(name)` | `SecureBytes`, wiped from memory when done |
+| `protected_string(ciphertext)` | `str`, cached for the rest of the session |
+
+Prefer the `*_by_id` calls: a lookup id is random, a name ends up readable in your code. A
+variable whose name is hidden from the client (dashboard: "Hide name from client") can only be
+read by id.
+
+`bool` variables accept `true`, `false`, `1`, `0`. Numbers follow the C++ SDK's rules: surrounding
+whitespace is ignored, a leading `+`, digit separators (`1_000`) and hex are not accepted.
+
+### Errors
+
+Every call raises `shieldy.ShieldyError` when it cannot deliver; `exc.error` says why. The codes
+have the same numbers as the C++ SDK's `shieldy::Error`.
+
+| `Error` | Meaning |
+|---|---|
+| `NATIVE_LIBRARY_NOT_FOUND` | No runtime at the resolved path, or one for the wrong architecture. |
+| `NATIVE_LIBRARY_INVALID` | The file loaded but is not a Shieldy runtime. |
+| `INITIALIZATION_FAILED` | The server refused to start the app: unknown App GUID, suspended app, outdated version, unregistered runtime build, maintenance. |
+| `AUTHENTICATION_FAILED` | The key was refused: wrong, expired, banned, or no free device seat. The server does not say which. |
+| `NOT_INITIALIZED`, `NOT_LOGGED_IN` | A call came too early. |
+| `NOT_FOUND` | No variable with that id or name for this license. |
+| `NATIVE_TOO_OLD` | The runtime predates the call; see `supports()`. |
+| `ATTESTATION_FAILED`, `KEY_EXCHANGE_FAILED`, `DECRYPT_FAILED` | The runtime could not prove it holds the session key, or a value did not decrypt. Treat as tampering. |
+| `INVALID_VALUE` | A variable did not parse as the requested type. |
+| `SERVER_UNREACHABLE` | No connection, and this device cannot start offline (offline start is off, it never signed in online here, or that was with another key). |
+| `OFFLINE_EXPIRED` | No connection, and this device's offline time (or the license) has run out. |
+| `CLOCK_INVALID` | No connection, and the system clock reads earlier than the last run. |
+| `OFFLINE_UNAVAILABLE` | The call needs a connection and the app is running offline (files). |
+
+The full list is in `src/shieldy/errors.py`.
+
+### Offline start
+
+When the app has offline start on (dashboard: Security -> Availability), a device that signed in
+online can start without internet for the number of days the app allows. Nothing changes in your
+code: `init()` and `login()` succeed offline as they do online. Show it if you like:
+
+```python
+state = shieldy.connection_state()
+if state.offline:
+    show_banner(f"Offline - works until {state.offline_until:%b %d}")
+```
+
+Offline, `license()`, variables and Protected Strings work; files need a connection. The device
+has to sign in with the same key it last used online. For a portable install, keep the lease next
+to the app with `Config(..., lease_directory="leases")`. To test it without pulling the cable, set
+`SHIELDY_DEV_FORCE_OFFLINE=1` with a development build of the runtime.
+
+### Trying another key
+
+When a key is refused, `login()` can be called again with another one, and `init()` works again
+after `shutdown()`. Runtimes built before October 2026 allowed one sign-in per process (the server
+ends the session at a refused key and they could not open another); with one of those, restart the
+process to let the user try another key.
+
+### Files and memory
+
+`file_by_id()` returns a `SecureBytes`: a buffer the SDK zeroes when you call `wipe()`, when a
+`with` block around it ends, or when it is garbage collected. Read it through the object
+(`len()`, indexing, slicing, `view()`, `text()`); `bytes(data)` makes a copy that can never be
+wiped. This is best effort, as it has to be in Python: copies the interpreter makes on its own
+(a `str` from `text()`, for instance) are out of the SDK's reach.
+
+## Protected Strings in the build
+
+Write secrets as `SHIELDY_OBF("...")` (double quotes) and keep coding against the plain text:
+
+```python
+import shieldy
+from shieldy.obf import SHIELDY_OBF
+
+def api_endpoint() -> str:
+    return SHIELDY_OBF("https://api.example.com/v2")
+```
+
+Before a release, run the dashboard's CLI over each file. It rewrites every marker to
+`shieldy.protected_string("<ciphertext>")`:
+
+```powershell
+python tools/shieldy_strings_cli.py --api-url https://<dashboard>/api --app-guid <App GUID> `
+    --api-key <key with apps:write> --file src/endpoints.py --language python --in-place
+python -m shieldy.obf check src/        # exit code 1 while any marker is left
+```
+
+Python has no compile step that could refuse a forgotten marker, so `SHIELDY_OBF` raises
+`UnencryptedMarkerError` when it runs, unless `SHIELDY_OBF_PLAINTEXT=1` is set (do that while you
+develop, never in a release), and `python -m shieldy.obf check` belongs in your release pipeline.
+Read protected strings where they are used, after `login()`, never at module level.
+See `examples/protected_strings_marker.py`.
+
+## Examples
+
+- `examples/basic.py`: the whole flow, configured from environment variables
+  (`SHIELDY_APP_GUID`, `SHIELDY_LICENSE_KEY`, optional `SHIELDY_VARIABLE_ID`, `SHIELDY_FILE_ID`,
+  `SHIELDY_PROTECTED_STRING`).
+- `examples/protected_strings_marker.py`: the `SHIELDY_OBF` workflow.
+
+## Working on this repository
+
+```powershell
+uv sync                    # Python 3.9+, creates .venv with the dev tools
+uv run pytest              # unit tests against a mock runtime, no server needed
+uv run pytest -m e2e       # a real runtime against a real server, see tests/e2e/README.md
+uv run ruff check src tests examples
+uv run mypy                # strict
+```
+
+How the SDK works inside, and why it is built the way it is: [docs/architecture.md](docs/architecture.md).
+A quick map of the repository, its commands and invariants: [CLAUDE.md](CLAUDE.md).
+
+`third_party/shieldy_api.h` is a copy of ShieldyCore's `cpp-module/shieldy_api.h`, the ABI the
+SDK mirrors in `src/shieldy/_abi.py`. `tests/test_abi.py` fails when the two disagree, and when the
+copy differs from a ShieldyCore checkout next to this repository.

shieldy_sdk-1.0.2/README.md

@@ -0,0 +1,195 @@
+# Shieldy Python SDK
+
+The Python client for Shieldy's native runtime (`native.dll` on Windows, `native.so` on Linux).
+It signs your application in with the end user's license key and reads what the dashboard
+delivers to that license: the license itself, remote variables, files and Protected Strings.
+
+```python
+import shieldy
+
+try:
+    shieldy.start(shieldy.Config("<App GUID>", "1.0"), read_license_key_from_user())
+except shieldy.ShieldyError as exc:
+    # exc.error is a shieldy.Error, e.g. Error.AUTHENTICATION_FAILED
+    raise SystemExit(f"Could not sign in: {exc.error}")
+
+lic = shieldy.license()
+if lic.level >= 20:
+    enable_pro_features()
+
+api_url = shieldy.variable_by_id("<Lookup ID>")              # str
+max_users = shieldy.variable_by_id_as("<Lookup ID>", int)    # int
+with shieldy.file_by_id("<Lookup ID>") as pak:               # SecureBytes, wiped after the block
+    load_assets(pak.view())
+token = shieldy.protected_string("<ciphertext>")             # str
+```
+
+Python 3.9 or newer, 64-bit or 32-bit to match the runtime you ship. The only dependency is
+[`cryptography`](https://cryptography.io).
+
+## Installing
+
+```powershell
+pip install shieldy-sdk                 # once published
+pip install path/to/ShieldyPythonSdk    # from a checkout
+```
+
+Ship the runtime with your application. Download it from the dashboard (your app -> Activity ->
+Runtime -> "Download the SDK"), and put it next to your entry script or your frozen executable.
+
+## Where the runtime is loaded from
+
+The SDK loads exactly one file, chosen in this order:
+
+1. `Config.native_library`, if you set it;
+2. the `SHIELDY_NATIVE_LIBRARY` environment variable;
+3. `native.dll` (`native.so` on Linux).
+
+A relative path is resolved against your application's directory, **never** the current working
+directory or `PATH`, so a library planted where the user starts your program is not picked up.
+Your application's directory is:
+
+| How the app runs | Directory |
+|---|---|
+| `python app.py` | the directory of `app.py` |
+| `python -m package` | the directory of `package/__main__.py` |
+| PyInstaller, cx_Freeze, py2exe | the directory of the executable, then PyInstaller's bundle directory (`sys._MEIPASS`) |
+| interactive interpreter, `python -c` | none: give an absolute path |
+
+`shieldy.application_directory()` shows what the SDK settled on.
+
+With PyInstaller, either copy the runtime next to the built executable, or bundle it:
+`pyinstaller --add-binary "native.dll;." app.py` (`native.so:.` on Linux).
+
+## API
+
+All calls are module-level functions on the one session the process has. They are thread-safe.
+
+| Call | Returns |
+|---|---|
+| `init(config)` | Loads the runtime and runs its protected start-up (`/initialize` on the server). |
+| `login(key)` | Signs in with the license key. |
+| `start(config, key)` | `init` then `login`. |
+| `shutdown()` | Ends the session. Also runs automatically when the interpreter exits. |
+| `is_logged_in()` | `bool` |
+| `supports(Feature.LOOKUP_IDS)` | Whether the runtime has the `*_by_id` calls (protocol 1.6.0+). |
+| `supports(Feature.OFFLINE_START)` | Whether the runtime has `connection_state()` (protocol 1.12.0+). |
+| `connection_state()` | `ConnectionState`: `offline` (`True` when this run started without a connection), `offline_until` (until when this device can start offline; `None`: it cannot). |
+| `license()` | `License`: `level`, `hwid_seats_used`, `hwid_seats_total`, `created`, `expires` (`None`: never), `is_expired()`, `days_left()`. Read once at login. |
+| `variable_by_id(id)` / `variable(name)` | `str` |
+| `variable_by_id_as(id, type)` / `variable_as(name, type)` | `int`, `float`, `bool` or `str` |
+| `file_by_id(id)` / `file(name)` | `SecureBytes`, wiped from memory when done |
+| `protected_string(ciphertext)` | `str`, cached for the rest of the session |
+
+Prefer the `*_by_id` calls: a lookup id is random, a name ends up readable in your code. A
+variable whose name is hidden from the client (dashboard: "Hide name from client") can only be
+read by id.
+
+`bool` variables accept `true`, `false`, `1`, `0`. Numbers follow the C++ SDK's rules: surrounding
+whitespace is ignored, a leading `+`, digit separators (`1_000`) and hex are not accepted.
+
+### Errors
+
+Every call raises `shieldy.ShieldyError` when it cannot deliver; `exc.error` says why. The codes
+have the same numbers as the C++ SDK's `shieldy::Error`.
+
+| `Error` | Meaning |
+|---|---|
+| `NATIVE_LIBRARY_NOT_FOUND` | No runtime at the resolved path, or one for the wrong architecture. |
+| `NATIVE_LIBRARY_INVALID` | The file loaded but is not a Shieldy runtime. |
+| `INITIALIZATION_FAILED` | The server refused to start the app: unknown App GUID, suspended app, outdated version, unregistered runtime build, maintenance. |
+| `AUTHENTICATION_FAILED` | The key was refused: wrong, expired, banned, or no free device seat. The server does not say which. |
+| `NOT_INITIALIZED`, `NOT_LOGGED_IN` | A call came too early. |
+| `NOT_FOUND` | No variable with that id or name for this license. |
+| `NATIVE_TOO_OLD` | The runtime predates the call; see `supports()`. |
+| `ATTESTATION_FAILED`, `KEY_EXCHANGE_FAILED`, `DECRYPT_FAILED` | The runtime could not prove it holds the session key, or a value did not decrypt. Treat as tampering. |
+| `INVALID_VALUE` | A variable did not parse as the requested type. |
+| `SERVER_UNREACHABLE` | No connection, and this device cannot start offline (offline start is off, it never signed in online here, or that was with another key). |
+| `OFFLINE_EXPIRED` | No connection, and this device's offline time (or the license) has run out. |
+| `CLOCK_INVALID` | No connection, and the system clock reads earlier than the last run. |
+| `OFFLINE_UNAVAILABLE` | The call needs a connection and the app is running offline (files). |
+
+The full list is in `src/shieldy/errors.py`.
+
+### Offline start
+
+When the app has offline start on (dashboard: Security -> Availability), a device that signed in
+online can start without internet for the number of days the app allows. Nothing changes in your
+code: `init()` and `login()` succeed offline as they do online. Show it if you like:
+
+```python
+state = shieldy.connection_state()
+if state.offline:
+    show_banner(f"Offline - works until {state.offline_until:%b %d}")
+```
+
+Offline, `license()`, variables and Protected Strings work; files need a connection. The device
+has to sign in with the same key it last used online. For a portable install, keep the lease next
+to the app with `Config(..., lease_directory="leases")`. To test it without pulling the cable, set
+`SHIELDY_DEV_FORCE_OFFLINE=1` with a development build of the runtime.
+
+### Trying another key
+
+When a key is refused, `login()` can be called again with another one, and `init()` works again
+after `shutdown()`. Runtimes built before October 2026 allowed one sign-in per process (the server
+ends the session at a refused key and they could not open another); with one of those, restart the
+process to let the user try another key.
+
+### Files and memory
+
+`file_by_id()` returns a `SecureBytes`: a buffer the SDK zeroes when you call `wipe()`, when a
+`with` block around it ends, or when it is garbage collected. Read it through the object
+(`len()`, indexing, slicing, `view()`, `text()`); `bytes(data)` makes a copy that can never be
+wiped. This is best effort, as it has to be in Python: copies the interpreter makes on its own
+(a `str` from `text()`, for instance) are out of the SDK's reach.
+
+## Protected Strings in the build
+
+Write secrets as `SHIELDY_OBF("...")` (double quotes) and keep coding against the plain text:
+
+```python
+import shieldy
+from shieldy.obf import SHIELDY_OBF
+
+def api_endpoint() -> str:
+    return SHIELDY_OBF("https://api.example.com/v2")
+```
+
+Before a release, run the dashboard's CLI over each file. It rewrites every marker to
+`shieldy.protected_string("<ciphertext>")`:
+
+```powershell
+python tools/shieldy_strings_cli.py --api-url https://<dashboard>/api --app-guid <App GUID> `
+    --api-key <key with apps:write> --file src/endpoints.py --language python --in-place
+python -m shieldy.obf check src/        # exit code 1 while any marker is left
+```
+
+Python has no compile step that could refuse a forgotten marker, so `SHIELDY_OBF` raises
+`UnencryptedMarkerError` when it runs, unless `SHIELDY_OBF_PLAINTEXT=1` is set (do that while you
+develop, never in a release), and `python -m shieldy.obf check` belongs in your release pipeline.
+Read protected strings where they are used, after `login()`, never at module level.
+See `examples/protected_strings_marker.py`.
+
+## Examples
+
+- `examples/basic.py`: the whole flow, configured from environment variables
+  (`SHIELDY_APP_GUID`, `SHIELDY_LICENSE_KEY`, optional `SHIELDY_VARIABLE_ID`, `SHIELDY_FILE_ID`,
+  `SHIELDY_PROTECTED_STRING`).
+- `examples/protected_strings_marker.py`: the `SHIELDY_OBF` workflow.
+
+## Working on this repository
+
+```powershell
+uv sync                    # Python 3.9+, creates .venv with the dev tools
+uv run pytest              # unit tests against a mock runtime, no server needed
+uv run pytest -m e2e       # a real runtime against a real server, see tests/e2e/README.md
+uv run ruff check src tests examples
+uv run mypy                # strict
+```
+
+How the SDK works inside, and why it is built the way it is: [docs/architecture.md](docs/architecture.md).
+A quick map of the repository, its commands and invariants: [CLAUDE.md](CLAUDE.md).
+
+`third_party/shieldy_api.h` is a copy of ShieldyCore's `cpp-module/shieldy_api.h`, the ABI the
+SDK mirrors in `src/shieldy/_abi.py`. `tests/test_abi.py` fails when the two disagree, and when the
+copy differs from a ShieldyCore checkout next to this repository.