Writing a Social Login Provider

coremio/modules/SocialAuth/Acme/
├── Acme.php          class Acme extends \SocialAuthProvider
├── config.php        meta + status + empty settings keys
├── acme.svg          brand logo, optional (fall back to a bi-* icon)
└── lang/
    ├── en.php
    └── tr.php

// Presentation. ['label' => string, 'icon' => 'bi-*', 'logo' => absolute url (optional)]
abstract public function provider_meta(): array;

// Credential schema for the Settings accordion. See the key table below.
abstract public function configFields(): array;

// The [Test Connection] button. Return true, or throw with a message the operator can act on.
abstract public function testConnection(): bool;

abstract protected function auth_endpoint(): string;    // where the popup sends the user
abstract protected function token_endpoint(): string;   // where the code is exchanged
abstract protected function scopes(): string;           // e.g. 'openid email profile'
abstract protected function jwks_url(): string;         // signature verification keys
abstract protected function issuers(): array;           // accepted `iss` values

// $ctx = ['code' => string, 'redirect_uri' => string, 'nonce' => string]
abstract public function feedback(array $ctx): array;

return [
    // The account link. `name` becomes a user info key, `value` is the encrypted stable id.
    'field_info' => [
        'name'  => "acme_uid",
        'value' => Crypt::encode($sub, Config::get("crypt/user")),
    ],
    // What the account is built from / matched by.
    'data' => [
        'name'         => "Ada",              // given name
        'surname'      => "Lovelace",         // family name
        'email'        => "[email protected]",  // MUST be provider-verified
        'picture'      => "",                 // avatar url, or an empty string
        'provider_uid' => $sub,               // the raw id, unencrypted
    ],
];

<?php
namespace WISECP\Modules\SocialAuth;

use Config;
use Crypt;
use Exception;
use Filter;
use Utility;

class Acme extends \SocialAuthProvider
{
    public function provider_meta(): array
    {
        return [
            'label' => $this->lang["button-label"] ?? "Continue with Acme",
            'icon'  => 'bi-box-arrow-in-right',
            'logo'  => $this->url . 'acme.svg',
        ];
    }

    public function configFields(): array
    {
        return [
            'client_id' => [
                'type'        => 'text',
                'label'       => $this->lang["field-client-id"] ?? "Client ID",
                'required'    => true,
                'placeholder' => "acme-0000-0000",
                'description' => $this->lang["field-client-id-desc"] ?? '',
            ],
            'client_secret' => [
                'type'        => 'password',
                'label'       => $this->lang["field-client-secret"] ?? "Client Secret",
                'required'    => true,
                'description' => $this->lang["field-client-secret-desc"] ?? '',
            ],
        ];
    }

    protected function auth_endpoint(): string  { return "https://id.acme.example/oauth2/authorize"; }
    protected function token_endpoint(): string { return "https://id.acme.example/oauth2/token"; }
    protected function scopes(): string         { return "openid email profile"; }
    protected function jwks_url(): string       { return "https://id.acme.example/.well-known/jwks.json"; }
    protected function issuers(): array         { return ["https://id.acme.example"]; }

    public function testConnection(): bool
    {
        $clientId = $this->client_id();
        if ($clientId === '')
            throw new Exception($this->lang["error-invalid-client-id"] ?? "Please enter a Client ID.");

        // Ask the provider whether this id exists: an unknown one answers invalid_client,
        // a real one answers redirect_uri_mismatch. A format check would pass either way.
        $probe = $this->auth_endpoint() . '?' . http_build_query([
            'client_id'     => $clientId,
            'response_type' => 'code',
            'scope'         => $this->scopes(),
            'redirect_uri'  => $this->callback_url(),
            'state'         => 'wisecp-connectivity-check',
        ]);

        $resp = (string) Utility::HttpRequest($probe, ['timeout' => 8]);
        if ($resp === '')
            throw new Exception($this->lang["error-unreachable"] ?? "Could not reach Acme.");

        if (str_contains($resp, 'invalid_client'))
            throw new Exception($this->lang["error-client-not-found"] ?? "Acme does not recognize this Client ID.");

        return true;
    }

    public function feedback(array $ctx): array
    {
        $code = (string) ($ctx['code'] ?? '');
        if ($code === '') throw new Exception("Missing authorization code.");

        $token   = $this->exchange_code($code, (string) ($ctx['redirect_uri'] ?? ''));
        $payload = $this->verify_id_token((string) $token['id_token'], (string) ($ctx['nonce'] ?? ''));

        $email = (string) ($payload["email"] ?? '');
        if (!$email)
            throw new Exception($this->lang["error-no-email"] ?? "Could not read your email address.");

        // Fail closed: the resolver matches an existing account by email, so an
        // unverified address would let anyone claim someone else's account.
        if (($payload["email_verified"] ?? false) !== true)
            throw new Exception($this->lang["error-email-unverified"] ?? "Acme has not verified this email address.");

        $fullName = trim((string) ($payload["given_name"] ?? '') . ' ' . (string) ($payload["family_name"] ?? ''));
        $smash    = Filter::name_smash(Utility::ucfirst_space(Utility::substr($fullName, 0, 255)));

        $sub = (string) ($payload["sub"] ?? '');
        if ($sub === '') throw new Exception($this->lang["error-no-account"] ?? "Could not identify your Acme account.");

        return [
            'field_info' => [
                'name'  => "acme_uid",
                'value' => Crypt::encode($sub, Config::get("crypt/user")),
            ],
            'data' => [
                'name'         => $smash["first"] ?? '',
                'surname'      => $smash["last"] ?? '',
                'email'        => $email,
                'picture'      => (string) ($payload["picture"] ?? ''),
                'provider_uid' => $sub,
            ],
        ];
    }
}

// classes/Auth.php - handleProviderCallback(), reduced to the part your class touches.
$st = $provider->consume_state($state);            // mode + context + nonce, one shot
if (!$st) return ['status' => 'error', 'message' => "Sign-in could not be completed."];

$result = $provider->feedback([
    'code'         => $code,
    'redirect_uri' => $provider->callback_url(),
    'nonce'        => (string) ($st['nonce'] ?? ''),
]);

// connectProvider() then does, in this order:
//   1. look the account up by field_info (survives an email change),
//   2. fall back to data.email,
//   3. on mode=register and member context only, create the account,
//   4. persist field_info so the next sign-in resolves by step 1.
return Auth::connectProvider('member', 'Acme', $result, (string) ($st['mode'] ?? 'login'));

// controllers/website/sign.php - the login page, and the same call with "register" on sign-up.
$this->addData("social_providers", \Auth::activeProviders("login", "client"));

// The theme then loops the array; each entry is ['meta' => [...], 'button' => '<html>'].