From 296710efe0d743b5b923f6c8dfea3f6d90970380 Mon Sep 17 00:00:00 2001 From: imtia33 Date: Mon, 17 Aug 2026 15:52:20 +0600 Subject: [PATCH 01/53] feat: add support for fetching user gravatar --- docs/references/avatars/get-gravatar.md | 5 + .../Modules/Avatars/Http/Gravatar/Get.php | 152 ++++++++++++++++++ .../Modules/Avatars/Services/Http.php | 2 + tests/e2e/Services/Avatars/AvatarsBase.php | 103 ++++++++++++ 4 files changed, 262 insertions(+) create mode 100644 docs/references/avatars/get-gravatar.md create mode 100644 src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php diff --git a/docs/references/avatars/get-gravatar.md b/docs/references/avatars/get-gravatar.md new file mode 100644 index 0000000000..df10dfb192 --- /dev/null +++ b/docs/references/avatars/get-gravatar.md @@ -0,0 +1,5 @@ +Use this endpoint to fetch a user's Gravatar avatar image. Gravatar is a globally-recognized avatar service that returns an avatar based on the SHA-256 hash of a user's email address. + +Pass an `email` address to fetch the Gravatar for that address, or leave it empty to use the currently signed-in user's email. If neither an `email` param nor an active session is provided, the request will fail. + +When the email has no associated Gravatar, the `default` parameter controls what is returned (e.g., a generated identicon, the mystery-person silhouette, or a `404` error). diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php new file mode 100644 index 0000000000..0015e46cfb --- /dev/null +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php @@ -0,0 +1,152 @@ +setHttpMethod(UtopiaAction::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/avatars/gravatar') + ->desc('Get user Gravatar') + ->groups(['api', 'avatars']) + ->label('scope', 'avatars.read') + ->label('cache', true) + ->label('cache.resource', 'avatar/gravatar') + ->label('cache.params', ['email', 'width', 'height', 'default', 'rating', 'project']) + ->label('sdk', new Method( + namespace: 'avatars', + group: null, + name: 'getGravatar', + description: '/docs/references/avatars/get-gravatar.md', + auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], + type: MethodType::LOCATION, + locationAuth: ['Project', 'ImpersonateUserId'], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_NONE, + ) + ], + contentType: ContentType::IMAGE + )) + ->param('email', '', new Email(), 'Email address. Pass an email address to fetch the Gravatar image for. When empty, the current user\'s email is used.', true) + ->param('width', 80, new Range(1, 2048), 'Image width. Pass an integer between 1 to 2048. Defaults to 80.', true) + ->param('height', 80, new Range(1, 2048), 'Image height. Pass an integer between 1 to 2048. Defaults to 80.', true) + ->param('default', 'mp', new WhiteList(['404', 'mp', 'identicon', 'monsterid', 'wavatar', 'retro', 'robohash', 'blank'], true), 'Default image to return when no Gravatar is found. Defaults to \'mp\'.', true) + ->param('rating', 'g', new WhiteList(['g', 'pg', 'r', 'x'], true), 'Maximum image rating to return. Defaults to \'g\'.', true) + ->inject('response') + ->inject('user') + ->callback($this->action(...)); + } + + public function action( + string $email, + int $width, + int $height, + string $default, + string $rating, + Response $response, + Document $user, + ): void { + if (!\extension_loaded('imagick')) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Imagick extension is missing'); + } + + // Resolve the email: explicit param takes priority, then current user's email. + // If neither is available, the caller must supply one or be signed in. + if (!empty($email)) { + $resolvedEmail = $email; + } elseif (!$user->isEmpty()) { + $resolvedEmail = $user->getAttribute('email', ''); + } else { + throw new Exception(Exception::GENERAL_BAD_REQUEST, 'Either the \'email\' param or an active session is required.'); + } + + // Gravatar spec: SHA-256 of strtolower(trim($email)) + $hash = \hash('sha256', \strtolower(\trim($resolvedEmail))); + + $gravatarUrl = \sprintf( + 'https://www.gravatar.com/avatar/%s?s=%d&d=%s&r=%s', + $hash, + $width, + \urlencode($default), + \urlencode($rating), + ); + + $host = \parse_url($gravatarUrl, PHP_URL_HOST) ?? ''; + + $isIpLiteral = \filter_var(\trim($host, '[]'), FILTER_VALIDATE_IP) !== false; + if (!$isIpLiteral) { + $domain = new Domain($host); + if (!$domain->isKnown()) { + throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); + } + } + + $hostnameValidator = new PublicHostname(); + if (!$hostnameValidator->isValid($host)) { + throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED, $hostnameValidator->getDescription()); + } + + $client = new Client(); + try { + $res = $client + ->setAllowRedirects(true) + ->fetch($gravatarUrl); + } catch (\Throwable) { + throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); + } + + if ($res->getStatusCode() === 404) { + throw new Exception(Exception::AVATAR_IMAGE_NOT_FOUND); + } + + if ($res->getStatusCode() !== 200) { + throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); + } + + try { + $image = new Image($res->getBody()); + } catch (\ImagickException) { + throw new Exception(Exception::AVATAR_IMAGE_NOT_FOUND); + } + + $image->crop($width, $height); + $data = $image->output('png', 80); + + $response + ->addHeader('Cache-Control', 'private, max-age=2592000') // 30 days + ->setContentType('image/png') + ->file($data); + unset($image); + } +} diff --git a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php index c462b25ca9..f6b076608b 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php @@ -6,6 +6,7 @@ use Appwrite\Platform\Modules\Avatars\Http\Browsers\Get as GetBrowser; use Appwrite\Platform\Modules\Avatars\Http\CreditCards\Get as GetCreditCard; use Appwrite\Platform\Modules\Avatars\Http\Favicon\Get as GetFavicon; use Appwrite\Platform\Modules\Avatars\Http\Flags\Get as GetFlag; +use Appwrite\Platform\Modules\Avatars\Http\Gravatar\Get as GetGravatar; use Appwrite\Platform\Modules\Avatars\Http\Image\Get as GetImage; use Appwrite\Platform\Modules\Avatars\Http\Initials\Get as GetInitials; use Appwrite\Platform\Modules\Avatars\Http\QR\Get as GetQR; @@ -26,5 +27,6 @@ class Http extends Service $this->addAction(GetQR::getName(), new GetQR()); $this->addAction(GetInitials::getName(), new GetInitials()); $this->addAction(GetScreenshot::getName(), new GetScreenshot()); + $this->addAction(GetGravatar::getName(), new GetGravatar()); } } diff --git a/tests/e2e/Services/Avatars/AvatarsBase.php b/tests/e2e/Services/Avatars/AvatarsBase.php index 9a65b8070f..b096ca5a4a 100644 --- a/tests/e2e/Services/Avatars/AvatarsBase.php +++ b/tests/e2e/Services/Avatars/AvatarsBase.php @@ -1342,4 +1342,107 @@ trait AvatarsBase return []; } + + public function testGetGravatar(): array + { + /** + * Test for SUCCESS + */ + + // Explicit email param — uses eldad@appwrite.io (known Gravatar, stable for testing) + $this->assertEventually(function () { + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'eldad@appwrite.io', + 'width' => 200, + 'height' => 200, + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + }, 30_000, 2_000); + + // Default size with identicon — deterministic for any unknown email + $this->assertEventually(function () { + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'no-gravatar-' . \uniqid() . '@example.com', + 'default' => 'identicon', + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + }, 30_000, 2_000); + + // Session-based default: no email param, uses current user's email. + // Only meaningful in client/console mode where $user is populated. + if ($this->getSide() === 'client') { + $this->assertEventually(function () { + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), []); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + }, 30_000, 2_000); + } + + /** + * Test for FAILURE + */ + + // Invalid email format → 400 (rejected by Email validator before action runs) + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'not-an-email', + ]); + $this->assertEquals(400, $response['headers']['status-code']); + + // Out-of-range width → 400 + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'eldad@appwrite.io', + 'width' => 2049, + ]); + $this->assertEquals(400, $response['headers']['status-code']); + + // Invalid default → 400 + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'eldad@appwrite.io', + 'default' => 'invalid', + ]); + $this->assertEquals(400, $response['headers']['status-code']); + + // Invalid rating → 400 + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'eldad@appwrite.io', + 'rating' => 'invalid', + ]); + $this->assertEquals(400, $response['headers']['status-code']); + + // default=404 with unknown email → 404 with avatar_image_not_found + $this->assertEventually(function () { + $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + 'x-appwrite-project' => $this->getProject()['$id'], + ], [ + 'email' => 'no-gravatar-' . \uniqid() . '@example.com', + 'default' => '404', + ]); + $this->assertEquals(404, $response['headers']['status-code']); + $this->assertEquals(Exception::AVATAR_IMAGE_NOT_FOUND, $response['body']['type']); + }, 30_000, 2_000); + + return []; + } } From e38831ad2b3634b667c3f4862a0c0c2a83530513 Mon Sep 17 00:00:00 2001 From: imtia33 Date: Mon, 17 Aug 2026 16:18:25 +0600 Subject: [PATCH 02/53] update: apply maintainer feedback for caching --- src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php index 0015e46cfb..05f3fac0ad 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php @@ -39,9 +39,6 @@ class Get extends Action ->desc('Get user Gravatar') ->groups(['api', 'avatars']) ->label('scope', 'avatars.read') - ->label('cache', true) - ->label('cache.resource', 'avatar/gravatar') - ->label('cache.params', ['email', 'width', 'height', 'default', 'rating', 'project']) ->label('sdk', new Method( namespace: 'avatars', group: null, @@ -144,7 +141,7 @@ class Get extends Action $data = $image->output('png', 80); $response - ->addHeader('Cache-Control', 'private, max-age=2592000') // 30 days + ->addHeader('Cache-Control', 'public, max-age=60') // 1 minute ->setContentType('image/png') ->file($data); unset($image); From 4eb87992f78f89a730a170ef399ea63f5e2f835d Mon Sep 17 00:00:00 2001 From: imtia33 Date: Mon, 17 Aug 2026 16:37:21 +0600 Subject: [PATCH 03/53] fix: change cache-control to private to prevent CDN session leakage --- src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php index 05f3fac0ad..e54d5398d2 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php @@ -141,7 +141,7 @@ class Get extends Action $data = $image->output('png', 80); $response - ->addHeader('Cache-Control', 'public, max-age=60') // 1 minute + ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute ->setContentType('image/png') ->file($data); unset($image); From b763a4dbbf1f25ebd38fa8dbd6a73a9d3d4d47c1 Mon Sep 17 00:00:00 2001 From: imtia33 Date: Mon, 17 Aug 2026 18:22:52 +0600 Subject: [PATCH 04/53] refactor: apply feedback for gravatar implementation --- docs/references/avatars/get-gravatar.md | 5 -- .../Modules/Avatars/Http/Gravatar/Get.php | 47 ++----------------- tests/e2e/Services/Avatars/AvatarsBase.php | 15 ++---- 3 files changed, 7 insertions(+), 60 deletions(-) delete mode 100644 docs/references/avatars/get-gravatar.md diff --git a/docs/references/avatars/get-gravatar.md b/docs/references/avatars/get-gravatar.md deleted file mode 100644 index df10dfb192..0000000000 --- a/docs/references/avatars/get-gravatar.md +++ /dev/null @@ -1,5 +0,0 @@ -Use this endpoint to fetch a user's Gravatar avatar image. Gravatar is a globally-recognized avatar service that returns an avatar based on the SHA-256 hash of a user's email address. - -Pass an `email` address to fetch the Gravatar for that address, or leave it empty to use the currently signed-in user's email. If neither an `email` param nor an active session is provided, the request will fail. - -When the email has no associated Gravatar, the `default` parameter controls what is returned (e.g., a generated identicon, the mystery-person silhouette, or a `404` error). diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php index e54d5398d2..e5e365f0ca 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php @@ -28,7 +28,7 @@ class Get extends Action public static function getName(): string { - return 'getGravatar'; + return 'getAvatarsGravatar'; } public function __construct() @@ -43,7 +43,7 @@ class Get extends Action namespace: 'avatars', group: null, name: 'getGravatar', - description: '/docs/references/avatars/get-gravatar.md', + description: 'You can use this endpoint to show a Gravatar image for a user by providing their email address. If no email is provided, the Gravatar for the currently authenticated user is returned. The fallback image and maximum rating can be customized.', auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], type: MethodType::LOCATION, locationAuth: ['Project', 'ImpersonateUserId'], @@ -56,8 +56,6 @@ class Get extends Action contentType: ContentType::IMAGE )) ->param('email', '', new Email(), 'Email address. Pass an email address to fetch the Gravatar image for. When empty, the current user\'s email is used.', true) - ->param('width', 80, new Range(1, 2048), 'Image width. Pass an integer between 1 to 2048. Defaults to 80.', true) - ->param('height', 80, new Range(1, 2048), 'Image height. Pass an integer between 1 to 2048. Defaults to 80.', true) ->param('default', 'mp', new WhiteList(['404', 'mp', 'identicon', 'monsterid', 'wavatar', 'retro', 'robohash', 'blank'], true), 'Default image to return when no Gravatar is found. Defaults to \'mp\'.', true) ->param('rating', 'g', new WhiteList(['g', 'pg', 'r', 'x'], true), 'Maximum image rating to return. Defaults to \'g\'.', true) ->inject('response') @@ -67,17 +65,11 @@ class Get extends Action public function action( string $email, - int $width, - int $height, string $default, string $rating, Response $response, Document $user, ): void { - if (!\extension_loaded('imagick')) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Imagick extension is missing'); - } - // Resolve the email: explicit param takes priority, then current user's email. // If neither is available, the caller must supply one or be signed in. if (!empty($email)) { @@ -91,28 +83,7 @@ class Get extends Action // Gravatar spec: SHA-256 of strtolower(trim($email)) $hash = \hash('sha256', \strtolower(\trim($resolvedEmail))); - $gravatarUrl = \sprintf( - 'https://www.gravatar.com/avatar/%s?s=%d&d=%s&r=%s', - $hash, - $width, - \urlencode($default), - \urlencode($rating), - ); - - $host = \parse_url($gravatarUrl, PHP_URL_HOST) ?? ''; - - $isIpLiteral = \filter_var(\trim($host, '[]'), FILTER_VALIDATE_IP) !== false; - if (!$isIpLiteral) { - $domain = new Domain($host); - if (!$domain->isKnown()) { - throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); - } - } - - $hostnameValidator = new PublicHostname(); - if (!$hostnameValidator->isValid($host)) { - throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED, $hostnameValidator->getDescription()); - } + $gravatarUrl = 'https://www.gravatar.com/avatar/' . $hash . '?s=256&d=' . \urlencode($default) . '&r=' . \urlencode($rating); $client = new Client(); try { @@ -131,19 +102,9 @@ class Get extends Action throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); } - try { - $image = new Image($res->getBody()); - } catch (\ImagickException) { - throw new Exception(Exception::AVATAR_IMAGE_NOT_FOUND); - } - - $image->crop($width, $height); - $data = $image->output('png', 80); - $response ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute ->setContentType('image/png') - ->file($data); - unset($image); + ->file($res->getBody()); } } diff --git a/tests/e2e/Services/Avatars/AvatarsBase.php b/tests/e2e/Services/Avatars/AvatarsBase.php index b096ca5a4a..25691bafc0 100644 --- a/tests/e2e/Services/Avatars/AvatarsBase.php +++ b/tests/e2e/Services/Avatars/AvatarsBase.php @@ -1355,13 +1355,12 @@ trait AvatarsBase 'x-appwrite-project' => $this->getProject()['$id'], ], [ 'email' => 'eldad@appwrite.io', - 'width' => 200, - 'height' => 200, ]); $this->assertEquals(200, $response['headers']['status-code']); $this->assertEquals('image/png', $response['headers']['content-type']); $this->assertNotEmpty($response['body']); + $this->assertEquals('c37bfe56394ab0f359cb3977eb2ada39', \md5($response['body'])); }, 30_000, 2_000); // Default size with identicon — deterministic for any unknown email @@ -1369,13 +1368,14 @@ trait AvatarsBase $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ 'x-appwrite-project' => $this->getProject()['$id'], ], [ - 'email' => 'no-gravatar-' . \uniqid() . '@example.com', + 'email' => 'no-gravatar-test@example.com', 'default' => 'identicon', ]); $this->assertEquals(200, $response['headers']['status-code']); $this->assertEquals('image/png', $response['headers']['content-type']); $this->assertNotEmpty($response['body']); + $this->assertEquals('5b8f150824ca586569a2606b41a16c6f', \md5($response['body'])); }, 30_000, 2_000); // Session-based default: no email param, uses current user's email. @@ -1404,15 +1404,6 @@ trait AvatarsBase ]); $this->assertEquals(400, $response['headers']['status-code']); - // Out-of-range width → 400 - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ - 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'eldad@appwrite.io', - 'width' => 2049, - ]); - $this->assertEquals(400, $response['headers']['status-code']); - // Invalid default → 400 $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ 'x-appwrite-project' => $this->getProject()['$id'], From e8dd33f5b67e476ec0b53ad469a5ff825ae6c2c0 Mon Sep 17 00:00:00 2001 From: imtia33 Date: Mon, 17 Aug 2026 21:39:31 +0600 Subject: [PATCH 05/53] Moved to new provider architecture for custom avatar --- .../AvatarPhotos/Gravatar/Provider.php | 53 +++++ .../AvatarPhotos/Initials/Provider.php | 107 ++++++++++ .../AvatarPhotos/Libavatar/Provider.php | 60 ++++++ src/Appwrite/AvatarPhotos/Photo.php | 133 +++++++++++++ src/Appwrite/AvatarPhotos/Static/Provider.php | 68 +++++++ .../Modules/Avatars/Http/Gravatar/Get.php | 110 ----------- .../Modules/Avatars/Http/Photo/Get.php | 103 ++++++++++ .../Modules/Avatars/Services/Http.php | 6 +- tests/e2e/Services/Avatars/AvatarsBase.php | 186 ++++++++++++------ 9 files changed, 649 insertions(+), 177 deletions(-) create mode 100644 src/Appwrite/AvatarPhotos/Gravatar/Provider.php create mode 100644 src/Appwrite/AvatarPhotos/Initials/Provider.php create mode 100644 src/Appwrite/AvatarPhotos/Libavatar/Provider.php create mode 100644 src/Appwrite/AvatarPhotos/Photo.php create mode 100644 src/Appwrite/AvatarPhotos/Static/Provider.php delete mode 100644 src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php create mode 100644 src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php diff --git a/src/Appwrite/AvatarPhotos/Gravatar/Provider.php b/src/Appwrite/AvatarPhotos/Gravatar/Provider.php new file mode 100644 index 0000000000..c4fabd19b2 --- /dev/null +++ b/src/Appwrite/AvatarPhotos/Gravatar/Provider.php @@ -0,0 +1,53 @@ +setAllowRedirects(true) + ->fetch($url); + } catch (\Throwable) { + return null; + } + + if ($res->getStatusCode() !== 200) { + return null; + } + + $body = $res->getBody(); + if (empty($body)) { + return null; + } + + return $body; + } +} diff --git a/src/Appwrite/AvatarPhotos/Initials/Provider.php b/src/Appwrite/AvatarPhotos/Initials/Provider.php new file mode 100644 index 0000000000..d98916c5a0 --- /dev/null +++ b/src/Appwrite/AvatarPhotos/Initials/Provider.php @@ -0,0 +1,107 @@ + '#FD366E'], // Pink + ['background' => '#FE9567'], // Orange + ['background' => '#7C67FE'], // Purple + ['background' => '#68A3FE'], // Blue + ['background' => '#85DBD8'], // Mint + ]; + + public function __construct(string $appRoot) + { + $this->appRoot = $appRoot; + } + + /** + * Generate an initials avatar image. + * + * @param string $name Full name or email to derive initials from. + * When empty or blank, returns null so the caller + * moves on to the next (static fallback) provider. + * @param int $width Canvas width in pixels. + * @param int $height Canvas height in pixels. + * @param string $background Optional hex colour (without #). Empty = auto. + * @return string|null Raw PNG bytes, or null when no name/email is available. + */ + public function get(string $name, int $width = 500, int $height = 500, string $background = ''): ?string + { + if (empty(\trim($name))) { + return null; + } + + $words = \explode(' ', \strtoupper($name)); + // Fallback: split on underscores when there is no space + $words = (\count($words) === 1) ? \explode('_', \strtoupper($name)) : $words; + + $initials = ''; + $code = 0; + + foreach ($words as $key => $w) { + if (\ctype_alnum($w[0] ?? '')) { + $initials .= $w[0]; + $code += \ord($w[0]); + + if ($key === 1) { + break; + } + } + } + + // If we still have no printable initials, bail out so the static + // fallback can be used instead. + if (empty($initials)) { + return null; + } + + $rand = (int) \substr((string) $code, -1); + $rand = ($rand > \count($this->themes) - 1) ? $rand % \count($this->themes) : $rand; + + $bg = (!empty($background)) ? '#' . \ltrim($background, '#') : $this->themes[$rand]['background']; + + $image = new Imagick(); + $punch = new Imagick(); + $draw = new ImagickDraw(); + + $fontSize = \min($width, $height) / 2; + + $punch->newImage($width, $height, 'transparent'); + + $fontPath = $this->appRoot . '/app/assets/fonts/inter-v8-latin-regular.woff2'; + $draw->setFont($fontPath); + $image->setFont($fontPath); + + $draw->setFillColor(new ImagickPixel('black')); + $draw->setFontSize($fontSize); + $draw->setTextAlignment(Imagick::ALIGN_CENTER); + $draw->annotation($width / 1.97, ($height / 2) + ($fontSize / 3), $initials); + + $punch->drawImage($draw); + $punch->negateImage(true, Imagick::CHANNEL_ALPHA); + + $image->newImage($width, $height, $bg); + $image->setImageFormat('png'); + $image->compositeImage($punch, Imagick::COMPOSITE_COPYOPACITY, 0, 0); + + return $image->getImageBlob(); + } +} diff --git a/src/Appwrite/AvatarPhotos/Libavatar/Provider.php b/src/Appwrite/AvatarPhotos/Libavatar/Provider.php new file mode 100644 index 0000000000..cd9a6e2332 --- /dev/null +++ b/src/Appwrite/AvatarPhotos/Libavatar/Provider.php @@ -0,0 +1,60 @@ +setAllowRedirects(true) + ->fetch($url); + } catch (\Throwable) { + return null; + } + + if ($res->getStatusCode() !== 200) { + return null; + } + + $body = $res->getBody(); + if (empty($body)) { + return null; + } + + return $body; + } +} diff --git a/src/Appwrite/AvatarPhotos/Photo.php b/src/Appwrite/AvatarPhotos/Photo.php new file mode 100644 index 0000000000..6788e9c1a4 --- /dev/null +++ b/src/Appwrite/AvatarPhotos/Photo.php @@ -0,0 +1,133 @@ +gravatar = new GravatarProvider(); + $this->libavatar = new LibavatarProvider(); + $this->initials = new InitialsProvider($appRoot); + $this->static = new StaticProvider(); + } + + /** + * Resolve and return the best available avatar for the given user data. + * + * @param string $email User's email address (may be empty). + * @param string $name User's display name (may be empty). + * @param int $width Desired output width in pixels. + * @param int $height Desired output height in pixels. + * @param int $quality Output quality 0–100. + * @param string $output Output format: 'png' | 'jpg' | 'webp'. + * @param string $rating Gravatar/Libravatar rating: 'g' | 'pg' | 'r' | 'x'. + * @param string $background Optional hex background for the Initials provider. + * @return string Raw image bytes in the requested $output format. + */ + public function resolve( + string $email, + string $name, + int $width = 256, + int $height = 256, + int $quality = 100, + string $output = 'png', + string $rating = 'g', + string $background = '', + ): string { + // ------------------------------------------------------------------- + // Priority 1: OAuth2 session photo + // TODO: Resolve profile photo from the user's active OAuth2 token. + // Each OAuth2 provider (Google, GitHub, …) exposes a profile- + // picture URL. Fetch it here and short-circuit the chain. + // Track in: https://github.com/appwrite/appwrite/issues/TODO + // ------------------------------------------------------------------- + + // ------------------------------------------------------------------- + // Priority 2: Gravatar + // ------------------------------------------------------------------- + if (!empty($email)) { + $raw = $this->gravatar->get($email, $rating); + if ($raw !== null) { + return $this->process($raw, $width, $height, $quality, $output); + } + } + + // ------------------------------------------------------------------- + // Priority 3: Libravatar + // ------------------------------------------------------------------- + if (!empty($email)) { + $raw = $this->libavatar->get($email, $rating); + if ($raw !== null) { + return $this->process($raw, $width, $height, $quality, $output); + } + } + + // ------------------------------------------------------------------- + // Priority 4: Initials + // Prefer name; fall back to email prefix when name is absent. + // ------------------------------------------------------------------- + $initialsInput = !empty($name) ? $name : $email; + if (!empty($initialsInput)) { + $raw = $this->initials->get($initialsInput, $width, $height, $background); + if ($raw !== null) { + // Initials PNG is already sized correctly — just re-encode if + // a different format or quality was requested. + return $this->process($raw, $width, $height, $quality, $output); + } + } + + // ------------------------------------------------------------------- + // Priority 5: Static fallback — always succeeds + // ------------------------------------------------------------------- + $raw = $this->static->get($width, $height); + return $this->process($raw, $width, $height, $quality, $output); + } + + /** + * Resize and re-encode raw image bytes. + */ + private function process(string $raw, int $width, int $height, int $quality, string $output): string + { + if (!\extension_loaded('imagick') || empty($raw)) { + return $raw; + } + + try { + $image = new Image($raw); + if ($width > 0 || $height > 0) { + $image->crop( + $width > 0 ? $width : 256, + $height > 0 ? $height : 256, + ); + } + return $image->output($output, $quality); + } catch (\Throwable) { + return $raw; + } + } +} diff --git a/src/Appwrite/AvatarPhotos/Static/Provider.php b/src/Appwrite/AvatarPhotos/Static/Provider.php new file mode 100644 index 0000000000..f9af02a083 --- /dev/null +++ b/src/Appwrite/AvatarPhotos/Static/Provider.php @@ -0,0 +1,68 @@ +buildSvg($width, $height); + + if (\extension_loaded('imagick')) { + try { + $imagick = new \Imagick(); + $imagick->setBackgroundColor(new \ImagickPixel('transparent')); + $imagick->readImageBlob($svg); + $imagick->setImageFormat('png'); + $imagick->resizeImage($width, $height, \Imagick::FILTER_LANCZOS, 1); + return $imagick->getImageBlob(); + } catch (\Throwable) { + // Fall through to raw SVG on Imagick failure. + } + } + + // Last resort: return the SVG bytes directly. The HTTP action sets + // the content-type header to image/png, so this branch should be + // considered a degraded path. + return $svg; + } + + /** + * Build the SVG source for the fallback silhouette. + */ + private function buildSvg(int $width, int $height): string + { + return << + + + + + + +SVG; + } +} diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php deleted file mode 100644 index e5e365f0ca..0000000000 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Gravatar/Get.php +++ /dev/null @@ -1,110 +0,0 @@ -setHttpMethod(UtopiaAction::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/avatars/gravatar') - ->desc('Get user Gravatar') - ->groups(['api', 'avatars']) - ->label('scope', 'avatars.read') - ->label('sdk', new Method( - namespace: 'avatars', - group: null, - name: 'getGravatar', - description: 'You can use this endpoint to show a Gravatar image for a user by providing their email address. If no email is provided, the Gravatar for the currently authenticated user is returned. The fallback image and maximum rating can be customized.', - auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], - type: MethodType::LOCATION, - locationAuth: ['Project', 'ImpersonateUserId'], - responses: [ - new SDKResponse( - code: Response::STATUS_CODE_OK, - model: Response::MODEL_NONE, - ) - ], - contentType: ContentType::IMAGE - )) - ->param('email', '', new Email(), 'Email address. Pass an email address to fetch the Gravatar image for. When empty, the current user\'s email is used.', true) - ->param('default', 'mp', new WhiteList(['404', 'mp', 'identicon', 'monsterid', 'wavatar', 'retro', 'robohash', 'blank'], true), 'Default image to return when no Gravatar is found. Defaults to \'mp\'.', true) - ->param('rating', 'g', new WhiteList(['g', 'pg', 'r', 'x'], true), 'Maximum image rating to return. Defaults to \'g\'.', true) - ->inject('response') - ->inject('user') - ->callback($this->action(...)); - } - - public function action( - string $email, - string $default, - string $rating, - Response $response, - Document $user, - ): void { - // Resolve the email: explicit param takes priority, then current user's email. - // If neither is available, the caller must supply one or be signed in. - if (!empty($email)) { - $resolvedEmail = $email; - } elseif (!$user->isEmpty()) { - $resolvedEmail = $user->getAttribute('email', ''); - } else { - throw new Exception(Exception::GENERAL_BAD_REQUEST, 'Either the \'email\' param or an active session is required.'); - } - - // Gravatar spec: SHA-256 of strtolower(trim($email)) - $hash = \hash('sha256', \strtolower(\trim($resolvedEmail))); - - $gravatarUrl = 'https://www.gravatar.com/avatar/' . $hash . '?s=256&d=' . \urlencode($default) . '&r=' . \urlencode($rating); - - $client = new Client(); - try { - $res = $client - ->setAllowRedirects(true) - ->fetch($gravatarUrl); - } catch (\Throwable) { - throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); - } - - if ($res->getStatusCode() === 404) { - throw new Exception(Exception::AVATAR_IMAGE_NOT_FOUND); - } - - if ($res->getStatusCode() !== 200) { - throw new Exception(Exception::AVATAR_REMOTE_URL_FAILED); - } - - $response - ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute - ->setContentType('image/png') - ->file($res->getBody()); - } -} diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php new file mode 100644 index 0000000000..1134147729 --- /dev/null +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php @@ -0,0 +1,103 @@ +setHttpMethod(UtopiaAction::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/avatars/photo') + ->desc('Get user photo') + ->groups(['api', 'avatars']) + ->label('scope', 'avatars.read') + ->label('sdk', new Method( + namespace: 'avatars', + group: null, + name: 'getPhoto', + description: 'Returns the best available profile photo for the currently authenticated user. ' + . 'The endpoint tries each source in priority order and returns the first successful result: ' + . '(1) OAuth2 session photo (planned — see TODO in source), ' + . '(2) Gravatar, ' + . '(3) Libravatar, ' + . '(4) initials generated from the user\'s name or email, ' + . '(5) a built-in static fallback image.', + auth: [AuthType::ADMIN, AuthType::SESSION, AuthType::KEY, AuthType::JWT], + type: MethodType::LOCATION, + locationAuth: ['Project', 'ImpersonateUserId'], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_NONE, + ) + ], + contentType: ContentType::IMAGE + )) + ->param('width', 256, new Range(0, 2000), 'Output image width in pixels. Pass an integer between 0 and 2000. Defaults to 256.', true) + ->param('height', 256, new Range(0, 2000), 'Output image height in pixels. Pass an integer between 0 and 2000. Defaults to 256.', true) + ->param('quality', 100, new Range(0, 100), 'Output image quality between 0 and 100. Defaults to 100.', true) + ->param('output', 'png', new WhiteList(['png', 'jpg', 'webp'], true), 'Output image format. Defaults to \'png\'.', true) + ->param('rating', 'g', new WhiteList(['g', 'pg', 'r', 'x'], true), 'Maximum image rating to fetch from Gravatar/Libravatar. Defaults to \'g\'.', true) + ->inject('response') + ->inject('user') + ->callback($this->action(...)); + } + + public function action( + int $width, + int $height, + int $quality, + string $output, + string $rating, + Response $response, + Document $user, + ): void { + $email = $user->getAttribute('email', ''); + $name = $user->getAttribute('name', ''); + + $photo = new Photo($this->getAppRoot()); + + $data = $photo->resolve( + email: $email, + name: $name, + width: $width, + height: $height, + quality: $quality, + output: $output, + rating: $rating, + ); + + $contentType = match ($output) { + 'jpg' => 'image/jpeg', + 'webp' => 'image/webp', + default => 'image/png', + }; + + $response + ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute — photo may change + ->setContentType($contentType) + ->file($data); + } +} diff --git a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php index f6b076608b..24c57cba8d 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php @@ -6,7 +6,8 @@ use Appwrite\Platform\Modules\Avatars\Http\Browsers\Get as GetBrowser; use Appwrite\Platform\Modules\Avatars\Http\CreditCards\Get as GetCreditCard; use Appwrite\Platform\Modules\Avatars\Http\Favicon\Get as GetFavicon; use Appwrite\Platform\Modules\Avatars\Http\Flags\Get as GetFlag; -use Appwrite\Platform\Modules\Avatars\Http\Gravatar\Get as GetGravatar; + +use Appwrite\Platform\Modules\Avatars\Http\Photo\Get as GetPhoto; use Appwrite\Platform\Modules\Avatars\Http\Image\Get as GetImage; use Appwrite\Platform\Modules\Avatars\Http\Initials\Get as GetInitials; use Appwrite\Platform\Modules\Avatars\Http\QR\Get as GetQR; @@ -27,6 +28,7 @@ class Http extends Service $this->addAction(GetQR::getName(), new GetQR()); $this->addAction(GetInitials::getName(), new GetInitials()); $this->addAction(GetScreenshot::getName(), new GetScreenshot()); - $this->addAction(GetGravatar::getName(), new GetGravatar()); + + $this->addAction(GetPhoto::getName(), new GetPhoto()); } } diff --git a/tests/e2e/Services/Avatars/AvatarsBase.php b/tests/e2e/Services/Avatars/AvatarsBase.php index 25691bafc0..027b8fd516 100644 --- a/tests/e2e/Services/Avatars/AvatarsBase.php +++ b/tests/e2e/Services/Avatars/AvatarsBase.php @@ -1343,96 +1343,152 @@ trait AvatarsBase return []; } - public function testGetGravatar(): array + + + public function testGetPhoto(): array { /** - * Test for SUCCESS + * Test for SUCCESS — authenticated user (client side) + * + * The endpoint always returns an image: even when no Gravatar/Libravatar + * avatar exists it falls back to initials or the static placeholder, so + * we always expect HTTP 200. */ - // Explicit email param — uses eldad@appwrite.io (known Gravatar, stable for testing) - $this->assertEventually(function () { - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ - 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'eldad@appwrite.io', - ]); + // Default call — uses session user; falls through priority chain and + // returns some image (initials or static fallback at minimum). + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), []); - $this->assertEquals(200, $response['headers']['status-code']); - $this->assertEquals('image/png', $response['headers']['content-type']); - $this->assertNotEmpty($response['body']); - $this->assertEquals('c37bfe56394ab0f359cb3977eb2ada39', \md5($response['body'])); - }, 30_000, 2_000); + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); - // Default size with identicon — deterministic for any unknown email - $this->assertEventually(function () { - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ - 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'no-gravatar-test@example.com', - 'default' => 'identicon', - ]); + // Width + height + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'width' => 128, + 'height' => 128, + ]); - $this->assertEquals(200, $response['headers']['status-code']); - $this->assertEquals('image/png', $response['headers']['content-type']); - $this->assertNotEmpty($response['body']); - $this->assertEquals('5b8f150824ca586569a2606b41a16c6f', \md5($response['body'])); - }, 30_000, 2_000); + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); - // Session-based default: no email param, uses current user's email. - // Only meaningful in client/console mode where $user is populated. - if ($this->getSide() === 'client') { - $this->assertEventually(function () { - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', \array_merge([ - 'x-appwrite-project' => $this->getProject()['$id'], - ], $this->getHeaders()), []); + // Quality param + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'width' => 200, + 'height' => 200, + 'quality' => 50, + ]); - $this->assertEquals(200, $response['headers']['status-code']); - $this->assertEquals('image/png', $response['headers']['content-type']); - $this->assertNotEmpty($response['body']); - }, 30_000, 2_000); - } + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertNotEmpty($response['body']); + + // Output format: webp + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'output' => 'webp', + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/webp', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + + // Output format: jpg + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'output' => 'jpg', + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/jpeg', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + + // Rating param + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'rating' => 'pg', + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertNotEmpty($response['body']); /** - * Test for FAILURE + * Test for SUCCESS — Gravatar flow + * + * Use a well-known email that has a real Gravatar so we can verify the + * provider is actually being reached. Wrapped in assertEventually to + * tolerate transient network hiccups. + * + * TODO: Once the OAuth2 session photo is implemented, add a test that + * verifies priority 1 takes precedence over Gravatar. + */ + $this->assertEventually(function () { + // When we have a Gravatar for the user's email the chain resolves at + // priority 2; result must be a non-trivial PNG. + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'width' => 256, + 'height' => 256, + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('image/png', $response['headers']['content-type']); + $this->assertNotEmpty($response['body']); + }, 30_000, 2_000); + + /** + * Test for FAILURE — invalid params */ - // Invalid email format → 400 (rejected by Email validator before action runs) - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + // Width out of range + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'not-an-email', + ], $this->getHeaders()), [ + 'width' => 2001, ]); $this->assertEquals(400, $response['headers']['status-code']); - // Invalid default → 400 - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + // Height out of range + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'eldad@appwrite.io', - 'default' => 'invalid', + ], $this->getHeaders()), [ + 'height' => 2001, ]); $this->assertEquals(400, $response['headers']['status-code']); - // Invalid rating → 400 - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ + // Quality out of range + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'eldad@appwrite.io', - 'rating' => 'invalid', + ], $this->getHeaders()), [ + 'quality' => 101, ]); $this->assertEquals(400, $response['headers']['status-code']); - // default=404 with unknown email → 404 with avatar_image_not_found - $this->assertEventually(function () { - $response = $this->client->call(Client::METHOD_GET, '/avatars/gravatar', [ - 'x-appwrite-project' => $this->getProject()['$id'], - ], [ - 'email' => 'no-gravatar-' . \uniqid() . '@example.com', - 'default' => '404', - ]); - $this->assertEquals(404, $response['headers']['status-code']); - $this->assertEquals(Exception::AVATAR_IMAGE_NOT_FOUND, $response['body']['type']); - }, 30_000, 2_000); + // Invalid output format + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'output' => 'bmp', + ]); + $this->assertEquals(400, $response['headers']['status-code']); + + // Invalid rating + $response = $this->client->call(Client::METHOD_GET, '/avatars/photo', \array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'rating' => 'xx', + ]); + $this->assertEquals(400, $response['headers']['status-code']); return []; } From dfd64e5ac11e8ee61f70317112d5a34d5d42fcbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 09:58:48 +0200 Subject: [PATCH 06/53] Add codebase VCS endpoints --- app/config/variables.php | 18 +++ docker-compose.yml | 3 + .../vcs/create-codebase-installation.md | 1 + .../VCS/Http/Codebase/Authorize/Get.php | 97 +++++++++++++ .../VCS/Http/Codebase/Callback/Get.php | 137 ++++++++++++++++++ .../VCS/Http/Codebase/Events/Create.php | 46 ++++++ .../Platform/Modules/VCS/Services/Http.php | 8 + 7 files changed, 310 insertions(+) create mode 100644 docs/references/vcs/create-codebase-installation.md create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php diff --git a/app/config/variables.php b/app/config/variables.php index 7e32f6ea16..346f9bcc59 100644 --- a/app/config/variables.php +++ b/app/config/variables.php @@ -1392,6 +1392,24 @@ return [ 'question' => '', 'filter' => '' ], + [ + 'name' => '_APP_VCS_CODEBASE_CLIENT_ID', + 'description' => 'Codebase app client ID. You can find it in your Codebase app details on Cursor.', + 'introduction' => '2.0.0', + 'default' => '', + 'required' => false, + 'question' => '', + 'filter' => '' + ], + [ + 'name' => '_APP_VCS_CODEBASE_PRIVATE_KEY', + 'description' => 'Codebase app private key. You can generate private keys from your Codebase app settings on Cursor.', + 'introduction' => '2.0.0', + 'default' => '', + 'required' => false, + 'question' => '', + 'filter' => '' + ], [ 'name' => '_APP_VCS_WEBHOOK_URL', 'description' => 'Base URL Appwrite advertises to self-hosted VCS providers when registering repository webhooks, if different from the public domain (e.g. a Docker-internal address). Falls back to the public domain when unset.', diff --git a/docker-compose.yml b/docker-compose.yml index 493b597c62..1372bca12a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -210,6 +210,8 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET + - _APP_VCS_CODEBASE_CLIENT_ID + - _APP_VCS_CODEBASE_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_MIGRATIONS_FIREBASE_CLIENT_ID - _APP_MIGRATIONS_FIREBASE_CLIENT_SECRET @@ -512,6 +514,7 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET + - _APP_VCS_CODEBASE_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_FUNCTIONS_TIMEOUT - _APP_SITES_TIMEOUT diff --git a/docs/references/vcs/create-codebase-installation.md b/docs/references/vcs/create-codebase-installation.md new file mode 100644 index 0000000000..5fcff97be9 --- /dev/null +++ b/docs/references/vcs/create-codebase-installation.md @@ -0,0 +1 @@ +Begin Appwrite's Codebase app installation to set up version control integration. This endpoint responds with a redirect URL to the Codebase app's installation page on Cursor. The Codebase app must be configured in your environment for this endpoint to work. \ No newline at end of file diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php new file mode 100644 index 0000000000..97e3dd6d60 --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -0,0 +1,97 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/vcs/codebase/authorize') + ->desc('Create Codebase app installation') + ->groups(['api', 'vcs']) + ->label('scope', 'vcs.read') + ->label('error', APP_VIEWS_DIR . '/general/error.phtml') + ->label('sdk', new Method( + namespace: 'vcs', + group: 'installations', + name: 'createCodebaseInstallation', + description: '/docs/references/vcs/create-codebase-installation.md', + auth: [AuthType::ADMIN], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_MOVED_PERMANENTLY, + model: Response::MODEL_NONE, + ) + ], + contentType: ContentType::HTML, + type: MethodType::WEBAUTH, + // 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']) + ->inject('response') + ->inject('project') + ->inject('platform') + ->callback($this->action(...)); + } + + public function action( + string $success, + string $failure, + Response $response, + Document $project, + array $platform + ) { + $clientId = System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID'); + + if (empty($clientId)) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Codebase client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); + } + + // The callback endpoint is public and Codebase performs no token + // exchange, so the callback verifies this signature before trusting + // the projectId and redirect URLs in state. + $state = \json_encode([ + 'projectId' => $project->getId(), + 'success' => $success, + 'failure' => $failure, + 'signature' => \hash_hmac('sha256', \json_encode([$project->getId(), $success, $failure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')), + ]); + + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $hostname = $platform['consoleHostname'] ?? ''; + + $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query([ + 'client_id' => $clientId, + 'state' => $state, + 'redirect_uri' => $protocol . '://' . $hostname . '/v1/vcs/codebase/callback', + ]); + + $response + ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') + ->addHeader('Pragma', 'no-cache') + ->redirect($url); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php new file mode 100644 index 0000000000..a0390e3972 --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php @@ -0,0 +1,137 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/vcs/codebase/callback') + ->desc('Get installation from Codebase app') + ->groups(['api', 'vcs']) + ->label('scope', 'public') + ->label('error', APP_VIEWS_DIR . '/general/error.phtml') + ->param('installation_id', '', new Text(256, 0), 'Codebase installation ID', true) + ->param('state', '', new Text(2048), 'Codebase state. Contains info sent when starting the installation flow.', true) + ->inject('response') + ->inject('dbForPlatform') + ->inject('platform') + ->callback($this->action(...)); + } + + public function action( + string $providerInstallationId, + string $state, + Response $response, + Database $dbForPlatform, + array $platform + ) { + if (empty($state)) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing state parameter. Please restart the installation from the Appwrite Console.'); + } + + $state = \json_decode($state, true) ?? []; + $redirectFailure = $state['failure'] ?? ''; + $projectId = $state['projectId'] ?? ''; + + // This endpoint is public and Codebase performs no token exchange -- + // without verifying the signature the Authorize action put in state, + // anyone could pass an arbitrary projectId here and attach an + // installation to another project. + $signature = \hash_hmac('sha256', \json_encode([$projectId, $state['success'] ?? '', $redirectFailure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')); + if (!\hash_equals($signature, $state['signature'] ?? '')) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Invalid state parameter. Please restart the installation from the Appwrite Console.'); + } + + $project = $dbForPlatform->getDocument('projects', $projectId); + + if ($project->isEmpty()) { + $this->failure($response, $redirectFailure, 'Project with the ID from state could not be found.', Exception::PROJECT_NOT_FOUND); + return; + } + + $region = $project->getAttribute('region', 'default'); + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $hostname = $platform['consoleHostname'] ?? ''; + + $defaultState = [ + 'success' => $protocol . '://' . $hostname . "/console/project-$region-$projectId/settings/git-installations", + 'failure' => $protocol . '://' . $hostname . "/console/project-$region-$projectId/settings/git-installations", + ]; + + $state = \array_merge($defaultState, \array_filter($state)); + $redirectSuccess = $state['success'] ?? ''; + $redirectFailure = $state['failure'] ?? ''; + + if (empty($providerInstallationId)) { + $this->failure($response, $redirectFailure, 'Codebase installation ID is missing.'); + return; + } + + $projectInternalId = $project->getSequence(); + + $installation = $dbForPlatform->findOne('installations', [ + Query::equal('providerInstallationId', [$providerInstallationId]), + Query::equal('projectInternalId', [$projectInternalId]), + Query::equal('provider', ['codebase']), + ]); + + if ($installation->isEmpty()) { + $teamId = $project->getAttribute('teamId', ''); + + $dbForPlatform->createDocument('installations', new Document([ + '$id' => ID::unique(), + '$permissions' => $this->getPermissions($teamId, $projectId), + 'providerInstallationId' => $providerInstallationId, + 'projectId' => $projectId, + 'projectInternalId' => $projectInternalId, + 'provider' => 'codebase', + 'organization' => '', + 'personal' => false, + ])); + } + + $response + ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') + ->addHeader('Pragma', 'no-cache') + ->redirect($redirectSuccess); + } + + /** + * Redirect back to the console with an error, or throw when no redirect is available. + */ + private function failure(Response $response, string $redirect, string $error, string $type = Exception::GENERAL_ARGUMENT_INVALID): void + { + if (empty($redirect)) { + throw new Exception($type, $error); + } + + $separator = \str_contains($redirect, '?') ? '&' : '?'; + $response + ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') + ->addHeader('Pragma', 'no-cache') + ->redirect($redirect . $separator . \http_build_query(['error' => $error])); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php new file mode 100644 index 0000000000..432e3fb81d --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php @@ -0,0 +1,46 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_POST) + ->setHttpPath('/v1/vcs/codebase/events') + ->desc('Create event') + ->groups(['api', 'vcs']) + ->label('scope', 'public') + ->inject('request') + ->inject('response') + ->callback($this->action(...)); + } + + public function action( + Request $request, + Response $response + ) { + $payload = \json_decode($request->getRawPayload(), true) ?? []; + + $event = $request->getHeaderLine('x-codebase-event', '') ?: ($payload['event'] ?? ''); + Span::add('vcs.codebase.event.name', $event); + + // Codebase does not deliver push or pull request events yet, so events + // are only acknowledged to prevent delivery retries. + $response->json(['success' => true]); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Services/Http.php b/src/Appwrite/Platform/Modules/VCS/Services/Http.php index e078c8fca0..13a8e5bb74 100644 --- a/src/Appwrite/Platform/Modules/VCS/Services/Http.php +++ b/src/Appwrite/Platform/Modules/VCS/Services/Http.php @@ -5,6 +5,9 @@ namespace Appwrite\Platform\Modules\VCS\Services; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Authorize\Get as GetBitbucketAuthorize; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Callback\Get as GetBitbucketCallback; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Events\Create as CreateBitbucketEvent; +use Appwrite\Platform\Modules\VCS\Http\Codebase\Authorize\Get as GetCodebaseAuthorize; +use Appwrite\Platform\Modules\VCS\Http\Codebase\Callback\Get as GetCodebaseCallback; +use Appwrite\Platform\Modules\VCS\Http\Codebase\Events\Create as CreateCodebaseEvent; use Appwrite\Platform\Modules\VCS\Http\Gitea\Authorize\Get as GetGiteaAuthorize; use Appwrite\Platform\Modules\VCS\Http\Gitea\Callback\Get as GetGiteaCallback; use Appwrite\Platform\Modules\VCS\Http\Gitea\Events\Create as CreateGiteaEvent; @@ -50,6 +53,10 @@ class Http extends Service $this->addAction(GetBitbucketAuthorize::getName(), new GetBitbucketAuthorize()); $this->addAction(GetBitbucketCallback::getName(), new GetBitbucketCallback()); + // Codebase Authorization & Callback + $this->addAction(GetCodebaseAuthorize::getName(), new GetCodebaseAuthorize()); + $this->addAction(GetCodebaseCallback::getName(), new GetCodebaseCallback()); + // Installations $this->addAction(GetInstallation::getName(), new GetInstallation()); $this->addAction(ListInstallations::getName(), new ListInstallations()); @@ -69,5 +76,6 @@ class Http extends Service $this->addAction(CreateGiteaEvent::getName(), new CreateGiteaEvent()); $this->addAction(CreateGitlabEvent::getName(), new CreateGitlabEvent()); $this->addAction(CreateBitbucketEvent::getName(), new CreateBitbucketEvent()); + $this->addAction(CreateCodebaseEvent::getName(), new CreateCodebaseEvent()); } } From 319a7e63a5bd40a7f8226962ad1e7820a475b543 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:00:24 +0200 Subject: [PATCH 07/53] Add extensive logging for debugging purposes --- .../VCS/Http/Codebase/Authorize/Get.php | 5 +++ .../VCS/Http/Codebase/Callback/Get.php | 40 ++++++++++++++++++- .../VCS/Http/Codebase/Events/Create.php | 8 ++++ 3 files changed, 52 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index 97e3dd6d60..8d8cb8ca0c 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -10,6 +10,7 @@ use Appwrite\SDK\Method; use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; +use Utopia\Console; use Utopia\Database\Document; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; @@ -89,6 +90,10 @@ class Get extends Action 'redirect_uri' => $protocol . '://' . $hostname . '/v1/vcs/codebase/callback', ]); + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); + Console::log('[CODEBASE DEBUG] Redirecting to install URL: ' . $url); + $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') ->addHeader('Pragma', 'no-cache') diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php index a0390e3972..5bf3df064c 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php @@ -4,7 +4,9 @@ namespace Appwrite\Platform\Modules\VCS\Http\Codebase\Callback; use Appwrite\Extend\Exception; use Appwrite\Platform\Permission as AppwritePermission; +use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Utopia\Console; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\ID; @@ -35,6 +37,7 @@ class Get extends Action ->label('error', APP_VIEWS_DIR . '/general/error.phtml') ->param('installation_id', '', new Text(256, 0), 'Codebase installation ID', true) ->param('state', '', new Text(2048), 'Codebase state. Contains info sent when starting the installation flow.', true) + ->inject('request') ->inject('response') ->inject('dbForPlatform') ->inject('platform') @@ -44,10 +47,29 @@ class Get extends Action public function action( string $providerInstallationId, string $state, + Request $request, Response $response, Database $dbForPlatform, array $platform ) { + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + $params = $request->getParams(); + Console::log('[CODEBASE DEBUG] Callback received'); + Console::log('[CODEBASE DEBUG] Callback params: ' . \json_encode($params)); + Console::log('[CODEBASE DEBUG] Callback headers: ' . \json_encode($request->getHeaders())); + Console::log('[CODEBASE DEBUG] Callback installation_id: "' . $providerInstallationId . '"'); + + // Surface anything that looks like an OAuth2 token flow (e.g. a code + // exchange), since Codebase is not expected to send one. + $oauthParams = \array_intersect_key($params, \array_flip([ + 'code', 'token', 'access_token', 'refresh_token', 'expires_in', 'token_type', 'scope', 'id_token', 'setup_action', 'authuser', 'session_state', + ])); + if (!empty($oauthParams)) { + Console::log('[CODEBASE DEBUG] Possible OAuth2 flow params detected: ' . \json_encode($oauthParams)); + } else { + Console::log('[CODEBASE DEBUG] No OAuth2 flow params detected'); + } + if (empty($state)) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing state parameter. Please restart the installation from the Appwrite Console.'); } @@ -56,14 +78,20 @@ class Get extends Action $redirectFailure = $state['failure'] ?? ''; $projectId = $state['projectId'] ?? ''; + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] Decoded state: ' . \json_encode($state)); + // This endpoint is public and Codebase performs no token exchange -- // without verifying the signature the Authorize action put in state, // anyone could pass an arbitrary projectId here and attach an // installation to another project. $signature = \hash_hmac('sha256', \json_encode([$projectId, $state['success'] ?? '', $redirectFailure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')); if (!\hash_equals($signature, $state['signature'] ?? '')) { + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] State signature mismatch, rejecting callback'); throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Invalid state parameter. Please restart the installation from the Appwrite Console.'); } + Console::log('[CODEBASE DEBUG] State signature valid'); $project = $dbForPlatform->getDocument('projects', $projectId); @@ -101,7 +129,7 @@ class Get extends Action if ($installation->isEmpty()) { $teamId = $project->getAttribute('teamId', ''); - $dbForPlatform->createDocument('installations', new Document([ + $installation = $dbForPlatform->createDocument('installations', new Document([ '$id' => ID::unique(), '$permissions' => $this->getPermissions($teamId, $projectId), 'providerInstallationId' => $providerInstallationId, @@ -111,8 +139,15 @@ class Get extends Action 'organization' => '', 'personal' => false, ])); + + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] Created installation "' . $installation->getId() . '" for project "' . $projectId . '"'); + } else { + Console::log('[CODEBASE DEBUG] Installation already exists: "' . $installation->getId() . '"'); } + Console::log('[CODEBASE DEBUG] Redirecting to success URL: ' . $redirectSuccess); + $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') ->addHeader('Pragma', 'no-cache') @@ -124,6 +159,9 @@ class Get extends Action */ private function failure(Response $response, string $redirect, string $error, string $type = Exception::GENERAL_ARGUMENT_INVALID): void { + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] Callback failed: ' . $error . ' (redirect: "' . $redirect . '")'); + if (empty($redirect)) { throw new Exception($type, $error); } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php index 432e3fb81d..e44aae970d 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php @@ -5,6 +5,7 @@ namespace Appwrite\Platform\Modules\VCS\Http\Codebase\Events; use Appwrite\Platform\Action; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Utopia\Console; use Utopia\Platform\Scope\HTTP; use Utopia\Span\Span; @@ -34,10 +35,17 @@ class Create extends Action Request $request, Response $response ) { + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + Console::log('[CODEBASE DEBUG] Event received'); + Console::log('[CODEBASE DEBUG] Event headers: ' . \json_encode($request->getHeaders())); + Console::log('[CODEBASE DEBUG] Event query params: ' . \json_encode($request->getParams())); + Console::log('[CODEBASE DEBUG] Event raw payload: ' . $request->getRawPayload()); + $payload = \json_decode($request->getRawPayload(), true) ?? []; $event = $request->getHeaderLine('x-codebase-event', '') ?: ($payload['event'] ?? ''); Span::add('vcs.codebase.event.name', $event); + Console::log('[CODEBASE DEBUG] Event name resolved to: "' . $event . '"'); // Codebase does not deliver push or pull request events yet, so events // are only acknowledged to prevent delivery retries. From 30e363cc14d92b66203495ef0a07827bdcfcaa7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:00:49 +0200 Subject: [PATCH 08/53] Code quality nitpick --- docs/references/vcs/create-codebase-installation.md | 1 - .../Platform/Modules/VCS/Http/Codebase/Authorize/Get.php | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) delete mode 100644 docs/references/vcs/create-codebase-installation.md diff --git a/docs/references/vcs/create-codebase-installation.md b/docs/references/vcs/create-codebase-installation.md deleted file mode 100644 index 5fcff97be9..0000000000 --- a/docs/references/vcs/create-codebase-installation.md +++ /dev/null @@ -1 +0,0 @@ -Begin Appwrite's Codebase app installation to set up version control integration. This endpoint responds with a redirect URL to the Codebase app's installation page on Cursor. The Codebase app must be configured in your environment for this endpoint to work. \ No newline at end of file diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index 8d8cb8ca0c..360ab62831 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -37,7 +37,7 @@ class Get extends Action namespace: 'vcs', group: 'installations', name: 'createCodebaseInstallation', - description: '/docs/references/vcs/create-codebase-installation.md', + description: 'Begin Appwrite\'s Codebase app installation to set up version control integration. This endpoint responds with a redirect URL to the Codebase app\'s installation page on Cursor. The Codebase app must be configured in your environment for this endpoint to work.', auth: [AuthType::ADMIN], responses: [ new SDKResponse( From 31411328598d6205ba1694bce7d73e8f896bc21b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:09:55 +0200 Subject: [PATCH 09/53] Fix "requested_scopes requires at least one scope" --- .../Platform/Modules/VCS/Http/Codebase/Authorize/Get.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index 360ab62831..4b75b1f258 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -86,6 +86,7 @@ class Get extends Action $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query([ 'client_id' => $clientId, + 'source' => 'app-metadata', 'state' => $state, 'redirect_uri' => $protocol . '://' . $hostname . '/v1/vcs/codebase/callback', ]); From 7cae8eaa78f06dedabbb4a3b9b1b4fc5f396f99f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:29:39 +0200 Subject: [PATCH 10/53] Simplify useless integration (not working) --- .../VCS/Http/Codebase/Authorize/Get.php | 44 +++++++++++++------ .../VCS/Http/Codebase/Callback/Get.php | 19 ++++++++ 2 files changed, 49 insertions(+), 14 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index 4b75b1f258..d1c8fedb60 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -71,25 +71,41 @@ class Get extends Action throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Codebase client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); } - // The callback endpoint is public and Codebase performs no token - // exchange, so the callback verifies this signature before trusting - // the projectId and redirect URLs in state. - $state = \json_encode([ - 'projectId' => $project->getId(), - 'success' => $success, - 'failure' => $failure, - 'signature' => \hash_hmac('sha256', \json_encode([$project->getId(), $success, $failure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')), - ]); - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; $hostname = $platform['consoleHostname'] ?? ''; - $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query([ + $callback = $protocol . '://' . $hostname . '/v1/vcs/codebase/callback'; + + $query = [ 'client_id' => $clientId, 'source' => 'app-metadata', - 'state' => $state, - 'redirect_uri' => $protocol . '://' . $hostname . '/v1/vcs/codebase/callback', - ]); + ]; + + // The correct redirect parameter name is undocumented, so send the + // callback URL under every plausible spelling -- Codebase should honor + // whichever one it recognises and ignore the rest. + // TODO: Narrow to the single correct parameter once confirmed. + foreach ([ + 'redirect_uri', + 'redirect_url', + 'redirectUri', + 'redirectUrl', + 'callback_uri', + 'callback_url', + 'callbackUri', + 'callbackUrl', + 'callback', + 'return_uri', + 'return_url', + 'returnUri', + 'returnUrl', + 'return_to', + 'returnTo', + ] as $param) { + $query[$param] = $callback; + } + + $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query($query); // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. Console::log('[CODEBASE DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php index 5bf3df064c..12943767ad 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php @@ -36,6 +36,7 @@ class Get extends Action ->label('scope', 'public') ->label('error', APP_VIEWS_DIR . '/general/error.phtml') ->param('installation_id', '', new Text(256, 0), 'Codebase installation ID', true) + ->param('installation_receipt', '', new Text(4096, 0), 'Codebase installation receipt JWT, signed by Cursor.', true) ->param('state', '', new Text(2048), 'Codebase state. Contains info sent when starting the installation flow.', true) ->inject('request') ->inject('response') @@ -46,6 +47,7 @@ class Get extends Action public function action( string $providerInstallationId, + string $installationReceipt, string $state, Request $request, Response $response, @@ -70,6 +72,23 @@ class Get extends Action Console::log('[CODEBASE DEBUG] No OAuth2 flow params detected'); } + // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + // Decode only -- the EdDSA signature is not verified, so the claims + // must not be trusted for authorization decisions yet. + if (!empty($installationReceipt)) { + $segments = \explode('.', $installationReceipt); + if (\count($segments) === 3) { + $receiptHeader = \json_decode(\base64_decode(\strtr($segments[0], '-_', '+/')), true) ?? []; + $receiptClaims = \json_decode(\base64_decode(\strtr($segments[1], '-_', '+/')), true) ?? []; + Console::log('[CODEBASE DEBUG] Receipt JWT header: ' . \json_encode($receiptHeader)); + Console::log('[CODEBASE DEBUG] Receipt JWT claims: ' . \json_encode($receiptClaims)); + } else { + Console::log('[CODEBASE DEBUG] installation_receipt is not a JWT: ' . $installationReceipt); + } + } else { + Console::log('[CODEBASE DEBUG] No installation_receipt received'); + } + if (empty($state)) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing state parameter. Please restart the installation from the Appwrite Console.'); } From fc1dc71fea89b5b5518e0c631ef83837f17a17c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:32:21 +0200 Subject: [PATCH 11/53] JWKs verficiation --- .../VCS/Http/Codebase/Callback/Get.php | 139 +++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php index 12943767ad..f1d23c5d43 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php @@ -11,6 +11,7 @@ use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\ID; use Utopia\Database\Query; +use Utopia\Fetch\Client as FetchClient; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; @@ -21,6 +22,18 @@ class Get extends Action use HTTP; use AppwritePermission; + /** + * Issuer and JWKS endpoint published by Cursor's OIDC discovery document at + * https://api.cursor.com/v1/origin/.well-known/openid-configuration + */ + private const RECEIPT_ISSUER = 'https://api.cursor.com/v1/origin'; + private const RECEIPT_JWKS_URL = 'https://api.cursor.com/v1/origin/keys'; + + /** + * Clock-skew tolerance, in seconds, applied to receipt exp/nbf checks. + */ + private const RECEIPT_LEEWAY = 60; + public static function getName() { return 'getVCSCodebaseCallback'; @@ -137,6 +150,22 @@ class Get extends Action return; } + // Authenticate the callback by verifying the installation receipt + // against Cursor's published JWKS. This proves the request genuinely + // originates from Codebase (the callback is public and has no token + // exchange) before any installation is created. + try { + $receiptClaims = $this->verifyReceipt($installationReceipt, $providerInstallationId); + } catch (\Throwable $e) { + Console::log('[CODEBASE DEBUG] Receipt verification failed: ' . $e->getMessage()); + $this->failure($response, $redirectFailure, 'Could not verify the Codebase installation receipt.'); + return; + } + + // The Cursor namespace (team/workspace) owning the installation. + $organization = $receiptClaims['namespace_id'] ?? ''; + Console::log('[CODEBASE DEBUG] Receipt verified, namespace_id: "' . $organization . '"'); + $projectInternalId = $project->getSequence(); $installation = $dbForPlatform->findOne('installations', [ @@ -155,13 +184,17 @@ class Get extends Action 'projectId' => $projectId, 'projectInternalId' => $projectInternalId, 'provider' => 'codebase', - 'organization' => '', + 'organization' => $organization, 'personal' => false, ])); // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. Console::log('[CODEBASE DEBUG] Created installation "' . $installation->getId() . '" for project "' . $projectId . '"'); } else { + $installation = $dbForPlatform->updateDocument('installations', $installation->getId(), new Document([ + 'organization' => $organization, + ])); + Console::log('[CODEBASE DEBUG] Installation already exists: "' . $installation->getId() . '"'); } @@ -191,4 +224,108 @@ class Get extends Action ->addHeader('Pragma', 'no-cache') ->redirect($redirect . $separator . \http_build_query(['error' => $error])); } + + /** + * Verify a Codebase installation receipt (an EdDSA-signed JWT) against + * Cursor's published JWKS and validate its claims. Returns the verified + * claims, or throws on any failure. + * + * @return array + */ + private function verifyReceipt(string $jwt, string $expectedInstallationId): array + { + if (empty($jwt)) { + throw new \Exception('receipt is missing'); + } + + $segments = \explode('.', $jwt); + if (\count($segments) !== 3) { + throw new \Exception('receipt is not a JWT'); + } + + [$headerB64, $payloadB64, $signatureB64] = $segments; + $header = \json_decode($this->base64UrlDecode($headerB64), true); + $claims = \json_decode($this->base64UrlDecode($payloadB64), true); + $signature = $this->base64UrlDecode($signatureB64); + + if (!\is_array($header) || !\is_array($claims)) { + throw new \Exception('receipt segments are not valid JSON'); + } + + if (($header['alg'] ?? '') !== 'EdDSA') { + throw new \Exception('unexpected signing algorithm'); + } + + $kid = $header['kid'] ?? ''; + if (empty($kid)) { + throw new \Exception('receipt is missing key id'); + } + + $publicKey = null; + foreach ($this->fetchJwks() as $key) { + if (($key['kid'] ?? '') === $kid && ($key['kty'] ?? '') === 'OKP' && ($key['crv'] ?? '') === 'Ed25519') { + $publicKey = $this->base64UrlDecode($key['x'] ?? ''); + break; + } + } + + if ($publicKey === null || \strlen($publicKey) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) { + throw new \Exception('no matching signing key in JWKS'); + } + + if (!\sodium_crypto_sign_verify_detached($signature, $headerB64 . '.' . $payloadB64, $publicKey)) { + throw new \Exception('signature is invalid'); + } + + if (($claims['iss'] ?? '') !== self::RECEIPT_ISSUER) { + throw new \Exception('unexpected issuer'); + } + + $clientId = System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID', ''); + if (($claims['aud'] ?? '') !== $clientId) { + throw new \Exception('receipt audience does not match this app'); + } + + // Bind the receipt to the installation id in the callback so a valid + // receipt cannot be replayed to attach a different installation. + if (($claims['sub'] ?? '') !== $expectedInstallationId) { + throw new \Exception('receipt subject does not match installation id'); + } + + $now = \time(); + if (isset($claims['exp']) && $now >= (int)$claims['exp'] + self::RECEIPT_LEEWAY) { + throw new \Exception('receipt has expired'); + } + if (isset($claims['nbf']) && $now < (int)$claims['nbf'] - self::RECEIPT_LEEWAY) { + throw new \Exception('receipt is not yet valid'); + } + + return $claims; + } + + /** + * Fetch Cursor's origin JWKS (the Ed25519 public keys that sign receipts). + * + * @return array> + */ + private function fetchJwks(): array + { + $client = new FetchClient(); + $client->addHeader('Accept', 'application/json'); + + $response = $client->fetch(url: self::RECEIPT_JWKS_URL, method: FetchClient::METHOD_GET); + $body = \json_decode($response->getBody(), true); + + return \is_array($body) && isset($body['keys']) && \is_array($body['keys']) ? $body['keys'] : []; + } + + private function base64UrlDecode(string $data): string + { + $remainder = \strlen($data) % 4; + if ($remainder > 0) { + $data .= \str_repeat('=', 4 - $remainder); + } + + return (string)\base64_decode(\strtr($data, '-_', '+/'), true); + } } From d0f0d2b32537399833fd56928e09f578cc75147e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:33:37 +0200 Subject: [PATCH 12/53] Cleanup of failed PoC --- .../VCS/Http/Codebase/Authorize/Get.php | 37 ++----------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index d1c8fedb60..62fdd2ee28 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -71,41 +71,12 @@ class Get extends Action throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Codebase client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); } - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; - $hostname = $platform['consoleHostname'] ?? ''; - - $callback = $protocol . '://' . $hostname . '/v1/vcs/codebase/callback'; - - $query = [ + // Codebase ignores a redirect parameter on the install URL; the + // callback URL is taken from the app's own configuration on Cursor. + $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query([ 'client_id' => $clientId, 'source' => 'app-metadata', - ]; - - // The correct redirect parameter name is undocumented, so send the - // callback URL under every plausible spelling -- Codebase should honor - // whichever one it recognises and ignore the rest. - // TODO: Narrow to the single correct parameter once confirmed. - foreach ([ - 'redirect_uri', - 'redirect_url', - 'redirectUri', - 'redirectUrl', - 'callback_uri', - 'callback_url', - 'callbackUri', - 'callbackUrl', - 'callback', - 'return_uri', - 'return_url', - 'returnUri', - 'returnUrl', - 'return_to', - 'returnTo', - ] as $param) { - $query[$param] = $callback; - } - - $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query($query); + ]); // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. Console::log('[CODEBASE DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); From 39053e075b7f2fba6d09b460ea727268240f16a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:41:09 +0200 Subject: [PATCH 13/53] Added cursor oauth2 provider --- src/Appwrite/Auth/OAuth2/Cursor.php | 311 ++++++++++++++++++ .../VCS/Http/Codebase/Authorize/Get.php | 9 +- .../VCS/Http/Codebase/Callback/Get.php | 132 +------- 3 files changed, 329 insertions(+), 123 deletions(-) create mode 100644 src/Appwrite/Auth/OAuth2/Cursor.php diff --git a/src/Appwrite/Auth/OAuth2/Cursor.php b/src/Appwrite/Auth/OAuth2/Cursor.php new file mode 100644 index 0000000000..4babadf334 --- /dev/null +++ b/src/Appwrite/Auth/OAuth2/Cursor.php @@ -0,0 +1,311 @@ + $this->appID, + ]; + + if (empty($this->getScopes())) { + // Without an explicit scope list the install page rejects the + // request ("requested_scopes requires at least one scope") unless + // told to read the scopes from the app's registered metadata. + $params['source'] = 'app-metadata'; + } else { + $params['scope'] = \implode(' ', $this->getScopes()); + } + + return 'https://cursor.com/codebase/apps/install?' . \http_build_query($params); + } + + /** + * Verifies an installation receipt JWT against Cursor's JWKS and returns + * its claims. The `sub` claim is the installation ID, `state` echoes the + * state given to the install URL, and `namespace_id` is the workspace. + * + * @return array + * @throws Exception + */ + public function verifyReceipt(string $receipt): array + { + $segments = \explode('.', $receipt); + + if (\count($segments) !== 3) { + throw new Exception('Installation receipt is not a JWT'); + } + + [$headerSegment, $claimsSegment, $signatureSegment] = $segments; + + $header = \json_decode($this->base64UrlDecode($headerSegment), true); + $claims = \json_decode($this->base64UrlDecode($claimsSegment), true); + $signature = $this->base64UrlDecode($signatureSegment); + + if (!\is_array($header) || !\is_array($claims)) { + throw new Exception('Installation receipt is malformed'); + } + + if (($header['alg'] ?? '') !== 'EdDSA') { + throw new Exception('Installation receipt has an unexpected algorithm'); + } + + // Receipts are documented to carry this media type; tolerate its + // absence, but never another Cursor-signed token kind in its place. + if (isset($header['typ']) && $header['typ'] !== 'origin-installation-receipt+jwt') { + throw new Exception('Installation receipt has an unexpected type'); + } + + $key = $this->getPublicKey($header['kid'] ?? ''); + + if ( + \strlen($signature) !== SODIUM_CRYPTO_SIGN_BYTES + || !\sodium_crypto_sign_verify_detached($signature, $headerSegment . '.' . $claimsSegment, $key) + ) { + throw new Exception('Installation receipt signature is invalid'); + } + + if (($claims['iss'] ?? '') !== $this->endpoint) { + throw new Exception('Installation receipt issuer is invalid'); + } + + if (($claims['aud'] ?? '') !== $this->appID) { + throw new Exception('Installation receipt audience does not match the configured client ID'); + } + + $now = \time(); + $leeway = 60; + + // Receipts are short-lived, single-use artifacts (about a five-minute + // window per Cursor's verification rules). + if (isset($claims['exp']) && $now >= (int)$claims['exp'] + $leeway) { + throw new Exception('Installation receipt has expired'); + } + + if (isset($claims['nbf']) && $now < (int)$claims['nbf'] - $leeway) { + throw new Exception('Installation receipt is not yet valid'); + } + + if (isset($claims['iat']) && $now < (int)$claims['iat'] - $leeway) { + throw new Exception('Installation receipt is issued in the future'); + } + + if (empty($claims['sub'])) { + throw new Exception('Installation receipt is missing the installation ID'); + } + + return $claims; + } + + /** + * App JWT authenticating this app to Cursor's API, signed with the app's + * Ed25519 private key. Used as a Bearer token for app-level endpoints, + * most importantly minting installation access tokens. + */ + public function getAppJWT(): string + { + $now = \time(); + + $headerSegment = $this->base64UrlEncode(\json_encode([ + 'alg' => 'EdDSA', + 'kid' => $this->appID, + 'typ' => 'JWT', + ])); + + $claimsSegment = $this->base64UrlEncode(\json_encode([ + 'iss' => $this->appID, + 'aud' => 'origin-apps', + 'iat' => $now, + 'exp' => $now + 300, + ])); + + $signature = \sodium_crypto_sign_detached($headerSegment . '.' . $claimsSegment, $this->getSigningKey()); + + return $headerSegment . '.' . $claimsSegment . '.' . $this->base64UrlEncode($signature); + } + + /** + * There is no authorization-code exchange: the "code" is the installation + * ID from the receipt's `sub` claim, exchanged for a short-lived (at most + * 15 minutes) installation access token. An empty or omitted scope list + * inherits the full installation grant. + * + * @param string $code + * + * @return array + */ + protected function getTokens(string $code): array + { + if (empty($this->tokens)) { + $payload = empty($this->getScopes()) + ? '{}' + : \json_encode(['scopes' => $this->getScopes()]); + + $response = \json_decode($this->request( + 'POST', + $this->endpoint . '/app/installations/' . \urlencode($code) . '/access_tokens', + [ + 'Authorization: Bearer ' . $this->getAppJWT(), + 'Content-Type: application/json', + ], + $payload + ), true); + + $this->tokens = [ + 'access_token' => $response['token'] ?? '', + 'expires_in' => isset($response['expiresAt']) + ? \max(0, (int)\strtotime($response['expiresAt']) - \time()) + : 0, + ]; + } + + return $this->tokens; + } + + /** + * Installation tokens cannot be refreshed -- a new one is minted from the + * installation ID with the app JWT. + * + * @param string $refreshToken + * + * @return array + */ + public function refreshTokens(string $refreshToken): array + { + $this->tokens = []; + + return $this->getTokens($refreshToken); + } + + /** + * Cursor Origin apps act as an installation, never as a user, so there is + * no user identity behind an access token. + */ + public function getUserID(string $accessToken): string + { + return ''; + } + + public function getUserEmail(string $accessToken): string + { + return ''; + } + + public function isEmailVerified(string $accessToken): bool + { + return false; + } + + public function getUserName(string $accessToken): string + { + return ''; + } + + /** + * Ed25519 public key for a JWKS key ID. + * + * @throws Exception + */ + protected function getPublicKey(string $kid): string + { + if (empty($this->jwks)) { + $this->jwks = \json_decode($this->request('GET', $this->endpoint . '/keys'), true)['keys'] ?? []; + } + + foreach ($this->jwks as $key) { + if ( + ($key['kid'] ?? '') === $kid + && ($key['kty'] ?? '') === 'OKP' + && ($key['crv'] ?? '') === 'Ed25519' + ) { + $publicKey = $this->base64UrlDecode($key['x'] ?? ''); + + if (\strlen($publicKey) === SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) { + return $publicKey; + } + } + } + + throw new Exception('Installation receipt is signed with an unknown key'); + } + + /** + * Ed25519 secret key derived from the PKCS#8 PEM in $appSecret. + * + * @throws Exception + */ + protected function getSigningKey(): string + { + // Keys configured through environment variables carry literal \n + // sequences instead of newlines. + $pem = \str_replace(['\n', '-----BEGIN PRIVATE KEY-----', '-----END PRIVATE KEY-----'], '', $this->appSecret); + $der = \base64_decode(\preg_replace('/\s+/', '', $pem) ?? '', true); + + // RFC 8410 PKCS#8 wraps the 32-byte Ed25519 seed in a nested octet + // string tagged 0x04 0x22 0x04 0x20. + $offset = \is_string($der) ? \strpos($der, "\x04\x22\x04\x20") : false; + + if ($offset === false || \strlen($der) < $offset + 4 + SODIUM_CRYPTO_SIGN_SEEDBYTES) { + throw new Exception('Private key is not a PKCS#8 Ed25519 key'); + } + + $seed = \substr($der, $offset + 4, SODIUM_CRYPTO_SIGN_SEEDBYTES); + + return \sodium_crypto_sign_secretkey(\sodium_crypto_sign_seed_keypair($seed)); + } + + protected function base64UrlEncode(string $data): string + { + return \rtrim(\strtr(\base64_encode($data), '+/', '-_'), '='); + } + + protected function base64UrlDecode(string $data): string + { + $remainder = \strlen($data) % 4; + if ($remainder > 0) { + $data .= \str_repeat('=', 4 - $remainder); + } + + return (string)\base64_decode(\strtr($data, '-_', '+/'), true); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php index 62fdd2ee28..cb519c1ace 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php @@ -2,6 +2,7 @@ namespace Appwrite\Platform\Modules\VCS\Http\Codebase\Authorize; +use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Extend\Exception; use Appwrite\Platform\Action; use Appwrite\SDK\AuthType; @@ -71,12 +72,8 @@ class Get extends Action throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Codebase client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); } - // Codebase ignores a redirect parameter on the install URL; the - // callback URL is taken from the app's own configuration on Cursor. - $url = 'https://cursor.com/codebase/apps/install?' . \http_build_query([ - 'client_id' => $clientId, - 'source' => 'app-metadata', - ]); + $oauth2 = new OAuth2Cursor($clientId, System::getEnv('_APP_VCS_CODEBASE_PRIVATE_KEY', ''), ''); + $url = $oauth2->getLoginURL(); // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. Console::log('[CODEBASE DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php index f1d23c5d43..023ba6f369 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php @@ -2,6 +2,7 @@ namespace Appwrite\Platform\Modules\VCS\Http\Codebase\Callback; +use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Extend\Exception; use Appwrite\Platform\Permission as AppwritePermission; use Appwrite\Utopia\Request; @@ -11,7 +12,6 @@ use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\ID; use Utopia\Database\Query; -use Utopia\Fetch\Client as FetchClient; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; @@ -22,18 +22,6 @@ class Get extends Action use HTTP; use AppwritePermission; - /** - * Issuer and JWKS endpoint published by Cursor's OIDC discovery document at - * https://api.cursor.com/v1/origin/.well-known/openid-configuration - */ - private const RECEIPT_ISSUER = 'https://api.cursor.com/v1/origin'; - private const RECEIPT_JWKS_URL = 'https://api.cursor.com/v1/origin/keys'; - - /** - * Clock-skew tolerance, in seconds, applied to receipt exp/nbf checks. - */ - private const RECEIPT_LEEWAY = 60; - public static function getName() { return 'getVCSCodebaseCallback'; @@ -154,8 +142,21 @@ class Get extends Action // against Cursor's published JWKS. This proves the request genuinely // originates from Codebase (the callback is public and has no token // exchange) before any installation is created. + $oauth2 = new OAuth2Cursor( + System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID', ''), + System::getEnv('_APP_VCS_CODEBASE_PRIVATE_KEY', ''), + '' + ); + try { - $receiptClaims = $this->verifyReceipt($installationReceipt, $providerInstallationId); + $receiptClaims = $oauth2->verifyReceipt($installationReceipt); + + // Bind the receipt to the installation id in the callback so a + // valid receipt cannot be replayed to attach a different + // installation. + if (($receiptClaims['sub'] ?? '') !== $providerInstallationId) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Receipt subject does not match installation ID'); + } } catch (\Throwable $e) { Console::log('[CODEBASE DEBUG] Receipt verification failed: ' . $e->getMessage()); $this->failure($response, $redirectFailure, 'Could not verify the Codebase installation receipt.'); @@ -225,107 +226,4 @@ class Get extends Action ->redirect($redirect . $separator . \http_build_query(['error' => $error])); } - /** - * Verify a Codebase installation receipt (an EdDSA-signed JWT) against - * Cursor's published JWKS and validate its claims. Returns the verified - * claims, or throws on any failure. - * - * @return array - */ - private function verifyReceipt(string $jwt, string $expectedInstallationId): array - { - if (empty($jwt)) { - throw new \Exception('receipt is missing'); - } - - $segments = \explode('.', $jwt); - if (\count($segments) !== 3) { - throw new \Exception('receipt is not a JWT'); - } - - [$headerB64, $payloadB64, $signatureB64] = $segments; - $header = \json_decode($this->base64UrlDecode($headerB64), true); - $claims = \json_decode($this->base64UrlDecode($payloadB64), true); - $signature = $this->base64UrlDecode($signatureB64); - - if (!\is_array($header) || !\is_array($claims)) { - throw new \Exception('receipt segments are not valid JSON'); - } - - if (($header['alg'] ?? '') !== 'EdDSA') { - throw new \Exception('unexpected signing algorithm'); - } - - $kid = $header['kid'] ?? ''; - if (empty($kid)) { - throw new \Exception('receipt is missing key id'); - } - - $publicKey = null; - foreach ($this->fetchJwks() as $key) { - if (($key['kid'] ?? '') === $kid && ($key['kty'] ?? '') === 'OKP' && ($key['crv'] ?? '') === 'Ed25519') { - $publicKey = $this->base64UrlDecode($key['x'] ?? ''); - break; - } - } - - if ($publicKey === null || \strlen($publicKey) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) { - throw new \Exception('no matching signing key in JWKS'); - } - - if (!\sodium_crypto_sign_verify_detached($signature, $headerB64 . '.' . $payloadB64, $publicKey)) { - throw new \Exception('signature is invalid'); - } - - if (($claims['iss'] ?? '') !== self::RECEIPT_ISSUER) { - throw new \Exception('unexpected issuer'); - } - - $clientId = System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID', ''); - if (($claims['aud'] ?? '') !== $clientId) { - throw new \Exception('receipt audience does not match this app'); - } - - // Bind the receipt to the installation id in the callback so a valid - // receipt cannot be replayed to attach a different installation. - if (($claims['sub'] ?? '') !== $expectedInstallationId) { - throw new \Exception('receipt subject does not match installation id'); - } - - $now = \time(); - if (isset($claims['exp']) && $now >= (int)$claims['exp'] + self::RECEIPT_LEEWAY) { - throw new \Exception('receipt has expired'); - } - if (isset($claims['nbf']) && $now < (int)$claims['nbf'] - self::RECEIPT_LEEWAY) { - throw new \Exception('receipt is not yet valid'); - } - - return $claims; - } - - /** - * Fetch Cursor's origin JWKS (the Ed25519 public keys that sign receipts). - * - * @return array> - */ - private function fetchJwks(): array - { - $client = new FetchClient(); - $client->addHeader('Accept', 'application/json'); - - $response = $client->fetch(url: self::RECEIPT_JWKS_URL, method: FetchClient::METHOD_GET); - $body = \json_decode($response->getBody(), true); - - return \is_array($body) && isset($body['keys']) && \is_array($body['keys']) ? $body['keys'] : []; - } - - private function base64UrlDecode(string $data): string - { - $remainder = \strlen($data) % 4; - if ($remainder > 0) { - $data .= \str_repeat('=', 4 - $remainder); - } - - return (string)\base64_decode(\strtr($data, '-_', '+/'), true); - } } From b08e71a6a0a4564bbe4883836f8000bd7d271db5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:41:45 +0200 Subject: [PATCH 14/53] Prepare empty env vars --- .env | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.env b/.env index e1032c8a8d..49be7302b3 100644 --- a/.env +++ b/.env @@ -170,5 +170,7 @@ _APP_VCS_GITLAB_WEBHOOK_SECRET= _APP_VCS_BITBUCKET_CLIENT_ID= _APP_VCS_BITBUCKET_CLIENT_SECRET= _APP_VCS_BITBUCKET_WEBHOOK_SECRET= +_APP_VCS_CODEBASE_CLIENT_ID= +_APP_VCS_CODEBASE_PRIVATE_KEY="" _APP_VCS_WEBHOOK_URL=http://appwrite/v1 _APP_WEBHOOK_MAX_FAILED_ATTEMPTS=10 From 4ccc6e66641ff36c344674c149ea82ee8f85852b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 10:43:16 +0200 Subject: [PATCH 15/53] Suport cursor oauth2 on project-level --- app/config/oAuthProviders.php | 11 +++ app/init/models.php | 2 + src/Appwrite/Auth/OAuth2/Cursor.php | 15 +++++ .../Project/Http/Project/OAuth2/Base.php | 1 + .../Http/Project/OAuth2/Cursor/Update.php | 65 ++++++++++++++++++ .../Modules/Project/Services/Http.php | 2 + src/Appwrite/Utopia/Response.php | 1 + .../Utopia/Response/Model/OAuth2Cursor.php | 67 +++++++++++++++++++ .../Project/OAuth2/OAuth2ProviderTest.php | 2 +- 9 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php create mode 100644 src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php diff --git a/app/config/oAuthProviders.php b/app/config/oAuthProviders.php index 31f1585b5c..113a088032 100644 --- a/app/config/oAuthProviders.php +++ b/app/config/oAuthProviders.php @@ -101,6 +101,17 @@ return [ 'mock' => false, 'class' => 'Appwrite\\Auth\\OAuth2\\Box', ], + 'cursor' => [ + 'name' => 'Cursor', + 'developers' => 'https://cursor.com/docs/api', + 'icon' => 'icon-cursor', + 'enabled' => true, + 'sandbox' => false, + 'form' => false, + 'beta' => false, + 'mock' => false, + 'class' => 'Appwrite\\Auth\\OAuth2\\Cursor', + ], 'dailymotion' => [ 'name' => 'Dailymotion', 'developers' => 'https://developers.dailymotion.com/api/', diff --git a/app/init/models.php b/app/init/models.php index 41651c9262..6f257f5f4b 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -126,6 +126,7 @@ use Appwrite\Utopia\Response\Model\OAuth2Autodesk; use Appwrite\Utopia\Response\Model\OAuth2Bitbucket; use Appwrite\Utopia\Response\Model\OAuth2Bitly; use Appwrite\Utopia\Response\Model\OAuth2Box; +use Appwrite\Utopia\Response\Model\OAuth2Cursor; use Appwrite\Utopia\Response\Model\OAuth2Dailymotion; use Appwrite\Utopia\Response\Model\OAuth2Discord; use Appwrite\Utopia\Response\Model\OAuth2Disqus; @@ -463,6 +464,7 @@ Response::setModel(new OAuth2Okta()); Response::setModel(new OAuth2Kick()); Response::setModel(new OAuth2Apple()); Response::setModel(new OAuth2Microsoft()); +Response::setModel(new OAuth2Cursor()); Response::setModel(new OAuth2ProviderList()); Response::setModel(new PolicyPasswordDictionary()); Response::setModel(new PolicyPasswordHistory()); diff --git a/src/Appwrite/Auth/OAuth2/Cursor.php b/src/Appwrite/Auth/OAuth2/Cursor.php index 4babadf334..2f3149c01a 100644 --- a/src/Appwrite/Auth/OAuth2/Cursor.php +++ b/src/Appwrite/Auth/OAuth2/Cursor.php @@ -217,6 +217,21 @@ class Cursor extends OAuth2 return $this->getTokens($refreshToken); } + /** + * End-to-end credential check used when enabling the provider: signing + * the app JWT proves the private key is well-formed, and the zero-cost + * rate-limit endpoint rejects it with a 401 unless the app ID and key + * match a registered app. + * + * @throws Exception + */ + public function verifyCredentials(): void + { + $this->request('GET', $this->endpoint . '/rate_limit', [ + 'Authorization: Bearer ' . $this->getAppJWT(), + ]); + } + /** * Cursor Origin apps act as an installation, never as a user, so there is * no user identity behind an access token. diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php index cb58c1cfc0..0739e7a275 100644 --- a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php +++ b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php @@ -319,6 +319,7 @@ abstract class Base extends Action 'kick' => Kick\Update::class, 'apple' => Apple\Update::class, 'microsoft' => Microsoft\Update::class, + 'cursor' => Cursor\Update::class, ]; } diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php new file mode 100644 index 0000000000..c11cd8221e --- /dev/null +++ b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php @@ -0,0 +1,65 @@ +addAction(UpdateOAuth2Kick::getName(), new UpdateOAuth2Kick()); $this->addAction(UpdateOAuth2Apple::getName(), new UpdateOAuth2Apple()); $this->addAction(UpdateOAuth2Microsoft::getName(), new UpdateOAuth2Microsoft()); + $this->addAction(UpdateOAuth2Cursor::getName(), new UpdateOAuth2Cursor()); } } diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 80dd69bd38..c1270b5976 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -327,6 +327,7 @@ class Response extends SwooleResponse public const MODEL_OAUTH2_OKTA = 'oAuth2Okta'; public const MODEL_OAUTH2_KICK = 'oAuth2Kick'; public const MODEL_OAUTH2_MICROSOFT = 'oAuth2Microsoft'; + public const MODEL_OAUTH2_CURSOR = 'oAuth2Cursor'; public const MODEL_OAUTH2_PROVIDER_LIST = 'oAuth2ProviderList'; // Health diff --git a/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php b/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php new file mode 100644 index 0000000000..7f7f7956d1 --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php @@ -0,0 +1,67 @@ + 'cursor', + ]; + + public function getProviderLabel(): string + { + return 'Cursor'; + } + + public function getClientIdExample(): string + { + return 'app_01k5wz9v3rq8tembsy0d4hxnpc'; + } + + public function getClientSecretExample(): string + { + return '-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n-----END PRIVATE KEY-----'; + } + + public function getClientIdLabel(): string + { + return 'app ID'; + } + + public function getClientSecretFieldName(): string + { + return 'privateKey'; + } + + public function getClientSecretLabel(): string + { + return 'private key'; + } + + public function getClientSecretDescription(): string + { + return parent::getClientSecretDescription() . ' Ed25519 key in PKCS#8 PEM format; only its public key is registered with Cursor.'; + } + + /** + * Get Name + * + * @return string + */ + public function getName(): string + { + return 'OAuth2Cursor'; + } + + /** + * Get Type + * + * @return string + */ + public function getType(): string + { + return Response::MODEL_OAUTH2_CURSOR; + } +} diff --git a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php index 63c1b1012f..b133346585 100644 --- a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php +++ b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php @@ -38,7 +38,7 @@ final class OAuth2ProviderTest extends TestCase $expected = [ 'amazon', 'apple', 'appwrite', 'auth0', 'authentik', 'autodesk', - 'bitbucket', 'bitly', 'box', 'dailymotion', 'discord', 'disqus', + 'bitbucket', 'bitly', 'box', 'cursor', 'dailymotion', 'discord', 'disqus', 'dropbox', 'etsy', 'facebook', 'figma', 'fusionauth', 'github', 'gitlab', 'google', 'keycloak', 'kick', 'linkedin', 'microsoft', 'notion', 'oidc', 'okta', 'paypal', 'paypalSandbox', 'podio', From 5716cd220f2cd42fed85f9fa6d857d929c091c7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 12:34:27 +0200 Subject: [PATCH 16/53] support Cursor for Console --- app/config/console.php | 5 ++++- docker-compose.yml | 2 ++ .../Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/app/config/console.php b/app/config/console.php index bf1850182a..9e6fd7e35b 100644 --- a/app/config/console.php +++ b/app/config/console.php @@ -57,7 +57,10 @@ $console = [ 'oAuthProviders' => [ 'githubEnabled' => true, 'githubSecret' => System::getEnv('_APP_CONSOLE_GITHUB_SECRET', ''), - 'githubAppid' => System::getEnv('_APP_CONSOLE_GITHUB_APP_ID', '') + 'githubAppid' => System::getEnv('_APP_CONSOLE_GITHUB_APP_ID', ''), + 'cursorEnabled' => true, + 'cursorSecret' => System::getEnv('_APP_CONSOLE_CURSOR_PRIVATE_KEY', ''), + 'cursorAppid' => System::getEnv('_APP_CONSOLE_CURSOR_APP_ID', ''), ], 'smtpBaseTemplate' => APP_BRANDED_EMAIL_BASE_TEMPLATE, ]; diff --git a/docker-compose.yml b/docker-compose.yml index 1372bca12a..b6e8fa0118 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -217,6 +217,8 @@ services: - _APP_MIGRATIONS_FIREBASE_CLIENT_SECRET - _APP_ASSISTANT_OPENAI_API_KEY - _APP_CONSOLE_COUNTRIES_DENYLIST + - _APP_CONSOLE_CURSOR_APP_ID + - _APP_CONSOLE_CURSOR_PRIVATE_KEY - _APP_EXPERIMENT_LOGGING_PROVIDER - _APP_EXPERIMENT_LOGGING_CONFIG - _APP_DATABASE_SHARED_TABLES diff --git a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php index b133346585..1fefb7c983 100644 --- a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php +++ b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php @@ -135,6 +135,7 @@ final class OAuth2ProviderTest extends TestCase yield 'dailymotion' => ['dailymotion', $actions['dailymotion'], 'apiKey', 'apiSecret']; yield 'bitbucket' => ['bitbucket', $actions['bitbucket'], 'key', 'secret']; yield 'dropbox' => ['dropbox', DropboxUpdate::class, 'appKey', 'appSecret']; + yield 'cursor' => ['cursor', $actions['cursor'], 'clientId', 'privateKey']; yield 'etsy' => ['etsy', $actions['etsy'], 'keyString', 'sharedSecret']; yield 'facebook' => ['facebook', $actions['facebook'], 'appId', 'appSecret']; yield 'notion' => ['notion', $actions['notion'], 'oauthClientId', 'oauthClientSecret']; From 394ff720bcd08b5a7e6f4660b2890f637b6bdac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 13:32:19 +0200 Subject: [PATCH 17/53] Cleanup --- app/config/console.php | 3 - app/config/oAuthProviders.php | 11 --- app/config/variables.php | 8 +- app/init/models.php | 2 - docker-compose.yml | 8 +- src/Appwrite/Auth/OAuth2/Cursor.php | 35 ++++---- .../Project/Http/Project/OAuth2/Base.php | 1 - .../Http/Project/OAuth2/Cursor/Update.php | 65 --------------- .../Modules/Project/Services/Http.php | 2 - .../VCS/Http/Codebase/Events/Create.php | 54 ------------ .../{Codebase => Origin}/Authorize/Get.php | 25 +++--- .../{Codebase => Origin}/Callback/Get.php | 83 ++++++++++--------- .../Modules/VCS/Http/Origin/Events/Create.php | 58 +++++++++++++ .../Platform/Modules/VCS/Services/Http.php | 14 ++-- src/Appwrite/Utopia/Response.php | 1 - .../Utopia/Response/Model/OAuth2Cursor.php | 67 --------------- .../Project/OAuth2/OAuth2ProviderTest.php | 3 +- 17 files changed, 145 insertions(+), 295 deletions(-) delete mode 100644 src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php delete mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php rename src/Appwrite/Platform/Modules/VCS/Http/{Codebase => Origin}/Authorize/Get.php (66%) rename src/Appwrite/Platform/Modules/VCS/Http/{Codebase => Origin}/Callback/Get.php (67%) create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php delete mode 100644 src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php diff --git a/app/config/console.php b/app/config/console.php index 9e6fd7e35b..8a741030b6 100644 --- a/app/config/console.php +++ b/app/config/console.php @@ -58,9 +58,6 @@ $console = [ 'githubEnabled' => true, 'githubSecret' => System::getEnv('_APP_CONSOLE_GITHUB_SECRET', ''), 'githubAppid' => System::getEnv('_APP_CONSOLE_GITHUB_APP_ID', ''), - 'cursorEnabled' => true, - 'cursorSecret' => System::getEnv('_APP_CONSOLE_CURSOR_PRIVATE_KEY', ''), - 'cursorAppid' => System::getEnv('_APP_CONSOLE_CURSOR_APP_ID', ''), ], 'smtpBaseTemplate' => APP_BRANDED_EMAIL_BASE_TEMPLATE, ]; diff --git a/app/config/oAuthProviders.php b/app/config/oAuthProviders.php index 113a088032..31f1585b5c 100644 --- a/app/config/oAuthProviders.php +++ b/app/config/oAuthProviders.php @@ -101,17 +101,6 @@ return [ 'mock' => false, 'class' => 'Appwrite\\Auth\\OAuth2\\Box', ], - 'cursor' => [ - 'name' => 'Cursor', - 'developers' => 'https://cursor.com/docs/api', - 'icon' => 'icon-cursor', - 'enabled' => true, - 'sandbox' => false, - 'form' => false, - 'beta' => false, - 'mock' => false, - 'class' => 'Appwrite\\Auth\\OAuth2\\Cursor', - ], 'dailymotion' => [ 'name' => 'Dailymotion', 'developers' => 'https://developers.dailymotion.com/api/', diff --git a/app/config/variables.php b/app/config/variables.php index 346f9bcc59..443dc19f66 100644 --- a/app/config/variables.php +++ b/app/config/variables.php @@ -1393,8 +1393,8 @@ return [ 'filter' => '' ], [ - 'name' => '_APP_VCS_CODEBASE_CLIENT_ID', - 'description' => 'Codebase app client ID. You can find it in your Codebase app details on Cursor.', + 'name' => '_APP_VCS_ORIGIN_CLIENT_ID', + 'description' => 'Origin app client ID. You can find it in your Origin app details on Cursor.', 'introduction' => '2.0.0', 'default' => '', 'required' => false, @@ -1402,8 +1402,8 @@ return [ 'filter' => '' ], [ - 'name' => '_APP_VCS_CODEBASE_PRIVATE_KEY', - 'description' => 'Codebase app private key. You can generate private keys from your Codebase app settings on Cursor.', + 'name' => '_APP_VCS_ORIGIN_PRIVATE_KEY', + 'description' => 'Origin app private key. You can generate private keys from your Origin app settings on Cursor.', 'introduction' => '2.0.0', 'default' => '', 'required' => false, diff --git a/app/init/models.php b/app/init/models.php index 6f257f5f4b..41651c9262 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -126,7 +126,6 @@ use Appwrite\Utopia\Response\Model\OAuth2Autodesk; use Appwrite\Utopia\Response\Model\OAuth2Bitbucket; use Appwrite\Utopia\Response\Model\OAuth2Bitly; use Appwrite\Utopia\Response\Model\OAuth2Box; -use Appwrite\Utopia\Response\Model\OAuth2Cursor; use Appwrite\Utopia\Response\Model\OAuth2Dailymotion; use Appwrite\Utopia\Response\Model\OAuth2Discord; use Appwrite\Utopia\Response\Model\OAuth2Disqus; @@ -464,7 +463,6 @@ Response::setModel(new OAuth2Okta()); Response::setModel(new OAuth2Kick()); Response::setModel(new OAuth2Apple()); Response::setModel(new OAuth2Microsoft()); -Response::setModel(new OAuth2Cursor()); Response::setModel(new OAuth2ProviderList()); Response::setModel(new PolicyPasswordDictionary()); Response::setModel(new PolicyPasswordHistory()); diff --git a/docker-compose.yml b/docker-compose.yml index b6e8fa0118..64f16a1347 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -210,15 +210,13 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET - - _APP_VCS_CODEBASE_CLIENT_ID - - _APP_VCS_CODEBASE_PRIVATE_KEY + - _APP_VCS_ORIGIN_CLIENT_ID + - _APP_VCS_ORIGIN_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_MIGRATIONS_FIREBASE_CLIENT_ID - _APP_MIGRATIONS_FIREBASE_CLIENT_SECRET - _APP_ASSISTANT_OPENAI_API_KEY - _APP_CONSOLE_COUNTRIES_DENYLIST - - _APP_CONSOLE_CURSOR_APP_ID - - _APP_CONSOLE_CURSOR_PRIVATE_KEY - _APP_EXPERIMENT_LOGGING_PROVIDER - _APP_EXPERIMENT_LOGGING_CONFIG - _APP_DATABASE_SHARED_TABLES @@ -516,7 +514,7 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET - - _APP_VCS_CODEBASE_PRIVATE_KEY + - _APP_VCS_ORIGIN_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_FUNCTIONS_TIMEOUT - _APP_SITES_TIMEOUT diff --git a/src/Appwrite/Auth/OAuth2/Cursor.php b/src/Appwrite/Auth/OAuth2/Cursor.php index 2f3149c01a..f1186ba57c 100644 --- a/src/Appwrite/Auth/OAuth2/Cursor.php +++ b/src/Appwrite/Auth/OAuth2/Cursor.php @@ -11,7 +11,12 @@ use Appwrite\Auth\OAuth2; // Cursor Origin apps are not a user-login provider: installs are approved on // cursor.com and confirmed with an EdDSA-signed installation receipt instead // of an authorization code, and API access tokens are minted from an app JWT -// signed with the app's Ed25519 private key ($appSecret holds the PKCS#8 PEM). +// signed with the app's Ed25519 private key. +// +// Like Apple, the secret is a JSON object: `{"privateKey": "..."}` with the +// PKCS#8 PEM. The private key is only needed to mint tokens -- an empty +// object `{}` is valid configuration for starting an install flow, which +// only requires the app ID. class Cursor extends OAuth2 { /** @@ -57,6 +62,7 @@ class Cursor extends OAuth2 $params['scope'] = \implode(' ', $this->getScopes()); } + // The Origin console still lives under the /codebase path on cursor.com. return 'https://cursor.com/codebase/apps/install?' . \http_build_query($params); } @@ -217,21 +223,6 @@ class Cursor extends OAuth2 return $this->getTokens($refreshToken); } - /** - * End-to-end credential check used when enabling the provider: signing - * the app JWT proves the private key is well-formed, and the zero-cost - * rate-limit endpoint rejects it with a 401 unless the app ID and key - * match a registered app. - * - * @throws Exception - */ - public function verifyCredentials(): void - { - $this->request('GET', $this->endpoint . '/rate_limit', [ - 'Authorization: Bearer ' . $this->getAppJWT(), - ]); - } - /** * Cursor Origin apps act as an installation, never as a user, so there is * no user identity behind an access token. @@ -285,15 +276,23 @@ class Cursor extends OAuth2 } /** - * Ed25519 secret key derived from the PKCS#8 PEM in $appSecret. + * Ed25519 secret key derived from the PKCS#8 PEM in the secret's + * `privateKey` field. * * @throws Exception */ protected function getSigningKey(): string { + $secret = \json_decode($this->appSecret, true); + $pem = \is_array($secret) ? ($secret['privateKey'] ?? '') : ''; + + if (empty($pem) || !\is_string($pem)) { + throw new Exception('Private key is not configured'); + } + // Keys configured through environment variables carry literal \n // sequences instead of newlines. - $pem = \str_replace(['\n', '-----BEGIN PRIVATE KEY-----', '-----END PRIVATE KEY-----'], '', $this->appSecret); + $pem = \str_replace(['\n', '-----BEGIN PRIVATE KEY-----', '-----END PRIVATE KEY-----'], '', $pem); $der = \base64_decode(\preg_replace('/\s+/', '', $pem) ?? '', true); // RFC 8410 PKCS#8 wraps the 32-byte Ed25519 seed in a nested octet diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php index 0739e7a275..cb58c1cfc0 100644 --- a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php +++ b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Base.php @@ -319,7 +319,6 @@ abstract class Base extends Action 'kick' => Kick\Update::class, 'apple' => Apple\Update::class, 'microsoft' => Microsoft\Update::class, - 'cursor' => Cursor\Update::class, ]; } diff --git a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php b/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php deleted file mode 100644 index c11cd8221e..0000000000 --- a/src/Appwrite/Platform/Modules/Project/Http/Project/OAuth2/Cursor/Update.php +++ /dev/null @@ -1,65 +0,0 @@ -addAction(UpdateOAuth2Kick::getName(), new UpdateOAuth2Kick()); $this->addAction(UpdateOAuth2Apple::getName(), new UpdateOAuth2Apple()); $this->addAction(UpdateOAuth2Microsoft::getName(), new UpdateOAuth2Microsoft()); - $this->addAction(UpdateOAuth2Cursor::getName(), new UpdateOAuth2Cursor()); } } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php deleted file mode 100644 index e44aae970d..0000000000 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Events/Create.php +++ /dev/null @@ -1,54 +0,0 @@ -setHttpMethod(Action::HTTP_REQUEST_METHOD_POST) - ->setHttpPath('/v1/vcs/codebase/events') - ->desc('Create event') - ->groups(['api', 'vcs']) - ->label('scope', 'public') - ->inject('request') - ->inject('response') - ->callback($this->action(...)); - } - - public function action( - Request $request, - Response $response - ) { - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] Event received'); - Console::log('[CODEBASE DEBUG] Event headers: ' . \json_encode($request->getHeaders())); - Console::log('[CODEBASE DEBUG] Event query params: ' . \json_encode($request->getParams())); - Console::log('[CODEBASE DEBUG] Event raw payload: ' . $request->getRawPayload()); - - $payload = \json_decode($request->getRawPayload(), true) ?? []; - - $event = $request->getHeaderLine('x-codebase-event', '') ?: ($payload['event'] ?? ''); - Span::add('vcs.codebase.event.name', $event); - Console::log('[CODEBASE DEBUG] Event name resolved to: "' . $event . '"'); - - // Codebase does not deliver push or pull request events yet, so events - // are only acknowledged to prevent delivery retries. - $response->json(['success' => true]); - } -} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php similarity index 66% rename from src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php rename to src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php index cb519c1ace..804edd6e11 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php @@ -1,6 +1,6 @@ setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/vcs/codebase/authorize') - ->desc('Create Codebase app installation') + ->setHttpPath('/v1/vcs/origin/authorize') + ->desc('Create Origin app installation') ->groups(['api', 'vcs']) ->label('scope', 'vcs.read') ->label('error', APP_VIEWS_DIR . '/general/error.phtml') ->label('sdk', new Method( namespace: 'vcs', group: 'installations', - name: 'createCodebaseInstallation', - description: 'Begin Appwrite\'s Codebase app installation to set up version control integration. This endpoint responds with a redirect URL to the Codebase app\'s installation page on Cursor. The Codebase app must be configured in your environment for this endpoint to work.', + name: 'createOriginInstallation', + description: 'Begin Appwrite\'s Origin app installation to set up version control integration. This endpoint responds with a redirect URL to the Origin app\'s installation page on Cursor. The Origin app must be configured in your environment for this endpoint to work.', auth: [AuthType::ADMIN], responses: [ new SDKResponse( @@ -66,18 +66,19 @@ class Get extends Action Document $project, array $platform ) { - $clientId = System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID'); + $clientId = System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID'); if (empty($clientId)) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Codebase client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Origin client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); } - $oauth2 = new OAuth2Cursor($clientId, System::getEnv('_APP_VCS_CODEBASE_PRIVATE_KEY', ''), ''); + // The Cursor adapter expects its secret as a JSON object. + $oauth2 = new OAuth2Cursor($clientId, \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), ''); $url = $oauth2->getLoginURL(); - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); - Console::log('[CODEBASE DEBUG] Redirecting to install URL: ' . $url); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); + Console::log('[ORIGIN DEBUG] Redirecting to install URL: ' . $url); $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php similarity index 67% rename from src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php rename to src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php index 023ba6f369..437a47c0dd 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Codebase/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php @@ -1,6 +1,6 @@ setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/vcs/codebase/callback') - ->desc('Get installation from Codebase app') + ->setHttpPath('/v1/vcs/origin/callback') + ->desc('Get installation from Origin app') ->groups(['api', 'vcs']) ->label('scope', 'public') ->label('error', APP_VIEWS_DIR . '/general/error.phtml') - ->param('installation_id', '', new Text(256, 0), 'Codebase installation ID', true) - ->param('installation_receipt', '', new Text(4096, 0), 'Codebase installation receipt JWT, signed by Cursor.', true) - ->param('state', '', new Text(2048), 'Codebase state. Contains info sent when starting the installation flow.', true) + ->param('installation_id', '', new Text(256, 0), 'Origin installation ID', true) + ->param('installation_receipt', '', new Text(4096, 0), 'Origin installation receipt JWT, signed by Cursor.', true) + ->param('state', '', new Text(2048), 'Origin state. Contains info sent when starting the installation flow.', true) ->inject('request') ->inject('response') ->inject('dbForPlatform') @@ -55,25 +55,25 @@ class Get extends Action Database $dbForPlatform, array $platform ) { - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. $params = $request->getParams(); - Console::log('[CODEBASE DEBUG] Callback received'); - Console::log('[CODEBASE DEBUG] Callback params: ' . \json_encode($params)); - Console::log('[CODEBASE DEBUG] Callback headers: ' . \json_encode($request->getHeaders())); - Console::log('[CODEBASE DEBUG] Callback installation_id: "' . $providerInstallationId . '"'); + Console::log('[ORIGIN DEBUG] Callback received'); + Console::log('[ORIGIN DEBUG] Callback params: ' . \json_encode($params)); + Console::log('[ORIGIN DEBUG] Callback headers: ' . \json_encode($request->getHeaders())); + Console::log('[ORIGIN DEBUG] Callback installation_id: "' . $providerInstallationId . '"'); // Surface anything that looks like an OAuth2 token flow (e.g. a code - // exchange), since Codebase is not expected to send one. + // exchange), since Origin is not expected to send one. $oauthParams = \array_intersect_key($params, \array_flip([ 'code', 'token', 'access_token', 'refresh_token', 'expires_in', 'token_type', 'scope', 'id_token', 'setup_action', 'authuser', 'session_state', ])); if (!empty($oauthParams)) { - Console::log('[CODEBASE DEBUG] Possible OAuth2 flow params detected: ' . \json_encode($oauthParams)); + Console::log('[ORIGIN DEBUG] Possible OAuth2 flow params detected: ' . \json_encode($oauthParams)); } else { - Console::log('[CODEBASE DEBUG] No OAuth2 flow params detected'); + Console::log('[ORIGIN DEBUG] No OAuth2 flow params detected'); } - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. // Decode only -- the EdDSA signature is not verified, so the claims // must not be trusted for authorization decisions yet. if (!empty($installationReceipt)) { @@ -81,13 +81,13 @@ class Get extends Action if (\count($segments) === 3) { $receiptHeader = \json_decode(\base64_decode(\strtr($segments[0], '-_', '+/')), true) ?? []; $receiptClaims = \json_decode(\base64_decode(\strtr($segments[1], '-_', '+/')), true) ?? []; - Console::log('[CODEBASE DEBUG] Receipt JWT header: ' . \json_encode($receiptHeader)); - Console::log('[CODEBASE DEBUG] Receipt JWT claims: ' . \json_encode($receiptClaims)); + Console::log('[ORIGIN DEBUG] Receipt JWT header: ' . \json_encode($receiptHeader)); + Console::log('[ORIGIN DEBUG] Receipt JWT claims: ' . \json_encode($receiptClaims)); } else { - Console::log('[CODEBASE DEBUG] installation_receipt is not a JWT: ' . $installationReceipt); + Console::log('[ORIGIN DEBUG] installation_receipt is not a JWT: ' . $installationReceipt); } } else { - Console::log('[CODEBASE DEBUG] No installation_receipt received'); + Console::log('[ORIGIN DEBUG] No installation_receipt received'); } if (empty($state)) { @@ -98,20 +98,20 @@ class Get extends Action $redirectFailure = $state['failure'] ?? ''; $projectId = $state['projectId'] ?? ''; - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] Decoded state: ' . \json_encode($state)); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] Decoded state: ' . \json_encode($state)); - // This endpoint is public and Codebase performs no token exchange -- + // This endpoint is public and Origin performs no token exchange -- // without verifying the signature the Authorize action put in state, // anyone could pass an arbitrary projectId here and attach an // installation to another project. $signature = \hash_hmac('sha256', \json_encode([$projectId, $state['success'] ?? '', $redirectFailure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')); if (!\hash_equals($signature, $state['signature'] ?? '')) { - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] State signature mismatch, rejecting callback'); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] State signature mismatch, rejecting callback'); throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Invalid state parameter. Please restart the installation from the Appwrite Console.'); } - Console::log('[CODEBASE DEBUG] State signature valid'); + Console::log('[ORIGIN DEBUG] State signature valid'); $project = $dbForPlatform->getDocument('projects', $projectId); @@ -134,17 +134,18 @@ class Get extends Action $redirectFailure = $state['failure'] ?? ''; if (empty($providerInstallationId)) { - $this->failure($response, $redirectFailure, 'Codebase installation ID is missing.'); + $this->failure($response, $redirectFailure, 'Origin installation ID is missing.'); return; } // Authenticate the callback by verifying the installation receipt // against Cursor's published JWKS. This proves the request genuinely - // originates from Codebase (the callback is public and has no token + // originates from Origin (the callback is public and has no token // exchange) before any installation is created. + // The Cursor adapter expects its secret as a JSON object. $oauth2 = new OAuth2Cursor( - System::getEnv('_APP_VCS_CODEBASE_CLIENT_ID', ''), - System::getEnv('_APP_VCS_CODEBASE_PRIVATE_KEY', ''), + System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), + \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), '' ); @@ -158,21 +159,21 @@ class Get extends Action throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Receipt subject does not match installation ID'); } } catch (\Throwable $e) { - Console::log('[CODEBASE DEBUG] Receipt verification failed: ' . $e->getMessage()); - $this->failure($response, $redirectFailure, 'Could not verify the Codebase installation receipt.'); + Console::log('[ORIGIN DEBUG] Receipt verification failed: ' . $e->getMessage()); + $this->failure($response, $redirectFailure, 'Could not verify the Origin installation receipt.'); return; } // The Cursor namespace (team/workspace) owning the installation. $organization = $receiptClaims['namespace_id'] ?? ''; - Console::log('[CODEBASE DEBUG] Receipt verified, namespace_id: "' . $organization . '"'); + Console::log('[ORIGIN DEBUG] Receipt verified, namespace_id: "' . $organization . '"'); $projectInternalId = $project->getSequence(); $installation = $dbForPlatform->findOne('installations', [ Query::equal('providerInstallationId', [$providerInstallationId]), Query::equal('projectInternalId', [$projectInternalId]), - Query::equal('provider', ['codebase']), + Query::equal('provider', ['origin']), ]); if ($installation->isEmpty()) { @@ -184,22 +185,22 @@ class Get extends Action 'providerInstallationId' => $providerInstallationId, 'projectId' => $projectId, 'projectInternalId' => $projectInternalId, - 'provider' => 'codebase', + 'provider' => 'origin', 'organization' => $organization, 'personal' => false, ])); - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] Created installation "' . $installation->getId() . '" for project "' . $projectId . '"'); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] Created installation "' . $installation->getId() . '" for project "' . $projectId . '"'); } else { $installation = $dbForPlatform->updateDocument('installations', $installation->getId(), new Document([ 'organization' => $organization, ])); - Console::log('[CODEBASE DEBUG] Installation already exists: "' . $installation->getId() . '"'); + Console::log('[ORIGIN DEBUG] Installation already exists: "' . $installation->getId() . '"'); } - Console::log('[CODEBASE DEBUG] Redirecting to success URL: ' . $redirectSuccess); + Console::log('[ORIGIN DEBUG] Redirecting to success URL: ' . $redirectSuccess); $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') @@ -212,8 +213,8 @@ class Get extends Action */ private function failure(Response $response, string $redirect, string $error, string $type = Exception::GENERAL_ARGUMENT_INVALID): void { - // TODO: Temporary debug logging while the Codebase integration is verified -- remove afterwards. - Console::log('[CODEBASE DEBUG] Callback failed: ' . $error . ' (redirect: "' . $redirect . '")'); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] Callback failed: ' . $error . ' (redirect: "' . $redirect . '")'); if (empty($redirect)) { throw new Exception($type, $error); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php new file mode 100644 index 0000000000..aac94ffa02 --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -0,0 +1,58 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_POST) + ->setHttpPath('/v1/vcs/origin/events') + ->desc('Create event') + ->groups(['api', 'vcs']) + ->label('scope', 'public') + ->inject('request') + ->inject('response') + ->callback($this->action(...)); + } + + public function action( + Request $request, + Response $response + ) { + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN DEBUG] Event received'); + Console::log('[ORIGIN DEBUG] Event headers: ' . \json_encode($request->getHeaders())); + Console::log('[ORIGIN DEBUG] Event query params: ' . \json_encode($request->getParams())); + Console::log('[ORIGIN DEBUG] Event raw payload: ' . $request->getRawPayload()); + + $payload = \json_decode($request->getRawPayload(), true) ?? []; + + // The delivery header is not confirmed yet -- accept both the Origin + // name and the pre-rename Codebase one. + $event = $request->getHeaderLine('x-origin-event', '') + ?: $request->getHeaderLine('x-codebase-event', '') + ?: ($payload['event'] ?? ''); + Span::add('vcs.origin.event.name', $event); + Console::log('[ORIGIN DEBUG] Event name resolved to: "' . $event . '"'); + + // Origin does not deliver push or pull request events yet, so events + // are only acknowledged to prevent delivery retries. + $response->json(['success' => true]); + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Services/Http.php b/src/Appwrite/Platform/Modules/VCS/Services/Http.php index 13a8e5bb74..71498db484 100644 --- a/src/Appwrite/Platform/Modules/VCS/Services/Http.php +++ b/src/Appwrite/Platform/Modules/VCS/Services/Http.php @@ -5,9 +5,6 @@ namespace Appwrite\Platform\Modules\VCS\Services; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Authorize\Get as GetBitbucketAuthorize; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Callback\Get as GetBitbucketCallback; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Events\Create as CreateBitbucketEvent; -use Appwrite\Platform\Modules\VCS\Http\Codebase\Authorize\Get as GetCodebaseAuthorize; -use Appwrite\Platform\Modules\VCS\Http\Codebase\Callback\Get as GetCodebaseCallback; -use Appwrite\Platform\Modules\VCS\Http\Codebase\Events\Create as CreateCodebaseEvent; use Appwrite\Platform\Modules\VCS\Http\Gitea\Authorize\Get as GetGiteaAuthorize; use Appwrite\Platform\Modules\VCS\Http\Gitea\Callback\Get as GetGiteaCallback; use Appwrite\Platform\Modules\VCS\Http\Gitea\Events\Create as CreateGiteaEvent; @@ -28,6 +25,9 @@ use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\Detections\Cre use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\Get as GetRepository; use Appwrite\Platform\Modules\VCS\Http\Installations\Repositories\XList as ListRepositories; use Appwrite\Platform\Modules\VCS\Http\Installations\XList as ListInstallations; +use Appwrite\Platform\Modules\VCS\Http\Origin\Authorize\Get as GetOriginAuthorize; +use Appwrite\Platform\Modules\VCS\Http\Origin\Callback\Get as GetOriginCallback; +use Appwrite\Platform\Modules\VCS\Http\Origin\Events\Create as CreateOriginEvent; use Utopia\Platform\Service; class Http extends Service @@ -53,9 +53,9 @@ class Http extends Service $this->addAction(GetBitbucketAuthorize::getName(), new GetBitbucketAuthorize()); $this->addAction(GetBitbucketCallback::getName(), new GetBitbucketCallback()); - // Codebase Authorization & Callback - $this->addAction(GetCodebaseAuthorize::getName(), new GetCodebaseAuthorize()); - $this->addAction(GetCodebaseCallback::getName(), new GetCodebaseCallback()); + // Origin Authorization & Callback + $this->addAction(GetOriginAuthorize::getName(), new GetOriginAuthorize()); + $this->addAction(GetOriginCallback::getName(), new GetOriginCallback()); // Installations $this->addAction(GetInstallation::getName(), new GetInstallation()); @@ -76,6 +76,6 @@ class Http extends Service $this->addAction(CreateGiteaEvent::getName(), new CreateGiteaEvent()); $this->addAction(CreateGitlabEvent::getName(), new CreateGitlabEvent()); $this->addAction(CreateBitbucketEvent::getName(), new CreateBitbucketEvent()); - $this->addAction(CreateCodebaseEvent::getName(), new CreateCodebaseEvent()); + $this->addAction(CreateOriginEvent::getName(), new CreateOriginEvent()); } } diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index c1270b5976..80dd69bd38 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -327,7 +327,6 @@ class Response extends SwooleResponse public const MODEL_OAUTH2_OKTA = 'oAuth2Okta'; public const MODEL_OAUTH2_KICK = 'oAuth2Kick'; public const MODEL_OAUTH2_MICROSOFT = 'oAuth2Microsoft'; - public const MODEL_OAUTH2_CURSOR = 'oAuth2Cursor'; public const MODEL_OAUTH2_PROVIDER_LIST = 'oAuth2ProviderList'; // Health diff --git a/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php b/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php deleted file mode 100644 index 7f7f7956d1..0000000000 --- a/src/Appwrite/Utopia/Response/Model/OAuth2Cursor.php +++ /dev/null @@ -1,67 +0,0 @@ - 'cursor', - ]; - - public function getProviderLabel(): string - { - return 'Cursor'; - } - - public function getClientIdExample(): string - { - return 'app_01k5wz9v3rq8tembsy0d4hxnpc'; - } - - public function getClientSecretExample(): string - { - return '-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n-----END PRIVATE KEY-----'; - } - - public function getClientIdLabel(): string - { - return 'app ID'; - } - - public function getClientSecretFieldName(): string - { - return 'privateKey'; - } - - public function getClientSecretLabel(): string - { - return 'private key'; - } - - public function getClientSecretDescription(): string - { - return parent::getClientSecretDescription() . ' Ed25519 key in PKCS#8 PEM format; only its public key is registered with Cursor.'; - } - - /** - * Get Name - * - * @return string - */ - public function getName(): string - { - return 'OAuth2Cursor'; - } - - /** - * Get Type - * - * @return string - */ - public function getType(): string - { - return Response::MODEL_OAUTH2_CURSOR; - } -} diff --git a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php index 1fefb7c983..63c1b1012f 100644 --- a/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php +++ b/tests/unit/Platform/Modules/Project/OAuth2/OAuth2ProviderTest.php @@ -38,7 +38,7 @@ final class OAuth2ProviderTest extends TestCase $expected = [ 'amazon', 'apple', 'appwrite', 'auth0', 'authentik', 'autodesk', - 'bitbucket', 'bitly', 'box', 'cursor', 'dailymotion', 'discord', 'disqus', + 'bitbucket', 'bitly', 'box', 'dailymotion', 'discord', 'disqus', 'dropbox', 'etsy', 'facebook', 'figma', 'fusionauth', 'github', 'gitlab', 'google', 'keycloak', 'kick', 'linkedin', 'microsoft', 'notion', 'oidc', 'okta', 'paypal', 'paypalSandbox', 'podio', @@ -135,7 +135,6 @@ final class OAuth2ProviderTest extends TestCase yield 'dailymotion' => ['dailymotion', $actions['dailymotion'], 'apiKey', 'apiSecret']; yield 'bitbucket' => ['bitbucket', $actions['bitbucket'], 'key', 'secret']; yield 'dropbox' => ['dropbox', DropboxUpdate::class, 'appKey', 'appSecret']; - yield 'cursor' => ['cursor', $actions['cursor'], 'clientId', 'privateKey']; yield 'etsy' => ['etsy', $actions['etsy'], 'keyString', 'sharedSecret']; yield 'facebook' => ['facebook', $actions['facebook'], 'appId', 'appSecret']; yield 'notion' => ['notion', $actions['notion'], 'oauthClientId', 'oauthClientSecret']; From b2b02b139271b1327ccc64841a399bb69a964a0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 14:38:35 +0200 Subject: [PATCH 18/53] feat: finish Origin (Cursor) VCS provider support Completes the Origin integration started on this branch: - Register 'origin' in the VCS provider registry, wiring the new utopia-php/vcs Origin adapter (dev-feat-origin) so installations, repository listing/creation, branches, contents, detections and namespaces work through the existing provider-agnostic endpoints - Authorize flow now sends HMAC-signed state and the registered callback to Cursor's install page, with the full scope list the integration needs - Callback verifies the installation receipt first, reads state from its claims (query parameter as fallback), binds the receipt subject to the installation, and resolves the owner slug for the installation's organization - Events endpoint verifies deliveries against Origin's published Ed25519 JWKS (with timestamp freshness and key-rotation refetch) and dispatches push, pull request and installation events into the same deployment pipeline as GitHub, including multi-ref pushes - Build statuses ride the adapter's check-run-backed commit statuses; PR comments work through the existing Comment flow unchanged - New GET /v1/vcs/archives endpoint packages a repository server-side behind an HMAC-signed expiring link, and Appwrite\Vcs\SourceArchive routes every deployment source fetch through it when a provider (Origin) offers no archive downloads Removes the temporary [ORIGIN DEBUG] logging. Co-Authored-By: Claude Fable 5 --- app/config/vcs.php | 22 ++ app/init/constants.php | 1 + composer.json | 2 +- composer.lock | 17 +- .../vcs/create-origin-installation.md | 1 + src/Appwrite/Auth/OAuth2/Cursor.php | 12 +- .../Platform/Modules/Compute/Base.php | 11 +- .../Http/Deployments/Duplicate/Create.php | 8 +- .../Modules/Functions/Workers/Builds.php | 6 +- .../Http/Deployments/Duplicate/Create.php | 6 +- .../Modules/VCS/Http/Archives/Get.php | 114 ++++++ .../Modules/VCS/Http/GitHub/Deployment.php | 6 +- .../Modules/VCS/Http/Origin/Authorize/Get.php | 59 ++- .../Modules/VCS/Http/Origin/Callback/Get.php | 131 +++---- .../Modules/VCS/Http/Origin/Events/Create.php | 360 +++++++++++++++++- .../Platform/Modules/VCS/Services/Http.php | 4 + src/Appwrite/Vcs/SourceArchive.php | 66 ++++ 17 files changed, 687 insertions(+), 139 deletions(-) create mode 100644 docs/references/vcs/create-origin-installation.md create mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php create mode 100644 src/Appwrite/Vcs/SourceArchive.php diff --git a/app/config/vcs.php b/app/config/vcs.php index d3a5dc8279..141b987b42 100644 --- a/app/config/vcs.php +++ b/app/config/vcs.php @@ -5,6 +5,7 @@ */ use Appwrite\Auth\OAuth2\Bitbucket as OAuth2Bitbucket; +use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Auth\OAuth2\Gitea as OAuth2Gitea; use Appwrite\Auth\OAuth2\Github as OAuth2Github; use Appwrite\Auth\OAuth2\Gitlab as OAuth2Gitlab; @@ -12,6 +13,7 @@ use Utopia\VCS\Adapter\Git\Bitbucket; use Utopia\VCS\Adapter\Git\Gitea; use Utopia\VCS\Adapter\Git\GitHub; use Utopia\VCS\Adapter\Git\GitLab; +use Utopia\VCS\Adapter\Git\Origin; return [ 'github' => [ @@ -62,6 +64,26 @@ return [ 'webhookSecret' => ['required' => true, 'envVariable' => '_APP_VCS_GITLAB_WEBHOOK_SECRET'], ], ], + 'origin' => [ + 'adapter' => Origin::class, + // Origin apps authenticate like GitHub Apps (an app-signed JWT minting + // installation tokens), so the same Ed25519 private key doubles as the + // OAuth2 secret. Auth\OAuth2\Cursor expects it JSON-wrapped, the way + // Apple does. + 'oauth2' => fn (string $clientId, string $clientSecret, string $endpoint) => new OAuth2Cursor($clientId, \json_encode([ + 'privateKey' => $clientSecret, + ]), ''), + 'variables' => [ + 'clientId' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_CLIENT_ID'], + // Factory::fromInstallation() reads appId + privateKey; the app id + // and OAuth2 client id are the same value on Origin. + 'appId' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_CLIENT_ID'], + 'privateKey' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_PRIVATE_KEY'], + 'clientSecret' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_PRIVATE_KEY'], + // No webhookSecret: Origin signs deliveries with its own Ed25519 + // key, verified against its published JWKS instead of a shared secret. + ], + ], 'bitbucket' => [ 'adapter' => Bitbucket::class, 'oauth2' => fn (string $clientId, string $clientSecret, string $endpoint) => new OAuth2Bitbucket($clientId, $clientSecret, ''), diff --git a/app/init/constants.php b/app/init/constants.php index 61d861936b..96ded3139b 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -114,6 +114,7 @@ const APP_VCS_GITHUB_URL = 'https://github.com/TeamAppwrite'; const APP_VCS_GITEA_EMAIL = 'team@appwrite.io'; // Used to detect Appwrite's own commits const APP_VCS_GITLAB_EMAIL = 'team@appwrite.io'; // Used to detect Appwrite's own commits const APP_VCS_BITBUCKET_EMAIL = 'team@appwrite.io'; // Used to detect Appwrite's own commits +const APP_VCS_ORIGIN_EMAIL = 'vcs@utopia.dev'; // Used to detect commits the VCS adapter pushes over Git HTTPS const APP_BRANDED_EMAIL_BASE_TEMPLATE = 'email-base-styled'; // Embeddings diff --git a/composer.json b/composer.json index 8e5b888dbe..a75d860459 100644 --- a/composer.json +++ b/composer.json @@ -99,7 +99,7 @@ "utopia-php/telemetry": "^0.4", "utopia-php/user-agent": "0.1.*", "mustangostang/spyc": "0.6.*", - "utopia-php/vcs": "5.*.*", + "utopia-php/vcs": "dev-feat-origin", "utopia-php/websocket": "1.0.*", "dragonmantank/cron-expression": "3.4.*", "chillerlan/php-qrcode": "4.3.*", diff --git a/composer.lock b/composer.lock index e21c79dec2..e0708c1fb9 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "c7acee2d0fe6b2299e47df05257a7225", + "content-hash": "f22cd38378c2891b4656c4c756478e6c", "packages": [ { "name": "adhocore/jwt", @@ -5031,16 +5031,16 @@ }, { "name": "utopia-php/vcs", - "version": "5.1.2", + "version": "dev-feat-origin", "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "abdb5763221d7e4900174c280244f83638e3133e" + "reference": "cbf57939aa7f0d40c5e6ab9120e13b3247bd767a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/abdb5763221d7e4900174c280244f83638e3133e", - "reference": "abdb5763221d7e4900174c280244f83638e3133e", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/cbf57939aa7f0d40c5e6ab9120e13b3247bd767a", + "reference": "cbf57939aa7f0d40c5e6ab9120e13b3247bd767a", "shasum": "" }, "require": { @@ -5091,10 +5091,10 @@ "vcs" ], "support": { - "source": "https://github.com/utopia-php/vcs/tree/5.1.2", + "source": "https://github.com/utopia-php/vcs/tree/feat-origin", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-07T12:32:15+00:00" + "time": "2026-08-18T12:28:48+00:00" }, { "name": "utopia-php/websocket", @@ -8401,7 +8401,8 @@ "minimum-stability": "dev", "stability-flags": { "utopia-php/http": 5, - "utopia-php/platform": 5 + "utopia-php/platform": 5, + "utopia-php/vcs": 20 }, "prefer-stable": true, "prefer-lowest": false, diff --git a/docs/references/vcs/create-origin-installation.md b/docs/references/vcs/create-origin-installation.md new file mode 100644 index 0000000000..264763aae1 --- /dev/null +++ b/docs/references/vcs/create-origin-installation.md @@ -0,0 +1 @@ +Begin Appwrite's Origin app installation to set up version control integration. This endpoint responds with a redirect URL to the Origin app's installation page on Cursor. The Origin app must be configured in your environment for this endpoint to work. diff --git a/src/Appwrite/Auth/OAuth2/Cursor.php b/src/Appwrite/Auth/OAuth2/Cursor.php index f1186ba57c..53b2232ad3 100644 --- a/src/Appwrite/Auth/OAuth2/Cursor.php +++ b/src/Appwrite/Auth/OAuth2/Cursor.php @@ -47,8 +47,6 @@ class Cursor extends OAuth2 public function getLoginURL(): string { - // The install page ignores redirect_uri and state parameters -- the - // callback URL is taken from the app's own configuration on Cursor. $params = [ 'client_id' => $this->appID, ]; @@ -62,6 +60,16 @@ class Cursor extends OAuth2 $params['scope'] = \implode(' ', $this->getScopes()); } + // The callback must exactly match a redirect URI registered on the + // app; Cursor echoes state back as the receipt's `state` claim. + if (!empty($this->callback)) { + $params['redirect_uri'] = $this->callback; + } + + if (!empty($this->state)) { + $params['state'] = \json_encode($this->state); + } + // The Origin console still lives under the /codebase path on cursor.com. return 'https://cursor.com/codebase/apps/install?' . \http_build_query($params); } diff --git a/src/Appwrite/Platform/Modules/Compute/Base.php b/src/Appwrite/Platform/Modules/Compute/Base.php index 77fae4af98..90b39bd812 100644 --- a/src/Appwrite/Platform/Modules/Compute/Base.php +++ b/src/Appwrite/Platform/Modules/Compute/Base.php @@ -11,6 +11,7 @@ use Appwrite\Platform\Action; use Appwrite\Platform\Modules\Compute\Validator\Specification as SpecificationValidator; use Appwrite\Platform\Permission as AppwritePermission; use Appwrite\Vcs\Factory as VcsFactory; +use Appwrite\Vcs\SourceArchive; use Utopia\Config\Config; use Utopia\Database\Database; use Utopia\Database\Document; @@ -172,12 +173,13 @@ class Base extends Action // git write and then hands the build to the jobs-service itself. if ($template->isEmpty()) { $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($vcs, $installation->getAttribute('providerInstallationId', ''), $owner, $repositoryName, $ref, $platform); $deployment = $deployments->createFromUrl( $function, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repositoryName, $ref), + $sourceUrl, $function->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, ); } else { $deployment = $dbForProject->createDocument('deployments', new Document([ @@ -394,12 +396,13 @@ class Base extends Action // pushes go through the Builds worker (same split as redeployVcsFunction). if ($template->isEmpty()) { $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($vcs, $installation->getAttribute('providerInstallationId', ''), $owner, $repositoryName, $ref, $platform); $deployment = $deployments->createFromUrl( $site, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repositoryName, $ref), + $sourceUrl, $site->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, ); } else { $publisherForBuilds->enqueue(new BuildMessage( diff --git a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php index 55616a18b7..3e23e1f1d7 100644 --- a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php +++ b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php @@ -10,6 +10,7 @@ use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; use Appwrite\Vcs\Factory as VcsFactory; +use Appwrite\Vcs\SourceArchive; use Utopia\Database\Database; use Utopia\Database\Helpers\ID; use Utopia\Database\Validator\UID; @@ -67,6 +68,7 @@ class Create extends Action ->inject('deployments') ->inject('deviceForFunctions') ->inject('vcsFactory') + ->inject('platform') ->callback($this->action(...)); } @@ -81,6 +83,7 @@ class Create extends Action Deployments $deployments, Device $deviceForFunctions, VcsFactory $vcsFactory, + array $platform, ) { $function = $dbForProject->getDocument('functions', $functionId); @@ -157,12 +160,13 @@ class Create extends Action $github = $vcsFactory->fromInstallation($installation); $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($github, $installation->getAttribute('providerInstallationId', ''), $owner, $repository, $ref, $platform); $deployment = $deployments->createFromUrl( $function, $deployment, - $github->getRepositoryPresignedUrl($owner, $repository, $ref), + $sourceUrl, $deployment->getAttribute('providerRootDirectory', ''), - $github->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, ); } else { // Public template repo: providerBranch holds the resolved ref, diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 776f0adae6..62c6290ad0 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -9,6 +9,7 @@ use Appwrite\Event\Realtime; use Appwrite\Usage\Build as BuildUsage; use Appwrite\Usage\Context; use Appwrite\Vcs\Factory as VcsFactory; +use Appwrite\Vcs\SourceArchive; use Exception; use Utopia\Config\Config; use Utopia\Console; @@ -401,12 +402,13 @@ class Builds extends Action // jobs-service like any other VCS commit, via the same Deployments // service the HTTP endpoints use. $ref = $deployment->getAttribute('providerCommitHash') ?: $branchName; + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($providerAdapter, $providerInstallationId, $cloneOwner, $cloneRepository, $ref, $platform); $deployments->createFromUrl( $resource, $deployment, - $providerAdapter->getRepositoryPresignedUrl($cloneOwner, $cloneRepository, $ref), + $sourceUrl, $resource->getAttribute('providerRootDirectory', ''), - $providerAdapter->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, ); Console::execute('rm -rf ' . \escapeshellarg('/tmp/builds/' . $deploymentId), '', $stdout, $stderr); diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php index f0d5755c24..2f2663db2e 100644 --- a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php +++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php @@ -10,6 +10,7 @@ use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; use Appwrite\Vcs\Factory as VcsFactory; +use Appwrite\Vcs\SourceArchive; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\ID; @@ -178,12 +179,13 @@ class Create extends Action $vcs = $vcsFactory->fromInstallation($installation); $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($vcs, $installation->getAttribute('providerInstallationId', ''), $owner, $repository, $ref, $platform); $deployment = $deployments->createFromUrl( $site, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repository, $ref), + $sourceUrl, $deployment->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, ); } else { // Public template repo: providerBranch holds the resolved ref, diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php new file mode 100644 index 0000000000..4951fa1a67 --- /dev/null +++ b/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php @@ -0,0 +1,114 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) + ->setHttpPath('/v1/vcs/archives') + ->desc('Download repository archive') + ->groups(['api', 'vcs']) + ->label('scope', 'public') + ->param('provider', '', new Text(64, 0), 'VCS provider the repository lives on.') + ->param('installation', '', new Text(256, 0), 'Provider installation ID the credentials belong to.') + ->param('owner', '', new Text(256, 0), 'Owner of the repository.') + ->param('repository', '', new Text(256, 0), 'Name of the repository.') + ->param('ref', '', new Text(256, 0), 'Branch, tag or commit to archive.') + ->param('expires', 0, new Integer(loose: true, bits: 64), 'Unix timestamp the link stops working at.') + ->param('signature', '', new Text(128, 0), 'HMAC binding every other parameter.') + ->inject('response') + ->inject('vcsFactory') + ->callback($this->action(...)); + } + + /** + * Packages a repository the provider cannot archive itself. The link is + * minted by Appwrite\Vcs\SourceArchive for the jobs-service source fetch, + * and the HMAC is the whole authorization: it commits to every parameter + * and an expiry, and only Appwrite can produce it. + */ + public function action( + string $provider, + string $installation, + string $owner, + string $repository, + string $ref, + int $expires, + string $signature, + Response $response, + VcsFactory $vcsFactory, + ) { + $expected = SourceArchive::signature($provider, $installation, $owner, $repository, $ref, $expires); + + if (empty($signature) || !\hash_equals($expected, $signature)) { + throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid archive signature.'); + } + + if ($expires < \time()) { + throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'The archive link has expired.'); + } + + $vcs = $vcsFactory->fromInstallation(new Document([ + 'provider' => $provider, + 'providerInstallationId' => $installation, + ])); + + // Git-forge archives wrap the tree in a "{repo}-{ref}/" root the + // source fetch strips, so this one has to match that shape. + $directory = '/tmp/vcs-archives/' . \uniqid(); + $wrapper = $repository . '-' . \substr(\preg_replace('/[^A-Za-z0-9._-]/', '-', $ref) ?? '', 0, 64); + $archive = $directory . '/archive.tar.gz'; + + $cloneType = \preg_match('/^[0-9a-f]{40}([0-9a-f]{24})?$/i', $ref) ? Git::CLONE_TYPE_COMMIT : Git::CLONE_TYPE_BRANCH; + $cloneCommand = $vcs->generateCloneCommand($owner, $repository, $ref, $cloneType, $directory . '/' . $wrapper, '*'); + + try { + $stdout = ''; + $stderr = ''; + + if (Console::execute($cloneCommand, '', $stdout, $stderr) !== 0) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to download the repository.'); + } + + $packCommand = 'tar --exclude=' . \escapeshellarg($wrapper . '/.git') . ' -czf ' . \escapeshellarg($archive) . ' -C ' . \escapeshellarg($directory) . ' ' . \escapeshellarg($wrapper); + if (Console::execute($packCommand, '', $stdout, $stderr) !== 0) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to package the repository.'); + } + + $contents = \file_get_contents($archive); + if ($contents === false) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to read the repository archive.'); + } + + $response + ->setContentType('application/gzip') + ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') + ->addHeader('Content-Disposition', 'attachment; filename="' . $wrapper . '.tar.gz"') + ->send($contents); + } finally { + Console::execute('rm -rf ' . \escapeshellarg($directory), '', $stdout, $stderr); + } + } +} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php index 535dffcb3f..742710ddb1 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php @@ -5,6 +5,7 @@ namespace Appwrite\Platform\Modules\VCS\Http\GitHub; use Appwrite\Extend\Exception; use Appwrite\Filter\BranchDomain as BranchDomainFilter; use Appwrite\Vcs\Comment; +use Appwrite\Vcs\SourceArchive; use Utopia\Config\Config; use Utopia\Console; use Utopia\Database\Database; @@ -391,13 +392,14 @@ trait Deployment // The Deployments service is built per repository: a webhook fans out to // many tenant projects, each with its own database. + [$sourceUrl, $sourceHeaders] = SourceArchive::presign($vcs, $providerInstallationId, $providerRepositoryOwner, $providerRepositoryName, $providerCommitHash, $platform); $deployment = $authorization->skip(fn () => $deploymentsFactory($dbForProject, $project) ->createFromUrl( $resource, $deployment, - $vcs->getRepositoryPresignedUrl($providerRepositoryOwner, $providerRepositoryName, $providerCommitHash), + $sourceUrl, $resource->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), + $sourceHeaders, )); if ($resource->getCollection() === 'sites') { diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php index 804edd6e11..1df76d5481 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php @@ -11,7 +11,6 @@ use Appwrite\SDK\Method; use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; -use Utopia\Console; use Utopia\Database\Document; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; @@ -20,6 +19,22 @@ class Get extends Action { use HTTP; + /** + * Everything the integration touches: cloning sources, pushing templates, + * deploying from pull requests, commenting on them, and reporting build + * checks. repository:metadata:read is granted implicitly. + */ + public const SCOPES = [ + 'repository:contents:read', + 'repository:contents:write', + 'repository:pull_requests:read', + 'repository:pull_requests:write', + 'repository:pull_requests:reviews:read', + 'repository:pull_requests:reviews:write', + 'repository:checks:read', + 'repository:checks:write', + ]; + public static function getName() { return 'getVCSOriginAuthorize'; @@ -38,7 +53,7 @@ class Get extends Action namespace: 'vcs', group: 'installations', name: 'createOriginInstallation', - description: 'Begin Appwrite\'s Origin app installation to set up version control integration. This endpoint responds with a redirect URL to the Origin app\'s installation page on Cursor. The Origin app must be configured in your environment for this endpoint to work.', + description: '/docs/references/vcs/create-origin-installation.md', auth: [AuthType::ADMIN], responses: [ new SDKResponse( @@ -56,6 +71,7 @@ class Get extends Action ->inject('response') ->inject('project') ->inject('platform') + ->inject('vcsConfigured') ->callback($this->action(...)); } @@ -64,25 +80,40 @@ class Get extends Action string $failure, Response $response, Document $project, - array $platform + array $platform, + callable $vcsConfigured, ) { - $clientId = System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID'); - - if (empty($clientId)) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Origin client ID is not configured. Please configure VCS (Version Control System) variables in .env file.'); + if (!$vcsConfigured('origin')) { + throw new Exception(Exception::GENERAL_SERVER_ERROR, 'This endpoint is not implemented on this server. Please configure VCS (Version Control System) variables in .env file.'); } - // The Cursor adapter expects its secret as a JSON object. - $oauth2 = new OAuth2Cursor($clientId, \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), ''); - $url = $oauth2->getLoginURL(); + $projectId = $project->getId(); - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] Authorize for project "' . $project->getId() . '" (success: "' . $success . '", failure: "' . $failure . '")'); - Console::log('[ORIGIN DEBUG] Redirecting to install URL: ' . $url); + // The callback is public and Origin performs no token exchange, so the + // state carries an HMAC binding the redirect targets to this project. + $state = [ + 'projectId' => $projectId, + 'success' => $success, + 'failure' => $failure, + 'signature' => \hash_hmac('sha256', \json_encode([$projectId, $success, $failure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')), + ]; + + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $callback = $protocol . '://' . ($platform['consoleHostname'] ?? '') . '/v1/vcs/origin/callback'; + + // The Cursor adapter expects its secret as a JSON object; starting an + // install only needs the app ID, so the key may be left out here. + $oauth2 = new OAuth2Cursor( + System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), + \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), + $callback, + $state, + self::SCOPES + ); $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') ->addHeader('Pragma', 'no-cache') - ->redirect($url); + ->redirect($oauth2->getLoginURL()); } } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php index 437a47c0dd..17ae23e0eb 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php @@ -5,8 +5,8 @@ namespace Appwrite\Platform\Modules\VCS\Http\Origin\Callback; use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Extend\Exception; use Appwrite\Platform\Permission as AppwritePermission; -use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Console; use Utopia\Database\Database; use Utopia\Database\Document; @@ -37,12 +37,12 @@ class Get extends Action ->label('scope', 'public') ->label('error', APP_VIEWS_DIR . '/general/error.phtml') ->param('installation_id', '', new Text(256, 0), 'Origin installation ID', true) - ->param('installation_receipt', '', new Text(4096, 0), 'Origin installation receipt JWT, signed by Cursor.', true) - ->param('state', '', new Text(2048), 'Origin state. Contains info sent when starting the installation flow.', true) - ->inject('request') + ->param('installation_receipt', '', new Text(8192, 0), 'Origin installation receipt JWT, signed by Cursor.', true) + ->param('state', '', new Text(2048, 0), 'Origin state. Contains info sent when starting the installation flow.', true) ->inject('response') ->inject('dbForPlatform') ->inject('platform') + ->inject('vcsFactory') ->callback($this->action(...)); } @@ -50,68 +50,57 @@ class Get extends Action string $providerInstallationId, string $installationReceipt, string $state, - Request $request, Response $response, Database $dbForPlatform, - array $platform + array $platform, + VcsFactory $vcsFactory, ) { - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - $params = $request->getParams(); - Console::log('[ORIGIN DEBUG] Callback received'); - Console::log('[ORIGIN DEBUG] Callback params: ' . \json_encode($params)); - Console::log('[ORIGIN DEBUG] Callback headers: ' . \json_encode($request->getHeaders())); - Console::log('[ORIGIN DEBUG] Callback installation_id: "' . $providerInstallationId . '"'); - - // Surface anything that looks like an OAuth2 token flow (e.g. a code - // exchange), since Origin is not expected to send one. - $oauthParams = \array_intersect_key($params, \array_flip([ - 'code', 'token', 'access_token', 'refresh_token', 'expires_in', 'token_type', 'scope', 'id_token', 'setup_action', 'authuser', 'session_state', - ])); - if (!empty($oauthParams)) { - Console::log('[ORIGIN DEBUG] Possible OAuth2 flow params detected: ' . \json_encode($oauthParams)); - } else { - Console::log('[ORIGIN DEBUG] No OAuth2 flow params detected'); + if (empty($installationReceipt)) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing installation receipt. Please restart the installation from the Appwrite Console.'); } - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - // Decode only -- the EdDSA signature is not verified, so the claims - // must not be trusted for authorization decisions yet. - if (!empty($installationReceipt)) { - $segments = \explode('.', $installationReceipt); - if (\count($segments) === 3) { - $receiptHeader = \json_decode(\base64_decode(\strtr($segments[0], '-_', '+/')), true) ?? []; - $receiptClaims = \json_decode(\base64_decode(\strtr($segments[1], '-_', '+/')), true) ?? []; - Console::log('[ORIGIN DEBUG] Receipt JWT header: ' . \json_encode($receiptHeader)); - Console::log('[ORIGIN DEBUG] Receipt JWT claims: ' . \json_encode($receiptClaims)); - } else { - Console::log('[ORIGIN DEBUG] installation_receipt is not a JWT: ' . $installationReceipt); - } - } else { - Console::log('[ORIGIN DEBUG] No installation_receipt received'); + // Authenticate the callback before trusting anything else on it: the + // endpoint is public and Origin performs no token exchange, so the + // EdDSA-signed receipt is the only proof the request came from Cursor. + // The Cursor adapter expects its secret as a JSON object. + $oauth2 = new OAuth2Cursor( + System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), + \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), + '' + ); + + try { + $receiptClaims = $oauth2->verifyReceipt($installationReceipt); + } catch (\Throwable $e) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Could not verify the Origin installation receipt. Please restart the installation from the Appwrite Console.'); } + // The receipt's subject is the authoritative installation id; a + // separately passed installation_id may only confirm it. + $receiptInstallationId = \strval($receiptClaims['sub'] ?? ''); + if (!empty($providerInstallationId) && $providerInstallationId !== $receiptInstallationId) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Receipt subject does not match the installation ID.'); + } + $providerInstallationId = $receiptInstallationId; + + // Cursor echoes the state given to the install URL as a receipt claim; + // accept a query parameter carrying the same value as a fallback. + $state = !empty($state) ? $state : \strval($receiptClaims['state'] ?? ''); if (empty($state)) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Missing state parameter. Please restart the installation from the Appwrite Console.'); } $state = \json_decode($state, true) ?? []; - $redirectFailure = $state['failure'] ?? ''; $projectId = $state['projectId'] ?? ''; + $redirectFailure = $state['failure'] ?? ''; - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] Decoded state: ' . \json_encode($state)); - - // This endpoint is public and Origin performs no token exchange -- - // without verifying the signature the Authorize action put in state, - // anyone could pass an arbitrary projectId here and attach an - // installation to another project. + // The receipt authenticates Cursor, and this HMAC authenticates the + // Appwrite Console that started the flow -- without it anyone could + // attach an installation to an arbitrary projectId. $signature = \hash_hmac('sha256', \json_encode([$projectId, $state['success'] ?? '', $redirectFailure]), System::getEnv('_APP_OPENSSL_KEY_V1', '')); if (!\hash_equals($signature, $state['signature'] ?? '')) { - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] State signature mismatch, rejecting callback'); throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Invalid state parameter. Please restart the installation from the Appwrite Console.'); } - Console::log('[ORIGIN DEBUG] State signature valid'); $project = $dbForPlatform->getDocument('projects', $projectId); @@ -138,36 +127,19 @@ class Get extends Action return; } - // Authenticate the callback by verifying the installation receipt - // against Cursor's published JWKS. This proves the request genuinely - // originates from Origin (the callback is public and has no token - // exchange) before any installation is created. - // The Cursor adapter expects its secret as a JSON object. - $oauth2 = new OAuth2Cursor( - System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), - \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), - '' - ); - + // The receipt names the workspace by its stable id; the owner slug the + // rest of the integration works with comes from the installation itself. + $organization = \strval($receiptClaims['namespace_id'] ?? ''); try { - $receiptClaims = $oauth2->verifyReceipt($installationReceipt); - - // Bind the receipt to the installation id in the callback so a - // valid receipt cannot be replayed to attach a different - // installation. - if (($receiptClaims['sub'] ?? '') !== $providerInstallationId) { - throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Receipt subject does not match installation ID'); - } + $adapter = $vcsFactory->fromInstallation(new Document([ + 'provider' => 'origin', + 'providerInstallationId' => $providerInstallationId, + ])); + $organization = $adapter->getOwnerName($providerInstallationId); } catch (\Throwable $e) { - Console::log('[ORIGIN DEBUG] Receipt verification failed: ' . $e->getMessage()); - $this->failure($response, $redirectFailure, 'Could not verify the Origin installation receipt.'); - return; + Console::warning('Failed to resolve Origin installation owner: ' . $e->getMessage()); } - // The Cursor namespace (team/workspace) owning the installation. - $organization = $receiptClaims['namespace_id'] ?? ''; - Console::log('[ORIGIN DEBUG] Receipt verified, namespace_id: "' . $organization . '"'); - $projectInternalId = $project->getSequence(); $installation = $dbForPlatform->findOne('installations', [ @@ -189,19 +161,12 @@ class Get extends Action 'organization' => $organization, 'personal' => false, ])); - - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] Created installation "' . $installation->getId() . '" for project "' . $projectId . '"'); } else { $installation = $dbForPlatform->updateDocument('installations', $installation->getId(), new Document([ 'organization' => $organization, ])); - - Console::log('[ORIGIN DEBUG] Installation already exists: "' . $installation->getId() . '"'); } - Console::log('[ORIGIN DEBUG] Redirecting to success URL: ' . $redirectSuccess); - $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') ->addHeader('Pragma', 'no-cache') @@ -213,9 +178,6 @@ class Get extends Action */ private function failure(Response $response, string $redirect, string $error, string $type = Exception::GENERAL_ARGUMENT_INVALID): void { - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] Callback failed: ' . $error . ' (redirect: "' . $redirect . '")'); - if (empty($redirect)) { throw new Exception($type, $error); } @@ -226,5 +188,4 @@ class Get extends Action ->addHeader('Pragma', 'no-cache') ->redirect($redirect . $separator . \http_build_query(['error' => $error])); } - } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index aac94ffa02..98ae1fa770 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -2,16 +2,36 @@ namespace Appwrite\Platform\Modules\VCS\Http\Origin\Events; +use Appwrite\Extend\Exception; use Appwrite\Platform\Action; +use Appwrite\Platform\Modules\VCS\Http\GitHub\Deployment; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Appwrite\Vcs\Factory as VcsFactory; +use Utopia\Config\Config; use Utopia\Console; +use Utopia\Database\Database; +use Utopia\Database\Document; +use Utopia\Database\Query; +use Utopia\Database\Validator\Authorization; +use Utopia\DSN\DSN; use Utopia\Platform\Scope\HTTP; use Utopia\Span\Span; +use Utopia\System\System; +use Utopia\VCS\Adapter\Git\Origin; class Create extends Action { use HTTP; + use Deployment; + + /** + * Origin's active signing keys, cached for the worker's lifetime. The set + * rotates rarely and a delivery that fails on a stale set refetches once. + * + * @var array|null + */ + protected static ?array $signingKeys = null; public static function getName() { @@ -26,33 +46,339 @@ class Create extends Action ->desc('Create event') ->groups(['api', 'vcs']) ->label('scope', 'public') + ->inject('vcsFactory') ->inject('request') ->inject('response') + ->inject('dbForPlatform') + ->inject('authorization') + ->inject('getProjectDB') + ->inject('deploymentsFactory') + ->inject('platform') ->callback($this->action(...)); } public function action( + VcsFactory $vcsFactory, Request $request, - Response $response + Response $response, + Database $dbForPlatform, + Authorization $authorization, + callable $getProjectDB, + callable $deploymentsFactory, + array $platform ) { - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN DEBUG] Event received'); - Console::log('[ORIGIN DEBUG] Event headers: ' . \json_encode($request->getHeaders())); - Console::log('[ORIGIN DEBUG] Event query params: ' . \json_encode($request->getParams())); - Console::log('[ORIGIN DEBUG] Event raw payload: ' . $request->getRawPayload()); + $vcs = $vcsFactory->fromProvider('origin'); - $payload = \json_decode($request->getRawPayload(), true) ?? []; - - // The delivery header is not confirmed yet -- accept both the Origin - // name and the pre-rename Codebase one. - $event = $request->getHeaderLine('x-origin-event', '') - ?: $request->getHeaderLine('x-codebase-event', '') - ?: ($payload['event'] ?? ''); + $event = $request->getHeaderLine($vcs->getEventHeaderName(), ''); Span::add('vcs.origin.event.name', $event); - Console::log('[ORIGIN DEBUG] Event name resolved to: "' . $event . '"'); - // Origin does not deliver push or pull request events yet, so events - // are only acknowledged to prevent delivery retries. - $response->json(['success' => true]); + $payload = $request->getRawPayload(); + $signature = $request->getHeaderLine($vcs->getSignatureHeaderName(), ''); + $deliveryId = $request->getHeaderLine('webhook-id', ''); + $timestamp = $request->getHeaderLine('webhook-timestamp', ''); + + // Origin signs the SHA-256 of ".." + // with its own Ed25519 key, verified against its published JWKS rather + // than a shared secret. Stale timestamps are replays. + $valid = false; + if (!empty($deliveryId) && \ctype_digit($timestamp) && \abs(\time() - (int) $timestamp) <= 300) { + $signedContent = $deliveryId . '.' . $timestamp . '.' . $payload; + + foreach ($this->signingKeys() as $publicKey) { + if ($vcs->validateWebhookEvent($signedContent, $signature, $publicKey)) { + $valid = true; + break; + } + } + + // The key set may have rotated since it was cached. + if (!$valid) { + foreach ($this->signingKeys(refresh: true) as $publicKey) { + if ($vcs->validateWebhookEvent($signedContent, $signature, $publicKey)) { + $valid = true; + break; + } + } + } + } + + Span::add('vcs.origin.event.signature.valid', $valid); + + if (!$valid) { + throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid webhook payload signature. The delivery could not be verified against Origin\'s published signing keys.'); + } + + $parsedPayloads = $vcs->getEvents($event, $payload); + + foreach ($parsedPayloads as $parsedPayload) { + match (true) { + $event === Origin::EVENT_PUSH => $this->handlePushEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), + \str_starts_with($event, Origin::EVENT_PULL_REQUEST . '.') => $this->handlePullRequestEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), + \str_starts_with($event, Origin::EVENT_INSTALLATION . '.') => $this->handleInstallationEvent($parsedPayload, $dbForPlatform, $authorization, $getProjectDB), + default => null, + }; + } + + $response->json(['events' => $parsedPayloads]); + } + + /** + * Origin's active Ed25519 signing keys as base64url raw key material, the + * shape the adapter's validateWebhookEvent() accepts. + * + * @return array + */ + protected function signingKeys(bool $refresh = false): array + { + if (!$refresh && self::$signingKeys !== null) { + return self::$signingKeys; + } + + $keys = []; + + try { + $ch = \curl_init('https://api.cursor.com/v1/origin/keys'); + \curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); + \curl_setopt($ch, CURLOPT_TIMEOUT, 15); + $body = \curl_exec($ch); + \curl_close($ch); + + $jwks = \is_string($body) ? \json_decode($body, true) : null; + foreach (\is_array($jwks['keys'] ?? null) ? $jwks['keys'] : [] as $key) { + if (($key['kty'] ?? '') === 'OKP' && ($key['crv'] ?? '') === 'Ed25519' && !empty($key['x'])) { + $keys[] = \strval($key['x']); + } + } + } catch (\Throwable $e) { + Console::warning('Failed to fetch Origin signing keys: ' . $e->getMessage()); + } + + // Never cache an empty set - a fetch hiccup would reject deliveries + // until the worker restarts. + if (!empty($keys)) { + self::$signingKeys = $keys; + } + + return self::$signingKeys ?? []; + } + + protected function handleInstallationEvent( + array $parsedPayload, + Database $dbForPlatform, + Authorization $authorization, + callable $getProjectDB, + ) { + if ($parsedPayload['action'] !== 'deleted') { + return; + } + + $providerInstallationId = $parsedPayload['installationId']; + + $installationCursor = null; + do { + $installationQueries = [ + Query::equal('providerInstallationId', [$providerInstallationId]), + Query::equal('provider', ['origin']), + Query::limit(1000), + ]; + if ($installationCursor !== null) { + $installationQueries[] = Query::cursorAfter($installationCursor); + } + $installations = $authorization->skip(fn () => $dbForPlatform->find('installations', $installationQueries)); + + foreach ($installations as $installation) { + $projectId = $installation->getAttribute('projectId', ''); + $project = $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); + + if (!$project->isEmpty() && $this->isProjectInCurrentRegion($project)) { + $dbForProject = $getProjectDB($project); + + foreach (['functions', 'sites'] as $collection) { + $cursor = null; + do { + $queries = [ + Query::equal('installationInternalId', [$installation->getSequence()]), + Query::limit(1000), + ]; + if ($cursor !== null) { + $queries[] = Query::cursorAfter($cursor); + } + $resources = $authorization->skip(fn () => $dbForProject->find($collection, $queries)); + + foreach ($resources as $resource) { + $authorization->skip(fn () => $dbForProject->updateDocument($collection, $resource->getId(), new Document([ + 'installationId' => '', + 'installationInternalId' => '', + 'providerRepositoryId' => '', + 'providerBranch' => '', + 'providerSilentMode' => false, + 'providerRootDirectory' => '', + 'repositoryId' => '', + 'repositoryInternalId' => '', + ]))); + } + + $cursor = count($resources) === 1000 ? $resources[array_key_last($resources)] : null; + } while ($cursor !== null); + } + } + + $cursor = null; + do { + $queries = [ + Query::equal('installationInternalId', [$installation->getSequence()]), + Query::limit(1000), + ]; + if ($cursor !== null) { + $queries[] = Query::cursorAfter($cursor); + } + $repositories = $authorization->skip(fn () => $dbForPlatform->find('repositories', $queries)); + + foreach ($repositories as $repository) { + $authorization->skip(fn () => $dbForPlatform->deleteDocument('repositories', $repository->getId())); + } + + $cursor = count($repositories) === 1000 ? $repositories[array_key_last($repositories)] : null; + } while ($cursor !== null); + + $authorization->skip(fn () => $dbForPlatform->deleteDocument('installations', $installation->getId())); + } + + $installationCursor = count($installations) === 1000 ? $installations[array_key_last($installations)] : null; + } while ($installationCursor !== null); + } + + private function isProjectInCurrentRegion(Document $project): bool + { + try { + $dsn = new DSN($project->getAttribute('database')); + $databaseName = $dsn->getHost(); + } catch (\InvalidArgumentException) { + $databaseName = $project->getAttribute('database'); + } + + $databases = Config::getParam('pools-database', []); + if (!\in_array($databaseName, $databases)) { + Console::warning("Skipping project {$project->getId()}: database '{$databaseName}' is not part of region " . System::getEnv('_APP_REGION')); + return false; + } + + return true; + } + + private function handlePushEvent( + array $parsedPayload, + VcsFactory $vcsFactory, + Database $dbForPlatform, + Authorization $authorization, + callable $getProjectDB, + array $platform, + callable $deploymentsFactory, + ) { + $providerBranchDeleted = $parsedPayload['branchDeleted'] ?? false; + $providerBranch = $parsedPayload['branch'] ?? ''; + $providerBranchUrl = $parsedPayload['branchUrl'] ?? ''; + $providerRepositoryId = $parsedPayload['repositoryId'] ?? ''; + $providerRepositoryName = $parsedPayload['repositoryName'] ?? ''; + $providerInstallationId = $parsedPayload['installationId'] ?? ''; + $providerRepositoryUrl = $parsedPayload['repositoryUrl'] ?? ''; + $providerCommitHash = $parsedPayload['commitHash'] ?? ''; + $providerRepositoryOwner = $parsedPayload['owner'] ?? ''; + $providerCommitAuthorName = $parsedPayload['headCommitAuthorName'] ?? ''; + $providerCommitAuthorEmail = $parsedPayload['headCommitAuthorEmail'] ?? ''; + $providerCommitAuthorUrl = $parsedPayload['authorUrl'] ?? ''; + $providerCommitMessage = $parsedPayload['headCommitMessage'] ?? ''; + $providerCommitUrl = $parsedPayload['headCommitUrl'] ?? ''; + + Span::add('vcs.origin.event.repo.id', $providerRepositoryId); + Span::add('vcs.origin.event.repo.name', $providerRepositoryName); + Span::add('vcs.origin.event.branch', $providerBranch); + Span::add('vcs.origin.event.installation.id', $providerInstallationId); + + $vcs = $vcsFactory->fromInstallation(new Document([ + 'provider' => 'origin', + 'providerInstallationId' => $providerInstallationId, + ])); + + // Find associated repositories + $repositories = $authorization->skip(fn () => $dbForPlatform->find('repositories', [ + Query::equal('providerRepositoryId', [$providerRepositoryId]), + Query::limit(100), + ])); + + // Create new deployment only on push (not committed by us) and not when branch is deleted + if (!\in_array($providerCommitAuthorEmail, [APP_VCS_GITHUB_EMAIL, APP_VCS_ORIGIN_EMAIL], true) && !$providerBranchDeleted) { + $providerAffectedFiles = $parsedPayload['affectedFiles'] ?? []; + $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthorName, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, '', $providerAffectedFiles, false, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory); + } + } + + private function handlePullRequestEvent( + array $parsedPayload, + VcsFactory $vcsFactory, + Database $dbForPlatform, + Authorization $authorization, + callable $getProjectDB, + array $platform, + callable $deploymentsFactory, + ) { + $action = $parsedPayload['action'] ?? ''; + + if ($action == 'opened' || $action == 'reopened' || $action == 'synchronize') { + $providerBranch = $parsedPayload['branch'] ?? ''; + $providerBranchUrl = $parsedPayload['branchUrl'] ?? ''; + $providerRepositoryId = $parsedPayload['repositoryId'] ?? ''; + $providerRepositoryName = $parsedPayload['repositoryName'] ?? ''; + $providerInstallationId = $parsedPayload['installationId'] ?? ''; + $providerRepositoryUrl = $parsedPayload['repositoryUrl'] ?? ''; + $providerPullRequestId = $parsedPayload['pullRequestNumber'] ?? ''; + $providerCommitHash = $parsedPayload['commitHash'] ?? ''; + $providerRepositoryOwner = $parsedPayload['owner'] ?? ''; + $external = $parsedPayload['external'] ?? false; + $providerCommitUrl = $parsedPayload['headCommitUrl'] ?? ''; + $providerCommitAuthorUrl = $parsedPayload['authorUrl'] ?? ''; + + Span::add('vcs.origin.event.repo.id', $providerRepositoryId); + Span::add('vcs.origin.event.repo.name', $providerRepositoryName); + Span::add('vcs.origin.event.branch', $providerBranch); + Span::add('vcs.origin.event.installation.id', $providerInstallationId); + + // Ignore sync for non-external. We handle it in push webhook. + // Origin has no fork model, so every pull request is non-external. + if (!$external && $action == 'synchronize') { + return; + } + + $vcs = $vcsFactory->fromInstallation(new Document([ + 'provider' => 'origin', + 'providerInstallationId' => $providerInstallationId, + ])); + + try { + $commitDetails = $vcs->getCommit($providerRepositoryOwner, $providerRepositoryName, $providerCommitHash); + } catch (\Throwable $e) { + Console::warning("Failed to fetch commit '{$providerCommitHash}': " . $e->getMessage()); + $commitDetails = []; + } + $providerCommitAuthor = $commitDetails['commitAuthor'] ?? ''; + $providerCommitMessage = $commitDetails['commitMessage'] ?? ''; + + $prFiles = $vcs->getPullRequestFiles($providerRepositoryOwner, $providerRepositoryName, (int) $providerPullRequestId); + $providerAffectedFiles = [ + ...array_column($prFiles, 'filename'), + // Only renamed files carry a previous filename; skip missing values from other file changes. + ...array_filter(array_column($prFiles, 'previousFilename')) + ]; + + $repositories = $authorization->skip(fn () => $dbForPlatform->find('repositories', [ + Query::equal('providerRepositoryId', [$providerRepositoryId]), + Query::orderDesc('$createdAt') + ])); + + $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthor, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, \strval($providerPullRequestId), $providerAffectedFiles, $external, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory); + } + + // No cleanup on close: Origin pull requests are never external, so no + // authorized-contributor entries accumulate on the repository. } } diff --git a/src/Appwrite/Platform/Modules/VCS/Services/Http.php b/src/Appwrite/Platform/Modules/VCS/Services/Http.php index 71498db484..55e268980c 100644 --- a/src/Appwrite/Platform/Modules/VCS/Services/Http.php +++ b/src/Appwrite/Platform/Modules/VCS/Services/Http.php @@ -2,6 +2,7 @@ namespace Appwrite\Platform\Modules\VCS\Services; +use Appwrite\Platform\Modules\VCS\Http\Archives\Get as GetArchive; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Authorize\Get as GetBitbucketAuthorize; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Callback\Get as GetBitbucketCallback; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Events\Create as CreateBitbucketEvent; @@ -63,6 +64,9 @@ class Http extends Service $this->addAction(DeleteInstallation::getName(), new DeleteInstallation()); $this->addAction(ListNamespaces::getName(), new ListNamespaces()); + // Archives + $this->addAction(GetArchive::getName(), new GetArchive()); + // Repositories $this->addAction(CreateRepository::getName(), new CreateRepository()); $this->addAction(GetRepository::getName(), new GetRepository()); diff --git a/src/Appwrite/Vcs/SourceArchive.php b/src/Appwrite/Vcs/SourceArchive.php new file mode 100644 index 0000000000..3e1093fc4c --- /dev/null +++ b/src/Appwrite/Vcs/SourceArchive.php @@ -0,0 +1,66 @@ + $platform + * @return array{string, array} The source URL and the headers to fetch it with + */ + public static function presign(Git $vcs, string $providerInstallationId, string $owner, string $repository, string $ref, array $platform): array + { + if ($vcs->supportsRepositoryArchives()) { + return [ + $vcs->getRepositoryPresignedUrl($owner, $repository, $ref), + $vcs->getRepositoryPresignedUrlHeaders(), + ]; + } + + $expires = \time() + self::TTL; + + $params = [ + 'provider' => $vcs->getName(), + 'installation' => $providerInstallationId, + 'owner' => $owner, + 'repository' => $repository, + 'ref' => $ref, + 'expires' => $expires, + 'signature' => self::signature($vcs->getName(), $providerInstallationId, $owner, $repository, $ref, $expires), + ]; + + // The jobs-service reaches Appwrite over the internal Docker network + // when configured, the same way its presigned callback URLs do. + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $endpoint = \rtrim(System::getEnv('_APP_JOBS_ENDPOINT', $protocol . '://' . ($platform['apiHostname'] ?? '')), '/'); + + return [$endpoint . '/v1/vcs/archives?' . \http_build_query($params), []]; + } + + public static function signature(string $provider, string $providerInstallationId, string $owner, string $repository, string $ref, int $expires): string + { + return \hash_hmac( + 'sha256', + \implode("\n", [$provider, $providerInstallationId, $owner, $repository, $ref, $expires]), + System::getEnv('_APP_OPENSSL_KEY_V1', '') + ); + } +} From 6d54b49414024a8afa4b49d1a86a4ac53bff160d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 15:12:05 +0200 Subject: [PATCH 19/53] Rename env vars --- .env | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.env b/.env index 49be7302b3..0be2ca8563 100644 --- a/.env +++ b/.env @@ -170,7 +170,7 @@ _APP_VCS_GITLAB_WEBHOOK_SECRET= _APP_VCS_BITBUCKET_CLIENT_ID= _APP_VCS_BITBUCKET_CLIENT_SECRET= _APP_VCS_BITBUCKET_WEBHOOK_SECRET= -_APP_VCS_CODEBASE_CLIENT_ID= -_APP_VCS_CODEBASE_PRIVATE_KEY="" +_APP_VCS_ORIGIN_CLIENT_ID= +_APP_VCS_ORIGIN_PRIVATE_KEY="" _APP_VCS_WEBHOOK_URL=http://appwrite/v1 _APP_WEBHOOK_MAX_FAILED_ATTEMPTS=10 From 1844afdf94a86a49ee5a0db8256cbedbc0f7256c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 15:49:49 +0200 Subject: [PATCH 20/53] chore: bump utopia-php/vcs for the Origin pushed_at fix Co-Authored-By: Claude Fable 5 --- composer.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/composer.lock b/composer.lock index e0708c1fb9..f003e55732 100644 --- a/composer.lock +++ b/composer.lock @@ -5035,12 +5035,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "cbf57939aa7f0d40c5e6ab9120e13b3247bd767a" + "reference": "f841df3867d6f98bfbab9faa5cd0b38a04674fb4" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/cbf57939aa7f0d40c5e6ab9120e13b3247bd767a", - "reference": "cbf57939aa7f0d40c5e6ab9120e13b3247bd767a", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/f841df3867d6f98bfbab9faa5cd0b38a04674fb4", + "reference": "f841df3867d6f98bfbab9faa5cd0b38a04674fb4", "shasum": "" }, "require": { @@ -5094,7 +5094,7 @@ "source": "https://github.com/utopia-php/vcs/tree/feat-origin", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-18T12:28:48+00:00" + "time": "2026-08-18T13:49:34+00:00" }, { "name": "utopia-php/websocket", From 7e1a2fd2133cb1e866a0a490cd37a3e0016742a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 15:52:29 +0200 Subject: [PATCH 21/53] chore: bump utopia-php/vcs for Origin error messages Co-Authored-By: Claude Fable 5 --- composer.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/composer.lock b/composer.lock index f003e55732..654825ebd4 100644 --- a/composer.lock +++ b/composer.lock @@ -5035,12 +5035,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "f841df3867d6f98bfbab9faa5cd0b38a04674fb4" + "reference": "cb6f3c1d6d72487b264070e663ade8da57cd3a4a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/f841df3867d6f98bfbab9faa5cd0b38a04674fb4", - "reference": "f841df3867d6f98bfbab9faa5cd0b38a04674fb4", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/cb6f3c1d6d72487b264070e663ade8da57cd3a4a", + "reference": "cb6f3c1d6d72487b264070e663ade8da57cd3a4a", "shasum": "" }, "require": { @@ -5094,7 +5094,7 @@ "source": "https://github.com/utopia-php/vcs/tree/feat-origin", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-18T13:49:34+00:00" + "time": "2026-08-18T13:52:12+00:00" }, { "name": "utopia-php/websocket", From 99d0243081f67250a16afffecae4bc5d15cb4953 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 16:14:08 +0200 Subject: [PATCH 22/53] chore: bump utopia-php/vcs for slash-branch commit lookups Co-Authored-By: Claude Fable 5 --- composer.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/composer.lock b/composer.lock index 654825ebd4..3b863515d2 100644 --- a/composer.lock +++ b/composer.lock @@ -5035,12 +5035,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "cb6f3c1d6d72487b264070e663ade8da57cd3a4a" + "reference": "41b0ea07fd78081fb9a29f16d578b23840891803" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/cb6f3c1d6d72487b264070e663ade8da57cd3a4a", - "reference": "cb6f3c1d6d72487b264070e663ade8da57cd3a4a", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/41b0ea07fd78081fb9a29f16d578b23840891803", + "reference": "41b0ea07fd78081fb9a29f16d578b23840891803", "shasum": "" }, "require": { @@ -5094,7 +5094,7 @@ "source": "https://github.com/utopia-php/vcs/tree/feat-origin", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-18T13:52:12+00:00" + "time": "2026-08-18T14:13:55+00:00" }, { "name": "utopia-php/websocket", From f23b94b848ba5c9112894cf55e80c98b3aa6fe31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 16:42:48 +0200 Subject: [PATCH 23/53] chore: temporary debug logging on the Origin events endpoint Marked with TODOs; strip once the integration is verified end to end. Co-Authored-By: Claude Fable 5 --- .../Modules/VCS/Http/Origin/Events/Create.php | 33 ++++++++++++++++--- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index 98ae1fa770..c84d12c41c 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -77,6 +77,10 @@ class Create extends Action $deliveryId = $request->getHeaderLine('webhook-id', ''); $timestamp = $request->getHeaderLine('webhook-timestamp', ''); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN EVENT] delivery=' . $deliveryId . ' type=' . $event . ' timestamp=' . $timestamp . ' signature=' . (empty($signature) ? 'missing' : 'present')); + Console::log('[ORIGIN EVENT] payload: ' . \mb_strimwidth($payload, 0, 8000, '...[truncated]')); + // Origin signs the SHA-256 of ".." // with its own Ed25519 key, verified against its published JWKS rather // than a shared secret. Stale timestamps are replays. @@ -103,18 +107,28 @@ class Create extends Action } Span::add('vcs.origin.event.signature.valid', $valid); + Console::log('[ORIGIN EVENT] signature valid: ' . \var_export($valid, true)); if (!$valid) { throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid webhook payload signature. The delivery could not be verified against Origin\'s published signing keys.'); } $parsedPayloads = $vcs->getEvents($event, $payload); + Console::log('[ORIGIN EVENT] parsed ' . \count($parsedPayloads) . ' event(s): ' . \json_encode($parsedPayloads)); foreach ($parsedPayloads as $parsedPayload) { - match (true) { - $event === Origin::EVENT_PUSH => $this->handlePushEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), - \str_starts_with($event, Origin::EVENT_PULL_REQUEST . '.') => $this->handlePullRequestEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), - \str_starts_with($event, Origin::EVENT_INSTALLATION . '.') => $this->handleInstallationEvent($parsedPayload, $dbForPlatform, $authorization, $getProjectDB), + $handler = match (true) { + $event === Origin::EVENT_PUSH => 'push', + \str_starts_with($event, Origin::EVENT_PULL_REQUEST . '.') => 'pull_request', + \str_starts_with($event, Origin::EVENT_INSTALLATION . '.') => 'installation', + default => 'none', + }; + Console::log('[ORIGIN EVENT] dispatching to handler: ' . $handler); + + match ($handler) { + 'push' => $this->handlePushEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), + 'pull_request' => $this->handlePullRequestEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), + 'installation' => $this->handleInstallationEvent($parsedPayload, $dbForPlatform, $authorization, $getProjectDB), default => null, }; } @@ -306,10 +320,21 @@ class Create extends Action Query::limit(100), ])); + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + Console::log('[ORIGIN EVENT] push: repo=' . $providerRepositoryId . ' branch=' . $providerBranch . ' commit=' . $providerCommitHash . ' authorEmail=' . $providerCommitAuthorEmail . ' deleted=' . \var_export($providerBranchDeleted, true)); + Console::log('[ORIGIN EVENT] push: matched ' . \count($repositories) . ' connected repositories document(s) for providerRepositoryId=' . $providerRepositoryId); + foreach ($repositories as $connected) { + Console::log('[ORIGIN EVENT] push: connected repo doc ' . $connected->getId() . ' project=' . $connected->getAttribute('projectId') . ' resource=' . $connected->getAttribute('resourceType') . '/' . $connected->getAttribute('resourceId')); + } + // Create new deployment only on push (not committed by us) and not when branch is deleted if (!\in_array($providerCommitAuthorEmail, [APP_VCS_GITHUB_EMAIL, APP_VCS_ORIGIN_EMAIL], true) && !$providerBranchDeleted) { $providerAffectedFiles = $parsedPayload['affectedFiles'] ?? []; + Console::log('[ORIGIN EVENT] push: creating git deployments'); $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthorName, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, '', $providerAffectedFiles, false, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory); + Console::log('[ORIGIN EVENT] push: createGitDeployments finished'); + } else { + Console::log('[ORIGIN EVENT] push: skipped (self-commit or branch deletion)'); } } From fa5048c3dc757a5f770d7d267bc4171cf65f6693 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:10:58 +0200 Subject: [PATCH 24/53] fix: deduplicate Origin webhook deliveries by webhook-id Origin delivers at least once and retries any delivery not acknowledged with a 2xx inside its sender timeout. The events endpoint processes deliveries synchronously and can outlast that window under load, so every retry of one push created another deployment - another build, more load, slower responses, more retries. Claim the delivery id atomically before processing and acknowledge late retries without action, as the Origin docs prescribe. Acknowledging first and processing asynchronously remains the proper fix and is marked as a TODO. Co-Authored-By: Claude Fable 5 --- .../Modules/VCS/Http/Origin/Events/Create.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index c84d12c41c..ada3fe27fd 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -12,6 +12,7 @@ use Utopia\Config\Config; use Utopia\Console; use Utopia\Database\Database; use Utopia\Database\Document; +use Utopia\Database\Exception\Duplicate; use Utopia\Database\Query; use Utopia\Database\Validator\Authorization; use Utopia\DSN\DSN; @@ -113,6 +114,21 @@ class Create extends Action throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid webhook payload signature. The delivery could not be verified against Origin\'s published signing keys.'); } + // Origin delivers at least once and retries anything not acknowledged + // with a 2xx in time. Processing here is synchronous and can outlast + // that window, so claim the delivery id before doing the work - a + // retry of a delivery already being processed must not deploy again. + // TODO: acknowledge first and process asynchronously instead. + try { + $authorization->skip(fn () => $dbForPlatform->createDocument('vcsCommentLocks', new Document([ + '$id' => 'origin-delivery-' . $deliveryId, + ]))); + } catch (Duplicate) { + Console::log('[ORIGIN EVENT] duplicate delivery ' . $deliveryId . ' - already processed, acknowledging without action'); + $response->json(['events' => [], 'duplicate' => true]); + return; + } + $parsedPayloads = $vcs->getEvents($event, $payload); Console::log('[ORIGIN EVENT] parsed ' . \count($parsedPayloads) . ' event(s): ' . \json_encode($parsedPayloads)); From 895d99653dd4c0cc8ee8c7e7af9384cc8223aef8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:14:56 +0200 Subject: [PATCH 25/53] chore: log outgoing PR comment image and link URLs Temporary, TODO-marked: compares the scheme we send against what the provider renders, while verifying the Origin integration. Co-Authored-By: Claude Fable 5 --- src/Appwrite/Vcs/Comment.php | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/Appwrite/Vcs/Comment.php b/src/Appwrite/Vcs/Comment.php index ac0f6e1dae..6989992b1a 100644 --- a/src/Appwrite/Vcs/Comment.php +++ b/src/Appwrite/Vcs/Comment.php @@ -2,6 +2,7 @@ namespace Appwrite\Vcs; +use Utopia\Console; use Utopia\Database\Document; use Utopia\System\System; @@ -243,6 +244,15 @@ class Comment $text .= "\n
\n\n> [!TIP]\n> {$this->tip}\n\n"; + // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. + // Log every image and link URL the comment carries, to compare the + // scheme we send against the scheme the provider ends up rendering. + $urls = []; + if (\preg_match_all('/(?:src|srcset|href)="([^"]+)"|\]\((https?:[^)]+)\)/', $text, $matches)) { + $urls = \array_values(\array_filter(\array_merge($matches[1], $matches[2]))); + } + Console::log('[VCS COMMENT] outgoing image/link URLs: ' . \json_encode($urls)); + return $text; } From 3024ae14096c19618becb681c201d34df9a99735 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:23:07 +0200 Subject: [PATCH 26/53] fix: surface swallowed VCS build-status reporting failures The gitAction call is best-effort by design, but a silent catch left the provider's check and PR comment frozen at their last state with nothing to debug from when reporting failed (seen with a dropped database connection). Log what was lost. Co-Authored-By: Claude Fable 5 --- src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php b/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php index 41c81ee3a5..3ee13ac603 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php @@ -18,6 +18,7 @@ use Appwrite\Usage\Context as UsageContext; use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Cache\Cache; +use Utopia\Console; use Utopia\Database\Database; use Utopia\Database\DateTime; use Utopia\Database\Document; @@ -514,8 +515,11 @@ class Jobs extends Action $dbForPlatform, $platform, ); - } catch (\Throwable) { - // Best-effort — never fails the build. + } catch (\Throwable $error) { + // Best-effort — never fails the build. But say what was lost: a + // swallowed failure here leaves the provider's check and comment + // frozen at their last state with nothing to debug from. + Console::warning('Failed to report build status to VCS provider for deployment ' . $deployment->getId() . ': ' . $error->getMessage()); } } From 28d3de729426a72a8d1b742b4aed25f68fbea13d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:24:28 +0200 Subject: [PATCH 27/53] chore: temporarily hardcode cloud.appwrite.io for PR comment assets Comment images can never render on the provider's HTTPS page from a plain-HTTP localhost dev stack (browsers auto-upgrade mixed-content images), so point them at real HTTPS assets while verifying the Origin integration. TODO-marked; restore the env-driven protocol and platform hostname before merge. Co-Authored-By: Claude Fable 5 --- src/Appwrite/Vcs/Comment.php | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Vcs/Comment.php b/src/Appwrite/Vcs/Comment.php index 6989992b1a..8d72b7dd17 100644 --- a/src/Appwrite/Vcs/Comment.php +++ b/src/Appwrite/Vcs/Comment.php @@ -128,8 +128,11 @@ class Comment $i = 0; foreach ($projects as $projectId => $project) { - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; - $hostname = $this->platform['consoleHostname'] ?? ''; + // TODO: Temporarily hardcoded so comment images resolve over real + // HTTPS while verifying the Origin integration - restore the + // env-driven protocol and platform hostname afterwards. + $protocol = 'https'; + $hostname = 'cloud.appwrite.io'; $text .= "## {$project['name']}\n\n"; $text .= "Project ID: `{$projectId}`\n\n"; @@ -258,8 +261,11 @@ class Comment public function generatImage(string $pathLight, string $pathDark, string $alt, int $width): string { - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; - $hostname = $this->platform['consoleHostname'] ?? ''; + // TODO: Temporarily hardcoded so comment images resolve over real + // HTTPS while verifying the Origin integration - restore the + // env-driven protocol and platform hostname afterwards. + $protocol = 'https'; + $hostname = 'cloud.appwrite.io'; $imageLight = $protocol . '://' . $hostname . $pathLight; $imageDark = $protocol . '://' . $hostname . $pathDark; From d05e47c5e85d02214d795c2eacc0f526bdcbaddc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:31:59 +0200 Subject: [PATCH 28/53] feat: text-only PR comments for providers without image support Reverts the temporary cloud.appwrite.io hostname hardcode and replaces it with a capability: adapters now report supportsCommentImages(), and the comment builder falls back to textual status cells and a plain QR link when the provider cannot render images. Origin renders comment markdown without an image proxy, so images on the consumer's own host can never display there; every other provider keeps the full visual comment. Co-Authored-By: Claude Fable 5 --- composer.lock | 8 +++--- src/Appwrite/Deployment/GitAction.php | 2 +- .../Modules/VCS/Http/GitHub/Deployment.php | 8 +++--- src/Appwrite/Vcs/Comment.php | 27 ++++++++++--------- 4 files changed, 24 insertions(+), 21 deletions(-) diff --git a/composer.lock b/composer.lock index 3b863515d2..75162b8e72 100644 --- a/composer.lock +++ b/composer.lock @@ -5035,12 +5035,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "41b0ea07fd78081fb9a29f16d578b23840891803" + "reference": "8b37a20f5ae04b1ab62e733da5267946d454aaa3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/41b0ea07fd78081fb9a29f16d578b23840891803", - "reference": "41b0ea07fd78081fb9a29f16d578b23840891803", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/8b37a20f5ae04b1ab62e733da5267946d454aaa3", + "reference": "8b37a20f5ae04b1ab62e733da5267946d454aaa3", "shasum": "" }, "require": { @@ -5094,7 +5094,7 @@ "source": "https://github.com/utopia-php/vcs/tree/feat-origin", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-18T14:13:55+00:00" + "time": "2026-08-18T15:30:44+00:00" }, { "name": "utopia-php/websocket", diff --git a/src/Appwrite/Deployment/GitAction.php b/src/Appwrite/Deployment/GitAction.php index 03d679b2ba..8d709a0a2e 100644 --- a/src/Appwrite/Deployment/GitAction.php +++ b/src/Appwrite/Deployment/GitAction.php @@ -86,7 +86,7 @@ final class GitAction ]); $previewUrl = $isSite && !$rule->isEmpty() ? "{$protocol}://" . $rule->getAttribute('domain', '') : ''; - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->parseComment($vcs->getComment($owner, $repositoryName, $commentId)); $comment->addBuild($project, $resource, $isSite ? 'site' : 'function', $status, $deployment->getId(), ['type' => 'logs'], $previewUrl); $vcs->updateComment($owner, $repositoryName, $commentId, $comment->generateComment()); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php index 742710ddb1..08fbedaebc 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php @@ -231,7 +231,7 @@ trait Deployment if ($lockAcquired) { // Wrap in try/finally to ensure lock file gets deleted try { - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->parseComment($vcs->getComment($owner, $repositoryName, $latestCommentId)); $comment->addBuild($project, $resource, $resourceType, $commentStatus, $deploymentId, $action, $commentPreviewUrl); @@ -243,7 +243,7 @@ trait Deployment } } } else { - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->addBuild($project, $resource, $resourceType, $commentStatus, $deploymentId, $action, $commentPreviewUrl); $latestCommentId = \strval($vcs->createComment($owner, $repositoryName, $providerPullRequestId, $comment->generateComment())); @@ -304,7 +304,7 @@ trait Deployment if ($lockAcquired) { // Wrap in try/finally to ensure lock file gets deleted try { - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->parseComment($vcs->getComment($owner, $repositoryName, $latestCommentId)); $comment->addBuild($project, $resource, $resourceType, $commentStatus, $deploymentId, $action, ''); @@ -531,7 +531,7 @@ trait Deployment $previewUrl = !$rule->isEmpty() ? ("{$protocol}://" . $rule->getAttribute('domain', '')) : ''; if (!empty($previewUrl)) { - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->parseComment($vcs->getComment($owner, $repositoryName, $latestCommentId)); $comment->addBuild($project, $resource, $resourceType, $commentStatus, $deploymentId, $action, $previewUrl); $vcs->updateComment($owner, $repositoryName, $latestCommentId, $comment->generateComment()); diff --git a/src/Appwrite/Vcs/Comment.php b/src/Appwrite/Vcs/Comment.php index 8d72b7dd17..9a6ca6ba5f 100644 --- a/src/Appwrite/Vcs/Comment.php +++ b/src/Appwrite/Vcs/Comment.php @@ -11,7 +11,8 @@ use Utopia\System\System; class Comment { public function __construct( - private array $platform + private array $platform, + private bool $withImages = true, ) { } @@ -128,11 +129,8 @@ class Comment $i = 0; foreach ($projects as $projectId => $project) { - // TODO: Temporarily hardcoded so comment images resolve over real - // HTTPS while verifying the Origin integration - restore the - // env-driven protocol and platform hostname afterwards. - $protocol = 'https'; - $hostname = 'cloud.appwrite.io'; + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $hostname = $this->platform['consoleHostname'] ?? ''; $text .= "## {$project['name']}\n\n"; $text .= "Project ID: `{$projectId}`\n\n"; @@ -177,7 +175,9 @@ class Comment $qrImagePathDark = '/images/vcs/qr-dark.svg'; $consoleUrl = $protocol . '://' . $hostname . '/v1/avatars/qr?text=' . \urlencode($site['previewUrl']); - $qr = '[' . $this->generatImage($qrImagePathLight, $qrImagePathDark, 'QR Code', 28) . '](' . $consoleUrl . ')'; + $qr = $this->withImages + ? '[' . $this->generatImage($qrImagePathLight, $qrImagePathDark, 'QR Code', 28) . '](' . $consoleUrl . ')' + : '[QR Code](' . $consoleUrl . ')'; $preview = '[Preview URL](' . $site['previewUrl'] . ')'; @@ -261,11 +261,14 @@ class Comment public function generatImage(string $pathLight, string $pathDark, string $alt, int $width): string { - // TODO: Temporarily hardcoded so comment images resolve over real - // HTTPS while verifying the Origin integration - restore the - // env-driven protocol and platform hostname afterwards. - $protocol = 'https'; - $hostname = 'cloud.appwrite.io'; + // Providers without comment image support get the textual cells only. + if (!$this->withImages) { + return ''; + } + + + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; + $hostname = $this->platform['consoleHostname'] ?? ''; $imageLight = $protocol . '://' . $hostname . $pathLight; $imageDark = $protocol . '://' . $hostname . $pathDark; From 90d7591ec4d2a21d786a2766c463b47d05307597 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Tue, 18 Aug 2026 17:33:05 +0200 Subject: [PATCH 29/53] chore: temporarily disable preview deployment authorization TODO-marked override while verifying the Origin integration; preview domains open without the auth cookie instead of redirecting to the console auth flow. Remove before merge. Co-Authored-By: Claude Fable 5 --- app/controllers/general.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/app/controllers/general.php b/app/controllers/general.php index ebf28a9162..d6f68a5217 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -246,6 +246,10 @@ function router(Http $utopia, Database $dbForPlatform, callable $getProjectDB, S - If authorized, continue as if auth was not required */ $requirePreview = \is_null($apiKey) || !$apiKey->isPreviewAuthDisabled(); + // TODO: Temporarily disabled while verifying the Origin integration - + // preview deployments open without the auth cookie / console redirect. + // Remove this override to restore preview authorization. + $requirePreview = false; if ($isPreview && $requirePreview) { $cookie = $request->getCookie(COOKIE_NAME_PREVIEW, ''); $authorized = false; From c2dd4a9ad4e68b6575c4e1c17973c7e456e727cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:28:27 +0200 Subject: [PATCH 30/53] chore: bump utopia-php/vcs to 5.2.0 The feat-origin branch merged and was tagged, so the dev pin goes back to main's 5.*.* constraint. 5.2.0 also makes Origin's createRepository() throw instead of riding Cursor's undocumented web API, so the create endpoint asks supportsRepositoryCreation() first and answers with a clear client error. Co-Authored-By: Claude Fable 5 --- .../Modules/VCS/Http/Installations/Repositories/Create.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php index d8dae58f3b..7f29f0b005 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php @@ -112,6 +112,11 @@ class Create extends Action } else { $providerInstallationId = $installation->getAttribute('providerInstallationId'); $vcs = $vcsFactory->fromInstallation($installation); + + if (!$vcs->supportsRepositoryCreation()) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'VCS provider does not support repository creation: ' . $provider); + } + $owner = !empty($providerNamespace) ? $providerNamespace : $vcs->getOwnerName($providerInstallationId); try { From 15415e95bf29b53e783c6c5e59412d8224f0f66c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:30:52 +0200 Subject: [PATCH 31/53] feat: report VCS provider capabilities to the console The console variables response gains a typed vcsProviders list: each configured provider with whether it supports repository creation and public repositories, read from the 5.2.0 adapter capability API. The _APP_VCS_PROVIDERS name list stays for released consoles. Co-Authored-By: Claude Fable 5 --- app/init/models.php | 2 + .../Modules/Console/Http/Variables/Get.php | 18 ++++++- src/Appwrite/Utopia/Response.php | 1 + .../Response/Model/ConsoleVariables.php | 7 +++ .../Utopia/Response/Model/VcsProvider.php | 52 +++++++++++++++++++ 5 files changed, 78 insertions(+), 2 deletions(-) create mode 100644 src/Appwrite/Utopia/Response/Model/VcsProvider.php diff --git a/app/init/models.php b/app/init/models.php index 41651c9262..41163bec25 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -227,6 +227,7 @@ use Appwrite\Utopia\Response\Model\User; use Appwrite\Utopia\Response\Model\Variable; use Appwrite\Utopia\Response\Model\VcsContent; use Appwrite\Utopia\Response\Model\VcsNamespace; +use Appwrite\Utopia\Response\Model\VcsProvider; use Appwrite\Utopia\Response\Model\VectorsDBCollection; use Appwrite\Utopia\Response\Model\Webhook; @@ -264,6 +265,7 @@ Response::setModel(new ProviderRepositoryFrameworkList()); Response::setModel(new ProviderRepositoryRuntimeList()); Response::setModel(new VcsNamespace()); Response::setModel(new BaseList('VCS Namespaces List', Response::MODEL_VCS_NAMESPACE_LIST, 'namespaces', Response::MODEL_VCS_NAMESPACE)); +Response::setModel(new VcsProvider()); Response::setModel(new BaseList('Branches List', Response::MODEL_BRANCH_LIST, 'branches', Response::MODEL_BRANCH)); Response::setModel(new BaseList('Frameworks List', Response::MODEL_FRAMEWORK_LIST, 'frameworks', Response::MODEL_FRAMEWORK)); Response::setModel(new BaseList('Runtimes List', Response::MODEL_RUNTIME_LIST, 'runtimes', Response::MODEL_RUNTIME)); diff --git a/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php b/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php index 9adf5ebf9a..92d4fa5466 100644 --- a/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php +++ b/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php @@ -7,6 +7,7 @@ use Appwrite\SDK\ContentType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; +use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Domains\Domain; @@ -47,6 +48,7 @@ class Get extends Action contentType: ContentType::JSON )) ->inject('vcsProviders') + ->inject('vcsFactory') ->inject('response') ->inject('platform') ->inject('dbForProject') @@ -55,6 +57,7 @@ class Get extends Action public function action( callable $vcsProviders, + VcsFactory $vcsFactory, Response $response, array $platform, Database $dbForProject @@ -71,7 +74,17 @@ class Get extends Action $isDomainEnabled = $isAAAAValid || $isAValid || $isCNAMEValid; - $isVcsEnabled = !empty($vcsProviders()); + $providers = $vcsProviders(); + $isVcsEnabled = !empty($providers); + $providerCapabilities = \array_map(function (string $provider) use ($vcsFactory) { + $adapter = $vcsFactory->fromProvider($provider); + + return new Document([ + 'name' => $provider, + 'supportForRepositoryCreation' => $adapter->supportsRepositoryCreation(), + 'supportForPublicRepositories' => $adapter->supportsPublicRepositories(), + ]); + }, $providers); $isAssistantEnabled = !empty(System::getEnv('_APP_ASSISTANT_OPENAI_API_KEY', '')); @@ -87,7 +100,8 @@ class Get extends Action '_APP_COMPUTE_SIZE_LIMIT' => +System::getEnv('_APP_COMPUTE_SIZE_LIMIT'), '_APP_USAGE_STATS' => System::getEnv('_APP_USAGE_STATS'), '_APP_VCS_ENABLED' => $isVcsEnabled, - '_APP_VCS_PROVIDERS' => $vcsProviders(), + '_APP_VCS_PROVIDERS' => $providers, + 'vcsProviders' => $providerCapabilities, '_APP_DOMAIN_ENABLED' => $isDomainEnabled, '_APP_ASSISTANT_ENABLED' => $isAssistantEnabled, '_APP_DOMAIN_SITES' => $platform['sitesDomain'], diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 80dd69bd38..c7e8d1f82f 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -195,6 +195,7 @@ class Response extends SwooleResponse public const MODEL_PROVIDER_REPOSITORY_RUNTIME_LIST = 'providerRepositoryRuntimeList'; public const MODEL_VCS_NAMESPACE = 'vcsNamespace'; public const MODEL_VCS_NAMESPACE_LIST = 'vcsNamespaceList'; + public const MODEL_VCS_PROVIDER = 'vcsProvider'; public const MODEL_BRANCH = 'branch'; public const MODEL_BRANCH_LIST = 'branchList'; public const MODEL_DETECTION_FRAMEWORK = 'detectionFramework'; diff --git a/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php b/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php index ab179d04ee..4013d6bb71 100644 --- a/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php +++ b/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php @@ -71,6 +71,13 @@ class ConsoleVariables extends Model 'example' => ['github'], 'array' => true, ]) + ->addRule('vcsProviders', [ + 'type' => Response::MODEL_VCS_PROVIDER, + 'description' => 'Configured VCS providers and their capabilities.', + 'default' => [], + 'example' => [], + 'array' => true, + ]) ->addRule('_APP_DOMAIN_ENABLED', [ 'type' => self::TYPE_BOOLEAN, 'description' => 'Defines if main domain is configured. If so, custom domains can be created.', diff --git a/src/Appwrite/Utopia/Response/Model/VcsProvider.php b/src/Appwrite/Utopia/Response/Model/VcsProvider.php new file mode 100644 index 0000000000..f7cd552603 --- /dev/null +++ b/src/Appwrite/Utopia/Response/Model/VcsProvider.php @@ -0,0 +1,52 @@ +addRule('name', [ + 'type' => self::TYPE_STRING, + 'description' => 'VCS (Version Control System) provider name.', + 'default' => '', + 'example' => 'github', + ]) + ->addRule('supportForRepositoryCreation', [ + 'type' => self::TYPE_BOOLEAN, + 'description' => 'Defines if the provider allows creating repositories. Some providers reserve repository creation for their own UI.', + 'default' => false, + 'example' => true, + ]) + ->addRule('supportForPublicRepositories', [ + 'type' => self::TYPE_BOOLEAN, + 'description' => 'Defines if the provider can host repositories that are readable without authentication.', + 'default' => false, + 'example' => true, + ]); + } + + /** + * Get Name + * + * @return string + */ + public function getName(): string + { + return 'VcsProvider'; + } + + /** + * Get Type + * + * @return string + */ + public function getType(): string + { + return Response::MODEL_VCS_PROVIDER; + } +} From 7d45b8a69454b13c40c79494f027b4d3e13e2c05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:33:48 +0200 Subject: [PATCH 32/53] chore: drop the temporary QA overrides and debug logging Removes the preview-authorization bypass, the outgoing comment URL logging, and the Origin event tracing added while verifying the integration. Also threads the event bus through the Origin webhook handlers - main's createGitDeployments() gained a Bus parameter that the endpoint predates. Co-Authored-By: Claude Fable 5 --- app/controllers/general.php | 4 -- .../Modules/VCS/Http/Origin/Events/Create.php | 43 +++++-------------- src/Appwrite/Vcs/Comment.php | 11 ----- 3 files changed, 11 insertions(+), 47 deletions(-) diff --git a/app/controllers/general.php b/app/controllers/general.php index 8343f79d9b..280a0380e1 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -247,10 +247,6 @@ function router(Http $utopia, Database $dbForPlatform, callable $getProjectDB, S - If authorized, continue as if auth was not required */ $requirePreview = \is_null($apiKey) || !$apiKey->isPreviewAuthDisabled(); - // TODO: Temporarily disabled while verifying the Origin integration - - // preview deployments open without the auth cookie / console redirect. - // Remove this override to restore preview authorization. - $requirePreview = false; if ($isPreview && $requirePreview) { $cookie = $request->getCookie(COOKIE_NAME_PREVIEW, ''); $authorized = false; diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index ada3fe27fd..f71cf947bf 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -8,6 +8,7 @@ use Appwrite\Platform\Modules\VCS\Http\GitHub\Deployment; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; use Appwrite\Vcs\Factory as VcsFactory; +use Utopia\Bus\Bus; use Utopia\Config\Config; use Utopia\Console; use Utopia\Database\Database; @@ -52,6 +53,7 @@ class Create extends Action ->inject('response') ->inject('dbForPlatform') ->inject('authorization') + ->inject('bus') ->inject('getProjectDB') ->inject('deploymentsFactory') ->inject('platform') @@ -64,6 +66,7 @@ class Create extends Action Response $response, Database $dbForPlatform, Authorization $authorization, + Bus $bus, callable $getProjectDB, callable $deploymentsFactory, array $platform @@ -78,10 +81,6 @@ class Create extends Action $deliveryId = $request->getHeaderLine('webhook-id', ''); $timestamp = $request->getHeaderLine('webhook-timestamp', ''); - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN EVENT] delivery=' . $deliveryId . ' type=' . $event . ' timestamp=' . $timestamp . ' signature=' . (empty($signature) ? 'missing' : 'present')); - Console::log('[ORIGIN EVENT] payload: ' . \mb_strimwidth($payload, 0, 8000, '...[truncated]')); - // Origin signs the SHA-256 of ".." // with its own Ed25519 key, verified against its published JWKS rather // than a shared secret. Stale timestamps are replays. @@ -108,7 +107,6 @@ class Create extends Action } Span::add('vcs.origin.event.signature.valid', $valid); - Console::log('[ORIGIN EVENT] signature valid: ' . \var_export($valid, true)); if (!$valid) { throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid webhook payload signature. The delivery could not be verified against Origin\'s published signing keys.'); @@ -124,27 +122,17 @@ class Create extends Action '$id' => 'origin-delivery-' . $deliveryId, ]))); } catch (Duplicate) { - Console::log('[ORIGIN EVENT] duplicate delivery ' . $deliveryId . ' - already processed, acknowledging without action'); $response->json(['events' => [], 'duplicate' => true]); return; } $parsedPayloads = $vcs->getEvents($event, $payload); - Console::log('[ORIGIN EVENT] parsed ' . \count($parsedPayloads) . ' event(s): ' . \json_encode($parsedPayloads)); foreach ($parsedPayloads as $parsedPayload) { - $handler = match (true) { - $event === Origin::EVENT_PUSH => 'push', - \str_starts_with($event, Origin::EVENT_PULL_REQUEST . '.') => 'pull_request', - \str_starts_with($event, Origin::EVENT_INSTALLATION . '.') => 'installation', - default => 'none', - }; - Console::log('[ORIGIN EVENT] dispatching to handler: ' . $handler); - - match ($handler) { - 'push' => $this->handlePushEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), - 'pull_request' => $this->handlePullRequestEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory), - 'installation' => $this->handleInstallationEvent($parsedPayload, $dbForPlatform, $authorization, $getProjectDB), + match (true) { + $event === Origin::EVENT_PUSH => $this->handlePushEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $bus, $getProjectDB, $platform, $deploymentsFactory), + \str_starts_with($event, Origin::EVENT_PULL_REQUEST . '.') => $this->handlePullRequestEvent($parsedPayload, $vcsFactory, $dbForPlatform, $authorization, $bus, $getProjectDB, $platform, $deploymentsFactory), + \str_starts_with($event, Origin::EVENT_INSTALLATION . '.') => $this->handleInstallationEvent($parsedPayload, $dbForPlatform, $authorization, $getProjectDB), default => null, }; } @@ -301,6 +289,7 @@ class Create extends Action VcsFactory $vcsFactory, Database $dbForPlatform, Authorization $authorization, + Bus $bus, callable $getProjectDB, array $platform, callable $deploymentsFactory, @@ -336,21 +325,10 @@ class Create extends Action Query::limit(100), ])); - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - Console::log('[ORIGIN EVENT] push: repo=' . $providerRepositoryId . ' branch=' . $providerBranch . ' commit=' . $providerCommitHash . ' authorEmail=' . $providerCommitAuthorEmail . ' deleted=' . \var_export($providerBranchDeleted, true)); - Console::log('[ORIGIN EVENT] push: matched ' . \count($repositories) . ' connected repositories document(s) for providerRepositoryId=' . $providerRepositoryId); - foreach ($repositories as $connected) { - Console::log('[ORIGIN EVENT] push: connected repo doc ' . $connected->getId() . ' project=' . $connected->getAttribute('projectId') . ' resource=' . $connected->getAttribute('resourceType') . '/' . $connected->getAttribute('resourceId')); - } - // Create new deployment only on push (not committed by us) and not when branch is deleted if (!\in_array($providerCommitAuthorEmail, [APP_VCS_GITHUB_EMAIL, APP_VCS_ORIGIN_EMAIL], true) && !$providerBranchDeleted) { $providerAffectedFiles = $parsedPayload['affectedFiles'] ?? []; - Console::log('[ORIGIN EVENT] push: creating git deployments'); - $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthorName, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, '', $providerAffectedFiles, false, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory); - Console::log('[ORIGIN EVENT] push: createGitDeployments finished'); - } else { - Console::log('[ORIGIN EVENT] push: skipped (self-commit or branch deletion)'); + $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthorName, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, '', $providerAffectedFiles, false, $dbForPlatform, $authorization, $bus, $getProjectDB, $platform, $deploymentsFactory); } } @@ -359,6 +337,7 @@ class Create extends Action VcsFactory $vcsFactory, Database $dbForPlatform, Authorization $authorization, + Bus $bus, callable $getProjectDB, array $platform, callable $deploymentsFactory, @@ -416,7 +395,7 @@ class Create extends Action Query::orderDesc('$createdAt') ])); - $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthor, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, \strval($providerPullRequestId), $providerAffectedFiles, $external, $dbForPlatform, $authorization, $getProjectDB, $platform, $deploymentsFactory); + $this->createGitDeployments($vcs, $providerInstallationId, $repositories, $providerBranch, $providerBranchUrl, $providerRepositoryName, $providerRepositoryUrl, $providerRepositoryOwner, $providerCommitHash, $providerCommitAuthor, $providerCommitAuthorUrl, $providerCommitMessage, $providerCommitUrl, \strval($providerPullRequestId), $providerAffectedFiles, $external, $dbForPlatform, $authorization, $bus, $getProjectDB, $platform, $deploymentsFactory); } // No cleanup on close: Origin pull requests are never external, so no diff --git a/src/Appwrite/Vcs/Comment.php b/src/Appwrite/Vcs/Comment.php index 9a6ca6ba5f..328dcaa19a 100644 --- a/src/Appwrite/Vcs/Comment.php +++ b/src/Appwrite/Vcs/Comment.php @@ -2,7 +2,6 @@ namespace Appwrite\Vcs; -use Utopia\Console; use Utopia\Database\Document; use Utopia\System\System; @@ -247,15 +246,6 @@ class Comment $text .= "\n
\n\n> [!TIP]\n> {$this->tip}\n\n"; - // TODO: Temporary debug logging while the Origin integration is verified -- remove afterwards. - // Log every image and link URL the comment carries, to compare the - // scheme we send against the scheme the provider ends up rendering. - $urls = []; - if (\preg_match_all('/(?:src|srcset|href)="([^"]+)"|\]\((https?:[^)]+)\)/', $text, $matches)) { - $urls = \array_values(\array_filter(\array_merge($matches[1], $matches[2]))); - } - Console::log('[VCS COMMENT] outgoing image/link URLs: ' . \json_encode($urls)); - return $text; } @@ -266,7 +256,6 @@ class Comment return ''; } - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; $hostname = $this->platform['consoleHostname'] ?? ''; From 5281c608d5a323eafc8eaaa90046010ac2a2c380 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:35:47 +0200 Subject: [PATCH 33/53] refactor(avatars): flatten photo providers and resolve them with balancer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move Gravatar/Provider.php & friends to Providers/Gravatar.php, so the class name says what the provider is instead of every file being called Provider.php. Static/Provider.php becomes Providers/Fallback.php since `static` is a reserved word and cannot be a class name. - Turn AvatarPhotos/Photo.php into the abstract base every provider extends. It is a contract — getName(), supports(), get() — not a resolver that merges the providers together. - Replace Photo::resolve() with utopia-php/balancer in the HTTP action: each provider is an Option, a filter drops the ones that cannot serve the user (no email, no name), and the First algorithm walks them in priority order until one returns bytes. Co-Authored-By: Claude Opus 5 (1M context) --- composer.json | 1 + composer.lock | 50 +++++- src/Appwrite/AvatarPhotos/Photo.php | 143 ++++-------------- .../Provider.php => Providers/Fallback.php} | 34 +++-- .../Provider.php => Providers/Gravatar.php} | 39 +++-- .../Provider.php => Providers/Initials.php} | 60 +++++--- .../Provider.php => Providers/Libavatar.php} | 44 +++--- .../Modules/Avatars/Http/Photo/Get.php | 97 ++++++++++-- .../Modules/Avatars/Services/Http.php | 4 +- 9 files changed, 277 insertions(+), 195 deletions(-) rename src/Appwrite/AvatarPhotos/{Static/Provider.php => Providers/Fallback.php} (76%) rename src/Appwrite/AvatarPhotos/{Gravatar/Provider.php => Providers/Gravatar.php} (51%) rename src/Appwrite/AvatarPhotos/{Initials/Provider.php => Providers/Initials.php} (67%) rename src/Appwrite/AvatarPhotos/{Libavatar/Provider.php => Providers/Libavatar.php} (55%) diff --git a/composer.json b/composer.json index 8e5b888dbe..c6e9cb303a 100644 --- a/composer.json +++ b/composer.json @@ -68,6 +68,7 @@ "utopia-php/agents": "2.*", "utopia-php/audit": "3.0.*", "utopia-php/auth": "^0.10", + "utopia-php/balancer": "0.4.*", "utopia-php/cache": "^4.0.0", "utopia-php/cli": "^0.24", "utopia-php/compression": "0.1.*", diff --git a/composer.lock b/composer.lock index e21c79dec2..a43774cbfd 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "c7acee2d0fe6b2299e47df05257a7225", + "content-hash": "9642605d1050cf8beed5f482eaa962a4", "packages": [ { "name": "adhocore/jwt", @@ -3143,6 +3143,54 @@ }, "time": "2026-07-23T07:34:27+00:00" }, + { + "name": "utopia-php/balancer", + "version": "0.4.1", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/balancer.git", + "reference": "7fc8922da3e381c227cd88435cb12b17040c6ee1" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/balancer/zipball/7fc8922da3e381c227cd88435cb12b17040c6ee1", + "reference": "7fc8922da3e381c227cd88435cb12b17040c6ee1", + "shasum": "" + }, + "require": { + "php": ">=8.1", + "utopia-php/telemetry": "^0.4.0" + }, + "require-dev": { + "laravel/pint": "1.2.*", + "phpstan/phpstan": "^1.8", + "phpunit/phpunit": "^9.3" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\Balancer\\": "src/Balancer" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "A simple library to balance choices between multiple options.", + "keywords": [ + "balancer", + "balancing", + "framework", + "php", + "upf", + "utopia" + ], + "support": { + "issues": "https://github.com/utopia-php/balancer/issues", + "source": "https://github.com/utopia-php/balancer/tree/0.4.1" + }, + "time": "2026-08-13T19:36:49+00:00" + }, { "name": "utopia-php/cache", "version": "4.0.2", diff --git a/src/Appwrite/AvatarPhotos/Photo.php b/src/Appwrite/AvatarPhotos/Photo.php index 6788e9c1a4..dafe7622d2 100644 --- a/src/Appwrite/AvatarPhotos/Photo.php +++ b/src/Appwrite/AvatarPhotos/Photo.php @@ -2,132 +2,43 @@ namespace Appwrite\AvatarPhotos; -use Appwrite\AvatarPhotos\Gravatar\Provider as GravatarProvider; -use Appwrite\AvatarPhotos\Libavatar\Provider as LibavatarProvider; -use Appwrite\AvatarPhotos\Initials\Provider as InitialsProvider; -use Appwrite\AvatarPhotos\Static\Provider as StaticProvider; -use Utopia\Image\Image; +use Utopia\Database\Document; /** - * Photo resolver. + * Base class every avatar photo provider extends. * - * Walks through avatar providers in priority order and returns the first - * successful result as processed PNG/WEBP/JPEG bytes. - * - * Priority chain: - * 1. OAuth2 session photo — TODO: implement in a follow-up PR - * 2. Gravatar — requires email - * 3. Libravatar — requires email - * 4. Initials — requires name or email - * 5. Static fallback — always succeeds + * A provider knows how to turn a user into raw image bytes from one source — + * Gravatar, Libravatar, generated initials, a built-in placeholder — and + * nothing more. Picking which provider actually answers a request is the + * caller's job; providers never chain into one another. */ -class Photo +abstract class Photo { - private GravatarProvider $gravatar; - private LibavatarProvider $libavatar; - private InitialsProvider $initials; - private StaticProvider $static; - - public function __construct(string $appRoot) - { - $this->gravatar = new GravatarProvider(); - $this->libavatar = new LibavatarProvider(); - $this->initials = new InitialsProvider($appRoot); - $this->static = new StaticProvider(); - } + /** + * Machine-readable name of the provider, e.g. 'gravatar'. + */ + abstract public function getName(): string; /** - * Resolve and return the best available avatar for the given user data. + * Whether this provider has everything it needs to attempt a lookup. * - * @param string $email User's email address (may be empty). - * @param string $name User's display name (may be empty). - * @param int $width Desired output width in pixels. - * @param int $height Desired output height in pixels. - * @param int $quality Output quality 0–100. - * @param string $output Output format: 'png' | 'jpg' | 'webp'. - * @param string $rating Gravatar/Libravatar rating: 'g' | 'pg' | 'r' | 'x'. - * @param string $background Optional hex background for the Initials provider. - * @return string Raw image bytes in the requested $output format. + * Providers that key off an email address return false for users without + * one, so the caller can skip them without paying for a network round-trip. */ - public function resolve( - string $email, - string $name, - int $width = 256, - int $height = 256, - int $quality = 100, - string $output = 'png', - string $rating = 'g', - string $background = '', - ): string { - // ------------------------------------------------------------------- - // Priority 1: OAuth2 session photo - // TODO: Resolve profile photo from the user's active OAuth2 token. - // Each OAuth2 provider (Google, GitHub, …) exposes a profile- - // picture URL. Fetch it here and short-circuit the chain. - // Track in: https://github.com/appwrite/appwrite/issues/TODO - // ------------------------------------------------------------------- - - // ------------------------------------------------------------------- - // Priority 2: Gravatar - // ------------------------------------------------------------------- - if (!empty($email)) { - $raw = $this->gravatar->get($email, $rating); - if ($raw !== null) { - return $this->process($raw, $width, $height, $quality, $output); - } - } - - // ------------------------------------------------------------------- - // Priority 3: Libravatar - // ------------------------------------------------------------------- - if (!empty($email)) { - $raw = $this->libavatar->get($email, $rating); - if ($raw !== null) { - return $this->process($raw, $width, $height, $quality, $output); - } - } - - // ------------------------------------------------------------------- - // Priority 4: Initials - // Prefer name; fall back to email prefix when name is absent. - // ------------------------------------------------------------------- - $initialsInput = !empty($name) ? $name : $email; - if (!empty($initialsInput)) { - $raw = $this->initials->get($initialsInput, $width, $height, $background); - if ($raw !== null) { - // Initials PNG is already sized correctly — just re-encode if - // a different format or quality was requested. - return $this->process($raw, $width, $height, $quality, $output); - } - } - - // ------------------------------------------------------------------- - // Priority 5: Static fallback — always succeeds - // ------------------------------------------------------------------- - $raw = $this->static->get($width, $height); - return $this->process($raw, $width, $height, $quality, $output); - } + abstract public function supports(Document $user): bool; /** - * Resize and re-encode raw image bytes. + * Fetch the raw image bytes for $user. + * + * Returning null means "I have no photo for this user" and is an expected + * outcome, not an error — the caller moves on to the next provider. Network + * or rendering failures must be swallowed and reported the same way. + * + * @param Document $user User to resolve a photo for. + * @param int $width Desired width in pixels. + * @param int $height Desired height in pixels. + * @param string $rating Maximum image rating: 'g' | 'pg' | 'r' | 'x'. + * @return string|null Raw image bytes, or null when unavailable. */ - private function process(string $raw, int $width, int $height, int $quality, string $output): string - { - if (!\extension_loaded('imagick') || empty($raw)) { - return $raw; - } - - try { - $image = new Image($raw); - if ($width > 0 || $height > 0) { - $image->crop( - $width > 0 ? $width : 256, - $height > 0 ? $height : 256, - ); - } - return $image->output($output, $quality); - } catch (\Throwable) { - return $raw; - } - } + abstract public function get(Document $user, int $width, int $height, string $rating): ?string; } diff --git a/src/Appwrite/AvatarPhotos/Static/Provider.php b/src/Appwrite/AvatarPhotos/Providers/Fallback.php similarity index 76% rename from src/Appwrite/AvatarPhotos/Static/Provider.php rename to src/Appwrite/AvatarPhotos/Providers/Fallback.php index f9af02a083..cc2bcbe030 100644 --- a/src/Appwrite/AvatarPhotos/Static/Provider.php +++ b/src/Appwrite/AvatarPhotos/Providers/Fallback.php @@ -1,6 +1,9 @@ 0 ? $width : 256; + $height = $height > 0 ? $height : 256; + // Generate an SVG silhouette and rasterise it with Imagick so the // caller always receives a PNG regardless of whether SVG support is // available in the client. diff --git a/src/Appwrite/AvatarPhotos/Gravatar/Provider.php b/src/Appwrite/AvatarPhotos/Providers/Gravatar.php similarity index 51% rename from src/Appwrite/AvatarPhotos/Gravatar/Provider.php rename to src/Appwrite/AvatarPhotos/Providers/Gravatar.php index c4fabd19b2..5414af9087 100644 --- a/src/Appwrite/AvatarPhotos/Gravatar/Provider.php +++ b/src/Appwrite/AvatarPhotos/Providers/Gravatar.php @@ -1,36 +1,48 @@ getAttribute('email', '')); + } + + public function get(Document $user, int $width, int $height, string $rating): ?string + { + $email = $user->getAttribute('email', ''); $hash = \hash('sha256', \strtolower(\trim($email))); // Use 'd=404' so Gravatar returns HTTP 404 instead of a generic image // when the user has no custom avatar — letting us fall through to the // next provider. - $url = 'https://www.gravatar.com/avatar/' . $hash - . '?s=256&d=404&r=' . \urlencode($rating); + $url = self::BASE_URL . $hash . '?' . \http_build_query([ + 's' => \max($width, $height) > 0 ? \max($width, $height) : 256, + 'd' => '404', + 'r' => $rating, + ]); $client = new Client(); + try { $res = $client ->setAllowRedirects(true) @@ -44,6 +56,7 @@ class Provider } $body = $res->getBody(); + if (empty($body)) { return null; } diff --git a/src/Appwrite/AvatarPhotos/Initials/Provider.php b/src/Appwrite/AvatarPhotos/Providers/Initials.php similarity index 67% rename from src/Appwrite/AvatarPhotos/Initials/Provider.php rename to src/Appwrite/AvatarPhotos/Providers/Initials.php index d98916c5a0..b06220f11e 100644 --- a/src/Appwrite/AvatarPhotos/Initials/Provider.php +++ b/src/Appwrite/AvatarPhotos/Providers/Initials.php @@ -1,10 +1,12 @@ '#FD366E'], // Pink @@ -27,24 +27,30 @@ class Provider ['background' => '#85DBD8'], // Mint ]; - public function __construct(string $appRoot) - { - $this->appRoot = $appRoot; + public function __construct( + private readonly string $appRoot, + private readonly string $background = '', + ) { } - /** - * Generate an initials avatar image. - * - * @param string $name Full name or email to derive initials from. - * When empty or blank, returns null so the caller - * moves on to the next (static fallback) provider. - * @param int $width Canvas width in pixels. - * @param int $height Canvas height in pixels. - * @param string $background Optional hex colour (without #). Empty = auto. - * @return string|null Raw PNG bytes, or null when no name/email is available. - */ - public function get(string $name, int $width = 500, int $height = 500, string $background = ''): ?string + public function getName(): string { + return 'initials'; + } + + public function supports(Document $user): bool + { + return !empty(\trim($this->getLabel($user))); + } + + public function get(Document $user, int $width, int $height, string $rating): ?string + { + if (!\extension_loaded('imagick')) { + return null; + } + + $name = $this->getLabel($user); + if (empty(\trim($name))) { return null; } @@ -73,10 +79,13 @@ class Provider return null; } + $width = $width > 0 ? $width : 500; + $height = $height > 0 ? $height : 500; + $rand = (int) \substr((string) $code, -1); $rand = ($rand > \count($this->themes) - 1) ? $rand % \count($this->themes) : $rand; - $bg = (!empty($background)) ? '#' . \ltrim($background, '#') : $this->themes[$rand]['background']; + $bg = (!empty($this->background)) ? '#' . \ltrim($this->background, '#') : $this->themes[$rand]['background']; $image = new Imagick(); $punch = new Imagick(); @@ -104,4 +113,15 @@ class Provider return $image->getImageBlob(); } + + /** + * Text the initials are derived from — the display name, falling back to + * the email address when the user has not set one. + */ + private function getLabel(Document $user): string + { + $name = $user->getAttribute('name', ''); + + return !empty($name) ? $name : $user->getAttribute('email', ''); + } } diff --git a/src/Appwrite/AvatarPhotos/Libavatar/Provider.php b/src/Appwrite/AvatarPhotos/Providers/Libavatar.php similarity index 55% rename from src/Appwrite/AvatarPhotos/Libavatar/Provider.php rename to src/Appwrite/AvatarPhotos/Providers/Libavatar.php index cd9a6e2332..60c190e5de 100644 --- a/src/Appwrite/AvatarPhotos/Libavatar/Provider.php +++ b/src/Appwrite/AvatarPhotos/Providers/Libavatar.php @@ -1,7 +1,9 @@ getAttribute('email', '')); + } + + public function get(Document $user, int $width, int $height, string $rating): ?string + { + $email = $user->getAttribute('email', ''); // Libravatar supports both SHA-256 and MD5; use MD5 for widest // compatibility with older instances. - $url = self::BASE_URL . $hash - . '?s=256&d=404&r=' . \urlencode($rating); + $hash = \md5(\strtolower(\trim($email))); + + $url = self::BASE_URL . $hash . '?' . \http_build_query([ + 's' => \max($width, $height) > 0 ? \max($width, $height) : 256, + 'd' => '404', + 'r' => $rating, + ]); $client = new Client(); + try { $res = $client ->setAllowRedirects(true) @@ -51,6 +60,7 @@ class Provider } $body = $res->getBody(); + if (empty($body)) { return null; } diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php index 1134147729..f485977bca 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php @@ -3,6 +3,11 @@ namespace Appwrite\Platform\Modules\Avatars\Http\Photo; use Appwrite\AvatarPhotos\Photo; +use Appwrite\AvatarPhotos\Providers\Fallback; +use Appwrite\AvatarPhotos\Providers\Gravatar; +use Appwrite\AvatarPhotos\Providers\Initials; +use Appwrite\AvatarPhotos\Providers\Libavatar; +use Appwrite\Extend\Exception; use Appwrite\Platform\Modules\Avatars\Http\Action; use Appwrite\SDK\AuthType; use Appwrite\SDK\ContentType; @@ -10,7 +15,11 @@ use Appwrite\SDK\Method; use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; +use Utopia\Balancer\Algorithm\First; +use Utopia\Balancer\Balancer; +use Utopia\Balancer\Option; use Utopia\Database\Document; +use Utopia\Image\Image; use Utopia\Platform\Action as UtopiaAction; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Range; @@ -74,20 +83,57 @@ class Get extends Action Response $response, Document $user, ): void { - $email = $user->getAttribute('email', ''); - $name = $user->getAttribute('name', ''); + // ------------------------------------------------------------------- + // Priority 1: OAuth2 session photo + // TODO: Resolve profile photo from the user's active OAuth2 token. + // Each OAuth2 provider (Google, GitHub, …) exposes a profile- + // picture URL. Add it as a provider at the front of the list. + // Track in: https://github.com/appwrite/appwrite/issues/TODO + // ------------------------------------------------------------------- + $providers = [ + new Gravatar(), + new Libavatar(), + new Initials($this->getAppRoot()), + new Fallback(), + ]; - $photo = new Photo($this->getAppRoot()); + $balancer = new Balancer(new First()); - $data = $photo->resolve( - email: $email, - name: $name, - width: $width, - height: $height, - quality: $quality, - output: $output, - rating: $rating, - ); + foreach ($providers as $provider) { + $balancer->addOption(new Option(['provider' => $provider])); + } + + // Skip providers that lack the data they need — no email means no + // Gravatar lookup — so we never pay for a doomed network round-trip. + $balancer->addFilter(function (Option $option) use ($user) { + /** @var Photo $provider */ + $provider = $option->getState('provider'); + + return $provider->supports($user); + }); + + // A provider that came up empty is out of the running; without this the + // First algorithm would hand back the same option forever. + $balancer->addFilter(fn (Option $option) => !$option->getState('attempted', false)); + + $data = null; + + while (($option = $balancer->run()) !== null) { + $option->setState('attempted', true); + + /** @var Photo $provider */ + $provider = $option->getState('provider'); + + $data = $provider->get($user, $width, $height, $rating); + + if ($data !== null) { + break; + } + } + + if ($data === null) { + throw new Exception(Exception::AVATAR_NOT_FOUND); + } $contentType = match ($output) { 'jpg' => 'image/jpeg', @@ -98,6 +144,31 @@ class Get extends Action $response ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute — photo may change ->setContentType($contentType) - ->file($data); + ->file($this->process($data, $width, $height, $quality, $output)); + } + + /** + * Resize and re-encode raw image bytes. + */ + private function process(string $raw, int $width, int $height, int $quality, string $output): string + { + if (!\extension_loaded('imagick') || empty($raw)) { + return $raw; + } + + try { + $image = new Image($raw); + + if ($width > 0 || $height > 0) { + $image->crop( + $width > 0 ? $width : 256, + $height > 0 ? $height : 256, + ); + } + + return $image->output($output, $quality); + } catch (\Throwable) { + return $raw; + } } } diff --git a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php index 24c57cba8d..e6348fc5ad 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Avatars/Services/Http.php @@ -6,10 +6,9 @@ use Appwrite\Platform\Modules\Avatars\Http\Browsers\Get as GetBrowser; use Appwrite\Platform\Modules\Avatars\Http\CreditCards\Get as GetCreditCard; use Appwrite\Platform\Modules\Avatars\Http\Favicon\Get as GetFavicon; use Appwrite\Platform\Modules\Avatars\Http\Flags\Get as GetFlag; - -use Appwrite\Platform\Modules\Avatars\Http\Photo\Get as GetPhoto; use Appwrite\Platform\Modules\Avatars\Http\Image\Get as GetImage; use Appwrite\Platform\Modules\Avatars\Http\Initials\Get as GetInitials; +use Appwrite\Platform\Modules\Avatars\Http\Photo\Get as GetPhoto; use Appwrite\Platform\Modules\Avatars\Http\QR\Get as GetQR; use Appwrite\Platform\Modules\Avatars\Http\Screenshots\Get as GetScreenshot; use Utopia\Platform\Service; @@ -28,7 +27,6 @@ class Http extends Service $this->addAction(GetQR::getName(), new GetQR()); $this->addAction(GetInitials::getName(), new GetInitials()); $this->addAction(GetScreenshot::getName(), new GetScreenshot()); - $this->addAction(GetPhoto::getName(), new GetPhoto()); } } From 891d169e2ff5f165cc6a29034cfe1fd3cc495fe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:36:15 +0200 Subject: [PATCH 34/53] fix: provide Origin credentials to every VCS-touching worker The generic worker reports build status through the adapter and the builds worker mints installation tokens, so both need the Origin client ID next to the private key. Also drops an unrelated trailing-comma change in app/config/console.php. Co-Authored-By: Claude Fable 5 --- app/config/console.php | 2 +- docker-compose.yml | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/app/config/console.php b/app/config/console.php index 8a741030b6..bf1850182a 100644 --- a/app/config/console.php +++ b/app/config/console.php @@ -57,7 +57,7 @@ $console = [ 'oAuthProviders' => [ 'githubEnabled' => true, 'githubSecret' => System::getEnv('_APP_CONSOLE_GITHUB_SECRET', ''), - 'githubAppid' => System::getEnv('_APP_CONSOLE_GITHUB_APP_ID', ''), + 'githubAppid' => System::getEnv('_APP_CONSOLE_GITHUB_APP_ID', '') ], 'smtpBaseTemplate' => APP_BRANDED_EMAIL_BASE_TEMPLATE, ]; diff --git a/docker-compose.yml b/docker-compose.yml index c07d99a1c5..aa7ca310a4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -430,6 +430,8 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET + - _APP_VCS_ORIGIN_CLIENT_ID + - _APP_VCS_ORIGIN_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_BUILDS_VOLUME - _APP_JOBS_HOST @@ -710,6 +712,7 @@ services: - _APP_VCS_BITBUCKET_CLIENT_ID - _APP_VCS_BITBUCKET_CLIENT_SECRET - _APP_VCS_BITBUCKET_WEBHOOK_SECRET + - _APP_VCS_ORIGIN_CLIENT_ID - _APP_VCS_ORIGIN_PRIVATE_KEY - _APP_VCS_WEBHOOK_URL - _APP_FUNCTIONS_TIMEOUT From 2b6f07259885b8b2182abc33b3724a2037e2ba6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:37:14 +0200 Subject: [PATCH 35/53] style: match the sibling .env defaults for the Origin private key Co-Authored-By: Claude Fable 5 --- .env | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.env b/.env index 0be2ca8563..d6a78fc36b 100644 --- a/.env +++ b/.env @@ -171,6 +171,6 @@ _APP_VCS_BITBUCKET_CLIENT_ID= _APP_VCS_BITBUCKET_CLIENT_SECRET= _APP_VCS_BITBUCKET_WEBHOOK_SECRET= _APP_VCS_ORIGIN_CLIENT_ID= -_APP_VCS_ORIGIN_PRIVATE_KEY="" +_APP_VCS_ORIGIN_PRIVATE_KEY= _APP_VCS_WEBHOOK_URL=http://appwrite/v1 _APP_WEBHOOK_MAX_FAILED_ATTEMPTS=10 From ca75eba630dd8d197cd35c9b2cc21a79723b50d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:42:14 +0200 Subject: [PATCH 36/53] refactor(avatars): heredoc description, self-locating font, no-store photo - Use the << --- .../AvatarPhotos/Providers/Initials.php | 8 +++++-- .../Modules/Avatars/Http/Photo/Get.php | 22 +++++++++++-------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/src/Appwrite/AvatarPhotos/Providers/Initials.php b/src/Appwrite/AvatarPhotos/Providers/Initials.php index b06220f11e..e4b8cf3bed 100644 --- a/src/Appwrite/AvatarPhotos/Providers/Initials.php +++ b/src/Appwrite/AvatarPhotos/Providers/Initials.php @@ -18,6 +18,9 @@ use Utopia\Database\Document; */ class Initials extends Photo { + /** Font used to render the initials, relative to the project root. */ + private const FONT_PATH = '/app/assets/fonts/inter-v8-latin-regular.woff2'; + /** Colour palette — same as the Initials endpoint. */ private array $themes = [ ['background' => '#FD366E'], // Pink @@ -28,7 +31,6 @@ class Initials extends Photo ]; public function __construct( - private readonly string $appRoot, private readonly string $background = '', ) { } @@ -95,7 +97,9 @@ class Initials extends Photo $punch->newImage($width, $height, 'transparent'); - $fontPath = $this->appRoot . '/app/assets/fonts/inter-v8-latin-regular.woff2'; + // Providers live at src/Appwrite/AvatarPhotos/Providers, four levels + // below the project root — same walk-up as Avatars\Http\Action. + $fontPath = \dirname(__DIR__, 4) . self::FONT_PATH; $draw->setFont($fontPath); $image->setFont($fontPath); diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php index f485977bca..5c9ea6be50 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php @@ -46,13 +46,17 @@ class Get extends Action namespace: 'avatars', group: null, name: 'getPhoto', - description: 'Returns the best available profile photo for the currently authenticated user. ' - . 'The endpoint tries each source in priority order and returns the first successful result: ' - . '(1) OAuth2 session photo (planned — see TODO in source), ' - . '(2) Gravatar, ' - . '(3) Libravatar, ' - . '(4) initials generated from the user\'s name or email, ' - . '(5) a built-in static fallback image.', + description: <<getAppRoot()), + new Initials(), new Fallback(), ]; @@ -142,7 +146,7 @@ class Get extends Action }; $response - ->addHeader('Cache-Control', 'private, max-age=60') // 1 minute — photo may change + ->addHeader('Cache-Control', 'private, no-store') // photo can change at any time ->setContentType($contentType) ->file($this->process($data, $width, $height, $quality, $output)); } From e58e2b80008c9ba9ffecb99f2ba7294b8f95248a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 12:47:01 +0200 Subject: [PATCH 37/53] Apply suggestion from @Meldiron --- .../Platform/Modules/Avatars/Http/Photo/Get.php | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php index 5c9ea6be50..7428deb54b 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Photo/Get.php @@ -47,15 +47,7 @@ class Get extends Action group: null, name: 'getPhoto', description: << Date: Wed, 19 Aug 2026 13:00:09 +0200 Subject: [PATCH 38/53] chore: bump utopia-php/vcs to 5.2.0 Brings the adapter capability API: supportsRepositoryCreation(), supportsRepositoryDeletion(), supportsPublicRepositories(), supportsCommentImages() and supportsRepositoryArchives(). Co-Authored-By: Claude Fable 5 --- composer.lock | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/composer.lock b/composer.lock index 7264779afb..5db8094d71 100644 --- a/composer.lock +++ b/composer.lock @@ -5068,16 +5068,16 @@ }, { "name": "utopia-php/vcs", - "version": "5.1.2", + "version": "5.2.0", "source": { "type": "git", - "url": "git@github.com:utopia-php/vcs.git", - "reference": "abdb5763221d7e4900174c280244f83638e3133e" + "url": "https://github.com/utopia-php/vcs.git", + "reference": "780f3c84d270a14744a8cd61b1234310d9af59c4" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/abdb5763221d7e4900174c280244f83638e3133e", - "reference": "abdb5763221d7e4900174c280244f83638e3133e", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/780f3c84d270a14744a8cd61b1234310d9af59c4", + "reference": "780f3c84d270a14744a8cd61b1234310d9af59c4", "shasum": "" }, "require": { @@ -5128,10 +5128,10 @@ "vcs" ], "support": { - "source": "https://github.com/utopia-php/vcs/tree/5.1.2", + "source": "https://github.com/utopia-php/vcs/tree/5.2.0", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-07T12:32:15+00:00" + "time": "2026-08-19T10:17:14+00:00" }, { "name": "utopia-php/websocket", From 5aede528d6527158403c933510a70611b5b0d0c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 13:00:21 +0200 Subject: [PATCH 39/53] feat: text-only PR comments for providers without image support Comment asks the adapter's supportsCommentImages() and drops the SVG status icons and QR image for providers that refuse hosted images, keeping the textual cells and links. Co-Authored-By: Claude Fable 5 --- src/Appwrite/Deployment/GitAction.php | 2 +- src/Appwrite/Vcs/Comment.php | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/Deployment/GitAction.php b/src/Appwrite/Deployment/GitAction.php index 03d679b2ba..8d709a0a2e 100644 --- a/src/Appwrite/Deployment/GitAction.php +++ b/src/Appwrite/Deployment/GitAction.php @@ -86,7 +86,7 @@ final class GitAction ]); $previewUrl = $isSite && !$rule->isEmpty() ? "{$protocol}://" . $rule->getAttribute('domain', '') : ''; - $comment = new Comment($platform); + $comment = new Comment($platform, $vcs->supportsCommentImages()); $comment->parseComment($vcs->getComment($owner, $repositoryName, $commentId)); $comment->addBuild($project, $resource, $isSite ? 'site' : 'function', $status, $deployment->getId(), ['type' => 'logs'], $previewUrl); $vcs->updateComment($owner, $repositoryName, $commentId, $comment->generateComment()); diff --git a/src/Appwrite/Vcs/Comment.php b/src/Appwrite/Vcs/Comment.php index ac0f6e1dae..328dcaa19a 100644 --- a/src/Appwrite/Vcs/Comment.php +++ b/src/Appwrite/Vcs/Comment.php @@ -10,7 +10,8 @@ use Utopia\System\System; class Comment { public function __construct( - private array $platform + private array $platform, + private bool $withImages = true, ) { } @@ -173,7 +174,9 @@ class Comment $qrImagePathDark = '/images/vcs/qr-dark.svg'; $consoleUrl = $protocol . '://' . $hostname . '/v1/avatars/qr?text=' . \urlencode($site['previewUrl']); - $qr = '[' . $this->generatImage($qrImagePathLight, $qrImagePathDark, 'QR Code', 28) . '](' . $consoleUrl . ')'; + $qr = $this->withImages + ? '[' . $this->generatImage($qrImagePathLight, $qrImagePathDark, 'QR Code', 28) . '](' . $consoleUrl . ')' + : '[QR Code](' . $consoleUrl . ')'; $preview = '[Preview URL](' . $site['previewUrl'] . ')'; @@ -248,6 +251,11 @@ class Comment public function generatImage(string $pathLight, string $pathDark, string $alt, int $width): string { + // Providers without comment image support get the textual cells only. + if (!$this->withImages) { + return ''; + } + $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; $hostname = $this->platform['consoleHostname'] ?? ''; From ddea0a18674dfce576051e59c7797add722a66ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 14:13:29 +0200 Subject: [PATCH 40/53] feat: source VCS deployments through the jobs-service clone artifact Deployments::createFromVcs() owns the choice every call site used to spell out: providers with archive downloads keep handing the sidecar a presigned tarball URL, and a provider without them (the upcoming Origin) is cloned by the sidecar itself over Git HTTPS, through the orchestrator's clone artifact (open-runtimes/orchestrator 1.3.0). Credentials ride a header via the adapter's clone surface, never the URL. Bumps open-runtimes/sdk-for-php to 0.11.1 for the CloneArtifact model and utopia-php/vcs to 5.2.1 for the clone URL and headers. Co-Authored-By: Claude Fable 5 --- composer.json | 2 +- composer.lock | 28 ++++----- src/Appwrite/Deployment/Deployments.php | 61 ++++++++++++++++--- .../Platform/Modules/Compute/Base.php | 16 +++-- .../Http/Deployments/Duplicate/Create.php | 8 ++- .../Modules/Functions/Workers/Builds.php | 8 ++- .../Http/Deployments/Duplicate/Create.php | 8 ++- .../Modules/VCS/Http/GitHub/Deployment.php | 8 ++- 8 files changed, 99 insertions(+), 40 deletions(-) diff --git a/composer.json b/composer.json index 1aaadf5dd6..c7cf907469 100644 --- a/composer.json +++ b/composer.json @@ -135,7 +135,7 @@ "league/csv": "9.14.*", "enshrined/svg-sanitize": "0.22.*", "utopia-php/client": "^0.3.0", - "open-runtimes/sdk-for-php": "0.10.*", + "open-runtimes/sdk-for-php": "0.11.*", "utopia-php/schedule": "^0.2.0" }, "require-dev": { diff --git a/composer.lock b/composer.lock index 5db8094d71..fd8de8542f 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "40231755d4dc80d8a23901402b42df4a", + "content-hash": "bc7793f803702df7c7726d103a13f599", "packages": [ { "name": "adhocore/jwt", @@ -1079,16 +1079,16 @@ }, { "name": "open-runtimes/sdk-for-php", - "version": "0.10.1", + "version": "0.11.1", "source": { "type": "git", "url": "https://github.com/open-runtimes/sdk-for-php.git", - "reference": "2a83df23a377d846a6a57e2146c485c4be706512" + "reference": "2db10da2fa7163d096bfd8343a44ae99a2852527" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/open-runtimes/sdk-for-php/zipball/2a83df23a377d846a6a57e2146c485c4be706512", - "reference": "2a83df23a377d846a6a57e2146c485c4be706512", + "url": "https://api.github.com/repos/open-runtimes/sdk-for-php/zipball/2db10da2fa7163d096bfd8343a44ae99a2852527", + "reference": "2db10da2fa7163d096bfd8343a44ae99a2852527", "shasum": "" }, "require": { @@ -1113,12 +1113,12 @@ "license": [ "MIT" ], - "description": "PHP SDK for the Open Runtimes orchestrator Jobs API.", + "description": "PHP SDK for the Open Runtimes orchestrator: jobs, deployments, sandboxes, and pools.", "support": { "issues": "https://github.com/open-runtimes/sdk-for-php/issues", - "source": "https://github.com/open-runtimes/sdk-for-php/tree/0.10.1" + "source": "https://github.com/open-runtimes/sdk-for-php/tree/0.11.1" }, - "time": "2026-07-31T13:09:22+00:00" + "time": "2026-08-19T12:49:14+00:00" }, { "name": "open-telemetry/api", @@ -5068,16 +5068,16 @@ }, { "name": "utopia-php/vcs", - "version": "5.2.0", + "version": "5.2.1", "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "780f3c84d270a14744a8cd61b1234310d9af59c4" + "reference": "ee3928969d6c654fad44fad7f38cc96383b031fa" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/780f3c84d270a14744a8cd61b1234310d9af59c4", - "reference": "780f3c84d270a14744a8cd61b1234310d9af59c4", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/ee3928969d6c654fad44fad7f38cc96383b031fa", + "reference": "ee3928969d6c654fad44fad7f38cc96383b031fa", "shasum": "" }, "require": { @@ -5128,10 +5128,10 @@ "vcs" ], "support": { - "source": "https://github.com/utopia-php/vcs/tree/5.2.0", + "source": "https://github.com/utopia-php/vcs/tree/5.2.1", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-19T10:17:14+00:00" + "time": "2026-08-19T12:49:54+00:00" }, { "name": "utopia-php/websocket", diff --git a/src/Appwrite/Deployment/Deployments.php b/src/Appwrite/Deployment/Deployments.php index 92d3c56150..79c6e3ddb9 100644 --- a/src/Appwrite/Deployment/Deployments.php +++ b/src/Appwrite/Deployment/Deployments.php @@ -7,6 +7,7 @@ use Appwrite\Extend\Exception; use OpenRuntimes\Orchestrator\Enum\CallbackEvent; use OpenRuntimes\Orchestrator\Enum\ReadFormat; use OpenRuntimes\Orchestrator\Jobs; +use OpenRuntimes\Orchestrator\Model\Artifact\CloneArtifact; use OpenRuntimes\Orchestrator\Model\Artifact\DownloadArtifact; use OpenRuntimes\Orchestrator\Model\Artifact\ReadArtifact; use OpenRuntimes\Orchestrator\Model\Artifact\StatArtifact; @@ -21,6 +22,7 @@ use Utopia\Database\Helpers\Permission; use Utopia\Database\Helpers\Role; use Utopia\Database\Query; use Utopia\System\System; +use Utopia\VCS\Adapter\Git; /** * Owns a deployment's lifecycle: upload bookkeeping, creating it and @@ -133,6 +135,41 @@ readonly class Deployments return $this->submit($resource, $deployment, ['url' => $url, 'subdir' => $rootDirectory, 'headers' => $headers]); } + /** + * Same as createFromUpload(), but builds from a repository on a VCS + * provider: a presigned archive URL when the provider hands those out, or + * a git clone through the jobs-service's clone artifact when the provider + * serves content over the git protocol only (Origin). + * + * @param string $ref Branch, tag, or commit the deployment builds from + */ + public function createFromVcs( + Document $resource, + Document $deployment, + Git $vcs, + string $owner, + string $repository, + string $ref, + string $rootDirectory = '', + ): Document { + if ($vcs->supportsRepositoryArchives()) { + return $this->createFromUrl( + $resource, + $deployment, + $vcs->getRepositoryPresignedUrl($owner, $repository, $ref), + $rootDirectory, + $vcs->getRepositoryPresignedUrlHeaders(), + ); + } + + return $this->submit($resource, $deployment, [ + 'clone' => $vcs->getRepositoryCloneUrl($owner, $repository), + 'ref' => $ref, + 'subdir' => $rootDirectory, + 'headers' => $vcs->getRepositoryCloneHeaders(), + ]); + } + private function submit(Document $resource, Document $deployment, ?array $source): Document { // The caller may have been holding this deployment for a while (the @@ -317,15 +354,25 @@ readonly class Deployments $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; $endpoint = System::getEnv('_APP_JOBS_ENDPOINT', "$protocol://{$platform['apiHostname']}"); - // Source artifacts, both ending in /mnt/code/source: - // - remote tarball ($source): templates (public codeload URL) and VCS - // (a short-lived presigned URL). Git-forge archives wrap the tree in - // a "{repo}-{ref}/" root the caller can't predict, so strip drops it - // and subdir then extracts just the rootDirectory from the unwrapped - // tree. Uploaded tarballs (the else branch) are flat — no strip. + // Source artifacts, all ending in /mnt/code/source: + // - remote tarball ($source with url): templates (public codeload URL) + // and VCS (a short-lived presigned URL). Git-forge archives wrap the + // tree in a "{repo}-{ref}/" root the caller can't predict, so strip + // drops it and subdir then extracts just the rootDirectory from the + // unwrapped tree. Uploaded tarballs (the else branch) are flat — no + // strip. + // - git clone ($source with clone): a provider without archive + // downloads; the sidecar clones over Git HTTPS and checks the tree + // out directly, so there is no archive to unarchive — or to stat, + // which is why this path reports no sourceSize. // - otherwise: the deployment's uploaded tarball, fetched from Appwrite // over a presigned GET (manual upload / duplicate). - if ($source !== null) { + if (isset($source['clone'])) { + $subdir = \trim($source['subdir'] ?? '', '/'); + $sourceArtifacts = [ + new CloneArtifact(id: 'source', in: $source['clone'], out: 'source', ref: $source['ref'] ?? '', subdir: $subdir, headers: $source['headers'] ?? []), + ]; + } elseif ($source !== null) { $subdir = \trim($source['subdir'] ?? '', '/'); $sourceArtifacts = [ new DownloadArtifact(id: 'source', in: $source['url'], out: 'source.tar.gz', headers: $source['headers'] ?? []), diff --git a/src/Appwrite/Platform/Modules/Compute/Base.php b/src/Appwrite/Platform/Modules/Compute/Base.php index fb3e5bd8a1..b9cf1948d5 100644 --- a/src/Appwrite/Platform/Modules/Compute/Base.php +++ b/src/Appwrite/Platform/Modules/Compute/Base.php @@ -175,12 +175,14 @@ class Base extends Action // git write and then hands the build to the jobs-service itself. if ($template->isEmpty()) { $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); - $deployment = $deployments->createFromUrl( + $deployment = $deployments->createFromVcs( $function, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repositoryName, $ref), + $vcs, + $owner, + $repositoryName, + $ref, $function->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), ); } else { $deployment = $dbForProject->createDocument('deployments', new Document([ @@ -400,12 +402,14 @@ class Base extends Action // pushes go through the Builds worker (same split as redeployVcsFunction). if ($template->isEmpty()) { $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); - $deployment = $deployments->createFromUrl( + $deployment = $deployments->createFromVcs( $site, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repositoryName, $ref), + $vcs, + $owner, + $repositoryName, + $ref, $site->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), ); } else { $publisherForBuilds->enqueue(new BuildMessage( diff --git a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php index 55616a18b7..5f98bbf24a 100644 --- a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php +++ b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php @@ -157,12 +157,14 @@ class Create extends Action $github = $vcsFactory->fromInstallation($installation); $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); - $deployment = $deployments->createFromUrl( + $deployment = $deployments->createFromVcs( $function, $deployment, - $github->getRepositoryPresignedUrl($owner, $repository, $ref), + $github, + $owner, + $repository, + $ref, $deployment->getAttribute('providerRootDirectory', ''), - $github->getRepositoryPresignedUrlHeaders(), ); } else { // Public template repo: providerBranch holds the resolved ref, diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 776f0adae6..16fe9f66be 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -401,12 +401,14 @@ class Builds extends Action // jobs-service like any other VCS commit, via the same Deployments // service the HTTP endpoints use. $ref = $deployment->getAttribute('providerCommitHash') ?: $branchName; - $deployments->createFromUrl( + $deployments->createFromVcs( $resource, $deployment, - $providerAdapter->getRepositoryPresignedUrl($cloneOwner, $cloneRepository, $ref), + $providerAdapter, + $cloneOwner, + $cloneRepository, + $ref, $resource->getAttribute('providerRootDirectory', ''), - $providerAdapter->getRepositoryPresignedUrlHeaders(), ); Console::execute('rm -rf ' . \escapeshellarg('/tmp/builds/' . $deploymentId), '', $stdout, $stderr); diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php index 9dc11db43e..f9a81f494e 100644 --- a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php +++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php @@ -182,12 +182,14 @@ class Create extends Action $vcs = $vcsFactory->fromInstallation($installation); $ref = $deployment->getAttribute('providerCommitHash') ?: $deployment->getAttribute('providerBranch'); - $deployment = $deployments->createFromUrl( + $deployment = $deployments->createFromVcs( $site, $deployment, - $vcs->getRepositoryPresignedUrl($owner, $repository, $ref), + $vcs, + $owner, + $repository, + $ref, $deployment->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), ); } else { // Public template repo: providerBranch holds the resolved ref, diff --git a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php index 892f666cad..b89364fb45 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/GitHub/Deployment.php @@ -395,12 +395,14 @@ trait Deployment // The Deployments service is built per repository: a webhook fans out to // many tenant projects, each with its own database. $deployment = $authorization->skip(fn () => $deploymentsFactory($dbForProject, $project) - ->createFromUrl( + ->createFromVcs( $resource, $deployment, - $vcs->getRepositoryPresignedUrl($providerRepositoryOwner, $providerRepositoryName, $providerCommitHash), + $vcs, + $providerRepositoryOwner, + $providerRepositoryName, + $providerCommitHash, $resource->getAttribute('providerRootDirectory', ''), - $vcs->getRepositoryPresignedUrlHeaders(), )); if ($resource->getCollection() === 'sites') { From 6b78dd45e42d2f13a7f8ee8a291970e047b40f96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 13:01:01 +0200 Subject: [PATCH 41/53] feat: report VCS provider capabilities to the console The console variables response gains two lists shaped like _APP_VCS_PROVIDERS: the configured providers that support repository creation and the ones that can host public repositories, read from the adapter capability API, so the console can hide flows a provider cannot serve. Co-Authored-By: Claude Fable 5 --- .../Modules/Console/Http/Variables/Get.php | 22 +++++++++++++++++-- .../Response/Model/ConsoleVariables.php | 14 ++++++++++++ 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php b/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php index 9adf5ebf9a..7474866438 100644 --- a/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php +++ b/src/Appwrite/Platform/Modules/Console/Http/Variables/Get.php @@ -7,6 +7,7 @@ use Appwrite\SDK\ContentType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; +use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Domains\Domain; @@ -47,6 +48,7 @@ class Get extends Action contentType: ContentType::JSON )) ->inject('vcsProviders') + ->inject('vcsFactory') ->inject('response') ->inject('platform') ->inject('dbForProject') @@ -55,6 +57,7 @@ class Get extends Action public function action( callable $vcsProviders, + VcsFactory $vcsFactory, Response $response, array $platform, Database $dbForProject @@ -71,7 +74,20 @@ class Get extends Action $isDomainEnabled = $isAAAAValid || $isAValid || $isCNAMEValid; - $isVcsEnabled = !empty($vcsProviders()); + $providers = $vcsProviders(); + $isVcsEnabled = !empty($providers); + + $providersWithRepositoryCreation = []; + $providersWithPublicRepositories = []; + foreach ($providers as $provider) { + $adapter = $vcsFactory->fromProvider($provider); + if ($adapter->supportsRepositoryCreation()) { + $providersWithRepositoryCreation[] = $provider; + } + if ($adapter->supportsPublicRepositories()) { + $providersWithPublicRepositories[] = $provider; + } + } $isAssistantEnabled = !empty(System::getEnv('_APP_ASSISTANT_OPENAI_API_KEY', '')); @@ -87,7 +103,9 @@ class Get extends Action '_APP_COMPUTE_SIZE_LIMIT' => +System::getEnv('_APP_COMPUTE_SIZE_LIMIT'), '_APP_USAGE_STATS' => System::getEnv('_APP_USAGE_STATS'), '_APP_VCS_ENABLED' => $isVcsEnabled, - '_APP_VCS_PROVIDERS' => $vcsProviders(), + '_APP_VCS_PROVIDERS' => $providers, + '_APP_VCS_PROVIDERS_WITH_REPOSITORY_CREATION' => $providersWithRepositoryCreation, + '_APP_VCS_PROVIDERS_WITH_PUBLIC_REPOSITORIES' => $providersWithPublicRepositories, '_APP_DOMAIN_ENABLED' => $isDomainEnabled, '_APP_ASSISTANT_ENABLED' => $isAssistantEnabled, '_APP_DOMAIN_SITES' => $platform['sitesDomain'], diff --git a/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php b/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php index ab179d04ee..2a32be686e 100644 --- a/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php +++ b/src/Appwrite/Utopia/Response/Model/ConsoleVariables.php @@ -71,6 +71,20 @@ class ConsoleVariables extends Model 'example' => ['github'], 'array' => true, ]) + ->addRule('_APP_VCS_PROVIDERS_WITH_REPOSITORY_CREATION', [ + 'type' => self::TYPE_STRING, + 'description' => 'List of configured VCS providers that support repository creation.', + 'default' => [], + 'example' => ['github'], + 'array' => true, + ]) + ->addRule('_APP_VCS_PROVIDERS_WITH_PUBLIC_REPOSITORIES', [ + 'type' => self::TYPE_STRING, + 'description' => 'List of configured VCS providers that can host public repositories.', + 'default' => [], + 'example' => ['github'], + 'array' => true, + ]) ->addRule('_APP_DOMAIN_ENABLED', [ 'type' => self::TYPE_BOOLEAN, 'description' => 'Defines if main domain is configured. If so, custom domains can be created.', From 194b8e5cef24fbdefb023c7d7301f0c0bc321cde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 13:01:14 +0200 Subject: [PATCH 42/53] fix: guard repository creation behind the adapter capability Origin's createRepository() throws in utopia-php/vcs 5.2.0; asking supportsRepositoryCreation() first turns that into a clear client error instead of an uncaught provider exception. Co-Authored-By: Claude Fable 5 --- .../Modules/VCS/Http/Installations/Repositories/Create.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php index d8dae58f3b..7f29f0b005 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Create.php @@ -112,6 +112,11 @@ class Create extends Action } else { $providerInstallationId = $installation->getAttribute('providerInstallationId'); $vcs = $vcsFactory->fromInstallation($installation); + + if (!$vcs->supportsRepositoryCreation()) { + throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'VCS provider does not support repository creation: ' . $provider); + } + $owner = !empty($providerNamespace) ? $providerNamespace : $vcs->getOwnerName($providerInstallationId); try { From a7d7e9144765f0461e3118e6f84d1750ef3effe2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:23:16 +0200 Subject: [PATCH 43/53] refactor(avatars): render initials endpoint through the Initials provider The provider was a copy of the endpoint's inline logic. Make it the single implementation instead: render() draws any label, getInitials()/getTheme() derive the letters and colour, and get() keeps resolving the label off the user for the photo chain. Initials derivation and theme selection are unchanged. Sizes of 0, which the Range(0, 2000) validator allows, now fall back to the 500px default rather than reaching Imagick::newImage(0, 0), and a '#'-prefixed background no longer yields '##aabbcc'. Co-Authored-By: Claude Opus 5 (1M context) --- .../AvatarPhotos/Providers/Initials.php | 109 ++++++++++++------ .../Modules/Avatars/Http/Initials/Get.php | 60 +--------- 2 files changed, 78 insertions(+), 91 deletions(-) diff --git a/src/Appwrite/AvatarPhotos/Providers/Initials.php b/src/Appwrite/AvatarPhotos/Providers/Initials.php index e4b8cf3bed..3bbfdd2462 100644 --- a/src/Appwrite/AvatarPhotos/Providers/Initials.php +++ b/src/Appwrite/AvatarPhotos/Providers/Initials.php @@ -11,17 +11,20 @@ use Utopia\Database\Document; /** * Initials provider. * - * Generates a coloured square with the user's initials — identical logic to - * the standalone GET /v1/avatars/initials endpoint, but exposed as a plain - * PHP class so the photo-resolution chain can call it without going through - * HTTP. + * Generates a coloured square with the user's initials. This is the single + * implementation behind both the photo-resolution chain and the standalone + * GET /v1/avatars/initials endpoint — the endpoint renders an arbitrary label + * through render(), the chain resolves the label off the user first. */ class Initials extends Photo { /** Font used to render the initials, relative to the project root. */ private const FONT_PATH = '/app/assets/fonts/inter-v8-latin-regular.woff2'; - /** Colour palette — same as the Initials endpoint. */ + /** Edge length used when the caller does not ask for a size. */ + private const DEFAULT_SIZE = 500; + + /** Colour palette — a theme is picked from the initials themselves. */ private array $themes = [ ['background' => '#FD366E'], // Pink ['background' => '#FE9567'], // Orange @@ -53,41 +56,35 @@ class Initials extends Photo $name = $this->getLabel($user); - if (empty(\trim($name))) { + // Nothing printable to draw — bail out so the static fallback can be + // used instead. The standalone endpoint has no such fallback and keeps + // rendering a plain coloured square, which is why this check lives + // here and not in render(). + if (empty($this->getInitials($name))) { return null; } - $words = \explode(' ', \strtoupper($name)); - // Fallback: split on underscores when there is no space - $words = (\count($words) === 1) ? \explode('_', \strtoupper($name)) : $words; + return $this->render($name, $width, $height); + } - $initials = ''; - $code = 0; + /** + * Render the initials of an arbitrary label as a PNG. + * + * @param string $name Label to derive the initials from. + * @param int $width Output width in pixels; defaults when not positive. + * @param int $height Output height in pixels; defaults when not positive. + * @return string Raw PNG bytes. + */ + public function render(string $name, int $width, int $height): string + { + $initials = $this->getInitials($name); - foreach ($words as $key => $w) { - if (\ctype_alnum($w[0] ?? '')) { - $initials .= $w[0]; - $code += \ord($w[0]); + $width = $width > 0 ? $width : self::DEFAULT_SIZE; + $height = $height > 0 ? $height : self::DEFAULT_SIZE; - if ($key === 1) { - break; - } - } - } - - // If we still have no printable initials, bail out so the static - // fallback can be used instead. - if (empty($initials)) { - return null; - } - - $width = $width > 0 ? $width : 500; - $height = $height > 0 ? $height : 500; - - $rand = (int) \substr((string) $code, -1); - $rand = ($rand > \count($this->themes) - 1) ? $rand % \count($this->themes) : $rand; - - $bg = (!empty($this->background)) ? '#' . \ltrim($this->background, '#') : $this->themes[$rand]['background']; + $bg = !empty($this->background) + ? '#' . \ltrim($this->background, '#') + : $this->getTheme($initials); $image = new Imagick(); $punch = new Imagick(); @@ -118,6 +115,50 @@ class Initials extends Photo return $image->getImageBlob(); } + /** + * First letter of the first two words, skipping words that do not start + * with an alphanumeric character. Underscores stand in for spaces when the + * label has none. + */ + private function getInitials(string $name): string + { + $words = \explode(' ', \strtoupper($name)); + // Fallback: split on underscores when there is no space + $words = (\count($words) === 1) ? \explode('_', \strtoupper($name)) : $words; + + $initials = ''; + + foreach ($words as $key => $w) { + if (\ctype_alnum($w[0] ?? '')) { + $initials .= $w[0]; + + if ($key === 1) { + break; + } + } + } + + return $initials; + } + + /** + * Background colour for a set of initials. Derived from the initials so the + * same label always gets the same colour. + */ + private function getTheme(string $initials): string + { + $code = 0; + + foreach (\str_split($initials) as $char) { + $code += \ord($char); + } + + $rand = (int) \substr((string) $code, -1); + $rand = ($rand > \count($this->themes) - 1) ? $rand % \count($this->themes) : $rand; + + return $this->themes[$rand]['background']; + } + /** * Text the initials are derived from — the display name, falling back to * the email address when the user has not set one. diff --git a/src/Appwrite/Platform/Modules/Avatars/Http/Initials/Get.php b/src/Appwrite/Platform/Modules/Avatars/Http/Initials/Get.php index 4808cb7267..d5f100e96f 100644 --- a/src/Appwrite/Platform/Modules/Avatars/Http/Initials/Get.php +++ b/src/Appwrite/Platform/Modules/Avatars/Http/Initials/Get.php @@ -2,6 +2,7 @@ namespace Appwrite\Platform\Modules\Avatars\Http\Initials; +use Appwrite\AvatarPhotos\Providers\Initials; use Appwrite\Platform\Modules\Avatars\Http\Action; use Appwrite\SDK\AuthType; use Appwrite\SDK\ContentType; @@ -9,9 +10,6 @@ use Appwrite\SDK\Method; use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; -use Imagick; -use ImagickDraw; -use ImagickPixel; use Utopia\Database\Document; use Utopia\Platform\Action as UtopiaAction; use Utopia\Platform\Scope\HTTP; @@ -64,65 +62,13 @@ class Get extends Action public function action(string $name, int $width, int $height, string $background, Response $response, Document $user) { - $themes = [ - ['background' => '#FD366E'], // Default (Pink) - ['background' => '#FE9567'], // Orange - ['background' => '#7C67FE'], // Purple - ['background' => '#68A3FE'], // Blue - ['background' => '#85DBD8'], // Mint - ]; - $name = (!empty($name)) ? $name : $user->getAttribute('name', $user->getAttribute('email', '')); - $words = \explode(' ', \strtoupper($name)); - // if there is no space, try to split by `_` underscore - $words = (count($words) == 1) ? \explode('_', \strtoupper($name)) : $words; - $initials = ''; - $code = 0; - - foreach ($words as $key => $w) { - if (ctype_alnum($w[0] ?? '')) { - $initials .= $w[0]; - $code += ord($w[0]); - - if ($key == 1) { - break; - } - } - } - - $rand = (int) \substr((string) $code, -1); - - $rand = ($rand > \count($themes) - 1) ? $rand % \count($themes) : $rand; - - $background = (!empty($background)) ? '#' . $background : $themes[$rand]['background']; - - $image = new Imagick(); - $punch = new Imagick(); - $draw = new ImagickDraw(); - $fontSize = \min($width, $height) / 2; - - $punch->newImage($width, $height, 'transparent'); - - $draw->setFont($this->getAppRoot() . '/app/assets/fonts/inter-v8-latin-regular.woff2'); - $image->setFont($this->getAppRoot() . '/app/assets/fonts/inter-v8-latin-regular.woff2'); - - $draw->setFillColor(new ImagickPixel('black')); - $draw->setFontSize($fontSize); - - $draw->setTextAlignment(Imagick::ALIGN_CENTER); - $draw->annotation($width / 1.97, ($height / 2) + ($fontSize / 3), $initials); - - $punch->drawImage($draw); - $punch->negateImage(true, Imagick::CHANNEL_ALPHA); - - $image->newImage($width, $height, $background); - $image->setImageFormat("png"); - $image->compositeImage($punch, Imagick::COMPOSITE_COPYOPACITY, 0, 0); + $image = (new Initials($background))->render($name, $width, $height); $response ->addHeader('Cache-Control', 'private, max-age=3888000') // 45 days ->setContentType('image/png') - ->file($image->getImageBlob()); + ->file($image); } } From 66c1f01d6166f79c900722f28662eb230396952a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:23:16 +0200 Subject: [PATCH 44/53] fix(avatars): bound remote photo lookups with explicit timeouts Gravatar and Libavatar each built a bare Client, inheriting utopia-php/fetch defaults of 15s request and 5s connect. The two run back to back, so one unreachable service could hold the request for ~20s before the local initials and fallback providers were reached. Move the request into Photo::fetch() so the budget is set in one place, and tighten it to 2s connect / 5s request. CURLOPT_TIMEOUT_MS covers the whole transfer including redirects and retries default to 0, so the remote leg is now capped at 10s. Co-Authored-By: Claude Opus 5 (1M context) --- src/Appwrite/AvatarPhotos/Photo.php | 46 +++++++++++++++++++ .../AvatarPhotos/Providers/Gravatar.php | 23 +--------- .../AvatarPhotos/Providers/Libavatar.php | 23 +--------- 3 files changed, 48 insertions(+), 44 deletions(-) diff --git a/src/Appwrite/AvatarPhotos/Photo.php b/src/Appwrite/AvatarPhotos/Photo.php index dafe7622d2..e46067bc68 100644 --- a/src/Appwrite/AvatarPhotos/Photo.php +++ b/src/Appwrite/AvatarPhotos/Photo.php @@ -3,6 +3,7 @@ namespace Appwrite\AvatarPhotos; use Utopia\Database\Document; +use Utopia\Fetch\Client; /** * Base class every avatar photo provider extends. @@ -14,6 +15,20 @@ use Utopia\Database\Document; */ abstract class Photo { + /** + * How long a provider may wait to open a connection to a remote service. + */ + protected const CONNECT_TIMEOUT = 2 * 1000; // 2 seconds + + /** + * How long a provider may wait for a complete remote response. + * + * Providers are tried one after another, so these budgets stack: a single + * unreachable service must not be able to hold the request open while we + * still have other providers — and a local fallback — left to try. + */ + protected const REQUEST_TIMEOUT = 5 * 1000; // 5 seconds + /** * Machine-readable name of the provider, e.g. 'gravatar'. */ @@ -41,4 +56,35 @@ abstract class Photo * @return string|null Raw image bytes, or null when unavailable. */ abstract public function get(Document $user, int $width, int $height, string $rating): ?string; + + /** + * GET $url with the provider timeout budget applied. + * + * Anything other than a 200 with a non-empty body — including a timeout or + * a transport error — is reported as null so the caller can move on. + * + * @return string|null Raw response body, or null when unavailable. + */ + protected function fetch(string $url): ?string + { + $client = new Client(); + + try { + $response = $client + ->setAllowRedirects(true) + ->setConnectTimeout(static::CONNECT_TIMEOUT) + ->setTimeout(static::REQUEST_TIMEOUT) + ->fetch($url); + } catch (\Throwable) { + return null; + } + + if ($response->getStatusCode() !== 200) { + return null; + } + + $body = $response->getBody(); + + return empty($body) ? null : $body; + } } diff --git a/src/Appwrite/AvatarPhotos/Providers/Gravatar.php b/src/Appwrite/AvatarPhotos/Providers/Gravatar.php index 5414af9087..a4985fdf60 100644 --- a/src/Appwrite/AvatarPhotos/Providers/Gravatar.php +++ b/src/Appwrite/AvatarPhotos/Providers/Gravatar.php @@ -4,7 +4,6 @@ namespace Appwrite\AvatarPhotos\Providers; use Appwrite\AvatarPhotos\Photo; use Utopia\Database\Document; -use Utopia\Fetch\Client; /** * Gravatar provider. @@ -41,26 +40,6 @@ class Gravatar extends Photo 'r' => $rating, ]); - $client = new Client(); - - try { - $res = $client - ->setAllowRedirects(true) - ->fetch($url); - } catch (\Throwable) { - return null; - } - - if ($res->getStatusCode() !== 200) { - return null; - } - - $body = $res->getBody(); - - if (empty($body)) { - return null; - } - - return $body; + return $this->fetch($url); } } diff --git a/src/Appwrite/AvatarPhotos/Providers/Libavatar.php b/src/Appwrite/AvatarPhotos/Providers/Libavatar.php index 60c190e5de..e5100c809e 100644 --- a/src/Appwrite/AvatarPhotos/Providers/Libavatar.php +++ b/src/Appwrite/AvatarPhotos/Providers/Libavatar.php @@ -4,7 +4,6 @@ namespace Appwrite\AvatarPhotos\Providers; use Appwrite\AvatarPhotos\Photo; use Utopia\Database\Document; -use Utopia\Fetch\Client; /** * Libravatar provider. @@ -45,26 +44,6 @@ class Libavatar extends Photo 'r' => $rating, ]); - $client = new Client(); - - try { - $res = $client - ->setAllowRedirects(true) - ->fetch($url); - } catch (\Throwable) { - return null; - } - - if ($res->getStatusCode() !== 200) { - return null; - } - - $body = $res->getBody(); - - if (empty($body)) { - return null; - } - - return $body; + return $this->fetch($url); } } From 5021eff4a4b06f0b4f628104f940502f82e09b65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:36:10 +0200 Subject: [PATCH 45/53] fix: drop the source-archive plumbing superseded on main Main now sources archive-less providers through the orchestrator's clone artifact (Deployments::createFromVcs(), #13285), so the merge leaves this branch's precursors with no callers: the SourceArchive presigner, the GET /v1/vcs/archives endpoint, and the vcsProvider response model that the console variables' env-style capability lists replaced. Co-Authored-By: Claude Fable 5 --- app/init/models.php | 2 - .../Modules/VCS/Http/Archives/Get.php | 114 ------------------ .../Platform/Modules/VCS/Services/Http.php | 4 - src/Appwrite/Utopia/Response.php | 1 - .../Utopia/Response/Model/VcsProvider.php | 52 -------- src/Appwrite/Vcs/SourceArchive.php | 66 ---------- 6 files changed, 239 deletions(-) delete mode 100644 src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php delete mode 100644 src/Appwrite/Utopia/Response/Model/VcsProvider.php delete mode 100644 src/Appwrite/Vcs/SourceArchive.php diff --git a/app/init/models.php b/app/init/models.php index 5156881b26..ad147b9b2b 100644 --- a/app/init/models.php +++ b/app/init/models.php @@ -228,7 +228,6 @@ use Appwrite\Utopia\Response\Model\User; use Appwrite\Utopia\Response\Model\Variable; use Appwrite\Utopia\Response\Model\VcsContent; use Appwrite\Utopia\Response\Model\VcsNamespace; -use Appwrite\Utopia\Response\Model\VcsProvider; use Appwrite\Utopia\Response\Model\VectorsDBCollection; use Appwrite\Utopia\Response\Model\Webhook; @@ -266,7 +265,6 @@ Response::setModel(new ProviderRepositoryFrameworkList()); Response::setModel(new ProviderRepositoryRuntimeList()); Response::setModel(new VcsNamespace()); Response::setModel(new BaseList('VCS Namespaces List', Response::MODEL_VCS_NAMESPACE_LIST, 'namespaces', Response::MODEL_VCS_NAMESPACE)); -Response::setModel(new VcsProvider()); Response::setModel(new BaseList('Branches List', Response::MODEL_BRANCH_LIST, 'branches', Response::MODEL_BRANCH)); Response::setModel(new BaseList('Frameworks List', Response::MODEL_FRAMEWORK_LIST, 'frameworks', Response::MODEL_FRAMEWORK)); Response::setModel(new BaseList('Runtimes List', Response::MODEL_RUNTIME_LIST, 'runtimes', Response::MODEL_RUNTIME)); diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php deleted file mode 100644 index 4951fa1a67..0000000000 --- a/src/Appwrite/Platform/Modules/VCS/Http/Archives/Get.php +++ /dev/null @@ -1,114 +0,0 @@ -setHttpMethod(Action::HTTP_REQUEST_METHOD_GET) - ->setHttpPath('/v1/vcs/archives') - ->desc('Download repository archive') - ->groups(['api', 'vcs']) - ->label('scope', 'public') - ->param('provider', '', new Text(64, 0), 'VCS provider the repository lives on.') - ->param('installation', '', new Text(256, 0), 'Provider installation ID the credentials belong to.') - ->param('owner', '', new Text(256, 0), 'Owner of the repository.') - ->param('repository', '', new Text(256, 0), 'Name of the repository.') - ->param('ref', '', new Text(256, 0), 'Branch, tag or commit to archive.') - ->param('expires', 0, new Integer(loose: true, bits: 64), 'Unix timestamp the link stops working at.') - ->param('signature', '', new Text(128, 0), 'HMAC binding every other parameter.') - ->inject('response') - ->inject('vcsFactory') - ->callback($this->action(...)); - } - - /** - * Packages a repository the provider cannot archive itself. The link is - * minted by Appwrite\Vcs\SourceArchive for the jobs-service source fetch, - * and the HMAC is the whole authorization: it commits to every parameter - * and an expiry, and only Appwrite can produce it. - */ - public function action( - string $provider, - string $installation, - string $owner, - string $repository, - string $ref, - int $expires, - string $signature, - Response $response, - VcsFactory $vcsFactory, - ) { - $expected = SourceArchive::signature($provider, $installation, $owner, $repository, $ref, $expires); - - if (empty($signature) || !\hash_equals($expected, $signature)) { - throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'Invalid archive signature.'); - } - - if ($expires < \time()) { - throw new Exception(Exception::GENERAL_ACCESS_FORBIDDEN, 'The archive link has expired.'); - } - - $vcs = $vcsFactory->fromInstallation(new Document([ - 'provider' => $provider, - 'providerInstallationId' => $installation, - ])); - - // Git-forge archives wrap the tree in a "{repo}-{ref}/" root the - // source fetch strips, so this one has to match that shape. - $directory = '/tmp/vcs-archives/' . \uniqid(); - $wrapper = $repository . '-' . \substr(\preg_replace('/[^A-Za-z0-9._-]/', '-', $ref) ?? '', 0, 64); - $archive = $directory . '/archive.tar.gz'; - - $cloneType = \preg_match('/^[0-9a-f]{40}([0-9a-f]{24})?$/i', $ref) ? Git::CLONE_TYPE_COMMIT : Git::CLONE_TYPE_BRANCH; - $cloneCommand = $vcs->generateCloneCommand($owner, $repository, $ref, $cloneType, $directory . '/' . $wrapper, '*'); - - try { - $stdout = ''; - $stderr = ''; - - if (Console::execute($cloneCommand, '', $stdout, $stderr) !== 0) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to download the repository.'); - } - - $packCommand = 'tar --exclude=' . \escapeshellarg($wrapper . '/.git') . ' -czf ' . \escapeshellarg($archive) . ' -C ' . \escapeshellarg($directory) . ' ' . \escapeshellarg($wrapper); - if (Console::execute($packCommand, '', $stdout, $stderr) !== 0) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to package the repository.'); - } - - $contents = \file_get_contents($archive); - if ($contents === false) { - throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Failed to read the repository archive.'); - } - - $response - ->setContentType('application/gzip') - ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') - ->addHeader('Content-Disposition', 'attachment; filename="' . $wrapper . '.tar.gz"') - ->send($contents); - } finally { - Console::execute('rm -rf ' . \escapeshellarg($directory), '', $stdout, $stderr); - } - } -} diff --git a/src/Appwrite/Platform/Modules/VCS/Services/Http.php b/src/Appwrite/Platform/Modules/VCS/Services/Http.php index 55e268980c..71498db484 100644 --- a/src/Appwrite/Platform/Modules/VCS/Services/Http.php +++ b/src/Appwrite/Platform/Modules/VCS/Services/Http.php @@ -2,7 +2,6 @@ namespace Appwrite\Platform\Modules\VCS\Services; -use Appwrite\Platform\Modules\VCS\Http\Archives\Get as GetArchive; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Authorize\Get as GetBitbucketAuthorize; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Callback\Get as GetBitbucketCallback; use Appwrite\Platform\Modules\VCS\Http\Bitbucket\Events\Create as CreateBitbucketEvent; @@ -64,9 +63,6 @@ class Http extends Service $this->addAction(DeleteInstallation::getName(), new DeleteInstallation()); $this->addAction(ListNamespaces::getName(), new ListNamespaces()); - // Archives - $this->addAction(GetArchive::getName(), new GetArchive()); - // Repositories $this->addAction(CreateRepository::getName(), new CreateRepository()); $this->addAction(GetRepository::getName(), new GetRepository()); diff --git a/src/Appwrite/Utopia/Response.php b/src/Appwrite/Utopia/Response.php index 4a2b7aaead..bfd02dafe1 100644 --- a/src/Appwrite/Utopia/Response.php +++ b/src/Appwrite/Utopia/Response.php @@ -195,7 +195,6 @@ class Response extends SwooleResponse public const MODEL_PROVIDER_REPOSITORY_RUNTIME_LIST = 'providerRepositoryRuntimeList'; public const MODEL_VCS_NAMESPACE = 'vcsNamespace'; public const MODEL_VCS_NAMESPACE_LIST = 'vcsNamespaceList'; - public const MODEL_VCS_PROVIDER = 'vcsProvider'; public const MODEL_BRANCH = 'branch'; public const MODEL_BRANCH_LIST = 'branchList'; public const MODEL_DETECTION_FRAMEWORK = 'detectionFramework'; diff --git a/src/Appwrite/Utopia/Response/Model/VcsProvider.php b/src/Appwrite/Utopia/Response/Model/VcsProvider.php deleted file mode 100644 index f7cd552603..0000000000 --- a/src/Appwrite/Utopia/Response/Model/VcsProvider.php +++ /dev/null @@ -1,52 +0,0 @@ -addRule('name', [ - 'type' => self::TYPE_STRING, - 'description' => 'VCS (Version Control System) provider name.', - 'default' => '', - 'example' => 'github', - ]) - ->addRule('supportForRepositoryCreation', [ - 'type' => self::TYPE_BOOLEAN, - 'description' => 'Defines if the provider allows creating repositories. Some providers reserve repository creation for their own UI.', - 'default' => false, - 'example' => true, - ]) - ->addRule('supportForPublicRepositories', [ - 'type' => self::TYPE_BOOLEAN, - 'description' => 'Defines if the provider can host repositories that are readable without authentication.', - 'default' => false, - 'example' => true, - ]); - } - - /** - * Get Name - * - * @return string - */ - public function getName(): string - { - return 'VcsProvider'; - } - - /** - * Get Type - * - * @return string - */ - public function getType(): string - { - return Response::MODEL_VCS_PROVIDER; - } -} diff --git a/src/Appwrite/Vcs/SourceArchive.php b/src/Appwrite/Vcs/SourceArchive.php deleted file mode 100644 index 3e1093fc4c..0000000000 --- a/src/Appwrite/Vcs/SourceArchive.php +++ /dev/null @@ -1,66 +0,0 @@ - $platform - * @return array{string, array} The source URL and the headers to fetch it with - */ - public static function presign(Git $vcs, string $providerInstallationId, string $owner, string $repository, string $ref, array $platform): array - { - if ($vcs->supportsRepositoryArchives()) { - return [ - $vcs->getRepositoryPresignedUrl($owner, $repository, $ref), - $vcs->getRepositoryPresignedUrlHeaders(), - ]; - } - - $expires = \time() + self::TTL; - - $params = [ - 'provider' => $vcs->getName(), - 'installation' => $providerInstallationId, - 'owner' => $owner, - 'repository' => $repository, - 'ref' => $ref, - 'expires' => $expires, - 'signature' => self::signature($vcs->getName(), $providerInstallationId, $owner, $repository, $ref, $expires), - ]; - - // The jobs-service reaches Appwrite over the internal Docker network - // when configured, the same way its presigned callback URLs do. - $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; - $endpoint = \rtrim(System::getEnv('_APP_JOBS_ENDPOINT', $protocol . '://' . ($platform['apiHostname'] ?? '')), '/'); - - return [$endpoint . '/v1/vcs/archives?' . \http_build_query($params), []]; - } - - public static function signature(string $provider, string $providerInstallationId, string $owner, string $repository, string $ref, int $expires): string - { - return \hash_hmac( - 'sha256', - \implode("\n", [$provider, $providerInstallationId, $owner, $repository, $ref, $expires]), - System::getEnv('_APP_OPENSSL_KEY_V1', '') - ); - } -} From d761597be18cd063f58730104c2d2ba4648ea691 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:40:43 +0200 Subject: [PATCH 46/53] refactor: drop Origin's duplicated OAuth2 registration The clientId/clientSecret entries and the oauth2 builder repeated appId and privateKey only so refreshForInstallation() could resolve an OAuth2 client it never uses: for a non-personal installation refresh() is a no-op, and every Origin installation is non-personal. The refresh now returns early for app installations - a GitHub App or Origin app authenticates per request with an app-signed JWT and has no personal tokens to refresh - so Origin registers only what the Factory reads, and oauth2FromProvider('origin') fails loudly instead of handing out a client with duplicated credentials. The install handshake keeps constructing its own Auth\OAuth2\Cursor, which needs the callback, state, and scopes the factory builder could never supply. Co-Authored-By: Claude Fable 5 --- app/config/vcs.php | 18 ++++++------------ src/Appwrite/Vcs/InstallationTokens.php | 7 +++++++ 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/app/config/vcs.php b/app/config/vcs.php index 141b987b42..49f6d3b57e 100644 --- a/app/config/vcs.php +++ b/app/config/vcs.php @@ -5,7 +5,6 @@ */ use Appwrite\Auth\OAuth2\Bitbucket as OAuth2Bitbucket; -use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Auth\OAuth2\Gitea as OAuth2Gitea; use Appwrite\Auth\OAuth2\Github as OAuth2Github; use Appwrite\Auth\OAuth2\Gitlab as OAuth2Gitlab; @@ -66,20 +65,15 @@ return [ ], 'origin' => [ 'adapter' => Origin::class, - // Origin apps authenticate like GitHub Apps (an app-signed JWT minting - // installation tokens), so the same Ed25519 private key doubles as the - // OAuth2 secret. Auth\OAuth2\Cursor expects it JSON-wrapped, the way - // Apple does. - 'oauth2' => fn (string $clientId, string $clientSecret, string $endpoint) => new OAuth2Cursor($clientId, \json_encode([ - 'privateKey' => $clientSecret, - ]), ''), + // No 'oauth2': Origin has no OAuth2 user flow. Installs are approved + // on Cursor and confirmed by a signed receipt, and the dedicated + // Origin endpoints construct their own Auth\OAuth2\Cursor for that + // handshake. 'variables' => [ - 'clientId' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_CLIENT_ID'], - // Factory::fromInstallation() reads appId + privateKey; the app id - // and OAuth2 client id are the same value on Origin. + // Factory::fromInstallation() reads appId + privateKey; Origin's + // app id doubles as its client id. 'appId' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_CLIENT_ID'], 'privateKey' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_PRIVATE_KEY'], - 'clientSecret' => ['required' => true, 'envVariable' => '_APP_VCS_ORIGIN_PRIVATE_KEY'], // No webhookSecret: Origin signs deliveries with its own Ed25519 // key, verified against its published JWKS instead of a shared secret. ], diff --git a/src/Appwrite/Vcs/InstallationTokens.php b/src/Appwrite/Vcs/InstallationTokens.php index c192f6c07b..043ebdbb37 100644 --- a/src/Appwrite/Vcs/InstallationTokens.php +++ b/src/Appwrite/Vcs/InstallationTokens.php @@ -17,6 +17,13 @@ class InstallationTokens */ public function refreshForInstallation(Document $installation, Database $dbForPlatform, Factory $vcsFactory): Document { + // Only personal installations carry OAuth tokens to refresh. An app + // installation (a GitHub App, an Origin app) authenticates per request + // with an app-signed JWT and may have no OAuth2 client to resolve at all. + if (!$installation->getAttribute('personal', false)) { + return $installation; + } + $provider = $installation->getAttribute('provider', 'github'); return $this->refresh($installation, $dbForPlatform, $vcsFactory->oauth2FromProvider($provider)); From 38aa35774a85a4908211aedeaa2ed5d058efde72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:41:32 +0200 Subject: [PATCH 47/53] refactor: inline the Origin installation description The one-endpoint markdown file under docs/references gives way to the heredoc description the newer modules use. Co-Authored-By: Claude Fable 5 --- docs/references/vcs/create-origin-installation.md | 1 - .../Platform/Modules/VCS/Http/Origin/Authorize/Get.php | 4 +++- 2 files changed, 3 insertions(+), 2 deletions(-) delete mode 100644 docs/references/vcs/create-origin-installation.md diff --git a/docs/references/vcs/create-origin-installation.md b/docs/references/vcs/create-origin-installation.md deleted file mode 100644 index 264763aae1..0000000000 --- a/docs/references/vcs/create-origin-installation.md +++ /dev/null @@ -1 +0,0 @@ -Begin Appwrite's Origin app installation to set up version control integration. This endpoint responds with a redirect URL to the Origin app's installation page on Cursor. The Origin app must be configured in your environment for this endpoint to work. diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php index 1df76d5481..ec491add54 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php @@ -53,7 +53,9 @@ class Get extends Action namespace: 'vcs', group: 'installations', name: 'createOriginInstallation', - description: '/docs/references/vcs/create-origin-installation.md', + description: << Date: Wed, 19 Aug 2026 15:41:38 +0200 Subject: [PATCH 48/53] revert: keep the build-status catch as main has it Co-Authored-By: Claude Fable 5 --- src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php b/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php index 6bf69c4aa0..bd40a7aa03 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Jobs.php @@ -20,7 +20,6 @@ use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Bus\Bus; use Utopia\Cache\Cache; -use Utopia\Console; use Utopia\Database\Database; use Utopia\Database\DateTime; use Utopia\Database\Document; @@ -524,11 +523,8 @@ class Jobs extends Action $dbForPlatform, $platform, ); - } catch (\Throwable $error) { - // Best-effort — never fails the build. But say what was lost: a - // swallowed failure here leaves the provider's check and comment - // frozen at their last state with nothing to debug from. - Console::warning('Failed to report build status to VCS provider for deployment ' . $deployment->getId() . ': ' . $error->getMessage()); + } catch (\Throwable) { + // Best-effort — never fails the build. } } From bf77c10878c381905f78c3c001079107dfd439a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:41:53 +0200 Subject: [PATCH 49/53] fix: request repository:metadata:read explicitly The install scopes relied on Origin granting metadata reads implicitly; listing every scope the integration touches keeps the grant explicit. Co-Authored-By: Claude Fable 5 --- .../Platform/Modules/VCS/Http/Origin/Authorize/Get.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php index ec491add54..8b7020c8c4 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php @@ -20,12 +20,13 @@ class Get extends Action use HTTP; /** - * Everything the integration touches: cloning sources, pushing templates, - * deploying from pull requests, commenting on them, and reporting build - * checks. repository:metadata:read is granted implicitly. + * Everything the integration touches: reading repository metadata, + * cloning sources, pushing templates, deploying from pull requests, + * commenting on them, and reporting build checks. */ public const SCOPES = [ 'repository:contents:read', + 'repository:metadata:read', 'repository:contents:write', 'repository:pull_requests:read', 'repository:pull_requests:write', From d1cc63b39057bbcbb83499da3ef1ac790cc0c3c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 15:51:09 +0200 Subject: [PATCH 50/53] refactor: fetch Origin signing keys through Utopia\Fetch Raw curl gives way to the Fetch client the rest of the codebase uses for outgoing requests, keeping the 15-second timeout, the non-200 guard, and the warn-don't-fail error handling. Co-Authored-By: Claude Fable 5 --- .../Modules/VCS/Http/Origin/Events/Create.php | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index f71cf947bf..ced2605ecb 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -17,6 +17,7 @@ use Utopia\Database\Exception\Duplicate; use Utopia\Database\Query; use Utopia\Database\Validator\Authorization; use Utopia\DSN\DSN; +use Utopia\Fetch\Client as FetchClient; use Utopia\Platform\Scope\HTTP; use Utopia\Span\Span; use Utopia\System\System; @@ -155,13 +156,11 @@ class Create extends Action $keys = []; try { - $ch = \curl_init('https://api.cursor.com/v1/origin/keys'); - \curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); - \curl_setopt($ch, CURLOPT_TIMEOUT, 15); - $body = \curl_exec($ch); - \curl_close($ch); + $client = new FetchClient(); + $client->setTimeout(15000); + $response = $client->fetch('https://api.cursor.com/v1/origin/keys', FetchClient::METHOD_GET); - $jwks = \is_string($body) ? \json_decode($body, true) : null; + $jwks = $response->getStatusCode() === 200 ? $response->json() : null; foreach (\is_array($jwks['keys'] ?? null) ? $jwks['keys'] : [] as $key) { if (($key['kty'] ?? '') === 'OKP' && ($key['crv'] ?? '') === 'Ed25519' && !empty($key['x'])) { $keys[] = \strval($key['x']); From 5aee65e6d111075db963d51a2e08b6b04a1879c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 16:04:09 +0200 Subject: [PATCH 51/53] refactor: verify Origin installs through the adapter utopia-php/vcs 5.2.2 owns the install handshake, so the OAuth2-shaped Cursor client - Origin has no OAuth2 - goes away: Authorize builds the install URL with the adapter's getInstallUrl(), the callback verifies receipts with verifyReceipt(), and the events endpoint reads signing keys from getSigningKeys() instead of fetching the JWKS by hand. The worker-lifetime key cache stays, since the adapter memoizes only per instance. Co-Authored-By: Claude Fable 5 --- app/config/vcs.php | 5 +- composer.lock | 12 +- src/Appwrite/Auth/OAuth2/Cursor.php | 333 ------------------ .../Modules/VCS/Http/Origin/Authorize/Get.php | 17 +- .../Modules/VCS/Http/Origin/Callback/Get.php | 11 +- .../Modules/VCS/Http/Origin/Events/Create.php | 24 +- 6 files changed, 28 insertions(+), 374 deletions(-) delete mode 100644 src/Appwrite/Auth/OAuth2/Cursor.php diff --git a/app/config/vcs.php b/app/config/vcs.php index 49f6d3b57e..f21d54c803 100644 --- a/app/config/vcs.php +++ b/app/config/vcs.php @@ -66,9 +66,8 @@ return [ 'origin' => [ 'adapter' => Origin::class, // No 'oauth2': Origin has no OAuth2 user flow. Installs are approved - // on Cursor and confirmed by a signed receipt, and the dedicated - // Origin endpoints construct their own Auth\OAuth2\Cursor for that - // handshake. + // on Cursor and confirmed by a signed receipt, a handshake the + // adapter itself owns (getInstallUrl / verifyReceipt). 'variables' => [ // Factory::fromInstallation() reads appId + privateKey; Origin's // app id doubles as its client id. diff --git a/composer.lock b/composer.lock index fd8de8542f..2ab68f778c 100644 --- a/composer.lock +++ b/composer.lock @@ -5068,16 +5068,16 @@ }, { "name": "utopia-php/vcs", - "version": "5.2.1", + "version": "5.2.2", "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "ee3928969d6c654fad44fad7f38cc96383b031fa" + "reference": "758eb3ab3c32a607b5aca78b1c9bae4ab1ba9b6e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/ee3928969d6c654fad44fad7f38cc96383b031fa", - "reference": "ee3928969d6c654fad44fad7f38cc96383b031fa", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/758eb3ab3c32a607b5aca78b1c9bae4ab1ba9b6e", + "reference": "758eb3ab3c32a607b5aca78b1c9bae4ab1ba9b6e", "shasum": "" }, "require": { @@ -5128,10 +5128,10 @@ "vcs" ], "support": { - "source": "https://github.com/utopia-php/vcs/tree/5.2.1", + "source": "https://github.com/utopia-php/vcs/tree/5.2.2", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-19T12:49:54+00:00" + "time": "2026-08-19T14:01:44+00:00" }, { "name": "utopia-php/websocket", diff --git a/src/Appwrite/Auth/OAuth2/Cursor.php b/src/Appwrite/Auth/OAuth2/Cursor.php deleted file mode 100644 index 53b2232ad3..0000000000 --- a/src/Appwrite/Auth/OAuth2/Cursor.php +++ /dev/null @@ -1,333 +0,0 @@ - $this->appID, - ]; - - if (empty($this->getScopes())) { - // Without an explicit scope list the install page rejects the - // request ("requested_scopes requires at least one scope") unless - // told to read the scopes from the app's registered metadata. - $params['source'] = 'app-metadata'; - } else { - $params['scope'] = \implode(' ', $this->getScopes()); - } - - // The callback must exactly match a redirect URI registered on the - // app; Cursor echoes state back as the receipt's `state` claim. - if (!empty($this->callback)) { - $params['redirect_uri'] = $this->callback; - } - - if (!empty($this->state)) { - $params['state'] = \json_encode($this->state); - } - - // The Origin console still lives under the /codebase path on cursor.com. - return 'https://cursor.com/codebase/apps/install?' . \http_build_query($params); - } - - /** - * Verifies an installation receipt JWT against Cursor's JWKS and returns - * its claims. The `sub` claim is the installation ID, `state` echoes the - * state given to the install URL, and `namespace_id` is the workspace. - * - * @return array - * @throws Exception - */ - public function verifyReceipt(string $receipt): array - { - $segments = \explode('.', $receipt); - - if (\count($segments) !== 3) { - throw new Exception('Installation receipt is not a JWT'); - } - - [$headerSegment, $claimsSegment, $signatureSegment] = $segments; - - $header = \json_decode($this->base64UrlDecode($headerSegment), true); - $claims = \json_decode($this->base64UrlDecode($claimsSegment), true); - $signature = $this->base64UrlDecode($signatureSegment); - - if (!\is_array($header) || !\is_array($claims)) { - throw new Exception('Installation receipt is malformed'); - } - - if (($header['alg'] ?? '') !== 'EdDSA') { - throw new Exception('Installation receipt has an unexpected algorithm'); - } - - // Receipts are documented to carry this media type; tolerate its - // absence, but never another Cursor-signed token kind in its place. - if (isset($header['typ']) && $header['typ'] !== 'origin-installation-receipt+jwt') { - throw new Exception('Installation receipt has an unexpected type'); - } - - $key = $this->getPublicKey($header['kid'] ?? ''); - - if ( - \strlen($signature) !== SODIUM_CRYPTO_SIGN_BYTES - || !\sodium_crypto_sign_verify_detached($signature, $headerSegment . '.' . $claimsSegment, $key) - ) { - throw new Exception('Installation receipt signature is invalid'); - } - - if (($claims['iss'] ?? '') !== $this->endpoint) { - throw new Exception('Installation receipt issuer is invalid'); - } - - if (($claims['aud'] ?? '') !== $this->appID) { - throw new Exception('Installation receipt audience does not match the configured client ID'); - } - - $now = \time(); - $leeway = 60; - - // Receipts are short-lived, single-use artifacts (about a five-minute - // window per Cursor's verification rules). - if (isset($claims['exp']) && $now >= (int)$claims['exp'] + $leeway) { - throw new Exception('Installation receipt has expired'); - } - - if (isset($claims['nbf']) && $now < (int)$claims['nbf'] - $leeway) { - throw new Exception('Installation receipt is not yet valid'); - } - - if (isset($claims['iat']) && $now < (int)$claims['iat'] - $leeway) { - throw new Exception('Installation receipt is issued in the future'); - } - - if (empty($claims['sub'])) { - throw new Exception('Installation receipt is missing the installation ID'); - } - - return $claims; - } - - /** - * App JWT authenticating this app to Cursor's API, signed with the app's - * Ed25519 private key. Used as a Bearer token for app-level endpoints, - * most importantly minting installation access tokens. - */ - public function getAppJWT(): string - { - $now = \time(); - - $headerSegment = $this->base64UrlEncode(\json_encode([ - 'alg' => 'EdDSA', - 'kid' => $this->appID, - 'typ' => 'JWT', - ])); - - $claimsSegment = $this->base64UrlEncode(\json_encode([ - 'iss' => $this->appID, - 'aud' => 'origin-apps', - 'iat' => $now, - 'exp' => $now + 300, - ])); - - $signature = \sodium_crypto_sign_detached($headerSegment . '.' . $claimsSegment, $this->getSigningKey()); - - return $headerSegment . '.' . $claimsSegment . '.' . $this->base64UrlEncode($signature); - } - - /** - * There is no authorization-code exchange: the "code" is the installation - * ID from the receipt's `sub` claim, exchanged for a short-lived (at most - * 15 minutes) installation access token. An empty or omitted scope list - * inherits the full installation grant. - * - * @param string $code - * - * @return array - */ - protected function getTokens(string $code): array - { - if (empty($this->tokens)) { - $payload = empty($this->getScopes()) - ? '{}' - : \json_encode(['scopes' => $this->getScopes()]); - - $response = \json_decode($this->request( - 'POST', - $this->endpoint . '/app/installations/' . \urlencode($code) . '/access_tokens', - [ - 'Authorization: Bearer ' . $this->getAppJWT(), - 'Content-Type: application/json', - ], - $payload - ), true); - - $this->tokens = [ - 'access_token' => $response['token'] ?? '', - 'expires_in' => isset($response['expiresAt']) - ? \max(0, (int)\strtotime($response['expiresAt']) - \time()) - : 0, - ]; - } - - return $this->tokens; - } - - /** - * Installation tokens cannot be refreshed -- a new one is minted from the - * installation ID with the app JWT. - * - * @param string $refreshToken - * - * @return array - */ - public function refreshTokens(string $refreshToken): array - { - $this->tokens = []; - - return $this->getTokens($refreshToken); - } - - /** - * Cursor Origin apps act as an installation, never as a user, so there is - * no user identity behind an access token. - */ - public function getUserID(string $accessToken): string - { - return ''; - } - - public function getUserEmail(string $accessToken): string - { - return ''; - } - - public function isEmailVerified(string $accessToken): bool - { - return false; - } - - public function getUserName(string $accessToken): string - { - return ''; - } - - /** - * Ed25519 public key for a JWKS key ID. - * - * @throws Exception - */ - protected function getPublicKey(string $kid): string - { - if (empty($this->jwks)) { - $this->jwks = \json_decode($this->request('GET', $this->endpoint . '/keys'), true)['keys'] ?? []; - } - - foreach ($this->jwks as $key) { - if ( - ($key['kid'] ?? '') === $kid - && ($key['kty'] ?? '') === 'OKP' - && ($key['crv'] ?? '') === 'Ed25519' - ) { - $publicKey = $this->base64UrlDecode($key['x'] ?? ''); - - if (\strlen($publicKey) === SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) { - return $publicKey; - } - } - } - - throw new Exception('Installation receipt is signed with an unknown key'); - } - - /** - * Ed25519 secret key derived from the PKCS#8 PEM in the secret's - * `privateKey` field. - * - * @throws Exception - */ - protected function getSigningKey(): string - { - $secret = \json_decode($this->appSecret, true); - $pem = \is_array($secret) ? ($secret['privateKey'] ?? '') : ''; - - if (empty($pem) || !\is_string($pem)) { - throw new Exception('Private key is not configured'); - } - - // Keys configured through environment variables carry literal \n - // sequences instead of newlines. - $pem = \str_replace(['\n', '-----BEGIN PRIVATE KEY-----', '-----END PRIVATE KEY-----'], '', $pem); - $der = \base64_decode(\preg_replace('/\s+/', '', $pem) ?? '', true); - - // RFC 8410 PKCS#8 wraps the 32-byte Ed25519 seed in a nested octet - // string tagged 0x04 0x22 0x04 0x20. - $offset = \is_string($der) ? \strpos($der, "\x04\x22\x04\x20") : false; - - if ($offset === false || \strlen($der) < $offset + 4 + SODIUM_CRYPTO_SIGN_SEEDBYTES) { - throw new Exception('Private key is not a PKCS#8 Ed25519 key'); - } - - $seed = \substr($der, $offset + 4, SODIUM_CRYPTO_SIGN_SEEDBYTES); - - return \sodium_crypto_sign_secretkey(\sodium_crypto_sign_seed_keypair($seed)); - } - - protected function base64UrlEncode(string $data): string - { - return \rtrim(\strtr(\base64_encode($data), '+/', '-_'), '='); - } - - protected function base64UrlDecode(string $data): string - { - $remainder = \strlen($data) % 4; - if ($remainder > 0) { - $data .= \str_repeat('=', 4 - $remainder); - } - - return (string)\base64_decode(\strtr($data, '-_', '+/'), true); - } -} diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php index 8b7020c8c4..58c12103ac 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Authorize/Get.php @@ -2,7 +2,6 @@ namespace Appwrite\Platform\Modules\VCS\Http\Origin\Authorize; -use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Extend\Exception; use Appwrite\Platform\Action; use Appwrite\SDK\AuthType; @@ -11,6 +10,7 @@ use Appwrite\SDK\Method; use Appwrite\SDK\MethodType; use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; +use Appwrite\Vcs\Factory as VcsFactory; use Utopia\Database\Document; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; @@ -75,6 +75,7 @@ class Get extends Action ->inject('project') ->inject('platform') ->inject('vcsConfigured') + ->inject('vcsFactory') ->callback($this->action(...)); } @@ -85,6 +86,7 @@ class Get extends Action Document $project, array $platform, callable $vcsConfigured, + VcsFactory $vcsFactory, ) { if (!$vcsConfigured('origin')) { throw new Exception(Exception::GENERAL_SERVER_ERROR, 'This endpoint is not implemented on this server. Please configure VCS (Version Control System) variables in .env file.'); @@ -104,19 +106,18 @@ class Get extends Action $protocol = System::getEnv('_APP_OPTIONS_FORCE_HTTPS') === 'disabled' ? 'http' : 'https'; $callback = $protocol . '://' . ($platform['consoleHostname'] ?? '') . '/v1/vcs/origin/callback'; - // The Cursor adapter expects its secret as a JSON object; starting an - // install only needs the app ID, so the key may be left out here. - $oauth2 = new OAuth2Cursor( + /** @var \Utopia\VCS\Adapter\Git\Origin $vcs */ + $vcs = $vcsFactory->fromProvider('origin'); + $installUrl = $vcs->getInstallUrl( System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), - \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), + self::SCOPES, $callback, - $state, - self::SCOPES + \json_encode($state) ?: '' ); $response ->addHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0') ->addHeader('Pragma', 'no-cache') - ->redirect($oauth2->getLoginURL()); + ->redirect($installUrl); } } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php index 17ae23e0eb..6c51fa124e 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Callback/Get.php @@ -2,7 +2,6 @@ namespace Appwrite\Platform\Modules\VCS\Http\Origin\Callback; -use Appwrite\Auth\OAuth2\Cursor as OAuth2Cursor; use Appwrite\Extend\Exception; use Appwrite\Platform\Permission as AppwritePermission; use Appwrite\Utopia\Response; @@ -62,15 +61,11 @@ class Get extends Action // Authenticate the callback before trusting anything else on it: the // endpoint is public and Origin performs no token exchange, so the // EdDSA-signed receipt is the only proof the request came from Cursor. - // The Cursor adapter expects its secret as a JSON object. - $oauth2 = new OAuth2Cursor( - System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', ''), - \json_encode(['privateKey' => System::getEnv('_APP_VCS_ORIGIN_PRIVATE_KEY', '')]), - '' - ); + /** @var \Utopia\VCS\Adapter\Git\Origin $vcs */ + $vcs = $vcsFactory->fromProvider('origin'); try { - $receiptClaims = $oauth2->verifyReceipt($installationReceipt); + $receiptClaims = $vcs->verifyReceipt($installationReceipt, System::getEnv('_APP_VCS_ORIGIN_CLIENT_ID', '')); } catch (\Throwable $e) { throw new Exception(Exception::GENERAL_ARGUMENT_INVALID, 'Could not verify the Origin installation receipt. Please restart the installation from the Appwrite Console.'); } diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php index ced2605ecb..0c9b096e99 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Origin/Events/Create.php @@ -17,7 +17,6 @@ use Utopia\Database\Exception\Duplicate; use Utopia\Database\Query; use Utopia\Database\Validator\Authorization; use Utopia\DSN\DSN; -use Utopia\Fetch\Client as FetchClient; use Utopia\Platform\Scope\HTTP; use Utopia\Span\Span; use Utopia\System\System; @@ -72,6 +71,7 @@ class Create extends Action callable $deploymentsFactory, array $platform ) { + /** @var Origin $vcs */ $vcs = $vcsFactory->fromProvider('origin'); $event = $request->getHeaderLine($vcs->getEventHeaderName(), ''); @@ -89,7 +89,7 @@ class Create extends Action if (!empty($deliveryId) && \ctype_digit($timestamp) && \abs(\time() - (int) $timestamp) <= 300) { $signedContent = $deliveryId . '.' . $timestamp . '.' . $payload; - foreach ($this->signingKeys() as $publicKey) { + foreach ($this->signingKeys($vcs) as $publicKey) { if ($vcs->validateWebhookEvent($signedContent, $signature, $publicKey)) { $valid = true; break; @@ -98,7 +98,7 @@ class Create extends Action // The key set may have rotated since it was cached. if (!$valid) { - foreach ($this->signingKeys(refresh: true) as $publicKey) { + foreach ($this->signingKeys($vcs, refresh: true) as $publicKey) { if ($vcs->validateWebhookEvent($signedContent, $signature, $publicKey)) { $valid = true; break; @@ -142,12 +142,13 @@ class Create extends Action } /** - * Origin's active Ed25519 signing keys as base64url raw key material, the - * shape the adapter's validateWebhookEvent() accepts. + * Origin's active signing keys, from the adapter, cached for the worker's + * lifetime - the adapter memoizes only per instance, and a new adapter is + * built for every delivery. * * @return array */ - protected function signingKeys(bool $refresh = false): array + protected function signingKeys(Origin $vcs, bool $refresh = false): array { if (!$refresh && self::$signingKeys !== null) { return self::$signingKeys; @@ -156,16 +157,7 @@ class Create extends Action $keys = []; try { - $client = new FetchClient(); - $client->setTimeout(15000); - $response = $client->fetch('https://api.cursor.com/v1/origin/keys', FetchClient::METHOD_GET); - - $jwks = $response->getStatusCode() === 200 ? $response->json() : null; - foreach (\is_array($jwks['keys'] ?? null) ? $jwks['keys'] : [] as $key) { - if (($key['kty'] ?? '') === 'OKP' && ($key['crv'] ?? '') === 'Ed25519' && !empty($key['x'])) { - $keys[] = \strval($key['x']); - } - } + $keys = $vcs->getSigningKeys($refresh); } catch (\Throwable $e) { Console::warning('Failed to fetch Origin signing keys: ' . $e->getMessage()); } From 27d92edd34150ff3bbf4c65014505cebb13c65fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 16:17:55 +0200 Subject: [PATCH 52/53] Upgrade orchestrator to support clone artifact for cursor --- docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index aa7ca310a4..abb56e3c21 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1506,7 +1506,7 @@ services: options: max-file: "5" max-size: 10m - image: ghcr.io/open-runtimes/orchestrator/jobs-service:0.18.0 + image: ghcr.io/open-runtimes/orchestrator/jobs-service:1.3.0 restart: unless-stopped user: root networks: From a746d26d41d7c50d4610cf6940bb840173f34a40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Ba=C4=8Do?= Date: Wed, 19 Aug 2026 16:21:21 +0200 Subject: [PATCH 53/53] test: a VCS registry entry owns an OAuth2 builder only when it has a flow The registry test required a callable builder on every provider, an invariant Origin deliberately broke: it has no OAuth2 user flow, so it registers none. The loop now checks the builder only where one exists, and a dedicated test pins Origin's absence - oauth2FromProvider('origin') must fail loudly rather than hand out a half-configured client. Co-Authored-By: Claude Fable 5 --- tests/unit/Vcs/FactoryTest.php | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/tests/unit/Vcs/FactoryTest.php b/tests/unit/Vcs/FactoryTest.php index 9c758593bd..671aec8ff9 100644 --- a/tests/unit/Vcs/FactoryTest.php +++ b/tests/unit/Vcs/FactoryTest.php @@ -31,7 +31,11 @@ final class FactoryTest extends TestCase foreach ($registry as $key => $entry) { $this->assertTrue(\is_subclass_of($entry['adapter'], Git::class), "Adapter for '{$key}' must extend Git"); - $this->assertIsCallable($entry['oauth2'], "OAuth2 builder for '{$key}' must be callable"); + // A provider with an OAuth2 user flow registers a builder; an + // app-only provider (Origin) deliberately registers none. + if (isset($entry['oauth2'])) { + $this->assertIsCallable($entry['oauth2'], "OAuth2 builder for '{$key}' must be callable"); + } $this->assertNotEmpty($entry['variables'], "Variables missing for '{$key}'"); foreach ($entry['variables'] as $name => $variable) { $this->assertStringStartsWith('_APP_VCS_', $variable['envVariable'] ?? '', "Env variable for '{$name}' missing or invalid for '{$key}'"); @@ -39,6 +43,21 @@ final class FactoryTest extends TestCase } } + public function testOriginRegistersNoOAuth2(): void + { + // Origin has no OAuth2 user flow: installs are approved on Cursor and + // confirmed by a signed receipt the adapter verifies itself, so the + // registry deliberately carries no builder and oauth2FromProvider() + // fails loudly instead of handing out a half-configured client. + $registry = Config::getParam('vcs', []); + $this->assertArrayHasKey('origin', $registry); + $this->assertArrayNotHasKey('oauth2', $registry['origin']); + + $factory = new Factory($this->cache(), $registry); + $this->expectException(Exception::class); + $factory->oauth2FromProvider('origin'); + } + public function testOauth2FromProviderUnknownThrows(): void { $factory = new Factory($this->cache(), ['github' => $this->githubEntry()]);