iam.dart

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Code generated by sidekick. DO NOT EDIT.

/// The Google Cloud client for the IAM API.
library;

import 'dart:convert';
import 'dart:typed_data';

import 'package:http/http.dart' as http;

import 'src/type.dart';
import 'src/types.dart';

/// API Overview
///
/// Manages Identity and Access Management (IAM) policies.
///
/// Any implementation of an API that offers access control features
/// implements the google.iam.v1.IAMPolicy interface.
///
/// ## Data model
///
/// Access control is applied when a principal (user or service account), takes
/// some action on a resource exposed by a service. Resources, identified by
/// URI-like names, are the unit of access control specification. Service
/// implementations can choose the granularity of access control and the
/// supported permissions for their resources.
/// For example one database service may allow access control to be
/// specified only at the Table level, whereas another might allow access control
/// to also be specified at the Column level.
///
/// ## Policy Structure
///
/// See google.iam.v1.Policy
///
/// This is intentionally not a CRUD style API because access control policies
/// are created and deleted implicitly with the resources to which they are
/// attached.
class IAMPolicy {
  static const String defaultHostUri = 'https://iam-meta-api.googleapis.com';

  final Uri baseUri;
  final http.Client client;

  IAMPolicy({String hostUri = defaultHostUri})
    : baseUri = Uri.parse(hostUri),
      client = http.Client();

  /// Sets the access control policy on the specified resource. Replaces any
  /// existing policy.
  ///
  /// Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED` errors.
  Future<Policy> setIamPolicy({
    required String resource,
    required Policy policy,
    FieldMask? updateMask,
  }) async {
    // post: "/v1/{resource=**}:setIamPolicy"

    final uri = baseUri.replace(
      path: '/v1/$resource:setIamPolicy',
      queryParameters: {
        if (updateMask != null) 'updateMask': updateMask.pathEncoding,
      },
    );

    final response = await client.post(uri, body: jsonEncode(policy.toJson()));
    return Policy.fromJson(jsonDecode(response.body));
  }

  /// Gets the access control policy for a resource.
  ///
  /// Returns an empty policy if the resource exists and does not have a policy
  /// set.
  Future<Policy> getIamPolicy({
    required String resource,
    GetPolicyOptions? options,
  }) async {
    // post: "/v1/{resource=**}:getIamPolicy"

    final uri = baseUri.replace(
      path: 'v1/$resource:getIamPolicy',
      queryParameters: {
        if (options?.requestedPolicyVersion != null)
          'options.requestedPolicyVersion':
              '${options?.requestedPolicyVersion}',
      },
    );

    final response = await client.post(uri);
    return Policy.fromJson(jsonDecode(response.body));
  }

  /// Returns permissions that a caller has on the specified resource.
  ///
  /// If the resource does not exist, this will return an empty set of
  /// permissions, not a `NOT_FOUND` error.
  ///
  /// Note: This operation is designed to be used for building permission-aware
  /// UIs and command-line tools, not for authorization checking. This operation
  /// may "fail open" without warning.
  Future<TestIamPermissionsResponse> testIamPermissions({
    required String resource,
    final List<String>? permissions,
  }) async {
    // post: "/v1/{resource=**}:testIamPermissions"

    final uri = baseUri.replace(
      path: '/v1/$resource:testIamPermissions',
      queryParameters: {
        if (permissions != null) 'permissions': permissions.join(','),
      },
    );

    final response = await client.post(uri);
    return TestIamPermissionsResponse.fromJson(jsonDecode(response.body));
  }
}

/// Request message for `SetIamPolicy` method.
class SetIamPolicyRequest {
  /// REQUIRED: The resource for which the policy is being specified.
  /// See the operation documentation for the appropriate value for this field.
  final String? resource;

  /// REQUIRED: The complete policy to be applied to the `resource`. The size of
  /// the policy is limited to a few 10s of KB. An empty policy is a
  /// valid policy but certain Cloud Platform services (such as Projects)
  /// might reject them.
  final Policy? policy;

