imapkit 5.2.0 → 5.3.0

package/dist/esm/oauth/provider.d.ts

@@ -0,0 +1,455 @@
+/**
+ * The OAuth 2.0 / OpenID Connect provider of the `oauth` option (README "OAuth 2.0 and OpenID Connect"): the
+ * authorization code flow with PKCE for mail clients, with tokens that IMAP (XOAUTH2, OAUTHBEARER) and SMTP (AUTH
+ * XOAUTH2) accept. No passwords: a consent policy decides every sign-in, from the first rung that has one: a queued
+ * decision, the user (picked by `login_hint`), the client, the server default. `prompt` shows the consent page,
+ * where the tester picks an account and clicks Allow or Deny. Strict like the IMAP side: a request that breaks a
+ * MUST of the RFCs is refused and the error description names the rule.
+ *
+ * This file holds the protocol logic and the state, src/oauth/http.ts the HTTP server and src/oauth/pages.ts the
+ * pages. Times come from `server.now()`, so tests with a fixed clock can let tokens expire.
+ */
+import type { ConsentPolicy, Outcome } from './policy.js';
+import type { SigningKey } from './jwt.js';
+import type { IMAPServer } from '../types.js';
+/** A client of the `oauth.clients` option */
+export interface OAuthClientOptions {
+    /** the name the consent page shows, the client ID if not set */
+    name?: string | undefined;
+    /** a confidential client authenticates with this secret, a client without one is public and must use PKCE */
+    secret?: string | undefined;
+    /** registered redirect URIs. A loopback http URI matches any port (RFC 8252 section 7.3), a trailing `*` any rest */
+    redirectUris?: string[] | undefined;
+    /** the consent policy of the client, the server default if not set */
+    consent?: ConsentPolicy | undefined;
+}
+/** The `oauth` option */
+export interface OAuthOptions {
+    port?: number | undefined;
+    /** address to listen on, 127.0.0.1 by default */
+    host?: string | undefined;
+    /** HTTPS with the `credentials` or the bundled localhost certificate */
+    secure?: boolean | undefined;
+    /** the public base URL, when clients reach the provider through another address (a tunnel, a proxy) */
+    issuer?: string | undefined;
+    /** the default consent policy, `prompt` if not set */
+    consent?: ConsentPolicy | undefined;
+    /** registered clients by client ID, `imapkit`, `imapkit-approve` and `imapkit-deny` if not set */
+    clients?: Record<string, OAuthClientOptions> | undefined;
+    /** more scopes, name to the description the consent page shows */
+    scopes?: Record<string, string> | undefined;
+    /** the scope that IMAP and SMTP logins need, `mail` by default */
+    mailScope?: string | undefined;
+    /** `refuse` (default) answers a request for an unknown scope with invalid_scope, `drop` grants the others */
+    unknownScopes?: 'refuse' | 'drop' | undefined;
+    /** `offline_access` (default) issues refresh tokens only for that scope, `always` for every code exchange */
+    refreshTokens?: 'offline_access' | 'always' | undefined;
+    /** a new refresh token on every refresh, reuse of an old one revokes the grant */
+    rotateRefreshTokens?: boolean | undefined;
+    /** access token lifetime in seconds, 3600 by default */
+    accessTokenTtl?: number | undefined;
+    /** authorization code lifetime in seconds, 60 by default, at most 600 (RFC 6749 section 4.1.2) */
+    codeTtl?: number | undefined;
+    /** accepts the `plain` PKCE method, which RFC 7636 section 4.2 only allows for clients that can not do S256 */
+    allowPlainPkce?: boolean | undefined;
+    /** RSA private key in PEM for the ID tokens, a new key on every start if not set */
+    signingKey?: string | Buffer | undefined;
+}
+/** A registered client */
+export interface OAuthClient {
+    id: string;
+    name: string;
+    secret: string | null;
+    redirectUris: string[];
+    consent: ConsentPolicy | null;
+}
+/** One line of the request checklist on the consent page */
+export interface Check {
+    level: 'ok' | 'note' | 'warn';
+    text: string;
+}
+/** A checked authorization request */
+export interface AuthRequest {
+    client: OAuthClient;
+    redirectUri: string;
+    /** false when the request left redirect_uri out and the only registered URI was used */
+    redirectUriSent: boolean;
+    state: string | undefined;
+    scope: string[];
+    codeChallenge: string | undefined;
+    codeChallengeMethod: string | undefined;
+    nonce: string | undefined;
+    loginHint: string | undefined;
+    /** the user that login_hint names, null when it names nobody */
+    hintUser: string | null | undefined;
+    prompt: string[];
+    checks: Check[];
+    /** other parameters the request sent, they are ignored */
+    ignored: string[];
+}
+/** A request waiting on the consent page */
+export interface PendingRequest extends AuthRequest {
+    id: string;
+    expiresAt: number;
+    source: string;
+}
+/** A page to show instead of a redirect */
+export interface PageData {
+    status: number;
+    title: string;
+    message: string;
+    details?: string[] | undefined;
+    tone: 'error' | 'info';
+}
+/** What the authorization endpoint answers */
+export type AuthorizeResult = {
+    type: 'redirect';
+    location: string;
+} | {
+    type: 'page';
+    page: PageData;
+} | {
+    type: 'consent';
+    request: PendingRequest;
+};
+/** A JSON answer of the token, revocation or userinfo endpoint */
+export interface JsonResult {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string> | undefined;
+    /** answer with an HTML error page instead of JSON, the html token fault */
+    htmlError?: boolean | undefined;
+}
+/** A queued decision, see queueOAuthDecision() */
+export interface QueuedDecision {
+    id: number;
+    decision: Outcome;
+    client: string | undefined;
+    user: string | undefined;
+    remaining: number;
+}
+/** A queued fault of the token endpoint, see queueOAuthTokenFault() */
+export interface TokenFault {
+    id: number;
+    grant: 'authorization_code' | 'refresh_token' | undefined;
+    error: string | undefined;
+    description: string | undefined;
+    status: number | undefined;
+    html: boolean;
+    delay: number;
+    /** claims to change in the ID token, null removes one */
+    claims: Record<string, unknown> | undefined;
+    remaining: number;
+}
+interface CodeRecord {
+    clientId: string;
+    user: string;
+    redirectUri: string;
+    redirectUriSent: boolean;
+    scope: string[];
+    challenge: string | undefined;
+    method: string | undefined;
+    nonce: string | undefined;
+    expiresAt: number;
+    authTime: number;
+    grantId: string;
+    used: boolean;
+}
+interface TokenRecord {
+    token: string;
+    type: 'access' | 'refresh';
+    clientId: string;
+    user: string;
+    scope: string[];
+    grantId: string;
+    /** null for refresh tokens, which do not expire */
+    expiresAt: number | null;
+    revoked: boolean;
+    /** a refresh token that rotation replaced */
+    rotated: boolean;
+    /** when the token was revoked or replaced, prune() forgets it a day later */
+    endedAt: number | null;
+}
+/** What `server.checkAccessToken()` gets from the provider */
+export type TokenCheck = {
+    user: string;
+} | {
+    error: 'invalid_token' | 'insufficient_scope';
+    reason: string;
+};
+/**
+ * Checks a registered redirect URI against the one a request sent
+ *
+ * @param {String} registered Registered URI, a trailing `*` matches any rest
+ * @param {String} given URI of the request
+ * @return {Boolean} true if they match
+ */
+declare function redirectMatches(registered: string, given: string): boolean;
+declare class OAuthProvider {
+    server: IMAPServer;
+    options: OAuthOptions;
+    /** the base URL of the endpoints, set when the HTTP server listens (see listening()) */
+    issuer: string;
+    clients: Map<string, OAuthClient>;
+    consent: ConsentPolicy;
+    decisions: QueuedDecision[];
+    tokenFaults: TokenFault[];
+    pending: Map<string, PendingRequest>;
+    codes: Map<string, CodeRecord>;
+    tokens: Map<string, TokenRecord>;
+    scopes: Record<string, string>;
+    mailScope: string;
+    accessTokenTtl: number;
+    codeTtl: number;
+    queueCounter: number;
+    key: SigningKey | null;
+    constructor(server: IMAPServer, options: OAuthOptions);
+    /**
+     * Checks an issuer URL of the options: http or https, no query or fragment (RFC 8414 section 2)
+     *
+     * @param {String} issuer URL
+     * @return {String} the URL without a trailing slash
+     */
+    checkIssuer(issuer: unknown): string;
+    /** Restores the clients and the default policy of the options and forgets every token, request and queue */
+    reset(): void;
+    /** Milliseconds since the epoch, from the `now` option */
+    nowMs(): number;
+    /**
+     * Sets the issuer from the address the HTTP server listens on, unless the `issuer` option gave one
+     *
+     * @param {String} host Address
+     * @param {Number} port Port
+     */
+    listening(host: string, port: number): void;
+    /** The URL of the discovery document */
+    discoveryUrl(): string;
+    /** The users as the consent and index pages show them, the default user first */
+    pageUsers(): {
+        name: string;
+        displayName: string | undefined;
+        consent: ConsentPolicy | undefined;
+    }[];
+    /**
+     * Marks a token as revoked or replaced by rotation
+     *
+     * @param {Object} record Token
+     * @param {String} how "revoked" or "rotated"
+     */
+    endToken(record: TokenRecord, how: 'revoked' | 'rotated'): void;
+    /**
+     * Emits an `oauth` event, `{ type, ... }`, and logs it with the debug option
+     *
+     * @param {String} type Event type
+     * @param {Object} data Event data
+     */
+    emit(type: string, data: Record<string, unknown>): void;
+    /**
+     * Answers an authorization request (RFC 6749 section 4.1.1, OpenID Connect Core 1.0 section 3.1.2.1)
+     *
+     * @param {URLSearchParams} input Query (GET) or form (POST) parameters
+     * @return {Object} a redirect, a page, or a request for the consent page
+     */
+    authorize(input: URLSearchParams): AuthorizeResult;
+    /**
+     * Checks the parameters of an authorization request after the client and the redirect URI
+     *
+     * @return {Object} the request, or the error redirect
+     */
+    checkRequest(client: OAuthClient, redirectUri: string, p: Record<string, string>, duplicates: string[], fail: (error: string, description: string) => AuthorizeResult): AuthRequest | AuthorizeResult;
+    /**
+     * Finds the redirect URI of a request
+     *
+     * @return {String|Object} the URI, or the error page
+     */
+    resolveRedirect(client: OAuthClient, given: string | undefined): string | AuthorizeResult;
+    /**
+     * Checks the scope parameter
+     *
+     * @return {Array|String} the granted scopes, or the error description
+     */
+    checkScope(value: string | undefined, checks: Check[]): string[] | string;
+    /**
+     * Checks the PKCE parameters (RFC 7636 section 4.3, RFC 9700 section 2.1.1)
+     *
+     * @return {String|null} the error description, null if they are fine
+     */
+    checkPkce(client: OAuthClient, p: Record<string, string>, checks: Check[]): string | null;
+    /**
+     * Finds the decision of a request: a queued decision, the user of login_hint, the client, the server default
+     *
+     * @param {Object} request Checked request
+     * @return {Object} `{ outcome, source }`
+     */
+    decide(request: AuthRequest): {
+        outcome: Outcome;
+        source: string;
+    };
+    /**
+     * Carries out a decision
+     *
+     * @param {Object} request Checked request
+     * @param {String|Object} outcome Decision
+     * @param {String} source Where the decision came from
+     * @param {String} [user] The user picked on the consent page
+     * @return {Object} redirect, page or consent request
+     */
+    finish(request: AuthRequest, outcome: Outcome, source: string, user?: string): AuthorizeResult;
+    /**
+     * The user an approved request signs in: the user of login_hint, or the first user
+     *
+     * @return {String|null} user name, null if there is none
+     */
+    pickUser(request: AuthRequest): string | null;
+    /** Sorted user names, the default user first */
+    userNames(): string[];
+    /**
+     * Answers the form of the consent page
+     *
+     * @param {URLSearchParams} form Form fields: request, action (allow, deny, outcome), user, remember, outcome, description
+     * @return {Object} redirect or page
+     */
+    answerConsent(form: URLSearchParams): AuthorizeResult;
+    /**
+     * Drops expired consent requests and codes, and tokens a day after they expired or ended. Until then a login with
+     * one is refused as expired or revoked, after that as unknown
+     */
+    prune(): void;
+    issueCode(request: AuthRequest, user: string): string;
+    /**
+     * Builds a redirect to the client, with `iss` (RFC 9207 section 2)
+     *
+     * @param {String} redirectUri Redirect URI, its query is kept (RFC 6749 section 3.1.2)
+     * @param {Object} params Response parameters
+     * @param {Boolean} [wrongIss] true sends another issuer, the wrong-iss fault
+     * @return {String} URL
+     */
+    redirectUrl(redirectUri: string, params: Record<string, string>, wrongIss?: boolean): string;
+    redirectError(target: {
+        redirectUri: string;
+        state: string | undefined;
+    }, error: string, description: string): AuthorizeResult;
+    errorPage(title: string, message: string, details?: string[]): AuthorizeResult;
+    clientList(): string[];
+    /**
+     * Answers a token request (RFC 6749 sections 4.1.3 and 6)
+     *
+     * @param {URLSearchParams} form Form parameters
+     * @param {String} [authorization] Authorization header
+     * @return {Promise<Object>} JSON answer
+     */
+    token(form: URLSearchParams, authorization: string | undefined): Promise<JsonResult>;
+    /**
+     * Authenticates the client of a token or revocation request (RFC 6749 section 2.3)
+     *
+     * @return {Object} `{ client }` or the error answer
+     */
+    authenticateClient(p: Record<string, string>, authorization: string | undefined): {
+        client: OAuthClient;
+    } | JsonResult;
+    exchangeCode(client: OAuthClient, p: Record<string, string>, fault: TokenFault | null): JsonResult;
+    refresh(client: OAuthClient, p: Record<string, string>): JsonResult;
+    /**
+     * Issues an access token, and a refresh token and an ID token when the grant calls for them
+     *
+     * @return {Object} token response (RFC 6749 section 5.1)
+     */
+    issueTokens(client: OAuthClient, user: string, scope: string[], grantId: string, extra: {
+        nonce?: string | undefined;
+        authTime?: number | undefined;
+        fault?: TokenFault | null | undefined;
+        refresh?: TokenRecord | undefined;
+    }): Record<string, unknown>;
+    newRefreshToken(client: OAuthClient, user: string, scope: string[], grantId: string): string;
+    /**
+     * Signs an ID token (OpenID Connect Core 1.0 section 2). The user name is the email address
+     *
+     * @return {String} JWT
+     */
+    idToken(client: OAuthClient, user: string, scope: string[], nonce: string | undefined, authTime: number | undefined, changes: Record<string, unknown> | undefined): string;
+    /** The claims of the email and profile scopes */
+    userClaims(user: string, scope: string[]): Record<string, unknown>;
+    /** The public key of the ID tokens (RFC 7517) */
+    jwks(): {
+        keys: Record<string, string>[];
+    };
+    takeTokenFault(grant: string | undefined): TokenFault | null;
+    /**
+     * Revokes every token of a grant
+     *
+     * @return {Number} how many tokens were revoked
+     */
+    revokeGrant(grantId: string): number;
+    /**
+     * Answers a revocation request (RFC 7009 section 2)
+     *
+     * @return {Object} JSON answer
+     */
+    revoke(form: URLSearchParams, authorization: string | undefined): JsonResult;
+    /**
+     * Answers a UserInfo request (OpenID Connect Core 1.0 section 5.3)
+     *
+     * @param {String} [authorization] Authorization header with the access token
+     * @return {Object} JSON answer
+     */
+    userinfo(authorization: string | undefined): JsonResult;
+    /**
+     * Why an access token can not be used
+     *
+     * @return {String|null} "expired", "revoked" ..., null for a usable token
+     */
+    tokenProblem(record: TokenRecord | undefined): string | null;
+    /**
+     * Checks an access token for an IMAP or SMTP login
+     *
+     * @param {String} token Access token
+     * @param {String} [username] The user the client logs in as, any if not set
+     * @param {String} via "imap" or "smtp", for the event
+     * @return {Object|null} `{ user }` or `{ error, reason }`, null for a token the provider did not issue
+     */
+    verifyAccessToken(token: string, username: string | undefined, via: string): TokenCheck | null;
+    /** The discovery document (OpenID Connect Discovery 1.0 section 3, RFC 8414 section 2) */
+    metadata(): Record<string, unknown>;
+    describeClient(client: OAuthClient): Record<string, unknown>;
+    describeToken(record: TokenRecord): Record<string, unknown>;
+    /**
+     * Selects tokens for the control API
+     *
+     * @param {Object} [filter] `{ user, client, token, type }`
+     * @return {Array} token records
+     */
+    findTokens(filter?: {
+        user?: unknown;
+        client?: unknown;
+        token?: unknown;
+        type?: unknown;
+    }): TokenRecord[];
+    queueDecision(options?: {
+        decision?: unknown;
+        client?: unknown;
+        user?: unknown;
+        count?: unknown;
+    }): {
+        id: number;
+    };
+    queueTokenFault(options?: Record<string, unknown>): {
+        id: number;
+    };
+    listClients(): Record<string, unknown>[];
+    setClient(id: string, options: OAuthClientOptions): Record<string, unknown>;
+    deleteClient(id: string): void;
+    setConsent(consent: unknown): {
+        consent: ConsentPolicy;
+    };
+    listTokens(filter?: Record<string, unknown>): Record<string, unknown>[];
+    expireTokens(filter?: Record<string, unknown>): {
+        expired: number;
+    };
+    revokeTokens(filter?: Record<string, unknown>): {
+        revoked: number;
+    };
+    info(): Record<string, unknown>;
+    /** Adds the control operations and their REST routes, see README "Control API" */
+    registerControl(): void;
+}
+export { OAuthProvider, redirectMatches };