@seamless-auth/types 0.28.0 → 0.30.0

package/src/schemas/policy/schema.ts

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+
+import { IsoDate } from '../../shared.js';
+import { SystemConfigSchema } from '../systemConfig/schema.js';
+
+/**
+ * The system config keys that decide who can sign in, and how. These are the ones a
+ * change can lock people out with, so each published change is kept as a version that
+ * can be restored in one step, and can be staged as a draft and dry-run first.
+ */
+export const POLICY_KEYS = [
+  'login_methods',
+  'passkey_login_fallback_enabled',
+  'phishing_resistant_only',
+  'prompt_passkey_enrollment',
+  'authenticator_policy',
+  'lockout_policy',
+  'recovery_codes',
+  'account_recovery',
+] as const;
+
+export const PolicyKeySchema = z.enum(POLICY_KEYS);
+
+export type PolicyKey = z.infer<typeof PolicyKeySchema>;
+
+export const PolicyDocumentSchema = SystemConfigSchema.pick({
+  login_methods: true,
+  passkey_login_fallback_enabled: true,
+  phishing_resistant_only: true,
+  prompt_passkey_enrollment: true,
+  authenticator_policy: true,
+  lockout_policy: true,
+  recovery_codes: true,
+  account_recovery: true,
+});
+
+export type PolicyDocument = z.infer<typeof PolicyDocumentSchema>;
+
+/**
+ * How a version came to be. Drafts are optional: a whole-config PATCH that touches a
+ * policy key still applies immediately, and is recorded as a `config_patch` version so
+ * it can be rolled back like any other.
+ */
+export const PolicyVersionSourceSchema = z.enum([
+  'publish',
+  'rollback',
+  'config_patch',
+  'bootstrap',
+]);
+
+export type PolicyVersionSource = z.infer<typeof PolicyVersionSourceSchema>;
+
+export const PolicyVersionSchema = z.object({
+  version: z.number().int().positive(),
+  policy: PolicyDocumentSchema,
+  source: PolicyVersionSourceSchema,
+  publishedAt: IsoDate,
+  /** User id of the administrator, or null for a version the server wrote itself. */
+  publishedBy: z.string().nullable(),
+  /** The version a rollback restored. */
+  rolledBackTo: z.number().int().positive().optional(),
+});
+
+export type PolicyVersion = z.infer<typeof PolicyVersionSchema>;
+
+export const PolicyDraftSchema = z.object({
+  policy: PolicyDocumentSchema,
+  /** The published version the draft was started from. */
+  basedOnVersion: z.number().int().positive(),
+  updatedAt: IsoDate,
+  updatedBy: z.string().nullable(),
+});
+
+export type PolicyDraft = z.infer<typeof PolicyDraftSchema>;
+
+/** `GET /system-config/policy`. */
+export const PolicyStateResponseSchema = z.object({
+  published: PolicyVersionSchema,
+  draft: PolicyDraftSchema.nullable(),
+});
+
+export type PolicyStateResponse = z.infer<typeof PolicyStateResponseSchema>;
+
+/** `PUT /system-config/policy/draft`. */
+export const PolicyDraftSaveRequestSchema = z
+  .object({
+    policy: PolicyDocumentSchema,
+  })
+  .strict();
+
+export type PolicyDraftSaveRequest = z.infer<typeof PolicyDraftSaveRequestSchema>;
+
+/**
+ * `POST /system-config/policy/publish`. `expectedVersion` is the published version the
+ * caller reviewed; publishing answers `409` if another version was published since, so
+ * a stale draft cannot silently undo someone else's change.
+ */
+export const PolicyPublishRequestSchema = z
+  .object({
+    expectedVersion: z.number().int().positive(),
+  })
+  .strict();
+
+export type PolicyPublishRequest = z.infer<typeof PolicyPublishRequestSchema>;
+
+/** `POST /system-config/policy/rollback`: publishes a copy of `version` as a new version. */
+export const PolicyRollbackRequestSchema = z
+  .object({
+    version: z.number().int().positive(),
+    expectedVersion: z.number().int().positive(),
+  })
+  .strict();
+
+export type PolicyRollbackRequest = z.infer<typeof PolicyRollbackRequestSchema>;
+
+/** `GET /system-config/policy/versions`, newest first. */
+export const PolicyVersionsResponseSchema = z.object({
+  versions: z.array(PolicyVersionSchema),
+});
+
+export type PolicyVersionsResponse = z.infer<typeof PolicyVersionsResponseSchema>;
+
+/**
+ * `POST /system-config/policy/dry-run`. Without `policy`, evaluates the current draft.
+ */
+export const PolicyDryRunRequestSchema = z
+  .object({
+    policy: PolicyDocumentSchema.optional(),
+    days: z.number().int().min(1).max(30).default(7),
+  })
+  .strict();
+
+export type PolicyDryRunRequest = z.infer<typeof PolicyDryRunRequestSchema>;
+
+export const PolicyDryRunReasonSchema = z.enum([
+  'method_disabled',
+  'phishing_resistant_required',
+  'fallback_disabled',
+  'synced_passkey_blocked',
+  'authenticator_not_allowed',
+  'user_verification_required',
+]);
+
+export type PolicyDryRunReason = z.infer<typeof PolicyDryRunReasonSchema>;
+
+export const PolicyDryRunUserSchema = z.object({
+  userId: z.string(),
+  email: z.string(),
+  /** Sign-ins in the window this policy would have refused. */
+  signIns: z.number().int().nonnegative(),
+  reasons: z.array(PolicyDryRunReasonSchema).min(1),
+  /** True when none of the user's enrolled factors would still sign them in. */
+  lockedOut: z.boolean(),
+});
+
+export type PolicyDryRunUser = z.infer<typeof PolicyDryRunUserSchema>;
+
+export const PolicyDryRunResponseSchema = z.object({
+  window: z.object({ from: IsoDate, to: IsoDate }),
+  signInsEvaluated: z.number().int().nonnegative(),
+  usersEvaluated: z.number().int().nonnegative(),
+  wouldFail: z.array(PolicyDryRunUserSchema),
+  usersLockedOut: z.number().int().nonnegative(),
+  /** Break-glass accounts are exempt from policy, so they are counted, never refused. */
+  breakGlassAccounts: z.number().int().nonnegative(),
+});
+
+export type PolicyDryRunResponse = z.infer<typeof PolicyDryRunResponseSchema>;

