├── .gitignore
├── .prettierrc
├── CHANGELOG.md
├── LICENSE
├── README.md
├── images
├── interactive-mode-error.png
├── strict-mode-error.png
└── user-input-secret-prompt.png
├── package-lock.json
├── package.json
├── src
├── .clasp.json
├── SecretService.js
├── appsscript.json
└── package.json
└── tests
├── integration-tests.js
├── mocks
├── PropertiesInstance.js
├── SpreadsheetApp.js
└── Storage.js
└── test.js
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | coverage
3 | .DS_Store
4 | .vscode
--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | {
2 | "printWidth": 100,
3 | "singleQuote": false,
4 | "trailingComma": "es5",
5 | "tabWidth": 4
6 | }
7 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | ## 2024-03-08 - 1.0.0
4 |
5 | - First public release.
6 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright 2024 Dataful.Tech
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # SecretService
2 |
3 | SecretService is a Google Apps Script library that allows to store secrets (passwords, API keys, etc.) safer and provides the following features:
4 |
5 | - Choose a storage for the secrets:
6 | - Any `Properties` instance from your script
7 | - Custom secret storage, like Google Cloud Secret Manager
8 | - Different modes in case of a missing secret:
9 | - Silent: do nothing, return null.
10 | - Strict: throw an error.
11 | - Interactive: prompt the user for a missing secret.
12 |
13 | SecretService is a [Dataful.Tech](https://dataful.tech) project.
14 |
15 | ## Security Note
16 |
17 | Storing secrets in Google Apps Script safely is challenging. The root cause is that other users often have access to the code and can edit it.
18 |
19 | For example, if you have a script attached to a Google Sheets document, any editor of the document will automatically be able to edit the script to display the secrets. The owner of the script will get a notification but it can be easily missed and the damage will be done by then. There are techniques to reduce the surface of the attack, however, they all come with their costs and inconveniences.
20 |
21 | ## Setup
22 |
23 | You can use SecretService in two ways:
24 |
25 | 1. **As a library**: use the library id `164Mv6awN8mIExnFu6ZeXviPSA2GhDVP3grAMfiJCpAkcjcGWaDlNU9K4`.
26 | 2. **Copy the code** from `src/SecretService.js` to your project.
27 |
28 | ## Usage
29 |
30 | Using SecretService is simple: either use library's methods directly or create an instance.
31 |
32 | ### Use Library Directly
33 |
34 | You can use the library directly, without initializing an instance:
35 |
36 | ```js
37 | const config = {
38 | storage: PropertiesService.getUserProperties(),
39 | };
40 |
41 | // Only once: set the secret
42 | // You can skip this step if you use the `interactive` mode
43 | SecretService.setSecret("API_KEY", "very-secret-value", config);
44 |
45 | // 3. Get the secret
46 | SecretService.getSecret("API_KEY", config);
47 |
48 | // Delete specific secrets:
49 | SecretService.deleteSecrets(["API_KEY", "ANOTHER_SECRET"], config);
50 |
51 | // Delete all secrets:
52 | SecretService.deleteAllSecrets(config);
53 | ```
54 |
55 | ### Create an Instance
56 |
57 | To avoid passing configuration on each call, you create an instance:
58 |
59 | ```js
60 | // Initialize with a configuration passing a storage object
61 | const SECRETS = SecretService.init({
62 | storage: PropertiesService.getUserProperties(),
63 | });
64 |
65 | // Only once: set the secret
66 | // You can skip this step if you use the `interactive` mode
67 | SECRETS.setSecret("API_KEY", "very-secret-value");
68 |
69 | // 3. Get the secret
70 | const secretValue = SECRETS.getSecret("API_KEY");
71 |
72 | // Delete specific secrets:
73 | SECRETS.deleteSecrets(["API_KEY", "ANOTHER_SECRET"]);
74 |
75 | // Delete all secrets:
76 | SECRETS.deleteAllSecrets();
77 | ```
78 |
79 | See more examples in the configuration section below.
80 |
81 | ## Configuration
82 |
83 | SecretService accepts four configuration parameters:
84 |
85 | - `storage` (required) - where to store the secrets.
86 | - `prefix` (default: `secret_service_`) - added to the secret's `key` to avoid collisions with other values.
87 | - `mode` - what to do if no secret is found. Options:
88 | - `silent` (default) - do nothing, return null.
89 | - `strict` - throw an error.
90 | - `interactive` - prompt the user to input the secret. Works only in scripts attached to a container (Google Sheet, Doc, Slide, or Form). Requires `scriptContainer`.
91 | - `scriptContainer` - the object referring to the script container app. Required when running in `interactive` mode: `SpreadsheetApp`, `DocumentApp`, `SlidesApp`, `FormApp`.
92 |
93 | Read more on the configuration options below.
94 |
95 | ### Storage
96 |
97 | SecretService supports two types of storages:
98 |
99 | #### Properties Storage
100 |
101 | You can pass to SecretService any Properties storage from your script:
102 |
103 | ```js
104 | const SECRETS = SecretService.init({
105 | storage: PropertiesService.getUserProperties(),
106 | // Alternatively:
107 | // storage: PropertiesService.getScriptProperties()
108 | // storage: PropertiesService.getDocumentProperties()
109 | });
110 | ```
111 |
112 | Generally, `UserProperties` is the safest storage as it is accessible only to the user running the script. Caveat: the user properties of the owner of a Google Sheets document are accessible to anyone via a custom function (why Google, why?).
113 |
114 | #### Google Cloud Secret Manager
115 |
116 | You can use Google Cloud Secret Manager as a storage backend via the [GCSecretManager library](https://github.com/dataful-tech/GCSecretManager):
117 |
118 | ```js
119 | const storage = GCSecretManager.init({project: "project-id"});
120 | const SECRETS = SecretService.init({storage});
121 |
122 | const secretValue = SECRETS.getSecret("API_KEY");
123 | ```
124 |
125 | GCSecretManager does not support destructive operations. It will require extra permissions scopes to access the Secret Manger API. For the details, please refer to the [documentation](https://github.com/dataful-tech/GCSecretManager).
126 |
127 | #### Custom Storage
128 |
129 | You can pass any custom storage for secrets that implements these methods:
130 |
131 | 1. `get(key, config)`
132 | 2. `set(key, value, config)`
133 | 3. `delete(key, config)`
134 | 4. `deleteAll(key, config)`
135 |
136 | `config` is an object passed to `SecretService.init(config)`, merged with a config override of any method.
137 |
138 | The custom storage does not have to implement all methods. For example, if you need only to get the secrets, you can implement only `get(key, config)` method.
139 |
140 | ### Mode
141 |
142 | The mode determines behavior of SecretService when a requested secret is not found.
143 |
144 | #### Silent
145 |
146 | Do nothing if a secret is not found and return `null`. It is the default behavior.
147 |
148 | ```js
149 | const SECRETS = SecretService.init({
150 | storage: PropertiesService.getUserProperties(),
151 | });
152 |
153 | // It will return null
154 | const API_KEY = SECRETS.getSecret("Does not exist");
155 | ```
156 |
157 | #### Strict
158 |
159 | Throw an error, if a secret is not found.
160 |
161 | ```js
162 | const SECRETS = SecretService.init({
163 | storage: PropertiesService.getUserProperties(),
164 | mode: "strict",
165 | });
166 |
167 | // Throws an error
168 | const API_KEY = SECRETS.getSecret("Does not exist");
169 | ```
170 |
171 |
172 |
173 |
191 |
192 |
197 |
198 |