google-cloud 0.0.1-preview.1

Google Cloud clients: Firestore, Cloud Storage, Cloud DNS and Cloud KMS

Readme Files Dependencies Versions

google-cloud#

Google Cloud client libraries for Zena, built on wasi:http and @zena/protobuf so they compile for WebAssembly component targets as well as the zena CLI host.

Installation#

zena pkg add @zena/google-cloud

Libraries#

  • google-cloud/firestore — Firestore document, collection, query, batch, and transaction client.
  • google-cloud/storage — Cloud Storage client for reading, writing, stating, and deleting objects.
  • google-cloud/dns — Cloud DNS client for managing record sets in a managed zone.
  • google-cloud/kms — Cloud KMS client for asymmetric signing and symmetric encryption/decryption.
  • google-cloud/auth — Default credentials and project ID discovery from the GCE metadata server or environment variables.
  • google-cloud/firestore-v1 and google-cloud/storage-v2 — Generated protobuf messages and low-level service clients for google.firestore.v1 and google.storage.v2.
  • google-cloud/testing/fake-kms and google-cloud/testing/firestore-emulator — Test helpers for in-process fake Cloud KMS and the Firestore emulator.

Firestore#

import { Direction, Fields, Firestore, Operator, integerValue } from 'google-cloud/firestore';

let db = await Firestore.connect();

let post = db.collection('posts').doc('hello');
await post.set(new Fields().string('title', 'Hello').integer('views', 0));

let snapshot = await post.get();
if (let (true, views) = snapshot.getInteger('views')) {
  await post.update(new Fields().integer('views', views + 1));
}

let popular = await db.collection('posts')
  .where('views', Operator.GreaterThan, integerValue(100))
  .orderBy('views', Direction.Descending)
  .limit(10)
  .get();
for (let p in popular) {
  console.log(p.id);
}

Firestore.connect() discovers the project and credentials as described under Credentials and talks gRPC to the API. new Firestore({projectId, databaseId?, transport}) accepts explicit configuration instead.

  • References: db.collection(path), db.doc(path), collection.doc(id), doc.collection(id). collection.add(fields) creates a document with a random ID.
  • Writes: set replaces a document, create fails with ALREADY_EXISTS when it exists, update sets the named top-level fields and fails with NOT_FOUND when it does not exist, and delete removes it. Errors are RpcErrors carrying the google.rpc.Code.
  • Transforms (applied by the server when the write commits): Fields.serverTimestamp, increment, incrementDouble, maximum, minimum, arrayUnion, and arrayRemove. In an update, deleteField removes a field. They apply to top-level fields and work in batches and transactions as well: post.update(new Fields().increment('views', 1).serverTimestamp('seen')).
  • Reads: get() returns a DocumentSnapshot, whose exists is false for a missing document. getString, getInteger, getDouble, and getBoolean take a field path such as author.name and return (true, value) or (false, _) when the field is absent or of another type. get(path) returns the raw Value. db.getAll(refs) reads several documents in one call in the order given.
  • Queries: where, orderBy, limit, offset, and select each return a new query. get() collects the results; stream() yields each document as it arrives (for await); count() counts them on the server.
  • Cursors: startAt, startAfter, endAt, and endBefore take values for the orderings or a DocumentSnapshot.
  • Batches & Transactions: db.batch() collects writes and commits them in one call. db.runTransaction(body) runs body with a Transaction, retrying up to five times on contention and rolling back if body throws.
  • Deadlines: Firestore.connect({timeout: milliseconds(10000)}) gives each call a deadline, failing with DEADLINE_EXCEEDED if exceeded.
let total = await db.runTransaction<i64>(async (tx: Transaction): Future<i64> => {
  let counter = db.doc('counters/visits');
  let snapshot = await tx.get(counter);
  var n: i64 = 0;
  if (let (true, stored) = snapshot.getInteger('n')) {
    n = stored;
  }
  tx.set(counter, new Fields().integer('n', n + 1));
  return n + 1;
});

