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. {@see \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 {@see \Taproot\IndieAuth\Storage\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	* {@see \Taproot\IndieAuth\Server} adds the following headers to the response returned from `showForm()`:
50	*
51	* ```
52	* Cache-Control: no-store
53	* Pragma: no-cache
54	* X-Frame-Options: DENY
55	* Content-Security-Policy: frame-ancestors 'none'
56	* ```
57	*
58	* These headers prevent the authorization form from being cached or embedded into a malicious webpage.
59	* It may make sense for you to add additional `Content-Security-Policy` values appropriate to your implementation,
60	* for example to prevent the execution of inline or 3rd party scripts.
61	*
62	* @param ServerRequestInterface $request The current request.
63	* @param array $authenticationResult The array returned from the Authentication Handler. Guaranteed to contain a 'me' key, may also contain additional keys e.g. 'profile'.
64	* @param string $formAction The URL which your form MUST submit to. Can also be used as the redirect URL for a logout process.
65	* @param array|Exception|null $clientHApp If available, the microformats-2 structure representing the client app. An instance of Exception if fetching the `client_id` failed.
66	* @return ResponseInterface A response containing the authorization form.
67	*/
68	public function showForm(ServerRequestInterface $request, array $authenticationResult, string $formAction, $clientHAppOrException): ResponseInterface;
69
70	/**
71	* Transform Authorization Code
72	*
73	* This method is called on a successful authorization form submission. The `$code` array
74	* is a partially-constructed authorization code array, which is guaranteed to have the
75	* following keys:
76	*
77	* * `client_id`: the validated `client_id` request parameter
78	* * `redirect_uri`: the validated `redirect_uri` request parameter
79	* * `state`: the `state` request parameter
80	* * `code_challenge`: the `code_challenge` request parameter
81	* * `code_challenge_method`: the `code_challenge_method` request parameter
82	* * `requested_scope`: the value of the `scope` request parameter
83	* * `me`: the value of the `me` key from the authentication result returned from the authentication request handler callback
84	*
85	* It may also have additional keys, which can come from the following locations:
86	*
87	* * All keys from the the authentication request handler callback result which do not clash
88	*   with the keys listed above (with the exception of `me`, which is always present). Usually
89	*   this is a `profile` key, but you may choose to return additional data from the authentication
90	*   callback, which will be present in `$data`.
91	*
92	* This method should add any additional data to the auth code, before it is persisted and
93	* returned to the client app. Typically, this involves setting the `scope` key to be a
94	* valid space-separated scope string of any scopes granted by the user in the form.
95	*
96	* If the form offers additional token configuration, this method should set any relevant
97	* keys in `$code` based on the form data in `$request`.
98	*
99	* @param array $code The base authorization code data, to be added to.
100	* @param ServerRequestInterface $request The current request.
101	* @return array The $code data after making any necessary changes.
102	*/
103	public function transformAuthorizationCode(ServerRequestInterface $request, array $code): array;
104	}