google-cloud 0.0.1-preview.1
Google Cloud clients: Firestore, Cloud Storage, Cloud DNS and Cloud KMS
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-v1andgoogle-cloud/storage-v2— Generated protobuf messages and low-level service clients forgoogle.firestore.v1andgoogle.storage.v2.google-cloud/testing/fake-kmsandgoogle-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:
setreplaces a document,createfails withALREADY_EXISTSwhen it exists,updatesets the named top-level fields and fails withNOT_FOUNDwhen it does not exist, anddeleteremoves it. Errors areRpcErrors carrying thegoogle.rpc.Code. - Transforms (applied by the server when the write commits):
Fields.serverTimestamp,increment,incrementDouble,maximum,minimum,arrayUnion, andarrayRemove. In anupdate,deleteFieldremoves 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 aDocumentSnapshot, whoseexistsisfalsefor a missing document.getString,getInteger,getDouble, andgetBooleantake a field path such asauthor.nameand return(true, value)or(false, _)when the field is absent or of another type.get(path)returns the rawValue.db.getAll(refs)reads several documents in one call in the order given. - Queries:
where,orderBy,limit,offset, andselecteach 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, andendBeforetake values for the orderings or aDocumentSnapshot. - Batches & Transactions:
db.batch()collects writes and commits them in one call.db.runTransaction(body)runsbodywith aTransaction, retrying up to five times on contention and rolling back ifbodythrows. - Deadlines:
Firestore.connect({timeout: milliseconds(10000)})gives each call a deadline, failing withDEADLINE_EXCEEDEDif 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. WhenFIRESTORE_EMULATOR_HOSTis set tohost:port,Firestore.connect()connects to the Firestore emulator over cleartext HTTP/2 with theownertoken.Firestore.connectFallback()uses Google's gRPC fallback protocol (protobuf/fallback), which works on HTTP/1.1-onlywasi:httphosts such as stockwasmtime serve.new Firestore({projectId, transport})accepts anyProtoTransport.
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_HOSTwhen set, ormetadata.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
/**
* 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
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 |
|
|