Transports & Emulator#

  • Firestore.connect() uses gRPC (protobuf/grpc) over HTTP/2. When FIRESTORE_EMULATOR_HOST is set to host:port, Firestore.connect() connects to the Firestore emulator over cleartext HTTP/2 with the owner token.
  • Firestore.connectFallback() uses Google's gRPC fallback protocol (protobuf/fallback), which works on HTTP/1.1-only wasi:http hosts such as stock wasmtime serve.
  • new Firestore({projectId, transport}) accepts any ProtoTransport.

Cloud Storage#

import { Storage } from 'google-cloud/storage';

let bucket = Storage.connect().bucket('my-bucket');
await bucket.write('notes/hello.txt', bytes, 'text/plain');
let read = await bucket.read('notes/hello.txt'); // null when absent
let object = await bucket.stat('notes/hello.txt'); // metadata, or null
await bucket.delete('notes/hello.txt'); // true if deleted

Storage.connect() uses the default credentials and talks gRPC to the Cloud Storage API (write streams data in chunks of at most 2 MiB). new Storage(transport) accepts any ProtoTransport, and storage.client exposes the generated StorageClient.

Cloud DNS#

import { CloudDns, RecordSet } from 'google-cloud/dns';

let zone = CloudDns.connect('my-project', 'my-zone');
await zone.put(new RecordSet('_atproto.alice.example.com.', 'TXT', 300, ['"did=did:plc:..."']));
let set = await zone.get('_atproto.alice.example.com.', 'TXT'); // null when absent
await zone.delete('_atproto.alice.example.com.', 'TXT'); // true if deleted

CloudDns uses the Cloud DNS REST API (https://dns.googleapis.com/dns/v1) with default credentials. Names are fully qualified (ending in a .), and put creates or replaces the record set of that name and type.

Cloud KMS#

import { sha256 } from 'zena:crypto';
import { CloudKms, ecPointFromPem } from 'google-cloud/kms';

// Asymmetric signing
let signingKey = CloudKms.connect(
  'projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1'
);
let derSignature = await signingKey.asymmetricSign(sha256(message));
let pubKey = await signingKey.publicKey();
let uncompressedPoint = ecPointFromPem(pubKey.pem);

// Symmetric encryption (AEAD)
let symmetricKey = CloudKms.connect('projects/p/locations/l/keyRings/r/cryptoKeys/s');
let ciphertext = await symmetricKey.encrypt(plaintext, additionalData);
let decrypted = await symmetricKey.decrypt(ciphertext, additionalData);

Credentials#

defaultCredentials() (google-cloud/auth):

  • GOOGLE_OAUTH_ACCESS_TOKEN, when set in the environment, is used directly (for local runs: GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)).
  • Otherwise, the GCE metadata server (at GCE_METADATA_HOST when set, or metadata.google.internal) supplies tokens for the default service account, caching each token until a minute before it expires.

defaultProjectId() reads GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT when set, falling back to the metadata server.

License#

MIT

8.3 KiB Raw
/**
 * A Cloud KMS client, over the REST API
 * (`https://cloudkms.googleapis.com/v1`), for signing with an asymmetric
 * key version and for encrypting with a symmetric key. Neither key ever
 * leaves Cloud KMS, which signs a digest, or encrypts and decrypts a
 * value, on request.
 *
 *     let key = CloudKms.connect('projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1');
 *     let der = await key.asymmetricSign(sha256(message));
 *     let publicKey = await key.publicKey();
 *
 *     let symmetric = CloudKms.connect('projects/p/locations/l/keyRings/r/cryptoKeys/s');
 *     let ciphertext = await symmetric.encrypt(secret, additionalData);
 *     let plaintext = await symmetric.decrypt(ciphertext, additionalData);
 *
 * A signature comes back DER-encoded (`zena:crypto`'s
 * `signatureFromDer` reads it), and a public key as PEM, which
 * `ecPointFromPem` reads. Each call asks its `Credentials` for an access
 * token, with the `cloud-platform` or `cloudkms` scope; the caller needs
 * `roles/cloudkms.signerVerifier` on a signing key, and
 * `roles/cloudkms.cryptoKeyEncrypterDecrypter` on a symmetric one.
 */

