@seamless-auth/types 0.24.0 → 0.26.0

package/src/schemas/enrollment/schema.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { IsoDate } from '../../shared.js';
+import { PaginationQuerySchema } from '../common/schema.js';
+import { AuthDeliverySchema } from '../messaging/schema.js';
+import { RedirectTargetSchema } from '../systemConfig/schema.js';
+
+/**
+ * How far a user is through passkey enrollment, counted in WebAuthn credentials
+ * (passkeys and security keys; TOTP does not count). Two or more is the goal, so
+ * losing one authenticator does not lock the user out.
+ */
+export const EnrollmentStatusSchema = z.enum(['none', 'one', 'two_or_more']);
+
+export type EnrollmentStatus = z.infer<typeof EnrollmentStatusSchema>;
+
+// Accepts the parsed boolean as well as the query string, so parsing an already
+// parsed query (as the server does to recover coerced types) gives the same answer.
+const BooleanQuerySchema = z.union([
+  z.boolean(),
+  z.enum(['true', 'false']).transform((value) => value === 'true'),
+]);
+
+export const AdminEnrollmentQuerySchema = PaginationQuerySchema.extend({
+  organizationId: z.uuid().optional(),
+  status: EnrollmentStatusSchema.optional(),
+  /** Only users brought in through `POST /admin/users/import`. */
+  imported: BooleanQuerySchema.optional(),
+  search: z.string().trim().min(1).max(120).optional(),
+});
+
+export type AdminEnrollmentQuery = z.infer<typeof AdminEnrollmentQuerySchema>;
+
+export const EnrollmentSummarySchema = z.object({
+  total: z.number().int().nonnegative(),
+  none: z.number().int().nonnegative(),
+  one: z.number().int().nonnegative(),
+  twoOrMore: z.number().int().nonnegative(),
+});
+
+export type EnrollmentSummary = z.infer<typeof EnrollmentSummarySchema>;
+
+export const EnrollmentUserSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  imported: z.boolean(),
+  credentialCount: z.number().int().nonnegative(),
+  status: EnrollmentStatusSchema,
+  lastLogin: IsoDate.nullable(),
+  enrollmentInvitedAt: IsoDate.nullable(),
+});
+
+export type EnrollmentUser = z.infer<typeof EnrollmentUserSchema>;
+
+/**
+ * `summary` counts every user matching `organizationId` and `imported`, whatever the
+ * `status` filter; `users` and `total` are the filtered, paginated list.
+ */
+export const AdminEnrollmentResponseSchema = z.object({
+  summary: EnrollmentSummarySchema,
+  users: z.array(EnrollmentUserSchema),
+  total: z.number().int().nonnegative(),
+});
+
+export type AdminEnrollmentResponse = z.infer<typeof AdminEnrollmentResponseSchema>;
+
+export const ENROLLMENT_INVITE_MAX_USERS = 200;
+
+/**
+ * Invites either the listed users or, with `organizationId`, the organization's members
+ * whose enrollment is at or below `status`. An organization-wide call sends at most
+ * `ENROLLMENT_INVITE_MAX_USERS` and reports how many remain, skipping anyone invited
+ * within the last day, so repeating it works through a large organization.
+ */
+export const EnrollmentInviteRequestSchema = z
+  .object({
+    userIds: z.array(z.uuid()).min(1).max(ENROLLMENT_INVITE_MAX_USERS).optional(),
+    organizationId: z.uuid().optional(),
+    status: z.enum(['none', 'one']).default('none'),
+    /** Where the email sends the user. Defaults to the tenant's sign-in page. */
+    signInUrl: RedirectTargetSchema.optional(),
+  })
+  .strict()
+  .refine((value) => Boolean(value.userIds) !== Boolean(value.organizationId), {
+    message: 'exactly one of userIds or organizationId is required',
+  });
+
+export type EnrollmentInviteRequest = z.infer<typeof EnrollmentInviteRequestSchema>;
+
+export const ENROLLMENT_INVITE_SKIP_REASONS = [
+  'not_found',
+  'already_enrolled',
+  'recently_invited',
+  'delivery_failed',
+] as const;
+
+export const EnrollmentInviteSkipReasonSchema = z.enum(ENROLLMENT_INVITE_SKIP_REASONS);
+
+export type EnrollmentInviteSkipReason = z.infer<typeof EnrollmentInviteSkipReasonSchema>;
+
+export const EnrollmentInviteResultSchema = z.object({
+  userId: z.string(),
+  status: z.enum(['sent', 'skipped']),
+  reason: EnrollmentInviteSkipReasonSchema.optional(),
+  /** Present in external delivery mode, for the caller to send itself. */
+  delivery: AuthDeliverySchema.optional(),
+});
+
+export type EnrollmentInviteResult = z.infer<typeof EnrollmentInviteResultSchema>;
+
+export const EnrollmentInviteResponseSchema = z.object({
+  sent: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  /** Organization-wide calls only: eligible members left for a later call. */
+  remaining: z.number().int().nonnegative().optional(),
+  results: z.array(EnrollmentInviteResultSchema),
+});
+
+export type EnrollmentInviteResponse = z.infer<typeof EnrollmentInviteResponseSchema>;