  /// OPTIONAL: A FieldMask specifying which fields of the policy to modify. Only
  /// the fields in the mask will be modified. If no mask is provided, the
  /// following default mask is used:
  ///
  /// `paths: "bindings, etag"`
  final FieldMask? updateMask;

  SetIamPolicyRequest({this.resource, this.policy, this.updateMask});
}

/// Request message for `GetIamPolicy` method.
class GetIamPolicyRequest {
  /// REQUIRED: The resource for which the policy is being requested.
  /// See the operation documentation for the appropriate value for this field.
  final String? resource;

  /// OPTIONAL: A `GetPolicyOptions` object for specifying options to
  /// `GetIamPolicy`.
  final GetPolicyOptions? options;

  GetIamPolicyRequest({this.resource, this.options});
}

/// Request message for `TestIamPermissions` method.
class TestIamPermissionsRequest {
  /// REQUIRED: The resource for which the policy detail is being requested.
  /// See the operation documentation for the appropriate value for this field.
  final String? resource;

  /// The set of permissions to check for the `resource`. Permissions with
  /// wildcards (such as '*' or 'storage.*') are not allowed. For more
  /// information see
  /// [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions).
  final List<String>? permissions;

  TestIamPermissionsRequest({this.resource, this.permissions});
}

/// Response message for `TestIamPermissions` method.
class TestIamPermissionsResponse {
  /// A subset of `TestPermissionsRequest.permissions` that the caller is
  /// allowed.
  final List<String>? permissions;

  TestIamPermissionsResponse({this.permissions});

  factory TestIamPermissionsResponse.fromJson(Map<String, Object?> json) {
    return TestIamPermissionsResponse(permissions: json['permissions']);
  }
}

/// Encapsulates settings provided to GetIamPolicy.
class GetPolicyOptions {
  /// Optional. The maximum policy version that will be used to format the
  /// policy.
  ///
  /// Valid values are 0, 1, and 3. Requests specifying an invalid value will be
  /// rejected.
  ///
  /// Requests for policies with any conditional role bindings must specify
  /// version 3. Policies with no conditional role bindings may specify any valid
  /// value or leave the field unset.
  ///
  /// The policy in the response might use the policy version that you specified,
  /// or it might use a lower policy version. For example, if you specify version
  /// 3, but the policy has no conditional role bindings, the response uses
  /// version 1.
  ///
  /// To learn which resources support conditions in their IAM policies, see the
  /// [IAM
  /// documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
  final int? requestedPolicyVersion;

  GetPolicyOptions({this.requestedPolicyVersion});
}

/// An Identity and Access Management (IAM) policy, which specifies access
/// controls for Google Cloud resources.
///
///
/// A `Policy` is a collection of `bindings`. A `binding` binds one or more
/// `members`, or principals, to a single `role`. Principals can be user
/// accounts, service accounts, Google groups, and domains (such as G Suite). A
/// `role` is a named list of permissions; each `role` can be an IAM predefined
/// role or a user-created custom role.
///
/// For some types of Google Cloud resources, a `binding` can also specify a
/// `condition`, which is a logical expression that allows access to a resource
/// only if the expression evaluates to `true`. A condition can add constraints
/// based on attributes of the request, the resource, or both. To learn which
/// resources support conditions in their IAM policies, see the
/// [IAM
/// documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
///
/// **JSON example:**
///
/// ```
///     {
///       "bindings": [
///         {
///           "role": "roles/resourcemanager.organizationAdmin",
///           "members": [
///             "user:[email protected]",
///             "group:[email protected]",
///             "domain:google.com",
///             "serviceAccount:[email protected]"
///           ]
///         },
///         {
///           "role": "roles/resourcemanager.organizationViewer",
///           "members": [
///             "user:[email protected]"
///           ],
///           "condition": {
///             "title": "expirable access",
///             "description": "Does not grant access after Sep 2020",
///             "expression": "request.time <
///             timestamp('2020-10-01T00:00:00.000Z')",
///           }
///         }
///       ],
///       "etag": "BwWWja0YfJA=",
///       "version": 3
///     }
/// ```
///
/// **YAML example:**
///
/// ```
///     bindings:
///     - members:
///       - user:[email protected]
///       - group:[email protected]
///       - domain:google.com
///       - serviceAccount:[email protected]
///       role: roles/resourcemanager.organizationAdmin
///     - members:
///       - user:[email protected]
///       role: roles/resourcemanager.organizationViewer
///       condition:
///         title: expirable access
///         description: Does not grant access after Sep 2020
///         expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
///     etag: BwWWja0YfJA=
///     version: 3
/// ```
///
/// For a description of IAM and its features, see the
/// [IAM documentation](https://cloud.google.com/iam/docs/).
class Policy {
  /// Specifies the format of the policy.
  ///
  /// Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
  /// are rejected.
  ///
  /// Any operation that affects conditional role bindings must specify version
  /// `3`. This requirement applies to the following operations:
  ///
  /// * Getting a policy that includes a conditional role binding
  /// * Adding a conditional role binding to a policy
  /// * Changing a conditional role binding in a policy
  /// * Removing any role binding, with or without a condition, from a policy
  ///   that includes conditions
  ///
  /// **Important:** If you use IAM Conditions, you must include the `etag` field
  /// whenever you call `setIamPolicy`. If you omit this field, then IAM allows
  /// you to overwrite a version `3` policy with a version `1` policy, and all of
  /// the conditions in the version `3` policy are lost.
  ///
  /// If a policy does not include any conditions, operations on that policy may
  /// specify any valid version or leave the field unset.
  ///
  /// To learn which resources support conditions in their IAM policies, see the
  /// [IAM
  /// documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
  final int? version;

