docs: adds an expires field to the bearer token response (#676)

* docs: adds an expires field to the bearer token response

Where a bearer token is returned to the client for future use, optionally include an `expires` field which indicates the latest time that it will be treated as valid.

The server is free to expire tokens at any time so this field is purely advisory.

Fixes #674

* chore: switch to RFC3339

Author: achingbrain

http/peer-id-auth.md

@@ -2,7 +2,7 @@
 
 | Lifecycle Stage | Maturity      | Status | Latest Revision |
 | --------------- | ------------- | ------ | --------------- |
-| 1A              | Working Draft | Active | r0, 2023-01-23  |
+| 1A              | Working Draft | Active | r1, 2025-05-28  |
 
 Authors: [@MarcoPolo]
 
@@ -172,6 +172,17 @@ protocol operates as follows:
    Authentication-Info: libp2p-PeerID sig="<base64-signature-bytes>" bearer="<base64-encoded-opaque-blob>"
    ```
 
+   The server MAY include an `expires` field which contains the expiry time of
+   the bearer token in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
+   format:
+
+   ```
+   Authentication-Info: libp2p-PeerID sig="<base64-signature-bytes>" bearer="<base64-encoded-opaque-blob>" expires="<RFC-3339-formatted-date-string>"
+   ```
+
+   Note that the `expires` field is only advisory, the server may expire the
+   token at any time.
+
    The `sig` param represents a signature over the parameters:
 
    - `challenge-server`
@@ -255,6 +266,17 @@ The client initiated handshake is as follows
    - The `hostname` parameter.
    - The token creation date (to allow tokens to expire).
 
+   The server MAY include an `expires` field which contains the expiry time of
+   the bearer token in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339)
+   format:
+
+   ```
+   Authentication-Info: libp2p-PeerID bearer="<base64-encoded-opaque-blob>" expires="<RFC-3339-formatted-date-string>"
+   ```
+
+   Note that the `expires` field is only advisory, the server may expire the
+   token at any time.
+
 5. The client SHOULD send the `bearer` token for future Peer ID authenticated
    requests.