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

7.3 KiB Raw
/**
 * A fake Cloud KMS, served by `zena:http` in the same program, for tests
 * of code that signs or encrypts through `google-cloud/kms`. It answers
 * asymmetricSign and getPublicKey for one secp256k1 key version, as Cloud
 * KMS may, with DER signatures whose s is high, and encrypt and decrypt
 * for one symmetric key, and refuses any token but `token`.
 *
 * Its encryption only has to be what the tests check: a ciphertext that
 * does not hold the plaintext, and that decrypts only with the same
 * additional data. It is a SHA-256 keystream, not a cipher to keep
 * anything with.
 */

import {Future} from 'zena:async';
import {Own} from 'zena:core';
import {secp256k1, sha256} from 'zena:crypto';
import {base64, hex} from 'zena:encoding';
import {App, Server} from 'zena:http';
import {JsonObject, parseJson, stringify} from 'zena:json';

/** The key version's name. */
export let FAKE_KMS_KEY = 'projects/p/locations/global/keyRings/r/cryptoKeys/rotation/cryptoKeyVersions/1';
/** Its private key. */
export let FAKE_KMS_PRIVATE_KEY = hex.decode('c9afa9d845ba75166b5c215767b1d6934e50c3db36e89b127b8a622b120f6721');
/** The symmetric key's name. */
export let FAKE_KMS_CRYPTO_KEY = 'projects/p/locations/global/keyRings/r/cryptoKeys/signing-keys';
/** What the symmetric key's keystream and tags are made from. */
let SYMMETRIC_SECRET = hex.decode('5eb63bbbe01eeed093cb22bb8f5acdc35eb63bbbe01eeed093cb22bb8f5acdc3');
let ORDER = hex.decode('fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141');
/** A secp256k1 SubjectPublicKeyInfo, up to the point. */
let SPKI_PREFIX = '3056301006072a8648ce3d020106052b8104000a034200';

/** `a` then `b`. */
function join(a: FixedArray<u8>, b: FixedArray<u8>) {
  let out = new FixedArray<u8>(a.length + b.length, 0 as u8);
  for (var i = 0; i < a.length; i += 1) {
    out[i] = a[i];
  }
  for (var i = 0; i < b.length; i += 1) {
    out[a.length + i] = b[i];
  }
  return out;
}

/** `n - x` for 32-byte big-endian numbers. */
function subtractFrom(n: FixedArray<u8>, x: FixedArray<u8>) {
  let out = new FixedArray<u8>(32, 0 as u8);
  var borrow = 0;
  for (var i = 31; i >= 0; i -= 1) {
    var d = (n[i] as i32) - (x[i] as i32) - borrow;
    borrow = if (d < 0) 1 else 0;
    if (d < 0) {
      d += 256;
    }
    out[i] = d as u8;
  }
  return out;
}

/** A DER INTEGER of a 32-byte number, with a leading zero byte always. */
function derInteger(value: FixedArray<u8>) {
  let head = new FixedArray<u8>(3, 0 as u8);
  head[0] = 0x02 as u8;
  head[1] = 33 as u8;
  return join(head, value);
}

/** The fake signs as Cloud KMS may: in DER, with the high-S twin of its signature. */
function highSDer(digest: FixedArray<u8>) {
  let signature = secp256k1.signDigest(FAKE_KMS_PRIVATE_KEY, digest);
  let body = join(derInteger(signature[0..32]), derInteger(subtractFrom(ORDER, signature[32..64])));
  let head = new FixedArray<u8>(2, 0 as u8);
  head[0] = 0x30 as u8;
  head[1] = body.length as u8;
  return join(head, body);
}

/** `bytes` XORed with the keystream for `additionalData`. */
function keystreamed(bytes: FixedArray<u8>, additionalData: FixedArray<u8>) {
  let out = new FixedArray<u8>(bytes.length, 0 as u8);
  for (var block = 0; block * 32 < bytes.length; block += 1) {
    let counter = new FixedArray<u8>(1, block as u8);
    let stream = sha256(join(join(SYMMETRIC_SECRET, additionalData), counter));
    for (var i = 0; i < 32 && block * 32 + i < bytes.length; i += 1) {
      out[block * 32 + i] = (bytes[block * 32 + i] ^ stream[i]) as u8;
    }
  }
  return out;
}