  /// Associates a list of `members`, or principals, with a `role`. Optionally,
  /// may specify a `condition` that determines how and when the `bindings` are
  /// applied. Each of the `bindings` must contain at least one principal.
  ///
  /// The `bindings` in a `Policy` can refer to up to 1,500 principals; up to 250
  /// of these principals can be Google groups. Each occurrence of a principal
  /// counts towards these limits. For example, if the `bindings` grant 50
  /// different roles to `user:[email protected]`, and not to any other
  /// principal, then you can add another 1,450 principals to the `bindings` in
  /// the `Policy`.
  final List<Binding>? bindings;

  /// Specifies cloud audit logging configuration for this policy.
  final List<AuditConfig>? auditConfigs;

  /// `etag` is used for optimistic concurrency control as a way to help
  /// prevent simultaneous updates of a policy from overwriting each other.
  /// It is strongly suggested that systems make use of the `etag` in the
  /// read-modify-write cycle to perform policy updates in order to avoid race
  /// conditions: An `etag` is returned in the response to `getIamPolicy`, and
  /// systems are expected to put that etag in the request to `setIamPolicy` to
  /// ensure that their change will be applied to the same version of the policy.
  ///
  /// **Important:** If you use IAM Conditions, you must include the `etag` field
  /// whenever you call `setIamPolicy`. If you omit this field, then IAM allows
  /// you to overwrite a version `3` policy with a version `1` policy, and all of
  /// the conditions in the version `3` policy are lost.
  final Uint8List? etag;

  Policy({this.version, this.bindings, this.auditConfigs, this.etag});

  factory Policy.fromJson(Map<String, Object?> json) {
    return Policy(
      version: json['version'],
      bindings: json['bindings'],
      auditConfigs: json['auditConfigs'],
      etag: json['etag'],
    );
  }

  Map<String, Object?> toJson() => {
    if (version != null) 'version': version,
    // todo:
    if (bindings != null) 'bindings': bindings,
    // todo:
    if (auditConfigs != null) 'auditConfigs': auditConfigs,
    if (etag != null) 'etag': etag,
  };
}

/// Associates `members`, or principals, with a `role`.
class Binding {
  /// Role that is assigned to the list of `members`, or principals.
  /// For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
  final String? role;

