GCS

Server Source code Package

Google Cloud Storage store with zero runtime dependencies. Uses raw fetch against the GCS JSON API with built-in auth: Application Default Credentials (ADC) on Cloud Run / GKE, or explicit service account JWT for non-GCP environments.

Installation

Loading...

Integrated

Loading...

Bundled

Add to your flow.json:

Loading...

Configuration

This store uses the standard store config wrapper (consent, data, env, id, ...). For the shared fields see store configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description	More
bucket*	string	GCS bucket name
prefix	string	Key prefix prepended to all store keys for scoping
credentials	string | object	Service account JSON (string or object). Omit for ADC on Cloud Run/GKE

* Required fields

Mapping

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

Prefix scoping

Key "walker.js" with prefix "public/" resolves to GCS path "public/walker.js"

Event

Out

Read with ADC

Read object from GCS bucket using ADC — no credentials needed

Event

Out

Provisioning

The package ships an idempotent setup() lifecycle that creates the GCS bucket described in flow config. It is invoked only by the explicit operator command:

Loading...

It never runs automatically and never alters an existing bucket.

Setup options

Option	Type	Default	Notes
projectId	string	(resolved)	GCP project that owns the bucket. Resolution order below.
location	string	'EU'	Multi-region or regional location.
storageClass	'STANDARD' | 'NEARLINE' | 'COLDLINE' | 'ARCHIVE'	'STANDARD'	Default object storage class.
versioning	boolean	false	Object versioning. Off by default; opt in.
lifecycle	{ rule: unknown[] }	(none)	Applied at create. Drift detection NOT included for lifecycle.
kmsKeyName	string	(none)	Customer-managed encryption key (CMEK) at create time.
labels	Record<string, string>	(none)	Cost-allocation labels.

bucket is taken from settings.bucket and is NOT duplicated under setup.

projectId resolution

The GCS create call requires a project. Resolution order:

1. Explicit setup.projectId.
2. project_id field inside the settings.credentials service-account JSON.
3. process.env.GOOGLE_CLOUD_PROJECT (Cloud Run / GKE convention).
4. Throws with an actionable error if none of the above is available.

Behavior

• Idempotent: HTTP 409 (bucket exists) is treated as success. The setup never patches or mutates an existing bucket.
• Drift detection: when the bucket already exists, setup performs a GET /b/<bucket> and logs WARN setup.drift { field, declared, actual } for any of location, storageClass, versioning, iamConfiguration (uniform bucket-level access, public access prevention), and labels that do not match. Drift is logged, never auto-fixed.
• Defaults enforced at create: uniform bucket-level access on, public access prevention enforced. These are baked in by the package.

Runtime hard-fail

At runtime, the first get / set / delete call issues a single HEAD /b/<bucket> per process per bucket. On 404, it throws with an actionable message:

Loading...

Operators see the error pointing at the exact command to fix it. Subsequent operations in the same process skip the check via an in-memory cache.

Authentication

Cloud Run / GKE (ADC)

When running on GCP infrastructure, omit credentials. The store fetches access tokens from the metadata server automatically, with no configuration needed.

Non-GCP (service account)

Pass a service account JSON via $env. reference. The store signs JWTs locally using node:crypto and exchanges them for access tokens via Google's OAuth2 endpoint.

Loading...

The GCS_SA_KEY environment variable should contain the full service account JSON (with client_email and private_key fields).

File serving pattern

The primary use case is serving static files via the file transformer:

Loading...

A request to /static/walker.js looks up public/walker.js in the my-assets bucket.

Security

• Key validation: Path traversal attempts (.., absolute paths) are rejected
• Prefix scoping: The prefix setting restricts all operations to a subdirectory
• No ambient credentials: ADC only works on GCP infrastructure; off-GCP requires explicit SA JSON

API

Loading...

get() returns Buffer for compatibility with the file transformer, which uses content instanceof Buffer for Content-Length calculation.