feat: add p/demo/access (administrable contracts)

[moul]

A library designed to streamline the implementation of this prevalent pattern.

Exposes a privileged API (administrable.Set) that can be fully controlled by the calling contract, and an unprivileged API designed to be exported and available to other contract directly.

$ gno doc gno.land/p/demo/access
package access // import "gno.land/p/demo/access"

Package access provides a simple access control library for managing authorized
addresses and controlling resource access.

Features: authorized address management, access verification.

Note: This package is suitable for basic access control in simple use cases.
Consider specialized libraries or frameworks for advanced access control and
permission management.

TYPES

type Set struct {
	// Has unexported fields.
}
    Set is an object containing the configuration and allowing the application
    of filters. It is suited to be used as a contract-side global variable or
    can be embedded in another Go object.

func New() Set
    New returns a Set object initialized with the caller as the unique
    authorized address. It is recommended to use this function in the `init()`
    function of the calling realm.

func NewWithAddress(addr std.Address) Set
    NewWithAddress returns a Set object initialized with the provided address as
    authorized.

func (s *Set) Add(addr std.Address)
    Add adds an address to the list of authorized addresses. It requires the
    caller or prevRealm to be authorized, otherwise, it panics.

func (s *Set) AssertCurrentHasAccess()
    AssertCurrentHasAccess checks whether the std.GetOrigCaller or std.PrevRealm
    is whitelisted as authorized. If not, it panics indicating restricted
    access.

func (s *Set) CurrentHasAccess() bool
    CurrentHasAccess checks if the caller or prevRealm is authorized.

func (s *Set) Del(addr std.Address) (success bool)
    Del removes an address from the list of authorized addresses. It requires
    the caller or prevRealm to be authorized, otherwise, it panics.

func (s *Set) ForceDel(addr std.Address) (success bool)
    ForceDel removes an address from the list of authorized addresses. It won't
    panic if there is only one address. It requires the caller or prevRealm to
    be authorized, otherwise, it panics.

func (s *Set) HasAccess(addr std.Address) bool
    HasAccess checks if the provided address is in the list of authorized ones.

func (s *Set) List() []std.Address
    List returns a slice containing all the authorized addresses.

func (s *Set) ReplaceAll(addr std.Address)
    ReplaceAll removes all existing authorized addresses and replaces them with
    a new one. It requires the caller or prevRealm to be authorized, otherwise,
    it panics.

func (s Set) Unprivileged() UnprivilegedSet
    Unprivileged returns an unprivileged structure that can be securely exposed
    as object.

type UnprivilegedSet struct {
	Set
}

func (u *UnprivilegedSet) Add(addr std.Address)

func (u *UnprivilegedSet) Del(addr std.Address)

func (u *UnprivilegedSet) ForceDel(addr std.Address)

func (u *UnprivilegedSet) ReplaceAll(addr std.Address)

Related with #289

Contributors Checklist

• Added new tests, or not needed, or not feasible
• Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory
• Updated the official documentation or not needed
• No breaking changes were made, or a BREAKING CHANGE: xxx message was included in the description
• Added references to related issues and PRs
• Provided any useful hints for running manual tests

Maintainers Checklist

• Checked that the author followed the guidelines in CONTRIBUTING.md
• Checked the conventional-commit (especially PR title and verb, presence of BREAKING CHANGE: in the body)
• Ensured that this PR is not a significant change or confirmed that the review/consideration process was appropriate for the change

[moul]

Can someone continue this PR, please?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (7339bdc) 55.83% compared to head (57c4a1c) 48.08%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #880      +/-   ##
==========================================
- Coverage   55.83%   48.08%   -7.75%     
==========================================
  Files         435      381      -54     
  Lines       66036    64497    -1539     
==========================================
- Hits        36869    31013    -5856     
- Misses      26292    31004    +4712     
+ Partials     2875     2480     -395     

Flag	Coverage Δ
go-1.21.x	∅ <ø> (∅)
misc	∅ <ø> (∅)
misc-_test.genstd	∅ <ø> (∅)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[thehowl]

Can someone continue this PR, please?

@leohhhn this looks like something you might be interested in working on :)

[leohhhn]

Continued in #2741

[leohhhn]

Superseded by #2741