enhance(api): OAuth bearer token authentication

[Johann150]

What

• Allow OAuth 2.0 Bearer Token Authentication according to RFC 6750 § 2.1 to be used alternatively to the body parameter i.
• Adjust the client to use this new method, also for GET requests.
• Handle authentication errors in the streaming API properly.
• Adjust the generated OpenAPI specification to document GET requests and the new authentication method.
  • Also properly document that authentication is possible for all API endpoints, even if it is not required. Authenticating on such an endpoint may provide more data.

Why

Towards implementing OAuth 2.0 (#8262), but does not solve the issue yet.

Additional info

Using both authentication methods at the same time is not allowed:

Clients MUST NOT use more than one method to transmit the token in each request.
-- https://datatracker.ietf.org/doc/html/rfc6750#section-2

[mei23]

appがGETでBearer認証した時にキャッシュしないために
&& !ctx.headers.authorization && !app とかが必要？

[Johann150]

From my understanding, requests that have an Authorization field are not cacheable. See also RFC 7234 § 3.2 and RFC 7235 § 4.2.

[mei23]

通常キャッシュはしないのはわかるけど、あえてキャッシュ可能とサーバーから返しちゃうのは違う感だわ

[mei23]

まあ、本来ここで考慮しといた方が良かった問題ではあるけどだわ
58e83f8

[mei23]

現状の実装は間違っていないし今の実装を否定するつもりもないけど、
不適切な実装や、不適切なユーザーでの挙動の上書き をある程度考慮してあげた方が親切と思うのだわ。

[mei23]

I found additional specs.

From my understanding, requests that have an Authorization field are not cacheable. See also RFC 7234 § 3.2 and RFC 7235 § 4.2.

This behavior seems to be overridden by the Cache-Control: public directive.
https://datatracker.ietf.org/doc/html/rfc7234#section-3
https://datatracker.ietf.org/doc/html/rfc7234#section-5.2.2.5

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#directives

public
:
Responses for requests with Authorization header fields must not be stored in a shared cache;
however, the public directive will cause such responses to be stored in a shared cache.

So, it seems that if you use the Authorization header, you should not make it public.

[Johann150]

Yes, but this was already the case. (Of course I cannot say if it is still the case.)

For example here, the code first checks that there is no authenticated users before setting public:

misskey/packages/backend/src/server/api/ApiCallService.ts

Lines 73 to 75 in 75888a5

	if (request.method === 'GET' && endpoint.meta.cacheSec && !body?.['i'] && !user) {
	reply.header('Cache-Control', `public, max-age=${endpoint.meta.cacheSec}`);
	}

I think even the check !body?.['i'] is not really necessary too? Because if the token is valid, the check for !user will be equivalent, and if it is not valid, it will always be an error.

[mei23]

Yes, user always exists on successful authentication (even with appToken authentication). So I think you should be fine without !body?.['i'].

[Johann150]

There are many merge conflicts and I do not have time or motivation to refactor to the new code layout.