Sundry updates and bugfixes

- Update to 1.0.0
- Fix the issue where the token is written as `str` instead of `bytes`
- Add documentation
- Update `README.md`

Author: davidharcombe

.gitignore

@@ -1,4 +1,5 @@
 .idea/
+.venv/
 .vscode/
 **/local/
 **/logs/

README.md

@@ -15,14 +15,86 @@ This library will store OAuth tokens in any of the following places:
 1. Google Cloud Storage files
 1. A local `json` file
 
-Other storage locations can be added at will simply by forking this library and
-extending the appropriate abstract classes.
+Other storage locations can be added at will simply by extending the
+`AbstractDatastore` class in the same way as the four examples.
 
 
 ## Initial Setup And Installation
 
-## 
+## Enable the APIs on Google Cloud
 
+In order to use the connectors to any of the Google Cloud storage methods
+(Secret Manager, Firestore and Google Cloud Storage) you will have to ensure
+that the relevant APIs have been enabled. Follow the instructions listed in the
+[developer documentation](https://cloud.google.com/apis/docs/getting-started)
+to enable the API you need.
+
+## Ensure the app's service account has acces to the APIs
+
+## Implementation specific
+
+### Secret Manager
+
+Two secrets will need to be manually added to Secret Manager before the library
+can be used. These are the client id and client secret. The easiest way to do
+this is using a small shell script like this:
+
+```
+#!/bin/bash
+
+while [[ $1 == -* ]] ; do
+  case $1 in
+    --project*)
+      IFS="=" read _cmd PROJECT <<< "$1" && [ -z ${PROJECT} ] && shift && PROJECT=$1
+      ;;
+    --client-id*)
+      IFS="=" read _cmd CLIENT_ID <<< "$1" && [ -z ${CLIENT_ID} ] && shift && CLIENT_ID=$1
+      ;;
+    --client-secret*)
+      IFS="=" read _cmd CLIENT_SECRET <<< "$1" && [ -z ${CLIENT_SECRET} ] && shift && CLIENT_SECRET=$1
+      ;;
+    *)
+      usage
+      echo ""
+      echo "Unknown parameter $1."
+      exit
+  esac
+  shift
+done
+
+if [ -z ${CLIENT_ID} ] || [ -z ${CLIENT_SECRET} ] || [ -z ${PROJECT} ]; then
+  echo You must supply CLIENT_ID and CLIENT_SECRET.
+  exit
+fi
+
+gcloud --project ${PROJECT} secrets create client_id --replication-policy=automatic 2>/dev/null
+echo "{ \"client_id\": \"${CLIENT_ID}\" }" | gcloud --project ${PROJECT} secrets versions add client_id --data-file=-
+
+gcloud --project ${PROJECT} secrets create client_secret --replication-policy=automatic 2>/dev/null
+echo "{ \"client_id\": \"${CLIENT_SECRET}\" }" | gcloud --project ${PROJECT} secrets versions add client_secret --data-file=-
+
+```
+
+The library will create any further secrets and versions automatically. It will
+also remove all but the latest secret each time an update occurs. This reduces
+the usage cost of Secret Manager substantially as projects are charged based
+partially on number of _active_ (ie not destroyed) secret versions.
+
+### Firestore
+
+Firestore requires no additional configuration.
+
+### Google Cloud Storage
+
+To use Google Cloud Storage you must have a bucket created in which the user
+token files and project secrets are to be stored and to which the app's service
+account has read/write access. This should then be locked down so that no other
+non-administrators have access.
+
+### Local files
+
+No special configuration is required. This implementation is HIGHLY insecure,
+and is provided simply for testing/development purposes.
 
 ## Examples
 
@@ -54,7 +126,9 @@ key = manager.get_document(encode_key('<token id>'))
 
 All that changes is where the datastore is!
 
-### Storing a token in Secret Manager
+### Storing a token
+
+#### Secret Manager
 
 ```
 from auth.secret_manager import SecretManager
@@ -66,21 +140,20 @@ manager.update_document(id=encode_key('<token_id>'), new_data=<token string>)
 This will implicitly create a `secret` if there was not one already, or simply
 update an existing secret with a new 'live' version of the secret.
 
-### Listing all the available secrets
+### Removing a secret
 
 ```
 from auth.secret_manager import SecretManager
 manager = SecretManager(project='<gcp project name>')
 
-manager.list_documents()
+manager.delete_document(id=encode_key('<token_id>'))
 ```
 
-
-### Removing a secret
+### Listing all the available secrets
 
 ```
 from auth.secret_manager import SecretManager
 manager = SecretManager(project='<gcp project name>')
 
-manager.delete_document(id=encode_key('<token_id>'))
+manager.list_documents()
 ```

auth/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

auth/abstract_datastore.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

auth/credentials.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@
 from datetime import datetime
 import json
 from typing import Any, Dict, Mapping, Type, TypeVar, Union
+from io import BytesIO
 
 import pytz
 from dateutil.relativedelta import relativedelta
@@ -25,13 +26,18 @@
 
 from auth import decorators
 
-from .abstract_datastore import AbstractDatastore
-from .credentials_helpers import encode_key
-from .exceptions import CredentialsError
+from auth.abstract_datastore import AbstractDatastore
+from auth.credentials_helpers import encode_key
+from auth.exceptions import CredentialsError
 
 
 @dataclass
 class ProjectCredentials(object):
+  """ProjectCredentials
+
+  A dataclass to hold the client is and secret to be passed around within the
+  functions.
+  """
   client_id: str
   client_secret: str
 
@@ -69,11 +75,33 @@ def datastore(self) -> AbstractDatastore:
 
   @datastore.setter
   def datastore(self, f: AbstractDatastore) -> None:
+    """datastore setter
+
+    This will always raise an exception. Once the `Credentials` object has been
+    created, the datastore cannot be changed. If you need to move the object
+    from one datastore to another, then create a second `Credentials` object
+    pointing to the new datastore and pass in the OAuth Credentials, either
+    as the OAuth credentials object or as a `Mapping[str, Any]`.
+
+    Args:
+        f (AbstractDatastore): the datastore
+
+    Raises:
+        KeyError: the datastore should be immutable
+    """
     raise KeyError('Datastore can only be set on instantiation.')
 
   @decorators.lazy_property
   def project_credentials(self) -> ProjectCredentials:
-    """The project credentials."""
+    """The project credentials.
+
+    This is lazy-evaluated using the decorator, so the project credentials
+    are only fetched once from the datastore for the life of the object,
+    reducing API calls and thus improving speed and reducing cost.
+
+    Returns:
+        ProjectCredentials: the project client id and secret as a dataclass
+    """
     secrets = None
     if secrets := self.datastore.get_document(id='client_id'):
       secrets |= self.datastore.get_document(id='client_secret')
@@ -92,7 +120,7 @@ def project_credentials(self) -> ProjectCredentials:
 
   @decorators.lazy_property
   def token_details(self) -> Dict[str, Any]:
-    """The users's refresh and access token."""
+    """The users's OAuth token."""
     return self.datastore.get_document(id=encode_key(self._email))
 
   def store_credentials(self,
@@ -111,7 +139,8 @@ def store_credentials(self,
       key = encode_key(self._email)
 
       if isinstance(creds, oauth.Credentials):
-        self.datastore.update_document(id=key, new_data=creds.to_json())
+        self.datastore.update_document(id=key,
+                                       new_data=self._to_dict(creds))
       else:
         self.datastore.update_document(id=key, new_data=creds)
 
@@ -125,23 +154,60 @@ def _refresh_credentials(self, creds: oauth.Credentials) -> None:
     self.store_credentials(creds)
 
   def _to_utc(self, last_date: datetime) -> datetime:
+    """Convert a datetime to UTC
+
+    Args:
+        last_date (datetime): the date to convert
+
+    Returns:
+        datetime: the date in UTC
+    """
     if (last_date.tzinfo is None or
             last_date.tzinfo.utcoffset(last_date) is None):
       last_date = pytz.UTC.localize(last_date)
 
     return last_date
 
-  @property
+  def _to_dict(self, credentials: oauth.Credentials) -> Mapping[str, Any]:
+    """Convert an OAuth token to a dict
+
+    Note the conversion of the expiry date (A `datetime` object) to the Zulu
+    format date string. This is because the primary function of the dict is to
+    be serialized to the `Datastore` and we have to ensure that all fields can
+    be turned to `json` for this purpose. When reinstantiated, the OAuth
+    Credentials object takes care of converting the expiry date back to a
+    `datetime` for us.
+
+    Args:
+        credentials (oauth.Credentials): the OAuth credentials
+
+    Returns:
+        Mapping[str, Any]: the credentials as a `dict[str, Any]`
+    """
+    return {'token': credentials.token,
+            'refresh_token': credentials.refresh_token,
+            'token_uri': credentials.token_uri,
+            'client_id': credentials.client_id,
+            'client_secret': credentials.client_secret,
+            'scopes': credentials.scopes,
+            'default_scopes': credentials.default_scopes,
+            'expiry': credentials.expiry.strftime('%Y-%m-%dT%H:%M:%SZ')}
+
+  @ property
   def credentials(self) -> oauth.Credentials:
     """Fetches the credentials.
 
     Returns:
        (google.oauth2.credentials.Credentials):  the credentials
     """
     expiry = self._to_utc(
-        datetime.now().astimezone(pytz.utc) + relativedelta(minutes=30))
+        datetime.now().astimezone(pytz.utc) + relativedelta(minutes=60))
+
     if token := self.token_details:
-      creds = oauth.Credentials.from_authorized_user_info(json.loads(token))
+      if isinstance(token, str):
+        token = json.loads(token)
+
+      creds = oauth.Credentials.from_authorized_user_info(token)
 
       if creds.expired:
         creds.expiry = expiry
@@ -153,7 +219,7 @@ def credentials(self) -> oauth.Credentials:
 
     return creds
 
-  @property
+  @ property
   def auth_headers(self) -> Dict[str, Any]:
     """Returns authorized http headers.
 

auth/credentials_helpers.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
 
 import base64
 
-from .exceptions import KeyEncodingError
+from auth.exceptions import KeyEncodingError
 
 
 def encode_key(key: str) -> str:
@@ -32,7 +32,7 @@ def encode_key(key: str) -> str:
   """
   try:
     if encoded_key := base64.b64encode(
-      key.encode('utf-8')).decode('utf-8').rstrip('='):
+            key.encode('utf-8')).decode('utf-8').rstrip('='):
       return encoded_key
 
   except:

auth/credentials_helpers_test.py

@@ -1,4 +1,4 @@
-# Copyright 2021 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,8 +16,8 @@
 import unittest
 from unittest import mock
 
-from .credentials_helpers import encode_key
-from .exceptions import KeyEncodingError
+from auth.credentials_helpers import encode_key
+from auth.exceptions import KeyEncodingError
 
 
 class CredentialsHelpersTest(unittest.TestCase):