refactor: address review feedback on getMFAChallenge

- Return the raw challenge Document from the server-only endpoint
  instead of manually rebuilding it, aliasing code -> secret first.
  Response models already filter to only their declared rules, so the
  manual reconstruction was redundant.
- Replace the /docs/references/... markdown path in the SDK Method
  description with an inline string. Every other inline-description
  endpoint in this codebase (Console/Variables/Get.php,
  Console/Scopes/*, Project OAuth2 config, etc.) is internal/admin-only
  and has no public docs page -- same situation here, so no markdown
  file should be referenced. This also fixes the CI spec-generation
  failure, which was failing because that file never existed.
- MFAChallengeSecret now extends MFAChallenge and only adds the
  `secret` rule, instead of duplicating all four base fields. Mirrors
  the EphemeralKey/Key relationship already in this codebase.
- Extend testMFACustomChallenge per review: assert a client session
  (no API key) gets 401 from the server endpoint, assert an incorrect
  otp is rejected before the real one is used, and assert the verify
  response's `secret` field comes back empty for a non-privileged
  caller (Session already marks it `sensitive`; this proves it).

Verified the label() set on Get.php against RecoveryCodes/Get.php --
no audits.* labels needed since those only apply to users.write
(mutating) endpoints, and this one is users.read.
This commit is contained in:
harsh-sikarwar committed 2026-08-08 22:49:37 +05:30
1 parent ffe62dd739
commit 6a55ae49f4
3 files changed
+28 -36

No files matched your search

@@ -10,7 +10,6 @@ use Appwrite\SDK\Method;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\Utopia\Response;
use Utopia\Database\Database;
use Utopia\Database\Document;
use Utopia\Database\Validator\UID;
use Utopia\Platform\Scope\HTTP;
use Utopia\Validator\Text;
@@ -38,7 +37,7 @@ class Get extends Action
namespace: 'users',
group: 'mfa',
name: 'getMFAChallenge',
description: '/docs/references/users/get-mfa-challenge.md',
description: 'Get a custom MFA challenge for a user, including the secret to be delivered through your own channel.',
auth: [AuthType::ADMIN, AuthType::KEY],
responses: [
new SDKResponse(
@@ -73,14 +72,8 @@ class Get extends Action
throw new Exception(Exception::USER_INVALID_TOKEN);
}
$document = new Document([
'$id' => $challenge->getId(),
'$createdAt' => $challenge->getCreatedAt(),
'userId' => $challenge->getAttribute('userId'),
'expire' => $challenge->getAttribute('expire'),
'secret' => $challenge->getAttribute('code'),
]);
$challenge->setAttribute('secret', $challenge->getAttribute('code'));
$response->dynamic($document, Response::MODEL_MFA_CHALLENGE_SECRET);
$response->dynamic($challenge, Response::MODEL_MFA_CHALLENGE_SECRET);
}
}
@@ -3,37 +3,14 @@
namespace Appwrite\Utopia\Response\Model;
use Appwrite\Utopia\Response;
use Appwrite\Utopia\Response\Model;
class MFAChallengeSecret extends Model
class MFAChallengeSecret extends MFAChallenge
{
public function __construct()
{
parent::__construct();
$this
->addRule('$id', [
'type' => self::TYPE_STRING,
'description' => 'Token ID.',
'default' => '',
'example' => 'bb8ea5c16897e',
])
->addRule('$createdAt', [
'type' => self::TYPE_DATETIME,
'description' => 'Token creation date in ISO 8601 format.',
'default' => '',
'example' => self::TYPE_DATETIME_EXAMPLE,
])
->addRule('userId', [
'type' => self::TYPE_STRING,
'description' => 'User ID.',
'default' => '',
'example' => '5e5ea5c168bb8',
])
->addRule('expire', [
'type' => self::TYPE_DATETIME,
'description' => 'Token expiration date in ISO 8601 format.',
'default' => '',
'example' => self::TYPE_DATETIME_EXAMPLE,
])
->addRule('secret', [
'type' => self::TYPE_STRING,
'description' => 'Challenge secret to be delivered to the end user through a custom channel.',
@@ -4289,6 +4289,14 @@ final class AccountCustomClientTest extends Scope
$challengeId = $challenge['body']['$id'];
$userId = $challenge['body']['userId'];
// Test FAILURE: a client session (no API key) must not be able to read the secret
$clientSecretResponse = $this->client->call(Client::METHOD_GET, '/users/' . $userId . '/mfa/challenges/' . $challengeId, array_merge([
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
], $this->getHeaders()));
$this->assertEquals(401, $clientSecretResponse['headers']['status-code']);
// Server SDK reads the raw secret via the server-only endpoint
$secretResponse = $this->client->call(Client::METHOD_GET, '/users/' . $userId . '/mfa/challenges/' . $challengeId, [
'content-type' => 'application/json',
@@ -4300,6 +4308,17 @@ final class AccountCustomClientTest extends Scope
$this->assertNotEmpty($secretResponse['body']['secret']);
$secret = $secretResponse['body']['secret'];
// Test FAILURE: verifying with a random/incorrect otp before the real one is used
$wrongFirst = $this->client->call(Client::METHOD_PUT, '/account/mfa/challenge', array_merge([
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
], $this->getHeaders()), [
'challengeId' => $challengeId,
'otp' => 'random-incorrect-code'
]);
$this->assertEquals(401, $wrongFirst['headers']['status-code']);
// Test SUCCESS: Verify with the correct secret
$verification = $this->client->call(Client::METHOD_PUT, '/account/mfa/challenge', array_merge([
'content-type' => 'application/json',
@@ -4312,6 +4331,9 @@ final class AccountCustomClientTest extends Scope
$this->assertEquals(200, $verification['headers']['status-code']);
$this->assertArrayHasKey('factors', $verification['body']);
$this->assertContains('custom', $verification['body']['factors']);
// The session response must never leak the MFA secret back to a non-privileged/non-key caller
$this->assertArrayHasKey('secret', $verification['body']);
$this->assertEmpty($verification['body']['secret']);
// Test that the challenge was consumed (can't verify the same one twice)
$reuse = $this->client->call(Client::METHOD_PUT, '/account/mfa/challenge', array_merge([