1 | ;
|
2 | // Copyright 2019 Google LLC
|
3 | //
|
4 | // Licensed under the Apache License, Version 2.0 (the "License");
|
5 | // you may not use this file except in compliance with the License.
|
6 | // You may obtain a copy of the License at
|
7 | //
|
8 | // http://www.apache.org/licenses/LICENSE-2.0
|
9 | //
|
10 | // Unless required by applicable law or agreed to in writing, software
|
11 | // distributed under the License is distributed on an "AS IS" BASIS,
|
12 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | // See the License for the specific language governing permissions and
|
14 | // limitations under the License.
|
15 | Object.defineProperty(exports, "__esModule", { value: true });
|
16 | exports.HmacKey = void 0;
|
17 | const common_1 = require("@google-cloud/common");
|
18 | /**
|
19 | * The API-formatted resource description of the HMAC key.
|
20 | *
|
21 | * Note: This is not guaranteed to be up-to-date when accessed. To get the
|
22 | * latest record, call the `getMetadata()` method.
|
23 | *
|
24 | * @name HmacKey#metadata
|
25 | * @type {object}
|
26 | */
|
27 | /**
|
28 | * An HmacKey object contains metadata of an HMAC key created from a
|
29 | * service account through the {@link Storage} client using
|
30 | * {@link Storage#createHmacKey}.
|
31 | *
|
32 | * @see [HMAC keys documentation]{@link https://cloud.google.com/storage/docs/authentication/hmackeys}
|
33 | *
|
34 | * @class
|
35 | */
|
36 | class HmacKey extends common_1.ServiceObject {
|
37 | /**
|
38 | * @typedef {object} HmacKeyOptions
|
39 | * @property {string} [projectId] The project ID of the project that owns
|
40 | * the service account of the requested HMAC key. If not provided,
|
41 | * the project ID used to instantiate the Storage client will be used.
|
42 | */
|
43 | /**
|
44 | * Constructs an HmacKey object.
|
45 | *
|
46 | * Note: this only create a local reference to an HMAC key, to create
|
47 | * an HMAC key, use {@link Storage#createHmacKey}.
|
48 | *
|
49 | * @param {Storage} storage The Storage instance this HMAC key is
|
50 | * attached to.
|
51 | * @param {string} accessId The unique accessId for this HMAC key.
|
52 | * @param {HmacKeyOptions} options Constructor configurations.
|
53 | * @example
|
54 | * const {Storage} = require('@google-cloud/storage');
|
55 | * const storage = new Storage();
|
56 | * const hmacKey = storage.hmacKey('access-id');
|
57 | */
|
58 | constructor(storage, accessId, options) {
|
59 | const methods = {
|
60 | /**
|
61 | * @typedef {object} DeleteHmacKeyOptions
|
62 | * @property {string} [userProject] This parameter is currently ignored.
|
63 | */
|
64 | /**
|
65 | * @typedef {array} DeleteHmacKeyResponse
|
66 | * @property {object} 0 The full API response.
|
67 | */
|
68 | /**
|
69 | * @callback DeleteHmacKeyCallback
|
70 | * @param {?Error} err Request error, if any.
|
71 | * @param {object} apiResponse The full API response.
|
72 | */
|
73 | /**
|
74 | * Deletes an HMAC key.
|
75 | * Key state must be set to `INACTIVE` prior to deletion.
|
76 | * Caution: HMAC keys cannot be recovered once you delete them.
|
77 | *
|
78 | * The authenticated user must have `storage.hmacKeys.delete` permission for the project in which the key exists.
|
79 | *
|
80 | * @method HmacKey#delete
|
81 | * @param {DeleteHmacKeyOptions} [options] Configuration options.
|
82 | * @param {DeleteHmacKeyCallback} [callback] Callback function.
|
83 | * @returns {Promise<DeleteHmacKeyResponse>}
|
84 | *
|
85 | * @example
|
86 | * const {Storage} = require('@google-cloud/storage');
|
87 | * const storage = new Storage();
|
88 | *
|
89 | * //-
|
90 | * // Delete HMAC key after making the key inactive.
|
91 | * //-
|
92 | * const hmacKey = storage.hmacKey('ACCESS_ID');
|
93 | * hmacKey.setMetadata({state: 'INACTIVE'}, (err, hmacKeyMetadata) => {
|
94 | * if (err) {
|
95 | * // The request was an error.
|
96 | * console.error(err);
|
97 | * return;
|
98 | * }
|
99 | * hmacKey.delete((err) => {
|
100 | * if (err) {
|
101 | * console.error(err);
|
102 | * return;
|
103 | * }
|
104 | * // The HMAC key is deleted.
|
105 | * });
|
106 | * });
|
107 | *
|
108 | * //-
|
109 | * // If the callback is omitted, a promise is returned.
|
110 | * //-
|
111 | * const hmacKey = storage.hmacKey('ACCESS_ID');
|
112 | * hmacKey
|
113 | * .setMetadata({state: 'INACTIVE'})
|
114 | * .then(() => {
|
115 | * return hmacKey.delete();
|
116 | * });
|
117 | */
|
118 | delete: true,
|
119 | /**
|
120 | * @callback GetHmacKeyCallback
|
121 | * @param {?Error} err Request error, if any.
|
122 | * @param {HmacKey} hmacKey this {@link HmacKey} instance.
|
123 | * @param {object} apiResponse The full API response.
|
124 | */
|
125 | /**
|
126 | * @typedef {array} GetHmacKeyResponse
|
127 | * @property {HmacKey} 0 This {@link HmacKey} instance.
|
128 | * @property {object} 1 The full API response.
|
129 | */
|
130 | /**
|
131 | * @typedef {object} GetHmacKeyOptions
|
132 | * @property {string} [userProject] This parameter is currently ignored.
|
133 | */
|
134 | /**
|
135 | * Retrieves and populate an HMAC key's metadata, and return
|
136 | * this {@link HmacKey} instance.
|
137 | *
|
138 | * HmacKey.get() does not give the HMAC key secret, as
|
139 | * it is only returned on creation.
|
140 | *
|
141 | * The authenticated user must have `storage.hmacKeys.get` permission
|
142 | * for the project in which the key exists.
|
143 | *
|
144 | * @method HmacKey#get
|
145 | * @param {GetHmacKeyOptions} [options] Configuration options.
|
146 | * @param {GetHmacKeyCallback} [callback] Callback function.
|
147 | * @returns {Promise<GetHmacKeyResponse>}
|
148 | *
|
149 | * @example
|
150 | * const {Storage} = require('@google-cloud/storage');
|
151 | * const storage = new Storage();
|
152 | *
|
153 | * //-
|
154 | * // Get the HmacKey's Metadata.
|
155 | * //-
|
156 | * storage.hmacKey('ACCESS_ID')
|
157 | * .get((err, hmacKey) => {
|
158 | * if (err) {
|
159 | * // The request was an error.
|
160 | * console.error(err);
|
161 | * return;
|
162 | * }
|
163 | * // do something with the returned HmacKey object.
|
164 | * });
|
165 | *
|
166 | * //-
|
167 | * // If the callback is omitted, a promise is returned.
|
168 | * //-
|
169 | * storage.hmacKey('ACCESS_ID')
|
170 | * .get()
|
171 | * .then((data) => {
|
172 | * const hmacKey = data[0];
|
173 | * });
|
174 | */
|
175 | get: true,
|
176 | /**
|
177 | * @typedef {object} GetHmacKeyMetadataOptions
|
178 | * @property {string} [userProject] This parameter is currently ignored.
|
179 | */
|
180 | /**
|
181 | * Retrieves and populate an HMAC key's metadata, and return
|
182 | * the HMAC key's metadata as an object.
|
183 | *
|
184 | * HmacKey.getMetadata() does not give the HMAC key secret, as
|
185 | * it is only returned on creation.
|
186 | *
|
187 | * The authenticated user must have `storage.hmacKeys.get` permission
|
188 | * for the project in which the key exists.
|
189 | *
|
190 | * @method HmacKey#getMetadata
|
191 | * @param {GetHmacKeyMetadataOptions} [options] Configuration options.
|
192 | * @param {HmacKeyMetadataCallback} [callback] Callback function.
|
193 | * @returns {Promise<HmacKeyMetadataResponse>}
|
194 | *
|
195 | * @example
|
196 | * const {Storage} = require('@google-cloud/storage');
|
197 | * const storage = new Storage();
|
198 | *
|
199 | * //-
|
200 | * // Get the HmacKey's metadata and populate to the metadata property.
|
201 | * //-
|
202 | * storage.hmacKey('ACCESS_ID')
|
203 | * .getMetadata((err, hmacKeyMetadata) => {
|
204 | * if (err) {
|
205 | * // The request was an error.
|
206 | * console.error(err);
|
207 | * return;
|
208 | * }
|
209 | * console.log(hmacKeyMetadata);
|
210 | * });
|
211 | *
|
212 | * //-
|
213 | * // If the callback is omitted, a promise is returned.
|
214 | * //-
|
215 | * storage.hmacKey('ACCESS_ID')
|
216 | * .getMetadata()
|
217 | * .then((data) => {
|
218 | * const hmacKeyMetadata = data[0];
|
219 | * console.log(hmacKeyMetadata);
|
220 | * });
|
221 | */
|
222 | getMetadata: true,
|
223 | /**
|
224 | * @typedef {object} SetHmacKeyMetadata Subset of {@link HmacKeyMetadata} to update.
|
225 | * @property {string} state New state of the HmacKey. Either 'ACTIVE' or 'INACTIVE'.
|
226 | * @property {string} [etag] Include an etag from a previous get HMAC key request
|
227 | * to perform safe read-modify-write.
|
228 | */
|
229 | /**
|
230 | * @typedef {object} SetHmacKeyMetadataOptions
|
231 | * @property {string} [userProject] This parameter is currently ignored.
|
232 | */
|
233 | /**
|
234 | * @callback HmacKeyMetadataCallback
|
235 | * @param {?Error} err Request error, if any.
|
236 | * @param {HmacKeyMetadata} metadata The updated {@link HmacKeyMetadata} object.
|
237 | * @param {object} apiResponse The full API response.
|
238 | */
|
239 | /**
|
240 | * @typedef {array} HmacKeyMetadataResponse
|
241 | * @property {HmacKeyMetadata} 0 The updated {@link HmacKeyMetadata} object.
|
242 | * @property {object} 1 The full API response.
|
243 | */
|
244 | /**
|
245 | * Updates the state of an HMAC key. See {@link SetHmacKeyMetadata} for
|
246 | * valid states.
|
247 | *
|
248 | * @method HmacKey#setMetadata
|
249 | * @param {SetHmacKeyMetadata} metadata The new metadata.
|
250 | * @param {SetHmacKeyMetadataOptions} [options] Configuration options.
|
251 | * @param {HmacKeyMetadataCallback} [callback] Callback function.
|
252 | * @returns {Promise<HmacKeyMetadataResponse>}
|
253 | *
|
254 | * @example
|
255 | * const {Storage} = require('@google-cloud/storage');
|
256 | * const storage = new Storage();
|
257 | *
|
258 | * const metadata = {
|
259 | * state: 'INACTIVE',
|
260 | * };
|
261 | *
|
262 | * storage.hmacKey('ACCESS_ID')
|
263 | * .setMetadata(metadata, (err, hmacKeyMetadata) => {
|
264 | * if (err) {
|
265 | * // The request was an error.
|
266 | * console.error(err);
|
267 | * return;
|
268 | * }
|
269 | * console.log(hmacKeyMetadata);
|
270 | * });
|
271 | *
|
272 | * //-
|
273 | * // If the callback is omitted, a promise is returned.
|
274 | * //-
|
275 | * storage.hmacKey('ACCESS_ID')
|
276 | * .setMetadata(metadata)
|
277 | * .then((data) => {
|
278 | * const hmacKeyMetadata = data[0];
|
279 | * console.log(hmacKeyMetadata);
|
280 | * });
|
281 | */
|
282 | setMetadata: {
|
283 | reqOpts: {
|
284 | method: 'PUT',
|
285 | },
|
286 | },
|
287 | };
|
288 | const projectId = (options && options.projectId) || storage.projectId;
|
289 | super({
|
290 | parent: storage,
|
291 | id: accessId,
|
292 | baseUrl: `/projects/${projectId}/hmacKeys`,
|
293 | methods,
|
294 | });
|
295 | }
|
296 | }
|
297 | exports.HmacKey = HmacKey;
|
298 | //# sourceMappingURL=hmacKey.js.map |
\ | No newline at end of file |