wordpress-seo / src / myyoast-client / application / ports / client-registration-interface.php

client-registration-interface.php in Yoast SEO – Advanced SEO with real-time guidance and built-in AI 28.2, at src/myyoast-client/application/ports/client-registration-interface.php

99 lines 3.0 KB

Raw Download Zip

1	<?php
2	// phpcs:disable Yoast.NamingConventions.NamespaceName.TooLong -- Needed in the folder structure.
3
4	namespace Yoast\WP\SEO\MyYoast_Client\Application\Ports;
5
6	use Yoast\WP\SEO\MyYoast_Client\Application\Exceptions\Registration_Failed_Exception;
7	use Yoast\WP\SEO\MyYoast_Client\Domain\Registered_Client;
8
9	/**
10	* Port for the full OAuth client registration lifecycle.
11	*/
12	interface Client_Registration_Interface {
13
14	/**
15	* Ensures the registration's redirect URIs exactly match the given set.
16	*
17	* Performs DCR when not yet registered; when registered with a different set, updates the
18	* registration in place via RFC 7592 (preserving the client_id) rather than re-registering.
19	*
20	* @param string[] $redirect_uris The exact set of OAuth redirect URIs the registration should have.
21	*
22	* @return Registered_Client The client credentials.
23	*
24	* @throws Registration_Failed_Exception If registration fails.
25	*/
26	public function ensure_registered( array $redirect_uris ): Registered_Client;
27
28	/**
29	* Returns the stored registered client, or null if not registered.
30	*
31	* @return Registered_Client\|null
32	*/
33	public function get_registered_client(): ?Registered_Client;
34
35	/**
36	* Reads the current client registration from the server.
37	*
38	* @return array<string, string\|string[]> The registration metadata.
39	*
40	* @throws Registration_Failed_Exception If the read fails.
41	*/
42	public function read_registration(): array;
43
44	/**
45	* Rotates the registration key pair.
46	*
47	* @return Registered_Client The updated credentials.
48	*
49	* @throws Registration_Failed_Exception If the rotation fails.
50	*/
51	public function rotate_registration_keys(): Registered_Client;
52
53	/**
54	* Deletes the client registration from the server and clears local data.
55	*
56	* @return bool True if deleted or already not registered, false on network failure.
57	*/
58	public function deregister(): bool;
59
60	/**
61	* Deletes all local registration data (credentials, key pairs, caches).
62	*
63	* @return void
64	*/
65	public function delete_local_data(): void;
66
67	/**
68	* Rotates the DPoP key pair (local only, no server coordination).
69	*
70	* @return void
71	*/
72	public function rotate_dpop_keys(): void;
73
74	/**
75	* Whether the given redirect URI has completed the OAuth authorization-code flow on this site.
76	*
77	* Per-URI verification state lives on the stored registration. It is pruned to the current
78	* redirect-URI set whenever the registration's redirect URIs change, and reset when the
79	* registration is forgotten (deregister or full local-data wipe).
80	*
81	* @param string $redirect_uri The redirect URI to check.
82	*
83	* @return bool
84	*/
85	public function is_uri_validated( string $redirect_uri ): bool;
86
87	/**
88	* Records that the given redirect URI has completed the authorization-code flow.
89	*
90	* Called by the authorization-code handler on every successful exchange; idempotent and a no-op
91	* when the site is not registered.
92	*
93	* @param string $redirect_uri The redirect URI that completed the auth-code flow.
94	*
95	* @return void
96	*/
97	public function mark_uri_validated( string $redirect_uri ): void;
98	}
99