gait-sdk 0.5.0__tar.gz

gait_sdk-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthony Narine
+
+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.

gait_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: gait-sdk
+Version: 0.5.0
+Summary: Official Python SDK for Gait: verify Gait identities (local JWKS or introspection) in Django and FastAPI, with live session checks, application identity, and security signals.
+Author: Anthony Narine
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/anthonynarine/gait-sdk
+Project-URL: Documentation, https://github.com/anthonynarine/gait-sdk#readme
+Project-URL: Changelog, https://github.com/anthonynarine/gait-sdk/blob/main/docs/CHANGELOG.md
+Project-URL: Security, https://github.com/anthonynarine/gait-sdk/blob/main/docs/SECURITY.md
+Keywords: gait,authentication,jwt,jwks,django,fastapi,sdk,identity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: python-decouple>=3.6
+Requires-Dist: requests>=2.31.0
+Requires-Dist: PyJWT[crypto]>=2.10.1
+Provides-Extra: django
+Requires-Dist: Django>=4.2; extra == "django"
+Requires-Dist: djangorestframework>=3.14; extra == "django"
+Requires-Dist: asgiref>=3.6; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21; extra == "test"
+Dynamic: license-file
+
+# gait-sdk
+
+[![PyPI](https://img.shields.io/pypi/v/gait-sdk.svg)](https://pypi.org/project/gait-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/gait-sdk.svg)](https://pypi.org/project/gait-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The official Python SDK for **Gait**, an identity and security platform. Drop it into a **Django REST Framework** or **FastAPI** service to verify who is calling you, using identities Gait issues. It never issues tokens, stores passwords, or makes authorization decisions.
+
+```
+Gait                authenticates   — who are you? (login, 2FA, sessions, signed tokens)
+gait-sdk            verifies        — is this token genuine, and whose is it?
+your application    authorizes      — what may this person do here?
+```
+
+That boundary is the core design rule. The SDK hands your code a verified **identity** (`subject`, `email`, session, token id, issuer). Roles, organizations and permissions belong to your application. See [Architecture](docs/ARCHITECTURE.md).
+
+---
+
+## Install
+
+```bash
+pip install "gait-sdk[django]"     # Django REST Framework services
+pip install "gait-sdk[fastapi]"    # FastAPI services
+pip install gait-sdk               # core only (verification, sessions, app identity)
+```
+
+Requires Python 3.10+. Pin exact versions in production (`gait-sdk==0.5.0`). See [Supply chain](docs/PUBLISHING.md#consuming-safely).
+
+---
+
+## Quick start: Django REST Framework
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "gait_sdk"]          # validates configuration at startup
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ["gait_sdk.authentication.ExternalJWTAuthentication"],
+}
+
+GAIT_TOKEN_VERIFIER = "jwks"                 # verify locally (recommended)
+GAIT_JWKS_URL = "https://auth.example.com/.well-known/jwks.json"
+GAIT_ISSUER = "https://auth.example.com"
+GAIT_AUDIENCE = "urn:gait:your-app"
+GAIT_AUTH_URL = "https://auth.example.com/api"   # used for live session checks
+```
+
+```python
+# views.py
+from gait_sdk.django.authentication import require_live_session
+
+class FinalizeReport(APIView):
+    def post(self, request, pk):
+        identity = request.verified_identity    # subject, email, session_id, token_id, issuer
+        ...                                     # YOUR authorization check first
+        require_live_session(request)           # sensitive action: confirm the session live
+        ...                                     # then mutate
+```
+
+## Quick start: FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from gait_sdk.fastapi.dependencies import require_live_session, validate_configuration, verify_token
+
+app = FastAPI()
+validate_configuration()   # fail at startup, not on the first request
+
+@app.get("/me")
+async def me(claims: dict = Depends(verify_token)):
+    return {"subject": claims["id"], "email": claims["email"]}   # "id" works in both verifier modes
+
+@app.post("/danger")
+async def danger(claims: dict = Depends(require_live_session)):
+    ...
+```
+
+---
+
+## Configuration
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `GAIT_TOKEN_VERIFIER` | `introspection` | `jwks` = verify tokens locally against Gait's published keys (recommended). `introspection` = ask Gait `/whoami/` on every request (legacy). Chosen explicitly, with **no automatic fallback**. |
+| `GAIT_JWKS_URL` | — | Required for `jwks`. Must be `https` (plain `http` only for `localhost`). |
+| `GAIT_ISSUER` | — | Required for `jwks`. Must equal Gait's `JWT_ISSUER` exactly. |
+| `GAIT_AUDIENCE` | — | Required for `jwks`. Must equal Gait's `JWT_AUDIENCE`. |
+| `GAIT_AUTH_URL` | — | Gait's API base (`…/api`), used by live session checks, introspection, application identity and signals. `https` required (http only for `localhost`). |
+| `GAIT_TIMEOUT` | `5` | Seconds for calls to Gait. |
+| `GAIT_APPLICATION_CREDENTIAL` | — | Only for application identity / security signals. A secret: keep it in the environment. |
+| `GAIT_ALLOW_COOKIE_AUTH` | `False` | Deprecated legacy cookie mode (introspection only). Leave off. See [Security](docs/SECURITY.md). |
+
+Settings come from Django settings first, then environment variables / `.env`. An invalid or incomplete configuration **stops the service at startup**.
+
+---
+
+## What you get
+
+| Module | For |
+|---|---|
+| `gait_sdk.verification` | Token verification (`JwksVerifier`, `IntrospectionVerifier`) → `VerifiedIdentity` |
+| `gait_sdk.session` | `check_session_live()`: live revocation check for sensitive actions |
+| `gait_sdk.authentication` / `gait_sdk.django` | DRF authentication class, `require_live_session(request)` |
+| `gait_sdk.fastapi.dependencies` | `verify_token`, `require_live_session`, `validate_configuration` |
+| `gait_sdk.application` | Verify your *service's* own Gait credential (machine identity) |
+| `gait_sdk.context` | `SecurityContext`: human identity + application identity together |
+| `gait_sdk.security` | Send tenant security signals to Gait |
+
+## Security, in one screen
+
+- **RS256 only.** `alg=none`, HS256 key-confusion and unknown algorithms are rejected. `iss`, `aud`, `exp`, `iat`, `sub`, `sid`, `jti` and `token_use="access"` are all required.
+- **The SDK holds no secrets for verification.** It only ever has Gait's *public* keys, so it cannot mint tokens even if compromised.
+- **Fails closed:** an invalid token → **401**; Gait unreachable → **503**. It never falls back to a weaker check.
+- **Real 401s** (not DRF's silent 403), so clients' refresh-on-401 logic works.
+- **Revocation:** local verification sees a revoked session only when its token expires (≤15 min). Protect sensitive actions with `require_live_session`.
+- **No token, cookie or credential value is ever logged.**
+
+Full threat model, guarantees, limits and audit history: [docs/SECURITY.md](docs/SECURITY.md). To report a vulnerability, see the same file.
+
+---
+
+## Upgrading from `auth_integration`
+
+The package was renamed in **0.5.0**. The old import name still works as a deprecated alias until 0.6.0, returning the *same* modules, so nothing breaks while you migrate:
+
+1. `pip install gait-sdk` (replacing the old git URL pin).
+2. Replace `auth_integration` with `gait_sdk` in imports, `INSTALLED_APPS`, and DRF settings strings.
+
+Details: [Integration guide](docs/INTEGRATION_GUIDE.md#upgrading-from-auth_integration).
+
+## Documentation
+
+| | |
+|---|---|
+| [Architecture](docs/ARCHITECTURE.md) | The boundary, components, verification & caching, trust model |
+| [Integration guide](docs/INTEGRATION_GUIDE.md) | Wiring into Django/FastAPI, JWKS cut-over runbook, sensitive actions, testing |
+| [Security](docs/SECURITY.md) | Threat model, guarantees, known limits, hardening checklist, audit log, reporting |
+| [Publishing](docs/PUBLISHING.md) | How releases reach PyPI (a step-by-step tutorial), and consuming safely |
+| [Changelog](docs/CHANGELOG.md) | Version history |
+| Module references | [`gait_sdk/docs/`](gait_sdk/docs/) |
+
+## License
+
+MIT, © Anthony Narine.

gait_sdk-0.5.0/README.md

@@ -0,0 +1,144 @@
+# gait-sdk
+
+[![PyPI](https://img.shields.io/pypi/v/gait-sdk.svg)](https://pypi.org/project/gait-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/gait-sdk.svg)](https://pypi.org/project/gait-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The official Python SDK for **Gait**, an identity and security platform. Drop it into a **Django REST Framework** or **FastAPI** service to verify who is calling you, using identities Gait issues. It never issues tokens, stores passwords, or makes authorization decisions.
+
+```
+Gait                authenticates   — who are you? (login, 2FA, sessions, signed tokens)
+gait-sdk            verifies        — is this token genuine, and whose is it?
+your application    authorizes      — what may this person do here?
+```
+
+That boundary is the core design rule. The SDK hands your code a verified **identity** (`subject`, `email`, session, token id, issuer). Roles, organizations and permissions belong to your application. See [Architecture](docs/ARCHITECTURE.md).
+
+---
+
+## Install
+
+```bash
+pip install "gait-sdk[django]"     # Django REST Framework services
+pip install "gait-sdk[fastapi]"    # FastAPI services
+pip install gait-sdk               # core only (verification, sessions, app identity)
+```
+
+Requires Python 3.10+. Pin exact versions in production (`gait-sdk==0.5.0`). See [Supply chain](docs/PUBLISHING.md#consuming-safely).
+
+---
+
+## Quick start: Django REST Framework
+
+```python
+# settings.py
+INSTALLED_APPS = [..., "gait_sdk"]          # validates configuration at startup
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": ["gait_sdk.authentication.ExternalJWTAuthentication"],
+}
+
+GAIT_TOKEN_VERIFIER = "jwks"                 # verify locally (recommended)
+GAIT_JWKS_URL = "https://auth.example.com/.well-known/jwks.json"
+GAIT_ISSUER = "https://auth.example.com"
+GAIT_AUDIENCE = "urn:gait:your-app"
+GAIT_AUTH_URL = "https://auth.example.com/api"   # used for live session checks
+```
+
+```python
+# views.py
+from gait_sdk.django.authentication import require_live_session
+
+class FinalizeReport(APIView):
+    def post(self, request, pk):
+        identity = request.verified_identity    # subject, email, session_id, token_id, issuer
+        ...                                     # YOUR authorization check first
+        require_live_session(request)           # sensitive action: confirm the session live
+        ...                                     # then mutate
+```
+
+## Quick start: FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from gait_sdk.fastapi.dependencies import require_live_session, validate_configuration, verify_token
+
+app = FastAPI()
+validate_configuration()   # fail at startup, not on the first request
+
+@app.get("/me")
+async def me(claims: dict = Depends(verify_token)):
+    return {"subject": claims["id"], "email": claims["email"]}   # "id" works in both verifier modes
+
+@app.post("/danger")
+async def danger(claims: dict = Depends(require_live_session)):
+    ...
+```
+
+---
+
+## Configuration
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `GAIT_TOKEN_VERIFIER` | `introspection` | `jwks` = verify tokens locally against Gait's published keys (recommended). `introspection` = ask Gait `/whoami/` on every request (legacy). Chosen explicitly, with **no automatic fallback**. |
+| `GAIT_JWKS_URL` | — | Required for `jwks`. Must be `https` (plain `http` only for `localhost`). |
+| `GAIT_ISSUER` | — | Required for `jwks`. Must equal Gait's `JWT_ISSUER` exactly. |
+| `GAIT_AUDIENCE` | — | Required for `jwks`. Must equal Gait's `JWT_AUDIENCE`. |
+| `GAIT_AUTH_URL` | — | Gait's API base (`…/api`), used by live session checks, introspection, application identity and signals. `https` required (http only for `localhost`). |
+| `GAIT_TIMEOUT` | `5` | Seconds for calls to Gait. |
+| `GAIT_APPLICATION_CREDENTIAL` | — | Only for application identity / security signals. A secret: keep it in the environment. |
+| `GAIT_ALLOW_COOKIE_AUTH` | `False` | Deprecated legacy cookie mode (introspection only). Leave off. See [Security](docs/SECURITY.md). |
+
+Settings come from Django settings first, then environment variables / `.env`. An invalid or incomplete configuration **stops the service at startup**.
+
+---
+
+## What you get
+
+| Module | For |
+|---|---|
+| `gait_sdk.verification` | Token verification (`JwksVerifier`, `IntrospectionVerifier`) → `VerifiedIdentity` |
+| `gait_sdk.session` | `check_session_live()`: live revocation check for sensitive actions |
+| `gait_sdk.authentication` / `gait_sdk.django` | DRF authentication class, `require_live_session(request)` |
+| `gait_sdk.fastapi.dependencies` | `verify_token`, `require_live_session`, `validate_configuration` |
+| `gait_sdk.application` | Verify your *service's* own Gait credential (machine identity) |
+| `gait_sdk.context` | `SecurityContext`: human identity + application identity together |
+| `gait_sdk.security` | Send tenant security signals to Gait |
+
+## Security, in one screen
+
+- **RS256 only.** `alg=none`, HS256 key-confusion and unknown algorithms are rejected. `iss`, `aud`, `exp`, `iat`, `sub`, `sid`, `jti` and `token_use="access"` are all required.
+- **The SDK holds no secrets for verification.** It only ever has Gait's *public* keys, so it cannot mint tokens even if compromised.
+- **Fails closed:** an invalid token → **401**; Gait unreachable → **503**. It never falls back to a weaker check.
+- **Real 401s** (not DRF's silent 403), so clients' refresh-on-401 logic works.
+- **Revocation:** local verification sees a revoked session only when its token expires (≤15 min). Protect sensitive actions with `require_live_session`.
+- **No token, cookie or credential value is ever logged.**
+
+Full threat model, guarantees, limits and audit history: [docs/SECURITY.md](docs/SECURITY.md). To report a vulnerability, see the same file.
+
+---
+
+## Upgrading from `auth_integration`
+
+The package was renamed in **0.5.0**. The old import name still works as a deprecated alias until 0.6.0, returning the *same* modules, so nothing breaks while you migrate:
+
+1. `pip install gait-sdk` (replacing the old git URL pin).
+2. Replace `auth_integration` with `gait_sdk` in imports, `INSTALLED_APPS`, and DRF settings strings.
+
+Details: [Integration guide](docs/INTEGRATION_GUIDE.md#upgrading-from-auth_integration).
+
+## Documentation
+
+| | |
+|---|---|
+| [Architecture](docs/ARCHITECTURE.md) | The boundary, components, verification & caching, trust model |
+| [Integration guide](docs/INTEGRATION_GUIDE.md) | Wiring into Django/FastAPI, JWKS cut-over runbook, sensitive actions, testing |
+| [Security](docs/SECURITY.md) | Threat model, guarantees, known limits, hardening checklist, audit log, reporting |
+| [Publishing](docs/PUBLISHING.md) | How releases reach PyPI (a step-by-step tutorial), and consuming safely |
+| [Changelog](docs/CHANGELOG.md) | Version history |
+| Module references | [`gait_sdk/docs/`](gait_sdk/docs/) |
+
+## License
+
+MIT, © Anthony Narine.

gait_sdk-0.5.0/auth_integration/__init__.py

@@ -0,0 +1,64 @@
+"""
+auth_integration -- DEPRECATED compatibility alias for `gait_sdk`
+=================================================================
+
+The package was renamed to `gait_sdk` in 0.5.0. This shim keeps every old
+import path working for one release so consumers can migrate in their own
+commit:
+
+    import auth_integration.verification      -> gait_sdk.verification
+    "auth_integration.authentication.ExternalJWTAuthentication"  (DRF setting)
+    INSTALLED_APPS = [..., "auth_integration"]
+
+Old names resolve to the SAME module objects as the new ones (not copies),
+so process-wide state -- the configured token verifier and its JWKS cache,
+the Django bearer cache -- is shared no matter which name a caller used.
+
+Scheduled for removal in 0.6.0. Migrate: replace `auth_integration` with
+`gait_sdk` in imports, settings strings, and INSTALLED_APPS.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+import warnings
+
+_OLD = "auth_integration"
+_NEW = "gait_sdk"
+
+warnings.warn(
+    "The 'auth_integration' package was renamed to 'gait_sdk' (0.5.0). "
+    "The old name is a deprecated alias and will be removed in 0.6.0.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+class _GaitSdkAliasFinder(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """Resolve `auth_integration.<x>` to the already-importable `gait_sdk.<x>` module object."""
+
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname.startswith(_OLD + "."):
+            if importlib.util.find_spec(_NEW + fullname[len(_OLD):]) is None:
+                return None
+            return importlib.util.spec_from_loader(fullname, self)
+        return None
+
+    def create_module(self, spec):
+        # Return the real gait_sdk module; the import system registers it in
+        # sys.modules under the old name too, so both names share one object.
+        return importlib.import_module(_NEW + spec.name[len(_OLD):])
+
+    def exec_module(self, module):
+        # Already executed when imported under its real name.
+        pass
+
+
+if not any(isinstance(f, _GaitSdkAliasFinder) for f in sys.meta_path):
+    sys.meta_path.insert(0, _GaitSdkAliasFinder())
+
+from gait_sdk import *  # noqa: E402,F401,F403
+from gait_sdk import __version__  # noqa: E402,F401

gait_sdk-0.5.0/gait_sdk/__init__.py

@@ -0,0 +1,31 @@
+# Filename: gait_sdk/__init__.py
+"""
+gait_sdk
+----------------
+Cross-framework authentication integration for Django + FastAPI.
+
+Design rules:
+-------------
+- Keep package import side-effect free.
+- Do NOT import framework-specific modules (Django/DRF/FastAPI) here.
+- Downstream services should import adapters from stable entrypoints:
+  - DRF:    gait_sdk.authentication.ExternalJWTAuthentication
+  - FastAPI: gait_sdk.fastapi.dependencies.verify_token
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+# ---------------------------------------------------------------------
+# 📌 Package Version
+# ---------------------------------------------------------------------
+# Step 1: Resolve installed version from package metadata (no heavy imports).
+try:
+    __version__ = version("gait-sdk")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+
+__all__ = ["__version__"]

gait_sdk-0.5.0/gait_sdk/application.py

@@ -0,0 +1,220 @@
+# Filename: gait_sdk/application.py
+"""
+gait_sdk.application — Gait Application (machine) identity
+====================================================================
+
+SDK2: adds Gait's machine/software identity to gait_sdk, kept
+strictly independent of — and never merged with — human identity.
+
+Framework-agnostic, deliberately mirroring `gait_sdk.client`'s own
+structure and style:
+
+- `ApplicationPrincipal` — an immutable value object representing a
+  Gait-verified Application/Organization/environment identity.
+- `verify_application()` — the one function that turns a raw
+  `ApplicationCredential` secret into a verified `ApplicationPrincipal` by
+  calling Gait's dedicated application-verification endpoint.
+
+Identity separation (do not blur this):
+-----------------------------------------------------------------------
+- `ClaimsUser` / user claims (`gait_sdk.django.authentication`,
+  `gait_sdk.fastapi.dependencies`) = HUMAN identity, derived from
+  a user JWT via Gait's `/whoami/`.
+- `ApplicationPrincipal` (this module) = SOFTWARE identity, derived from
+  an `ApplicationCredential` secret via Gait's `/applications/verify/`.
+
+Verifying one never establishes, requires, or invalidates the other — see
+`tests/test_application.py`'s independence tests. Do not add an
+organization/environment/application field to `ClaimsUser`, and do not add
+a human role to `ApplicationPrincipal`.
+
+Verified read-only against Gait's frozen backend contract
+(`applications/views.py`, `applications/serializers.py`,
+`applications/services.py`, `applications/test_verification_api.py` in the
+Gait backend repo) — not invented. Endpoint: `POST /api/applications/verify/`
+(same `GAIT_AUTH_URL` base as `/whoami/`). Credential transport: a
+dedicated header, never the human `Authorization: Bearer` header — a
+single request may need to carry both a user token and an application
+credential at once. Every failure (missing/unknown/revoked/expired
+credential, or a suspended/revoked owning Application) is a uniform 401
+with no distinguishing detail — Gait deliberately does not give an
+unauthenticated caller an oracle for probing credential/application state,
+and this SDK does not attempt to recover a finer-grained reason either.
+
+Security:
+---------
+- The raw ApplicationCredential is never logged, never stored on
+  `ApplicationPrincipal`, and never echoed into any exception message.
+- `organization_id`, `organization_slug`, and `environment` are exactly
+  what Gait's verification response says — there is no parameter on
+  `verify_application()` through which a caller can select, override, or
+  broaden any of them.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from gait_sdk.exceptions import AuthServiceUnavailable, InvalidApplicationCredentialError
+from gait_sdk.settings import GAIT_APPLICATION_CREDENTIAL, GAIT_AUTH_URL, GAIT_TIMEOUT
+
+# -----------------------------------------------------------------------------
+# ⚙️ Logger (never logs the raw credential — see verify_application)
+# -----------------------------------------------------------------------------
+logger = logging.getLogger("gait_sdk.application")
+logger.setLevel(logging.INFO)
+
+# -----------------------------------------------------------------------------
+# 🔑 Dedicated application-credential transport
+# -----------------------------------------------------------------------------
+# Must match Gait's own applications/views.py::APPLICATION_CREDENTIAL_HEADER
+# exactly — confirmed by read-only inspection of the frozen backend, not
+# guessed. Deliberately never Authorization: Bearer, which is reserved for
+# human tokens (see module docstring).
+APPLICATION_CREDENTIAL_HEADER = "Gait-Application-Credential"
+
+# Gait's own Application.Environment choices (applications/models.py),
+# mirrored here only so this SDK can fail closed on an unrecognized value.
+# This module has no opinion about what any of these environments *mean* —
+# it only refuses to build an ApplicationPrincipal around a value Gait
+# itself wouldn't have produced.
+_VALID_ENVIRONMENTS = frozenset({"local", "test", "ci", "staging", "production"})
+
+_REQUIRED_STRING_FIELDS = (
+    "application_id",
+    "application_slug",
+    "organization_id",
+    "organization_slug",
+    "environment",
+)
+
+
+# -----------------------------------------------------------------------------
+# ✅ ApplicationPrincipal — verified machine identity
+# -----------------------------------------------------------------------------
+@dataclass(frozen=True)
+class ApplicationPrincipal:
+    """A Gait-verified machine/software identity.
+
+    Represents "Gait has verified this software identity" — nothing about
+    what that software is authorized to do, and nothing about any human.
+    Every field comes directly from Gait's verification response; this SDK
+    never fills in, defaults, or overrides any of them.
+
+    Deliberately excludes: the credential itself, any credential hash/id,
+    a human role, business-domain permissions, and a Lumen Facility or
+    Lumen Organization. See module docstring for the identity-separation
+    rationale this reflects.
+    """
+
+    application_id: str
+    application_slug: str
+    organization_id: str
+    organization_slug: str
+    environment: str
+
+
+def _build_application_principal(raw: Any) -> ApplicationPrincipal:
+    """Validate Gait's verification response shape before trusting it (fail closed).
+
+    Authoritative but not blindly trusted: every required field must be a
+    non-empty string, and `environment` must be one of Gait's own known
+    values. A response missing, mistyping, or emptying any of these never
+    produces a partially-populated ApplicationPrincipal — it raises
+    AuthServiceUnavailable instead, the same failure class already used
+    for "Gait's response can't be trusted" elsewhere in this package (see
+    gait_sdk.client.validate_token's own malformed-JSON handling).
+    """
+    if not isinstance(raw, dict):
+        raise AuthServiceUnavailable("Malformed response from authentication service.")
+
+    for key in _REQUIRED_STRING_FIELDS:
+        value = raw.get(key)
+        if not isinstance(value, str) or not value:
+            raise AuthServiceUnavailable("Malformed response from authentication service.")
+
+    if raw["environment"] not in _VALID_ENVIRONMENTS:
+        raise AuthServiceUnavailable("Malformed response from authentication service.")
+
+    return ApplicationPrincipal(
+        application_id=raw["application_id"],
+        application_slug=raw["application_slug"],
+        organization_id=raw["organization_id"],
+        organization_slug=raw["organization_slug"],
+        environment=raw["environment"],
+    )
+
+
+# -----------------------------------------------------------------------------
+# 🔐 Public API — verify_application
+# -----------------------------------------------------------------------------
+async def verify_application(credential: Optional[str] = None) -> ApplicationPrincipal:
+    """
+    Verify a Gait ApplicationCredential and return the resulting ApplicationPrincipal.
+
+    Args:
+        credential: The raw ApplicationCredential secret. If omitted, falls
+            back to the server-side `GAIT_APPLICATION_CREDENTIAL` setting.
+            This value is a backend secret — never accept it from a
+            browser/frontend request, and never pass a value a caller
+            supplied over an untrusted channel.
+
+    Returns:
+        ApplicationPrincipal: the Gait-verified machine identity. Its
+        `organization_id`, `organization_slug`, and `environment` are
+        exactly what Gait returned — there is no argument here through
+        which a caller can select or broaden any of them (see PART 9/10 of
+        the SDK2 milestone this implements).
+
+    Raises:
+        InvalidApplicationCredentialError: the credential is missing (not
+            configured/provided) or Gait rejected it (unknown, revoked,
+            expired, or belongs to a suspended/revoked Application) — Gait
+            itself does not distinguish these reasons in its own response,
+            and this SDK does not attempt to re-derive a finer-grained one.
+        AuthServiceUnavailable: Gait is unreachable, times out, or returns
+            a response this SDK cannot parse or trust (malformed JSON, an
+            unexpected status code, or a structurally invalid identity
+            payload).
+    """
+    # Step 1: resolve the credential — explicit failure if none exists,
+    # never a silently manufactured or fallback identity.
+    raw_credential = credential if credential is not None else GAIT_APPLICATION_CREDENTIAL
+    if not raw_credential:
+        logger.error("No application credential configured or provided - cannot verify.")
+        raise InvalidApplicationCredentialError("Application credential is not configured.")
+
+    if not GAIT_AUTH_URL:
+        logger.error("Missing GAIT_AUTH_URL - cannot verify application identity.")
+        raise AuthServiceUnavailable("Authentication service misconfigured.")
+
+    url = f"{GAIT_AUTH_URL.rstrip('/')}/applications/verify/"
+    headers = {APPLICATION_CREDENTIAL_HEADER: raw_credential}
+
+    # Step 2: call Gait. Never log `headers` or `raw_credential`.
+    try:
+        async with httpx.AsyncClient(timeout=GAIT_TIMEOUT) as client:
+            response = await client.post(url, headers=headers)
+    except httpx.RequestError:
+        logger.error("Gait application-verification API unreachable.")
+        raise AuthServiceUnavailable("Authentication service unreachable.")
+
+    # Step 3: interpret the response.
+    if response.status_code == 200:
+        try:
+            raw = response.json()
+        except Exception:
+            logger.error("Malformed JSON from Gait during application verification.")
+            raise AuthServiceUnavailable("Malformed response from authentication service.")
+        return _build_application_principal(raw)
+
+    if response.status_code == 401:
+        logger.warning("Application credential rejected by Gait.")
+        raise InvalidApplicationCredentialError("Invalid application credential.")
+
+    logger.error("Unexpected status %s from Gait during application verification.", response.status_code)
+    raise AuthServiceUnavailable(f"Unexpected response: {response.status_code}")