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.Iam = void 0;
|
17 | const promisify_1 = require("@google-cloud/promisify");
|
18 | const arrify = require("arrify");
|
19 | const util_1 = require("./util");
|
20 | /**
|
21 | * Get and set IAM policies for your Cloud Storage bucket.
|
22 | *
|
23 | * @see [Cloud Storage IAM Management](https://cloud.google.com/storage/docs/access-control/iam#short_title_iam_management)
|
24 | * @see [Granting, Changing, and Revoking Access](https://cloud.google.com/iam/docs/granting-changing-revoking-access)
|
25 | * @see [IAM Roles](https://cloud.google.com/iam/docs/understanding-roles)
|
26 | *
|
27 | * @constructor Iam
|
28 | *
|
29 | * @param {Bucket} bucket The parent instance.
|
30 | * @example
|
31 | * const {Storage} = require('@google-cloud/storage');
|
32 | * const storage = new Storage();
|
33 | * const bucket = storage.bucket('my-bucket');
|
34 | * // bucket.iam
|
35 | */
|
36 | class Iam {
|
37 | constructor(bucket) {
|
38 | this.request_ = bucket.request.bind(bucket);
|
39 | this.resourceId_ = 'buckets/' + bucket.getId();
|
40 | }
|
41 | /**
|
42 | * @typedef {object} GetPolicyOptions Requested options for IAM#getPolicy().
|
43 | * @property {number} [requestedPolicyVersion] The version of IAM policies to
|
44 | * request. If a policy with a condition is requested without setting
|
45 | * this, the server will return an error. This must be set to a value
|
46 | * of 3 to retrieve IAM policies containing conditions. This is to
|
47 | * prevent client code that isn't aware of IAM conditions from
|
48 | * interpreting and modifying policies incorrectly. The service might
|
49 | * return a policy with version lower than the one that was requested,
|
50 | * based on the feature syntax in the policy fetched.
|
51 | * @see [IAM Policy versions]{@link https://cloud.google.com/iam/docs/policies#versions}
|
52 | * @property {string} [userProject] The ID of the project which will be
|
53 | * billed for the request.
|
54 | */
|
55 | /**
|
56 | * @typedef {array} GetPolicyResponse
|
57 | * @property {Policy} 0 The policy.
|
58 | * @property {object} 1 The full API response.
|
59 | */
|
60 | /**
|
61 | * @typedef {object} Policy
|
62 | * @property {PolicyBinding[]} policy.bindings Bindings associate members with roles.
|
63 | * @property {string} [policy.etag] Etags are used to perform a read-modify-write.
|
64 | * @property {number} [policy.version] The syntax schema version of the Policy.
|
65 | * To set an IAM policy with conditional binding, this field must be set to
|
66 | * 3 or greater.
|
67 | * @see [IAM Policy versions]{@link https://cloud.google.com/iam/docs/policies#versions}
|
68 | */
|
69 | /**
|
70 | * @typedef {object} PolicyBinding
|
71 | * @property {string} role Role that is assigned to members.
|
72 | * @property {string[]} members Specifies the identities requesting access for the bucket.
|
73 | * @property {Expr} [condition] The condition that is associated with this binding.
|
74 | */
|
75 | /**
|
76 | * @typedef {object} Expr
|
77 | * @property {string} [title] An optional title for the expression, i.e. a
|
78 | * short string describing its purpose. This can be used e.g. in UIs
|
79 | * which allow to enter the expression.
|
80 | * @property {string} [description] An optional description of the
|
81 | * expression. This is a longer text which describes the expression,
|
82 | * e.g. when hovered over it in a UI.
|
83 | * @property {string} expression Textual representation of an expression in
|
84 | * Common Expression Language syntax. The application context of the
|
85 | * containing message determines which well-known feature set of CEL
|
86 | * is supported.The condition that is associated with this binding.
|
87 | *
|
88 | * @see [Condition] https://cloud.google.com/storage/docs/access-control/iam#conditions
|
89 | */
|
90 | /**
|
91 | * Get the IAM policy.
|
92 | *
|
93 | * @param {GetPolicyOptions} [options] Request options.
|
94 | * @param {GetPolicyCallback} [callback] Callback function.
|
95 | * @returns {Promise<GetPolicyResponse>}
|
96 | *
|
97 | * @see [Buckets: setIamPolicy API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy}
|
98 | *
|
99 | * @example
|
100 | * const {Storage} = require('@google-cloud/storage');
|
101 | * const storage = new Storage();
|
102 | * const bucket = storage.bucket('my-bucket');
|
103 | *
|
104 | * bucket.iam.getPolicy(
|
105 | * {requestedPolicyVersion: 3},
|
106 | * function(err, policy, apiResponse) {
|
107 | *
|
108 | * },
|
109 | * );
|
110 | *
|
111 | * //-
|
112 | * // If the callback is omitted, we'll return a Promise.
|
113 | * //-
|
114 | * bucket.iam.getPolicy({requestedPolicyVersion: 3})
|
115 | * .then(function(data) {
|
116 | * const policy = data[0];
|
117 | * const apiResponse = data[1];
|
118 | * });
|
119 | *
|
120 | * @example <caption>include:samples/iam.js</caption>
|
121 | * region_tag:storage_view_bucket_iam_members
|
122 | * Example of retrieving a bucket's IAM policy:
|
123 | */
|
124 | getPolicy(optionsOrCallback, callback) {
|
125 | const { options, callback: cb } = util_1.normalize(optionsOrCallback, callback);
|
126 | const qs = {};
|
127 | if (options.userProject) {
|
128 | qs.userProject = options.userProject;
|
129 | }
|
130 | if (options.requestedPolicyVersion !== null &&
|
131 | options.requestedPolicyVersion !== undefined) {
|
132 | qs.optionsRequestedPolicyVersion = options.requestedPolicyVersion;
|
133 | }
|
134 | this.request_({
|
135 | uri: '/iam',
|
136 | qs,
|
137 | }, cb);
|
138 | }
|
139 | /**
|
140 | * Set the IAM policy.
|
141 | *
|
142 | * @throws {Error} If no policy is provided.
|
143 | *
|
144 | * @param {Policy} policy The policy.
|
145 | * @param {SetPolicyOptions} [options] Configuration opbject.
|
146 | * @param {SetPolicyCallback} callback Callback function.
|
147 | * @returns {Promise<SetPolicyResponse>}
|
148 | *
|
149 | * @see [Buckets: setIamPolicy API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy}
|
150 | * @see [IAM Roles](https://cloud.google.com/iam/docs/understanding-roles)
|
151 | *
|
152 | * @example
|
153 | * const {Storage} = require('@google-cloud/storage');
|
154 | * const storage = new Storage();
|
155 | * const bucket = storage.bucket('my-bucket');
|
156 | *
|
157 | * const myPolicy = {
|
158 | * bindings: [
|
159 | * {
|
160 | * role: 'roles/storage.admin',
|
161 | * members:
|
162 | * ['serviceAccount:myotherproject@appspot.gserviceaccount.com']
|
163 | * }
|
164 | * ]
|
165 | * };
|
166 | *
|
167 | * bucket.iam.setPolicy(myPolicy, function(err, policy, apiResponse) {});
|
168 | *
|
169 | * //-
|
170 | * // If the callback is omitted, we'll return a Promise.
|
171 | * //-
|
172 | * bucket.iam.setPolicy(myPolicy).then(function(data) {
|
173 | * const policy = data[0];
|
174 | * const apiResponse = data[1];
|
175 | * });
|
176 | *
|
177 | * @example <caption>include:samples/iam.js</caption>
|
178 | * region_tag:storage_add_bucket_iam_member
|
179 | * Example of adding to a bucket's IAM policy:
|
180 | *
|
181 | * @example <caption>include:samples/iam.js</caption>
|
182 | * region_tag:storage_remove_bucket_iam_member
|
183 | * Example of removing from a bucket's IAM policy:
|
184 | */
|
185 | setPolicy(policy, optionsOrCallback, callback) {
|
186 | if (policy === null || typeof policy !== 'object') {
|
187 | throw new Error('A policy object is required.');
|
188 | }
|
189 | const { options, callback: cb } = util_1.normalize(optionsOrCallback, callback);
|
190 | this.request_({
|
191 | method: 'PUT',
|
192 | uri: '/iam',
|
193 | json: Object.assign({
|
194 | resourceId: this.resourceId_,
|
195 | }, policy),
|
196 | qs: options,
|
197 | }, cb);
|
198 | }
|
199 | /**
|
200 | * Test a set of permissions for a resource.
|
201 | *
|
202 | * @throws {Error} If permissions are not provided.
|
203 | *
|
204 | * @param {string|string[]} permissions The permission(s) to test for.
|
205 | * @param {TestIamPermissionsOptions} [options] Configuration object.
|
206 | * @param {TestIamPermissionsCallback} [callback] Callback function.
|
207 | * @returns {Promise<TestIamPermissionsResponse>}
|
208 | *
|
209 | * @see [Buckets: testIamPermissions API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/buckets/testIamPermissions}
|
210 | *
|
211 | * @example
|
212 | * const {Storage} = require('@google-cloud/storage');
|
213 | * const storage = new Storage();
|
214 | * const bucket = storage.bucket('my-bucket');
|
215 | *
|
216 | * //-
|
217 | * // Test a single permission.
|
218 | * //-
|
219 | * const test = 'storage.buckets.delete';
|
220 | *
|
221 | * bucket.iam.testPermissions(test, function(err, permissions, apiResponse) {
|
222 | * console.log(permissions);
|
223 | * // {
|
224 | * // "storage.buckets.delete": true
|
225 | * // }
|
226 | * });
|
227 | *
|
228 | * //-
|
229 | * // Test several permissions at once.
|
230 | * //-
|
231 | * const tests = [
|
232 | * 'storage.buckets.delete',
|
233 | * 'storage.buckets.get'
|
234 | * ];
|
235 | *
|
236 | * bucket.iam.testPermissions(tests, function(err, permissions) {
|
237 | * console.log(permissions);
|
238 | * // {
|
239 | * // "storage.buckets.delete": false,
|
240 | * // "storage.buckets.get": true
|
241 | * // }
|
242 | * });
|
243 | *
|
244 | * //-
|
245 | * // If the callback is omitted, we'll return a Promise.
|
246 | * //-
|
247 | * bucket.iam.testPermissions(test).then(function(data) {
|
248 | * const permissions = data[0];
|
249 | * const apiResponse = data[1];
|
250 | * });
|
251 | */
|
252 | testPermissions(permissions, optionsOrCallback, callback) {
|
253 | if (!Array.isArray(permissions) && typeof permissions !== 'string') {
|
254 | throw new Error('Permissions are required.');
|
255 | }
|
256 | const { options, callback: cb } = util_1.normalize(optionsOrCallback, callback);
|
257 | const permissionsArray = arrify(permissions);
|
258 | const req = Object.assign({
|
259 | permissions: permissionsArray,
|
260 | }, options);
|
261 | this.request_({
|
262 | uri: '/iam/testPermissions',
|
263 | qs: req,
|
264 | useQuerystring: true,
|
265 | }, (err, resp) => {
|
266 | if (err) {
|
267 | cb(err, null, resp);
|
268 | return;
|
269 | }
|
270 | const availablePermissions = arrify(resp.permissions);
|
271 | const permissionsHash = permissionsArray.reduce((acc, permission) => {
|
272 | acc[permission] = availablePermissions.indexOf(permission) > -1;
|
273 | return acc;
|
274 | }, {});
|
275 | cb(null, permissionsHash, resp);
|
276 | });
|
277 | }
|
278 | }
|
279 | exports.Iam = Iam;
|
280 | /*! Developer Documentation
|
281 | *
|
282 | * All async methods (except for streams) will return a Promise in the event
|
283 | * that a callback is omitted.
|
284 | */
|
285 | promisify_1.promisifyAll(Iam);
|
286 | //# sourceMappingURL=iam.js.map |
\ | No newline at end of file |