TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/exegia/corpora-py/llms.txt
Use this file to discover all available pages before exploring further.
exegia.auth module provides application-level authentication on top of Supabase Auth. It handles sign-in and sign-up flows and always checks whether a matching public.users record exists before returning a result — meaning a successful sign-in requires both a valid Supabase auth identity and a provisioned application profile.
Architecture
Context Fabric splits authentication into two layers that work together:exegia.supabase — low-level layer
client.pycreates a single synchronous Supabase client using the service-role key and theSUPABASE_API_URLconstant (constructed fromPROJECT_REF). Because the service-role key bypasses Row Level Security, all database operations in this layer run with elevated permissions regardless of the calling user’s session.authentication.pyprovides typed wrappers aroundsupabase.auth.*methods, translating raw credentials into structuredAuthResponse,AuthOtpResponse, andOAuthResponseobjects fromsupabase_auth.
exegia.auth — high-level layer
- After any authentication call, this layer checks for a matching
public.usersrecord keyed byauth.users.id. - On success, it returns a
SignInResultorSignUpResultdataclass carrying aCurrentUserthat joins the auth identity with the application profile. - On failure (authenticated but no profile), it signals
needs_signupso the caller can route the user to registration.
Supported Flows
| Flow | Module | When to use |
|---|---|---|
| Email OTP (magic link) | exegia.auth.signin | Passwordless login via email |
| OIDC ID token (Apple/Google) | exegia.auth.signin | Social login with ID token |
| Anonymous session | exegia.auth.signup | Guest access before registration |
| Profile registration | exegia.auth.signup | Create public.users record |
Result Types
All sign-in functions return aSignInResult. The sign_up() function returns a SignUpResult. Both are frozen dataclasses.
SignInResult
True when the user is fully authenticated and has a public.users record.The combined auth identity and application profile. Set only when
ok is True.The Supabase session carrying access and refresh tokens. Present on success and also on the
needs_signup path, so registration can be completed without re-authenticating.A user-facing message, populated on non-
ok paths.True when the user authenticated successfully but has no public.users record yet. Defaults to False.SignUpResult
True if a new public.users record was created for the user.The combined auth identity and profile. Set on success and on the
already_registered path.The Supabase session. Populated when the anonymous flow started a new session.
A user-facing message, populated on non-
ok paths.True when the user already has a public.users record, so no new record was created. Defaults to False.CurrentUser Dataclass
CurrentUser is the unified view of a signed-in user. It is a frozen dataclass with two fields that wrap the auth.users identity (a supabase_auth.User) and the public.users profile row, plus a set of convenience properties.
Dataclass fields
| Field | Type | Description |
|---|---|---|
auth_user | User | The Supabase Auth user object (auth.users row) |
profile | dict[str, Any] | None | The public.users record, or None when no profile exists yet |
| Property | Type | Description |
|---|---|---|
id | str | Auth user UUID — also the public.users primary key |
email | str | None | User email from the auth identity |
is_anonymous | bool | Whether the user is an unlinked anonymous session |
is_permanent | bool | Whether the account is fully registered (not anonymous) |
has_profile | bool | Whether a public.users record was found |
providers | list[str] | List of linked OAuth provider identifiers, e.g. ["google"] |
has_provider(provider: str) -> bool to check whether a specific provider is already linked to the user.
Configuration Required
The Supabase client is created at import time using two constants resolved from environment variables. Both must be set before importing anyexegia.auth or exegia.supabase module:
PROJECT_REF— your Supabase project reference, used to constructSUPABASE_API_URLashttps://supabase_kong_{PROJECT_REF}.orb.localSUPABASE_SECRET_KEY— service-role key that bypasses RLS
Sign In
Email OTP and Apple/Google OIDC flows that return a
SignInResult.Sign Up
Profile registration, anonymous sessions, and identity linking.