"""Stub OIDC provider — interface contract placeholder.

This is a deliberately unimplemented :class:`AuthProvider` whose only
job is to fail loudly when ``auth.provider: oidc-stub`` is configured
without the real OIDC integration being in place. It exists so that
the configuration switch and the dependency-injection wiring can be
exercised end-to-end before the IdP integration work is scheduled.

Future OIDC integration checklist
---------------------------------
When the real OIDC integration lands, replace this file with
:file:`auth/providers/oidc.py` implementing:

- [ ] :meth:`authenticate` — accept (username, password)? OR redirect-flow?
      OIDC is fundamentally a redirect flow, NOT a password POST. The
      right answer is probably a separate ``/auth/oauth/{provider}/redirect``
      and ``/auth/oauth/{provider}/callback`` route pair that bypasses
      the password-based login. The :class:`AuthProvider` interface is
      only for backends that accept username + password; an OIDC
      adapter may need to extend the protocol or expose a separate
      callback-handler hook.
- [ ] :meth:`get_user_by_id` — query local cache (auto-provisioned
      OIDC users live in the local ``users`` table after first login).
- [ ] :meth:`sync_user_attributes` — pull latest profile from the IdP
      on each successful login (department / title / email).
- [ ] :meth:`revoke_user` — call the IdP's account-disable API (e.g.
      Keycloak's ``PUT /admin/realms/{realm}/users/{id}/disable``).
- [ ] State cache for OAuth ``state`` parameter (Redis, TTL 5 min).
- [ ] First-login user auto-provisioning policy: just-in-time
      creation / reject / invite-only.

Until then, configuring ``auth.provider: oidc-stub`` and starting
the server lets a smoke test confirm:

1. The DI factory resolves the right class.
2. The route layer calls :meth:`authenticate` and surfaces 501.
3. ``auth_sessions.auth_provider='oidc-stub'`` would be written
   for any session that *did* get created (none, in this stub).
"""

from __future__ import annotations

from .exceptions import ProviderNotImplemented
from .user import User


class StubOIDCProvider:
    """Unimplemented OIDC adapter. All methods raise :class:`ProviderNotImplemented`.

    The class satisfies the :class:`AuthProvider` Protocol structurally
    (it has ``name`` and the four methods), but every method body is
    a deliberate failure. This is on purpose: configuring
    ``auth.provider: oidc-stub`` and then successfully logging in would
    be a security bug.
    """

    name = "oidc-stub"

    async def authenticate(self, *, username: str, password: str) -> User:
        raise ProviderNotImplemented(
            "OIDC authentication is not implemented yet. "
            "Use auth.provider: local in agentkit.yaml, or implement "
            "auth/providers/oidc.py (see the checklist in this module's "
            "docstring)."
        )

    async def get_user_by_id(self, user_id: str) -> User | None:
        raise ProviderNotImplemented(
            "StubOIDCProvider.get_user_by_id is not implemented. "
            "See auth/providers/oidc_stub.py for the future OIDC checklist."
        )

    async def sync_user_attributes(self, user_id: str) -> None:
        raise ProviderNotImplemented(
            "StubOIDCProvider.sync_user_attributes is not implemented. "
            "See auth/providers/oidc_stub.py for the future OIDC checklist."
        )

    async def revoke_user(self, user_id: str) -> None:
        raise ProviderNotImplemented(
            "StubOIDCProvider.revoke_user is not implemented. "
            "See auth/providers/oidc_stub.py for the future OIDC checklist."
        )