  /// Specifies the principals requesting access for a Google Cloud resource.
  /// `members` can have the following values:
  ///
  /// * `allUsers`: A special identifier that represents anyone who is
  ///    on the internet; with or without a Google account.
  ///
  /// * `allAuthenticatedUsers`: A special identifier that represents anyone
  ///    who is authenticated with a Google account or a service account.
  ///
  /// * `user:{emailid}`: An email address that represents a specific Google
  ///    account. For example, `[email protected]` .
  ///
  ///
  /// * `serviceAccount:{emailid}`: An email address that represents a service
  ///    account. For example, `[email protected]`.
  ///
  /// * `group:{emailid}`: An email address that represents a Google group.
  ///    For example, `[email protected]`.
  ///
  /// * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
  ///    identifier) representing a user that has been recently deleted. For
  ///    example, `[email protected]?uid=123456789012345678901`. If the user is
  ///    recovered, this value reverts to `user:{emailid}` and the recovered user
  ///    retains the role in the binding.
  ///
  /// * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
  ///    unique identifier) representing a service account that has been recently
  ///    deleted. For example,
  ///    `[email protected]?uid=123456789012345678901`.
  ///    If the service account is undeleted, this value reverts to
  ///    `serviceAccount:{emailid}` and the undeleted service account retains the
  ///    role in the binding.
  ///
  /// * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
  ///    identifier) representing a Google group that has been recently
  ///    deleted. For example, `[email protected]?uid=123456789012345678901`. If
  ///    the group is recovered, this value reverts to `group:{emailid}` and the
  ///    recovered group retains the role in the binding.
  ///
  ///
  /// * `domain:{domain}`: The G Suite domain (primary) that represents all the
  ///    users of that domain. For example, `google.com` or `example.com`.
  ///
  ///
  final List<String>? members;

  /// The condition that is associated with this binding.
  ///
  /// If the condition evaluates to `true`, then this binding applies to the
  /// current request.
  ///
  /// If the condition evaluates to `false`, then this binding does not apply to
  /// the current request. However, a different role binding might grant the same
  /// role to one or more of the principals in this binding.
  ///
  /// To learn which resources support conditions in their IAM policies, see the
  /// [IAM
  /// documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
  final Expr? condition;

  Binding({this.role, this.members, this.condition});
}

/// Specifies the audit configuration for a service.
/// The configuration determines which permission types are logged, and what
/// identities, if any, are exempted from logging.
/// An AuditConfig must have one or more AuditLogConfigs.
///
/// If there are AuditConfigs for both `allServices` and a specific service,
/// the union of the two AuditConfigs is used for that service: the log_types
/// specified in each AuditConfig are enabled, and the exempted_members in each
/// AuditLogConfig are exempted.
///
/// Example Policy with multiple AuditConfigs:
///
///     {
///       "audit_configs": [
///         {
///           "service": "allServices",
///           "audit_log_configs": [
///             {
///               "log_type": "DATA_READ",
///               "exempted_members": [
///                 "user:[email protected]"
///               ]
///             },
///             {
///               "log_type": "DATA_WRITE"
///             },
///             {
///               "log_type": "ADMIN_READ"
///             }
///           ]
///         },
///         {
///           "service": "sampleservice.googleapis.com",
///           "audit_log_configs": [
///             {
///               "log_type": "DATA_READ"
///             },
///             {
///               "log_type": "DATA_WRITE",
///               "exempted_members": [
///                 "user:[email protected]"
///               ]
///             }
///           ]
///         }
///       ]
///     }
///
/// For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ
/// logging. It also exempts `[email protected]` from DATA_READ logging, and
/// `[email protected]` from DATA_WRITE logging.
class AuditConfig {
  /// Specifies a service that will be enabled for audit logging.
  /// For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.
  /// `allServices` is a special value that covers all services.
  final String? service;

  /// The configuration for logging of each type of permission.
  final List<AuditLogConfig>? auditLogConfigs;

  AuditConfig({this.service, this.auditLogConfigs});
}

/// Provides the configuration for logging a type of permissions.
/// Example:
///
///     {
///       "audit_log_configs": [
///         {
///           "log_type": "DATA_READ",
///           "exempted_members": [
///             "user:[email protected]"
///           ]
///         },
///         {
///           "log_type": "DATA_WRITE"
///         }
///       ]
///     }
///
/// This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting
/// [email protected] from DATA_READ logging.
class AuditLogConfig {
  /// The log type that this config enables.
  final AuditLogConfig$LogType? logType;

