Add Authentication RFD

docs/rfds/auth.mdx

@@ -0,0 +1,151 @@
+---
+title: "AUTHENTICATION"
+---
+
+Author(s): [anna239](https://github.com/anna239)
+
+## Elevator pitch
+
+> What are you proposing to change?
+
+I suggest adding more information about auth methods that agent supports, which will allow clients to draw more appropriate UI.
+
+## Status quo
+
+> How do things work today and what problems does this cause? Why would we change things?
+
+Agents have different ways of authenticating users: env vars with api keys, running a command like `<agent_name> login`, some just open a browser and use oauth.
+[AuthMethod](https://agentclientprotocol.com/protocol/schema#authmethod) does not really tell the client what should be done to authenticate. This means we can't show the user a control for entering key if an aggent support auth through env var.
+
+## What we propose to do about it
+
+> What are you proposing to improve the situation?
+
+We can add different types of AuthMethods, so that clients can show some UI for them. For example, this auth method
+
+```json
+{
+  "id": "123",
+  "name": "OpenAI api key",
+  "description": "Provide your key",
+  "type": "envVar",
+  "varName": "OPEN_AI_KEY"
+}
+```
+
+would allow client to prompt user to enter a key, then client can provide this key to an agent via `OPEN_AI_KEY` env variable.
+
+## Shiny future
+
+> How will things will play out once this feature exists?
+
+It will be easier for end-users to start using an agent from inside the IDE as auth process will be more straightforward
+
+## Implementation details and plan
+
+> Tell me more about your implementation. What is your detailed implementation plan?
+
+I suggest adding following auth types:
+
+1. Env variable
+
+A user can enter a key and a client will pass it to the agent as an env variable
+
+```json
+{
+  "id": "123",
+  "name": "OpenAI api key",
+  "description": "Provide your key",
+  "type": "envVar",
+  "varName": "OPEN_AI_KEY",
+  "link": "OPTIONAL link to a page where user can get their key",
+  "requiresRestart": true // default
+}
+```
+
+2. Start argument
+
+A user can enter a key, and a client will pass it to the agent as a start parameter
+
+```json
+{
+  "id": "123",
+  "name": "OpenAI api key",
+  "description": "Provide your key",
+  "type": "startParam",
+  "paramName": "OPEN_AI_KEY",
+  "link": "OPTIONAL link to a page where user can get their key",
+  "requiresRestart": true // default
+}
+```
+
+3. Agent auth
+
+Same as what there is now – agent handles the auth itself, this should be a default type if no type is provided for backward compatibility
+
+```json
+{
+  "id": "123",
+  "name": "Agent",
+  "description": "Authenticate through agent",
+  "type": "agent",
+  "requiresRestart": false // default, can be changed
+}
+```
+
+4. Terminal auth
+
+What's now done with `terminal-auth` capability and \_meta field, for backward compatibility clients might want to read properties from both \_meta and the object itself.
+This means that the client should run the provided command themselves in the terminal and let user interact with that terminal
+
+```json
+{
+  "id": "123",
+  "name": "Run in terminal",
+  "type": "terminal",
+  "command": "/path/to/command",
+  "args": ["--setup"],
+  "env": { "VAR1": "value1", "VAR2": "value2" },
+  "label": "Setup Label",
+  "requiresRestart": true // default, can be changed
+}
+```
+
+### AuthErrors
+
+It might be useful to include a list of AuthMethod ids to the AUTH_REQUIRED JsonRpc error. Why do we need this if they're already shared during `initialize`:
+All supported auth methods are shared during `initialize`. When user starts a session, they've already selected a model, which can narrow down a list of options.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "error": {
+    "code": -32000,
+    "message": "Authentication required",
+    "authMethods": [
+      {
+        "id": "chatgpt",
+        "name": "Login with ChatGPT",
+        "description": "Use your ChatGPT login with Codex CLI (requires a paid ChatGPT subscription)"
+      }
+    ]
+  }
+}
+```
+
+## Frequently asked questions
+
+> What questions have arisen over the course of authoring this document or during subsequent discussions?
+
+### What alternative approaches did you consider, and why did you settle on this one?
+
+An alternative approach would be to include this information to an agent's declaration making it more static, see [Registry RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/289)
+
+There is also an alternative to adding a separate `elicitation` capability, which is to create a separate auth type for this. Then the client can decide themselves if they support it or not.
+
+## Revision history
+
+<!-- If there have been major updates to this RFD, you can include the git revisions and a summary of the changes. -->
+
+There was a part about elicitations https://github.com/agentclientprotocol/agent-client-protocol/blob/939ef116a1b14016e4e3808b8764237250afa253/docs/rfds/auth.mdx removed it for now, will move to a separate rfd