import {Future} from 'zena:async';
import {Own} from 'zena:core';
import {base64} from 'zena:encoding';
import {fetch, Response} from 'zena:fetch';
import {JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {Credentials} from 'protobuf/runtime';
import {defaultCredentials} from './auth.zena';

/** The origin of the Cloud KMS API. */
export let KMS_ORIGIN = 'https://cloudkms.googleapis.com';

/** An answer from Cloud KMS that is an error, with its HTTP status, or a key it cannot read. */
export class KmsError extends Error {
  status: i32;

  new(status: i32, message: String) : status = status, super(message);
}

/** A key version's public key, as Cloud KMS describes it. */
export final class KmsPublicKey {
  /** Such as `EC_SIGN_SECP256K1_SHA256` or `EC_SIGN_P256_SHA256`. */
  algorithm: String;
  /** The SubjectPublicKeyInfo, PEM-encoded. */
  pem: String;

  new(this.algorithm, this.pem);
}

/**
 * One key: an asymmetric signing key version, to sign with, or a
 * symmetric key, to encrypt and decrypt with.
 */
export final class CloudKms {
  #origin: String;
  #credentials: Credentials;
  /**
   * `projects/…/cryptoKeys/<key>/cryptoKeyVersions/<n>` for a signing key
   * version, and `projects/…/cryptoKeys/<key>` for a symmetric key, whose
   * primary version encrypts.
   */
  name: String;

  /**
   * The key version `name`, at `origin`, the API's own (`KMS_ORIGIN`)
   * unless a test serves it.
   */
  new(name: String, credentials: Credentials, origin: String = 'https://cloudkms.googleapis.com')
      : name = name, #credentials = credentials, #origin = origin;

  /** The key version with the default credentials (see `defaultCredentials`). */
  static connect(name: String): CloudKms {
    return new CloudKms(name, defaultCredentials());
  }

  /** The DER-encoded signature of the 32-byte SHA-256 `digest`. */
  async asymmetricSign(digest: FixedArray<u8>): Future<FixedArray<u8>> {
    let request = new JsonObject();
    let sha = new JsonObject();
    sha['sha256'] = base64.encode(digest);
    request['digest'] = sha;
    let response = await this.#call('POST', `/v1/${this.name}:asymmetricSign`, stringify(request));
    let answer = jsonObject(await checked(response, 'signing'));
    let signature = answer['signature'];
    if (!(signature is String)) {
      throw new KmsError(0, 'Cloud KMS answered asymmetricSign without a signature');
    }
    return base64.decode(signature);
  }

  /**
   * `plaintext`, at most 64 KiB, encrypted with the symmetric key, and
   * bound to `additionalData`, which is not encrypted, and which
   * decrypting needs too.
   */
  async encrypt(plaintext: FixedArray<u8>, additionalData: FixedArray<u8>): Future<FixedArray<u8>> {
    let request = new JsonObject();
    request['plaintext'] = base64.encode(plaintext);
    request['additionalAuthenticatedData'] = base64.encode(additionalData);
    let response = await this.#call('POST', `/v1/${this.name}:encrypt`, stringify(request));
    let answer = jsonObject(await checked(response, 'encrypting'));
    let ciphertext = answer['ciphertext'];
    if (!(ciphertext is String)) {
      throw new KmsError(0, 'Cloud KMS answered encrypt without a ciphertext');
    }
    return base64.decode(ciphertext);
  }

  /**
   * `ciphertext`, from `encrypt` with the same `additionalData`,
   * decrypted. Throws `KmsError` with status 400 for a ciphertext that is
   * not one, or other additional data.
   */
  async decrypt(ciphertext: FixedArray<u8>, additionalData: FixedArray<u8>): Future<FixedArray<u8>> {
    let request = new JsonObject();
    request['ciphertext'] = base64.encode(ciphertext);
    request['additionalAuthenticatedData'] = base64.encode(additionalData);
    let response = await this.#call('POST', `/v1/${this.name}:decrypt`, stringify(request));
    let answer = jsonObject(await checked(response, 'decrypting'));
    let plaintext = answer['plaintext'];
    // An empty plaintext comes back without the member.
    return if (plaintext is String) base64.decode(plaintext) else new FixedArray<u8>(0, 0 as u8);
  }

  /** The key version's public key. */
  async publicKey(): Future<KmsPublicKey> {
    let response = await this.#call('GET', `/v1/${this.name}/publicKey`, null);
    let answer = jsonObject(await checked(response, 'reading the public key'));
    let algorithm = answer['algorithm'];
    let pem = answer['pem'];
    if (!(algorithm is String) || !(pem is String)) {
      throw new KmsError(0, 'Cloud KMS answered getPublicKey without an algorithm and a PEM');
    }
    return new KmsPublicKey(algorithm, pem);
  }

  async #call(method: String, path: String, body: String | null): Future<Own<Response>> {
    let headers = new GrowableArray<(String, String)>();
    headers.push(('accept', 'application/json'));
    if (body != null) {
      headers.push(('content-type', 'application/json'));
    }
    let authorization = await this.#credentials.authorization();
    if (authorization != null) {
      headers.push(('authorization', authorization));
    }
    return try {
      await fetch(`${this.#origin}${path}`, {method, headers, body})
    } catch (e) {
      throw new KmsError(0, e.message)
    };
  }
}