package/src/schemas/messaging/schema.ts

@@ -81,6 +81,12 @@ export const AuthDeliverySchema = z.discriminatedUnion('kind', [
     token: z.string().optional(),
     magicLinkUrl: z.string(),
   }),
+  z.object({
+    kind: z.literal('enrollment_invite_email'),
+    to: z.string(),
+    // The sign-in page. It carries no credential, so it signs nobody in on its own.
+    signInUrl: z.string(),
+  }),
 ]);
 
 export type AuthDeliveryInstruction = z.infer<typeof AuthDeliverySchema>;

package/src/schemas/oauth/schema.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { RefreshSuccessResponseSchema } from '../auth/auth.schema.js';
-import { OAuthProviderIdSchema, RedirectTargetSchema } from '../systemConfig/schema.js';
+import { NextStepSchema, RefreshSuccessResponseSchema } from '../auth/auth.schema.js';
+import { OAuthProviderIdSchema } from '../common/schema.js';
+import { RedirectTargetSchema } from '../systemConfig/schema.js';
 
 export const OAuthProviderParamSchema = z.object({
   providerId: OAuthProviderIdSchema,
@@ -58,6 +59,13 @@ export const OAuthLoginSuccessResponseSchema = RefreshSuccessResponseSchema.omit
    * as an error.
    */
   returnTo: RedirectTargetSchema.optional(),
+  /**
+   * Present when the provider has `promptPasskeyEnrollment` set and the user has no
+   * passkey. The session in this response is a full access session, so the client sends
+   * the user into passkey enrollment before the app. Absent means there is nothing
+   * further to do.
+   */
+  nextStep: NextStepSchema.optional(),
 });
 
 export type OAuthLoginSuccessResponse = z.infer<typeof OAuthLoginSuccessResponseSchema>;
@@ -66,6 +74,9 @@ export const OAUTH_ERROR_CODES = [
   'oauth_missing_email',
   'oauth_email_not_verified',
   'oauth_missing_subject',
+  'oauth_invalid_id_token',
+  // A member of an organization that has retired this provider. Answered with 403.
+  'oauth_provider_retired',
 ] as const;
 
 export const OAuthErrorCodeSchema = z.enum(OAUTH_ERROR_CODES);

