@qlover/oauth-wrapper 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+import { OAuthClientsInterface, OAuthClientsRepositoryInterface, OAuthClientListItem, OAuthClientDetail, OAuthClientCreate, OAuthClientCreateResponse, OAuthClientUpdate, OAuthClientSecretRotateResponse, OAuthTokenServiceInterface, OAuthUserAdapterInterface, OAuthWrapperRepositoryInterface, OAuthTokenResponse, OAuthTokenRequest, OAuthSessionPayload, OAuthServiceInterface, OAuthSessionInterface, OAuthAuthorizeQuery, OAuthConsentBody, OAuthAuthorizePageData, OAuthAuthorizeValidationError, OAuthConsentResult, OAuthUserInfoResponse, OAuthUserProfile, OAuthRfcCodeType, OAuthClientRow } from './core.js';
+export { CreateAuthorizationCodeInput, CreateOAuthRefreshTokenInput, OAuthAuthorizationCodeRow, OAuthAuthorizationCodeRowSchema, OAuthAuthorizeQuerySchema, OAuthClientCreateResponseSchema, OAuthClientCreateSchema, OAuthClientDetailSchema, OAuthClientListItemSchema, OAuthClientRowSchema, OAuthClientSecretRotateResponseSchema, OAuthClientUpdateSchema, OAuthConsentBodySchema, OAuthRefreshTokenRow, OAuthRefreshTokenSchema, OAuthRfcCodes, OAuthRfcErrorCodesType, OAuthTokenAuthorizationCodeRequest, OAuthTokenAuthorizationCodeSchema, OAuthTokenErrorResponse, OAuthTokenErrorResponseSchema, OAuthTokenRefreshRequest, OAuthTokenRefreshSchema, OAuthTokenRequestSchema, OAuthTokenResponseSchema, OAuthTokenRevokeRequest, OAuthTokenRevokeSchema, OAuthUserAccessToken, OAuthUserCredentials, OAuthUserCredentialsRow, OAuthUserCredentialsSchema, OAuthUserInfoErrorResponse, OAuthUserInfoErrorResponseSchema, OAuthUserInfoResponseSchema, computePkceS256Challenge, generatePkceVerifier, isOAuthRedirectUri, randomOAuthState } from './core.js';
+import { EncryptorInterface, ExecutorError } from '@qlover/fe-corekit';
+import 'zod';
+
+/**
+ * Business logic for OAuth client management in developer console.
+ */
+declare class OAuthClientsService implements OAuthClientsInterface {
+    protected clientsRepo: OAuthClientsRepositoryInterface;
+    constructor(clientsRepo: OAuthClientsRepositoryInterface);
+    /**
+     * List all OAuth clients owned by a user
+     * @override
+     */
+    listForOwner(ownerUserId: number): Promise<OAuthClientListItem[]>;
+    /**
+     * Get detailed information about a specific OAuth client
+     * @override
+     */
+    getByClientId(ownerUserId: number, clientId: string): Promise<OAuthClientDetail>;
+    /**
+     * Create a new OAuth client
+     * @override
+     */
+    create(ownerUserId: number, input: OAuthClientCreate): Promise<OAuthClientCreateResponse>;
+    /**
+     * Update an existing OAuth client
+     * @override
+     */
+    update(ownerUserId: number, clientId: string, input: OAuthClientUpdate): Promise<OAuthClientDetail>;
+    /**
+     * Rotate the client secret
+     * @override
+     */
+    rotateSecret(ownerUserId: number, clientId: string): Promise<OAuthClientSecretRotateResponse>;
+    /**
+     * Delete an OAuth client
+     * @override
+     */
+    delete(ownerUserId: number, clientId: string): Promise<void>;
+    private mapToDetail;
+}
+
+/**
+ * OAuth 2.0 token endpoint (`POST /oauth/token`).
+ *
+ * Significance: Exchanges authorization codes and refresh tokens for provider access tokens.
+ * Core idea: Validate client + grant, consume codes, proxy user adapter token APIs.
+ * Main purpose: Standard token endpoint for third-party OAuth clients.
+ *
+ * @example
+ * const tokens = await service.exchangeToken(formFields);
+ */
+declare class OAuthTokenService implements OAuthTokenServiceInterface {
+    protected tokenEncryption: EncryptorInterface<string, string>;
+    protected userAdapter: OAuthUserAdapterInterface;
+    protected oauthRepo: OAuthWrapperRepositoryInterface;
+    protected static REFRESH_TOKEN_TTL_MS: number;
+    constructor(tokenEncryption: EncryptorInterface<string, string>, userAdapter: OAuthUserAdapterInterface, oauthRepo: OAuthWrapperRepositoryInterface);
+    /**
+     * @override
+     */
+    exchangeToken(rawFields: Record<string, string>): Promise<OAuthTokenResponse>;
+    protected exchangeAuthorizationCode(request: Extract<OAuthTokenRequest, {
+        grant_type: 'authorization_code';
+    }>, verifiedClientId: string): Promise<OAuthTokenResponse>;
+    protected assertPkceForAuthorizationCode(request: Extract<OAuthTokenRequest, {
+        grant_type: 'authorization_code';
+    }>, authCode: {
+        code_challenge?: string | null;
+        code_challenge_method?: string | null;
+    }): void;
+    protected exchangeRefreshToken(request: Extract<OAuthTokenRequest, {
+        grant_type: 'refresh_token';
+    }>, verifiedClientId: string): Promise<OAuthTokenResponse>;
+    protected fetchProviderAccessToken(userId: number): Promise<{
+        access_token: string;
+        expires_in: number;
+    }>;
+    protected issueMiddlewareRefreshToken(clientId: string, userId: number): Promise<string>;
+    /**
+     * @override
+     * RFC 7009 — revoke middleware refresh tokens. Idempotent: unknown tokens are ignored.
+     */
+    revokeToken(rawFields: Record<string, string>): Promise<void>;
+}
+
+declare class OAuthWrapperService<SessionPayload extends OAuthSessionPayload = OAuthSessionPayload> implements OAuthServiceInterface<SessionPayload> {
+    protected oauthSession: OAuthSessionInterface<SessionPayload>;
+    protected userAdapter: OAuthUserAdapterInterface;
+    protected tokenService: OAuthTokenServiceInterface;
+    protected oauthRepo: OAuthWrapperRepositoryInterface;
+    constructor(oauthSession: OAuthSessionInterface<SessionPayload>, userAdapter: OAuthUserAdapterInterface, tokenService: OAuthTokenServiceInterface, oauthRepo: OAuthWrapperRepositoryInterface);
+    /**
+     * @override
+     */
+    getOAuthSession(): OAuthSessionInterface<SessionPayload>;
+    /**
+     * @override
+     */
+    getOAuthAdapter(): OAuthUserAdapterInterface;
+    /**
+     * @override
+     */
+    getOAuthTokenService(): OAuthTokenServiceInterface;
+    /**
+     * @override
+     */
+    getOAuthRepo(): OAuthWrapperRepositoryInterface;
+    protected isQuery(query: unknown): query is OAuthAuthorizeQuery;
+    protected isValidateConsent(value: unknown): value is OAuthConsentBody;
+    /**
+     * @override
+     */
+    resolveAuthorizePage(rawQuery: Record<string, string | string[] | undefined>): Promise<{
+        ok: true;
+        data: OAuthAuthorizePageData;
+    } | {
+        ok: false;
+        error: OAuthAuthorizeValidationError;
+    }>;
+    /**
+     * @override
+     */
+    processConsent(requestBody: unknown): Promise<OAuthConsentResult>;
+    /**
+     * @override
+     */
+    exchangeToken(rawFields: Record<string, string>): Promise<OAuthTokenResponse>;
+    /**
+     * @override
+     */
+    revokeToken(rawFields: Record<string, string>): Promise<void>;
+    /**
+     * @override
+     */
+    logoutUser(userId: number): Promise<void>;
+    /**
+     * @override
+     */
+    getUserInfo(accessToken: string): Promise<OAuthUserInfoResponse>;
+    protected toUserInfoResponse(profile: OAuthUserProfile): OAuthUserInfoResponse;
+}
+
+declare class OAuthWrapperError extends ExecutorError {
+    readonly status: number;
+    readonly name = "OAuthWrapperError";
+    constructor(id: OAuthRfcCodeType, status: number, cause?: unknown);
+}
+
+declare function validatePkceParams(parsed: {
+    code_challenge?: string;
+    code_challenge_method?: 'S256';
+}, confidential: boolean): OAuthAuthorizeValidationError | null;
+declare function normalizeQuery(raw: Record<string, string | string[] | undefined>): Record<string, string | undefined>;
+declare function isRedirectUriAllowed(redirectUri: string, client: OAuthClientRow): boolean;
+
+/**
+ * Hashes OAuth client secrets for storage (scrypt, Node built-in).
+ *
+ * @example
+ * const hash = await hashClientSecret('my-secret');
+ */
+declare function hashClientSecret(secret: string): Promise<string>;
+/**
+ * Verifies a plaintext client secret against a stored scrypt hash.
+ */
+declare function verifyClientSecret(secret: string, storedHash: string): Promise<boolean>;
+
+/**
+ * Builds OAuth 2.0 redirect URLs for authorization responses.
+ */
+declare function buildOAuthRedirectUrl(redirectUri: string, params: Record<string, string | undefined>): string;
+declare function parseScopeList(scope: string | undefined): string[];
+
+/**
+ * PKCE helpers for RFC 7636 (S256 only).
+ *
+ * Significance: Validates and verifies code_verifier against stored code_challenge.
+ * Main purpose: Secure authorization code exchange for public OAuth clients.
+ */
+declare function isValidCodeVerifier(verifier: string): boolean;
+declare function isValidCodeChallenge(challenge: string): boolean;
+/**
+ * Computes the S256 code_challenge for a code_verifier.
+ */
+declare function computeS256CodeChallenge(verifier: string): string;
+/**
+ * Returns true when {@link verifier} matches the stored S256 {@link challenge}.
+ */
+declare function verifyPkceS256(verifier: string, challenge: string): boolean;
+
+export { OAuthAuthorizePageData, OAuthAuthorizeQuery, OAuthAuthorizeValidationError, OAuthClientCreate, OAuthClientCreateResponse, OAuthClientDetail, OAuthClientListItem, OAuthClientRow, OAuthClientSecretRotateResponse, OAuthClientUpdate, OAuthClientsInterface, OAuthClientsRepositoryInterface, OAuthClientsService, OAuthConsentBody, OAuthConsentResult, OAuthRfcCodeType, OAuthServiceInterface, OAuthSessionInterface, OAuthSessionPayload, OAuthTokenRequest, OAuthTokenResponse, OAuthTokenService, OAuthTokenServiceInterface, OAuthUserAdapterInterface, OAuthUserInfoResponse, OAuthUserProfile, OAuthWrapperError, OAuthWrapperRepositoryInterface, OAuthWrapperService, buildOAuthRedirectUrl, computeS256CodeChallenge, hashClientSecret, isRedirectUriAllowed, isValidCodeChallenge, isValidCodeVerifier, normalizeQuery, parseScopeList, validatePkceParams, verifyClientSecret, verifyPkceS256 };