1	<?php declare(strict_types=1);
2
3	namespace Taproot\IndieAuth\Callback;
4
5	use Psr\Http\Message\ServerRequestInterface;
6	use Psr\Http\Message\ResponseInterface;
7
8	/**
9	* Authorization Form Interface
10	*/
11	interface AuthorizationFormInterface {
12	/**
13	* Show Form
14	*
15	* This method is called once the IndieAuth Authorization Endpoint has confirmed that:
16	*
17	* * The current user is authenticated
18	* * The client app (client_id) has been fetched and is valid
19	* * The client app redirect_uri is known to be valid
20	*
21	* It should build an authorization form which the currently logged-in user can use
22	* to choose which scopes (if any) to grant the app.
23	*
24	* Information specific to the IndieAuth authorization request can be found in
25	* `$request->getQueryParams()`. The parameters most likely to be of use to the authorization
26	* form are:
27	*
28	* * `scope`: a space-separated list of scopes which the client app is requesting. May be absent.
29	* * `client_id`: the URL of the client app. Should be shown to the user. This also makes a good “cancel” link.
30	* * `redirect_uri`: the URI which the user will be redirected to on successful authorization.
31	*
32	* The form MUST submit a POST request to `$formAction`, with the `taproot_indieauth_action`
33	* parameter set to `approve`.
34	*
35	* The form MUST additionally include any CSRF tokens required to protect the submission.
36	* Refer to whatever CSRF protection code you’re using (e.g. `\Taproot\IndieAuth\Middleware\DoubleSubmitCookieCsrfMiddleware`)
37	* and make sure to include the required element. This will usually involve getting a
38	* CSRF token with `$request->getAttribute()` and including it in an `<input type="hidden" …/>`.
39	*
40	* The form SHOULD offer the user the opportunity to choose which of the request scopes,
41	* if any, they wish to grant. It should describe what effect each scope grants. If no scopes are
42	* requested, tell the user that the app is only requesting authorization, not access to their data.
43	*
44	* The form MAY offer the user UIs for additional token configuration, e.g. a custom token lifetime.
45	* You may have to refer to the documentation for your instance of `TokenStorageInterface` to ensure
46	* that lifetime configuration works correctly. Any other additional data is not used by the IndieAuth
47	* library, but, if stored on the access token, will be available to your app for use.
48	*
49	* @param ServerRequestInterface $request The current request.
50	* @param array $authenticationResult The array returned from the Authentication Handler. Guaranteed to contain a 'me' key, may also contain additional keys e.g. 'profile'.
51	* @param string $formAction The URL which your form MUST submit to. Can also be used as the redirect URL for a logout process.
52	* @param array|null $clientHApp If available, the microformats-2 structure representing the client app.
53	* @return ResponseInterface A response containing the authorization form.
54	*/
55	public function showForm(ServerRequestInterface $request, array $authenticationResult, string $formAction, ?array $clientHApp): ResponseInterface;
56
57	/**
58	* Transform Authorization Code
59	*
60	* This method is called on a successful authorization form submission. The `$code` array
61	* is a partially-constructed authorization code array, which is guaranteed to have the
62	* following keys:
63	*
64	* * `client_id`: the validated `client_id` request parameter
65	* * `redirect_uri`: the validated `redirect_uri` request parameter
66	* * `state`: the `state` request parameter
67	* * `code_challenge`: the `code_challenge` request parameter
68	* * `code_challenge_method`: the `code_challenge_method` request parameter
69	* * `requested_scope`: the value of the `scope` request parameter
70	* * `me`: the value of the `me` key from the authentication result returned from the authentication request handler callback
71	*
72	* It may also have additional keys, which can come from the following locations:
73	*
74	* * All keys from the the authentication request handler callback result which do not clash
75	*   with the keys listed above (with the exception of `me`, which is always present). Usually
76	*   this is a `profile` key, but you may choose to return additional data from the authentication
77	*   callback, which will be present in `$data`.
78	*
79	* This method should add any additional data to the auth code, before it is persisted and
80	* returned to the client app. Typically, this involves setting the `scope` key to be a
81	* valid space-separated scope string of any scopes granted by the user in the form.
82	*
83	* If the form offers additional token configuration, this method should set any relevant
84	* keys in `$code` based on the form data in `$request`.
85	*
86	* @param array $code The base authorization code data, to be added to.
87	* @param ServerRequestInterface $request The current request.
88	* @return array The $code data after making any necessary changes.
89	*/
90	public function transformAuthorizationCode(ServerRequestInterface $request, array $code): array;
91	}