Merge pull request #12 from llm-agents-php/feature/oauth

OAuth 2.1 Client Registration Implementation

Author: butschster

composer.json

@@ -16,6 +16,7 @@
   ],
   "require": {
     "php": ">=8.3",
+    "ext-openssl": "*",
     "php-mcp/schema": "^1.0",
     "psr/clock": "^1.0",
     "psr/container": "^1.0 || ^2.0",

context.yaml

@@ -72,11 +72,16 @@ documents:
       - type: file
         sourcePaths:
           - src/Transports/HttpServer.php
-          - vendor/react/http/src/HttpServer.php
-          - vendor/react/http/src/Io/MiddlewareRunner.php
-          - vendor/react/http/src/Middleware
+          - src/Transports/HttpServerTransport.php
           - src/Transports/Middleware
 
+  - description: OAuth
+    outputPath: src/oauth.md
+    sources:
+      - type: file
+        sourcePaths:
+          - src/Authentication
+
   - description: Session
     outputPath: src/session.md
     sources:

src/Authentication/AuthInfo.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication;
+
+/**
+ * Information about a validated access token, provided to request handlers.
+ */
+interface AuthInfo
+{
+    /**
+     * The access token.
+     */
+    public function getToken(): string;
+
+    /**
+     * The client ID associated with this token.
+     */
+    public function getClientId(): string;
+
+    /**
+     * Scopes associated with this token.
+     *
+     * @return string[]
+     */
+    public function getScopes(): array;
+
+    /**
+     * When the token expires (in seconds since epoch).
+     */
+    public function getExpiresAt(): ?int;
+
+    /**
+     * The RFC 8707 resource server identifier for which this token is valid.
+     * If set, this MUST match the MCP server's resource identifier (minus hash fragment).
+     */
+    public function getResource(): ?string;
+
+    /**
+     * Additional data associated with the token.
+     * This field should be used for any additional data that needs to be attached to the auth info.
+     *
+     * @return array<string, mixed>
+     */
+    public function getExtra(): array;
+}

src/Authentication/AuthorizationParams.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication;
+
+/**
+ * Parameters for OAuth authorization flow.
+ */
+final readonly class AuthorizationParams
+{
+    /**
+     * @param string[] $scopes
+     */
+    public function __construct(
+        public string $codeChallenge,
+        public string $redirectUri,
+        public ?string $state = null,
+        public array $scopes = [],
+        public ?string $resource = null,
+    ) {}
+}

src/Authentication/Contract/OAuthRegisteredClientsStoreInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication\Contract;
+
+use Mcp\Server\Authentication\Dto\OAuthClientInformation;
+
+/**
+ * Store for registered OAuth clients.
+ */
+interface OAuthRegisteredClientsStoreInterface
+{
+    /**
+     * Get client information by client ID.
+     *
+     * @throws \RuntimeException if client retrieval fails
+     */
+    public function getClient(string $clientId): ?OAuthClientInformation;
+
+    /**
+     * Register a new client (optional - for dynamic registration).
+     *
+     * @throws \RuntimeException if client registration fails
+     */
+    public function registerClient(OAuthClientInformation $client): OAuthClientInformation;
+}

src/Authentication/Contract/OAuthServerProviderInterface.php

@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication\Contract;
+
+use Mcp\Server\Authentication\AuthInfo;
+use Mcp\Server\Authentication\AuthorizationParams;
+use Mcp\Server\Authentication\Dto\OAuthClientInformation;
+use Mcp\Server\Authentication\Dto\OAuthTokenRevocationRequest;
+use Mcp\Server\Authentication\Dto\OAuthTokens;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Implements an end-to-end OAuth server.
+ */
+interface OAuthServerProviderInterface
+{
+    /**
+     * A store used to read information about registered OAuth clients.
+     */
+    public function getClientsStore(): OAuthRegisteredClientsStoreInterface;
+
+    /**
+     * Begins the authorization flow, which can either be implemented by this server itself
+     * or via redirection to a separate authorization server.
+     *
+     * This server must eventually issue a redirect with an authorization response or an
+     * error response to the given redirect URI. Per OAuth 2.1:
+     * - In the successful case, the redirect MUST include the `code` and `state` (if present) query parameters.
+     * - In the error case, the redirect MUST include the `error` query parameter, and MAY include
+     *   an optional `error_description` query parameter.
+     *
+     * @throws \RuntimeException if authorization fails
+     */
+    public function authorize(
+        OAuthClientInformation $client,
+        AuthorizationParams $params,
+        ResponseInterface $response,
+    ): ResponseInterface;
+
+    /**
+     * Returns the `codeChallenge` that was used when the indicated authorization began.
+     *
+     * @throws \RuntimeException if code challenge retrieval fails
+     */
+    public function challengeForAuthorizationCode(
+        OAuthClientInformation $client,
+        string $authorizationCode,
+    ): string;
+
+    /**
+     * Exchanges an authorization code for an access token.
+     *
+     * @throws \RuntimeException if token exchange fails
+     */
+    public function exchangeAuthorizationCode(
+        OAuthClientInformation $client,
+        string $authorizationCode,
+        ?string $codeVerifier = null,
+        ?string $redirectUri = null,
+        ?string $resource = null,
+    ): OAuthTokens;
+
+    /**
+     * Exchanges a refresh token for an access token.
+     *
+     * @param string[] $scopes
+     *
+     * @throws \RuntimeException if token exchange fails
+     */
+    public function exchangeRefreshToken(
+        OAuthClientInformation $client,
+        string $refreshToken,
+        array $scopes = [],
+        ?string $resource = null,
+    ): OAuthTokens;
+
+    /**
+     * Verifies an access token and returns information about it.
+     *
+     * @throws \RuntimeException if token verification fails
+     */
+    public function verifyAccessToken(string $token): AuthInfo;
+
+    /**
+     * Revokes an access or refresh token. If unimplemented, token revocation is not supported (not recommended).
+     *
+     * If the given token is invalid or already revoked, this method should do nothing.
+     *
+     * @throws \RuntimeException if token revocation fails
+     */
+    public function revokeToken(
+        OAuthClientInformation $client,
+        OAuthTokenRevocationRequest $request,
+    ): void;
+
+    /**
+     * Whether to skip local PKCE validation.
+     *
+     * If true, the server will not perform PKCE validation locally and will pass the
+     * code_verifier to the upstream server.
+     *
+     * NOTE: This should only be true if the upstream server is performing the actual PKCE validation.
+     */
+    public function skipLocalPkceValidation(): bool;
+}

src/Authentication/Contract/OAuthTokenVerifierInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication\Contract;
+
+use Mcp\Server\Authentication\AuthInfo;
+
+/**
+ * Slim implementation useful for token verification only.
+ */
+interface OAuthTokenVerifierInterface
+{
+    /**
+     * Verifies an access token and returns information about it.
+     *
+     * @throws \RuntimeException if token verification fails
+     */
+    public function verifyAccessToken(string $token): AuthInfo;
+}

src/Authentication/DefaultAuthInfo.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication;
+
+/**
+ * Default implementation of AuthInfo.
+ */
+final readonly class DefaultAuthInfo implements AuthInfo
+{
+    /**
+     * @param string[] $scopes
+     * @param array<string, mixed> $extra
+     */
+    public function __construct(
+        private string $token,
+        private string $clientId,
+        private array $scopes,
+        private ?int $expiresAt = null,
+        private ?string $resource = null,
+        private array $extra = [],
+    ) {}
+
+    public function getToken(): string
+    {
+        return $this->token;
+    }
+
+    public function getClientId(): string
+    {
+        return $this->clientId;
+    }
+
+    public function getScopes(): array
+    {
+        return $this->scopes;
+    }
+
+    public function getExpiresAt(): ?int
+    {
+        return $this->expiresAt;
+    }
+
+    public function getResource(): ?string
+    {
+        return $this->resource;
+    }
+
+    public function getExtra(): array
+    {
+        return $this->extra;
+    }
+}

src/Authentication/Dto/OAuthClientInformation.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication\Dto;
+
+/**
+ * OAuth client information as used in dynamic registration and client authentication.
+ */
+final readonly class OAuthClientInformation implements \JsonSerializable
+{
+    public function __construct(
+        public string $clientId,
+        public ?string $clientSecret = null,
+        public ?int $clientIdIssuedAt = null,
+        public ?int $clientSecretExpiresAt = null,
+    ) {}
+
+    public function getClientId(): string
+    {
+        return $this->clientId;
+    }
+
+    public function getClientSecret(): ?string
+    {
+        return $this->clientSecret;
+    }
+
+    public function getClientIdIssuedAt(): ?int
+    {
+        return $this->clientIdIssuedAt;
+    }
+
+    public function getClientSecretExpiresAt(): ?int
+    {
+        return $this->clientSecretExpiresAt;
+    }
+
+    public function jsonSerialize(): array
+    {
+        return \array_filter([
+            'client_id' => $this->clientId,
+            'client_secret' => $this->clientSecret,
+            'client_id_issued_at' => $this->clientIdIssuedAt,
+            'client_secret_expires_at' => $this->clientSecretExpiresAt,
+        ], static fn($value) => $value !== null);
+    }
+}

src/Authentication/Dto/OAuthErrorResponse.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mcp\Server\Authentication\Dto;
+
+/**
+ * OAuth error response as defined in RFC 6749 Section 4.1.2.1.
+ */
+final readonly class OAuthErrorResponse implements \JsonSerializable
+{
+    public function __construct(
+        public string $error,
+        public ?string $errorDescription = null,
+        public ?string $errorUri = null,
+    ) {}
+
+    public function jsonSerialize(): array
+    {
+        return \array_filter([
+            'error' => $this->error,
+            'error_description' => $this->errorDescription,
+            'error_uri' => $this->errorUri,
+        ], static fn($value) => $value !== null);
+    }
+}