Represent a chain-agnostic Object Capability (OCAP), created using CAIP-122, as an IPLD object.
In this document we define a way to record the result of CAIP-122 signing operation as an IPLD-based object capability (OCAP). This creates not just an event receipt of an authentication, but also a composable and replay-able authorization receipt for verifiable authorizations, when the message signed contains the appropriate fields. The first CACAO profile was tailored to the ethereum dapps supporting EIP-4361 but roughly equivalent profiles for other wallet/dapp ecosystems are being added over time.
"Sign-in with X" is a way for a user to authenticate into a service, and provide authorization. In essense, it is a signature of a well-formed payload.
We could see this as a stepping point for a rich capability-based authorization system.
In order to do this, we would like to have a standardized IPLD-based representation of the payload and the signature, that together comprise a capability.
We start construction with declaring a container format, that represents a signed payload.
It should contain meta-information, payload and signatures. For reference let's call such container CACAO (for Chain Agnostic CApability Object).
We use IPLD schema language to describe the format.
Reminder, unless a field is marked optional, it is mandatory.
Header uniquely identifies the payload format:
The header type will be caip122 in reference to the CAIP-122 specification for the SIWx data model. In an older version of the specification, the header type was restricted to eip4361 as it was designed to work only with Sign-in with Ethereum. As such, newer implementations MUST be able to deal with both header types appropriately.
The payload structure must be presented as follows:
It is important to note, that issuer here is did:pkh, which includes both blockchain address and blockchain network information.
Also, as per CAIP-122 specificaction,iat, nbf, and exp are encoded as RFC 3339 date-time, which could include milliseconds precision.
The signature in essence is just bytes, but we have to give a hint on how the signature verification should work. The signature verification type is referenced from methods that are listed as possible within the CAIP-122 namespace.
This construction allows a dApp to uniformly request a SIWx signature regardless of the user's account nature.
Signature signing and verification should follow the workflow as specified in the CAIP-122 namespaces. For example, for eip155 chains, we reconstruct the SIWx payload as follows, resulting in a message conformant with EIP-4361:
Signature verification goes according to t in SignatureMeta:
For example,
As a proper IPLD object, it can be deterministically serialized using CBOR into bytes. Performance is almost as fast as vanilla JSON serialization. For transport purposes we propose that a CACAO is passed inside a base64url-serialized CAR file, with root of the CAR file set to a tip of capability chain. Here and now we use CARv1 format, as CARv2 is still being worked on.
We propose, that all the necessary parent CACAOs are passed there as well. This way, even if a referenced CACAO is not yet available over IPFS, both consumer and presenter of CACAO still can access it.
In the previous version of this specification, the header type was restricted to eip4361 as it was designed to work only with Sign-in with Ethereum. Newer implementations should support both header types - eip4361 and caip122.
Below you could find a CACAO, along with its serialized presentation in CAR file.
CACAO:
CACAO Serialized: base64url-encoded CARv1 file with the IPFS block of the CACAO above:
Present version of CAIP-74 updates and clarifies the previous versions:
Copyright and related rights waived via CC0.