@ghuri/socialauth 0.0.0-stage → 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+import { Context } from 'hono';
+import { VerifyFunction, OAuth2Strategy, Profile, OAuthTokens } from '@ghuri/oauth';
+import { a as SocialApp, S as SocialAccount, b as SocialToken } from './models-Cepu1xG8.js';
+export { e as emptyDict } from './models-Cepu1xG8.js';
+import * as _ghuri_core from '@ghuri/core';
+import { AppConfig, Signal, ViewFunction } from '@ghuri/core';
+import '@ghuri/orm';
+
+/** Credentials of one provider app, as in settings (`PROVIDERS.github.APP`) or a `SocialApp` row. */
+interface AppSettings {
+    clientId: string;
+    secret?: string;
+    key?: string;
+    /** For `openid_connect`: the id used in URLs (`/accounts/okta/login/`). */
+    providerId?: string;
+    name?: string;
+    /** Provider-specific settings (`serverUrl` for OpenID Connect, `tenant` for Microsoft…). */
+    settings?: Record<string, unknown>;
+}
+interface ProviderSettings {
+    APP?: AppSettings;
+    /** Several apps of one provider (`openid_connect`). */
+    APPS?: AppSettings[];
+    SCOPE?: string[];
+    AUTH_PARAMS?: Record<string, string>;
+    /** Override whether this provider's emails count as verified. */
+    VERIFIED_EMAIL?: boolean;
+    [key: string]: unknown;
+}
+interface SocialAccountSettings {
+    PROVIDERS?: Record<string, ProviderSettings>;
+    ADAPTER?: new () => SocialAccountAdapter;
+    AUTO_SIGNUP?: boolean;
+    EMAIL_AUTHENTICATION?: boolean;
+    EMAIL_REQUIRED?: boolean;
+    LOGIN_ON_GET?: boolean;
+    STORE_TOKENS?: boolean;
+    LOGIN_RESPONSE?: 'session' | 'jwt';
+    FRONTEND_URL?: string;
+    /** Where browser flows go on errors (default `LOGIN_URL`), with `?error=`. */
+    LOGIN_ERROR_URL?: string;
+}
+interface ResolvedSocialSettings {
+    providers: Record<string, ProviderSettings>;
+    adapter?: new () => SocialAccountAdapter;
+    autoSignup: boolean;
+    emailAuthentication: boolean;
+    emailRequired: boolean;
+    loginOnGet: boolean;
+    storeTokens: boolean;
+    loginResponse: 'session' | 'jwt';
+    frontendUrl?: string;
+    loginErrorUrl: string;
+}
+declare function socialSettings(): ResolvedSocialSettings;
+
+interface StrategyContext {
+    /** The id used in URLs and stored on `SocialAccount.provider` (`github`, or an OIDC app's `providerId`). */
+    key: string;
+    app: AppSettings;
+    settings: ProviderSettings;
+    callbackURL: string;
+    verify: VerifyFunction;
+}
+declare abstract class Provider {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    /** Several apps per provider, each with its own `providerId` (OpenID Connect). */
+    readonly multipleApps: boolean;
+    /** Default scopes when `SCOPE` is not set. */
+    readonly defaultScope: string[];
+    abstract createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    scope(settings: ProviderSettings): string[];
+    /** May this provider's email be trusted to belong to the user? */
+    emailVerified(profile: Profile, settings: ProviderSettings): boolean;
+    /**
+     * Native / mobile login: verify a token the app obtained with the provider's own SDK and return the profile.
+     * The token must have been issued to one of our client ids. Default: ID tokens of OpenID Connect providers.
+     */
+    verifyNativeToken(ctx: StrategyContext, tokens: {
+        accessToken?: string;
+        idToken?: string;
+    }): Promise<Profile>;
+    profileFromClaims(key: string, claims: Record<string, any>): Profile;
+}
+declare class GitHubProvider extends Provider {
+    readonly id = "github";
+    readonly name = "GitHub";
+    readonly defaultScope: string[];
+    private api;
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    private profile;
+    /** Checks with GitHub that the token belongs to our OAuth app (`POST /applications/{client_id}/token`). */
+    verifyNativeToken(ctx: StrategyContext, tokens: {
+        accessToken?: string;
+    }): Promise<Profile>;
+}
+declare class GoogleProvider extends Provider {
+    readonly id = "google";
+    readonly name = "Google";
+    readonly defaultScope: string[];
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+}
+declare class FacebookProvider extends Provider {
+    readonly id = "facebook";
+    readonly name = "Facebook";
+    readonly defaultScope: string[];
+    private graph;
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    private profile;
+    /** Checks the token with `debug_token` (issued to our app id) before trusting it. */
+    verifyNativeToken(ctx: StrategyContext, tokens: {
+        accessToken?: string;
+    }): Promise<Profile>;
+}
+declare class MicrosoftProvider extends Provider {
+    readonly id = "microsoft";
+    readonly name = "Microsoft";
+    readonly defaultScope: string[];
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    profileFromClaims(key: string, claims: Record<string, any>): Profile;
+    emailVerified(profile: Profile, settings: ProviderSettings): boolean;
+}
+declare class DiscordProvider extends Provider {
+    readonly id = "discord";
+    readonly name = "Discord";
+    readonly defaultScope: string[];
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    verifyNativeToken(): Promise<Profile>;
+}
+declare class GitLabProvider extends Provider {
+    readonly id = "gitlab";
+    readonly name = "GitLab";
+    readonly defaultScope: string[];
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+    profileFromClaims(key: string, claims: Record<string, any>): Profile;
+}
+declare class OpenIDConnectProvider extends Provider {
+    readonly id = "openid_connect";
+    readonly name = "OpenID Connect";
+    readonly multipleApps = true;
+    readonly defaultScope: string[];
+    createStrategy(ctx: StrategyContext): OAuth2Strategy;
+}
+/** Add (or replace) a provider: `registerProvider(new MyProvider())`. */
+declare function registerProvider(provider: Provider): void;
+declare function getProvider(id: string): Provider | undefined;
+declare function allProviders(): Provider[];
+
+interface ResolvedProvider {
+    /** The id in URLs and on `SocialAccount.provider`. */
+    key: string;
+    provider: Provider;
+    app: AppSettings;
+    settings: ProviderSettings;
+    /** The `SocialApp` row, when the credentials came from the database. */
+    row?: SocialApp;
+}
+/** The provider for `key` (`github`, or the `providerId` of a multi-app provider), or null if not configured. */
+declare function resolveProvider(key: string): Promise<ResolvedProvider | null>;
+/** Every configured provider (for login buttons). */
+declare function configuredProviders(): Promise<ResolvedProvider[]>;
+
+type Process = 'login' | 'connect';
+/** `browser`: redirects (the OAuth callback); `api`: JSON (native tokens, SPA calls). */
+type Mode = 'browser' | 'api';
+interface SocialLogin extends ResolvedProvider {
+    profile: Profile;
+    tokens?: OAuthTokens;
+    /** Whether the provider vouches for `profile.email`. */
+    emailVerified: boolean;
+    process: Process;
+    next?: string;
+}
+declare class SocialAuthError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare function buildLogin(resolved: ResolvedProvider, profile: Profile, opts: {
+    tokens?: OAuthTokens;
+    process?: Process;
+    next?: string;
+}): SocialLogin;
+/** A one-time code an SPA exchanges for a JWT pair at `token/` (tokens never travel in URLs). */
+declare function makeLoginCode(user: any): Promise<string>;
+/** The user of a login code, once (replays are refused while the cache remembers the code). */
+declare function redeemLoginCode(code: string): Promise<any | null>;
+/** Log the user in and answer for the mode and `LOGIN_RESPONSE`. */
+declare function finishLogin(c: Context, user: any, login: SocialLogin, mode: Mode): Promise<Response>;
+/** Process a successful provider login (django-allauth's `complete_social_login`). */
+declare function completeSocialLogin(c: Context, login: SocialLogin, mode: Mode): Promise<Response>;
+
+/** Throw from `preSocialLogin()` to answer with your own response. */
+declare class ImmediateResponse extends Error {
+    readonly response: Response;
+    constructor(response: Response);
+}
+interface SignupData {
+    username?: string;
+    email?: string;
+}
+declare class SocialAccountAdapter {
+    /** May new users sign up through social login? */
+    isOpenForSignup(_c: Context, _login: SocialLogin): boolean | Promise<boolean>;
+    /** Called after the provider answered, before anything is looked up or created. */
+    preSocialLogin(_c: Context, _login: SocialLogin): Promise<void>;
+    /** May the user be created without showing the signup form? */
+    isAutoSignupAllowed(_c: Context, login: SocialLogin): boolean | Promise<boolean>;
+    /** A new, unsaved user instance. */
+    newUser(_c: Context, _login: SocialLogin): any;
+    /** Copy profile data (and signup form data) onto the new user. */
+    populateUser(_c: Context, login: SocialLogin, user: any, data: SignupData): any;
+    /** Save the new user (with an unusable password). */
+    saveUser(_c: Context, _login: SocialLogin, user: any): Promise<any>;
+    /** Username candidates, best first. */
+    usernameCandidates(login: SocialLogin): string[];
+    /** A username that is free, from the profile. */
+    generateUsername(_c: Context, login: SocialLogin): Promise<string>;
+    /** Where to go after connecting an account. */
+    getConnectRedirectUrl(_c: Context, _account: SocialAccount): string;
+    /** Customize error responses; return undefined for the default. */
+    authenticationError(_c: Context, _error: {
+        provider: string;
+        message: string;
+        code?: string;
+    }): Response | undefined | Promise<Response | undefined>;
+}
+declare function getAdapter(): SocialAccountAdapter;
+
+/** The `socialaccount` app (django-allauth's): `SocialApp`, `SocialAccount`, `SocialToken`. */
+declare class SocialAuthConfig extends AppConfig {
+    name: string;
+    label: string;
+    verboseName: string;
+    path: string | undefined;
+    migrations: Record<string, unknown>;
+    models: {
+        SocialApp: typeof SocialApp;
+        SocialAccount: typeof SocialAccount;
+        SocialToken: typeof SocialToken;
+    };
+    ready(): void;
+}
+
+/** Before a social login is processed (after the provider answered). */
+declare const preSocialLogin: Signal<{
+    c: Context;
+    login: SocialLogin;
+}>;
+/** A provider account was linked to a user (signup or connect). */
+declare const socialAccountAdded: Signal<{
+    c: Context;
+    login: SocialLogin;
+    account: SocialAccount;
+}>;
+/** An existing link logged in again (profile and tokens refreshed). */
+declare const socialAccountUpdated: Signal<{
+    c: Context;
+    login: SocialLogin;
+    account: SocialAccount;
+}>;
+/** A link was removed from the connections page. */
+declare const socialAccountRemoved: Signal<{
+    c: Context;
+    account: SocialAccount;
+}>;
+
+declare function storeTokens(login: SocialLogin, account: SocialAccount): Promise<void>;
+/**
+ * A usable access token for the account (refreshed with the stored refresh token when it expired), or null
+ * when tokens are not stored or cannot be refreshed.
+ */
+declare function getAccessToken(account: SocialAccount): Promise<string | null>;
+
+/** `GET providers/`: configured providers with their login URLs (for SPA buttons). */
+declare const providersView: ViewFunction;
+/** `<provider>/login/`: POST starts the flow; GET confirms first (unless LOGIN_ON_GET). */
+declare const loginView: ViewFunction;
+/** `<provider>/login/callback/`: the provider sends the browser back here. */
+declare const callbackView: ViewFunction;
+/**
+ * `POST <provider>/token/` `{ id_token }` or `{ access_token }`: log in with a token a native app got from the
+ * provider's SDK. The token is checked against our client id(s) before it is trusted.
+ */
+declare const nativeTokenView: ViewFunction;
+/** `POST token/` `{ code }`: exchange the one-time code from an SPA redirect for a JWT pair. */
+declare const tokenExchangeView: ViewFunction;
+/** `signup/`: finish a social signup that needs a username or email. */
+declare const signupView: ViewFunction;
+/** `connections/`: list the user's social accounts (GET) and disconnect one (POST `{ account }`). */
+declare const connectionsView: ViewFunction;
+/**
+ * `path('accounts/', include(socialUrls))` → `providers/`, `token/`, `signup/`, `connections/`,
+ * `<provider>/login/`, `<provider>/login/callback/`, `<provider>/token/`.
+ */
+declare const socialUrls: _ghuri_core.UrlPatterns;
+
+export { type AppSettings, DiscordProvider, FacebookProvider, GitHubProvider, GitLabProvider, GoogleProvider, ImmediateResponse, MicrosoftProvider, type Mode, OpenIDConnectProvider, type Process, Provider, type ProviderSettings, type ResolvedProvider, type ResolvedSocialSettings, type SignupData, SocialAccount, SocialAccountAdapter, type SocialAccountSettings, SocialApp, SocialAuthConfig, SocialAuthError, type SocialLogin, SocialToken, type StrategyContext, allProviders, buildLogin, callbackView, completeSocialLogin, configuredProviders, connectionsView, finishLogin, getAccessToken, getAdapter, getProvider, loginView, makeLoginCode, nativeTokenView, preSocialLogin, providersView, redeemLoginCode, registerProvider, resolveProvider, signupView, socialAccountAdded, socialAccountRemoved, socialAccountUpdated, socialSettings, socialUrls, storeTokens, tokenExchangeView };