auth-fixes (#3)

## Summary

Resolve `{ENV_VAR}` placeholders in the OpenAPI spec before serving it. Replace the monolithic `x-introspect-url` extension with composable `x-server-url` + individual `x-*-path` fields so auth endpoints are configurable per-environment without hardcoding.

## Changes

- **`openapi_first/app.py`** — add `_resolve_spec_env_vars()` that replaces `{ENV_VAR}` patterns (e.g. `{AUTH_SERVER}`) with the corresponding OS environment variable before returning the spec JSON. Called in `__init__` after spec load.
- **`openapi_first/security.py`** — build the introspection URL dynamically from `x-server-url` + `x-introspect-path` extensions on the `bearerAuth` security scheme, instead of reading a single `x-introspect-url`.

## Migration

Existing specs using `x-introspect-url: "https://auth.example.com/introspect"` must switch to the new extension format:

```yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-server-url: "{AUTH_SERVER}"
      x-login-path: "/login"
      x-register-path: "/register"
      x-logout-path: "/logout"
      x-me-path: "/me"
      x-introspect-path: "/introspect"

Reviewed-on: #3
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

openapi_first/app.py

@@ -32,10 +32,34 @@ Notes:
             - Alter FastAPI dependency injection semantics.
 """
 
+import os
+import re
+
 from fastapi import FastAPI
 
-from .loader import load_openapi
 from .binder import bind_routes
+from .loader import load_openapi
+from .security import make_security_dependencies, parse_security_schemes
+
+_env_pattern = re.compile(r"\{(\w+)\}")
+
+
+def _resolve_env(value: str) -> str:
+    """Replace {ENV_VAR} placeholders with values from os.environ."""
+    def _replace(m: re.Match) -> str:
+        return os.environ.get(m.group(1), m.group(0))
+    return _env_pattern.sub(_replace, value)
+
+
+def _resolve_spec_env_vars(obj):
+    """Recursively resolve {ENV_VAR} in all string values of the spec."""
+    if isinstance(obj, str):
+        return _resolve_env(obj)
+    if isinstance(obj, dict):
+        return {k: _resolve_spec_env_vars(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_resolve_spec_env_vars(v) for v in obj]
+    return obj
 
 
 class OpenAPIFirstApp(FastAPI):
@@ -48,15 +72,19 @@ class OpenAPIFirstApp(FastAPI):
             - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route
               registration with OpenAPI-driven binding.
             - All routes are derived from the provided OpenAPI specification,
-              and each `operationId` is mapped to a Python function in the
+              and each ``operationId`` is mapped to a Python function in the
               supplied routes module.
+            - Auth dependencies are auto-injected from the spec's
+              ``securitySchemes`` and per-operation ``security`` fields.
 
         **Guarantees:**
 
             - No route can exist without an OpenAPI declaration.
             - No OpenAPI operation can exist without a handler.
-            - Swagger UI and `/openapi.json` always reflect the provided spec.
+            - Swagger UI and ``/openapi.json`` always reflect the provided spec.
             - Handler functions remain framework-agnostic and testable.
+            - Auth enforcement is driven entirely by the spec — no manual
+              middleware or decorators required.
 
     Example:
         ```python
@@ -87,28 +115,33 @@ class OpenAPIFirstApp(FastAPI):
                 specification is treated as the authoritative API contract.
             routes_module (module):
                 Python module containing handler functions whose names correspond
-                exactly to OpenAPI `operationId` values.
+                exactly to OpenAPI ``operationId`` values.
             **fastapi_kwargs (Any):
                 Additional keyword arguments passed directly to
-                `fastapi.FastAPI` (e.g., title, version, middleware, lifespan
+                ``fastapi.FastAPI`` (e.g., title, version, middleware, lifespan
                 handlers).
 
         Raises:
             OpenAPIFirstError:
                 If the OpenAPI specification is invalid, or if any declared
-                `operationId` does not have a corresponding handler function.
+                ``operationId`` does not have a corresponding handler function.
         """
         # Initialize FastAPI normally
         super().__init__(**fastapi_kwargs)
 
         # Load and validate OpenAPI specification
-        self._openapi_spec = load_openapi(openapi_path)
+        self._openapi_spec = _resolve_spec_env_vars(load_openapi(openapi_path))
 
-        # Bind routes strictly from OpenAPI spec
+        # Parse security schemes and build per-route dependencies
+        security_schemes = parse_security_schemes(self._openapi_spec)
+        security_deps = make_security_dependencies(self._openapi_spec, security_schemes)
+
+        # Bind routes strictly from OpenAPI spec (with security deps)
         bind_routes(
             app=self,
             spec=self._openapi_spec,
             routes_module=routes_module,
+            security_deps=security_deps,
         )
 
         # Override FastAPI's OpenAPI generation