@origincloud/kms 0.0.0-stage → 0.28.0

package/src/v1beta1/key.ts

@@ -0,0 +1,590 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/kms/v1beta1/key.proto
+
+import {
+  type CallOptions,
+  type Client,
+  type Service,
+  newRequestId,
+  pathValue,
+  query,
+} from "@origincloud/core";
+
+/**
+ * Calls KeyService.
+ *
+ * Keys and the operations made with them.
+ *
+ * An `ENCRYPT_DECRYPT` key encrypts with AES-256-GCM-SIV. Its ciphertext
+ * names the key version that made it but not the key: Decrypt names the
+ * key, and a ciphertext decrypts only under the key and the encryption
+ * context it was made with. A signing key signs with ECDSA over P-256 and
+ * SHA-256 (ASN.1 DER signatures) or with Ed25519; its public keys are read
+ * with GetPublicKey.
+ */
+export class KeyClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of KeyService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("kms", true);
+  }
+
+  /** Returns a key, deleted or not. Needs `kms.key.get` on the project. */
+  async getKey(request: GetKeyRequest, options?: CallOptions): Promise<Key> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<Key>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists a project's keys in a region, ordered by name. Deleted ones are
+   * listed only when `showDeleted` is set, so a page may hold fewer keys
+   * than `pageSize` and still be followed by another. Needs `kms.key.list`
+   * on the project.
+   */
+  async listKeys(request: ListKeysRequest, options?: CallOptions): Promise<ListKeysResponse> {
+    const p0 = pathValue("parent", request.parent, "projects/*/regions/*");
+    return this.service.call<ListKeysResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}/keys`,
+        query: query(request, ["parent"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything listKeys lists from the request's page on,
+   * fetching the next page as the loop reaches it. A page that fails ends
+   * the iteration with its error.
+   */
+  async *allKeys(request: ListKeysRequest, options?: CallOptions): AsyncGenerator<Key, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.listKeys(page, options);
+      yield* response.keys ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+
+  /**
+   * Creates a key, `ENABLED`, with its first version as the primary. The
+   * platform assigns its id, which its `name` returns; an id is never used
+   * again. Needs `kms.key.create` on the project.
+   */
+  async createKey(request: CreateKeyRequest, options?: CallOptions): Promise<Key> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("parent", request.parent, "projects/*/regions/*");
+    return this.service.call<Key>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}/keys`,
+        body: request.key,
+        query: query(request, ["parent", "key"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Enables or disables a key, or changes its tags: `state` and `tags` are
+   * the fields it changes. A disabled key refuses every operation but
+   * GetPublicKey with `CONFLICT` until it is enabled again. Setting the
+   * state or the tags the key has already succeeds and changes nothing. A
+   * deleted key can't be changed: undelete it first. A key the platform
+   * manages (`platformManaged`) is refused with `FORBIDDEN`, even when the
+   * request would change nothing. Needs
+   * `kms.key.update` on the project.
+   */
+  async updateKey(request: UpdateKeyRequest, options?: CallOptions): Promise<Key> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("key.name", request.key?.name, "projects/*/regions/*/keys/*");
+    return this.service.call<Key>(
+      {
+        method: "PATCH",
+        path: `/v1beta1/${p0}`,
+        body: request.key,
+        query: query(request, ["key.name", "key"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Deletes a key: it becomes `DELETED` at once, refuses every operation
+   * but GetPublicKey, and its material is destroyed at `purgeTime`, after
+   * `destroyDelay`. Until then UndeleteKey restores it, disabled. After it,
+   * nothing it encrypted can ever be decrypted again. Deleting a deleted key
+   * succeeds and changes nothing. A key the platform manages is refused with
+   * `FORBIDDEN`, deleted or not. Needs `kms.key.delete` on the project.
+   */
+  async deleteKey(request: DeleteKeyRequest, options?: CallOptions): Promise<Key> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<Key>(
+      {
+        method: "DELETE",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Restores a deleted key whose material isn't destroyed yet: it becomes
+   * `DISABLED`, to be enabled with UpdateKey. Refused with `CONFLICT` for a
+   * key that isn't deleted, or whose `purgeTime` has passed, and with
+   * `FORBIDDEN` for a key the platform manages. Needs `kms.key.delete` on
+   * the project.
+   */
+  async undeleteKey(request: UndeleteKeyRequest, options?: CallOptions): Promise<Key> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<Key>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:undelete`,
+        body: request,
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Adds a new version to a key and makes it the primary: new ciphertexts
+   * and signatures use it, and every earlier version still decrypts and
+   * its public key stays readable. Refused with `CONFLICT` for a key that
+   * isn't enabled, and with `FORBIDDEN` for a key the platform manages.
+   * Needs `kms.key.rotate` on the project.
+   */
+  async rotateKey(request: RotateKeyRequest, options?: CallOptions): Promise<Key> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<Key>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:rotate`,
+        body: request,
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Encrypts up to 64 KiB with an `ENCRYPT_DECRYPT` key's primary version,
+   * bound to the encryption context. For more data, encrypt it yourself
+   * with a data key from GenerateDataKey. Refused with `CONFLICT` for a key
+   * that isn't enabled, and with `BAD_REQUEST` for a signing key. Needs
+   * `kms.key.encrypt` on the project.
+   */
+  async encrypt(request: EncryptRequest, options?: CallOptions): Promise<EncryptResponse> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<EncryptResponse>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:encrypt`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Decrypts a ciphertext Encrypt or GenerateDataKey made with this key,
+   * given the same encryption context. Refused with `BAD_REQUEST` for a
+   * ciphertext that doesn't decrypt under this key and context, and with
+   * `CONFLICT` for a key that isn't enabled. Needs `kms.key.decrypt` on the
+   * project.
+   */
+  async decrypt(request: DecryptRequest, options?: CallOptions): Promise<DecryptResponse> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<DecryptResponse>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:decrypt`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Returns a new random 256-bit data key, in plaintext and encrypted under
+   * an `ENCRYPT_DECRYPT` key's primary version with the encryption context.
+   * Encrypt your data with the plaintext, keep only the ciphertext beside
+   * it, and recover the data key with Decrypt when you need it. Needs
+   * `kms.key.generate_data_key` on the project.
+   */
+  async generateDataKey(request: GenerateDataKeyRequest, options?: CallOptions): Promise<GenerateDataKeyResponse> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<GenerateDataKeyResponse>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:generateDataKey`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Signs up to 64 KiB with a signing key's primary version, or the
+   * version `keyVersion` names. ECDSA hashes
+   * the data with SHA-256 itself: send the data, not a digest. Refused with
+   * `CONFLICT` for a key that isn't enabled, and with `BAD_REQUEST` for an
+   * `ENCRYPT_DECRYPT` key. Needs `kms.key.sign` on the project.
+   */
+  async sign(request: SignRequest, options?: CallOptions): Promise<SignResponse> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*");
+    return this.service.call<SignResponse>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:sign`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Returns a signing key version's public key, to verify its signatures
+   * with. Answered for a disabled or deleted key too, until its material is
+   * destroyed. Refused with `BAD_REQUEST` for an `ENCRYPT_DECRYPT` key.
+   * Needs `kms.key.get_public_key` on the project.
+   */
+  async getPublicKey(request: GetPublicKeyRequest, options?: CallOptions): Promise<PublicKey> {
+    const p0 = pathValue("name", request.name, "projects/*/regions/*/keys/*/versions/*/publicKey");
+    return this.service.call<PublicKey>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * A key: its versions' material is kept by the platform and never leaves
+ * it.
+ */
+export interface Key {
+  /** The key's resource name. */
+  name?: string;
+  /** What the key is for. */
+  purpose?: Key_Purpose;
+  /**
+   * Whether the key can be used. A new key is `ENABLED`; UpdateKey sets it
+   * to `ENABLED` or `DISABLED`, and DeleteKey makes it `DELETED`.
+   */
+  state?: Key_State;
+  /** The version new ciphertexts and signatures use. */
+  primaryVersion?: string;
+  /** Every version, oldest first. RotateKey adds one. */
+  versions?: Key_Version[];
+  /** When the key was created. */
+  createTime?: string;
+  /** When the key last changed. */
+  updateTime?: string;
+  /**
+   * When a deleted key's material is destroyed, or was; unset unless the
+   * key is `DELETED`.
+   */
+  purgeTime?: string;
+  /**
+   * Labels of your own, at most 50. The `origin:name` tag is the name the
+   * console shows.
+   */
+  tags?: Record<string, string>;
+  /**
+   * Whether the platform manages the key: it made the key in your project
+   * for its own use of the project's data, such as the key, tagged
+   * `origin:name=volumes`, that protects your volumes' data keys. You see it,
+   * its grants and its audit log entries like any key of yours, but
+   * UpdateKey, DeleteKey, UndeleteKey and RotateKey refuse it with
+   * `FORBIDDEN`, whatever roles you hold.
+   */
+  platformManaged?: boolean;
+}
+
+/** What a key is for, and the algorithm it uses. */
+export const Key_Purpose = {
+  /** Not set. */
+  PURPOSE_UNSPECIFIED: "PURPOSE_UNSPECIFIED",
+  /** Encrypt, Decrypt and GenerateDataKey, with AES-256-GCM-SIV. */
+  ENCRYPT_DECRYPT: "ENCRYPT_DECRYPT",
+  /** Sign with ECDSA over P-256 and SHA-256; signatures are ASN.1 DER. */
+  SIGN_ECDSA_P256_SHA256: "SIGN_ECDSA_P256_SHA256",
+  /** Sign with Ed25519; signatures are 64 bytes. */
+  SIGN_ED25519: "SIGN_ED25519",
+} as const;
+
+/** What a key is for, and the algorithm it uses. */
+export type Key_Purpose = (typeof Key_Purpose)[keyof typeof Key_Purpose];
+
+/** Whether a key can be used. */
+export const Key_State = {
+  /** Not set. */
+  STATE_UNSPECIFIED: "STATE_UNSPECIFIED",
+  /** Serves every operation of its purpose. */
+  ENABLED: "ENABLED",
+  /** Refuses every operation but GetPublicKey until enabled again. */
+  DISABLED: "DISABLED",
+  /**
+   * Deleted: refuses every operation but GetPublicKey. Until
+   * `purgeTime` UndeleteKey restores it; after it, its material is
+   * destroyed.
+   */
+  DELETED: "DELETED",
+} as const;
+
+/** Whether a key can be used. */
+export type Key_State = (typeof Key_State)[keyof typeof Key_State];
+
+/** A version of the key: one generation of its material. */
+export interface Key_Version {
+  /**
+   * The version's resource name,
+   * `projects/{project}/regions/{region}/keys/{key}/versions/{version}`,
+   * numbered from 1.
+   */
+  keyVersion?: string;
+  /** When the version was created. */
+  createTime?: string;
+}
+
+/** A signing key version's public key. */
+export interface PublicKey {
+  /**
+   * The public key's resource name: its version's, followed by
+   * `/publicKey`.
+   */
+  name?: string;
+  /** The algorithm the key version signs with. */
+  algorithm?: Key_Purpose;
+  /**
+   * The public key as a PEM-encoded SubjectPublicKeyInfo, which OpenSSL and
+   * most libraries read.
+   */
+  pem?: string;
+}
+
+/** The request for GetKey. */
+export interface GetKeyRequest {
+  /** The key to return. */
+  name?: string;
+}
+
+/** The request for ListKeys. */
+export interface ListKeysRequest {
+  /**
+   * The project and region whose keys to list,
+   * `projects/{project}/regions/{region}`.
+   */
+  parent?: string;
+  /**
+   * The most keys to return; the server clamps it, and 0 means its
+   * default.
+   */
+  pageSize?: number;
+  /** A previous response's `nextPageToken`, for the page after it. */
+  pageToken?: string;
+  /** Whether deleted keys are listed too. */
+  showDeleted?: boolean;
+}
+
+/** The response for ListKeys. */
+export interface ListKeysResponse {
+  /** The keys on this page. */
+  keys?: Key[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}
+
+/** The request for CreateKey. */
+export interface CreateKeyRequest {
+  /**
+   * The project and region to create the key in,
+   * `projects/{project}/regions/{region}`.
+   */
+  parent?: string;
+  /** The key to create: its `purpose`, and optionally its tags. */
+  key?: Key;
+  /**
+   * A UUID; a repeat with the same id within a day returns the key the
+   * first request created, as it was then, instead of creating a second
+   * one.
+   */
+  requestId?: string;
+}
+
+/** The request for UpdateKey. */
+export interface UpdateKeyRequest {
+  /**
+   * The key, by its name, with the state to set (`ENABLED` or `DISABLED`)
+   * or the tags to replace its tags with.
+   */
+  key?: Key;
+  /** The fields to change: `state`, `tags`, or both. `*` is both. */
+  updateMask?: string;
+  /**
+   * A UUID; a repeat with the same id within a day returns the key as the
+   * first request left it, instead of changing it again.
+   */
+  requestId?: string;
+}
+
+/** The request for DeleteKey. */
+export interface DeleteKeyRequest {
+  /** The key to delete. */
+  name?: string;
+  /**
+   * How long until the key's material is destroyed: whole days, from 1 to
+   * 90; 30 days when unset.
+   */
+  destroyDelay?: string;
+  /**
+   * A UUID; a repeat with the same id within a day returns the key as the
+   * first request left it.
+   */
+  requestId?: string;
+}
+
+/** The request for UndeleteKey. */
+export interface UndeleteKeyRequest {
+  /** The deleted key to restore. */
+  name?: string;
+  /**
+   * A UUID; a repeat with the same id within a day returns the key as the
+   * first request left it, instead of answering `CONFLICT`.
+   */
+  requestId?: string;
+}
+
+/** The request for RotateKey. */
+export interface RotateKeyRequest {
+  /** The key to rotate. */
+  name?: string;
+  /**
+   * A UUID; a repeat with the same id within a day returns the key as the
+   * first request left it, instead of adding another version.
+   */
+  requestId?: string;
+}
+
+/** The request for Encrypt. */
+export interface EncryptRequest {
+  /** The `ENCRYPT_DECRYPT` key to encrypt with. */
+  name?: string;
+  /** The data to encrypt, at most 64 KiB. */
+  plaintext?: string;
+  /**
+   * Pairs bound into the ciphertext, which Decrypt must be given again,
+   * exactly. They aren't secret: the audit log records them. At most 16
+   * pairs, each key and value 1 to 256 bytes.
+   */
+  encryptionContext?: Record<string, string>;
+}
+
+/** The response for Encrypt. */
+export interface EncryptResponse {
+  /** The ciphertext, to store and pass to Decrypt. */
+  ciphertext?: string;
+  /** The key version that encrypted it. */
+  keyVersion?: string;
+}
+
+/** The request for Decrypt. */
+export interface DecryptRequest {
+  /** The key the ciphertext was made with. */
+  name?: string;
+  /** What Encrypt or GenerateDataKey returned as `ciphertext`. */
+  ciphertext?: string;
+  /** The encryption context the ciphertext was made with. */
+  encryptionContext?: Record<string, string>;
+}
+
+/** The response for Decrypt. */
+export interface DecryptResponse {
+  /** The decrypted data. */
+  plaintext?: string;
+  /** The key version that decrypted it. */
+  keyVersion?: string;
+}
+
+/** The request for GenerateDataKey. */
+export interface GenerateDataKeyRequest {
+  /** The `ENCRYPT_DECRYPT` key to encrypt the data key with. */
+  name?: string;
+  /** Pairs bound into the data key's ciphertext, as Encrypt's. */
+  encryptionContext?: Record<string, string>;
+}
+
+/** The response for GenerateDataKey. */
+export interface GenerateDataKeyResponse {
+  /** The 32-byte data key. Use it, then discard it: never store it. */
+  plaintext?: string;
+  /**
+   * The data key encrypted under the key, to store beside your data and
+   * pass to Decrypt.
+   */
+  ciphertext?: string;
+  /** The key version that encrypted it. */
+  keyVersion?: string;
+}
+
+/** The request for Sign. */
+export interface SignRequest {
+  /** The signing key to sign with. */
+  name?: string;
+  /** The data to sign, at most 64 KiB. */
+  data?: string;
+  /**
+   * The version of `name` to sign with, `{name}/versions/{version}`.
+   * Without it, the key's primary version signs. Name it when the
+   * signature's verifiers must know the version before the signature
+   * exists, for example a token whose header names its key: the primary
+   * can change between reading it and signing. Refused with `BAD_REQUEST`
+   * for a version of another key or a destroyed version.
+   */
+  keyVersion?: string;
+}
+
+/** The response for Sign. */
+export interface SignResponse {
+  /** The signature: ASN.1 DER for ECDSA, 64 bytes for Ed25519. */
+  signature?: string;
+  /** The key version that signed, whose public key verifies it. */
+  keyVersion?: string;
+}
+
+/** The request for GetPublicKey. */
+export interface GetPublicKeyRequest {
+  /**
+   * The public key to return: a key version's name followed by
+   * `/publicKey`.
+   */
+  name?: string;
+}