@qlover/oauth-wrapper 0.2.0

package/dist/core.d.ts

@@ -0,0 +1,460 @@
+import { z } from 'zod';
+import { ValueOf } from '@qlover/fe-corekit';
+
+/**
+ * Accepts HTTPS/HTTP URLs and custom URL schemes (e.g. mobile deep links).
+ */
+declare function isOAuthRedirectUri(value: string): boolean;
+declare const OAuthClientRowSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    client_id: z.ZodString;
+    client_secret_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    logo_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    grant_types: z.ZodArray<z.ZodString>;
+    scopes: z.ZodArray<z.ZodString>;
+    confidential: z.ZodBoolean;
+    owner_user_id: z.ZodNumber;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthClientRow = z.infer<typeof OAuthClientRowSchema>;
+declare const OAuthClientListItemSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    logo_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    confidential: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthClientListItem = z.infer<typeof OAuthClientListItemSchema>;
+declare const OAuthClientDetailSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    logo_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    grant_types: z.ZodArray<z.ZodString>;
+    scopes: z.ZodArray<z.ZodString>;
+    confidential: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthClientDetail = z.infer<typeof OAuthClientDetailSchema>;
+declare const OAuthClientCreateSchema: z.ZodObject<{
+    client_name: z.ZodString;
+    client_uri: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    confidential: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type OAuthClientCreate = z.infer<typeof OAuthClientCreateSchema>;
+declare const OAuthClientUpdateSchema: z.ZodObject<{
+    client_name: z.ZodString;
+    client_uri: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type OAuthClientUpdate = z.infer<typeof OAuthClientUpdateSchema>;
+declare const OAuthClientCreateResponseSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    confidential: z.ZodBoolean;
+    client_name: z.ZodString;
+    client_uri: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthClientCreateResponse = z.infer<typeof OAuthClientCreateResponseSchema>;
+declare const OAuthClientSecretRotateResponseSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_secret: z.ZodString;
+}, z.core.$strip>;
+type OAuthClientSecretRotateResponse = z.infer<typeof OAuthClientSecretRotateResponseSchema>;
+declare const OAuthAuthorizeQuerySchema: z.ZodObject<{
+    response_type: z.ZodLiteral<"code">;
+    client_id: z.ZodString;
+    redirect_uri: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    code_challenge: z.ZodOptional<z.ZodString>;
+    code_challenge_method: z.ZodOptional<z.ZodLiteral<"S256">>;
+}, z.core.$strip>;
+type OAuthAuthorizeQuery = z.infer<typeof OAuthAuthorizeQuerySchema>;
+declare const OAuthConsentBodySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>;
+    client_id: z.ZodString;
+    redirect_uri: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    trust: z.ZodOptional<z.ZodBoolean>;
+    code_challenge: z.ZodOptional<z.ZodString>;
+    code_challenge_method: z.ZodOptional<z.ZodLiteral<"S256">>;
+}, z.core.$strip>;
+type OAuthConsentBody = z.infer<typeof OAuthConsentBodySchema>;
+declare const OAuthAuthorizationCodeRowSchema: z.ZodObject<{
+    code: z.ZodString;
+    client_id: z.ZodString;
+    user_id: z.ZodNumber;
+    redirect_uri: z.ZodString;
+    scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    code_challenge: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    code_challenge_method: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expires_at: z.ZodString;
+    used: z.ZodBoolean;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthAuthorizationCodeRow = z.infer<typeof OAuthAuthorizationCodeRowSchema>;
+
+interface OAuthClientsInterface {
+    listForOwner(ownerUserId: number): Promise<OAuthClientListItem[]>;
+    getByClientId(ownerUserId: number, clientId: string): Promise<OAuthClientDetail>;
+    create(ownerUserId: number, input: OAuthClientCreate): Promise<OAuthClientCreateResponse>;
+    update(ownerUserId: number, clientId: string, input: OAuthClientUpdate): Promise<OAuthClientDetail>;
+    rotateSecret(ownerUserId: number, clientId: string): Promise<OAuthClientSecretRotateResponse>;
+    delete(ownerUserId: number, clientId: string): Promise<void>;
+}
+
+/**
+ * Reads and manages registered OAuth clients from Supabase (service role).
+ */
+interface OAuthClientsRepositoryInterface {
+    findClientById(clientId: string): Promise<OAuthClientRow | null>;
+    listClientByOwner(ownerUserId: number): Promise<OAuthClientListItem[]>;
+    createClient(ownerUserId: number, input: OAuthClientCreate): Promise<{
+        client: OAuthClientRow;
+        clientSecret?: string;
+    }>;
+    updateClient(ownerUserId: number, clientId: string, input: OAuthClientUpdate): Promise<OAuthClientDetail>;
+    rotateClientSecret(ownerUserId: number, clientId: string): Promise<{
+        clientSecret: string;
+    }>;
+    deleteClient(ownerUserId: number, clientId: string): Promise<void>;
+    verifyClientCredentials(clientId: string, clientSecret: string | undefined): Promise<OAuthClientRow>;
+}
+
+type OAuthSessionPayload = {
+    userId: number;
+    email: string;
+    name: string;
+    providerSessionToken: string;
+};
+interface OAuthSessionInterface<Payload extends OAuthSessionPayload> {
+    getSession(): Promise<Payload | null>;
+    hasSession(): Promise<boolean>;
+    setSession(payload: Payload): Promise<void>;
+    clearSession(): Promise<void>;
+}
+
+declare const OAuthTokenAuthorizationCodeSchema: z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    code_verifier: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenAuthorizationCodeRequest = z.infer<typeof OAuthTokenAuthorizationCodeSchema>;
+declare const OAuthTokenRefreshSchema: z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenRefreshRequest = z.infer<typeof OAuthTokenRefreshSchema>;
+declare const OAuthTokenRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    code_verifier: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "grant_type">;
+type OAuthTokenRequest = z.infer<typeof OAuthTokenRequestSchema>;
+declare const OAuthTokenErrorResponseSchema: z.ZodObject<{
+    error: z.ZodString;
+    error_id: z.ZodOptional<z.ZodString>;
+    error_description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenErrorResponse = z.infer<typeof OAuthTokenErrorResponseSchema>;
+/** RFC 7009 token revocation request (refresh_token only in this wrapper). */
+declare const OAuthTokenRevokeSchema: z.ZodObject<{
+    token: z.ZodString;
+    token_type_hint: z.ZodOptional<z.ZodEnum<{
+        refresh_token: "refresh_token";
+        access_token: "access_token";
+    }>>;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenRevokeRequest = z.infer<typeof OAuthTokenRevokeSchema>;
+
+/**
+ * OAuth user adapter profile shape.
+ *
+ * Significance: Keeps OAuth services independent from provider SDK user models.
+ * Core idea: Represent only the profile fields required by OAuth login and userinfo.
+ * Main function: Provide a canonical user profile contract for adapters.
+ * Main purpose: Let the OAuth wrapper switch user providers without changing services.
+ *
+ * @example
+ * const sub = String(profile.id);
+ */
+type OAuthUserProfile = {
+    id: string | number;
+    email?: string | null;
+    name?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    roles?: string[];
+    [key: string]: unknown;
+};
+/**
+ * OAuth provider login credentials result.
+ *
+ * Significance: Normalizes provider login responses for middleware sessions.
+ * Core idea: Require a session token while allowing provider-specific metadata.
+ * Main function: Carry the provider session token after credential verification.
+ * Main purpose: Persist the token needed to mint OAuth access tokens later.
+ *
+ * @example
+ * const sessionToken = credentials.token;
+ */
+type OAuthUserCredentials = {
+    token: string;
+    [key: string]: unknown;
+};
+/**
+ * OAuth provider access token result.
+ *
+ * Significance: Normalizes provider token exchange responses.
+ * Core idea: OAuth token services only need access, expiry, and optional refresh token.
+ * Main function: Return a provider access token for third-party OAuth clients.
+ * Main purpose: Hide provider SDK response details behind the adapter contract.
+ *
+ * @example
+ * return { access_token: token.access_token, expires_in: token.expires_in };
+ */
+type OAuthUserAccessToken = {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string | null;
+    [key: string]: unknown;
+};
+/**
+ * User adapter contract for the OAuth wrapper.
+ *
+ * Significance: Defines the boundary between OAuth core services and user providers.
+ * Core idea: Keep provider-specific login, token exchange, and profile lookup behind one port.
+ * Main function: Verify credentials, exchange provider tokens, and load user profiles.
+ * Main purpose: Allow any upstream user API to be swapped without changing OAuth services.
+ *
+ * @example
+ * const access = await adapter.exchangeAccessToken({ token: sessionToken });
+ */
+interface OAuthUserAdapterInterface {
+    /**
+     * Verifies user credentials with the backing user provider.
+     *
+     * @param email - User email or username accepted by the provider.
+     * @param password - Plain credential submitted by the login form.
+     * @returns Provider credentials containing a session token.
+     */
+    login(email: string, password: string): Promise<OAuthUserCredentials>;
+    /**
+     * Exchanges a provider session token for a provider access token.
+     *
+     * @param params - Session token and optional language preference.
+     * @returns Provider access token payload used as the OAuth access token response.
+     */
+    exchangeAccessToken(params: {
+        token: string;
+        lang?: string;
+    }): Promise<OAuthUserAccessToken>;
+    /**
+     * Loads profile information using a provider session token.
+     *
+     * @param sessionToken - Provider session token from a successful login.
+     * @returns Canonical user profile for session creation.
+     */
+    getUserInfo(sessionToken: string): Promise<OAuthUserProfile>;
+    /**
+     * Loads profile information using a provider access token.
+     *
+     * @param accessToken - Bearer access token presented to the userinfo endpoint.
+     * @returns Canonical user profile for OIDC userinfo claims.
+     */
+    getUserInfoByAccessToken(accessToken: string): Promise<OAuthUserProfile>;
+}
+
+declare const OAuthUserCredentialsSchema: z.ZodObject<{
+    user_id: z.ZodNumber;
+    provider_refresh_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider_session_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthUserCredentialsRow = z.infer<typeof OAuthUserCredentialsSchema>;
+declare const OAuthRefreshTokenSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    user_id: z.ZodNumber;
+    expires_at: z.ZodString;
+    revoked: z.ZodBoolean;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type OAuthRefreshTokenRow = z.infer<typeof OAuthRefreshTokenSchema>;
+declare const OAuthTokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    expires_in: z.ZodNumber;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenResponse = z.infer<typeof OAuthTokenResponseSchema>;
+
+type CreateAuthorizationCodeInput = {
+    code: string;
+    client_id: string;
+    user_id: number;
+    redirect_uri: string;
+    scope: string | null;
+    code_challenge: string | null;
+    code_challenge_method: string | null;
+    expires_at: string;
+};
+type CreateOAuthRefreshTokenInput = {
+    refresh_token: string;
+    client_id: string;
+    user_id: number;
+    expires_at: string;
+};
+interface OAuthWrapperRepositoryInterface extends OAuthClientsRepositoryInterface {
+    create(input: CreateAuthorizationCodeInput): Promise<void>;
+    consumeCode(code: string): Promise<OAuthAuthorizationCodeRow | null>;
+    getUserCredentials(userId: number): Promise<OAuthUserCredentialsRow | null>;
+    upsertUserCredentials(userId: number, fields: {
+        provider_refresh_token?: string | null;
+        provider_session_token?: string | null;
+    }): Promise<void>;
+    findRefreshToken(tokenHash: string): Promise<OAuthRefreshTokenRow | null>;
+    upsertRefreshToken(input: {
+        refresh_token: string;
+        client_id: string;
+        user_id: number;
+        expires_at: string;
+    }): Promise<void>;
+    revokeRefreshToken(tokenHash: string): Promise<void>;
+    findByTokenHash(tokenHash: string): Promise<OAuthRefreshTokenRow | null>;
+    createRefreshToken(input: CreateOAuthRefreshTokenInput): Promise<void>;
+    revokeByTokenHash(tokenHash: string): Promise<void>;
+    /** Revoke all active refresh tokens issued for the given user. */
+    revokeRefreshTokensByUserId(userId: number): Promise<void>;
+}
+
+declare const OAuthUserInfoResponseSchema: z.ZodObject<{
+    sub: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+    roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type OAuthUserInfoResponse = z.infer<typeof OAuthUserInfoResponseSchema>;
+declare const OAuthUserInfoErrorResponseSchema: z.ZodObject<{
+    error: z.ZodLiteral<"invalid_token">;
+    error_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthUserInfoErrorResponse = z.infer<typeof OAuthUserInfoErrorResponseSchema>;
+
+/**
+ * OAuth authorize page data shared by server rendering and client UI.
+ *
+ * Significance: Prevents UI components from importing server-only services for types.
+ * Core idea: Keep the authorize page view model in the shared contract layer.
+ * Main function: Describe client metadata and request parameters for consent rendering.
+ * Main purpose: Let OAuth server modules move independently from UI code.
+ *
+ * @example
+ * const clientId = data.clientId;
+ */
+interface OAuthAuthorizePageData {
+    clientId: string;
+    clientName: string;
+    clientUri: string | null;
+    logoUri: string | null;
+    redirectUri: string;
+    scopes: string[];
+    state?: string;
+    responseType: 'code';
+    codeChallenge?: string;
+    codeChallengeMethod?: 'S256';
+    confidential: boolean;
+}
+type OAuthAuthorizeValidationError = {
+    errorKey: string;
+    message: string;
+};
+type OAuthConsentResult = {
+    redirectUrl: string;
+};
+interface OAuthTokenServiceInterface {
+    exchangeToken(rawFields: Record<string, string> | OAuthTokenRequest): Promise<OAuthTokenResponse>;
+    /**
+     * RFC 7009 token revocation. Revokes middleware refresh tokens when present.
+     * Always resolves (idempotent) per RFC guidance.
+     */
+    revokeToken(rawFields: Record<string, string>): Promise<void>;
+}
+interface OAuthServiceInterface<SessionPayload extends OAuthSessionPayload> extends OAuthTokenServiceInterface {
+    resolveAuthorizePage(rawQuery: Record<string, string | string[] | undefined>): Promise<{
+        ok: true;
+        data: OAuthAuthorizePageData;
+    } | {
+        ok: false;
+        error: OAuthAuthorizeValidationError;
+    }>;
+    processConsent(requestBody: unknown): Promise<OAuthConsentResult>;
+    getUserInfo(accessToken: string): Promise<OAuthUserInfoResponse>;
+    getOAuthSession(): OAuthSessionInterface<SessionPayload>;
+    getOAuthAdapter(): OAuthUserAdapterInterface;
+    getOAuthTokenService(): OAuthTokenServiceInterface;
+    getOAuthRepo(): OAuthWrapperRepositoryInterface;
+    /**
+     * Application logout: revoke issued refresh tokens, clear stored provider
+     * credentials, and clear the authorization-server session cookie.
+     */
+    logoutUser(userId: number): Promise<void>;
+}
+
+declare const OAuthRfcCodes: {
+    readonly INVALID_REQUEST: "invalid_request";
+    readonly INVALID_CLIENT: "invalid_client";
+    readonly INVALID_GRANT: "invalid_grant";
+    readonly INVALID_TOKEN: "invalid_token";
+    readonly UNAUTHORIZED_CLIENT: "unauthorized_client";
+    readonly INVALID_SCOPE: "invalid_scope";
+    readonly ACCESS_DENIED: "access_denied";
+    readonly UNSUPPORTED_RESPONSE_TYPE: "unsupported_response_type";
+    readonly UNSUPPORTED_GRANT_TYPE: "unsupported_grant_type";
+    readonly OAUTH_ERROR: "oauth_error";
+};
+type OAuthRfcErrorCodesType = typeof OAuthRfcCodes;
+/**
+ * OAuth 2.0 RFC 6749 `error` parameter values used in redirects and token responses.
+ */
+type OAuthRfcCodeType = ValueOf<OAuthRfcErrorCodesType>;
+
+declare function generatePkceVerifier(length?: number): string;
+declare function computePkceS256Challenge(verifier: string): Promise<string>;
+declare function randomOAuthState(): string;
+
+export { type CreateAuthorizationCodeInput, type CreateOAuthRefreshTokenInput, type OAuthAuthorizationCodeRow, OAuthAuthorizationCodeRowSchema, type OAuthAuthorizePageData, type OAuthAuthorizeQuery, OAuthAuthorizeQuerySchema, type OAuthAuthorizeValidationError, type OAuthClientCreate, type OAuthClientCreateResponse, OAuthClientCreateResponseSchema, OAuthClientCreateSchema, type OAuthClientDetail, OAuthClientDetailSchema, type OAuthClientListItem, OAuthClientListItemSchema, type OAuthClientRow, OAuthClientRowSchema, type OAuthClientSecretRotateResponse, OAuthClientSecretRotateResponseSchema, type OAuthClientUpdate, OAuthClientUpdateSchema, type OAuthClientsInterface, type OAuthClientsRepositoryInterface, type OAuthConsentBody, OAuthConsentBodySchema, type OAuthConsentResult, type OAuthRefreshTokenRow, OAuthRefreshTokenSchema, type OAuthRfcCodeType, OAuthRfcCodes, type OAuthRfcErrorCodesType, type OAuthServiceInterface, type OAuthSessionInterface, type OAuthSessionPayload, type OAuthTokenAuthorizationCodeRequest, OAuthTokenAuthorizationCodeSchema, type OAuthTokenErrorResponse, OAuthTokenErrorResponseSchema, type OAuthTokenRefreshRequest, OAuthTokenRefreshSchema, type OAuthTokenRequest, OAuthTokenRequestSchema, type OAuthTokenResponse, OAuthTokenResponseSchema, type OAuthTokenRevokeRequest, OAuthTokenRevokeSchema, type OAuthTokenServiceInterface, type OAuthUserAccessToken, type OAuthUserAdapterInterface, type OAuthUserCredentials, type OAuthUserCredentialsRow, OAuthUserCredentialsSchema, type OAuthUserInfoErrorResponse, OAuthUserInfoErrorResponseSchema, type OAuthUserInfoResponse, OAuthUserInfoResponseSchema, type OAuthUserProfile, type OAuthWrapperRepositoryInterface, computePkceS256Challenge, generatePkceVerifier, isOAuthRedirectUri, randomOAuthState };