Add standards-based Customer Identity OIDC client

Author: ShivSankalp

README.md

@@ -51,9 +51,9 @@ catches both surfaces without importing the one you do not use.
 
 ## Hosted Auth
 
-Hosted Auth redirects the user to a branded NamoID sign-in page and returns a
-one-time code. The Client ID resolves the application, its environment, and its
-Hosted Auth domain, so there is no issuer or application UUID to configure.
+Hosted Auth uses standard OpenID Connect Authorization Code flow with S256 PKCE.
+The Client ID resolves the application and issuer; discovery supplies the
+authorization, token, UserInfo, revocation, JWKS, and logout endpoints.
 
 ```python
 from namoid import NamoIDClient
@@ -63,32 +63,32 @@ namoid = NamoIDClient(
     client_secret=os.environ["NAMOID_CLIENT_SECRET"],   # server-side only
 )
 
-# 1. Start a state-bound transaction and keep the verifier in the user's session.
-transaction = namoid.create_transaction()
+# 1. Start a state-, nonce-, and PKCE-bound transaction. Keep it server-side.
+transaction = namoid.create_oidc_transaction("https://app.example/auth/callback")
 session["namoid_state"] = transaction.state
+session["namoid_nonce"] = transaction.nonce
 session["namoid_verifier"] = transaction.code_verifier
 
-# 2. Send the browser to the application's own hosted sign-in page.
-url = namoid.hosted_auth_url(
-    return_to="https://app.example/auth/callback",
-    state=transaction.state,
-    completion_mode="confidential",
-    code_challenge=transaction.code_challenge,
-)
+# 2. Send the browser to the discovered authorization endpoint.
+url = namoid.authorization_url(transaction)
 
-# 3. On the callback, compare state, then exchange the code on the server.
+# 3. On the callback, compare state, then exchange using the same redirect URI.
 tokens = namoid.exchange_code(
     code=request.args["code"],
     code_verifier=session.pop("namoid_verifier"),
+    redirect_uri="https://app.example/auth/callback",
 )
 
-# 4. Confirm the token and create your own application session.
-result = namoid.validate_access_token(tokens.access_token)
-if not result.valid:
-    raise Unauthorized()
+# 4. Verify the ID token signature and callback-bound nonce, then fetch UserInfo.
+claims = namoid.validate_id_token(tokens.raw["id_token"],
+                                  nonce=session.pop("namoid_nonce"))
+user = namoid.user_info(tokens.access_token)
+assert claims["sub"] == user["sub"]
 
-# 5. On sign-out, revoke the NamoID session too.
-namoid.revoke_session(access_token=tokens.access_token, refresh_token=tokens.refresh_token)
+# 5. On sign-out, revoke the refresh token and redirect through provider logout.
+namoid.revoke_token(tokens.refresh_token, token_type_hint="refresh_token")
+url = namoid.logout_url(id_token_hint=tokens.raw["id_token"],
+                        post_logout_redirect_uri="https://app.example/signed-out")
 ```
 
 `AsyncNamoIDClient` has exactly the same methods with `await`, for FastAPI,
@@ -98,25 +98,36 @@ Starlette, or any async framework:
 from namoid import AsyncNamoIDClient
 
 async with AsyncNamoIDClient(client_id=..., client_secret=...) as namoid:
