Improve documentation for storage implementers

[gonzojive]

Preflight checklist

• I could not find a solution in the existing issues, docs, nor discussions.
• I agree to follow this project's Code of Conduct.
• I have read and am following this repository's Contribution Guidelines.
• This issue affects my Ory Network project.
• I have joined the Ory Community Slack.
• I am signed up to the Ory Security Patch Newsletter.

Describe your problem

I would like to use a key/value storage to back an OAuth2 server. The documentation of the storage interface is sparse, and the interface itself is abstruse. The memory store provided has few comments and seems to implement numerous interfaces, some of which are probably superfluous for my use case.

// Storage defines fosite's minimal storage interface.
type Storage interface {
	ClientManager
}

// ClientManager defines the (persistent) manager interface for clients.
type ClientManager interface {
	// GetClient loads the client by its ID or returns an error
	// if the client does not exist or another error occurred.
	GetClient(ctx context.Context, id string) (Client, error)
	// ClientAssertionJWTValid returns an error if the JTI is
	// known or the DB check failed and nil if the JTI is not known.
	ClientAssertionJWTValid(ctx context.Context, jti string) error
	// SetClientAssertionJWT marks a JTI as known for the given
	// expiry time. Before inserting the new JTI, it will clean
	// up any existing JTIs that have expired as those tokens can
	// not be replayed due to the expiry.
	SetClientAssertionJWT(ctx context.Context, jti string, exp time.Time) error
}

// PARStorage holds information needed to store and retrieve PAR context.
type PARStorage interface {
	// CreatePARSession stores the pushed authorization request context. The requestURI is used to derive the key.
	CreatePARSession(ctx context.Context, requestURI string, request AuthorizeRequester) error
	// GetPARSession gets the push authorization request context. The caller is expected to merge the AuthorizeRequest.
	GetPARSession(ctx context.Context, requestURI string) (AuthorizeRequester, error)
	// DeletePARSession deletes the context.
	DeletePARSession(ctx context.Context, requestURI string) (err error)
}

As a casual oauth2 user:

• At a high level, what is the storage implementation responsible for storing and doing exactly?
• Is "ClientManager" managing the individual users of my application, or does one client correspond to the "client_id" parameter included in the authorization request? In the Google assistant Handle authorization requests docs, the client_id is an id associated with the Google client that is directing authorization requests of users to my application's HTTP endpoint. I may have millions of users and one client_id...
• The JTI acronym is used without defining what it is. JTI could also be defined as a type to make this more readable type JTI string. Same for RequestURI below
• PARStorage
  • Do I need to implement PARStorage? This interface is not really mentioned in the godoc much, and I can't tell how it fits in
  • What is this requestURI parameter? Where does it come from?

Describe your ideal solution

Ability to implement persistent storage without a lot of background research.

Workarounds or alternatives

Library users do more work to understand requirements.

Version

v0.43.0

Additional Context

No response

[github-actions]

Hello contributors!

I am marking this issue as stale as it has not received any engagement from the community or maintainers for a year. That does not imply that the issue has no merit! If you feel strongly about this issue

• open a PR referencing and resolving the issue;
• leave a comment on it and discuss ideas on how you could contribute towards resolving it;
• leave a comment and describe in detail why this issue is critical for your use case;
• open a new issue with updated details and a plan for resolving the issue.

Throughout its lifetime, Ory has received over 10.000 issues and PRs. To sustain that growth, we need to prioritize and focus on issues that are important to the community. A good indication of importance, and thus priority, is activity on a topic.

Unfortunately, burnout has become a topic of concern amongst open-source projects.

It can lead to severe personal and health issues as well as opening catastrophic attack vectors.

The motivation for this automation is to help prioritize issues in the backlog and not ignore, reject, or belittle anyone.

If this issue was marked as stale erroneously you can exempt it by adding the backlog label, assigning someone, or setting a milestone for it.

Thank you for your understanding and to anyone who participated in the conversation! And as written above, please do participate in the conversation if this topic is important to you!

Thank you 🙏✌️