Rendered from docs/design/riskmandate-gcp-key-vault-password-manager-mvp.md, which is the source of truth and the markdown twin of this page. Rendered at site v0.1.2.

Risk Mandate — GCP Key Vault Architecture & Password Manager MVP

2026-10-05 · Dinis Cruz

Summary

Risk Mandate needs two things from a cloud: an identity and a place to store encrypted keys. Everything else (SGit vault encryption, key unlock, sharing) happens in the browser.

Decision: build it all in GCP, one project per client deployment, so a deployment can be created and destroyed as one unit. The stack is Identity Platform for login, Cloud Storage for Firebase for the encrypted keyring and SGit vaults, Storage Security Rules as the per-user guardrail, and a passkey with the WebAuthn PRF extension as the only thing that can decrypt.

The first build is a password manager. It contains every risky piece of the vault-management design: login, browser-direct storage, passkey unlock, keyring format, device enrolment, recovery and multi-user sharing. Once it works, vault key management and user preferences are a layer on top: the same keyring holds vault keys instead of passwords.

The server side never holds plaintext. A full compromise of the GCP project, Identity Platform or the admin account yields ciphertext only. This matches SGit's existing principle, and SGit's existing public/private key support and encrypted-data-on-top-of-encrypted-data design already cover most of what's needed.

Why all-GCP rather than Cognito

The Cognito + S3 design works (see the Cognito architecture doc) and Cognito is familiar. GCP wins on deployment shape:

One cloud per deployment. Google sign-in needs a Google OAuth client, which lives in a GCP project. With Cognito, a client wanting Google sign-in would run AWS and a GCP project. All-GCP keeps it to one.
Clean create/destroy. A GCP project is a complete boundary: identity config, bucket, IAM, billing. Deleting the project wipes the deployment.
Familiarity is no longer a deciding factor. GCP is well known to the team.

What GCP does not give in this design: mailboxes, Drive or Calendar. Those are Workspace, which carries the resale terms issue documented in the onboarding doc. This design needs none of them.

Client-owned deployments

In a client deployment the client controls everything. The GCP project sits in the client's own Google Cloud organisation and billing account; Risk Mandate deploys the architecture into it. The client creates (or authorises Risk Mandate to create) the Google OAuth client for Google sign-in, so that credential is theirs too. Risk Mandate holds no standing access it doesn't need.

The GCP stack

Layer	GCP component	Role	Cognito equivalent
Web app	Static site (GitHub Pages or Firebase Hosting)	All crypto and UI run in the browser	Same
Login	Identity Platform: Google sign-in, email/password, OIDC/SAML federation for a client's own IdP	Proves who the user is	Cognito user pool
Browser-direct storage	Firebase SDK talking to Cloud Storage for Firebase	No server in the data path	Identity pool + temporary AWS credentials
Access guardrail	Storage Security Rules keyed on the user's UID (and tenant if used)	Each user touches only their own paths	IAM policy variables on S3 prefixes
Encrypted data	Keyring files, public-key directory, inboxes, SGit vault objects in the bucket	Ciphertext only	S3
Unlock	Passkey + WebAuthn PRF, held in the user's Google Password Manager or iCloud Keychain	Derives the key that opens the keyring	Same

Pricing reference: Identity Platform basic sign-in is free to 50,000 monthly active users, then roughly $0.0055 per MAU; SAML/OIDC federation is free only to 50 MAU.

Deployment units: project, tenant, region

Project per client (recommended). Own Identity Platform config, own bucket, own IAM, own billing. Destroying the project removes everything. Best fit for create/destroy and client ownership.
Tenants within one project (option). Identity Platform has built-in multi-tenancy: separate user pools under one project. Useful for a shared Risk Mandate environment hosting several small or pilot clients. Security Rules then key on both UID and tenant.
Region. Set per client by the bucket location, for data residency. Identity Platform itself is global; check where its user records are held if a client has strict residency needs.
Automation. Script project creation end to end (Terraform or gcloud): create project, enable Identity Platform, add Firebase, create bucket in the chosen region, deploy Security Rules, configure providers. Watch per-organisation and per-billing-account project quotas if spinning many up.

Where the passkey lives

The passkey is not stored in Identity Platform, the bucket or anything Risk Mandate administers.

It lives in the user's authenticator: in plain Chrome that is Google Password Manager, on Apple devices iCloud Keychain, or a hardware security key.
It syncs through the user's own personal account (their personal Google or Apple account), which no Risk Mandate or client admin can reach.
It is a WebAuthn credential registered by Risk Mandate's own page against the riskmandate.ai origin. It needs no Google app, no OAuth client and no Identity Platform setting.

The user meets Google in two unrelated roles: once as a login provider (Google sign-in through Identity Platform, which needs an OAuth client) and once as the home of the passkey (Google Password Manager, which needs no configuration). Neither role creates a lock-in: login can be any provider, and the passkey would sit in the same place under any cloud.

First-run and returning-user flow

You, in Chrome, at riskmandate.ai:

