obelisk-auth 1.0.0__tar.gz

obelisk_auth-1.0.0/.gitignore

@@ -0,0 +1,56 @@
+node_modules/
+coverage/
+dist/
+.cache/
+# W270 — Playwright capture output. The CANON-053 evidence record is the
+# hash-bound docs/visual-qa/LATEST.json; the PNGs themselves are regenerable
+# local artifacts (14MB+ of binary churn per visual wave does not belong in git).
+output/
+.env
+.env.*
+!.env.example
+*.log
+audits/mcp-keys.json
+audits/*.key
+audits/*.pem
+audits/grants-secret.key
+audits/oidc-signing-key.pem
+# S321 — the post-quantum signing key. `audits/*.pem` already covered the ES256
+# key, but the ML-DSA key persists as an RFC 9964 AKP *JWK* whose `priv` member is
+# the 32-byte seed, so it is a PRIVATE KEY with a .jwk extension that no existing
+# pattern matched. Glob, not just the literal, so a rotation sibling
+# (pq-signing-key.prev.jwk / .next.jwk) cannot be committed either.
+audits/pq-signing-key*.jwk
+audits/*.lock
+context/.session-lock
+STUDIO_AI_MODEL_v2_mobile_frontier_research.docx
+STUDIO_AI_MODEL_v2_mobile_frontier_research.html
+.ops-cache/
+secrets/
+
+# stale root session-lock (canonical lock is context/.session-lock)
+.session-lock
+
+# Python
+__pycache__/
+*.pyc
+
+.secrets/
+
+# W141 deploy artifact — stamped by gate-deploy.mjs per deploy, never source
+build-info.json
+
+# W214 — ledger reconciliation backup written by scripts/dedupe-cache-ledger.mjs
+# (git history is the real backup; the .bak is a local safety net, never source)
+*.ndjson.bak
+
+# Atomic-write temp files (never commit interrupted .tmp debris — W230)
+audits/.*.tmp
+*.tmp
+
+# W239 — propagation quarantine. The guard copies every landed blob here before
+# removing it, so a rejected propagation is always recoverable. Local forensic
+# state, not repo content: committing it would add the very clobber the guard
+# just rejected. audits/propagation-log.jsonl is the committed, append-only
+# record of what happened.
+.quarantine/

obelisk_auth-1.0.0/LICENSE

@@ -0,0 +1,83 @@
+Obelisk Client SDK License Agreement
+
+Copyright (c) 2026 VaultSpark Studios LLC. All rights reserved.
+
+This is a proprietary software license, not an open-source license. By
+installing, copying, or otherwise using the software package
+"@vaultspark/obelisk-auth" and its contents (the "SDK"), you ("Licensee")
+agree to be bound by this Agreement. If you do not agree, do not install or
+use the SDK.
+
+1. DEFINITIONS.
+   "Licensor" means VaultSpark Studios LLC.
+   "Obelisk Gate Service" means the hosted identity and authentication service
+   operated by Licensor at obeliskgate.com (and its official successors).
+   "Application" means Licensee's own software product or service that
+   integrates with the Obelisk Gate Service by means of the SDK.
+
+2. LICENSE GRANT. Subject to Licensee's continuous compliance with this
+   Agreement, Licensor grants Licensee a limited, non-exclusive,
+   non-transferable, non-sublicensable, revocable license to install and use
+   the SDK in unmodified form, solely to integrate Licensee's Application with
+   the official Obelisk Gate Service. No other rights are granted.
+
+3. RESTRICTIONS. Except to the extent this Section is unenforceable under
+   applicable law, Licensee shall NOT, and shall not permit any third party to:
+   (a) fork, copy (except a single installation copy as strictly necessary to
+       use the SDK as permitted), or create derivative works of the SDK;
+   (b) modify, adapt, translate, or alter the SDK, other than supplying the
+       configuration values documented in the README;
+   (c) distribute, publish, sublicense, sell, rent, lease, host, or otherwise
+       make the SDK (or any part of it, in source or object form) available to
+       any third party, except as unmodified installation copies bundled inside
+       Licensee's own Application solely to call the Obelisk Gate Service;
+   (d) reverse engineer, decompile, or disassemble the SDK, except to the
+       limited extent applicable law expressly permits despite this limitation;
+   (e) use the SDK with, or to build, any service other than the official
+       Obelisk Gate Service, including any competing or substitute identity,
+       authentication, or authorization service;
+   (f) remove, obscure, or alter any copyright, trademark, license, or
+       attribution notice in or on the SDK; or
+   (g) use the names, logos, or trademarks of Licensor except as permitted by
+       the TRADEMARKS.md file included with the SDK.
+
+4. RESERVATION OF RIGHTS. The SDK is licensed, not sold. Licensor and its
+   licensors retain all right, title, and interest in and to the SDK, including
+   all intellectual property rights. All rights not expressly granted are
+   reserved. The Obelisk Gate Service itself — including its identity provider,
+   the Obelisk Rating engine, the tamper-evident receipt chain, the Obelisk
+   Warden risk engine, and all server-side software and infrastructure — is
+   proprietary, is NOT included in or licensed by the SDK, and is not covered by
+   this Agreement.
+
+5. TRADEMARKS. "Obelisk", "Obelisk Gate", "Obelisk Rating", "Obelisk Warden",
+   and "VaultSpark" are trademarks of Licensor. This Agreement grants no
+   trademark rights except as expressly stated in TRADEMARKS.md.
+
+6. TERM AND TERMINATION. This Agreement is effective until terminated. It
+   terminates automatically and immediately upon any breach by Licensee. Upon
+   termination, Licensee shall cease all use of the SDK and destroy all copies.
+   Sections 3 through 10 survive termination.
+
+7. USE OF THE SERVICE. Access to and use of the Obelisk Gate Service is governed
+   by its own terms of service (the Gate Toll Terms at obeliskgate.com/legal/terms).
+   This Agreement covers only the SDK, and confers no right to use the Service.
+
+8. DISCLAIMER OF WARRANTY. THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE",
+   WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+   TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE,
+   AND NON-INFRINGEMENT. LICENSEE BEARS THE ENTIRE RISK OF USE.
+
+9. LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT
+   SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, REVENUE, DATA, OR
+   GOODWILL, ARISING OUT OF OR RELATED TO THE SDK OR THIS AGREEMENT. LICENSOR'S
+   TOTAL AGGREGATE LIABILITY SHALL NOT EXCEED USD $100.
+
+10. GENERAL. This Agreement is governed by the laws of the State of Delaware,
+    USA, without regard to conflict-of-laws rules. If any provision is held
+    unenforceable, the remaining provisions remain in effect. This Agreement is
+    the entire agreement between the parties regarding the SDK and supersedes
+    all prior understandings regarding its subject matter.
+
+Contact: https://obeliskgate.com/help

obelisk_auth-1.0.0/NOTICE

@@ -0,0 +1,17 @@
+@vaultspark/obelisk-auth
+Copyright (c) 2026 VaultSpark Studios LLC. All rights reserved.
+
+This is PROPRIETARY software, licensed — not sold — under the Obelisk Client SDK
+License Agreement (see the LICENSE file). It is NOT open source. You may install
+and use it in unmodified form solely to integrate your application with the
+official Obelisk Gate Service. Forking, modification, redistribution, reverse
+engineering, and use with any other service are prohibited. See LICENSE for the
+full terms and TRADEMARKS.md for trademark use.
+
+"Obelisk", "Obelisk Gate", "Obelisk Rating", "Obelisk Warden", and "VaultSpark"
+are trademarks of VaultSpark Studios LLC.
+
+This package is a CLIENT SDK only. The Obelisk Gate Service — its identity
+provider, the Obelisk Rating engine, the tamper-evident receipt chain, and the
+Obelisk Warden risk engine — is a proprietary hosted service and is not included
+in, disclosed by, or licensed by this package.

obelisk_auth-1.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: obelisk-auth
+Version: 1.0.0
+Summary: Drop-in OIDC client for the Obelisk Gate identity platform — login, tokens, refresh, userinfo, and local ES256 token verification.
+Project-URL: Homepage, https://obeliskgate.com
+Author: VaultSpark Studios
+License: Proprietary
+License-File: LICENSE
+License-File: NOTICE
+Keywords: auth,es256,jwt,obelisk,oidc,openid-connect,pkce
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# obelisk-auth (Python)
+
+A drop-in OIDC client for the **Obelisk Gate** identity platform
+(`https://obeliskgate.com`). It is the Python counterpart of the JavaScript
+`@obeliskgate/obelisk-auth` package and speaks the exact same contract: login +
+tokens + refresh + userinfo + **local** ES256 token verification.
+
+Obelisk is a conformant OpenID Connect provider:
+
+- `GET /.well-known/openid-configuration` — discovery (RFC 8414)
+- `GET /.well-known/jwks.json` — JWKS (ES256 / P-256 public keys)
+- `GET /auth/authorize` — authorization-code flow, **PKCE S256 only**
+- `POST /auth/token` — exchange `code`+`code_verifier` → `id_token` / `access_token` / `refresh_token`
+- `GET /auth/userinfo` — Bearer-authenticated claims
+
+Tokens are ES256 JWTs, so they can be verified **locally** against the cached
+JWKS with no network round-trip per request — the property that makes Obelisk
+useful as an agent-era auth plane.
+
+## The agent-era angle
+
+Every token is locally verifiable, and the **id_token** carries an `obelisk`
+claim block that proves *how* the principal authenticated:
+
+```json
+"obelisk": {
+  "v": "obelisk-claims-v1",
+  "assurance": "passkey",
+  "anchor": "0a1b2c3d...",
+  "rating": { "...": "live issuer security posture" }
+}
+```
+
+`assurance` distinguishes operator-proof factors (passkey) from weaker ones, and
+`anchor` ties the issuance into Obelisk's tamper-evident receipt chain. Pull it
+out of verified claims with `obelisk_block(claims)`.
+
+## Install
+
+```bash
+pip install obelisk-auth
+```
+
+Dependencies are stdlib `urllib` for HTTP plus `PyJWT` and `cryptography` for
+ES256 verification (no hand-rolled crypto).
+
+## Login (copy-paste)
+
+```python
+from obelisk_auth import ObeliskAuth, obelisk_block
+
+auth = ObeliskAuth(
+    issuer="https://obeliskgate.com",
+    client_id="rp-statvault",
+    redirect_uri="https://statvault.org/auth/callback",
+)
+
+# 1) Start the login. Persist code_verifier + state + nonce in the user session,
+#    then redirect the browser to the authorization URL.
+login = auth.begin_login(scope="openid profile offline_access")
+session["pkce"] = {
+    "code_verifier": login.code_verifier,
+    "state": login.state,
+    "nonce": login.nonce,
+}
+redirect(login.authorization_url)
+
+# 2) On the callback (e.g. /auth/callback?code=...&state=...):
+#    First confirm the returned `state` matches what you stashed (CSRF defense).
+assert request.args["state"] == session["pkce"]["state"]
+
+result = auth.complete_login(
+    code=request.args["code"],
+    code_verifier=session["pkce"]["code_verifier"],
+    nonce=session["pkce"]["nonce"],
+)
+
+print(result.claims["sub"])                 # the user's stable subject id
+print(obelisk_block(result.claims))         # assurance + anchor + rating
+
+access_token = result.tokens["access_token"]
+refresh_token = result.tokens.get("refresh_token")  # present with offline_access
+```
+
+## Verify a token locally (no network per request)
+
+```python
+from obelisk_auth import ObeliskAuth, obelisk_block
+
+auth = ObeliskAuth(
+    issuer="https://obeliskgate.com",
+    client_id="rp-statvault",
+    redirect_uri="https://statvault.org/auth/callback",
+)
+
+# On a protected route, given a Bearer access token:
+v = auth.verify_access_token(bearer_token)
+if not v.ok:
+    raise Unauthorized(v.reason)            # e.g. "expired", "issuer-mismatch"
+
+print(v.claims["sub"])
+
+# Gate capability on how the user proved themselves:
+block = obelisk_block(v.claims)
+if block and block.get("assurance") != "passkey":
+    raise Forbidden("this action requires a passkey-proven session")
+```
+
+The first `verify_*` call fetches the JWKS once and caches it by `kid`; later
+calls verify in-process. If a key rotates (unknown `kid`), the SDK refetches the
+JWKS exactly once and retries.
+
+## Refresh + userinfo
+
+```python
+rotated = auth.refresh(refresh_token)       # rotating refresh tokens
+new_access = rotated["access_token"]
+
+info = auth.get_userinfo(new_access)        # Bearer-authenticated userinfo
+print(info["sub"])
+```
+
+> Reusing a superseded refresh token revokes the whole token family on the
+> server (OAuth 2.0 BCP reuse detection); be prepared to force re-authentication.
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `discover()` | Fetch + cache the discovery document. |
+| `get_jwks(force=False)` | Fetch + cache the JWKS. |
+| `begin_login(scope=...)` → `LoginStart` | PKCE S256 authorize URL + `code_verifier`/`state`/`nonce`. |
+| `complete_login(code, code_verifier, nonce=...)` → `LoginResult` | Exchange + verify id_token. |
+| `verify_id_token(id_token, nonce=...)` | Local ES256 verify (raises on failure). |
+| `verify_access_token(token)` → `VerifyResult` | Local ES256 verify (never raises). |
+| `refresh(refresh_token)` | Rotate a refresh token. |
+| `get_userinfo(access_token)` | Bearer userinfo. |
+| `obelisk_block(claims)` | Extract the verified `obelisk` assurance block. |
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The bundled tests are pure unit tests (no live server): PKCE-S256 challenge
+correctness, authorization-URL construction, full login flow against a mocked
+token endpoint, and round-trip ES256 sign/verify with a generated P-256 key.

obelisk_auth-1.0.0/README.md

@@ -0,0 +1,149 @@
+# obelisk-auth (Python)
+
+A drop-in OIDC client for the **Obelisk Gate** identity platform
+(`https://obeliskgate.com`). It is the Python counterpart of the JavaScript
+`@obeliskgate/obelisk-auth` package and speaks the exact same contract: login +
+tokens + refresh + userinfo + **local** ES256 token verification.
+
+Obelisk is a conformant OpenID Connect provider:
+
+- `GET /.well-known/openid-configuration` — discovery (RFC 8414)
+- `GET /.well-known/jwks.json` — JWKS (ES256 / P-256 public keys)
+- `GET /auth/authorize` — authorization-code flow, **PKCE S256 only**
+- `POST /auth/token` — exchange `code`+`code_verifier` → `id_token` / `access_token` / `refresh_token`
+- `GET /auth/userinfo` — Bearer-authenticated claims
+
+Tokens are ES256 JWTs, so they can be verified **locally** against the cached
+JWKS with no network round-trip per request — the property that makes Obelisk
+useful as an agent-era auth plane.
+
+## The agent-era angle
+
+Every token is locally verifiable, and the **id_token** carries an `obelisk`
+claim block that proves *how* the principal authenticated:
+
+```json
+"obelisk": {
+  "v": "obelisk-claims-v1",
+  "assurance": "passkey",
+  "anchor": "0a1b2c3d...",
+  "rating": { "...": "live issuer security posture" }
+}
+```
+
+`assurance` distinguishes operator-proof factors (passkey) from weaker ones, and
+`anchor` ties the issuance into Obelisk's tamper-evident receipt chain. Pull it
+out of verified claims with `obelisk_block(claims)`.
+
+## Install
+
+```bash
+pip install obelisk-auth
+```
+
+Dependencies are stdlib `urllib` for HTTP plus `PyJWT` and `cryptography` for
+ES256 verification (no hand-rolled crypto).
+
+## Login (copy-paste)
+
+```python
+from obelisk_auth import ObeliskAuth, obelisk_block
+
+auth = ObeliskAuth(
+    issuer="https://obeliskgate.com",
+    client_id="rp-statvault",
+    redirect_uri="https://statvault.org/auth/callback",
+)
+
+# 1) Start the login. Persist code_verifier + state + nonce in the user session,
+#    then redirect the browser to the authorization URL.
+login = auth.begin_login(scope="openid profile offline_access")
+session["pkce"] = {
+    "code_verifier": login.code_verifier,
+    "state": login.state,
+    "nonce": login.nonce,
+}
+redirect(login.authorization_url)
+
+# 2) On the callback (e.g. /auth/callback?code=...&state=...):
+#    First confirm the returned `state` matches what you stashed (CSRF defense).
+assert request.args["state"] == session["pkce"]["state"]
+
+result = auth.complete_login(
+    code=request.args["code"],
+    code_verifier=session["pkce"]["code_verifier"],
+    nonce=session["pkce"]["nonce"],
+)
+
+print(result.claims["sub"])                 # the user's stable subject id
+print(obelisk_block(result.claims))         # assurance + anchor + rating
+
+access_token = result.tokens["access_token"]
+refresh_token = result.tokens.get("refresh_token")  # present with offline_access
+```
+
+## Verify a token locally (no network per request)
+
+```python
+from obelisk_auth import ObeliskAuth, obelisk_block
+
+auth = ObeliskAuth(
+    issuer="https://obeliskgate.com",
+    client_id="rp-statvault",
+    redirect_uri="https://statvault.org/auth/callback",
+)
+
+# On a protected route, given a Bearer access token:
+v = auth.verify_access_token(bearer_token)
+if not v.ok:
+    raise Unauthorized(v.reason)            # e.g. "expired", "issuer-mismatch"
+
+print(v.claims["sub"])
+
+# Gate capability on how the user proved themselves:
+block = obelisk_block(v.claims)
+if block and block.get("assurance") != "passkey":
+    raise Forbidden("this action requires a passkey-proven session")
+```
+
+The first `verify_*` call fetches the JWKS once and caches it by `kid`; later
+calls verify in-process. If a key rotates (unknown `kid`), the SDK refetches the
+JWKS exactly once and retries.
+
+## Refresh + userinfo
+
+```python
+rotated = auth.refresh(refresh_token)       # rotating refresh tokens
+new_access = rotated["access_token"]
+
+info = auth.get_userinfo(new_access)        # Bearer-authenticated userinfo
+print(info["sub"])
+```
+
+> Reusing a superseded refresh token revokes the whole token family on the
+> server (OAuth 2.0 BCP reuse detection); be prepared to force re-authentication.
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `discover()` | Fetch + cache the discovery document. |
+| `get_jwks(force=False)` | Fetch + cache the JWKS. |
+| `begin_login(scope=...)` → `LoginStart` | PKCE S256 authorize URL + `code_verifier`/`state`/`nonce`. |
+| `complete_login(code, code_verifier, nonce=...)` → `LoginResult` | Exchange + verify id_token. |
+| `verify_id_token(id_token, nonce=...)` | Local ES256 verify (raises on failure). |
+| `verify_access_token(token)` → `VerifyResult` | Local ES256 verify (never raises). |
+| `refresh(refresh_token)` | Rotate a refresh token. |
+| `get_userinfo(access_token)` | Bearer userinfo. |
+| `obelisk_block(claims)` | Extract the verified `obelisk` assurance block. |
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The bundled tests are pure unit tests (no live server): PKCE-S256 challenge
+correctness, authorization-URL construction, full login flow against a mocked
+token endpoint, and round-trip ES256 sign/verify with a generated P-256 key.

obelisk_auth-1.0.0/obelisk_auth/__init__.py

@@ -0,0 +1,455 @@
+"""obelisk_auth — a drop-in OIDC client for the Obelisk Gate identity platform.
+
+Obelisk (https://obeliskgate.com) is a conformant OpenID Connect provider. This
+SDK is the Python counterpart of the JavaScript ``@vaultspark/obelisk-auth``
+package: it gives any service login + tokens + refresh + userinfo + **local**
+token verification by pointing it at an Obelisk issuer. No per-service auth
+engine, no hand-rolled crypto.
+
+The agent-era angle
+-------------------
+The interesting property for autonomous agents is that **every token can be
+verified locally, with zero network round-trips per request**. Obelisk signs
+ES256 (ECDSA P-256 / SHA-256) JWTs and publishes its public keys at
+``/.well-known/jwks.json``; this SDK fetches that JWKS once, caches it by ``kid``,
+and verifies signatures in-process (refetching only on key rotation). An agent
+holding a token can therefore prove the token's authenticity offline.
+
+Beyond plain authenticity, Obelisk's **id_token** carries an ``obelisk`` claim
+block::
+
+    "obelisk": {
+        "v": "obelisk-claims-v1",
+        "assurance": "passkey",   # HOW the user proved themselves
+        "anchor": "<32-hex>",     # receipt anchor binding this issuance
+        "rating": { ... },        # the issuer's live security posture
+        "tenant": "<id>"          # optional tenant binding
+    }
+
+``assurance`` tells a relying party *how* the principal proved themselves
+(passkey is operator-proof; sole-factor TOTP is not), and ``anchor`` ties the
+issuance to Obelisk's tamper-evident receipt chain. Use :func:`obelisk_block`
+to pull this block out of verified claims and gate capability on it.
+
+Standard-library-first
+-----------------------
+HTTP uses ``urllib`` from the stdlib. The only third-party dependencies are
+``cryptography`` and ``PyJWT`` (declared in ``pyproject.toml``) — used solely so
+the ES256 signature verification reuses battle-tested JOSE crypto rather than
+re-implementing it.
+
+Quickstart
+----------
+>>> from obelisk_auth import ObeliskAuth
+>>> auth = ObeliskAuth(
+...     issuer="https://obeliskgate.com",
+...     client_id="rp-statvault",
+...     redirect_uri="https://statvault.org/auth/callback",
+... )
+>>> login = auth.begin_login(scope="openid profile offline_access")
+>>> # persist login.code_verifier + login.state + login.nonce in the user session,
+>>> # then redirect the browser to login.authorization_url ...
+>>> # ... on the callback (after validating that `state` matches what you stashed):
+>>> result = auth.complete_login(code, login.code_verifier, nonce=login.nonce)
+>>> result.claims["sub"]          # doctest: +SKIP
+'founder'
+>>> # protect a route with a Bearer token, no network per request:
+>>> v = auth.verify_access_token(bearer_token)  # doctest: +SKIP
+>>> v.ok                                          # doctest: +SKIP
+True
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+import jwt as pyjwt
+from jwt import PyJWK, PyJWKSet
+
+__all__ = [
+    "ObeliskAuth",
+    "LoginStart",
+    "LoginResult",
+    "VerifyResult",
+    "ObeliskError",
+    "pkce_challenge_s256",
+    "obelisk_block",
+]
+
+__version__ = "1.0.0"
+
+# A fetch function: (url, *, method, headers, body) -> (status, parsed_json).
+FetchFn = Callable[..., Any]
+
+
+class ObeliskError(Exception):
+    """Raised when an Obelisk operation fails (token exchange, verification)."""
+
+
+# ── value objects ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class LoginStart:
+    """The output of :meth:`ObeliskAuth.begin_login`.
+
+    ``code_verifier``, ``state`` and ``nonce`` MUST be persisted in the user's
+    session and used to validate the callback. ``authorization_url`` is where the
+    browser is redirected.
+    """
+
+    authorization_url: str
+    code_verifier: str
+    state: str
+    nonce: str
+
+    def __iter__(self):  # allow tuple-unpacking: url, verifier, state, nonce = login
+        yield self.authorization_url
+        yield self.code_verifier
+        yield self.state
+        yield self.nonce
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    """The output of :meth:`ObeliskAuth.complete_login`."""
+
+    tokens: Dict[str, Any]
+    claims: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    """The output of :meth:`ObeliskAuth.verify_access_token`."""
+
+    ok: bool
+    claims: Dict[str, Any] = field(default_factory=dict)
+    reason: Optional[str] = None
+
+
+# ── PKCE (RFC 7636, S256 only) ───────────────────────────────────────────────
+
+
+def _b64u_no_pad(raw: bytes) -> str:
+    """base64url encode without padding (the JOSE / RFC 7636 convention)."""
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def pkce_challenge_s256(verifier: str) -> str:
+    """Return the S256 code challenge for a verifier.
+
+    Matches the Gate's ``pkceChallengeS256`` in ``auth-kit/src/oidc.js`` exactly::
+
+        base64url( SHA-256( utf8(verifier) ) )   # no padding
+
+    The Gate verifies with ``verifyPkceS256`` (constant-time compare of this same
+    value), so the challenge we send here is precisely what it recomputes from the
+    ``code_verifier`` at the token endpoint.
+    """
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return _b64u_no_pad(digest)
+
+
+# ── obelisk claim block helper ───────────────────────────────────────────────
+
+
+def obelisk_block(claims: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Extract the ``obelisk`` assurance claim block from verified claims.
+
+    Returns the block (``{"v", "assurance", "anchor", "rating", ...}``) or
+    ``None`` if the token carries no such block. Only trust this AFTER the
+    claims have been verified (e.g. via :meth:`ObeliskAuth.verify_access_token`
+    or :meth:`ObeliskAuth.verify_id_token`).
+    """
+    block = claims.get("obelisk")
+    return block if isinstance(block, dict) else None
+
+
+# ── HTTP (stdlib urllib) ─────────────────────────────────────────────────────
+
+
+def _default_fetch(
+    url: str,
+    *,
+    method: str = "GET",
+    headers: Optional[Dict[str, str]] = None,
+    body: Optional[str] = None,
+    timeout: float = 15.0,
+) -> Any:
+    """Minimal JSON fetch over ``urllib``. Returns parsed JSON (any type)."""
+    data = body.encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method, headers=headers or {})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (trusted issuer)
+        raw = resp.read().decode("utf-8")
+    return json.loads(raw) if raw else {}
+
+
+# ── the client ───────────────────────────────────────────────────────────────
+
+
+class ObeliskAuth:
+    """An OIDC client for an Obelisk Gate issuer.
+
+    Parameters
+    ----------
+    issuer:
+        The Obelisk Gate origin, e.g. ``https://obeliskgate.com``.
+    client_id:
+        This relying party's ``client_id`` (also the token audience).
+    redirect_uri:
+        The registered callback URL for this relying party.
+    client_secret:
+        Optional confidential-client secret (sent as ``client_secret`` form
+        field). Public PKCE clients leave this ``None``.
+    fetch_impl:
+        Optional HTTP override with signature
+        ``(url, *, method, headers, body) -> parsed_json``. Defaults to a stdlib
+        ``urllib`` implementation. Override it to inject mocks in tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        issuer: str,
+        client_id: str,
+        redirect_uri: str,
+        client_secret: Optional[str] = None,
+        fetch_impl: Optional[FetchFn] = None,
+    ) -> None:
+        if not issuer or not client_id:
+            raise ValueError("obelisk-auth: issuer + client_id required")
+        self._base = str(issuer).rstrip("/")
+        self.issuer = issuer
+        self.client_id = client_id
+        self.redirect_uri = redirect_uri
+        self._client_secret = client_secret
+        self._fetch = fetch_impl or _default_fetch
+        self._discovery: Optional[Dict[str, Any]] = None
+        self._jwks: Optional[PyJWKSet] = None
+
+    # ── discovery + JWKS ─────────────────────────────────────────────────────
+
+    def discover(self) -> Dict[str, Any]:
+        """Fetch (and cache) the OIDC discovery document (RFC 8414)."""
+        if self._discovery is None:
+            url = f"{self._base}/.well-known/openid-configuration"
+            self._discovery = self._fetch(url, method="GET")
+        return self._discovery
+
+    def get_jwks(self, force: bool = False) -> PyJWKSet:
+        """Fetch (and cache) the issuer JWKS. ``force`` refetches on rotation."""
+        if self._jwks is None or force:
+            d = self.discover()
+            url = d.get("jwks_uri") or f"{self._base}/.well-known/jwks.json"
+            raw = self._fetch(url, method="GET")
+            self._jwks = PyJWKSet.from_dict(raw)
+        return self._jwks
+
+    def _key_for(self, token: str) -> PyJWK:
+        """Resolve the signing key for a token by ``kid``; refetch once on miss."""
+        header = pyjwt.get_unverified_header(token)
+        kid = header.get("kid")
+        try:
+            return self.get_jwks().__getitem__(kid) if kid else self._single_key(self.get_jwks())
+        except (KeyError, pyjwt.PyJWKSetError):
+            # key rotated → refetch the JWKS once, then retry. Normalize a final
+            # miss to PyJWKSetError so callers have one exception type to handle.
+            jwks = self.get_jwks(force=True)
+            try:
+                return jwks[kid] if kid else self._single_key(jwks)
+            except KeyError as exc:
+                raise pyjwt.PyJWKSetError(
+                    f"no key for kid: {kid}"
+                ) from exc
+
+    @staticmethod
+    def _single_key(jwks: PyJWKSet) -> PyJWK:
+        keys = list(jwks.keys)
+        if not keys:
+            raise ObeliskError("obelisk-auth: empty JWKS")
+        return keys[0]
+
+    # ── login start ──────────────────────────────────────────────────────────
+
+    def begin_login(
+        self,
+        *,
+        scope: str = "openid profile",
+        extra: Optional[Dict[str, str]] = None,
+    ) -> LoginStart:
+        """Start an authorization-code + PKCE (S256) login.
+
+        Returns a :class:`LoginStart` whose ``code_verifier``, ``state`` and
+        ``nonce`` the caller MUST persist in the user's session to validate the
+        callback. Redirect the browser to ``authorization_url``.
+        """
+        code_verifier = secrets.token_urlsafe(32)
+        state = secrets.token_urlsafe(16)
+        nonce = secrets.token_urlsafe(16)
+        d = self.discover()
+        endpoint = d.get("authorization_endpoint") or f"{self._base}/auth/authorize"
+        params = {
+            "response_type": "code",
+            "client_id": self.client_id,
+            "redirect_uri": self.redirect_uri,
+            "scope": scope,
+            "state": state,
+            "nonce": nonce,
+            "code_challenge": pkce_challenge_s256(code_verifier),
+            "code_challenge_method": "S256",  # Obelisk accepts S256 ONLY
+        }
+        if extra:
+            params.update(extra)
+        url = f"{endpoint}?{urllib.parse.urlencode(params)}"
+        return LoginStart(
+            authorization_url=url,
+            code_verifier=code_verifier,
+            state=state,
+            nonce=nonce,
+        )
+
+    # ── login completion ─────────────────────────────────────────────────────
+
+    def complete_login(
+        self,
+        code: str,
+        code_verifier: str,
+        *,
+        nonce: Optional[str] = None,
+    ) -> LoginResult:
+        """Exchange a callback ``code`` for tokens and verify the id_token.
+
+        Pass the ``code_verifier`` and ``nonce`` stashed in
+        :meth:`begin_login`. The id_token signature, issuer, audience and (if
+        provided) nonce are all verified locally. Raises :class:`ObeliskError`
+        on any failure.
+        """
+        d = self.discover()
+        endpoint = d.get("token_endpoint") or f"{self._base}/auth/token"
+        form = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+            "client_id": self.client_id,
+            "code_verifier": code_verifier,
+        }
+        if self._client_secret:
+            form["client_secret"] = self._client_secret
+        tokens = self._fetch(
+            endpoint,
+            method="POST",
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            body=urllib.parse.urlencode(form),
+        )
+        if not tokens or tokens.get("error"):
+            raise ObeliskError(
+                f"obelisk-auth: token exchange failed ({tokens and tokens.get('error')})"
+            )
+        claims = self.verify_id_token(tokens["id_token"], nonce=nonce)
+        return LoginResult(tokens=tokens, claims=claims)
+
+    # ── verification ─────────────────────────────────────────────────────────
+
+    def _decode(
+        self,
+        token: str,
+        *,
+        audience: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Verify an ES256 JWT locally against the cached JWKS.
+
+        Checks signature + ``exp``/``nbf`` + ``iss`` (+ ``aud`` when given). Raises
+        ``pyjwt`` exceptions on failure; callers translate them.
+        """
+        key = self._key_for(token)
+        options = {"require": ["exp", "iss"]}
+        return pyjwt.decode(
+            token,
+            key=key.key,
+            algorithms=["ES256"],  # Obelisk signs ES256 ONLY
+            issuer=self._base,
+            audience=audience,
+            options=options if audience else {"require": ["exp", "iss"], "verify_aud": False},
+        )
+
+    def verify_id_token(
+        self,
+        id_token: str,
+        *,
+        nonce: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Verify an id_token (signature + iss + aud + optional nonce).
+
+        Returns the verified claims. Raises :class:`ObeliskError` if invalid or
+        if the nonce does not match.
+        """
+        try:
+            claims = self._decode(id_token, audience=self.client_id)
+        except pyjwt.PyJWTError as exc:
+            raise ObeliskError(f"obelisk-auth: id_token invalid ({exc})") from exc
+        if nonce is not None and claims.get("nonce") != nonce:
+            raise ObeliskError("obelisk-auth: nonce mismatch")
+        return claims
+
+    def verify_access_token(self, access_token: str) -> VerifyResult:
+        """Verify a Bearer access token locally (no network per request).
+
+        Returns a :class:`VerifyResult`; ``ok=False`` carries a ``reason`` rather
+        than raising, so it is convenient to use in request-path guards.
+        """
+        try:
+            claims = self._decode(access_token, audience=None)
+        except pyjwt.ExpiredSignatureError:
+            return VerifyResult(ok=False, reason="expired")
+        except pyjwt.ImmatureSignatureError:
+            return VerifyResult(ok=False, reason="not-yet-valid")
+        except pyjwt.InvalidIssuerError:
+            return VerifyResult(ok=False, reason="issuer-mismatch")
+        except (pyjwt.PyJWKSetError, KeyError):
+            # No JWK matches the token's kid (even after a forced refetch) —
+            # the token was signed by a key this issuer does not publish.
+            return VerifyResult(ok=False, reason="no-key")
+        except pyjwt.PyJWTError as exc:
+            return VerifyResult(ok=False, reason=str(exc) or "invalid")
+        return VerifyResult(ok=True, claims=claims)
+
+    # ── refresh + userinfo ───────────────────────────────────────────────────
+
+    def refresh(self, refresh_token: str) -> Dict[str, Any]:
+        """Rotate a refresh token.
+
+        Obelisk rotates the token (returns a fresh one) and revokes the entire
+        family on reuse of a superseded token. Returns the raw token response.
+        """
+        d = self.discover()
+        endpoint = d.get("token_endpoint") or f"{self._base}/auth/token"
+        form = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": self.client_id,
+        }
+        if self._client_secret:
+            form["client_secret"] = self._client_secret
+        return self._fetch(
+            endpoint,
+            method="POST",
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            body=urllib.parse.urlencode(form),
+        )
+
+    def get_userinfo(self, access_token: str) -> Dict[str, Any]:
+        """Fetch the userinfo claims for a Bearer access token."""
+        d = self.discover()
+        endpoint = d.get("userinfo_endpoint") or f"{self._base}/auth/userinfo"
+        return self._fetch(
+            endpoint,
+            method="GET",
+            headers={"authorization": f"Bearer {access_token}"},
+        )

obelisk_auth-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "obelisk-auth"
+version = "1.0.0"
+description = "Drop-in OIDC client for the Obelisk Gate identity platform — login, tokens, refresh, userinfo, and local ES256 token verification."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+# S321 — the license TEXT must ship, not just the word "Proprietary".
+#
+# This package declared a proprietary license and carried no LICENSE file, so a public
+# PyPI release would have reached users with terms asserted and nowhere stated. The npm
+# SDK has always shipped LICENSE + NOTICE + TRADEMARKS in its allowlist; the Python SDK
+# was declaring the same posture without the documents behind it. "Proprietary" with no
+# text is not a weaker license, it is an unstated one.
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "VaultSpark Studios" }]
+keywords = ["oidc", "openid-connect", "obelisk", "auth", "pkce", "es256", "jwt"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+# Standard-library-first: HTTP is stdlib urllib. The only third-party deps are
+# the JOSE crypto stack — we never hand-roll signature verification.
+dependencies = [
+    "PyJWT>=2.8.0",
+    "cryptography>=42.0.0",
+]
+
+[project.urls]
+Homepage = "https://obeliskgate.com"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["obelisk_auth"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

obelisk_auth-1.0.0/tests/test_obelisk_auth.py

@@ -0,0 +1,394 @@
+"""Unit tests for obelisk_auth — no live server required.
+
+Coverage:
+  * PKCE-S256 challenge correctness (known-answer + matches Gate's verifyPkceS256).
+  * Authorization-URL construction (endpoints, PKCE params, S256-only).
+  * Discovery + JWKS caching.
+  * Full login flow against a mocked /auth/token, with a locally-minted ES256
+    id_token verified through the real local-verification path.
+  * Local access-token verification: valid, wrong-issuer, expired, tampered.
+  * obelisk_block extraction.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import time
+from typing import Any, Dict, List, Optional
+
+import jwt as pyjwt
+import pytest
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from obelisk_auth import (
+    LoginStart,
+    ObeliskAuth,
+    ObeliskError,
+    obelisk_block,
+    pkce_challenge_s256,
+)
+
+ISSUER = "https://gate.test"
+CLIENT_ID = "rp-statvault"
+REDIRECT = "https://statvault.example/cb"
+
+
+# ── helpers: a minimal in-test Gate (ES256 signer + JWKS) ────────────────────
+
+
+def _b64u(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+class FakeGate:
+    """An ES256 signing key + its JWKS, mirroring how Obelisk signs tokens."""
+
+    def __init__(self) -> None:
+        self._priv = ec.generate_private_key(ec.SECP256R1())
+        # Build the public JWK the way the Gate publishes it.
+        pub_jwk = json.loads(pyjwt.algorithms.ECAlgorithm.to_jwk(self._priv.public_key()))
+        canonical = json.dumps(
+            {"crv": pub_jwk["crv"], "kty": pub_jwk["kty"], "x": pub_jwk["x"], "y": pub_jwk["y"]},
+            separators=(",", ":"),
+        )
+        self.kid = _b64u(hashlib.sha256(canonical.encode()).digest())
+        pub_jwk.update({"use": "sig", "alg": "ES256", "kid": self.kid})
+        self.jwks = {"keys": [pub_jwk]}
+
+    def sign(self, claims: Dict[str, Any]) -> str:
+        return pyjwt.encode(
+            claims, self._priv, algorithm="ES256", headers={"kid": self.kid}
+        )
+
+    def id_token(self, *, sub: str, nonce: Optional[str] = None, **extra: Any) -> str:
+        now = int(time.time())
+        claims: Dict[str, Any] = {
+            "iss": ISSUER,
+            "sub": sub,
+            "aud": CLIENT_ID,
+            "iat": now,
+            "exp": now + 3600,
+            "obelisk": {
+                "v": "obelisk-claims-v1",
+                "assurance": "passkey",
+                "anchor": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
+                "rating": {"rating": 91.4, "band": "fortress"},
+            },
+        }
+        if nonce is not None:
+            claims["nonce"] = nonce
+        claims.update(extra)
+        return self.sign(claims)
+
+    def access_token(self, *, sub: str, scope: str = "openid profile") -> str:
+        now = int(time.time())
+        return self.sign(
+            {"iss": ISSUER, "sub": sub, "aud": CLIENT_ID, "iat": now, "exp": now + 3600, "scope": scope}
+        )
+
+
+def make_fetch(gate: FakeGate, *, token_response: Dict[str, Any]):
+    """A fetch_impl that serves discovery, JWKS, token and userinfo locally."""
+    calls: List[str] = []
+
+    def fetch(url: str, *, method: str = "GET", headers=None, body=None):
+        calls.append(f"{method} {url}")
+        if url.endswith("/.well-known/openid-configuration"):
+            return {
+                "issuer": ISSUER,
+                "authorization_endpoint": f"{ISSUER}/auth/authorize",
+                "token_endpoint": f"{ISSUER}/auth/token",
+                "userinfo_endpoint": f"{ISSUER}/auth/userinfo",
+                "jwks_uri": f"{ISSUER}/.well-known/jwks.json",
+                "code_challenge_methods_supported": ["S256"],
+            }
+        if url.endswith("/.well-known/jwks.json"):
+            return gate.jwks
+        if url.endswith("/auth/token"):
+            return token_response
+        if url.endswith("/auth/userinfo"):
+            return {"sub": "founder", "name": "Founder"}
+        raise AssertionError(f"unexpected fetch: {url}")
+
+    fetch.calls = calls  # type: ignore[attr-defined]
+    return fetch
+
+
+def make_auth(gate: FakeGate, token_response: Dict[str, Any]) -> ObeliskAuth:
+    return ObeliskAuth(
+        issuer=ISSUER,
+        client_id=CLIENT_ID,
+        redirect_uri=REDIRECT,
+        fetch_impl=make_fetch(gate, token_response=token_response),
+    )
+
+
+# ── PKCE ──────────────────────────────────────────────────────────────────────
+
+
+def test_pkce_challenge_known_answer():
+    # RFC 7636 Appendix B canonical verifier → challenge.
+    verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+    assert pkce_challenge_s256(verifier) == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+
+
+def test_pkce_challenge_is_unpadded_base64url_sha256():
+    verifier = "a-test-verifier-string"
+    expected = (
+        base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest())
+        .rstrip(b"=")
+        .decode("ascii")
+    )
+    challenge = pkce_challenge_s256(verifier)
+    assert challenge == expected
+    assert "=" not in challenge  # JOSE: no padding
+
+
+def test_pkce_matches_gate_verify_pkce_s256():
+    # The Gate's verifyPkceS256 recomputes base64url(sha256(verifier)) and
+    # constant-time compares to the stored challenge. Emulate that check here.
+    verifier = "another_verifier_0123456789"
+    challenge = pkce_challenge_s256(verifier)
+    recomputed = pkce_challenge_s256(verifier)
+    assert challenge == recomputed  # the Gate would accept this verifier
+
+
+# ── authorization URL ──────────────────────────────────────────────────────────
+
+
+def test_begin_login_builds_authorize_url():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    login = auth.begin_login(scope="openid profile offline_access")
+
+    assert isinstance(login, LoginStart)
+    from urllib.parse import urlparse, parse_qs
+
+    parsed = urlparse(login.authorization_url)
+    assert parsed.scheme + "://" + parsed.netloc + parsed.path == f"{ISSUER}/auth/authorize"
+    q = parse_qs(parsed.query)
+    assert q["response_type"] == ["code"]
+    assert q["client_id"] == [CLIENT_ID]
+    assert q["redirect_uri"] == [REDIRECT]
+    assert q["scope"] == ["openid profile offline_access"]
+    assert q["code_challenge_method"] == ["S256"]  # S256 ONLY
+    assert q["state"] == [login.state]
+    assert q["nonce"] == [login.nonce]
+    # the challenge in the URL is exactly S256(verifier)
+    assert q["code_challenge"] == [pkce_challenge_s256(login.code_verifier)]
+
+
+def test_begin_login_values_are_unique_each_call():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    a = auth.begin_login()
+    b = auth.begin_login()
+    assert a.code_verifier != b.code_verifier
+    assert a.state != b.state
+    assert a.nonce != b.nonce
+
+
+def test_login_start_tuple_unpacking():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    url, verifier, state, nonce = auth.begin_login()
+    assert url.startswith(f"{ISSUER}/auth/authorize?")
+    assert verifier and state and nonce
+
+
+# ── discovery + jwks caching ───────────────────────────────────────────────────
+
+
+def test_discover_caches():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    d1 = auth.discover()
+    d2 = auth.discover()
+    assert d1["issuer"] == ISSUER
+    assert d1 is d2  # cached object
+    disc_calls = [c for c in auth._fetch.calls if "openid-configuration" in c]
+    assert len(disc_calls) == 1
+
+
+def test_jwks_caches_and_force_refetches():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    auth.get_jwks()
+    auth.get_jwks()
+    jwks_calls = [c for c in auth._fetch.calls if "jwks.json" in c]
+    assert len(jwks_calls) == 1
+    auth.get_jwks(force=True)
+    jwks_calls = [c for c in auth._fetch.calls if "jwks.json" in c]
+    assert len(jwks_calls) == 2
+
+
+# ── full login flow ─────────────────────────────────────────────────────────────
+
+
+def test_complete_login_verifies_id_token():
+    gate = FakeGate()
+    nonce = "nonce-xyz"
+    id_token = gate.id_token(sub="founder", nonce=nonce)
+    access = gate.access_token(sub="founder")
+    auth = make_auth(
+        gate,
+        token_response={
+            "id_token": id_token,
+            "access_token": access,
+            "refresh_token": "rt-1",
+            "token_type": "Bearer",
+            "expires_in": 3600,
+        },
+    )
+    result = auth.complete_login("the-code", "the-verifier", nonce=nonce)
+    assert result.claims["sub"] == "founder"
+    assert result.claims["aud"] == CLIENT_ID
+    assert result.tokens["access_token"] == access
+    # the obelisk assurance block survives verification
+    block = obelisk_block(result.claims)
+    assert block is not None
+    assert block["assurance"] == "passkey"
+    assert len(block["anchor"]) == 32
+
+
+def test_complete_login_rejects_nonce_mismatch():
+    gate = FakeGate()
+    id_token = gate.id_token(sub="founder", nonce="real-nonce")
+    auth = make_auth(gate, token_response={"id_token": id_token, "access_token": "x"})
+    with pytest.raises(ObeliskError, match="nonce mismatch"):
+        auth.complete_login("code", "verifier", nonce="WRONG")
+
+
+def test_complete_login_raises_on_token_error():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={"error": "invalid_grant"})
+    with pytest.raises(ObeliskError, match="token exchange failed"):
+        auth.complete_login("code", "verifier")
+
+
+# ── local access-token verification ─────────────────────────────────────────────
+
+
+def test_verify_access_token_valid():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    token = gate.access_token(sub="founder")
+    v = auth.verify_access_token(token)
+    assert v.ok is True
+    assert v.claims["sub"] == "founder"
+    assert v.reason is None
+
+
+def test_verify_access_token_rejects_wrong_issuer_key():
+    # A token from a DIFFERENT gate (different signing key) must not verify.
+    gate_a = FakeGate()
+    gate_b = FakeGate()
+    auth = make_auth(gate_a, token_response={})  # auth trusts gate A's JWKS
+    forged = gate_b.access_token(sub="founder")
+    v = auth.verify_access_token(forged)
+    assert v.ok is False
+
+
+def test_verify_access_token_expired():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    now = int(time.time())
+    token = gate.sign(
+        {"iss": ISSUER, "sub": "founder", "aud": CLIENT_ID, "iat": now - 7200, "exp": now - 3600}
+    )
+    v = auth.verify_access_token(token)
+    assert v.ok is False
+    assert v.reason == "expired"
+
+
+def test_verify_access_token_tampered_payload():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    token = gate.access_token(sub="founder")
+    header, payload, sig = token.split(".")
+    tampered_claims = base64.urlsafe_b64encode(
+        json.dumps({"iss": ISSUER, "sub": "attacker", "aud": CLIENT_ID, "exp": int(time.time()) + 3600}).encode()
+    ).rstrip(b"=").decode()
+    forged = f"{header}.{tampered_claims}.{sig}"
+    v = auth.verify_access_token(forged)
+    assert v.ok is False
+
+
+def test_verify_access_token_wrong_issuer_claim():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    now = int(time.time())
+    token = gate.sign(
+        {"iss": "https://evil.test", "sub": "founder", "aud": CLIENT_ID, "iat": now, "exp": now + 3600}
+    )
+    v = auth.verify_access_token(token)
+    assert v.ok is False
+    assert v.reason == "issuer-mismatch"
+
+
+# ── refresh + userinfo ──────────────────────────────────────────────────────────
+
+
+def test_refresh_posts_refresh_grant():
+    gate = FakeGate()
+    auth = make_auth(
+        gate,
+        token_response={"access_token": "at-2", "refresh_token": "rt-2", "expires_in": 3600},
+    )
+    out = auth.refresh("rt-1")
+    assert out["access_token"] == "at-2"
+    assert out["refresh_token"] == "rt-2"
+    assert any("POST" in c and "/auth/token" in c for c in auth._fetch.calls)
+
+
+def test_get_userinfo():
+    gate = FakeGate()
+    auth = make_auth(gate, token_response={})
+    info = auth.get_userinfo("at")
+    assert info["sub"] == "founder"
+
+
+# ── obelisk_block helper ────────────────────────────────────────────────────────
+
+
+def test_obelisk_block_present_and_absent():
+    assert obelisk_block({"obelisk": {"assurance": "passkey"}}) == {"assurance": "passkey"}
+    assert obelisk_block({"sub": "x"}) is None
+    assert obelisk_block({"obelisk": "not-a-dict"}) is None
+
+
+# ── constructor validation ──────────────────────────────────────────────────────
+
+
+def test_constructor_requires_issuer_and_client():
+    with pytest.raises(ValueError):
+        ObeliskAuth(issuer="", client_id="x", redirect_uri="y")
+    with pytest.raises(ValueError):
+        ObeliskAuth(issuer="https://x", client_id="", redirect_uri="y")
+
+
+def test_version_agrees_with_packaging_metadata():
+    """S321 - two owners of one fact.
+
+    The version lives in BOTH pyproject.toml and obelisk_auth.__version__. Bumping
+    0.1.0 -> 1.0.0 for the PyPI release touched the manifest first, which would have
+    shipped a package whose own __version__ disagreed with the version the registry
+    serves - the same two-spellings defect this project keeps finding elsewhere.
+    Nothing compared them, so this does.
+    """
+    import pathlib
+    import re
+
+    import obelisk_auth
+
+    pyproject = (pathlib.Path(__file__).resolve().parent.parent / "pyproject.toml").read_text(
+        encoding="utf-8"
+    )
+    match = re.search(r'(?m)^version = "([^"]+)"', pyproject)
+    assert match, "pyproject.toml must declare a version"
+    assert obelisk_auth.__version__ == match.group(1), (
+        "obelisk_auth.__version__ must equal the packaged version; a module that "
+        "misreports its own version is unfalsifiable from the outside"
+    )