GCP Service Accounts & Workload IAM Matrix

The GERCIA Platform enforces strict Principle of Least Privilege (PoLP) across Google Cloud Platform (GCP). Every serverless service, background job, and edge component operates with a dedicated, isolated Service Account (SA) with permissions scoped strictly to the resources it requires.

In accordance with ADR-007, workloads running on Google Cloud Run execute using native Cloud Run Service Account attachment via Application Default Credentials (ADC metadata server). No static JSON private keys are ever stored on disk or embedded inside application containers, eliminating disk-compromise credential leakage vectors.

---

1. Workload IAM Architecture

flowchart TD
    subgraph GCP_IAM ["Google Cloud Platform IAM (Project: gercia-gcp / 621952369587)"]
        SA_SERVER["gercia-server-{prd,stg}<br>(Server Service Account)"]
        SA_JOB["gercia-migrator-{prd,stg}<br>(Migrator Job Service Account)"]
        SA_FIREBASE["firebase-adminsdk-fbsvc"]
        SA_ASSISTANT["gercia-assistant<br>(Commercial Assistant)"]
    end

    subgraph GCP_SERVICES ["Target Google Cloud & Google Workspace Services"]
        GSM["Google Secret Manager (GSM)<br>(Runtime credentials injection)"]
        GAR["Google Artifact Registry (GAR)<br>(Docker image pulls & pushes)"]
        CLOUDSQL["Google Cloud SQL for PostgreSQL<br>(Private IP VPC Peering)"]
        GCS_DOCS["GCS: gs://gercia-documents-{prd,stg}<br>(Sovereign Attachments Repository)"]
        FCM["Firebase Cloud Messaging (FCM)<br>(Mobile push notifications)"]
        GCAL["Google Calendar & Meet API<br>(Workspace Domain-Wide Delegation)"]
    end

    subgraph RUNTIME ["Execution Environments (Serverless Google Cloud Run)"]
        RUN_SERVER["Gercia.Server (Cloud Run Service • REST, STS, MCP)"]
        RUN_JOB["gercia-migrator (Cloud Run Job • --migrate)"]
        PAGES_FN["Cloudflare Pages Functions (Assistente GERCIA)"]
    end

    SA_SERVER --> GSM
    SA_SERVER --> CLOUDSQL
    SA_SERVER -- "roles/storage.objectUser" --> GCS_DOCS
    SA_JOB --> GSM
    SA_JOB --> CLOUDSQL
    SA_FIREBASE --> FCM
    SA_ASSISTANT --> GCAL

    SA_SERVER -. "Native Service Account Attachment" .-> RUN_SERVER
    SA_JOB -. "Native Service Account Attachment" .-> RUN_JOB
    SA_ASSISTANT -. "Encrypted Secret in Pages" .-> PAGES_FN

---

2. Official Service Accounts Inventory (gercia-gcp)

Service Account Email	Display Name	Operational Role	OAuth 2 Unique ID	Authentication & Execution Mode
gercia-server-prd@gercia-gcp.iam.gserviceaccount.com	gercia-server-prd	GERCIA Server PRD	113375797391591415959	Native Cloud Run Service Account (--service-account) for Gercia.Server
gercia-server-stg@gercia-gcp.iam.gserviceaccount.com	gercia-server-stg	GERCIA Server STG	102094089010967793596	Native Cloud Run Service Account (--service-account) for Gercia.Server
gercia-migrator-prd@gercia-gcp.iam.gserviceaccount.com	gercia-migrator-prd	GERCIA Migrator PRD	109220931877678621715	Native Cloud Run Job (--service-account) for gercia-migrator
gercia-migrator-stg@gercia-gcp.iam.gserviceaccount.com	gercia-migrator-stg	GERCIA Migrator STG	100313191815715880437	Native Cloud Run Job (--service-account) for gercia-migrator
firebase-adminsdk-fbsvc@gercia-gcp.iam.gserviceaccount.com	firebase-adminsdk	Firebase Admin SDK Agent	105091758920963890391	FCM Push Token Issuer & Delivery Agent
gercia-assistant@gercia-gcp.iam.gserviceaccount.com	gercia-assistant	GERCIA Assistant Calendar Agent	107076042180771417418	Cloudflare Pages Encrypted Secrets (GOOGLE_SERVICE_ACCOUNT_KEY)
621952369587-compute@developer.gserviceaccount.com	(Compute Engine)	Default Compute Engine SA	104780274625227978368	Google Cloud Build CI/CD Pipeline Executor
gercia-gcp@appspot.gserviceaccount.com	(App Engine)	App Engine Default SA (Disabled)	111721097850181335879	Disabled (Hardened • roles/editor stripped)