package/src/schemas/recovery/schema.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+
+import { IsoDate } from '../../shared.js';
+import { NextStepSchema, RefreshSuccessResponseSchema } from '../auth/auth.schema.js';
+import { AuthDeliverySchema } from '../messaging/schema.js';
+
+/**
+ * Ten base32 characters, shown as `XXXXX-XXXXX`. Accepted with or without the dash
+ * and in either case, because people copy them from paper.
+ */
+export const RecoveryCodeSchema = z
+  .string()
+  .trim()
+  .regex(/^[A-Za-z2-7]{5}-?[A-Za-z2-7]{5}$/, { message: 'Not a recovery code' });
+
+export type RecoveryCode = z.infer<typeof RecoveryCodeSchema>;
+
+/** `GET /recovery-codes`. `createdAt` is null until the user has generated a set. */
+export const RecoveryCodesStatusSchema = z.object({
+  enabled: z.boolean(),
+  remaining: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+  createdAt: IsoDate.nullable(),
+});
+
+export type RecoveryCodesStatus = z.infer<typeof RecoveryCodesStatusSchema>;
+
+/**
+ * `POST /recovery-codes`. The only time the codes are ever returned; the server keeps
+ * them hashed. Generating a set invalidates the previous one.
+ */
+export const RecoveryCodesGeneratedSchema = z.object({
+  message: z.string(),
+  codes: z.array(RecoveryCodeSchema).min(1),
+  createdAt: IsoDate,
+});
+
+export type RecoveryCodesGenerated = z.infer<typeof RecoveryCodesGeneratedSchema>;
+
+/** `POST /recovery-codes/redeem`, with the pre-auth token from `/login`. */
+export const RecoveryCodeRedeemRequestSchema = z.object({
+  code: RecoveryCodeSchema,
+});
+
+export type RecoveryCodeRedeemRequest = z.infer<typeof RecoveryCodeRedeemRequestSchema>;
+
+/**
+ * The session a recovery issues. `recovery: true` marks a restricted session: until
+ * the user enrolls a new passkey or TOTP, the API answers `403 enrollment_required` on
+ * everything but enrollment, recovery codes, `/users/me` and logout, and the server
+ * adapters' `requireAuth` refuse it unless told otherwise. Enrolling rotates it into a
+ * normal session.
+ */
+export const RecoverySessionResponseSchema = RefreshSuccessResponseSchema.omit({
+  sessionId: true,
+}).extend({
+  recovery: z.literal(true),
+  nextStep: NextStepSchema,
+});
+
+export type RecoverySessionResponse = z.infer<typeof RecoverySessionResponseSchema>;
+
+export const AccountRecoveryChannelSchema = z.enum(['email', 'phone']);
+
+export type AccountRecoveryChannel = z.infer<typeof AccountRecoveryChannelSchema>;
+
+/**
+ * `POST /recovery/start`, with the pre-auth token from `/login`. Sends a code to the
+ * verified address on file for that channel. The answer is the same whether or not
+ * the account has one, so it does not say which channels an account has.
+ */
+export const AccountRecoveryStartRequestSchema = z.object({
+  channel: AccountRecoveryChannelSchema.default('email'),
+});
+
+export type AccountRecoveryStartRequest = z.infer<typeof AccountRecoveryStartRequestSchema>;
+
+export const AccountRecoveryStartResponseSchema = z.object({
+  message: z.string(),
+  delivery: AuthDeliverySchema.optional(),
+});
+
+export type AccountRecoveryStartResponse = z.infer<typeof AccountRecoveryStartResponseSchema>;
+
+/** `POST /recovery/verify`: the code from `/recovery/start` opens the request. */
+export const AccountRecoveryVerifyRequestSchema = z.object({
+  code: z.string().trim().min(1),
+});
+
+export type AccountRecoveryVerifyRequest = z.infer<typeof AccountRecoveryVerifyRequestSchema>;
+
+export const AccountRecoveryStateSchema = z.enum(['pending', 'ready', 'cancelled', 'completed']);
+
+export type AccountRecoveryState = z.infer<typeof AccountRecoveryStateSchema>;
+
+/**
+ * `POST /recovery/verify` and `GET /recovery/status`. `pending` until `completesAt`,
+ * then `ready`; every other channel and active session was told when it opened, and
+ * any of them can cancel it.
+ */
+export const AccountRecoveryStatusSchema = z.object({
+  state: AccountRecoveryStateSchema,
+  requestedAt: IsoDate,
+  completesAt: IsoDate,
+});
+
+export type AccountRecoveryStatus = z.infer<typeof AccountRecoveryStatusSchema>;
+
+/**
+ * `POST /recovery/cancel`. Either the token from the notice sent to the other
+ * channels, or no body with an access session for the account.
+ */
+export const AccountRecoveryCancelRequestSchema = z.object({
+  cancelToken: z.string().trim().min(1).optional(),
+});
+
+export type AccountRecoveryCancelRequest = z.infer<typeof AccountRecoveryCancelRequestSchema>;

