Discovery

By design, the XYZ protocol minimizes the need for any pre-flight discovery. To start things off, the client only needs to know the transaction endpoint of the server, everything else can be negotiated dynamically. For example, the client indicates all of its supported interaction modes for a given transaction request, and the AS responds to whichever ones from that set that it supports with the appropriate information for that interaction mode.

Even so, the protocol allows for some additional discovery mechanisms.

Capabilities

For managing extensions, the capabilities section of the transaction request allows a client to specify the set of things that it can do:

{
    "capabilities": [
        "foo",
        "bar",
        "extension-B"
    ]
}

The AS responds with the subset of those things that it supports:

{
    "capabilities": [
        "foo",
        "extension-B"
    ]
}

The AS can never add something to the list that the client didn't send. With the example above, even if the AS supports extension-A it cannot put that in the response as that was not indicated by the client as a capability.

Options Discovery

The client can also send an HTTP OPTIONS request to the transaction endpoint to get a JSON document describing the server.

OPTIONS /transaction HTTP/1.1
Host: server.example.com
{
    "capabilities": [
        "foo",
        "extension-A",
        "extension-B"
    ],
    "interact_methods": [
        "callback",
        "redirect",
        "user_code"
    ],
    "key_proofs": [
        "jwsd",
        "mtls",
        "httpsig",
        "dpop",
        "oauthpop",
        "jws"
    ],
    "tx_endpoint": "http://host.docker.internal:9834/api/as/transaction"
}

Clients can use this information to pre-configure an optimized request to the AS, if desired. However, note that this method of discovery is not required to start a transaction.

Also note that presence of a value in the discovery document is not a guarantee that a client can use that feature. An AS is not obligated to allow any particular client or transaction request to use a given feature. For example, a client might be registered with a particular key proofing type and can therefore only use that type, even if the server supports others.