useoutlet 0.1.0__py3-none-any.whl

useoutlet/__init__.py

@@ -0,0 +1,79 @@
+"""useoutlet: connect your users' AI accounts to your app.
+
+Status: direct mode is live today. Vault mode (connect / refresh / status /
+revoke) is open. Register your app at useoutlet.dev/register.
+
+    from useoutlet import Outlet
+
+    outlet = Outlet(app_id="app_yourapp", app_secret=os.environ["OUTLET_APP_SECRET"])
+    request = outlet.connect(providers=["openai"], requested_cap_usd=10)
+    # send the user to request.grant_url, then
+    session = outlet.wait(request.id)
+
+    # use the official provider SDK: Outlet is not in the data path
+    ai = OpenAI(api_key=session.keys["openai"])
+
+A connection that ends (capped, revoked or expired) is a ConnectionEndedError
+from status(), refresh() and wait(). The Connect your AI button, the CLI and
+the MCP docs server live in the npm package, @useoutlet/sdk.
+"""
+
+from ._version import __version__
+from .client import AsyncOutlet, Outlet
+from .direct import direct
+from .grants import refresh, revoke, status
+from .pkce import PkceChallenge, create_grant, exchange_code, pkce_challenge
+from .providers import (
+    KeyShape,
+    ProviderCheck,
+    ProviderEntry,
+    ProviderKind,
+    ProviderMode,
+    ProviderModes,
+    get_provider,
+    provider_ids,
+    providers,
+)
+from .types import (
+    CapReason,
+    ConnectionEndedError,
+    EndReason,
+    GrantInfo,
+    GrantRequest,
+    GrantStatus,
+    Mode,
+    OutletError,
+    OutletSession,
+)
+
+__all__ = [
+    "AsyncOutlet",
+    "CapReason",
+    "ConnectionEndedError",
+    "EndReason",
+    "GrantInfo",
+    "GrantRequest",
+    "GrantStatus",
+    "KeyShape",
+    "Mode",
+    "Outlet",
+    "OutletError",
+    "OutletSession",
+    "PkceChallenge",
+    "ProviderCheck",
+    "ProviderEntry",
+    "ProviderKind",
+    "ProviderMode",
+    "ProviderModes",
+    "__version__",
+    "create_grant",
+    "direct",
+    "exchange_code",
+    "get_provider",
+    "pkce_challenge",
+    "provider_ids",
+    "providers",
+    "refresh",
+    "revoke",
+    "status",
+]

useoutlet/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

useoutlet/client.py

