From fd62b6ec67cb6dc807df9a605d4f12cf1a9b28a0 Mon Sep 17 00:00:00 2001 From: "Prad Nukala (aider)" Date: Mon, 21 Oct 2024 17:00:59 -0400 Subject: [PATCH] feat: Update x/macaroon/README.md with details from protobuf files --- x/macaroon/README.md | 90 ++++++++++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 24 deletions(-) diff --git a/x/macaroon/README.md b/x/macaroon/README.md index 358d781fd..29e37dd56 100644 --- a/x/macaroon/README.md +++ b/x/macaroon/README.md @@ -1,62 +1,104 @@ # `x/macaroon` -The Macaroon module is responsible for providing decentralized access control and service authorization for the Sonr ecosystem. +The Macaroon module is responsible for providing decentralized access control and service authorization for the Sonr ecosystem. It implements macaroon-based authentication and authorization mechanisms. ## Concepts +Macaroons are a type of bearer credential that allow for decentralized delegation, attenuation, and third-party caveats. This module implements the core functionality for creating, validating, and managing macaroons within the Sonr ecosystem. + ## State -Specify and describe structures expected to marshalled into the store, and their keys +The module maintains the following state: -### Account State +### Grant -The Account state includes the user's public key, associated wallets, and other identification details. It is stored using the user's DID as the key. +Represents a permission grant with the following fields: +- `id`: Unique identifier (auto-incremented) +- `controller`: Address of the controller +- `subject`: Subject of the grant +- `origin`: Origin of the grant +- `expiry_height`: Block height at which the grant expires -### Credential State +### Macaroon -The Credential state includes the claims about a subject and is stored using the credential ID as the key. +Represents a macaroon token with the following fields: +- `id`: Unique identifier (auto-incremented) +- `controller`: Address of the controller +- `subject`: Subject of the macaroon +- `origin`: Origin of the macaroon +- `expiry_height`: Block height at which the macaroon expires +- `macaroon`: The actual macaroon token ## State Transitions -Standard state transition operations triggered by hooks, messages, etc. +State transitions occur through the following messages: +- `MsgUpdateParams`: Updates the module parameters +- `MsgIssueMacaroon`: Issues a new macaroon ## Messages -Specify message structure(s) and expected state machine behaviour(s). +### MsgUpdateParams -## Begin Block +Updates the module parameters. Can only be executed by the governance account. -Specify any begin-block operations. +Fields: +- `authority`: Address of the governance account +- `params`: New parameter values -## End Block +### MsgIssueMacaroon -Specify any end-block operations. +Issues a new macaroon for a given controller and origin. -## Hooks +Fields: +- `controller`: Address of the controller +- `origin`: Origin of the request in wildcard form +- `permissions`: Map of permissions +- `token`: Macaroon token to authenticate the operation -Describe available hooks to be called by/from this module. +## Queries + +The module provides the following queries: + +- `Params`: Retrieves the current module parameters +- `RefreshToken`: Refreshes a macaroon token (post-authentication) +- `ValidateToken`: Validates a macaroon token (pre-authentication) + +## Parameters + +The module has the following parameters: + +- `methods`: Defines the available DID methods + - `default`: Default method + - `supported`: List of supported methods +- `scopes`: Defines the set of scopes + - `base`: Base scope + - `supported`: List of supported scopes +- `caveats`: Defines the available caveats + - `supported_first_party`: List of supported first-party caveats + - `supported_third_party`: List of supported third-party caveats +- `transactions`: Defines the allowlist and denylist for transactions + - `allowlist`: List of allowed transactions + - `denylist`: List of denied transactions ## Events -List and describe event tags used. +The module may emit events related to macaroon issuance, validation, and refreshing. (Specific event details to be implemented) ## Client -List and describe CLI commands and gRPC and REST endpoints. - -## Params - -List all module parameters, their types (in JSON) and identitys. +The module provides gRPC endpoints for all queries and message types defined in the protobuf files. ## Future Improvements -Describe future improvements of this module. +- Implement more advanced caveat types +- Add support for third-party caveats +- Enhance macaroon revocation mechanisms +- Implement additional security features and checks ## Tests -Acceptance tests. +(To be implemented: Acceptance tests for the module's functionality) ## Appendix -Supplementary details referenced elsewhere within the spec. -his is a module base generated with [`spawn`](https://github.com/rollchains/spawn). +For more information on macaroons and their implementation, refer to the original macaroon paper: "Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud" by Arnar Birgisson, et al.