1import type * as cip from "@distilled.cloud/aws/cognito-identity-provider";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { UserPoolClient } from "./UserPoolClient.ts";
5
6export interface SignUpRequest extends Omit<cip.SignUpRequest, "ClientId"> {}
7export interface ConfirmSignUpRequest extends Omit<
8 cip.ConfirmSignUpRequest,
9 "ClientId"
10> {}
11export interface ResendConfirmationCodeRequest extends Omit<
12 cip.ResendConfirmationCodeRequest,
13 "ClientId"
14> {}
15export interface InitiateAuthRequest extends Omit<
16 cip.InitiateAuthRequest,
17 "ClientId"
18> {}
19export interface RespondToAuthChallengeRequest extends Omit<
20 cip.RespondToAuthChallengeRequest,
21 "ClientId"
22> {}
23export interface ForgotPasswordRequest extends Omit<
24 cip.ForgotPasswordRequest,
25 "ClientId"
26> {}
27export interface ConfirmForgotPasswordRequest extends Omit<
28 cip.ConfirmForgotPasswordRequest,
29 "ClientId"
30> {}
31export interface RevokeTokenRequest extends Omit<
32 cip.RevokeTokenRequest,
33 "ClientId" | "ClientSecret"
34> {}
35export interface GetTokensFromRefreshTokenRequest extends Omit<
36 cip.GetTokensFromRefreshTokenRequest,
37 "ClientId"
38> {}
39
40/**
41 * The typed client returned by binding {@link UserPoolAuth} to a
42 * `UserPoolClient`. Every method automatically injects the app client ID.
43 */
44export interface UserPoolAuthClient {
45 /** Register a new user (public sign-up flow). */
46 signUp: (
47 request: SignUpRequest,
48 ) => Effect.Effect<cip.SignUpResponse, cip.SignUpError>;
49 /** Confirm a sign-up with the emailed/SMSed confirmation code. */
50 confirmSignUp: (
51 request: ConfirmSignUpRequest,
52 ) => Effect.Effect<cip.ConfirmSignUpResponse, cip.ConfirmSignUpError>;
53 /** Resend the sign-up confirmation code. */
54 resendConfirmationCode: (
55 request: ResendConfirmationCodeRequest,
56 ) => Effect.Effect<
57 cip.ResendConfirmationCodeResponse,
58 cip.ResendConfirmationCodeError
59 >;
60 /** Start an authentication flow (e.g. `USER_PASSWORD_AUTH`). */
61 initiateAuth: (
62 request: InitiateAuthRequest,
63 ) => Effect.Effect<cip.InitiateAuthResponse, cip.InitiateAuthError>;
64 /** Answer an auth challenge returned by `initiateAuth`. */
65 respondToAuthChallenge: (
66 request: RespondToAuthChallengeRequest,
67 ) => Effect.Effect<
68 cip.RespondToAuthChallengeResponse,
69 cip.RespondToAuthChallengeError
70 >;
71 /** Start the forgot-password flow. */
72 forgotPassword: (
73 request: ForgotPasswordRequest,
74 ) => Effect.Effect<cip.ForgotPasswordResponse, cip.ForgotPasswordError>;
75 /** Complete the forgot-password flow with the confirmation code. */
76 confirmForgotPassword: (
77 request: ConfirmForgotPasswordRequest,
78 ) => Effect.Effect<
79 cip.ConfirmForgotPasswordResponse,
80 cip.ConfirmForgotPasswordError
81 >;
82 /** Fetch the signed-in user's profile from an access token. */
83 getUser: (
84 request: cip.GetUserRequest,
85 ) => Effect.Effect<cip.GetUserResponse, cip.GetUserError>;
86 /** Sign the user out of all devices (invalidates tokens). */
87 globalSignOut: (
88 request: cip.GlobalSignOutRequest,
89 ) => Effect.Effect<cip.GlobalSignOutResponse, cip.GlobalSignOutError>;
90 /** Revoke a refresh token and all access tokens derived from it. */
91 revokeToken: (
92 request: RevokeTokenRequest,
93 ) => Effect.Effect<cip.RevokeTokenResponse, cip.RevokeTokenError>;
94 /** Exchange a refresh token for fresh access/ID tokens (refresh-token
95 * rotation aware). */
96 getTokensFromRefreshToken: (
97 request: GetTokensFromRefreshTokenRequest,
98 ) => Effect.Effect<
99 cip.GetTokensFromRefreshTokenResponse,
100 cip.GetTokensFromRefreshTokenError
101 >;
102 /** Change the signed-in user's password. */
103 changePassword: (
104 request: cip.ChangePasswordRequest,
105 ) => Effect.Effect<cip.ChangePasswordResponse, cip.ChangePasswordError>;
106 /** Update the signed-in user's attributes. */
107 updateUserAttributes: (
108 request: cip.UpdateUserAttributesRequest,
109 ) => Effect.Effect<
110 cip.UpdateUserAttributesResponse,
111 cip.UpdateUserAttributesError
112 >;
113 /** Delete attributes from the signed-in user's profile. */
114 deleteUserAttributes: (
115 request: cip.DeleteUserAttributesRequest,
116 ) => Effect.Effect<
117 cip.DeleteUserAttributesResponse,
118 cip.DeleteUserAttributesError
119 >;
120 /** Send a verification code for an updated attribute (email/phone). */
121 getUserAttributeVerificationCode: (
122 request: cip.GetUserAttributeVerificationCodeRequest,
123 ) => Effect.Effect<
124 cip.GetUserAttributeVerificationCodeResponse,
125 cip.GetUserAttributeVerificationCodeError
126 >;
127 /** Verify an attribute with the code delivered to it. */
128 verifyUserAttribute: (
129 request: cip.VerifyUserAttributeRequest,
130 ) => Effect.Effect<
131 cip.VerifyUserAttributeResponse,
132 cip.VerifyUserAttributeError
133 >;
134 /** Set the signed-in user's MFA preferences (SMS / TOTP / email). */
135 setUserMFAPreference: (
136 request: cip.SetUserMFAPreferenceRequest,
137 ) => Effect.Effect<
138 cip.SetUserMFAPreferenceResponse,
139 cip.SetUserMFAPreferenceError
140 >;
141 /** Begin TOTP enrollment: returns the shared secret to seed the
142 * authenticator app. */
143 associateSoftwareToken: (
144 request: cip.AssociateSoftwareTokenRequest,
145 ) => Effect.Effect<
146 cip.AssociateSoftwareTokenResponse,
147 cip.AssociateSoftwareTokenError
148 >;
149 /** Complete TOTP enrollment by verifying a generated code. */
150 verifySoftwareToken: (
151 request: cip.VerifySoftwareTokenRequest,
152 ) => Effect.Effect<
153 cip.VerifySoftwareTokenResponse,
154 cip.VerifySoftwareTokenError
155 >;
156 /** List the auth factors configured for the signed-in user. */
157 getUserAuthFactors: (
158 request: cip.GetUserAuthFactorsRequest,
159 ) => Effect.Effect<
160 cip.GetUserAuthFactorsResponse,
161 cip.GetUserAuthFactorsError
162 >;
163 /** Delete the signed-in user's own account. */
164 deleteUser: (
165 request: cip.DeleteUserRequest,
166 ) => Effect.Effect<cip.DeleteUserResponse, cip.DeleteUserError>;
167}
168
169/**
170 * Runtime binding for the public (client-side) Cognito user pool auth flows.
171 *
172 * Bind this to a `UserPoolClient` inside a function runtime to get a typed
173 * client for sign-up, sign-in, and token flows. These operations are
174 * unauthenticated (Cognito does not evaluate IAM for them), so the binding
175 * grants no IAM policy — it injects the app client ID into every call.
176 * ### Authenticating Users
177 * **Example:** Username/Password Sign-In
178 * ```typescript
179 * const auth = yield* Cognito.UserPoolAuth(client);
180 *
181 * const result = yield* auth.initiateAuth({
182 * AuthFlow: "USER_PASSWORD_AUTH",
183 * AuthParameters: { USERNAME: username, PASSWORD: password },
184 * });
185 * const idToken = result.AuthenticationResult?.IdToken;
186 * ```
187 *
188 * **Example:** Sign-Up and Confirmation
189 * ```typescript
190 * yield* auth.signUp({
191 * Username: "user@example.com",
192 * Password: "Sup3r-secret!",
193 * UserAttributes: [{ Name: "email", Value: "user@example.com" }],
194 * });
195 * yield* auth.confirmSignUp({
196 * Username: "user@example.com",
197 * ConfirmationCode: code,
198 * });
199 * ```
200 *
201 * **Example:** Read the Signed-In User
202 * ```typescript
203 * const user = yield* auth.getUser({ AccessToken: accessToken });
204 * ```
205 *
206 * ### Self-Service Account Management
207 * **Example:** Change Password and Update Attributes
208 * ```typescript
209 * yield* auth.changePassword({
210 * AccessToken: accessToken,
211 * PreviousPassword: oldPassword,
212 * ProposedPassword: newPassword,
213 * });
214 * yield* auth.updateUserAttributes({
215 * AccessToken: accessToken,
216 * UserAttributes: [{ Name: "nickname", Value: "sam" }],
217 * });
218 * ```
219 *
220 * **Example:** Refresh Tokens
221 * ```typescript
222 * const refreshed = yield* auth.getTokensFromRefreshToken({
223 * RefreshToken: refreshToken,
224 * });
225 * ```
226 *
227 * @binding
228 */
229export interface UserPoolAuth extends Binding.Service<
230 UserPoolAuth,
231 "AWS.Cognito.UserPoolAuth",
232 <C extends UserPoolClient>(client: C) => Effect.Effect<UserPoolAuthClient>
233> {}
234export const UserPoolAuth = Binding.Service<UserPoolAuth>(
235 "AWS.Cognito.UserPoolAuth",
236);