diff --git a/src/Schema/OAuthFlow.php b/src/Schema/OAuthFlow.php index 4f7c0cf..ef3321c 100644 --- a/src/Schema/OAuthFlow.php +++ b/src/Schema/OAuthFlow.php @@ -5,19 +5,24 @@ class OAuthFlow { - private string $authorizationUrl; + private ?string $authorizationUrl; - private string $tokenUrl; + private ?string $tokenUrl; - private string $refreshUrl; + private ?string $refreshUrl; /** @var array */ - private array $scopes = []; + private array $scopes; /** * @param array $scopes */ - public function __construct(string $authorizationUrl, string $tokenUrl, string $refreshUrl, array $scopes) + public function __construct( + ?string $authorizationUrl = null, + ?string $tokenUrl = null, + ?string $refreshUrl = null, + array $scopes = [], + ) { $this->authorizationUrl = $authorizationUrl; $this->tokenUrl = $tokenUrl; @@ -31,9 +36,9 @@ public function __construct(string $authorizationUrl, string $tokenUrl, string $ public static function fromArray(array $data): self { return new self( - $data['authorizationUrl'], - $data['tokenUrl'], - $data['refreshUrl'], + $data['authorizationUrl'] ?? null, + $data['tokenUrl'] ?? null, + $data['refreshUrl'] ?? null, $data['scopes'], ); } @@ -43,40 +48,51 @@ public static function fromArray(array $data): self */ public function toArray(): array { - return [ - 'authorizationUrl' => $this->authorizationUrl, - 'tokenUrl' => $this->tokenUrl, - 'refreshUrl' => $this->refreshUrl, - 'scopes' => $this->scopes, - ]; + $data = []; + + if ($this->authorizationUrl !== null) { + $data['authorizationUrl'] = $this->authorizationUrl; + } + + if ($this->tokenUrl !== null) { + $data['tokenUrl'] = $this->tokenUrl; + } + + if ($this->refreshUrl !== null) { + $data['refreshUrl'] = $this->refreshUrl; + } + + $data['scopes'] = $this->scopes; + + return $data; } - public function getAuthorizationUrl(): string + public function getAuthorizationUrl(): ?string { return $this->authorizationUrl; } - public function setAuthorizationUrl(string $authorizationUrl): void + public function setAuthorizationUrl(?string $authorizationUrl): void { $this->authorizationUrl = $authorizationUrl; } - public function getTokenUrl(): string + public function getTokenUrl(): ?string { return $this->tokenUrl; } - public function setTokenUrl(string $tokenUrl): void + public function setTokenUrl(?string $tokenUrl): void { $this->tokenUrl = $tokenUrl; } - public function getRefreshUrl(): string + public function getRefreshUrl(): ?string { return $this->refreshUrl; } - public function setRefreshUrl(string $refreshUrl): void + public function setRefreshUrl(?string $refreshUrl): void { $this->refreshUrl = $refreshUrl; } diff --git a/src/Schema/SecurityScheme.php b/src/Schema/SecurityScheme.php index 9d82d35..b06a3b5 100644 --- a/src/Schema/SecurityScheme.php +++ b/src/Schema/SecurityScheme.php @@ -31,11 +31,16 @@ class SecurityScheme self::IN_QUERY, ]; + public const FLOW_IMPLICIT = 'implicit'; + public const FLOW_PASSWORD = 'password'; + public const FLOW_CLIENT_CREDENTIALS = 'clientCredentials'; + public const FLOW_AUTHORIZATION_CODE = 'authorizationCode'; + public const FLOWS = [ - 'implicit', - 'password', - 'clientCredentials', - 'authorizationCode', + self::FLOW_IMPLICIT, + self::FLOW_PASSWORD, + self::FLOW_CLIENT_CREDENTIALS, + self::FLOW_AUTHORIZATION_CODE, ]; private string $type; @@ -204,10 +209,6 @@ public function getBearerFormat(): ?string public function setBearerFormat(?string $bearerFormat): void { - if ($this->type === self::TYPE_HTTP && $this->scheme === 'bearer' && $bearerFormat === null) { - throw new InvalidArgumentException('Attribute "bearerFormat" is required for type "http" and scheme "bearer".'); - } - $this->bearerFormat = $bearerFormat; } @@ -229,13 +230,16 @@ public function setFlows(array $flows): void } if ($this->type === self::TYPE_OAUTH2) { - foreach (self::FLOWS as $flow) { - if (!array_key_exists($flow, $flows)) { + foreach ($flows as $flowType => $flow) { + if (!in_array($flowType, self::FLOWS, true)) { throw new InvalidArgumentException(sprintf( - 'Attribute "flows" is missing required key "%s".', - $flow + 'Invalid flow type "%s" given. It must be one of "%s".', + $flowType, + implode(', ', self::FLOWS) )); } + + self::validateFlow($flowType, $flow); } } @@ -256,4 +260,32 @@ public function setOpenIdConnectUrl(?string $openIdConnectUrl): void $this->openIdConnectUrl = $openIdConnectUrl; } + private static function validateFlow(string $flowType, OAuthFlow $flow): void + { + $needsAuthorizationUrl = in_array($flowType, [ + self::FLOW_IMPLICIT, + self::FLOW_AUTHORIZATION_CODE, + ], true); + + if ($needsAuthorizationUrl && $flow->getAuthorizationUrl() === null) { + throw new InvalidArgumentException(sprintf( + 'Attribute "authorizationUrl" is required for flow "%s".', + $flowType + )); + } + + $needsTokenUrl = in_array($flowType, [ + self::FLOW_PASSWORD, + self::FLOW_CLIENT_CREDENTIALS, + self::FLOW_AUTHORIZATION_CODE, + ], true); + + if ($needsTokenUrl && $flow->getTokenUrl() === null) { + throw new InvalidArgumentException(sprintf( + 'Attribute "tokenUrl" is required for flow "%s".', + $flowType + )); + } + } + } diff --git a/tests/Cases/Schema/ExamplesTest.php b/tests/Cases/Schema/ExamplesTest.php index 245a453..9306974 100644 --- a/tests/Cases/Schema/ExamplesTest.php +++ b/tests/Cases/Schema/ExamplesTest.php @@ -95,6 +95,14 @@ public function testRedoclyMuseum(): void self::assertSameDataStructure($rawData, $openApiData); } + public function testOauthFlows(): void + { + $rawData = Yaml::parseFile(__DIR__ . '/examples/oauth-flows-example.yaml'); + $openApi = OpenApi::fromArray($rawData); + $openApiData = $openApi->toArray(); + self::assertSameDataStructure($rawData, $openApiData); + } + /** * @param mixed[] $expected * @param mixed[] $actual diff --git a/tests/Cases/Schema/OAuthFlowTest.php b/tests/Cases/Schema/OAuthFlowTest.php index c220e6f..de83157 100644 --- a/tests/Cases/Schema/OAuthFlowTest.php +++ b/tests/Cases/Schema/OAuthFlowTest.php @@ -36,6 +36,53 @@ public function testRequired(): void Assert::same($expectedData, OAuthFlow::fromArray($realData)->toArray()); } + public function testImplicitFlowWithoutTokenUrl(): void + { + $data = [ + 'authorizationUrl' => 'https://example.com/authorization', + 'scopes' => ['read' => 'Read access'], + ]; + + $flow = OAuthFlow::fromArray($data); + + Assert::same('https://example.com/authorization', $flow->getAuthorizationUrl()); + Assert::null($flow->getTokenUrl()); + Assert::null($flow->getRefreshUrl()); + Assert::same($data, $flow->toArray()); + } + + public function testClientCredentialsFlowWithoutAuthorizationUrl(): void + { + $data = [ + 'tokenUrl' => 'https://example.com/token', + 'scopes' => [], + ]; + + $flow = OAuthFlow::fromArray($data); + + Assert::null($flow->getAuthorizationUrl()); + Assert::same('https://example.com/token', $flow->getTokenUrl()); + Assert::same($data, $flow->toArray()); + } + + /** + * The OpenAPI Specification marks `scopes` as REQUIRED on the OAuth Flow Object (the map MAY + * be empty, but the key MUST be present). fromArray() must not silently manufacture it - a + * missing key has to surface as an error instead of producing an OAuthFlow with scopes = []. + */ + public function testMissingScopesIsNotSilentlyAccepted(): void + { + $data = [ + 'tokenUrl' => 'https://example.com/token', + ]; + + Assert::exception(static function () use ($data): void { + Assert::error(static function () use ($data): void { + OAuthFlow::fromArray($data); + }, E_WARNING, 'Undefined array key "scopes"'); + }, \TypeError::class); + } + } (new OAuthFlowTest())->run(); diff --git a/tests/Cases/Schema/SecuritySchemeTest.php b/tests/Cases/Schema/SecuritySchemeTest.php index 1ce5f93..f8b5919 100644 --- a/tests/Cases/Schema/SecuritySchemeTest.php +++ b/tests/Cases/Schema/SecuritySchemeTest.php @@ -158,13 +158,18 @@ public function testMissingScheme(): void }, InvalidArgumentException::class, 'Attribute "scheme" is required for type "http".'); } - public function testMissingBearerFormat(): void + public function testBearerFormatIsOptional(): void { - Assert::exception(static function (): void { - $securityScheme = new SecurityScheme(SecurityScheme::TYPE_HTTP); - $securityScheme->setScheme('bearer'); - $securityScheme->setBearerFormat(null); - }, InvalidArgumentException::class, 'Attribute "bearerFormat" is required for type "http" and scheme "bearer".'); + $data = [ + 'type' => SecurityScheme::TYPE_HTTP, + 'scheme' => 'bearer', + ]; + + Assert::noError(static function () use ($data): void { + SecurityScheme::fromArray($data); + }); + + Assert::same($data, SecurityScheme::fromArray($data)->toArray()); } public function testMissingFlows(): void @@ -175,19 +180,33 @@ public function testMissingFlows(): void }, InvalidArgumentException::class, 'Attribute "flows" is required for type "oauth2".'); } - public function testMissingFlow(): void + public function testSingleFlowIsAccepted(): void + { + $data = [ + 'type' => SecurityScheme::TYPE_OAUTH2, + 'flows' => [ + 'authorizationCode' => [ + 'authorizationUrl' => 'https://example.com/authorization', + 'tokenUrl' => 'https://example.com/token', + 'scopes' => ['read' => 'Read access'], + ], + ], + ]; + + Assert::same($data, SecurityScheme::fromArray($data)->toArray()); + } + + public function testUnknownFlowTypeIsRejected(): void { Assert::exception(static function (): void { $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); $securityScheme->setFlows([ - 'implicit' => OAuthFlow::fromArray([ + 'telepathy' => OAuthFlow::fromArray([ 'authorizationUrl' => 'https://example.com/authorization', - 'tokenUrl' => 'https://example.com/token', - 'refreshUrl' => 'https://example.com/refresh', - 'scopes' => ['read' => 'Read access', 'write' => 'Write access'], + 'scopes' => [], ]), ]); - }, InvalidArgumentException::class, 'Attribute "flows" is missing required key "password".'); + }, InvalidArgumentException::class, 'Invalid flow type "telepathy" given. It must be one of "implicit, password, clientCredentials, authorizationCode".'); } public function testMissingOpenIdConnectUrl(): void @@ -198,6 +217,52 @@ public function testMissingOpenIdConnectUrl(): void }, InvalidArgumentException::class, 'Attribute "openIdConnectUrl" is required for type "openIdConnect".'); } + public function testImplicitFlowRequiresAuthorizationUrl(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_IMPLICIT => OAuthFlow::fromArray(['scopes' => []]), + ]); + }, InvalidArgumentException::class, 'Attribute "authorizationUrl" is required for flow "implicit".'); + } + + public function testClientCredentialsFlowRequiresTokenUrl(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_CLIENT_CREDENTIALS => OAuthFlow::fromArray(['scopes' => []]), + ]); + }, InvalidArgumentException::class, 'Attribute "tokenUrl" is required for flow "clientCredentials".'); + } + + public function testAuthorizationCodeFlowRequiresBothUrls(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_AUTHORIZATION_CODE => OAuthFlow::fromArray([ + 'authorizationUrl' => 'https://example.com/authorization', + 'scopes' => [], + ]), + ]); + }, InvalidArgumentException::class, 'Attribute "tokenUrl" is required for flow "authorizationCode".'); + } + + public function testRefreshUrlIsNeverRequired(): void + { + Assert::noError(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_PASSWORD => OAuthFlow::fromArray([ + 'tokenUrl' => 'https://example.com/token', + 'scopes' => [], + ]), + ]); + }); + } + } (new SecuritySchemeTest())->run(); diff --git a/tests/Cases/Schema/examples/oauth-flows-example.yaml b/tests/Cases/Schema/examples/oauth-flows-example.yaml new file mode 100644 index 0000000..406bff2 --- /dev/null +++ b/tests/Cases/Schema/examples/oauth-flows-example.yaml @@ -0,0 +1,21 @@ +openapi: 3.1.0 +info: + title: OAuth Flows Example + version: 1.0.0 +paths: {} +components: + securitySchemes: + petstore_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + scopes: + "write:pets": modify pets in your account + "read:pets": read your pets + authorizationCode: + authorizationUrl: https://example.com/api/oauth/dialog + tokenUrl: https://example.com/api/oauth/token + scopes: + "write:pets": modify pets in your account + "read:pets": read your pets