-    tokens = await namoid.exchange_code(code=code, code_verifier=verifier)
+    tokens = await namoid.exchange_code(
+        code=code, code_verifier=verifier,
+        redirect_uri="https://app.example/auth/callback",
+    )
 ```
 
 Both accept an `http_client` if you want to supply your own configured
 `httpx.Client` / `httpx.AsyncClient`, and cache the auth config after the first
 fetch.
 
-For a browser-only public client, redirect with `completion_mode="public"` and
-exchange with `confidential=False` — PKCE protects the flow and no secret is
-involved. Never put a Client Secret anywhere a browser can reach.
+For a public client, omit `client_secret`; PKCE protects the code exchange. For
+a confidential web application, the SDK sends the secret using HTTP Basic
+authentication at the discovered token endpoint. Never put a Client Secret
+anywhere a browser can reach.
 
 | Method | Endpoint |
 |---|---|
 | `get_auth_config()` | `GET /v1/auth/config` |
-| `hosted_auth_url(...)` | builds the URL, no request |
-| `exchange_code(...)` | `POST /v1/auth/hosted/exchange` |
-| `refresh(...)` | `POST /v1/auth/refresh` |
+| `get_oidc_discovery()` | issuer `/.well-known/openid-configuration` |
+| `authorization_url(...)` | discovered authorization endpoint |
+| `exchange_code(...)` | discovered token endpoint |
+| `refresh(...)` | discovered token endpoint |
+| `user_info(...)` | discovered UserInfo endpoint |
+| `validate_id_token(...)` | discovered JWKS endpoint; local verification |
+| `revoke_token(...)` | discovered revocation endpoint |
+| `logout_url(...)` | discovered end-session endpoint |
 | `validate_access_token(...)` | `POST /v1/auth/tokens/validate` |
-| `revoke_session(...)` | `POST /v1/auth/logout` |
+
+The older `hosted_auth_url(...)` and `revoke_session(...)` helpers remain for
+applications using NamoID's legacy Hosted Auth contract.
 
 Every failure raises `NamoIDError`, carrying `status`, `code` (the API's own
 error code when present), and the parsed `detail`.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "namoid"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python SDK for NamoID, enterprise identity for India (OAuth 2.1 / OIDC)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -44,18 +44,17 @@ classifiers = [
 
 dependencies = [
   "httpx>=0.28",
+  "joserfc>=1.0",
 ]
 
 [project.optional-dependencies]
 # Protect an MCP server. Framework-agnostic core: discovery, audience-bound
 # token verification, and RFC 9728 metadata.
 mcp = [
-  "joserfc>=1.0",
 ]
 # The same core wired into FastMCP. `fastmcp` itself requires a newer Python
 # than this package's floor, so pip enforces that when the extra is installed.
 fastmcp = [
-  "joserfc>=1.0",
   "fastmcp>=3.4.5,<4",
 ]
 

src/namoid/__init__.py

@@ -23,7 +23,7 @@
 from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __homepage__ = "https://namoid.in"
 
 # Public name -> the module that defines it. Resolved on first attribute access
@@ -37,6 +37,12 @@
     "HostedAuthTransaction": "namoid.hosted_auth",
     "TokenResponse": "namoid.hosted_auth",
     "TokenValidation": "namoid.hosted_auth",
+    "OIDCDiscovery": "namoid.oidc",
+    "OIDCTransaction": "namoid.oidc",
+    "build_authorization_url": "namoid.oidc",
+    "build_logout_url": "namoid.oidc",
+    "create_oidc_transaction": "namoid.oidc",
+    "validate_id_token": "namoid.oidc",
     "build_configured_hosted_auth_url": "namoid.hosted_auth",
     "build_hosted_auth_url": "namoid.hosted_auth",
     "create_hosted_auth_transaction": "namoid.hosted_auth",
@@ -48,12 +54,18 @@
     "HostedAuthTransaction",
     "NamoIDClient",
     "NamoIDError",
+    "OIDCDiscovery",
+    "OIDCTransaction",
     "TokenResponse",
     "TokenValidation",
     "__homepage__",
     "__version__",
     "build_configured_hosted_auth_url",
     "build_hosted_auth_url",
+    "build_authorization_url",
+    "build_logout_url",
+    "create_oidc_transaction",
+    "validate_id_token",
     "create_hosted_auth_transaction",
 ]
 
@@ -84,6 +96,12 @@ def __dir__() -> list[str]:
     from namoid.hosted_auth import (
         build_configured_hosted_auth_url as build_configured_hosted_auth_url,
     )
+    from namoid.oidc import OIDCDiscovery as OIDCDiscovery
+    from namoid.oidc import OIDCTransaction as OIDCTransaction
+    from namoid.oidc import build_authorization_url as build_authorization_url
+    from namoid.oidc import build_logout_url as build_logout_url
+    from namoid.oidc import create_oidc_transaction as create_oidc_transaction
+    from namoid.oidc import validate_id_token as validate_id_token
     from namoid.hosted_auth import build_hosted_auth_url as build_hosted_auth_url
     from namoid.hosted_auth import (
         create_hosted_auth_transaction as create_hosted_auth_transaction,