/** The tag that binds `plaintext` to `additionalData`. */
function tagOf(plaintext: FixedArray<u8>, additionalData: FixedArray<u8>) {
  let length = new FixedArray<u8>(1, additionalData.length as u8);
  return sha256(join(join(join(SYMMETRIC_SECRET, length), additionalData), plaintext));
}

/** The tag, then the keystreamed plaintext. */
function fakeEncrypt(plaintext: FixedArray<u8>, additionalData: FixedArray<u8>) {
  return join(tagOf(plaintext, additionalData), keystreamed(plaintext, additionalData));
}

/** The plaintext of `ciphertext`, or null when it was not encrypted with `additionalData`. */
function fakeDecrypt(ciphertext: FixedArray<u8>, additionalData: FixedArray<u8>): FixedArray<u8> | null {
  if (ciphertext.length < 32) {
    return null;
  }
  let plaintext = keystreamed(ciphertext[32..ciphertext.length], additionalData);
  return if (hex.encode(tagOf(plaintext, additionalData)) == hex.encode(ciphertext[0..32])) plaintext else null;
}

/** The base64 member `name` of `body`, decoded; empty when it is missing. */
function bytesMember(body: JsonObject, name: String) {
  let value = body[name];
  return if (value is String) base64.decode(value) else new FixedArray<u8>(0, 0 as u8);
}

/** A started server for the keys; its origin is `http://127.0.0.1:<port>`. */
export function startFakeKms(): Own<Server> {
  let app = new App();
  app.use(async (req, res, next): Future<void> => {
    res.type = 'application/json';
    if (req.getHeader('authorization') != 'Bearer token') {
      res.statusCode = 403;
      res.body = '{"error":{"code":403,"message":"Permission denied on the key"}}';
      return;
    }
    if (req.method == 'POST' && req.path == `/v1/${FAKE_KMS_KEY}:asymmetricSign`) {
      let body = parseJson(await req.text()) as JsonObject;
      let digest = base64.decode((body['digest'] as JsonObject)['sha256'] as String);
      let answer = new JsonObject();
      answer['name'] = FAKE_KMS_KEY;
      answer['signature'] = base64.encode(highSDer(digest));
      res.body = stringify(answer);
      return;
    }
    if (req.method == 'POST' && req.path == `/v1/${FAKE_KMS_CRYPTO_KEY}:encrypt`) {
      let body = parseJson(await req.text()) as JsonObject;
      let answer = new JsonObject();
      answer['name'] = `${FAKE_KMS_CRYPTO_KEY}/cryptoKeyVersions/1`;
      answer['ciphertext'] = base64.encode(fakeEncrypt(bytesMember(body, 'plaintext'),
          bytesMember(body, 'additionalAuthenticatedData')));
      res.body = stringify(answer);
      return;
    }
    if (req.method == 'POST' && req.path == `/v1/${FAKE_KMS_CRYPTO_KEY}:decrypt`) {
      let body = parseJson(await req.text()) as JsonObject;
      let plaintext = fakeDecrypt(bytesMember(body, 'ciphertext'), bytesMember(body, 'additionalAuthenticatedData'));
      if (plaintext == null) {
        res.statusCode = 400;
        res.body = '{"error":{"code":400,"message":"Decryption failed: the ciphertext is invalid."}}';
        return;
      }
      let answer = new JsonObject();
      answer['plaintext'] = base64.encode(plaintext);
      res.body = stringify(answer);
      return;
    }
    if (req.method == 'GET' && req.path == `/v1/${FAKE_KMS_KEY}/publicKey`) {
      let spki = join(hex.decode(SPKI_PREFIX), secp256k1.publicKey(FAKE_KMS_PRIVATE_KEY, false));
      let encoded = base64.encode(spki);
      var pem = '-----BEGIN PUBLIC KEY-----\n';
      var at = 0;
      while (at < encoded.length) {
        let end = if (at + 64 < encoded.length) at + 64 else encoded.length;
        pem = `${pem}${encoded.sliceBytes(at, end)}\n`;
        at = end;
      }
      pem = `${pem}-----END PUBLIC KEY-----\n`;
      let answer = new JsonObject();
      answer['pem'] = pem;
      answer['algorithm'] = 'EC_SIGN_SECP256K1_SHA256';
      res.body = stringify(answer);
      return;
    }
    res.statusCode = 404;
    res.body = '{"error":{"code":404,"message":"not found"}}';
  });
  let server = new Server(app, 0 as u16);
  server.start();
  return server;
}

  • 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