feat(core,schemas): implement the social verification flow

implement the social verification flow

packages/connectors/connector-mock-social/src/index.ts

@@ -2,9 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 
 import type {
+ CreateConnector,
  GetAuthorizationUri,
  GetUserInfo,
- CreateConnector,
  SocialConnector,
 } from '@logto/connector-kit';
 import {
@@ -17,11 +17,23 @@ import {
 import { defaultMetadata } from './constant.js';
 import { mockSocialConfigGuard } from './types.js';
 
-const getAuthorizationUri: GetAuthorizationUri = async ({ state, redirectUri }) => {
+const getAuthorizationUri: GetAuthorizationUri = async (
+ { state, redirectUri, connectorId },
+ setSession
+) => {
+ try {
+ await setSession({ state, redirectUri, connectorId });
+ } catch (error: unknown) {
+ // Ignore the error if the method is not implemented
+ if (!(error instanceof ConnectorError && error.code === ConnectorErrorCodes.NotImplemented)) {
+ throw error;
+ }
+ }
+
  return `http://mock.social.com/?state=${state}&redirect_uri=${redirectUri}`;
 };
 
-const getUserInfo: GetUserInfo = async (data) => {
+const getUserInfo: GetUserInfo = async (data, getSession) => {
  const dataGuard = z.object({
  code: z.string(),
  userId: z.optional(z.string()),
@@ -34,6 +46,19 @@ const getUserInfo: GetUserInfo = async (data) => {
  throw new ConnectorError(ConnectorErrorCodes.InvalidResponse, JSON.stringify(data));
  }
 
+ try {
+ const connectorSession = await getSession();
+ // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+ if (!connectorSession) {
+ throw new ConnectorError(ConnectorErrorCodes.AuthorizationFailed);
+ }
+ } catch (error: unknown) {
+ // Ignore the error if the method is not implemented
+ if (!(error instanceof ConnectorError && error.code === ConnectorErrorCodes.NotImplemented)) {
+ throw error;
+ }
+ }
+
  const { code, userId, ...rest } = result.data;
 
  // For mock use only. Use to track the created user entity

packages/core/src/routes/experience/classes/experience-interaction.ts

@@ -83,6 +83,7 @@ export default class ExperienceInteraction {
  /** Set the verified `accountId` of the current interaction from the verification record */
  public identifyUser(verificationRecord: VerificationRecord) {
  // Throws an 404 error if the user is not found by the given verification record
+ // TODO: refactor using real-time user verification. Static verifiedUserId will be removed.
  assertThat(
  verificationRecord.verifiedUserId,
  new RequestError({

packages/core/src/routes/experience/classes/verifications/index.ts

@@ -14,8 +14,16 @@ import {
  passwordVerificationRecordDataGuard,
  type PasswordVerificationRecordData,
 } from './password-verification.js';
+import {
+ SocialVerification,
+ socialVerificationRecordDataGuard,
+ type SocialVerificationRecordData,
+} from './social-verification.js';
 
-type VerificationRecordData = PasswordVerificationRecordData | CodeVerificationRecordData;
+type VerificationRecordData =
+ | PasswordVerificationRecordData
+ | CodeVerificationRecordData
+ | SocialVerificationRecordData;
 
 /**
  * Union type for all verification record types
@@ -25,11 +33,12 @@ type VerificationRecordData = PasswordVerificationRecordData | CodeVerificationR
  * This union type is used to narrow down the type of the verification record.
  * Used in the ExperienceInteraction class to store and manage all the verification records. With a given verification type, we can narrow down the type of the verification record.
  */
-export type VerificationRecord = PasswordVerification | CodeVerification;
+export type VerificationRecord = PasswordVerification | CodeVerification | SocialVerification;
 
 export const verificationRecordDataGuard = z.discriminatedUnion('type', [
  passwordVerificationRecordDataGuard,
  codeVerificationRecordDataGuard,
+ socialVerificationRecordDataGuard,
 ]);
 
 /**
@@ -47,5 +56,8 @@ export const buildVerificationRecord = (
  case VerificationType.VerificationCode: {
  return new CodeVerification(libraries, queries, data);
  }
+ case VerificationType.Social: {
+ return new SocialVerification(libraries, queries, data);
+ }
  }
 };

packages/core/src/routes/experience/classes/verifications/social-verification.ts

@@ -0,0 +1,183 @@
+import { socialUserInfoGuard, type SocialUserInfo, type ToZodObject } from '@logto/connector-kit';
+import {
+ VerificationType,
+ type JsonObject,
+ type SocialAuthorizationUrlPayload,
+ type User,
+} from '@logto/schemas';
+import { generateStandardId } from '@logto/shared';
+import { z } from 'zod';
+
+import { type WithLogContext } from '#src/middleware/koa-audit-log.js';
+import {
+ createSocialAuthorizationUrl,
+ verifySocialIdentity,
+} from '#src/routes/interaction/utils/social-verification.js';
+import type Libraries from '#src/tenants/Libraries.js';
+import type Queries from '#src/tenants/Queries.js';
+import type TenantContext from '#src/tenants/TenantContext.js';
+
+import { type VerificationRecord } from './verification-record.js';
+
+/** The JSON data type for the SocialVerification record stored in the interaction storage */
+export type SocialVerificationRecordData = {
+ id: string;
+ connectorId: string;
+ type: VerificationType.Social;
+ /**
+ * The social identity returned by the connector.
+ */
+ socialUserInfo?: SocialUserInfo;
+ userId?: string;
+};
+
+export const socialVerificationRecordDataGuard = z.object({
+ id: z.string(),
+ connectorId: z.string(),
+ type: z.literal(VerificationType.Social),
+ socialUserInfo: socialUserInfoGuard.optional(),
+ userId: z.string().optional(),
+}) satisfies ToZodObject<SocialVerificationRecordData>;
+
+export class SocialVerification implements VerificationRecord<VerificationType.Social> {
+ /**
+ * Factory method to create a new SocialVerification instance
+ */
+ static create(libraries: Libraries, queries: Queries, connectorId: string) {
+ return new SocialVerification(libraries, queries, {
+ id: generateStandardId(),
+ connectorId,
+ type: VerificationType.Social,
+ });
+ }
+
+ public readonly id: string;
+ public readonly type = VerificationType.Social;
+ public readonly connectorId: string;
+ public socialUserInfo?: SocialUserInfo;
+
+ /**
+ * The userId of the user that has been verified by the social identity.
+ * @deprecated will be removed in the coming PR
+ */
+ public userId?: string;
+
+ constructor(
+ private readonly libraries: Libraries,
+ private readonly queries: Queries,
+ data: SocialVerificationRecordData
+ ) {
+ const { id, connectorId, socialUserInfo, userId } =
+ socialVerificationRecordDataGuard.parse(data);
+
+ this.id = id;
+ this.connectorId = connectorId;
+ this.socialUserInfo = socialUserInfo;
+ this.userId = userId;
+ }
+
+ /**
+ * Returns true if the social identity has been verified
+ */
+ get isVerified() {
+ return Boolean(this.socialUserInfo);
+ }
+
+ get verifiedUserId() {
+ return this.userId;
+ }
+
+ /**
+ * Create the authorization URL for the social connector.
+ * Store the connector session result in the provider's interaction storage.
+ *
+ * @remarks
+ * Refers to the {@link createSocialAuthorizationUrl} method in the interaction/utils/social-verification.ts file.
+ * Currently, all the intermediate connector session results are stored in the provider's interactionDetails separately,
+ * apart from the new verification record.
+ * For compatibility reasons, we keep using the old {@link createSocialAuthorizationUrl} method here as a single source of truth.
+ * Especially for the SAML connectors,
+ * SAML ACS endpoint will find the connector session result by the jti and assign it to the interaction storage.
+ * We will need to update the SAML ACS endpoint before move the logic to this new SocialVerification class.
+ *
+ * TODO: Consider store the connector session result in the verification record directly.
+ * SAML ACS endpoint will find the verification record by the jti and assign the connector session result to the verification record.
+ */
+ async createAuthorizationUrl(
+ ctx: WithLogContext,
+ tenantContext: TenantContext,
+ { state, redirectUri }: SocialAuthorizationUrlPayload
+ ) {
+ return createSocialAuthorizationUrl(ctx, tenantContext, {
+ connectorId: this.connectorId,
+ state,
+ redirectUri,
+ });
+ }
+
+ /**
+ * Verify the social identity and store the social identity in the verification record.
+ *
+ * - Store the social identity in the verification record.
+ * - Find the user by the social identity and store the userId in the verification record if the user exists.
+ *
+ * @remarks
+ * Refer to the {@link verifySocialIdentity} method in the interaction/utils/social-verification.ts file.
+ * For compatibility reasons, we keep using the old {@link verifySocialIdentity} method here as a single source of truth.
+ * See the above {@link createAuthorizationUrl} method for more details.
+ *
+ * TODO: check the log event
+ */
+ async verify(ctx: WithLogContext, tenantContext: TenantContext, connectorData: JsonObject) {
+ const socialUserInfo = await verifySocialIdentity(
+ { connectorId: this.connectorId, connectorData },
+ ctx,
+ tenantContext
+ );
+
+ this.socialUserInfo = socialUserInfo;
+
+ const user = await this.findUserBySocialIdentity();
+ this.userId = user?.id;
+ }
+
+ async findUserBySocialIdentity(): Promise<User | undefined> {
+ const { socials } = this.libraries;
+ const {
+ users: { findUserByIdentity },
+ } = this.queries;
+
+ if (!this.socialUserInfo) {
+ return;
+ }
+
+ const {
+ metadata: { target },
+ } = await socials.getConnector(this.connectorId);
+
+ const user = await findUserByIdentity(target, this.socialUserInfo.id);
+
+ return user ?? undefined;
+ }
+
+ async findRelatedUserBySocialIdentity(): ReturnType<typeof socials.findSocialRelatedUser> {
+ const { socials } = this.libraries;
+
+ if (!this.socialUserInfo) {
+ return null;
+ }
+
+ return socials.findSocialRelatedUser(this.socialUserInfo);
+ }
+
+ toJson(): SocialVerificationRecordData {
+ const { id, connectorId, socialUserInfo, type } = this;
+
+ return {
+ id,
+ connectorId,
+ type,
+ socialUserInfo,
+ };
+ }
+}

packages/core/src/routes/experience/index.ts

@@ -26,6 +26,7 @@ import koaExperienceInteraction, {
  type WithExperienceInteractionContext,
 } from './middleware/koa-experience-interaction.js';
 import passwordVerificationRoutes from './verification-routes/password-verification.js';
+import socialVerificationRoutes from './verification-routes/social-verification.js';
 import verificationCodeRoutes from './verification-routes/verification-code.js';
 
 type RouterContext<T> = T extends Router<unknown, infer Context> ? Context : never;
@@ -62,6 +63,10 @@ export default function experienceApiRoutes<T extends AnonymousRouter>(
  new RequestError({ code: 'session.verification_session_not_found', status: 404 })
  );
 
+ // TODO: SIE verification method check
+ // TODO: forgot password verification method check, only allow email and phone verification code
+ // TODO: user suspension check
+
  ctx.experienceInteraction.identifyUser(verificationRecord);
 
  await ctx.experienceInteraction.save();
@@ -89,4 +94,5 @@ export default function experienceApiRoutes<T extends AnonymousRouter>(
 
  passwordVerificationRoutes(router, tenant);
  verificationCodeRoutes(router, tenant);
+ socialVerificationRoutes(router, tenant);
 }