Google Cloud Storage (GCS) Integration Guide

Connection Configuration

BurnLedger connects to GCS using a service account key with read-only permissions.

Configuration fields:

There is no project_id field — the project is taken from the service account key. These are the exact JSON keys the connector reads; they are snake_case in both SDKs — do not write credentialsJson or readOnly, since the connection object is sent to the API verbatim and unknown keys are ignored.

TypeScript

const system = await bl.registerSystem({
  name: "user-uploads-gcs",
  connectorType: "gcs",
  connectionConfig: {
    bucket: "myapp-user-uploads",
    // Raw service account JSON, e.g. fs.readFileSync("burnledger-key.json", "utf8")
    credentials_json: process.env.GCS_CREDENTIALS_JSON,
  },
  subjectQuery: "users/{identifier}/",
  hashScope: "existence",
});

Python

system = bl.register_system(
    name="user-uploads-gcs",
    connector_type="gcs",
    connection_config={
        "bucket": "myapp-user-uploads",
        # Raw service account JSON, e.g. open("burnledger-key.json").read()
        "credentials_json": os.environ["GCS_CREDENTIALS_JSON"],
    },
    subject_query="users/{identifier}/",
    hash_scope="existence",
)

Object Prefix Pattern

Same syntax as S3. Use {identifier} as the subject placeholder. The expanded string is used verbatim as the object-name prefix — there are no wildcards, and * is passed through as a literal character that will match nothing. A template with no {identifier} is rejected with INVALID_QUERY_TEMPLATE.

users/{identifier}/
uploads/{identifier}-
{identifier}/documents/

Service Account Setup

BurnLedger verifies that the credential cannot write to the bucket and rejects connections with write access — without ever writing. It calls Bucket.IAM().TestPermissions for storage.objects.create and storage.objects.delete, which evaluates the principal's IAM bindings without performing either action. If the principal would be granted a write permission, construction is refused.

This IAM test only runs against real GCS. On fake-gcs-server or other non-GCP S3/GCS-compatible endpoints there is no IAM to query, so verification cannot run — in that case set "read_only": true in the connector config to assert the credential is read-only (BurnLedger only ever reads regardless). Without a successful IAM test and without the assertion, construction is refused (fails closed).

Create a custom role

gcloud iam roles create burnledger_readonly \
  --project=myproject \
  --title="BurnLedger Read-Only" \
  --permissions=storage.objects.get,storage.objects.list,storage.buckets.get

Create a service account

# Create
gcloud iam service-accounts create burnledger-ro \
  --display-name="BurnLedger Read-Only"

# Bind the custom role to the bucket
gsutil iam ch \
  serviceAccount:burnledger-ro@myproject.iam.gserviceaccount.com:projects/myproject/roles/burnledger_readonly \
  gs://myapp-user-uploads

# Generate the key
gcloud iam service-accounts keys create burnledger-key.json \
  --iam-account=burnledger-ro@myproject.iam.gserviceaccount.com

Pass the contents of burnledger-key.json as credentials_json verbatim. Do not base64-encode it — unlike the BigQuery connector, the GCS connector does no decoding and hands the string straight to the Google SDK.

Verify

# Should succeed
gsutil ls gs://myapp-user-uploads/users/test/

# Should fail with "AccessDeniedException: 403"
gsutil cp /dev/null gs://myapp-user-uploads/test-write

Retained copies and soft delete

A deleted object that is still recoverable has not been deleted, so BurnLedger will not certify zero over it. Retention state is probed at construction:

• Retention state cannot be determined (the credential lacks permission to read it, or the API call fails) → construction is refused. It is not assumed to be "not retained": assuming the safe-looking answer is exactly how a verification record gets signed over data that is still recoverable.
• Recoverable copies exist for the subject → attestation fails rather than reporting zero. Purge them, then re-run.

Soft delete is ON BY DEFAULT on this store, so a bucket or container nobody has explicitly configured will hit this. That is the control working — the data really is still recoverable — but it is a change in behaviour: previously only live objects were counted, and a subject with soft-deleted blobs would have been certified as having none.

Hash Scope Options

Composite and customer-managed-encryption objects may have no MD5 in their metadata; the md5 field is then the empty string, and the hash rests on the remaining four fields.

Troubleshooting