package/src/schemas/systemConfig/schema.ts

@@ -45,6 +45,24 @@ export const RedirectTargetSchema = z.url().refine(
 
 export type RedirectTarget = z.infer<typeof RedirectTargetSchema>;
 
+// Provider endpoints the server fetches, and the authorization URL the browser is sent
+// to. `z.url()` alone accepts any scheme, including `javascript:`.
+const ProviderUrlSchema = z.url({ protocol: /^https?$/ });
+
+/**
+ * The auth server reads a provider's secret from this env var, so the name is held to
+ * the shape of an OAuth client secret: configuration cannot point the token exchange at
+ * any other secret the server holds (GHSA-qx82-28gf-w744).
+ */
+export const OAuthClientSecretEnvSchema = z
+  .string()
+  .trim()
+  .regex(/^[A-Z][A-Z0-9_]{0,59}_CLIENT_SECRET$/, {
+    message: 'Must be an env var name ending in _CLIENT_SECRET, for example GOOGLE_CLIENT_SECRET',
+  });
+
+export type OAuthClientSecretEnv = z.infer<typeof OAuthClientSecretEnvSchema>;
+
 export const OAuthProviderConfigSchema = z.object({
   id: OAuthProviderIdSchema,
   name: z.string().trim().min(1).max(80),
@@ -52,10 +70,10 @@ export const OAuthProviderConfigSchema = z.object({
   clientId: z.string().trim().min(1),
   // The secret itself never lives in config; this names the environment
   // variable the server reads it from.
-  clientSecretEnv: z.string().trim().min(1),
-  authorizationUrl: z.url(),
-  tokenUrl: z.url(),
-  userInfoUrl: z.url(),
+  clientSecretEnv: OAuthClientSecretEnvSchema,
+  authorizationUrl: ProviderUrlSchema,
+  tokenUrl: ProviderUrlSchema,
+  userInfoUrl: ProviderUrlSchema,
   scopes: z.array(z.string().trim().min(1)).default([]),
   redirectUri: z.url().optional(),
   redirectUris: z.array(z.url()).default([]),
@@ -73,7 +91,7 @@ export const OAuthProviderConfigSchema = z.object({
    * read for the profile claims instead of calling `userInfoUrl`.
    */
   issuer: z.url().optional(),
-  jwksUri: z.url().optional(),
+  jwksUri: ProviderUrlSchema.optional(),
   /**
    * Links a first sign-in to a user imported under this source (see
    * `ImportUsersRequestSchema`) whose external id equals the ID token claim at
@@ -277,6 +295,41 @@ export const DefaultAuthenticatorPolicy = {
 
 const DurationSchema = z.string().regex(/^\d+[smhd]$/);
 
+const DURATION_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 } as const;
+
+function durationSeconds(value: string) {
+  const unit = value.slice(-1) as keyof typeof DURATION_SECONDS;
+  return Number(value.slice(0, -1)) * DURATION_SECONDS[unit];
+}
+
+/**
+ * Single-use recovery codes. On by default: a user only has codes after generating
+ * them, so the switch only matters once someone has. Not a login method, so no
+ * `login_methods` change can take a user's way back in away from them.
+ */
+export const RecoveryCodesPolicySchema = z.object({
+  enabled: z.boolean().default(true),
+  /** Ask for a set of codes as part of first passkey enrollment. */
+  requireAtEnrollment: z.boolean().default(false),
+});
+
+export type RecoveryCodesPolicy = z.infer<typeof RecoveryCodesPolicySchema>;
+
+/**
+ * Self-service recovery through a verified email or phone, completed only after
+ * `delay` and announced on every other channel and session so the owner can cancel.
+ * Off by default: it is a way into an account that does not need its factors.
+ */
+export const AccountRecoveryPolicySchema = z.object({
+  enabled: z.boolean().default(false),
+  delay: DurationSchema.refine(
+    (value) => durationSeconds(value) >= 3600 && durationSeconds(value) <= 30 * 86400,
+    { message: 'delay must be between 1h and 30d' },
+  ).default('24h'),
+});
+
+export type AccountRecoveryPolicy = z.infer<typeof AccountRecoveryPolicySchema>;
+
 export const SystemConfigSchema = z.object({
   app_name: z.string().min(3),
   default_roles: z.array(RoleNameSchema).min(1),
@@ -305,6 +358,10 @@ export const SystemConfigSchema = z.object({
   authenticator_policy: AuthenticatorPolicySchema.default(() =>
     AuthenticatorPolicySchema.parse({}),
   ),
+  recovery_codes: RecoveryCodesPolicySchema.default(() => RecoveryCodesPolicySchema.parse({})),
+  account_recovery: AccountRecoveryPolicySchema.default(() =>
+    AccountRecoveryPolicySchema.parse({}),
+  ),
 
   access_token_ttl: z.string().regex(/^\d+[smhd]$/),
 
@@ -377,6 +434,8 @@ export const SystemConfigPatchSchema = z
     oauth_providers: z.array(OAuthProviderConfigSchema).optional(),
     lockout_policy: LockoutPolicySchema.optional(),
     authenticator_policy: AuthenticatorPolicySchema.optional(),
+    recovery_codes: RecoveryCodesPolicySchema.optional(),
+    account_recovery: AccountRecoveryPolicySchema.optional(),
     access_token_ttl: SystemConfigSchema.shape.access_token_ttl.optional(),
     session_idle_ttl: DurationSchema.optional(),
     refresh_token_ttl: SystemConfigSchema.shape.refresh_token_ttl.optional(),
@@ -511,6 +570,10 @@ export type AvailableRolesResponse = z.infer<typeof AvailableRolesResponseSchema
  */
 export const PublicSystemConfigResponseSchema = z.object({
   loginMethods: z.array(LoginMethodSchema).min(1),
+  // Optional so a client still parses a server from before v0.20. Lets the sign-in
+  // screens offer "use a recovery code" and "can't sign in?" only where they work.
+  recoveryCodes: z.boolean().optional(),
+  accountRecovery: z.boolean().optional(),
 });
 
 export type PublicSystemConfigResponse = z.infer<typeof PublicSystemConfigResponseSchema>;