package/src/schemas/organization/schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { IsoDate } from '../../shared.js';
-import { MetadataSchema } from '../common/schema.js';
+import { MetadataSchema, OAuthProviderIdSchema } from '../common/schema.js';
 
 export const OrganizationIdParamSchema = z.object({
   organizationId: z.uuid(),
@@ -8,6 +8,12 @@ export const OrganizationIdParamSchema = z.object({
 
 export type OrganizationIdParam = z.infer<typeof OrganizationIdParamSchema>;
 
+export const OrganizationOAuthProviderParamSchema = OrganizationIdParamSchema.extend({
+  providerId: OAuthProviderIdSchema,
+});
+
+export type OrganizationOAuthProviderParam = z.infer<typeof OrganizationOAuthProviderParamSchema>;
+
 export const OrganizationMemberParamSchema = OrganizationIdParamSchema.extend({
   userId: z.uuid(),
 });
@@ -86,6 +92,11 @@ export const OrganizationSchema = z.object({
   updatedAt: IsoDate,
   membership: OrganizationMembershipSchema.optional(),
   memberCount: z.number().int().nonnegative().optional(),
+  /**
+   * OAuth providers this organization's members can no longer sign in with, for cutting
+   * over from a legacy identity provider.
+   */
+  retiredOAuthProviders: z.array(OAuthProviderIdSchema).optional(),
 });
 
 export type Organization = z.infer<typeof OrganizationSchema>;

package/src/schemas/systemConfig/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { OAuthProviderIdSchema } from '../common/schema.js';
 import { UserImportSourceSchema } from '../userImport/schema.js';
 import { RoleNameSchema } from '../role/schema.js';
 
@@ -44,10 +45,6 @@ export const RedirectTargetSchema = z.url().refine(
 
 export type RedirectTarget = z.infer<typeof RedirectTargetSchema>;
 
-export const OAuthProviderIdSchema = z.string().regex(/^[a-z0-9-]{2,40}$/);
-
-export type OAuthProviderId = z.infer<typeof OAuthProviderIdSchema>;
-
 export const OAuthProviderConfigSchema = z.object({
   id: OAuthProviderIdSchema,
   name: z.string().trim().min(1).max(80),
@@ -85,6 +82,12 @@ export const OAuthProviderConfigSchema = z.object({
    */
   externalIdSource: UserImportSourceSchema.optional(),
   externalIdJsonPath: z.string().trim().min(1).optional(),
+  /**
+   * After a sign-in through this provider by a user with no passkey, the callback
+   * response carries `nextStep: 'enroll_passkey'`. Meant for a legacy identity provider
+   * that users are being moved off.
+   */
+  promptPasskeyEnrollment: z.boolean().default(false),
 });
 
 export type OAuthProviderConfig = z.infer<typeof OAuthProviderConfigSchema>;
@@ -280,6 +283,13 @@ export const SystemConfigSchema = z.object({
   available_roles: z.array(RoleNameSchema).min(1),
   login_methods: z.array(LoginMethodSchema).min(1),
   passkey_login_fallback_enabled: z.boolean(),
+  /**
+   * After an email or phone code sign-in, or a magic link sign-in, by a user with no
+   * passkey, the session response carries `nextStep: 'enroll_passkey'`. For moving an
+   * organization onto passkeys, for example after importing its users. OAuth
+   * providers have their own `promptPasskeyEnrollment`.
+   */
+  prompt_passkey_enrollment: z.boolean().default(false),
   oauth_providers: z.array(OAuthProviderConfigSchema).default([]),
   lockout_policy: LockoutPolicySchema.default(DefaultLockoutPolicy),
   // Derived from the field defaults rather than restated, so the two cannot drift.
@@ -354,6 +364,7 @@ export const SystemConfigPatchSchema = z
     login_methods: SystemConfigSchema.shape.login_methods.optional(),
     passkey_login_fallback_enabled:
       SystemConfigSchema.shape.passkey_login_fallback_enabled.optional(),
+    prompt_passkey_enrollment: z.boolean().optional(),
     oauth_providers: z.array(OAuthProviderConfigSchema).optional(),
     lockout_policy: LockoutPolicySchema.optional(),
     authenticator_policy: AuthenticatorPolicySchema.optional(),
@@ -413,10 +424,28 @@ export const OAuthProviderIdParamSchema = z.object({
 
 export type OAuthProviderIdParam = z.infer<typeof OAuthProviderIdParamSchema>;
 
+type WithoutDefaults<Shape extends z.ZodRawShape> = {
+  [Key in keyof Shape]: Shape[Key] extends z.ZodDefault<infer Inner> ? Inner : Shape[Key];
+};
+
+function withoutDefaults<Shape extends z.ZodRawShape>(shape: Shape): WithoutDefaults<Shape> {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, field]) => [
+      key,
+      field instanceof z.ZodDefault ? field.unwrap() : field,
+    ]),
+  ) as WithoutDefaults<Shape>;
+}
+
 // The id is immutable and taken from the path, so it is omitted here. Every other
 // field is optional so callers can patch a single attribute without resending the
 // whole provider; the merged result is re-validated against the full schema.
-export const OAuthProviderUpdateSchema = OAuthProviderConfigSchema.omit({ id: true })
+//
+// Defaults are stripped first: `.partial()` keeps them, so a patch of one field would
+// parse to that field plus every default, and merging that over the stored provider
+// silently reset settings such as `accountLinking` and `allowSignup`.
+export const OAuthProviderUpdateSchema = z
+  .object(withoutDefaults(OAuthProviderConfigSchema.omit({ id: true }).shape))
   .partial()
   .strict();