/**
 * The uncompressed SEC1 point (`04`, x, y) of an elliptic-curve
 * SubjectPublicKeyInfo in PEM, as Cloud KMS gives it: the contents of its
 * closing BIT STRING. Throws `KmsError` for anything else.
 */
export function ecPointFromPem(pem: String): FixedArray<u8> {
  var body = '';
  for (let line in pem.split('\n')) {
    let trimmed = line.trim();
    if (trimmed.length > 0 && !trimmed.startsWith('-----')) {
      body = `${body}${trimmed}`;
    }
  }
  var der = new FixedArray<u8>(0, 0 as u8);
  try {
    der = base64.decode(body);
  } catch (e) {
    throw new KmsError(0, 'the public key is not PEM');
  }
  // SEQUENCE { SEQUENCE { algorithm, curve }, BIT STRING { 0 unused bits, point } }:
  // for P-256 and secp256k1 the point is the last 65 bytes, after 03 42 00.
  let n = der.length;
  if (n < 68 || der[0] != (0x30 as u8) || der[n - 68] != (0x03 as u8) || der[n - 67] != (0x42 as u8) ||
      der[n - 66] != (0 as u8) || der[n - 65] != (0x04 as u8)) {
    throw new KmsError(0, 'the public key is not an uncompressed P-256 or secp256k1 point');
  }
  let point = new FixedArray<u8>(65, 0 as u8);
  for (var i = 0; i < 65; i += 1) {
    point[i] = der[n - 65 + i];
  }
  return point;
}

function jsonObject(text: String): JsonObject {
  let json = try {
    parseJson(text)
  } catch (e) {
    null
  };
  if (!(json is JsonObject)) {
    throw new KmsError(0, 'Cloud KMS answered with something other than a JSON object');
  }
  return json;
}

/** Returns `response`'s body text when it is a success, or throws `KmsError` naming what `doing` was. */
async function checked(response: Own<Response>, doing: String): Future<String> {
  let status = response.status;
  let text = await response.text();
  if (status >= 200 && status < 300) {
    return text;
  }
  var message = text;
  let json = try {
    parseJson(text)
  } catch (e) {
    null
  };
  if (json is JsonObject) {
    let error = json['error'];
    if (error is JsonObject) {
      let detail = error['message'];
      if (detail is String) {
        message = detail;
      }
    }
  }
  throw new KmsError(status, `Cloud KMS, ${doing}: HTTP ${status}: ${message}`);
}
  • protobuf protobuf.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19
  • protobuf protobuf.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1