---

3. Serverless Identity & Zero-Disk Credentials

Under the serverless container execution model on Google Cloud Platform:

1. No Static Filesystem Keys: Cloud Run services bind directly to their assigned service accounts at deploy time via gcloud run deploy --service-account <SA_EMAIL>. Containers obtain short-lived OAuth 2.0 access tokens dynamically from the Google metadata server (http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token).
2. Elimination of Host Mount Vulnerabilities: Because no JSON credentials reside on persistent disks or container filesystems, an adversary achieving Remote Code Execution (RCE) inside a container cannot exfiltrate long-lived private keys.
3. Environment-Specific Secret Scoping: Service accounts have IAM permissions strictly partitioned by environment (_PRD vs _STG) within Google Secret Manager.

---

4. Minimum IAM Role Assignments (Least Privilege)

To prevent lateral movement in the event of workload compromise, service accounts are bound strictly to their minimum operational roles:

• Application Workloads (Gercia.Server & gercia-migrator Job):
  • roles/secretmanager.secretAccessor (Conditioned to secrets matching target environment suffix).
  • roles/cloudsql.client (Enables secure connection brokering to Google Cloud SQL over private VPC).
  • roles/logging.logWriter (Allows transmitting structured NDJSON logs into Google Cloud Logging).
  • roles/storage.objectUser (Allows generating V4 Signed URLs and reading/writing sovereign attachments in gs://gercia-documents-{prd,stg}).

The Zero-Trust V4 Signed URL Document Security Pattern

A fundamental security principle across the GERCIA platform is that client applications (Angular SPA, Mobile KMP, Hardware Edge) never access Google Cloud Storage buckets directly via static public links or permanent credentials. All interactions are brokered dynamically by Gercia.Server using ephemeral Google Cloud Storage V4 Signed URLs:

flowchart TD
    subgraph CLIENTS ["Client Applications (B2B SaaS Web, Mobile & Edge)"]
        UI["@gercia/app / GERCIA Care / GERCIA Hub"]
    end

    subgraph API ["Gateway Authentication & Authorization"]
        SERVER["Gercia.Server (Cloud Run)<br>GcsStorageService (V4 Signed URLs)"]
    end

    subgraph GCS ["Google Cloud Storage (southamerica-east1 - São Paulo)"]
        BUCKET["gs://gercia-documents-{prd,stg}<br>(Standard • 5-Rule FinOps Lifecycle • 100% Private)"]
    end

    UI -- "1. Request upload or read URL (with JWT & Tenant context)" --> SERVER
    SERVER -- "2. Validates RLS, Tenant & Permissions, signs URL (15-min expiry)" --> UI
    UI -- "3. PUT or GET object directly using Signed URL" --> BUCKET

Zero Public Access & Ephemeral Access Enforcement

All platform document buckets enforce Uniform bucket-level access and Public Access Prevention: Enforced. No object can ever be accessed without an active, cryptographically signed V4 signature generated by an authorized Gercia.Server instance.

---

5. Google Cloud Storage (GCS) Buckets Matrix

All platform buckets reside exclusively in the southamerica-east1 (São Paulo) region, ensuring Brazilian data sovereignty (LGPD compliance) and ultra-low latency:

Bucket Name	Storage Class	Access Control	Encryption	Protection & Retention Policy	Operational Consumer
gs://gercia-documents-prd	Standard	Uniform	Google-Managed	5-Rule FinOps Lifecycle (Standard ➔ Nearline 30d ➔ Coldline 90d ➔ Archive 365d) • Soft Delete: Disabled • Retention Lock: Disabled	Gercia.Server (Production) • Sovereign attachments & clinical documents repository
gs://gercia-documents-stg	Standard	Uniform	Google-Managed	5-Rule FinOps Lifecycle (Standard ➔ Nearline 30d ➔ Coldline 90d ➔ Archive 365d) • Soft Delete: Disabled • Retention Lock: Disabled	Gercia.Server (Staging) • Sovereign attachments & clinical documents repository
gs://gercia-build-cache	Standard	Uniform	Google-Managed	Standard Overwrite (cache-nuget.tar.gz)	Google Cloud Build CI/CD pipelines

Sovereign Document Repositories & FinOps 5-Stage Lifecycle Policy

All clinical documents, medical attachments, compounding formula sheets, and digital prescriptions stored in gs://gercia-documents-{prd,stg} originate under the STANDARD storage class for immediate sub-second access during active patient care. To reconcile statutory compliance (LGPD, CFM, ANVISA RDC 67/2007) with optimal cloud economics, the buckets enforce a progressive 5-stage lifecycle transition policy:

flowchart LR
    S0["1. Standard<br>(Day 0 - 30)<br>Active Clinical Access & Rapid Retrieval"]
    S1["2. Nearline<br>(Day 30 - 90)<br>Infrequent Access (~50% Cost Cut)"]
    S2["3. Coldline<br>(Day 90 - 365)<br>Rare Access (~80% Cost Cut)"]
    S3["4. Archive<br>(Day 365+)<br>Statutory Custody (~94% Cost Cut)"]

    S0 -- "Age ≥ 30 Days" --> S1
    S1 -- "Age ≥ 90 Days" --> S2
    S2 -- "Age ≥ 365 Days" --> S3

Official GCS Lifecycle Rules Matrix

Rule #	Lifecycle Action	Target Condition	Precondition Filter	FinOps & Architecture Rationale
1	Delete Object	Noncurrent object with 3+ newer versions	Object Versioning enabled	Version Bloat Prevention: Prevents disk bloat by retaining at most 3 noncurrent versions when files are updated or superseded.
2	Delete Object	7+ days since object became noncurrent	Object Versioning enabled	Temporary Version Purge: Automatically cleans up superseded versions after 7 days, maintaining zero redundant storage cost.
3	Set to Nearline	30+ days since creation	Storage class matches Standard	Recent Access Optimization: Documents older than 30 days transition to Nearline, halving storage costs while retaining millisecond retrieval times.
4	Set to Coldline	90+ days since creation	Storage class matches Nearline	Quarterly Archival: Files older than 1 quarter transition to Coldline, reducing costs by ~80% compared to Standard tier.
5	Set to Archive	365+ days since creation	Storage class matches Coldline	Long-Term Statutory Custody: Files older than 1 year move to Archive tier, achieving ~94% cost savings for long-term clinical and legal custody.

Protection & Deletion Governance (Current Operational State)

• Soft Delete: Explicitly DISABLED (retentionDurationSeconds: 0) to prevent lingering deleted object costs during active iteration.
• Retention Policy (Bucket Lock / WORM): DISABLED for operational flexibility; to be evaluated for immutable statutory enforcement in future compliance iterations.
• Evaluation Semantics: Deletion rules override storage class transitions, and more restrictive/cheaper storage classes take precedence if multiple rules match concurrently.

---

6. Google Workspace Domain-Wide Delegation (DWD) & Calendar Integration

The commercial sales and platform assistant (Assistente GERCIA) operates autonomously on the institutional website (gercia.com.br), answering prospect inquiries, performing real-time slot availability lookups, and booking meetings directly into Google Calendar with automated Google Meet room provisioning.

Security Architecture & Least-Privilege Scoping

To interact with Google Calendar on behalf of the commercial executive (leonardo@gercia.com.br) without compromising organizational security, the platform utilizes Google Workspace Domain-Wide Delegation (DWD):

flowchart TD
    subgraph CF_EDGE ["Cloudflare Pages Edge Runtime (functions/api/)"]
        ASSISTANT["Commercial Assistant API<br>(assistant.ts)"]
        CRYPTO["Web Crypto API (crypto.subtle)<br>RS256 JWT Generator"]
        ASSISTANT --> CRYPTO
    end

    subgraph GCP_SA ["Google Cloud IAM (gercia-gcp)"]
        SA["gercia-assistant@gercia-gcp.iam.gserviceaccount.com<br>Client ID: 107076042180771417418"]
    end

    subgraph GOOGLE_AUTH ["Google OAuth2 STS (oauth2.googleapis.com)"]
        TOKEN_EP["/token<br>grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer"]
    end

    subgraph GW ["Google Workspace Admin, Calendar API & Groups"]
        ADMIN["Admin Console (admin.google.com)<br>Domain-Wide Delegation Policy"]
        CALENDAR["Google Calendar API (v3)<br>Target: GOOGLE_CALENDAR_ID (primary or custom)"]
        MEET["Google Meet API<br>(Auto-Generates Video Room)"]
        GROUP["Google Group: comercial@gercia.com.br<br>(Attendees Fan-Out to Sales Team)"]
    end

    CRYPTO -- "1. Signs JWT with sub: GOOGLE_SERVICE_ACCOUNT_USER" --> TOKEN_EP
    SA -. "Identifies by Client ID" .-> TOKEN_EP
    TOKEN_EP -- "2. Validates DWD Delegated Scopes" --> ADMIN
    TOKEN_EP -- "3. Issues Short-Lived Access Token (1 hour)" --> ASSISTANT
    ASSISTANT -- "4. Queries freeBusy & Inserts Event" --> CALENDAR
    CALENDAR -- "5. Generates Video Conference" --> MEET
    CALENDAR -. "6. Dispatches invite to attendees" .-> GROUP

Delegation Specification Matrix

Parameter	Configuration Value	Operational Purpose
Service Account	gercia-assistant@gercia-gcp.iam.gserviceaccount.com	Dedicated GCP identity for commercial assistant scheduling
OAuth2 Client ID	107076042180771417418	Unique numerical identifier authorized in Google Workspace Admin
Delegated Scopes	https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.freebusy	Read/write calendar events and query busy intervals
Impersonated Subject (sub)	GOOGLE_SERVICE_ACCOUNT_USER (defaults to leonardo@gercia.com.br)	Authorized licensed Google Workspace user acting as delegation operator
Target Calendar ID	GOOGLE_CALENDAR_ID (defaults to dedicated c_006478a0a739b0676da33d3f89bbed3dc70c6543ad7cabefecb8a3b3e9cf8322@group.calendar.google.com)	Isolated commercial calendar segregating demonstrations from executive schedules
Commercial Attendee Fan-Out	COMMERCIAL_GROUP_EMAIL (comercial@gercia.com.br)	Google Group automatically added as an attendee to synchronize team members
Signature Algorithm	RS256 (RSA SHA-256 via Web Crypto API)	Zero-dependency cryptographic signing inside Cloudflare Workers (workerd)
Key Storage	Cloudflare Pages Encrypted Secrets	GOOGLE_SERVICE_ACCOUNT_KEY (PEM format) & GOOGLE_SERVICE_ACCOUNT_EMAIL

Architecture Note: Why Google Groups Cannot Be Impersonated Directly

In Google Workspace Domain-Wide Delegation, the sub claim strictly requires the primary email address of an individual, licensed Workspace user account. Attempting to set sub: comercial@gercia.com.br triggers an unauthorized_client error because Google Groups do not possess personal OAuth user profiles or standalone primary calendars.

Instead, the architecture couples a licensed operator (GOOGLE_SERVICE_ACCOUNT_USER) with an automatic attendee fan-out pattern: the Google Group comercial@gercia.com.br is added to every scheduled event’s attendees array. Google Calendar automatically delivers invitations, calendar synchronization, and notifications to all members of the group without requiring additional paid Workspace seat licenses.