From 875c25596f6274a4947dbfcb7cf7d587b6bb5c0c Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Sun, 9 Aug 2026 00:24:13 +1200 Subject: [PATCH 01/11] fix(databases): type-guard the deprecated databases path like every other one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The legacy /v1/databases path was exempt from the by-id type guard while its own list stayed type-filtered, so the two disagreed about which databases exist: GET /v1/databases/{id} answered for a DocumentsDB or VectorsDB database that GET /v1/databases had never listed, and /collections on one then queried database_{sequence} — a table shaped for another product — and 500'd. The guard and the list filter already share getAllowedDatabaseTypes() precisely so they cannot diverge; the legacy path just opted out of it. Removing the exemption and giving legacy the mirror of TablesDB's set makes them agree. TablesDB and legacy are the same product either side of a rename, so each serves both types and refuses the other two — a caller migrating between the two paths never loses a database, and DocumentsDB and VectorsDB now get a typed not-found instead of an opaque 500. Fixes DAT-2219 Co-Authored-By: Claude Fable 5 --- .../Databases/Http/Databases/Action.php | 25 ++-- .../Databases/DatabaseTypeMismatchTest.php | 106 ++++++++++++++- .../LegacyCollectionsRefusalTest.php | 125 ++++++++++++++++++ 3 files changed, 238 insertions(+), 18 deletions(-) create mode 100644 tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php diff --git a/src/Appwrite/Platform/Modules/Databases/Http/Databases/Action.php b/src/Appwrite/Platform/Modules/Databases/Http/Databases/Action.php index 9ea4f11ccb..b30d45aff9 100644 --- a/src/Appwrite/Platform/Modules/Databases/Http/Databases/Action.php +++ b/src/Appwrite/Platform/Modules/Databases/Http/Databases/Action.php @@ -26,10 +26,10 @@ class Action extends AppwriteAction * the list filter ({@see getDatabaseTypeQueryFilters()}) and the by-id guard * ({@see isDatabaseTypeMismatch()}) so they cannot diverge. * - * TablesDB is the compatibility successor to the legacy databases API, so it - * also serves legacy-typed databases; the other product APIs are scoped to - * their own type. Every database carries a non-null `type` (set on create - * and backfilled to 'legacy' by migration V23), so null is not represented. + * TablesDB and the legacy databases API are the same product either side of a + * rename, so each serves both types; DocumentsDB and VectorsDB are scoped to + * their own. Every database carries a non-null `type` (set on create and + * backfilled to 'legacy' by migration V23), so null is not represented. * * @return string[] */ @@ -37,22 +37,23 @@ class Action extends AppwriteAction { return match ($this->getDatabaseType()) { DATABASE_TYPE_TABLESDB => [DATABASE_TYPE_TABLESDB, DATABASE_TYPE_LEGACY], + DATABASE_TYPE_LEGACY => [DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB], default => [$this->getDatabaseType()], }; } /** - * A database resolved by id on a product-DB path must be one of the path's - * allowed types; otherwise it is treated as not-found rather than proceeding - * to a type-mismatched backend operation that surfaces as an opaque 500. The - * legacy /v1/databases API is intentionally not type-guarded. + * A database resolved by id must be one of the path's allowed types; otherwise + * it is treated as not-found rather than proceeding to a type-mismatched backend + * operation that surfaces as an opaque 500. + * + * The legacy path was previously exempt, which left it resolving by id what its + * own list refused to return: `GET /v1/databases/{id}` answered for a DocumentsDB + * or VectorsDB database that `GET /v1/databases` had never listed, and + * `/collections` on one then 500'd against a table shaped for another product. */ protected function isDatabaseTypeMismatch(Document $database): bool { - if ($this->getDatabaseType() === DATABASE_TYPE_LEGACY) { - return false; - } - return !in_array($database->getAttribute('type', ''), $this->getAllowedDatabaseTypes(), true); } diff --git a/tests/unit/Platform/Modules/Databases/DatabaseTypeMismatchTest.php b/tests/unit/Platform/Modules/Databases/DatabaseTypeMismatchTest.php index 68da1db3fa..a78e2391c9 100644 --- a/tests/unit/Platform/Modules/Databases/DatabaseTypeMismatchTest.php +++ b/tests/unit/Platform/Modules/Databases/DatabaseTypeMismatchTest.php @@ -5,8 +5,10 @@ declare(strict_types=1); namespace Tests\Unit\Platform\Modules\Databases; use Appwrite\Platform\Modules\Databases\Http\Databases\Action; +use Appwrite\Platform\Modules\Databases\Http\Databases\XList; use PHPUnit\Framework\TestCase; use Utopia\Database\Document; +use Utopia\Database\Query; final class DatabaseTypeMismatchTest extends TestCase { @@ -80,9 +82,73 @@ final class DatabaseTypeMismatchTest extends TestCase $this->assertTrue($vectors->exposeMismatch(new Document(['type' => DATABASE_TYPE_LEGACY]))); } - public function testLegacyDatabasesPathIsNeverTypeGuarded(): void + /** + * The legacy path is the mirror of the TablesDB one: same product either side of + * a rename, so it serves both types and refuses the other two. + * + * It was previously exempt from the guard entirely, which let it resolve by id + * what its own list refused to return — `GET /v1/databases/{id}` answered for a + * DocumentsDB or VectorsDB database that `GET /v1/databases` never listed, and + * `/collections` on one then 500'd against a table shaped for another product. + */ + public function testLegacyPathServesTablesdbAndRefusesTheOtherProducts(): void { - $legacy = new class () extends Action { + $legacy = $this->legacyAction(); + + $this->assertSame([DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB], $legacy->exposeAllowedTypes()); + + $this->assertFalse($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_LEGACY]))); + $this->assertFalse($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_TABLESDB]))); + $this->assertTrue($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_DOCUMENTSDB]))); + $this->assertTrue($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_VECTORSDB]))); + $this->assertTrue($legacy->exposeMismatch(new Document([]))); + } + + /** + * The by-id guard and the list filter must select the same set, or the two + * disagree about which databases exist. + */ + public function testLegacyListFilterAndByIdGuardSelectTheSameSet(): void + { + $legacy = $this->legacyAction(); + $filters = $legacy->exposeQueryFilters(); + + $this->assertCount(1, $filters); + $this->assertSame('type', $filters[0]->getAttribute()); + + $listed = $filters[0]->getValues(); + $this->assertSame($legacy->exposeAllowedTypes(), $listed); + + foreach ([DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB, DATABASE_TYPE_DOCUMENTSDB, DATABASE_TYPE_VECTORSDB] as $type) { + $this->assertSame( + in_array($type, $listed, true), + !$legacy->exposeMismatch(new Document(['type' => $type])), + "list and get disagree about whether a '{$type}' database exists on /v1/databases", + ); + } + } + + /** + * The two paths over the same product must accept the same databases, so a caller + * migrating from /v1/databases to /v1/tablesdb never loses one. + */ + public function testLegacyAndTablesdbPathsAcceptTheSameDatabases(): void + { + $legacy = $this->legacyAction(); + $tablesdb = $this->tablesdbAction(); + + foreach ([DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB, DATABASE_TYPE_DOCUMENTSDB, DATABASE_TYPE_VECTORSDB] as $type) { + $this->assertSame( + $tablesdb->exposeMismatch(new Document(['type' => $type])), + $legacy->exposeMismatch(new Document(['type' => $type])), + "the deprecated and successor paths disagree about a '{$type}' database", + ); + } + } + + private function legacyAction(): object + { + $legacy = new class () extends XList { public static function getName(): string { return 'testLegacyTypeGuard'; @@ -92,11 +158,39 @@ final class DatabaseTypeMismatchTest extends TestCase { return $this->isDatabaseTypeMismatch($database); } + + /** @return string[] */ + public function exposeAllowedTypes(): array + { + return $this->getAllowedDatabaseTypes(); + } + + /** @return Query[] */ + public function exposeQueryFilters(): array + { + return $this->getDatabaseTypeQueryFilters(); + } }; $legacy->setHttpPath('/v1/databases/:databaseId/collections'); - $this->assertFalse($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_LEGACY]))); - $this->assertFalse($legacy->exposeMismatch(new Document([]))); - $this->assertFalse($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_TABLESDB]))); - $this->assertFalse($legacy->exposeMismatch(new Document(['type' => DATABASE_TYPE_DOCUMENTSDB]))); + + return $legacy; + } + + private function tablesdbAction(): object + { + $tablesdb = new class () extends Action { + public static function getName(): string + { + return 'testTablesdbMirrorGuard'; + } + + public function exposeMismatch(Document $database): bool + { + return $this->isDatabaseTypeMismatch($database); + } + }; + $tablesdb->setHttpPath('/v1/tablesdb/:databaseId/tables'); + + return $tablesdb; } } diff --git a/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php b/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php new file mode 100644 index 0000000000..42aee62bbf --- /dev/null +++ b/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php @@ -0,0 +1,125 @@ + $attributes + * @return array{reached: bool} + */ + private function listCollections(array $attributes): array + { + $reached = false; + + $dbForProject = $this->createMock(Database::class); + $dbForProject + ->method('getDocument') + ->willReturn(new Document(['$id' => 'db', '$sequence' => '7', ...$attributes])); + $dbForProject + ->method('find') + ->willReturnCallback(function () use (&$reached): array { + $reached = true; + + return []; + }); + $dbForProject + ->method('count') + ->willReturnCallback(function () use (&$reached): int { + $reached = true; + + return 0; + }); + + (new XList())->action( + 'db', + [], + '', + false, + $this->createMock(UtopiaResponse::class), + $dbForProject, + new Authorization(), + ); + + return ['reached' => $reached]; + } + + public function testAVectorsDatabaseIsRefusedBeforeTheBackendIsQueried(): void + { + try { + $this->listCollections(['type' => DATABASE_TYPE_VECTORSDB]); + $this->fail('Listing collections of a VectorsDB database on /v1/databases must be refused, not served.'); + } catch (Exception $exception) { + $this->assertSame(Exception::DATABASE_NOT_FOUND, $exception->getType()); + } + } + + public function testADocumentsDatabaseIsRefusedBeforeTheBackendIsQueried(): void + { + try { + $this->listCollections(['type' => DATABASE_TYPE_DOCUMENTSDB]); + $this->fail('Listing collections of a DocumentsDB database on /v1/databases must be refused, not served.'); + } catch (Exception $exception) { + $this->assertSame(Exception::DATABASE_NOT_FOUND, $exception->getType()); + } + } + + /** + * The mismatched call must not reach `database_{sequence}` at all — that query is + * where the 500 came from. + */ + public function testTheRefusedCallNeverReachesTheBackend(): void + { + foreach ([DATABASE_TYPE_VECTORSDB, DATABASE_TYPE_DOCUMENTSDB] as $type) { + $reached = true; + + try { + $reached = $this->listCollections(['type' => $type])['reached']; + } catch (Exception) { + $reached = false; + } + + $this->assertFalse($reached, "a '{$type}' database must be refused before database_{sequence} is queried"); + } + } + + /** + * The guard must not over-refuse: the products this path really serves still reach + * the backend. + */ + public function testTheServedTypesStillReachTheBackend(): void + { + foreach ([DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB] as $type) { + $this->assertTrue( + $this->listCollections(['type' => $type])['reached'], + "a '{$type}' database must still be served by /v1/databases/{id}/collections", + ); + } + } +} From 1344f96a8390d83c3796671bebbab0c4656bf1eb Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Sun, 9 Aug 2026 00:29:38 +1200 Subject: [PATCH 02/11] test(databases): keep the reachability flag alive across the refusal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The flag lived on the call's return value, but the call under test throws on the path the assertion cares about, so it never came back and the catch decided the outcome on its own — the assertion passed whether or not the backend had been queried. Moving it onto the instance keeps what the action did before it threw. Also takes Rector's createStub for the response, which is never asserted on. Co-Authored-By: Claude Fable 5 --- .../LegacyCollectionsRefusalTest.php | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php b/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php index 42aee62bbf..4fd21e5c8a 100644 --- a/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php +++ b/tests/unit/Platform/Modules/Databases/LegacyCollectionsRefusalTest.php @@ -23,6 +23,15 @@ use Utopia\Database\Validator\Authorization; */ final class LegacyCollectionsRefusalTest extends TestCase { + /** + * Whether the action queried `database_{sequence}`. + * + * An instance property rather than a return value, because the call under test + * throws on the path this suite cares about — a returned flag would be lost with + * the stack, leaving the assertion to pass on the catch alone. + */ + private bool $reached = false; + protected function setUp(): void { parent::setUp(); @@ -32,11 +41,10 @@ final class LegacyCollectionsRefusalTest extends TestCase /** * @param array $attributes - * @return array{reached: bool} */ - private function listCollections(array $attributes): array + private function listCollections(array $attributes): void { - $reached = false; + $this->reached = false; $dbForProject = $this->createMock(Database::class); $dbForProject @@ -44,15 +52,15 @@ final class LegacyCollectionsRefusalTest extends TestCase ->willReturn(new Document(['$id' => 'db', '$sequence' => '7', ...$attributes])); $dbForProject ->method('find') - ->willReturnCallback(function () use (&$reached): array { - $reached = true; + ->willReturnCallback(function (): array { + $this->reached = true; return []; }); $dbForProject ->method('count') - ->willReturnCallback(function () use (&$reached): int { - $reached = true; + ->willReturnCallback(function (): int { + $this->reached = true; return 0; }); @@ -62,12 +70,10 @@ final class LegacyCollectionsRefusalTest extends TestCase [], '', false, - $this->createMock(UtopiaResponse::class), + $this->createStub(UtopiaResponse::class), $dbForProject, new Authorization(), ); - - return ['reached' => $reached]; } public function testAVectorsDatabaseIsRefusedBeforeTheBackendIsQueried(): void @@ -92,20 +98,18 @@ final class LegacyCollectionsRefusalTest extends TestCase /** * The mismatched call must not reach `database_{sequence}` at all — that query is - * where the 500 came from. + * where the 500 came from. Refusing and querying anyway would still 500. */ public function testTheRefusedCallNeverReachesTheBackend(): void { foreach ([DATABASE_TYPE_VECTORSDB, DATABASE_TYPE_DOCUMENTSDB] as $type) { - $reached = true; - try { - $reached = $this->listCollections(['type' => $type])['reached']; + $this->listCollections(['type' => $type]); } catch (Exception) { - $reached = false; + // The refusal is expected here; what it did on the way is the assertion. } - $this->assertFalse($reached, "a '{$type}' database must be refused before database_{sequence} is queried"); + $this->assertFalse($this->reached, "a '{$type}' database must be refused before database_{sequence} is queried"); } } @@ -116,8 +120,10 @@ final class LegacyCollectionsRefusalTest extends TestCase public function testTheServedTypesStillReachTheBackend(): void { foreach ([DATABASE_TYPE_LEGACY, DATABASE_TYPE_TABLESDB] as $type) { + $this->listCollections(['type' => $type]); + $this->assertTrue( - $this->listCollections(['type' => $type])['reached'], + $this->reached, "a '{$type}' database must still be served by /v1/databases/{id}/collections", ); } From eb632575844f6ebdb5249a65202403174dd397f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Sat, 8 Aug 2026 21:00:14 +0200 Subject: [PATCH 03/11] fix(oauth2): derive emailVerification from provider, not assumption The OAuth2 callback hardcoded 'emailVerification' => true for every new user, on the assumption that "email should already be authenticated by OAuth2 provider". That assumption does not hold: several adapters report no verification signal at all, and many inferred verification from !empty($email) -- conflating "the provider returned a string" with "the provider vouched for the address". $isVerified was already computed and already trusted for the account-linking checks; it just never reached the attribute. - Set emailVerification from $isVerified when creating an OAuth2 user. - Set it on the branch where an existing account gains an email, which previously left the flag untouched against a brand-new address. OR'd with the current value so an already-verified user is never downgraded. - Yahoo: read the email_verified claim it advertises on its OIDC userinfo endpoint. - Bitly: walk emails[].is_verified instead of returning a bare true. - X: read data.confirmed_email directly rather than via getUserEmail(). - Amazon, Box, Etsy, Facebook, Figma, Kick, Microsoft, Notion, Slack, Stripe, Tradeshift, Twitch, Yammer: return false. None of these expose a usable signal at the endpoint the adapter calls, so unverified is the safe default. Tradeshift was additionally testing the whole user array rather than an email. Slack and Twitch do expose email_verified, but only on OIDC endpoints the adapters do not call. Migrating changes the source field for getUserID(), which is the provider UID join key on identities, so it needs its own change with a migration plan. Co-Authored-By: Claude Opus 5 (1M context) --- app/controllers/api/account.php | 10 +++++++--- src/Appwrite/Auth/OAuth2/Amazon.php | 5 ++--- src/Appwrite/Auth/OAuth2/Bitly.php | 10 +++++++++- src/Appwrite/Auth/OAuth2/Box.php | 5 ++--- src/Appwrite/Auth/OAuth2/Etsy.php | 5 ++--- src/Appwrite/Auth/OAuth2/Facebook.php | 5 ++--- src/Appwrite/Auth/OAuth2/Figma.php | 5 ++--- src/Appwrite/Auth/OAuth2/Kick.php | 3 ++- src/Appwrite/Auth/OAuth2/Microsoft.php | 5 ++--- src/Appwrite/Auth/OAuth2/Notion.php | 5 ++--- src/Appwrite/Auth/OAuth2/Slack.php | 5 ++--- src/Appwrite/Auth/OAuth2/Stripe.php | 5 ++--- src/Appwrite/Auth/OAuth2/Tradeshift.php | 5 ++--- src/Appwrite/Auth/OAuth2/Twitch.php | 5 ++--- src/Appwrite/Auth/OAuth2/X.php | 5 ++++- src/Appwrite/Auth/OAuth2/Yahoo.php | 8 +++++--- src/Appwrite/Auth/OAuth2/Yammer.php | 5 ++--- 17 files changed, 51 insertions(+), 45 deletions(-) diff --git a/app/controllers/api/account.php b/app/controllers/api/account.php index 7e2b650c6a..35ebf065e0 100644 --- a/app/controllers/api/account.php +++ b/app/controllers/api/account.php @@ -1807,8 +1807,8 @@ Http::get('/v1/account/sessions/oauth2/:provider/redirect') Permission::delete(Role::user($userId)), ], 'email' => $email, - 'emailVerification' => true, - 'status' => true, // Email should already be authenticated by OAuth2 provider + 'emailVerification' => $isVerified, // Trust the provider's userinfo claim, not the mere fact an email was returned + 'status' => true, 'password' => null, 'hash' => $proofForPassword->getHash()->getName(), 'hashOptions' => $proofForPassword->getHash()->getOptions(), @@ -1866,6 +1866,8 @@ Http::get('/v1/account/sessions/oauth2/:provider/redirect') 'emailIsFree' => null, ]; + $isVerified = $oauth2->isEmailVerified($accessToken); + try { $parsedEmail = new Email($providerEmail); $canonical = $parsedEmail->getCanonical(); @@ -1874,7 +1876,7 @@ Http::get('/v1/account/sessions/oauth2/:provider/redirect') || ($plan['supportsCanonicalEmailValidation'] ?? false) ) && ($project->getAttribute('auths', [])['canonicalEmails'] ?? false) - && $oauth2->isEmailVerified($accessToken); + && $isVerified; $email = $canonicalize ? $canonical : $providerEmail; $emails = array_values(array_unique([$email, $providerEmail])); $emailMetadata = [ @@ -1913,6 +1915,8 @@ Http::get('/v1/account/sessions/oauth2/:provider/redirect') } $user->setAttribute('email', $email); + // Never downgrade an already-verified user; only ever promote to verified + $user->setAttribute('emailVerification', $user->getAttribute('emailVerification', false) || $isVerified); $user->setAttribute('emailCanonical', $emailMetadata['emailCanonical']); $user->setAttribute('emailIsCanonical', $emailMetadata['emailIsCanonical']); $user->setAttribute('emailIsCorporate', $emailMetadata['emailIsCorporate']); diff --git a/src/Appwrite/Auth/OAuth2/Amazon.php b/src/Appwrite/Auth/OAuth2/Amazon.php index 2fa3f4cfe9..7a7f1b3e9d 100644 --- a/src/Appwrite/Auth/OAuth2/Amazon.php +++ b/src/Appwrite/Auth/OAuth2/Amazon.php @@ -149,9 +149,8 @@ class Amazon extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Bitly.php b/src/Appwrite/Auth/OAuth2/Bitly.php index 290876a8cb..e6f062e086 100644 --- a/src/Appwrite/Auth/OAuth2/Bitly.php +++ b/src/Appwrite/Auth/OAuth2/Bitly.php @@ -157,7 +157,15 @@ class Bitly extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - return true; + $user = $this->getUser($accessToken); + + foreach ($user['emails'] ?? [] as $email) { + if (($email['is_verified'] ?? false) === true) { + return true; + } + } + + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Box.php b/src/Appwrite/Auth/OAuth2/Box.php index e88c165833..7a15ab325f 100644 --- a/src/Appwrite/Auth/OAuth2/Box.php +++ b/src/Appwrite/Auth/OAuth2/Box.php @@ -150,9 +150,8 @@ class Box extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Etsy.php b/src/Appwrite/Auth/OAuth2/Etsy.php index c878945740..3a6e66773f 100644 --- a/src/Appwrite/Auth/OAuth2/Etsy.php +++ b/src/Appwrite/Auth/OAuth2/Etsy.php @@ -158,9 +158,8 @@ class Etsy extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Facebook.php b/src/Appwrite/Auth/OAuth2/Facebook.php index 90fe8e7388..ab1842a80e 100644 --- a/src/Appwrite/Auth/OAuth2/Facebook.php +++ b/src/Appwrite/Auth/OAuth2/Facebook.php @@ -131,9 +131,8 @@ class Facebook extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Figma.php b/src/Appwrite/Auth/OAuth2/Figma.php index b5e53cbed4..da29312641 100644 --- a/src/Appwrite/Auth/OAuth2/Figma.php +++ b/src/Appwrite/Auth/OAuth2/Figma.php @@ -139,9 +139,8 @@ class Figma extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Kick.php b/src/Appwrite/Auth/OAuth2/Kick.php index bf7ff7930d..652bd10efe 100644 --- a/src/Appwrite/Auth/OAuth2/Kick.php +++ b/src/Appwrite/Auth/OAuth2/Kick.php @@ -147,7 +147,8 @@ class Kick extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - return !empty($this->getUserEmail($accessToken)); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Microsoft.php b/src/Appwrite/Auth/OAuth2/Microsoft.php index 19966ec1ac..0d89eeb718 100644 --- a/src/Appwrite/Auth/OAuth2/Microsoft.php +++ b/src/Appwrite/Auth/OAuth2/Microsoft.php @@ -147,9 +147,8 @@ class Microsoft extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Microsoft explicitly does not verify emails in Graph /me, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Notion.php b/src/Appwrite/Auth/OAuth2/Notion.php index c2f1ee98e4..124c09e599 100644 --- a/src/Appwrite/Auth/OAuth2/Notion.php +++ b/src/Appwrite/Auth/OAuth2/Notion.php @@ -137,9 +137,8 @@ class Notion extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Slack.php b/src/Appwrite/Auth/OAuth2/Slack.php index 9c87e45ed6..fac80e9aad 100644 --- a/src/Appwrite/Auth/OAuth2/Slack.php +++ b/src/Appwrite/Auth/OAuth2/Slack.php @@ -131,9 +131,8 @@ class Slack extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // email_verified lives on openid.connect.userInfo, not users.identity; unverified is the safe default until we migrate + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Stripe.php b/src/Appwrite/Auth/OAuth2/Stripe.php index 9d1c9206ad..e5fb530d70 100644 --- a/src/Appwrite/Auth/OAuth2/Stripe.php +++ b/src/Appwrite/Auth/OAuth2/Stripe.php @@ -146,9 +146,8 @@ class Stripe extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Tradeshift.php b/src/Appwrite/Auth/OAuth2/Tradeshift.php index 8d0bfa8784..16d72821bf 100644 --- a/src/Appwrite/Auth/OAuth2/Tradeshift.php +++ b/src/Appwrite/Auth/OAuth2/Tradeshift.php @@ -154,9 +154,8 @@ class Tradeshift extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUser($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Twitch.php b/src/Appwrite/Auth/OAuth2/Twitch.php index ed73054c31..8f4ab1a661 100644 --- a/src/Appwrite/Auth/OAuth2/Twitch.php +++ b/src/Appwrite/Auth/OAuth2/Twitch.php @@ -144,9 +144,8 @@ class Twitch extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // email_verified lives on the OIDC userinfo endpoint, not Helix /users; unverified is the safe default until we migrate + return false; } /** diff --git a/src/Appwrite/Auth/OAuth2/X.php b/src/Appwrite/Auth/OAuth2/X.php index c0789fe343..f6ffe5e972 100644 --- a/src/Appwrite/Auth/OAuth2/X.php +++ b/src/Appwrite/Auth/OAuth2/X.php @@ -142,7 +142,10 @@ class X extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - return !empty($this->getUserEmail($accessToken)); + // X only populates confirmed_email once the address is confirmed, so its presence is the verification signal + $user = $this->getUser($accessToken); + + return !empty($user['data']['confirmed_email']); } /** diff --git a/src/Appwrite/Auth/OAuth2/Yahoo.php b/src/Appwrite/Auth/OAuth2/Yahoo.php index 1a6c6b860d..21ecd9a04d 100644 --- a/src/Appwrite/Auth/OAuth2/Yahoo.php +++ b/src/Appwrite/Auth/OAuth2/Yahoo.php @@ -156,7 +156,9 @@ class Yahoo extends OAuth2 /** * Check if the OAuth email is verified * - * If present, the email is verified. This was verfied through a manual Yahoo sign up process + * Yahoo is an OpenID Connect provider and advertises the `email_verified` + * claim on its userinfo endpoint, so use that instead of merely assuming a + * returned address is confirmed. * * @param string $accessToken * @@ -164,9 +166,9 @@ class Yahoo extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); + $user = $this->getUser($accessToken); - return !empty($email); + return $user['email_verified'] ?? false; } /** diff --git a/src/Appwrite/Auth/OAuth2/Yammer.php b/src/Appwrite/Auth/OAuth2/Yammer.php index 9e1827bc58..0bbe20861f 100644 --- a/src/Appwrite/Auth/OAuth2/Yammer.php +++ b/src/Appwrite/Auth/OAuth2/Yammer.php @@ -133,9 +133,8 @@ class Yammer extends OAuth2 */ public function isEmailVerified(string $accessToken): bool { - $email = $this->getUserEmail($accessToken); - - return !empty($email); + // Provider exposes no email verification signal, so treat as unverified until one is confirmed + return false; } /** From 486e90cc3f29bd6e492e4f9863a85cbfb769e8bb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 9 Aug 2026 03:33:42 +0000 Subject: [PATCH 04/11] fix(events): allow documentsdb and vectorsdb event triggers Event::generateEvents already emits documentsdb.* and vectorsdb.* prefixes for those database types, but the public allowlist only accepted databases/tablesdb. Mirror the tablesdb config so functions and webhooks can subscribe to DocumentsDB and VectorsDB events. Co-authored-by: Chirag Aggarwal --- app/config/events.php | 146 ++++++++++++++++++ tests/unit/Event/EventTest.php | 10 ++ .../Event/Validator/EventValidatorTest.php | 48 ++++++ .../Validator/FunctionEventValidatorTest.php | 12 ++ 4 files changed, 216 insertions(+) diff --git a/app/config/events.php b/app/config/events.php index b551e2d6e9..b9eb849688 100644 --- a/app/config/events.php +++ b/app/config/events.php @@ -311,6 +311,152 @@ return [ '$description' => 'This event triggers when a database is deleted.', ], ], + 'documentsdb' => [ + '$model' => Response::MODEL_DATABASE, + '$resource' => true, + '$description' => 'This event triggers on any DocumentsDB database event.', + 'collections' => [ + '$model' => Response::MODEL_COLLECTION, + '$resource' => true, + '$description' => 'This event triggers on any collection event.', + 'documents' => [ + '$model' => Response::MODEL_DOCUMENT, + '$resource' => true, + '$description' => 'This event triggers on any documents event.', + 'create' => [ + '$description' => 'This event triggers when a document is created.', + ], + 'update' => [ + '$description' => 'This event triggers when a document is updated.' + ], + 'upsert' => [ + '$description' => 'This event triggers when a document is upserted.', + ], + 'delete' => [ + '$description' => 'This event triggers when a document is deleted.' + ], + ], + 'indexes' => [ + '$model' => Response::MODEL_INDEX, + '$resource' => true, + '$description' => 'This event triggers on any indexes event.', + 'create' => [ + '$description' => 'This event triggers when an index is created.', + ], + 'delete' => [ + '$description' => 'This event triggers when an index is deleted.' + ], + 'update' => [ + '$description' => 'This event triggers when an index is updated.', + ], + ], + 'attributes' => [ + '$model' => Response::MODEL_ATTRIBUTE, + '$resource' => true, + '$description' => 'This event triggers on any attributes event.', + 'create' => [ + '$description' => 'This event triggers when an attribute is created.', + ], + 'update' => [ + '$description' => 'This event triggers when an attribute is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when an attribute is deleted.' + ] + ], + 'create' => [ + '$description' => 'This event triggers when a collection is created.' + ], + 'update' => [ + '$description' => 'This event triggers when a collection is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when a collection is deleted.', + ], + ], + 'create' => [ + '$description' => 'This event triggers when a database is created.' + ], + 'update' => [ + '$description' => 'This event triggers when a database is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when a database is deleted.', + ], + ], + 'vectorsdb' => [ + '$model' => Response::MODEL_DATABASE, + '$resource' => true, + '$description' => 'This event triggers on any VectorsDB database event.', + 'collections' => [ + '$model' => Response::MODEL_COLLECTION, + '$resource' => true, + '$description' => 'This event triggers on any collection event.', + 'documents' => [ + '$model' => Response::MODEL_DOCUMENT, + '$resource' => true, + '$description' => 'This event triggers on any documents event.', + 'create' => [ + '$description' => 'This event triggers when a document is created.', + ], + 'update' => [ + '$description' => 'This event triggers when a document is updated.' + ], + 'upsert' => [ + '$description' => 'This event triggers when a document is upserted.', + ], + 'delete' => [ + '$description' => 'This event triggers when a document is deleted.' + ], + ], + 'indexes' => [ + '$model' => Response::MODEL_INDEX, + '$resource' => true, + '$description' => 'This event triggers on any indexes event.', + 'create' => [ + '$description' => 'This event triggers when an index is created.', + ], + 'delete' => [ + '$description' => 'This event triggers when an index is deleted.' + ], + 'update' => [ + '$description' => 'This event triggers when an index is updated.', + ], + ], + 'attributes' => [ + '$model' => Response::MODEL_ATTRIBUTE, + '$resource' => true, + '$description' => 'This event triggers on any attributes event.', + 'create' => [ + '$description' => 'This event triggers when an attribute is created.', + ], + 'update' => [ + '$description' => 'This event triggers when an attribute is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when an attribute is deleted.' + ] + ], + 'create' => [ + '$description' => 'This event triggers when a collection is created.' + ], + 'update' => [ + '$description' => 'This event triggers when a collection is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when a collection is deleted.', + ], + ], + 'create' => [ + '$description' => 'This event triggers when a database is created.' + ], + 'update' => [ + '$description' => 'This event triggers when a database is updated.', + ], + 'delete' => [ + '$description' => 'This event triggers when a database is deleted.', + ], + ], 'buckets' => [ '$model' => Response::MODEL_BUCKET, '$resource' => true, diff --git a/tests/unit/Event/EventTest.php b/tests/unit/Event/EventTest.php index 6f15c80b9a..04f3f7749f 100644 --- a/tests/unit/Event/EventTest.php +++ b/tests/unit/Event/EventTest.php @@ -216,5 +216,15 @@ final class EventTest extends TestCase $this->assertContains('documentsdb.factory-db.collections.assembly.documents.doc-123.update', $documentsDbEvents); $this->assertNotContains('documentsdb.factory-db.tables.assembly.rows.doc-123.update', $documentsDbEvents); $this->assertNotContains('databases.factory-db.collections.assembly.documents.doc-123.update', $documentsDbEvents); + + $vectorsDb = new Document(['type' => 'vectorsdb']); + $vectorsDbEvents = Event::generateEvents('databases.[databaseId].collections.[collectionId].documents.[documentId].update', [ + 'databaseId' => 'factory-db', + 'collectionId' => 'assembly', + 'documentId' => 'doc-123', + ], $vectorsDb); + $this->assertContains('vectorsdb.factory-db.collections.assembly.documents.doc-123.update', $vectorsDbEvents); + $this->assertNotContains('vectorsdb.factory-db.tables.assembly.rows.doc-123.update', $vectorsDbEvents); + $this->assertNotContains('databases.factory-db.collections.assembly.documents.doc-123.update', $vectorsDbEvents); } } diff --git a/tests/unit/Event/Validator/EventValidatorTest.php b/tests/unit/Event/Validator/EventValidatorTest.php index 3af99bc3c2..ab95e1c7b8 100644 --- a/tests/unit/Event/Validator/EventValidatorTest.php +++ b/tests/unit/Event/Validator/EventValidatorTest.php @@ -79,6 +79,50 @@ final class EventValidatorTest extends TestCase $this->assertTrue($this->object->isValid('tablesdb.books.tables.chapters')); $this->assertTrue($this->object->isValid('tablesdb.books.tables.*')); $this->assertTrue($this->object->isValid('tablesdb.books.tables.chapters.columns.name.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.prolog')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.*')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.*.documents.prolog.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.*.documents.prolog')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.*.documents.*')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.chapters.documents.prolog')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.chapters.documents.*')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*.documents.prolog.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*.documents.prolog')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*.documents.*')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*')); + $this->assertTrue($this->object->isValid('documentsdb.*')); + $this->assertTrue($this->object->isValid('documentsdb.books')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.*')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.attributes.name.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.prolog')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.*')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.*.documents.prolog.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.*.documents.prolog')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.*.documents.*')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.chapters.documents.prolog')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.chapters.documents.*')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*.documents.prolog.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*.documents.prolog')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*.documents.*')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*')); + $this->assertTrue($this->object->isValid('vectorsdb.*')); + $this->assertTrue($this->object->isValid('vectorsdb.books')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.*')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.attributes.name.create')); $this->assertTrue($this->object->isValid('functions.*')); $this->assertTrue($this->object->isValid('buckets.*')); $this->assertTrue($this->object->isValid('teams.*')); @@ -97,6 +141,10 @@ final class EventValidatorTest extends TestCase $this->assertFalse($this->object->isValid('tables.*.rows.*.unknown')); $this->assertFalse($this->object->isValid('tablesdb.books.collections.chapters.documents.prolog.create')); $this->assertFalse($this->object->isValid('tablesdb.books.tables.chapters.rows.prolog.unknown')); + $this->assertFalse($this->object->isValid('documentsdb.books.tables.chapters.rows.prolog.create')); + $this->assertFalse($this->object->isValid('documentsdb.books.collections.chapters.documents.prolog.unknown')); + $this->assertFalse($this->object->isValid('vectorsdb.books.tables.chapters.rows.prolog.create')); + $this->assertFalse($this->object->isValid('vectorsdb.books.collections.chapters.documents.prolog.unknown')); $this->assertFalse($this->object->isValid('users.torsten.unknown')); $this->assertFalse($this->object->isValid('users.torsten.delete.email')); $this->assertFalse($this->object->isValid('teams.*.memberships.*.update.unknown')); diff --git a/tests/unit/Event/Validator/FunctionEventValidatorTest.php b/tests/unit/Event/Validator/FunctionEventValidatorTest.php index 3fbbbb905b..59e08eb23a 100644 --- a/tests/unit/Event/Validator/FunctionEventValidatorTest.php +++ b/tests/unit/Event/Validator/FunctionEventValidatorTest.php @@ -62,6 +62,16 @@ final class FunctionEventValidatorTest extends TestCase $this->assertTrue($this->object->isValid('tablesdb.*.tables.*.rows.*.create')); $this->assertTrue($this->object->isValid('tablesdb.*.tables.*')); $this->assertTrue($this->object->isValid('tablesdb.*')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('documentsdb.books.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('documentsdb.*.collections.*')); + $this->assertTrue($this->object->isValid('documentsdb.*')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.prolog.create')); + $this->assertTrue($this->object->isValid('vectorsdb.books.collections.chapters.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*.documents.*.create')); + $this->assertTrue($this->object->isValid('vectorsdb.*.collections.*')); + $this->assertTrue($this->object->isValid('vectorsdb.*')); $this->assertTrue($this->object->isValid('buckets.*')); $this->assertTrue($this->object->isValid('teams.*')); $this->assertTrue($this->object->isValid('users.*')); @@ -78,6 +88,8 @@ final class FunctionEventValidatorTest extends TestCase $this->assertFalse($this->object->isValid('tables.*.unknown')); $this->assertFalse($this->object->isValid('tables.*.rows.*.unknown')); $this->assertFalse($this->object->isValid('tablesdb.books.collections.chapters.documents.prolog.create')); + $this->assertFalse($this->object->isValid('documentsdb.books.tables.chapters.rows.prolog.create')); + $this->assertFalse($this->object->isValid('vectorsdb.books.tables.chapters.rows.prolog.create')); $this->assertFalse($this->object->isValid('users.torsten.unknown')); $this->assertFalse($this->object->isValid('users.torsten.delete.email')); $this->assertFalse($this->object->isValid('teams.*.memberships.*.update.unknown')); From 5c40b17eeb177f8a780d353c88edef95454a31cb Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sun, 9 Aug 2026 18:02:29 +0530 Subject: [PATCH 05/11] docs: update OAuth2 provider contribution guide Reflect the current Project OAuth2 registry, Console/SDK requirements, and remove obsolete logo/form paths that were blocking contributors. Co-authored-by: Cursor --- docs/tutorials/add-oauth2-provider.md | 228 +++++++++++++++++++------- 1 file changed, 171 insertions(+), 57 deletions(-) diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index da5f514919..b80c9f6ecb 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -8,11 +8,13 @@ OAuth2 providers help users to log in to the apps and websites without the need As of the writing of these lines, we do not accept any minor OAuth2 providers. For us to accept some smaller and potentially unlimited number of OAuth2 providers, some product design and software architecture changes must be applied first. +> **Tip:** Use an existing simple provider such as [Yahoo](https://github.com/search?q=repo%3Aappwrite%2Fappwrite+Yahoo&type=code) as a copy-paste reference. Search the Appwrite repository for that provider name and update every matching file for your new provider. + ## 1. Prerequisites It's really easy to contribute to an open source project, but when using GitHub, there are a few steps we need to follow. This section will take you step-by-step through the process of preparing your own local version of Appwrite, where you can make any changes without affecting Appwrite right away. -> If you are experienced with GitHub or have made a pull request before, you can skip to [Implement new provider](#2-implement-new-provider). +> If you are experienced with GitHub or have made a pull request before, you can skip to [Implement new provider](#2-implement-new-provider-backend). ### 1.1 Fork the Appwrite repository @@ -28,13 +30,41 @@ $ git clone COPIED_URL > To fork a repository, you will need a basic understanding of CLI and git-cli binaries installed. If you are a beginner, we recommend you to use `Github Desktop`. It is a really clean and simple visual Git client. -Finally, you will need to create a `feat-XXX-YYY-oauth` branch based on the `master` branch and switch to it. The `XXX` should represent the issue ID and `YYY` the OAuth provider name. +Finally, you will need to create a `feat-XXX-YYY-oauth` branch based on the `main` branch and switch to it. The `XXX` should represent the issue ID and `YYY` the OAuth provider name. -## 2. Implement new provider +Adding a provider usually spans **two repositories**: -### 2.1 List your new provider +1. **[appwrite/appwrite](https://github.com/appwrite/appwrite)** — backend adapter, config, Project OAuth2 API, response models, and tests +2. **[appwrite/console](https://github.com/appwrite/console)** — Console UI list, update switch, and icons -The first step in adding a new OAuth2 provider is to add it to the list of providers located at: +The Console served by `docker compose` in this repository is a **prebuilt image** (`appwrite-console`). Local Console source changes are not picked up until you run the Console repo locally (or build and point compose at your own image). + +## 2. Implement new provider (backend) + +Throughout this guide, replace `XXX` / `Xxx` / `xxx` with your provider name in the correct casing (`Yahoo` / `yahoo`, `GitHub` / `github`, `paypalSandbox` / `PaypalSandbox`, and so on). + +### 2.1 Checklist + +| Step | File / location | +|------|-----------------| +| Config | `app/config/oAuthProviders.php` | +| Adapter | `src/Appwrite/Auth/OAuth2/Xxx.php` | +| Update action | `src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Xxx/Update.php` | +| Provider registry | `src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php` (`getProviderActions()`) | +| HTTP registration | `src/Appwrite/Platform/Modules/Project/Services/Http.php` | +| Get response models | `src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Get.php` | +| Response model class | `src/Appwrite/Utopia/Response/Model/OAuth2Xxx.php` | +| Response constant | `src/Appwrite/Utopia/Response.php` (`MODEL_OAUTH2_XXX`) | +| Provider list model | `src/Appwrite/Utopia/Response/Model/OAuth2ProviderList.php` | +| Model registration | `app/init/models.php` | +| Unit test allow-list | `tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php` | +| Changelog | `CHANGES.md` | + +Do **not** invent a separate test class for the provider unless it needs adapter-specific unit coverage. Add the provider id to the existing `OAuth2ProviderTest` expected list so the registry stays complete. + +### 2.2 List your new provider + +Add an entry to: ``` app/config/oAuthProviders.php @@ -44,21 +74,34 @@ Make sure to fill in all data needed and that your provider array key name: - is in [`camelCase`](https://en.wikipedia.org/wiki/Camel_case) format for sentence, but lowercase for names. `github` must be all lowercased, but `paypalSandbox` should have uppercase S - has no spaces or special characters +- matches `getName()` on your adapter class and `getProviderId()` on your Update action -> Please make sure to keep the list of providers in `oAuthProviders.php` in the alphabetical order A-Z. +Keep the list of providers in `oAuthProviders.php` in alphabetical order A–Z. -### 2.2 Add Provider Logo +Example shape: -Add a logo image to your new provider in this path: `public/images/users`. Your logo should be a png 100×100px file with the name of your provider (all lowercase). Please make sure to leave about 30px padding around the logo to be consistent with other logos. +```php +'yahoo' => [ + 'name' => 'Yahoo', + 'developers' => 'https://developer.yahoo.com/oauth2/guide/flows_authcode/', + 'icon' => 'icon-yahoo', + 'enabled' => true, + 'sandbox' => false, + 'form' => false, + 'beta' => false, + 'mock' => false, + 'class' => 'Appwrite\\Auth\\OAuth2\\Yahoo', +], +``` + +The `icon` value is metadata for the backend. Console icons live in the Console repository (see [section 3](#3-console-and-sdk)). ### 2.3 Add Provider Class -Once you have finished setting up all the metadata for the new provider, you need to start coding. - -Create a new file `XXX.php` where `XXX` is the name of the OAuth provider in [`PascalCase`](https://stackoverflow.com/a/41769355/7659504) in this location +Create a new file `Xxx.php` where `Xxx` is the name of the OAuth provider in [`PascalCase`](https://stackoverflow.com/a/41769355/7659504) in this location: ```bash -src/Appwrite/Auth/OAuth2/XXX.php +src/Appwrite/Auth/OAuth2/Xxx.php ``` Inside this file, create a new class that extends the basic OAuth2 provider abstract class. Note that the class name should start with a capital letter, as PHP FIG standards suggest. @@ -86,7 +129,7 @@ class [PROVIDER NAME] extends OAuth2 public function getName(): string { - return '[PROVIDER NAME]'; + return '[providerId]'; // must match oAuthProviders.php key, e.g. 'yahoo' } public function getLoginURL(): string @@ -163,6 +206,13 @@ class [PROVIDER NAME] extends OAuth2 return $this->user; } + + /** + * Optional. Called when enabling the provider from the Console with + * credentials set. Throw \Exception if client id/secret are invalid. + * See Github::verifyCredentials() for a token-endpoint probe pattern. + */ + // public function verifyCredentials(): void {} } ``` @@ -171,56 +221,120 @@ class [PROVIDER NAME] extends OAuth2 > If your OAuth2 provider has different endpoints for getting username/email/id, you can fire specific requests from specific get-method, and stop using `getUser` method. -Please mention in your documentation what resources or API docs you used to implement the provider's OAuth2 protocol. +Please mention in your pull request what resources or API docs you used to implement the provider's OAuth2 protocol. -## 3. Test your provider +### 2.4 Project OAuth2 Update action -After you finish adding your new provider to Appwrite, you should be able to see it in your Appwrite console. Navigate to 'Project > Users > Providers' and check your new provider's settings form. +Each provider exposes `PATCH /v1/project/oauth2/{providerId}` through a dedicated Update action. Copy a simple provider such as Yahoo: -> To start the Appwrite console from the source code, you can simply run `docker compose up -d'. - -Add credentials and check both a successful and a failed login (where the user denies integration on the provider page). - -You can test your OAuth2 provider by trying to login using the [OAuth2 method](https://appwrite.io/docs/references/cloud/client-web/account#createOAuth2Session) when integrating the Appwrite Web SDK in a demo app. - -Pass your new adapter name as the provider parameter. If login is successful, you will be redirected to your success URL parameter. Otherwise, you will be redirected to your failure URL. - -If everything goes well, raise a pull request and be ready to respond to any feedback which can arise during our code review. - -## 4. Raise a pull request - -First of all, commit the changes with the message `Added XXX OAuth2 Provider` and push it. This will publish a new branch to your forked version of Appwrite. If you visit it at `github.com/YOUR_USERNAME/appwrite`, you will see a new alert saying you are ready to submit a pull request. Follow the steps GitHub provides, and at the end, you will have your pull request submitted. - -## 🤕 Stuck ? - -If you need any help with the contribution, feel free to head over to [our Discord channel](https://appwrite.io/discord) and we'll be happy to help you out. - -## 😉 Need more freedom - -If your OAuth provider requires special configuration apart from `clientId` and `clientSecret` you can create a custom form. Currently this is being realized through putting all custom fields as JSON into the `clientSecret` field to keep the project API stable. You can implement your custom form following these steps: - -1. Add your custom form in `app/views/console/users/oauth/[PROVIDER].phtml`. Below is a template you can use. Add the filename to `app/config/oAuthProviders.php`. - -```php -getParam('provider', ''); -?> - - - - - +```bash +src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Xxx/Update.php ``` -2. Add the config for creating the JSON in `public/scripts/views/forms/oauth-custom.js` using this template +Implement at least: -```js -{ - "[Provider]":{ - "[JSON property name 1]":"[html element Id 1]", - "[JSON property name 2]":"[html element Id 2]" - } +- `getProviderId()` — same key as in `oAuthProviders.php` +- `getProviderClass()` — your adapter class +- `getProviderLabel()` — human-readable name (e.g. `Yahoo`) +- `getProviderSDKMethod()` — e.g. `updateOAuth2Yahoo` +- `getResponseModel()` — e.g. `Response::MODEL_OAUTH2_YAHOO` +- `getClientIdName()` / `getClientIdExample()` +- `getClientSecretName()` / `getClientSecretExample()` + +Then wire the action in: + +1. `Base::getProviderActions()` — map `'xxx' => Xxx\Update::class` +2. `Modules/Project/Services/Http.php` — `use` + `$this->addAction(...)` + +### 2.5 Response model + +1. Add `public const MODEL_OAUTH2_XXX = 'oAuth2Xxx';` in `src/Appwrite/Utopia/Response.php` +2. Create `src/Appwrite/Utopia/Response/Model/OAuth2Xxx.php` extending `OAuth2Base` (see `OAuth2Yahoo.php`) +3. Register it in `app/init/models.php` with `Response::setModel(new OAuth2Xxx());` +4. Include `Response::MODEL_OAUTH2_XXX` in: + - `OAuth2ProviderList.php` + - `Project/Http/Project/OAuth2/Get.php` + +### 2.6 Tests and changelog + +1. Add your provider id to the `$expected` array in `OAuth2ProviderTest::testProviderRegistryIsExplicitAndComplete()` +2. Add a line under the relevant section in `CHANGES.md` + +## 3. Console and SDK + +Backend-only changes are **not enough** for the provider to appear or save correctly in the Console. + +### 3.1 Console repository ([appwrite/console](https://github.com/appwrite/console)) + +Open a companion PR that: + +1. Adds the provider to `src/lib/stores/oauth-providers.ts` (name, icon key, docs URL, usually `component: Main`). Auth settings **filters out** providers missing from this map. +2. Adds a `case` in `src/routes/(console)/project-[region]-[project]/auth/updateOAuth.ts` that calls `projectSdk.updateOAuth2Xxx(...)`. +3. Adds SVG icons under: + - `static/icons/light/color/{provider}.svg` + - `static/icons/light/grayscale/{provider}.svg` + - `static/icons/dark/color/{provider}.svg` + - `static/icons/dark/grayscale/{provider}.svg` + +Use an existing provider folder (for example `yahoo`) as the icon template. + +### 3.2 Specs and Console SDK + +The Console checks `OAuthProvider` from `@appwrite.io/console` before calling Update: + +```ts +if (!isValueOfStringEnum(OAuthProvider, provider.key)) { + throw new Error(`Invalid OAuth2 provider: ${provider.key}`); } ``` -3. In your provider class `src/Appwrite/Auth/OAuth2/[Provider].php` add logic to decode the JSON using the same property names. +Until the generated SDK enum includes your provider: + +1. Regenerate Appwrite API specs after the backend endpoints/models land +2. Regenerate / bump the Console SDK so `OAuthProvider` and `updateOAuth2Xxx` exist +3. Point local Console at that SDK build while developing + +Without the SDK update, enabling the provider in the UI fails with **Invalid OAuth2 provider**, even when `PATCH /v1/project/oauth2/{providerId}` works via curl. + +### 3.3 Local development tips + +- Rebuild / recreate the Appwrite containers after backend changes: `docker compose up -d --force-recreate --build` +- Confirm the backend lists the provider, for example: + - `GET /v1/project/oauth2` (Network tab while on Auth settings), or + - `docker exec -it appwrite php -r "print_r(require '/usr/src/code/app/config/oAuthProviders.php');"` +- To exercise Console UI changes, run the Console repository against your local Appwrite endpoint. The `appwrite-console` service in this repo’s compose file uses a published image and will not include your unreleased Console edits. +- You can still validate the Project API without Console by calling `PATCH /v1/project/oauth2/{providerId}` directly. + +## 4. Test your provider + +1. Run unit coverage for the Project OAuth2 registry: + + ```shell + docker compose exec appwrite test tests/unit/Platform/Modules/Project/OAuth2/ + ``` + +2. With backend + Console wired, open **Auth → Settings**, find your provider, save Client ID / Client Secret, and enable it. + +3. Exercise login with the [OAuth2 session API](https://appwrite.io/docs/references/cloud/client-web/account#createOAuth2Session) (or a small Web SDK demo). Pass your provider id as the `provider` parameter. Confirm both success and failure (user denies consent) redirects. + +If everything goes well, raise pull requests for Appwrite and Console and be ready to respond to code review feedback. + +## 5. Raise a pull request + +Commit the changes with a clear message such as `Added XXX OAuth2 Provider` and push your branch. Open a PR from your fork. Link the related feature issue, and link the Console PR when you have one. + +## Stuck? + +If you need any help with the contribution, feel free to head over to [our Discord channel](https://appwrite.io/discord) and we'll be happy to help you out. + +## Providers with extra fields + +If your OAuth provider needs more than a single client id + client secret (domain, tenant, realm, Apple key material, OIDC discovery URLs, and so on), do **not** add legacy `.phtml` Console forms. Those paths are obsolete. + +Instead, follow an existing multi-field provider such as Auth0, Microsoft, Apple, or OIDC: + +1. Override `getParameters()` (and often the Update action constructor) in `.../OAuth2/Xxx/Update.php` so the Project API exposes the extra params. +2. Store non-secret extras in the JSON blob under `{providerId}Secret` when that is the existing pattern for that style of provider (see Auth0 / Gitlab / Apple). +3. Override `buildReadResponse()` when the Console needs those extras back (with secrets zeroed). +4. In the Console, either reuse `mainOAuth.svelte` with parameters from the API, or add a dedicated component under `auth/(providers)/` when the UI is special-cased (Google and OIDC are examples). +5. Extend the `updateOAuth.ts` switch to pass every field through to `updateOAuth2Xxx`. From 567722f61c28ab1577178a5688fd96cbeef5249d Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sun, 9 Aug 2026 18:06:14 +0530 Subject: [PATCH 06/11] docs: note shared OAuth2 response models for sandbox pairs Document that paypal/paypalSandbox and tradeshift/tradeshiftBox reuse one model via $conditions, so contributors do not add a redundant model class. Co-authored-by: Cursor --- docs/tutorials/add-oauth2-provider.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index b80c9f6ecb..62c0d2e3be 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -248,6 +248,8 @@ Then wire the action in: ### 2.5 Response model +For a standalone provider (the common case): + 1. Add `public const MODEL_OAUTH2_XXX = 'oAuth2Xxx';` in `src/Appwrite/Utopia/Response.php` 2. Create `src/Appwrite/Utopia/Response/Model/OAuth2Xxx.php` extending `OAuth2Base` (see `OAuth2Yahoo.php`) 3. Register it in `app/init/models.php` with `Response::setModel(new OAuth2Xxx());` @@ -255,6 +257,13 @@ Then wire the action in: - `OAuth2ProviderList.php` - `Project/Http/Project/OAuth2/Get.php` +**Shared models for sandbox / alternate IDs:** Production and sandbox variants that expose the same response shape reuse one model. Do not create a second model class. Instead, list both provider ids in `$conditions['$id']`, and point both Update actions at the same `MODEL_OAUTH2_*` constant. Examples: + +- `paypal` / `paypalSandbox` → `OAuth2Paypal` with `'$id' => ['paypal', 'paypalSandbox']` +- `tradeshift` / `tradeshiftBox` → `OAuth2Tradeshift` with `'$id' => ['tradeshift', 'tradeshiftBox']` + +You still need a separate adapter class, Update action, and `oAuthProviders.php` entry for each id; only the response model is shared. Each id must still appear in `Base::getProviderActions()` and in `OAuth2ProviderTest`. + ### 2.6 Tests and changelog 1. Add your provider id to the `$expected` array in `OAuth2ProviderTest::testProviderRegistryIsExplicitAndComplete()` From ba2b71d0bfee01536d8eeb6cafd08942e22fefa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Sun, 9 Aug 2026 14:37:52 +0200 Subject: [PATCH 07/11] chore: respect _APP_SDK_PREVIEW in SDK exclusion logic Preview SDKs are built from a PR so a reviewer can see the API surface that PR produces, but they were generated with the same exclusions as a released SDK. appwrite-labs/cloud#5213 added `_APP_SDK_PREVIEW=enabled` to lift them; this covers the CE-side rules the flag did not reach. Two independent layers hide an endpoint, and both are now gated: - `exclude` in `app/config/sdks.php` (console-cli: assistant, avatars). The lists above the gate are byte-for-byte unchanged. - `hide:` on `Appwrite\SDK\Method`, which drops the endpoint from the spec itself and therefore cannot be recovered at generation time: `createOAuth2Session`, `graphql.get`, and the VCS installation entry points for GitHub and the OAuth2-based providers. Only `sdk-preview.yml` sets the flag, on both the `specs` and `sdks` steps. Every other run, releases included, leaves it unset. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/sdk-preview.yml | 4 ++-- AGENTS.md | 18 ++++++++++++++++++ app/config/sdks.php | 19 ++++++++++++++++++- app/controllers/api/account.php | 3 ++- app/controllers/api/graphql.php | 3 ++- .../Modules/VCS/Http/Authorize/Base.php | 3 ++- .../Modules/VCS/Http/GitHub/Authorize/Get.php | 3 ++- 7 files changed, 46 insertions(+), 7 deletions(-) diff --git a/.github/workflows/sdk-preview.yml b/.github/workflows/sdk-preview.yml index 468e0f0b97..ec34cbc51f 100644 --- a/.github/workflows/sdk-preview.yml +++ b/.github/workflows/sdk-preview.yml @@ -48,11 +48,11 @@ jobs: - name: Generate Specs run: | - docker compose exec appwrite specs --version=latest --mode=normal --git=no + docker compose exec -e _APP_SDK_PREVIEW=enabled appwrite specs --version=latest --mode=normal --git=no - name: Generate SDK run: | - docker compose exec appwrite sdks --platform=${{ steps.set-sdk.outputs.platform }} --sdk=${{ steps.set-sdk.outputs.sdk_type }} --version=latest --git=no + docker compose exec -e _APP_SDK_PREVIEW=enabled appwrite sdks --platform=${{ steps.set-sdk.outputs.platform }} --sdk=${{ steps.set-sdk.outputs.sdk_type }} --version=latest --git=no sudo chown -R $USER:$USER ./app/sdks/${{ steps.set-sdk.outputs.platform }}-${{ steps.set-sdk.outputs.sdk_type }} - name: Build and Publish SDK diff --git a/AGENTS.md b/AGENTS.md index fce82613aa..f5db88cf50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -233,6 +233,24 @@ Register new injections alongside existing ones in `app/init/resources.php` and Use `snake_case`; dots only for parent/child relationships (`project.id`, `storage.bucket.id`). See [Tracing with Utopia Span](#tracing-with-utopia-span) for full rules. +## SDK generation exclusions + +Two independent mechanisms keep an endpoint out of a generated SDK: + +1. **`exclude` in `app/config/sdks.php`** -- per-SDK `services` / `methods` lists, applied at generation time. +2. **`hide:` on `Appwrite\SDK\Method`** -- `true` drops the endpoint from every spec, an array drops it from the listed platforms only. An endpoint dropped from the spec cannot be recovered at generation time. + +Both are lifted when `_APP_SDK_PREVIEW=enabled`. Preview SDKs are built from a PR so a reviewer can see the whole API surface that PR produces, and they publish nothing. Only `.github/workflows/sdk-preview.yml` sets the flag, on **both** the `specs` and `sdks` steps -- setting it on `sdks` alone leaves anything hidden at layer 2 silently missing. Every other run, releases included, leaves it unset and keeps every rule. + +Read the flag inline at each call site with a comment, never behind a helper: + +```php +// Preview SDK builds show the whole surface, so they do not hide. +hide: System::getEnv('_APP_SDK_PREVIEW', 'disabled') !== 'enabled', +``` + +A new `hide:` must respect the flag. `->label('docs', false)` is a separate mechanism for routes that are not part of the public API at all (mocks, OAuth callbacks) and stays unconditional. + ## Tracing with Utopia Span In handlers, only call `Span::add($key, $value)`. **Never** call `Span::init`, `setError`, or `Span::finish` -- lifecycle is owned by the entry-point harness (`app/http.php`, `app/worker.php`, `app/realtime.php`, `Bus::dispatch`). For selective export, filter in the sampler in `app/init/span.php`. diff --git a/app/config/sdks.php b/app/config/sdks.php index 8d128cfe0c..8db20b196a 100644 --- a/app/config/sdks.php +++ b/app/config/sdks.php @@ -1,6 +1,8 @@ [ 'key' => APP_SDK_PLATFORM_CLIENT, 'name' => 'Client', @@ -589,3 +591,18 @@ return [ ], ], ]; + +// A preview SDK is built from a PR to show the whole API surface that PR produces +// and publishes nothing, so none of the exclusions above apply to it. Only the +// preview workflow sets _APP_SDK_PREVIEW; every other run, releases included, +// leaves it unset and keeps every rule. The per-endpoint counterpart is the `hide` +// argument on Appwrite\SDK\Method, lifted under the same flag at its call sites. +if (System::getEnv('_APP_SDK_PREVIEW', 'disabled') === 'enabled') { + foreach ($platforms as $platformKey => $platform) { + foreach (\array_keys($platform['sdks']) as $index) { + unset($platforms[$platformKey]['sdks'][$index]['exclude']); + } + } +} + +return $platforms; diff --git a/app/controllers/api/account.php b/app/controllers/api/account.php index 35ebf065e0..844159c7e5 100644 --- a/app/controllers/api/account.php +++ b/app/controllers/api/account.php @@ -1320,7 +1320,8 @@ Http::get('/v1/account/sessions/oauth2/:provider') ) ], contentType: ContentType::HTML, - hide: [APP_SDK_PLATFORM_SERVER], + // Preview SDK builds show the whole surface, so they do not hide. + hide: System::getEnv('_APP_SDK_PREVIEW', 'disabled') === 'enabled' ? false : [APP_SDK_PLATFORM_SERVER], )) ->label('abuse-limit', 50) ->label('abuse-key', 'ip:{ip}') diff --git a/app/controllers/api/graphql.php b/app/controllers/api/graphql.php index 1c596bb931..5ead85582f 100644 --- a/app/controllers/api/graphql.php +++ b/app/controllers/api/graphql.php @@ -54,7 +54,8 @@ Http::get('/v1/graphql') group: 'graphql', name: 'get', auth: [AuthType::ADMIN, AuthType::KEY, AuthType::SESSION, AuthType::JWT], - hide: true, + // Preview SDK builds show the whole surface, so they do not hide. + hide: System::getEnv('_APP_SDK_PREVIEW', 'disabled') !== 'enabled', description: '/docs/references/graphql/get.md', responses: [ new SDKResponse( diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Authorize/Base.php b/src/Appwrite/Platform/Modules/VCS/Http/Authorize/Base.php index 06b0fcea1a..e28a96434e 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Authorize/Base.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Authorize/Base.php @@ -67,7 +67,8 @@ abstract class Base extends Action ], contentType: ContentType::HTML, type: MethodType::WEBAUTH, - hide: true, + // Preview SDK builds show the whole surface, so they do not hide. + hide: System::getEnv('_APP_SDK_PREVIEW', 'disabled') !== 'enabled', )) ->param('success', '', fn ($redirectValidator) => $redirectValidator, 'URL to redirect back to console after a successful installation attempt.', true, ['redirectValidator']) ->param('failure', '', fn ($redirectValidator) => $redirectValidator, 'URL to redirect back to console after a failed installation attempt.', true, ['redirectValidator']) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Authorize/Get.php index 6188c14b5d..efa43f4837 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Authorize/Get.php @@ -46,7 +46,8 @@ class Get extends Action ], contentType: ContentType::HTML, type: MethodType::WEBAUTH, - hide: true, + // Preview SDK builds show the whole surface, so they do not hide. + hide: System::getEnv('_APP_SDK_PREVIEW', 'disabled') !== 'enabled', )) ->param('success', '', fn ($redirectValidator) => $redirectValidator, 'URL to redirect back to console after a successful installation attempt.', true, ['redirectValidator']) ->param('failure', '', fn ($redirectValidator) => $redirectValidator, 'URL to redirect back to console after a failed installation attempt.', true, ['redirectValidator']) From 3de43fe1bcce4f6da2de47f2f36d81001f3b2345 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sun, 9 Aug 2026 18:09:05 +0530 Subject: [PATCH 08/11] docs: clarify draft PRs until Console SDK ships Advise contributors that local @appwrite.io/console wiring is for development only, and to keep Appwrite/Console PRs in draft until the official SDK release includes the provider. Co-authored-by: Cursor --- docs/tutorials/add-oauth2-provider.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index 62c0d2e3be..7205645abf 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -275,7 +275,7 @@ Backend-only changes are **not enough** for the provider to appear or save corre ### 3.1 Console repository ([appwrite/console](https://github.com/appwrite/console)) -Open a companion PR that: +Open a companion **draft** PR that: 1. Adds the provider to `src/lib/stores/oauth-providers.ts` (name, icon key, docs URL, usually `component: Main`). Auth settings **filters out** providers missing from this map. 2. Adds a `case` in `src/routes/(console)/project-[region]-[project]/auth/updateOAuth.ts` that calls `projectSdk.updateOAuth2Xxx(...)`. @@ -297,13 +297,15 @@ if (!isValueOfStringEnum(OAuthProvider, provider.key)) { } ``` -Until the generated SDK enum includes your provider: +Without an SDK that includes your provider, enabling it in the UI fails with **Invalid OAuth2 provider**, even when `PATCH /v1/project/oauth2/{providerId}` works via curl. -1. Regenerate Appwrite API specs after the backend endpoints/models land -2. Regenerate / bump the Console SDK so `OAuthProvider` and `updateOAuth2Xxx` exist -3. Point local Console at that SDK build while developing +The release sequence is: -Without the SDK update, enabling the provider in the UI fails with **Invalid OAuth2 provider**, even when `PATCH /v1/project/oauth2/{providerId}` works via curl. +1. Land the backend endpoints and models in Appwrite, then regenerate API specs +2. Wait for the official `@appwrite.io/console` package to be published with `OAuthProvider` and `updateOAuth2Xxx` for your provider +3. Finish and undraft the Console PR once that published SDK is available + +Linking or patching a local `@appwrite.io/console` build (or temporarily bypassing the enum check) is **only for local development**. Do not treat a local SDK as merge-ready. Open your Appwrite and Console PRs as **drafts** until the official Console SDK release includes your provider, then bump the Console dependency to that release and mark the PRs ready for review. ### 3.3 Local development tips @@ -326,11 +328,11 @@ Without the SDK update, enabling the provider in the UI fails with **Invalid OAu 3. Exercise login with the [OAuth2 session API](https://appwrite.io/docs/references/cloud/client-web/account#createOAuth2Session) (or a small Web SDK demo). Pass your provider id as the `provider` parameter. Confirm both success and failure (user denies consent) redirects. -If everything goes well, raise pull requests for Appwrite and Console and be ready to respond to code review feedback. +If everything goes well, open draft pull requests for Appwrite and Console (see [section 3.2](#32-specs-and-console-sdk) for when to mark them ready) and be ready to respond to code review feedback. ## 5. Raise a pull request -Commit the changes with a clear message such as `Added XXX OAuth2 Provider` and push your branch. Open a PR from your fork. Link the related feature issue, and link the Console PR when you have one. +Commit the changes with a clear message such as `Added XXX OAuth2 Provider` and push your branch. Open a **draft** PR from your fork. Link the related feature issue, and link the Console draft PR when you have one. Mark both ready for review only after the official `@appwrite.io/console` SDK includes your provider. ## Stuck? From 9e7a5e7cefc0b3b94f66448ed4877495658f6879 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sun, 9 Aug 2026 18:10:02 +0530 Subject: [PATCH 09/11] docs: add verified specs and SDK generation commands Document php app/cli.php specs/sdks (and docker compose shortcuts) for regenerating Console specs and the local console-web SDK while developing a new OAuth provider. Co-authored-by: Cursor --- docs/tutorials/add-oauth2-provider.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index 7205645abf..9c56e44afa 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -299,11 +299,31 @@ if (!isValueOfStringEnum(OAuthProvider, provider.key)) { Without an SDK that includes your provider, enabling it in the UI fails with **Invalid OAuth2 provider**, even when `PATCH /v1/project/oauth2/{providerId}` works via curl. +After the backend endpoints and models land, regenerate specs and SDKs from a running Appwrite container (`bin/specs` and `bin/sdks` are thin wrappers around `php app/cli.php`): + +```bash +# 1. Regenerate API specs (writes under app/config/specs/) +docker compose exec appwrite php app/cli.php specs --git=no + +# 2. Generate the Console web SDK locally (for local Console development only) +docker compose exec appwrite php app/cli.php sdks --platform=console --sdk=web --version=latest --git=no +``` + +Equivalent shortcuts: + +```bash +docker compose exec appwrite specs --git=no +docker compose exec appwrite sdks --platform=console --sdk=web --version=latest --git=no +``` + +Omit the flags to run the interactive prompts instead. Commit the updated specs with the Appwrite PR; official SDK publishing is handled separately by maintainers. + The release sequence is: -1. Land the backend endpoints and models in Appwrite, then regenerate API specs -2. Wait for the official `@appwrite.io/console` package to be published with `OAuthProvider` and `updateOAuth2Xxx` for your provider -3. Finish and undraft the Console PR once that published SDK is available +1. Land the backend endpoints and models in Appwrite, regenerate specs (`php app/cli.php specs`), and open a **draft** Appwrite PR +2. Generate a local Console SDK (`php app/cli.php sdks`) only to exercise Console changes locally +3. Wait for the official `@appwrite.io/console` package to be published with `OAuthProvider` and `updateOAuth2Xxx` for your provider +4. Finish and undraft the Console PR once that published SDK is available Linking or patching a local `@appwrite.io/console` build (or temporarily bypassing the enum check) is **only for local development**. Do not treat a local SDK as merge-ready. Open your Appwrite and Console PRs as **drafts** until the official Console SDK release includes your provider, then bump the Console dependency to that release and mark the PRs ready for review. From 0aa4ab12d44c8aef78efb6b0ee86ceb1aea791cc Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sun, 9 Aug 2026 18:10:47 +0530 Subject: [PATCH 10/11] docs: run specs and SDK generation with host PHP Drop docker compose from the OAuth provider tutorial commands; php app/cli.php works from the repo root without a running stack. Co-authored-by: Cursor --- docs/tutorials/add-oauth2-provider.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index 9c56e44afa..631612073b 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -299,21 +299,14 @@ if (!isValueOfStringEnum(OAuthProvider, provider.key)) { Without an SDK that includes your provider, enabling it in the UI fails with **Invalid OAuth2 provider**, even when `PATCH /v1/project/oauth2/{providerId}` works via curl. -After the backend endpoints and models land, regenerate specs and SDKs from a running Appwrite container (`bin/specs` and `bin/sdks` are thin wrappers around `php app/cli.php`): +After the backend endpoints and models land, regenerate specs and SDKs from the repo root with PHP (no Docker stack required; `composer install` must already have been run): ```bash # 1. Regenerate API specs (writes under app/config/specs/) -docker compose exec appwrite php app/cli.php specs --git=no +php app/cli.php specs --git=no # 2. Generate the Console web SDK locally (for local Console development only) -docker compose exec appwrite php app/cli.php sdks --platform=console --sdk=web --version=latest --git=no -``` - -Equivalent shortcuts: - -```bash -docker compose exec appwrite specs --git=no -docker compose exec appwrite sdks --platform=console --sdk=web --version=latest --git=no +php app/cli.php sdks --platform=console --sdk=web --version=latest --git=no ``` Omit the flags to run the interactive prompts instead. Commit the updated specs with the Appwrite PR; official SDK publishing is handled separately by maintainers. From a65fa6896b3e6a6c8d6e055655fde78154ed6707 Mon Sep 17 00:00:00 2001 From: fogelito Date: Sun, 9 Aug 2026 15:55:37 +0300 Subject: [PATCH 11/11] skip sunqueries --- src/Appwrite/Platform/Tasks/ScheduleBase.php | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Platform/Tasks/ScheduleBase.php b/src/Appwrite/Platform/Tasks/ScheduleBase.php index efa9a0f8eb..78c120faf2 100644 --- a/src/Appwrite/Platform/Tasks/ScheduleBase.php +++ b/src/Appwrite/Platform/Tasks/ScheduleBase.php @@ -237,10 +237,19 @@ abstract class ScheduleBase extends Action foreach ($batches as $batch) { $dbStart = microtime(true); - $documents = $dbForPlatform->find('projects', [ - Query::equal('$id', $batch), - Query::limit(count($batch)), - ]); + // The project's subquery attributes cost one query each, per project — five + // thousand extra queries for a batch of a thousand projects — and no + // schedule task reads them. The only attributes used here are accessedAt, + // teamId, database and the sequence, and the documents enqueued for the + // workers are reloaded there by id, so the stripped arrays never reach the + // code that needs them. Same group Action::$filters marks as Project. + $documents = $dbForPlatform->skipFilters( + fn () => $dbForPlatform->find('projects', [ + Query::equal('$id', $batch), + Query::limit(count($batch)), + ]), + ['subQueryKeys', 'subQueryWebhooks', 'subQueryPlatforms', 'subQueryBlocks', 'subQueryDevKeys'] + ); $dbQueryDuration += microtime(true) - $dbStart; $transformStart = microtime(true);