Sign in. Click "Sign in with Google" (or email/password). Identity Platform returns an ID token; the Firebase SDK can now reach your paths in the bucket. Everything there is ciphertext, and you have no keyring yet.
Create a passkey. The page sees no keyring and calls navigator.credentials.create with the PRF extension. Chrome shows its own dialog and offers to save the passkey in Google Password Manager. You approve with fingerprint, PIN or face.
Create the keyring. The browser takes the PRF output, derives a wrapping key, generates your key pair and a keyring key, encrypts the keyring and writes it to the bucket. A recovery code is shown once.
Returning visit (same Chrome, or any Chrome signed into the same Google account so the passkey has synced): sign in, the page fetches the keyring, calls navigator.credentials.get with PRF, you confirm, the keyring unlocks in memory.
New device without the passkey (e.g. Safari on an iPhone using iCloud Keychain): sign in, unlock with the passkey from another device via cross-device sign-in, or with the recovery code, then register a new passkey on this device; a new wrapped-key entry is added to the keyring.

Keyring design

The keyring is an encrypted file in Cloud Storage. Google stores it but cannot read it.

Wrapped keyring-key entries, one per unlock method: each registered passkey (keyring key wrapped with that passkey's PRF output via HKDF + AES-GCM) and one recovery code.
Encrypted body, holding the user's private key, and the entries they can open: passwords in the MVP; SGit vault keys and preferences later.

One unlock opens everything: passkey unlocks the keyring; the keyring holds the private key and all the keys/secrets. Plaintext exists only in the browser, briefly.

Losing every passkey and the recovery code means the data is unrecoverable. This must be stated in the terms and in onboarding copy.

The problem. Single-user wrapping works until a secret must be readable by a second person. You can't wrap it with their passkey (their PRF secret never leaves their device), and you can't send it through the server in plaintext.

The solution: a key pair per user. At setup each user's browser generates a public/private key pair.

The private key goes into the user's keyring, protected by their passkey like everything else.
The public key is published in a readable directory: "this user, this public key".

Sharing flow.

Your browser fetches the colleague's public key.
It encrypts the vault key (or password entry key) to that public key.
It drops the result in the colleague's inbox in the bucket.
On their next unlock, their browser decrypts it with their private key and adds it to their own keyring.

The public key shares keys, not data. The data stays where it is, encrypted under its vault key; sharing hands over the ability to open it. The server carries the package but can never read it.

What it drags in (design up front, not later):

Concern	Why it matters	Approach
Revocation	A removed member already holds the key	Rotate the vault key, re-encrypt, re-share to remaining members
Directory trust	A compromised admin could swap a public key and intercept the next share	Key fingerprints users can compare, or signed directory entries
Group membership	Who can open what is real metadata	Store membership per vault; update on add/remove

If the MVP stores only single-user wrapped keys and sharing is added later, the core data model gets rewritten. Build the key pair and inbox in from the start, even if version one only shares with one person.

Fit with SGit. SGit already supports public/private keys and is designed to store encrypted data on top of its own encrypted data. The keyring, the per-user key pairs and the inbox are applications of existing SGit capability, not new machinery. Reuse SGit's key formats and primitives rather than introducing a parallel scheme.

Storage layout

Path	Contents	Who can read/write (Security Rules)
`users/{uid}/keyring`	Encrypted keyring	Owner only
`directory/{uid}.pub`	Public key (signed)	Owner writes; signed-in users read
`inbox/{uid}/{shareId}`	Keys encrypted to that user	Any signed-in user writes; owner reads and deletes
`vaults/{vaultId}/...`	SGit vault objects	Members, per membership record

With tenants, prefix every path with tenants/{tenantId}/ and add the tenant check to every rule.

Password manager MVP

Why it's the right first build: if an admin with full GCP access cannot read a stored password, the security model holds for vault keys too. It is easy to test, easy to demo, and has every hard piece.

Scope:

Sign in (Google and email/password via Identity Platform)
First-run passkey creation, keyring creation, recovery code
Add, view, edit, delete password entries
Add a second device; recover with the recovery code
Share an entry with another user (key pair + inbox)
Revoke a share (rotation)
Fingerprint display for verifying another user's public key

Then vault management is the same keyring holding SGit vault keys, and user preferences become more encrypted fields.

Threat summary

Attacker	Gets	Cannot get
GCP project or Identity Platform admin	Ciphertext, user emails and login metadata, ability to impersonate a login, delete data	Plaintext; the PRF secret is bound to the riskmandate.ai origin and the user's device
Bucket read access	Ciphertext	Plaintext
Directory tampering	Future shares, unless fingerprints or signatures are checked	Existing keys
Whoever controls the served JavaScript	Everything for users who load it	—

The served code is the real boundary. Host the site separately from the GCP project and protect that host independently. Use bucket versioning and retention to defend availability against deletion.

Open questions and next steps

Confirm Storage Security Rules can check the Identity Platform tenant claim, if tenants are used.
Confirm where Identity Platform stores user records, for clients with residency requirements.
Map SGit's existing key pair and layered-encryption support onto the keyring, directory and inbox; list any gaps.
Choose directory trust: fingerprints, signed entries, or both.
Define the keyring format, versioning and conflict handling for two devices writing at once.
Build the PRF compatibility matrix (older Android, managed Chrome, Firefox, Safari).
Write the project-creation script and test create/destroy end to end.
Build the password manager MVP; test by giving someone full GCP admin and asking them to read a password.