  /// Specifies the identities that do not cause logging for this type of
  /// permission.
  ///
  /// Follows the same format of [Binding.members].
  final List<String>? exemptedMembers;

  AuditLogConfig({this.logType, this.exemptedMembers});
}

/// The list of valid permission types for which logging can be configured.
/// Admin writes are always logged, and are not configurable.
class AuditLogConfig$LogType {
  /// Default case. Should never be this.
  static const AuditLogConfig$LogType logTypeUnspecified =
      AuditLogConfig$LogType('LOG_TYPE_UNSPECIFIED');

  /// Admin reads. Example: CloudIAM getIamPolicy
  static const AuditLogConfig$LogType adminRead = AuditLogConfig$LogType(
    'ADMIN_READ',
  );

  /// Data writes. Example: CloudSQL Users create
  static const AuditLogConfig$LogType dataWrite = AuditLogConfig$LogType(
    'DATA_WRITE',
  );

  /// Data reads. Example: CloudSQL Users list
  static const AuditLogConfig$LogType dataRead = AuditLogConfig$LogType(
    'DATA_READ',
  );

  final String value;

  const AuditLogConfig$LogType(this.value);
}

/// The difference delta between two policies.
class PolicyDelta {
  /// The delta for Bindings between two policies.
  final List<BindingDelta>? bindingDeltas;

  /// The delta for AuditConfigs between two policies.
  final List<AuditConfigDelta>? auditConfigDeltas;

  PolicyDelta({this.bindingDeltas, this.auditConfigDeltas});
}

/// One delta entry for Binding. Each individual change (only one member in each
/// entry) to a binding will be a separate entry.
class BindingDelta {
  /// The action that was performed on a Binding.
  /// Required
  final BindingDelta$Action? action;

  /// Role that is assigned to `members`.
  /// For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
  /// Required
  final String? role;

  /// A single identity requesting access for a Google Cloud resource.
  /// Follows the same format of Binding.members.
  /// Required
  final String? member;

  /// The condition that is associated with this binding.
  final Expr? condition;

  BindingDelta({this.action, this.role, this.member, this.condition});
}

/// The type of action performed on a Binding in a policy.
class BindingDelta$Action {
  /// Unspecified.
  static const BindingDelta$Action actionUnspecified = BindingDelta$Action(
    'ACTION_UNSPECIFIED',
  );

  /// Addition of a Binding.
  static const BindingDelta$Action add = BindingDelta$Action('ADD');

  /// Removal of a Binding.
  static const BindingDelta$Action remove = BindingDelta$Action('REMOVE');

  final String value;

  const BindingDelta$Action(this.value);
}

/// One delta entry for AuditConfig. Each individual change (only one
/// exempted_member in each entry) to a AuditConfig will be a separate entry.
class AuditConfigDelta {
  /// The action that was performed on an audit configuration in a policy.
  /// Required
  final AuditConfigDelta$Action? action;

  /// Specifies a service that was configured for Cloud Audit Logging.
  /// For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.
  /// `allServices` is a special value that covers all services.
  /// Required
  final String? service;

  /// A single identity that is exempted from "data access" audit
  /// logging for the `service` specified above.
  /// Follows the same format of Binding.members.
  final String? exemptedMember;

  /// Specifies the log_type that was be enabled. ADMIN_ACTIVITY is always
  /// enabled, and cannot be configured.
  /// Required
  final String? logType;

  AuditConfigDelta({
    this.action,
    this.service,
    this.exemptedMember,
    this.logType,
  });
}

/// The type of action performed on an audit configuration in a policy.
class AuditConfigDelta$Action {
  /// Unspecified.
  static const AuditConfigDelta$Action actionUnspecified =
      AuditConfigDelta$Action('ACTION_UNSPECIFIED');

  /// Addition of an audit configuration.
  static const AuditConfigDelta$Action add = AuditConfigDelta$Action('ADD');

  /// Removal of an audit configuration.
  static const AuditConfigDelta$Action remove = AuditConfigDelta$Action(
    'REMOVE',
  );

  final String value;

  const AuditConfigDelta$Action(this.value);
}