@@ -0,0 +1,304 @@
+"""The Outlet client: the grant flow for a server, with the credential held
+once. A confidential client (app secret) starts a connection request, sends
+the user to its grant URL and waits for the approval. A public client (no
+secret) starts it with PKCE and finishes on the return address with
+exchange(). refresh(), status() and revoke() then use the secret or the
+grant's refresh token, whichever the client holds; a rotated token replaces
+the old one in the client."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from . import grants as _grants
+from . import http as _http
+from .direct import direct
+from .ended import ended
+from .http import DEFAULT_TIMEOUT, Auth, api
+from .pkce import create_grant, exchange_code
+from .types import GrantInfo, GrantRequest, OutletError, OutletSession
+
+# A connection request the user never finished is forgotten after this long.
+_PENDING_TTL = 3600.0
+
+_WAIT_NEEDS_SECRET = (
+    "wait() needs the app secret. A public client finishes the connection with "
+    "exchange(code, state) on the return address."
+)
+
+
+@dataclass
+class _Pending:
+    grant_request_id: str
+    verifier: str
+    started: float
+
+
+class Outlet:
+    """The Outlet client.
+
+    app_id: your app's registered Outlet id (app_..., public).
+    app_secret: your confidential app secret (apps_...), server-side only.
+      Leave it out for a public client (PKCE, SPEC section 7.1).
+    base_url: the vault to talk to. Defaults to https://api.useoutlet.dev/v0.
+    timeout: seconds one vault call may take.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.app_id = app_id
+        self.app_secret = app_secret or None
+        self._base_url = base_url
+        self.timeout = timeout
+        # grant id -> the refresh token the vault last issued (public clients)
+        self._tokens: dict[str, str] = {}
+        # state -> the PKCE values of a connection request not yet exchanged
+        self._pending: dict[str, _Pending] = {}
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url or _http.DEFAULT_BASE_URL
+
+    @property
+    def public(self) -> bool:
+        """True for a public client: no app secret, PKCE instead."""
+        return self.app_secret is None
+
+    # The grant flow
+
+    def connect(
+        self,
+        providers: Sequence[str],
+        requested_cap_usd: float | None = None,
+        redirect_uri: str | None = None,
+    ) -> GrantRequest:
+        """Start a connection request. Send the user to the returned grant_url.
+
+        providers: the provider the user connects. The vault takes one provider
+          per connection request; use a separate request for each provider.
+        requested_cap_usd: your proposed monthly Vault cap in USD. The user
+          sets the cap on the approval card.
+        redirect_uri: the return address (public clients: required, and it
+          must be registered for the app).
+
+        A confidential client then calls wait(); a public client calls
+        exchange() with the code and state from the return address.
+        """
+        if isinstance(providers, str):
+            providers = [providers]
+        if self.public:
+            started = create_grant(
+                self.app_id,
+                providers,
+                redirect_uri or "",
+                requested_cap_usd,
+                base_url=self.base_url,
+                timeout=self.timeout,
+            )
+            self._remember(started)
+            return started
+        r = api(
+            self.base_url,
+            "/grants",
+            method="POST",
+            body={
+                "app_id": self.app_id,
+                "providers": list(providers),
+                "requested_cap_usd": requested_cap_usd,
+                "redirect_uri": redirect_uri,
+            },
+            auth=Auth(app_secret=self.app_secret),
+            timeout=self.timeout,
+        )
+        # The vault answers this path in camelCase and the PKCE path in
+        # snake_case (SPEC section 7.1). Both spellings are read.
+        return GrantRequest(
+            id=str(r.get("grantRequestId") or r.get("grant_request_id") or ""),
+            grant_url=str(r.get("grantUrl") or r.get("grant_url") or ""),
+        )
+
+    def wait(
+        self,
+        grant_request_id: str,
+        *,
+        interval: float = 1.5,
+        timeout: float | None = None,
+    ) -> OutletSession:
+        """Confidential clients: wait for the user to approve. Polls the grant
+        request every `interval` seconds, as the npm package's connect() does,
+        and returns the session once the vault delivers the key. A request that
+        ends before approval (revoked, capped) raises ConnectionEndedError.
+        timeout: seconds to wait in all; None waits until the vault answers."""
+        if self.public:
+            raise OutletError(_WAIT_NEEDS_SECRET, "app_secret_required")
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            r = api(
+                self.base_url,
+                f"/grants/{grant_request_id}",
+                auth=Auth(app_secret=self.app_secret),
+                timeout=self.timeout,
+            )
+            state = r.get("status") if isinstance(r, dict) else None
+            if state == "complete":
+                return OutletSession.from_wire(r)
+            if state in ("capped", "revoked"):
+                raise ended(state, str(r.get("grantId") or grant_request_id), status=409)
+            if deadline is not None and time.monotonic() >= deadline:
+                raise OutletError(
+                    f"The connection request was not approved within {timeout:g} seconds.",
+                    "approval_timeout",
+                )
+            time.sleep(interval)
+
+    def exchange(self, code: str, state: str, request: GrantRequest | None = None) -> OutletSession:
+        """Public clients: finish the connection on the return address. Verifies
+        state against the request this client started, exchanges the code and
+        verifier over the back channel, and holds the session's refresh token
+        for refresh(), status() and revoke(). Pass `request` when your app
+        kept the GrantRequest itself (another process, say)."""
+        self._forget_stale()
+        if request is not None:
+            if not request.verifier:
+                raise OutletError("No PKCE transaction in progress.", "no_pkce_txn")
+            pending: _Pending | None = _Pending(request.id, request.verifier, time.monotonic())
+            expected = request.state
+        else:
+            if not self._pending:
+                raise OutletError("No PKCE transaction in progress.", "no_pkce_txn")
+            pending = self._pending.get(state) if state else None
+            expected = state if pending else None
+        if not code:
+            raise OutletError("No authorization code in the redirect URL.", "no_code")
+        if not state or pending is None or state != expected:
+            raise OutletError("State mismatch. Possible CSRF; aborting.", "state_mismatch")
+        session = exchange_code(
+            pending.grant_request_id,
+            code,
+            pending.verifier,
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+        self._pending.pop(state, None)
+        if session.refresh_token:
+            self._tokens[session.grant_id] = session.refresh_token
+        return session
+
+    # After connect
+
+    def refresh(self, grant_id: str, refresh_token: str | None = None) -> OutletSession:
+        """Re-fetch (and possibly rotate) the keys for a grant. A public client's
+        token rotates: the new one replaces the old in this client, and the
+        session carries it for your own store. Pass `refresh_token` to seed a
+        token this client has not seen (one you stored earlier). Raises
+        ConnectionEndedError when the connection is capped, revoked or expired."""
+        token = refresh_token or self._tokens.get(grant_id)
+        session = _grants.refresh(
+            grant_id,
+            app_secret=self.app_secret,
+            refresh_token=token,
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+        if session.refresh_token:
+            self._tokens[grant_id] = session.refresh_token
+        return session
+
+    def status(self, grant_id: str, refresh_token: str | None = None) -> GrantInfo:
+        """Current status and spend for a grant, never key material. Raises
+        ConnectionEndedError for a capped or revoked connection."""
+        return _grants.status(
+            grant_id,
+            app_secret=self.app_secret,
+            refresh_token=refresh_token or self._tokens.get(grant_id),
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+
+    def revoke(self, grant_id: str, refresh_token: str | None = None) -> None:
+        """Revoke a grant from the app's side. The client forgets its token."""
+        _grants.revoke(
+            grant_id,
+            app_secret=self.app_secret,
+            refresh_token=refresh_token or self._tokens.get(grant_id),
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+        self._tokens.pop(grant_id, None)
+
+    # Direct mode, for symmetry with the npm package's Outlet.direct()
+    direct = staticmethod(direct)
+
+    # Pending PKCE requests
+
+    def _remember(self, started: GrantRequest) -> None:
+        self._forget_stale()
+        if started.state and started.verifier:
+            self._pending[started.state] = _Pending(started.id, started.verifier, time.monotonic())
+
+    def _forget_stale(self) -> None:
+        cutoff = time.monotonic() - _PENDING_TTL
+        for state in [s for s, p in self._pending.items() if p.started < cutoff]:
+            del self._pending[state]
+
+
+class AsyncOutlet:
+    """The same client for asyncio apps. Each call runs the sync client in a
+    worker thread (asyncio.to_thread), so the event loop is never blocked. The
+    standard library has no async HTTP client, and this package adds none."""
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.sync = Outlet(app_id, app_secret, base_url=base_url, timeout=timeout)
+
+    @property
+    def public(self) -> bool:
+        return self.sync.public
+
+    async def connect(
+        self,
+        providers: Sequence[str],
+        requested_cap_usd: float | None = None,
+        redirect_uri: str | None = None,
+    ) -> GrantRequest:
+        return await asyncio.to_thread(
+            self.sync.connect, providers, requested_cap_usd, redirect_uri
+        )
+
+    async def wait(
+        self, grant_request_id: str, *, interval: float = 1.5, timeout: float | None = None
+    ) -> OutletSession:
+        return await asyncio.to_thread(
+            self.sync.wait, grant_request_id, interval=interval, timeout=timeout
+        )
+
+    async def exchange(
+        self, code: str, state: str, request: GrantRequest | None = None
+    ) -> OutletSession:
+        return await asyncio.to_thread(self.sync.exchange, code, state, request)
+
+    async def refresh(self, grant_id: str, refresh_token: str | None = None) -> OutletSession:
+        return await asyncio.to_thread(self.sync.refresh, grant_id, refresh_token)
+
+    async def status(self, grant_id: str, refresh_token: str | None = None) -> GrantInfo:
+        return await asyncio.to_thread(self.sync.status, grant_id, refresh_token)
+
+    async def revoke(self, grant_id: str, refresh_token: str | None = None) -> None:
+        await asyncio.to_thread(self.sync.revoke, grant_id, refresh_token)
+
+    direct = staticmethod(direct)

useoutlet/direct.py

@@ -0,0 +1,164 @@
+"""Direct (paste) mode. Vault mode is open: register your app at useoutlet.dev/register.
+
+The user pastes their own provider API key; direct() checks it locally and
+returns the same OutletSession shape that the vault flow returns, so upgrading
+later is a one-line change. No network: the key never leaves the process and
+is never sent to Outlet.
+
+    session = direct({"openai": user_pasted_key})
+    ai = OpenAI(api_key=session.keys["openai"])
+
+Works with any provider: pass its key under that provider's id. For an
+OpenAI-compatible one (for example {"groq": key}), point the OpenAI SDK at the
+provider's base URL. The provider registry (providers.py) names the nineteen
+with a named Direct screen. Its key shapes and format hints are for the person
+pasting a key. direct() refuses no key over them.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from collections.abc import Mapping
+from typing import NoReturn
+
+from .providers import get_provider
+from .types import OutletError, OutletSession
+
+# First-class providers with well-defined key shapes get strict checks.
+# Order within openai matters: the generic "sk-" entry must come last.
+_ACCEPTED: dict[str, list[str]] = {
+    "openai": ["sk-proj-", "sk-svcacct-", "sk-"],
+    "anthropic": ["sk-ant-"],
+    "google": ["AIza"],
+}
+
+_BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _display_name(provider: str) -> str:
+    """The registry's display name for nicer error messages. A provider outside
+    the registry falls back to the raw id the developer passed."""
+    entry = get_provider(provider)
+    return entry.display_name if entry else provider
+
+
+def _fail(message: str, code: str) -> NoReturn:
+    raise OutletError(message, code)
+
+
+def _clean(raw: str) -> str:
+    """Pasted keys arrive with the user's clipboard noise: surrounding whitespace,
+    sometimes quotes from a config file. Clean before judging, so honest pastes
+    do not fail format checks."""
+    return raw.strip().strip("\"'")
+
+
+def _validate_key(provider: str, raw: str) -> str:
+    key = _clean(raw)
+    name = _display_name(provider)
+
+    if not key:
+        _fail(f"Empty {name} key.", "invalid_key_format")
+
+    # Admin keys are the user's root org credential. Direct mode exists
+    # precisely so apps never hold one. Refuse loudly for ANY provider, not
+    # just the named.
+    if key.startswith("sk-ant-admin"):
+        _fail(
+            "This is an Anthropic ADMIN key. It controls the whole organization. "
+            "Never paste an admin key into an app. Use a regular API key "
+            "(starts with sk-ant-api).",
+            "admin_key_rejected",
+        )
+    if key.startswith("sk-admin-"):
+        _fail(
+            "This is an OpenAI ADMIN key. It controls the whole organization. "
+            "Never paste an admin key into an app. Use a project API key "
+            "(starts with sk-proj-).",
+            "admin_key_rejected",
+        )
+
+    # Provider-exclusive prefixes pasted into the wrong field are a mistake no
+    # matter which provider you named: "sk-ant-" is Anthropic-only, "AIza" is
+    # Google-only. The generic "sk-" is NOT exclusive (DeepSeek, Qwen, Moonshot
+    # and others use it), so it is only judged among the first-class three.
+    if provider != "anthropic" and key.startswith("sk-ant-"):
+        _fail(
+            f"That looks like an ANTHROPIC key, but it was pasted into the {name} field.",
+            "wrong_provider_key",
+        )
+    if provider != "google" and key.startswith("AIza"):
+        _fail(
+            f"That looks like a GOOGLE key, but it was pasted into the {name} field.",
+            "wrong_provider_key",
+        )
+
+    # First-class providers (OpenAI, Anthropic, Google): strict format and mix-up.
+    if provider in _ACCEPTED:
+        if provider != "openai" and key.startswith("sk-") and not key.startswith("sk-ant-"):
+            _fail(
+                f"That looks like an OPENAI key, but it was pasted into the {name} field.",
+                "wrong_provider_key",
+            )
+        prefixes = _ACCEPTED[provider]
+        if not any(key.startswith(p) for p in prefixes):
+            _fail(
+                f"This doesn't look like a {name} API key (expected it to start with "
+                f"{' or '.join(prefixes)}).",
+                "invalid_key_format",
+            )
+        return key
+
+    # Any other provider's key is an opaque value: a token, a JWT, a generic
+    # "sk-", or two parts around a colon or a dot (fal, Higgsfield, Z.ai). We
+    # accept any non-empty, non-admin key whole rather than reject a valid key
+    # we cannot model. The registry's key shapes are never enforced here.
+    return key
+
+
+def _base36(n: int) -> str:
+    digits = ""
+    while n:
+        n, r = divmod(n, 36)
+        digits = _BASE36[r] + digits
+    return digits or "0"
+
+
+def _local_id() -> str:
+    """Not a secret: a local handle apps can log and store safely."""
+    tail = "".join(secrets.choice(_BASE36) for _ in range(6))
+    return f"direct_{_base36(int(time.time() * 1000))}{tail}"
+
+
+def direct(keys: Mapping[str, str]) -> OutletSession:
+    """Check pasted provider keys and return a session, entirely locally.
+
+    keys: the provider API keys the user pasted, by provider id. Checked
+    locally (format and provider mix-ups for OpenAI, Anthropic and Google; a
+    safety check that refuses admin keys for everyone), never transmitted
+    anywhere by the SDK.
+    """
+    if not keys:
+        _fail("direct() needs at least one provider key.", "no_keys")
+    checked = {provider: _validate_key(provider, raw) for provider, raw in keys.items()}
+    return OutletSession(
+        grant_id=_local_id(),
+        keys=checked,
+        # No Outlet meter in direct mode; real caps arrive with vault mode.
+        cap_usd=float("inf"),
+        # Direct keys live until the user revokes them in their provider console.
+        expires_at="9999-12-31T23:59:59Z",
+        mode="direct",
+    )
+
+
+def assert_vault_grant(grant_id: str) -> None:
+    """Vault operations (refresh, status, revoke) have nothing to act on for a
+    direct-mode session. Fail with directions rather than a confusing 404."""
+    if grant_id.startswith("direct_"):
+        _fail(
+            "This is a direct-mode session: there is no vault grant behind it. "
+            "To revoke, delete the key on the provider's website.",
+            "direct_mode_session",
+        )

useoutlet/ended.py

@@ -0,0 +1,59 @@
+"""Connection ends: the vault's refusals and status answers turned into
+ConnectionEndedError. Every end passes through ended(). The npm package also
+tells the page's Connect your AI button; a server has no button to tell."""
+
+from __future__ import annotations
+
+from .providers import get_provider
+from .types import ConnectionEndedError, EndReason, GrantInfo, OutletError
+
+
+def ended(
+    reason: EndReason,
+    grant_id: str,
+    *,
+    info: GrantInfo | None = None,
+    provider: str | None = None,
+    status: int | None = None,
+) -> ConnectionEndedError:
+    """The typed error for a connection that ended."""
+    message = None
+    if reason == "refused" and provider:
+        entry = get_provider(provider)
+        name = entry.display_name if entry else provider
+        message = f"{name} refused this Direct API key. Ask the user for a new one."
+    return ConnectionEndedError(
+        reason, grant_id, info=info, provider=provider, status=status, message=message
+    )
+
+
+def ended_from_vault(e: OutletError, grant_id: str) -> ConnectionEndedError | None:
+    """The connection end behind a vault refusal, or None when the code is not
+    one: 409 grant_capped, 409 grant_revoked, and 401 unauthorized for a refresh
+    token the vault no longer knows (rotated away or gone)."""
+    if e.code == "grant_capped":
+        return ended("capped", grant_id, status=e.status)
+    if e.code == "grant_revoked":
+        return ended("revoked", grant_id, status=e.status)
+    if e.code == "unauthorized":
+        return ended("expired", grant_id, status=e.status)
+    return None
+
+
+def ended_from_info(info: GrantInfo) -> ConnectionEndedError | None:
+    """The connection end a status answer reports, or None while it is open."""
+    if info.status not in ("capped", "revoked"):
+        return None
+    provider = info.providers[0] if info.providers else None
+    return ended(info.status, info.grant_id, info=info, provider=provider, status=409)
+
+
+def is_connection_ended(e: object) -> bool:
+    """True for a ConnectionEndedError, from this package or another copy of it."""
+    if isinstance(e, ConnectionEndedError):
+        return True
+    return (
+        getattr(e, "code", None) == "connection_ended"
+        and isinstance(getattr(e, "reason", None), str)
+        and isinstance(getattr(e, "grant_id", None), str)
+    )