Readme content (#22)

Author: chlowell

README.md

@@ -1,14 +1,7 @@
-# Project
+# Microsoft Authentication Library (MSAL) Extensions for Go
 
-> This repo has been populated by an initial template to help get you started. Please
-> make sure to update the content to build a great experience for community-building.
-
-As the maintainer of this project, please make a few updates:
-
-- Improving this README.MD file to provide a great experience
-- Updating SUPPORT.MD with content about this project's support experience
-- Understanding the security reporting process in SECURITY.MD
-- Remove this section from the README
+This repository contains extension modules for [Microsoft Authentication Library (MSAL) for Go](https://github.com/AzureAD/microsoft-authentication-library-for-go):
+  - [github.com/AzureAD/microsoft-authentication-extensions-for-go/cache](https://github.com/AzureAD/microsoft-authentication-extensions-for-go/tree/dev/cache): cross-platform persistent caching for MSAL public clients
 
 ## Contributing
 
@@ -23,11 +16,3 @@ provided by the bot. You will only need to do this once across all repos using o
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
-
-## Trademarks
-
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
-trademarks or logos is subject to and must follow 
-[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
-Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
-Any use of third-party trademarks or logos are subject to those third-party's policies.

cache/README.md

@@ -0,0 +1,33 @@
+# Microsoft Authentication Library (MSAL) Extensions for Go
+
+This module contains a persistent cache for [Microsoft Authentication Library (MSAL) for Go](https://github.com/AzureAD/microsoft-authentication-library-for-go) public client applications such as CLI tools. It isn't recommended for web applications or RPC APIs, in which it can cause scaling and performance problems.
+
+The cache supports encrypted storage on Linux, macOS and Windows. The encryption facility depends on the platform:
+- Linux: [libsecret](https://wiki.gnome.org/Projects/Libsecret) (used as a DBus Secret Service client)
+- macOS: keychain
+- Windows: data protection API (DPAPI)
+
+See the `accessor` package for more details. The `file` package has a plaintext storage provider to use when encryption isn't possible.
+
+> Plaintext storage is dangerous. Bearer tokens are not cryptographically bound to a machine and can be stolen. In particular, the refresh token can be used to get access tokens for many resources.
+> It's important to warn end-users before falling back to plaintext. End-users should ensure they store the tokens in a secure location (e.g. encrypted disk) and must understand they are responsible for their safety.
+
+## Installation
+
+```sh
+go get -u github.com/AzureAD/microsoft-authentication-extensions-for-go/cache
+```
+
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

cache/accessor/linux.go

@@ -115,8 +115,8 @@ type attribute struct {
 
 type option func(*Storage) error
 
-// WithAttribute adds an attribute to the secret schema representing the cache.
-// Storage supports up to 2 attributes.
+// WithAttribute adds an attribute to the schema representing the cache.
+// [Storage] supports up to 2 attributes.
 func WithAttribute(name, value string) option {
 	return func(s *Storage) error {
 		if len(s.attributes) == 2 {
@@ -127,17 +127,17 @@ func WithAttribute(name, value string) option {
 	}
 }
 
-// WithLabel sets a label on the secret schema representing the cache. The default label is "MSALCache".
+// WithLabel sets a label on the schema representing the cache. The default label is "MSALCache".
 func WithLabel(label string) option {
 	return func(s *Storage) error {
 		s.label = label
 		return nil
 	}
 }
 
-// Storage uses libsecret to store data by a DBus Secret Service such as GNOME Keyring or KDE Wallet. The Service must
-// be unlocked before Storage can read or write data to it. Unlocking typically requires user interaction, and some
-// systems may be unable to unlock the Service in a headless environment such as an SSH session.
+// Storage uses libsecret to store data with a DBus Secret Service such as GNOME Keyring or KDE Wallet. The Service
+// must be unlocked before Storage can access it. Unlocking typically requires user interaction, and some systems may
+// be unable to unlock the Service in a headless environment such as an SSH session.
 type Storage struct {
 	// attributes are key/value pairs on the secret schema
 	attributes []attribute

cache/accessor/windows.go

@@ -58,7 +58,7 @@ func (s *Storage) Read(context.Context) ([]byte, error) {
 }
 
 // Write stores data in the file, creating the file if it doesn't exist.
-func (s *Storage) Write(ctx context.Context, data []byte) error {
+func (s *Storage) Write(_ context.Context, data []byte) error {
 	s.m.Lock()
 	defer s.m.Unlock()
 

cache/cache.go

@@ -30,7 +30,7 @@ type locker interface {
 }
 
 // Cache caches authentication data in external storage, using a file lock to coordinate
-// access to it with other processes.
+// access with other processes.
 type Cache struct {
 	// a provides read/write access to storage
 	a accessor.Accessor
@@ -47,7 +47,7 @@ type Cache struct {
 }
 
 // New is the constructor for Cache. "p" is the path to a file used to track when stored
-// data changes. Export will create this file and any directories in its path which don't
+// data changes. [Cache.Export] will create this file and any directories in its path which don't
 // already exist.
 func New(a accessor.Accessor, p string) (*Cache, error) {
 	lock, err := lock.New(p+".lockfile", retryDelay)

cache/example_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See LICENSE in the project root for license information.
+
+package cache_test
+
+import (
+	"github.com/AzureAD/microsoft-authentication-extensions-for-go/cache"
+	"github.com/AzureAD/microsoft-authentication-extensions-for-go/cache/accessor"
+	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/public"
+)
+
+// This example shows how to configure an MSAL public client to store data in a peristent, encrypted cache.
+func Example() {
+	// On Linux and macOS, "s" is an arbitrary name identifying the cache.
+	// On Windows, it's the path to a file in which to store cache data.
+	s := "..."
+	a, err := accessor.New(s)
+	if err != nil {
+		// TODO: handle error
+	}
+	c, err := cache.New(a, s)
+	if err != nil {
+		// TODO: handle error
+	}
+	app, err := public.New("client-id", public.WithCache(c))
+	if err != nil {
+		// TODO: handle error
+	}
+
+	_ = app
+}