@webda/auth 0.0.0-stage → 4.0.0-beta.11

package/lib/oauth/oauth.service.d.ts

@@ -0,0 +1,296 @@
+import { type AsyncEventUnknown, type AuthResult, type ProviderInfo, type ResolvedIdentity, SecretString, Service, ServiceParameters, type WebContext } from "@webda/core";
+import { type AuthProvider } from "../provider.js";
+/**
+ * Credentials as returned by an OAuth token endpoint (google-auth-library `Credentials` shape): `id_token`,
+ * `access_token`, `refresh_token`, `expiry_date`, `token_type`, `scope`... Values are not typed by the schema
+ * (providers send nulls); providers check what they use.
+ */
+export interface OAuthTokens {
+    /** Any provider field */
+    [key: string]: any;
+}
+/**
+ * Input of the `Auth.<Provider>.Token` operations: `token`, or the provider credentials `tokens`
+ * @WebdaSchema
+ */
+export interface OAuthTokenRequest {
+    /**
+     * Token issued by the provider to the client (an ID token for OpenID Connect providers)
+     */
+    token?: string;
+    /**
+     * Credentials obtained by the client from the provider (v3 body; its `id_token` is verified)
+     */
+    tokens?: OAuthTokens;
+}
+/** Parameters of an authorization request */
+export interface OAuthAuthorizationRequest {
+    /** Random state to send back on the callback */
+    state: string;
+    /** Callback url */
+    redirectUri: string;
+    /** Scopes to request */
+    scope: string[];
+    /** PKCE code challenge (base64url SHA-256 of the verifier) */
+    codeChallenge: string;
+    /** PKCE method */
+    codeChallengeMethod: "S256";
+    /** OpenID Connect nonce: the ID token of the callback must carry it */
+    nonce: string;
+}
+/** Parameters of a code exchange */
+export interface OAuthCallbackRequest {
+    /** Authorization code */
+    code: string;
+    /** redirect_uri of the authorization request */
+    redirectUri: string;
+    /** PKCE code verifier */
+    codeVerifier: string;
+    /** Nonce of the authorization request: providers returning an ID token must check it */
+    nonce: string;
+}
+/** Browser redirects of the OAuth callback */
+export interface OAuthRedirects {
+    /**
+     * Where a successful login lands when the login did not carry an allowed `redirect` parameter
+     * @default "/"
+     */
+    success: string;
+    /**
+     * Where a failed login or callback lands, with `?reason=<CODE>` (required)
+     */
+    failure?: string;
+}
+/** OAuthProvider parameters */
+export declare class OAuthProviderParameters extends ServiceParameters {
+    /**
+     * Route prefix of the login (`<url>`) and callback (`<url>/callback`) routes
+     * @default "/auth/<providerName>"
+     */
+    url?: string;
+    /**
+     * OAuth client id
+     */
+    client_id: string;
+    /**
+     * OAuth client secret
+     *
+     * Can be encrypted with `webda config encrypt`
+     */
+    client_secret?: string | SecretString;
+    /**
+     * Scopes requested from the provider (the default depends on the provider)
+     */
+    scope?: string[];
+    /**
+     * Callback url registered at the provider
+     * @default "<absolute url of the request>/callback"; set it explicitly behind a proxy
+     */
+    redirect_uri?: string;
+    /**
+     * Allowed post-login targets for the `redirect` query parameter of the login route: absolute http(s) urls, a
+     * target matches when it has the same origin and its path is the listed path or below it
+     * @default []
+     */
+    authorized_uris: string[];
+    /**
+     * Browser redirects of the callback
+     * @default { "success": "/" }
+     */
+    redirects: OAuthRedirects;
+    /** Only these email domains may use this provider (see ProviderEmailPolicy) */
+    allowedEmailDomains?: string[];
+    /** Whether the verification of the email is believed (see ProviderEmailPolicy) */
+    trustEmailVerification?: boolean | string[];
+    /**
+     * @param params - raw parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+/** Pending login, kept in an encrypted cookie between the login and the callback */
+interface PendingLogin {
+    /** Provider that started it */
+    provider: string;
+    /** Random state sent to the provider */
+    state: string;
+    /** PKCE code verifier */
+    verifier: string;
+    /** OpenID Connect nonce */
+    nonce: string;
+    /** Post-login target, already checked against authorized_uris */
+    redirect?: string;
+    /** redirect_uri sent to the provider: the code exchange must use the same */
+    redirectUri: string;
+    /** Expiry timestamp (ms) */
+    expires: number;
+}
+/**
+ * Loggable reason of an error: library messages may contain tokens or their payload, so only a short code or the
+ * error class name is kept
+ * @param err - any error
+ * @returns a reason without any part of the message
+ */
+export declare function safeErrorReason(err: any): string;
+/**
+ * Keep only the known credentials keys, as bounded strings or finite numbers
+ * @param tokens - client provided credentials
+ * @returns the sanitised credentials
+ */
+export declare function sanitizeTokens(tokens: OAuthTokens): OAuthTokens;
+/**
+ * Base of the OAuth 2.0 / OpenID Connect login providers
+ *
+ * Exposes, under `url` (default `/auth/<providerName>`):
+ * - `GET <url>{?redirect}`: starts a login with a random `state`, a PKCE (S256) verifier and an OpenID `nonce`, kept
+ *   in a dedicated encrypted cookie (10 min, HttpOnly, SameSite=Lax, path `url`), then redirects to the provider;
+ *   `redirect` must match `authorized_uris`
+ * - `GET <url>/callback`: consumes that cookie, checks the state, exchanges the code (`handleCallback`) and hands
+ *   the identity to `Authentication.complete()`; never throws, failures go to `redirects.failure?reason=<CODE>`
+ * - operation `Auth.<Provider>.Token` (`POST auth/<providerName>/token`, JSON body `{ token }` or `{ tokens }`) for
+ *   non-browser clients; it never links an identity to the session user
+ *
+ * Subclasses implement `providerName`, `getAuthorizationUrl`, `handleCallback` and `handleToken`; the provider of the
+ * returned identities is always forced to `providerName`.
+ */
+export declare abstract class OAuthProvider<T extends OAuthProviderParameters = OAuthProviderParameters, E extends AsyncEventUnknown = {}> extends Service<T, E> implements AuthProvider {
+    static Parameters: typeof OAuthProviderParameters;
+    /** Unique provider name, used in ident keys ("google") */
+    abstract readonly providerName: string;
+    /**
+     * Build the authorization url of the provider, sending the PKCE challenge and the nonce
+     * @param request - authorization request
+     * @returns the url to redirect the browser to
+     */
+    abstract getAuthorizationUrl(request: OAuthAuthorizationRequest): string | Promise<string>;
+    /**
+     * Exchange an authorization code (with the PKCE verifier) and verify the result, including the nonce of an ID
+     * token
+     * @param request - code exchange
+     * @returns the identity proven by the provider
+     * @throws an HttpError (for example TokenInvalid) whose code is used as the failure reason
+     */
+    abstract handleCallback(request: OAuthCallbackRequest): Promise<ResolvedIdentity>;
+    /**
+     * Verify a token presented by a non-browser client
+     * @param request - `token` and/or `tokens` (at least one is present)
+     * @returns the identity proven by the provider
+     * @throws TokenInvalid when the token cannot be verified
+     */
+    abstract handleToken(request: OAuthTokenRequest): Promise<ResolvedIdentity>;
+    /**
+     * Called after a successful `Authentication.complete()` (status ok or mfa_required)
+     * @param _identity - the identity
+     * @param _result - the result
+     * @param _source - browser callback or token operation
+     * @param _request - the token operation request (token operation only)
+     */
+    protected onAuthenticated(_identity: ResolvedIdentity, _result: AuthResult, _source: "callback" | "token", _request?: OAuthTokenRequest): Promise<void>;
+    /**
+     * @returns false when the provider works without client secret (public clients)
+     */
+    protected requiresClientSecret(): boolean;
+    /**
+     * @returns the name of the pending login cookie
+     */
+    protected getCookieName(): string;
+    /** @override */
+    resolve(): this;
+    /** @override */
+    init(): Promise<this>;
+    /**
+     * Register `Auth.<Provider>.Token`: its id and path depend on the provider name
+     * @override
+     */
+    initOperations(): void;
+    /**
+     * @returns public info
+     */
+    getPublicInfo(): ProviderInfo;
+    /**
+     * Log in with a token obtained by the client from the provider
+     *
+     * Requires a JSON request (a cross-site form or `text/plain` POST is refused). A request carrying a logged-in
+     * session never links the identity to that user: an identity owned by another user is refused
+     * (IDENT_LINKED_ELSEWHERE), a new or unowned one gets a fresh session.
+     * @param token - token (an ID token for OpenID Connect providers)
+     * @param tokens - credentials obtained from the provider (v3 body)
+     * @returns the auth result
+     */
+    token(token?: string, tokens?: OAuthTokens): Promise<AuthResult>;
+    /**
+     * Refuse a request that is not JSON: cross-site requests can only send form or `text/plain` bodies without a
+     * preflight
+     * @param ctx - operation context
+     * @throws UnsupportedMediaType when the HTTP request is not `application/json`
+     */
+    protected requireJson(ctx: any): void;
+    /**
+     * The token operation never links: with a logged-in session, an identity owned by another user is refused and a
+     * new or unowned one starts a fresh session
+     * @param ctx - operation context
+     * @param identity - verified identity
+     * @throws IdentLinkedElsewhere when the identity belongs to another user than the session one
+     */
+    protected leaveForeignSession(ctx: any, identity: ResolvedIdentity): Promise<void>;
+    /**
+     * @param identity - identity returned by the subclass
+     * @returns the identity
+     * @throws TokenInvalid when it has no subject
+     */
+    protected checkIdentity(identity: ResolvedIdentity): ResolvedIdentity;
+    /**
+     * @param identity - identity returned by the subclass
+     * @returns the identity, always attributed to this provider
+     */
+    protected ownIdentity(identity: ResolvedIdentity): ResolvedIdentity;
+    /**
+     * Check a post-login target against `authorized_uris`: same origin, and the listed path or below it; an encoded
+     * slash or backslash in the path is refused
+     * @param redirect - candidate
+     * @returns the normalised url, undefined when not allowed
+     */
+    protected allowedRedirect(redirect: unknown): string | undefined;
+    /**
+     * @param ctx - web context
+     * @returns the callback url sent to the provider
+     */
+    protected getRedirectUri(ctx: WebContext): string;
+    /**
+     * Set (or clear, without value) the pending login cookie, scoped to the callback path: the path of the effective
+     * redirect_uri, which includes any deployment prefix (API Gateway stage, path-stripping proxy) the routes do not see
+     * @param ctx - web context
+     * @param redirectUri - callback url
+     * @param value - encrypted pending login
+     */
+    protected sendPendingCookie(ctx: WebContext, redirectUri: string, value?: string): void;
+    /**
+     * Read and clear the pending login cookie
+     * @param ctx - web context
+     * @returns the pending login, undefined when absent, invalid, expired or of another provider
+     */
+    protected consumePending(ctx: WebContext): Promise<PendingLogin | undefined>;
+    /**
+     * Redirect without caching
+     * @param ctx - web context
+     * @param url - target
+     */
+    protected redirect(ctx: WebContext, url: string): void;
+    /**
+     * @param ctx - web context
+     * @param reason - failure code
+     */
+    protected fail(ctx: WebContext, reason: string): void;
+    /**
+     * Start a login: redirect the browser to the provider
+     * @param ctx - web context
+     */
+    login(ctx: WebContext): Promise<void>;
+    /**
+     * Provider callback: verify the state, exchange the code, complete the login and redirect; never throws
+     * @param ctx - web context
+     */
+    callback(ctx: WebContext): Promise<void>;
+}
+export {};
+//# sourceMappingURL=oauth.service.d.ts.map

package/lib/oauth/oauth.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.service.d.ts","sourceRoot":"","sources":["../../src/oauth/oauth.service.ts"],"names":[],"mappings":"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"}