feat(api,platform): add support for the operator-only API to clone users

Author: azasypkin

components/secutils-docs/static/img/docs/guides/api_keys/api_keys_step4_token_reveal.png

@@ -23,6 +23,12 @@ import { getOryApi } from '../../tools/ory';
 
 export interface RecoverAccountModalProps {
   email?: string;
+  /**
+   * Optional pre-existing Kratos recovery flow ID. When provided (e.g. via the `/signin?recover=1&flow=...` deep-link
+   * Kratos uses for admin-issued recovery codes), the modal jumps straight to the "enter recovery code" step instead of
+   * asking the user to request a new code.
+   */
+  flowId?: string;
   onClose: () => void;
 }
 
@@ -39,14 +45,38 @@ async function getRecoverFlow(api: FrontendApi, flowId?: string) {
   return await api.createBrowserRecoveryFlow();
 }
 
-export function RecoverAccountModal({ email, onClose }: RecoverAccountModalProps) {
+export function RecoverAccountModal({ email, flowId, onClose }: RecoverAccountModalProps) {
   const { addToast, uiState, refreshUiState } = useAppContext();
   const navigate = useNavigate();
 
   const [userEmail, setUserEmail] = useState<string>(email ?? '');
   const [recoveryCode, setRecoveryCode] = useState<string>('');
 
   const [accountRecoveryStatus, setAccountRecoveryStatus] = useState<AsyncData<undefined, RecoveryFlow> | null>(null);
+
+  // When a Kratos recovery flow ID is supplied via deep-link, hydrate it on mount so the
+  // submit step is wired up to the same flow Kratos already issued the code for.
+  useEffect(() => {
+    if (!flowId) {
+      return;
+    }
+
+    let cancelled = false;
+    getOryApi()
+      .then(async (api) => {
+        const flow = await getRecoverFlow(api, flowId);
+        if (cancelled) {
+          return;
+        }
+        setAccountRecoveryStatus({ status: 'succeeded', data: undefined, state: flow });
+      })
+      .catch((err: unknown) => {
+        console.error('Failed to load recovery flow from deep-link.', err);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [flowId]);
   const onSendRecoveryCode: MouseEventHandler<HTMLButtonElement> = (e) => {
     e.preventDefault();
 
@@ -156,6 +186,10 @@ export function RecoverAccountModal({ email, onClose }: RecoverAccountModalProps
   }, [uiState, navigate]);
 
   const awaitingRecoveryCode = !!accountRecoveryStatus?.state;
+  // True only when the modal was opened by following a Kratos-issued recovery link and the referenced flow has been
+  // successfully hydrated. In this mode the email step is bypassed because the flow is already bound to a specific
+  // identity server-side.
+  const isDeepLinkMode = !!flowId && accountRecoveryStatus?.state?.id === flowId;
   return (
     <EuiModal onClose={onClose}>
       <EuiModalHeader>
@@ -167,23 +201,32 @@ export function RecoverAccountModal({ email, onClose }: RecoverAccountModalProps
       </EuiModalHeader>
       <EuiModalBody>
         <EuiForm id="account-recovery-form" component="form">
-          <EuiFormRow label="Email">
-            <EuiFieldText
-              value={userEmail}
-              autoComplete={'email'}
-              type={'email'}
-              required
-              disabled={awaitingRecoveryCode}
-              onChange={(e) => setUserEmail(e.target.value)}
-            />
-          </EuiFormRow>
+          {isDeepLinkMode ? null : (
+            <EuiFormRow label="Email">
+              <EuiFieldText
+                value={userEmail}
+                autoComplete={'email'}
+                type={'email'}
+                required
+                disabled={awaitingRecoveryCode}
+                onChange={(e) => setUserEmail(e.target.value)}
+              />
+            </EuiFormRow>
+          )}
           {awaitingRecoveryCode ? (
-            <EuiFormRow label={'Recovery code'}>
+            <EuiFormRow
+              label={'Recovery code'}
+              helpText={isDeepLinkMode ? 'Enter the code that was issued for your account.' : undefined}
+            >
               <EuiFieldText
                 value={recoveryCode}
                 autoComplete={'off'}
                 type={'text'}
-                append={<EuiButtonIcon iconType="refresh" onClick={onSendRecoveryCode} aria-label="Resend code" />}
+                append={
+                  isDeepLinkMode ? undefined : (
+                    <EuiButtonIcon iconType="refresh" onClick={onSendRecoveryCode} aria-label="Resend code" />
+                  )
+                }
                 onChange={(e) => setRecoveryCode(e.target.value)}
               />
             </EuiFormRow>
@@ -199,7 +242,7 @@ export function RecoverAccountModal({ email, onClose }: RecoverAccountModalProps
             type="submit"
             form="account-recovery-form"
             fill
-            disabled={accountRecoveryStatus?.status === 'pending' || !userEmail?.trim() || !recoveryCode?.trim()}
+            disabled={accountRecoveryStatus?.status === 'pending' || !recoveryCode?.trim()}
             onClick={onRecoverAccount}
             isLoading={accountRecoveryStatus?.status === 'pending'}
           >

components/secutils-docs/static/img/docs/guides/csp/import_url_step3_created.png

@@ -9,7 +9,7 @@ import {
 } from '@elastic/eui';
 import type { FrontendApi, LoginFlow, UiNodeInputAttributes } from '@ory/kratos-client-fetch';
 import type { ChangeEvent } from 'react';
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { Navigate, useNavigate, useSearchParams } from 'react-router';
 
 import { RecoverAccountModal } from './recover_account_modal';
@@ -89,12 +89,34 @@ export function SigninPage() {
 
   const [signinStatus, setSigninStatus] = useState<AsyncData<null, { isPasskey: boolean }> | null>(null);
   const [isResetPasswordModalOpen, setIsResetPasswordModalOpen] = useState(false);
-  const onToggleResetPasswordModal = useCallback(() => {
-    setIsResetPasswordModalOpen((isOpen) => !isOpen);
-  }, []);
+
+  // Kratos lands users on `/signin?recover=1[&flow=<recovery-flow-id>]` after an admin- or user-initiated recovery
+  // flow. Auto-open the modal with the flow ID so the user only has to enter the code.
+  const recoverParam = searchParams.get('recover');
+  const recoveryFlowId = searchParams.get('flow');
+  useEffect(() => {
+    if (recoverParam === '1') {
+      setIsResetPasswordModalOpen(true);
+    }
+  }, [recoverParam]);
+
+  const onCloseResetPasswordModal = useCallback(() => {
+    setIsResetPasswordModalOpen(false);
+    // Clear the deep-link params so refreshing/navigating away no longer reopens the modal and the signin flow's own
+    // `flow` param isn't confused with the recovery one.
+    if (searchParams.has('recover') || (recoverParam === '1' && searchParams.has('flow'))) {
+      searchParams.delete('recover');
+      searchParams.delete('flow');
+      setSearchParams(searchParams);
+    }
+  }, [recoverParam, searchParams, setSearchParams]);
 
   const resetPasswordModal = isResetPasswordModalOpen ? (
-    <RecoverAccountModal onClose={onToggleResetPasswordModal} email={email} />
+    <RecoverAccountModal
+      onClose={onCloseResetPasswordModal}
+      email={email}
+      flowId={recoverParam === '1' ? (recoveryFlowId ?? undefined) : undefined}
+    />
   ) : null;
 
   if (uiState.user) {

components/secutils-docs/static/img/docs/guides/web_scraping/detect_resources_step7_responders_created.png

@@ -0,0 +1,32 @@
+### Clone user by email (creates a sandbox copy + returns Kratos recovery link)
+POST {{host}}/api/users/_clone
+Accept: application/json
+Content-Type: application/json
+Authorization: {{api-credentials}}
+
+{
+  "source": { "email": "demo@secutils.dev" },
+  "destination": { "email": "demo+clone@secutils.dev", "handle": "clone" },
+  "includeHistory": true,
+  "copySubscription": true,
+  "recoveryLinkExpiresIn": "1h"
+}
+
+### Clone user by ID (alternative selector) with explicit handle
+POST {{host}}/api/users/_clone
+Accept: application/json
+Content-Type: application/json
+Authorization: {{api-credentials}}
+
+{
+  "source": { "id": "00000000-0000-0000-0000-000000000001" },
+  "destination": {
+    "email": "support+u123@secutils.dev",
+    "handle": "supportu123"
+  }
+}
+
+### Remove the clone by ID (sibling of POST /api/users/remove)
+DELETE {{host}}/api/users/{{user-id}}
+Accept: application/json
+Authorization: {{api-credentials}}

components/secutils-docs/static/img/docs/guides/webhooks/json_step2_form.png

@@ -31,7 +31,7 @@ password = { enabled = true }
 webauthn = { enabled = true, config = { passwordless = true, rp = { display_name = "Secutils.dev", id = "localhost", origin = "http://localhost:7171" } } }
 
 [selfservice.flows]
-recovery = { enabled = true, lifespan = "15m", use = "code", notify_unknown_recipients = false, after = { hooks = [{  hook = "revoke_active_sessions" }] } }
+recovery = { enabled = true, lifespan = "15m", use = "code", ui_url = "http://localhost:7171/signin?recover=1", notify_unknown_recipients = false, after = { hooks = [{  hook = "revoke_active_sessions" }] } }
 settings = { privileged_session_max_age = "15m" }
 verification = { enabled = true }
 

components/secutils-docs/static/img/docs/guides/webhooks/json_step3_created.png

@@ -29,7 +29,7 @@ password = { enabled = true }
 webauthn = { enabled = true, config = { passwordless = true, rp = { display_name = "Secutils.dev", id = "localhost", origin = "http://localhost:7171" } } }
 
 [selfservice.flows]
-recovery = { enabled = true, lifespan = "15m", use = "code", notify_unknown_recipients = false, after = { hooks = [{  hook = "revoke_active_sessions" }] } }
+recovery = { enabled = true, lifespan = "15m", use = "code", ui_url = "http://127.0.0.1:7171/signin?recover=1", notify_unknown_recipients = false, after = { hooks = [{  hook = "revoke_active_sessions" }] } }
 settings = { privileged_session_max_age = "15m" }
 verification = { enabled = true }