Supabase Auth

Supabase Auth already knows who your user is. This page connects that identity to CipherStash in two layers you can adopt independently:

1. Federation — exchange the user's Supabase session for a CipherStash token, so every encryption and decryption request authenticates as that user instead of as a shared service credential. This is the foundation.
2. Identity-bound encryption (lock context) — an optional layer on top of federation that binds a value to the user's identity claim, so only that user can decrypt it — enforced by ZeroKMS, not by your application code.

Federation is useful on its own. Lock context requires it. Start with federation; add lock context where per-user secrecy matters.

Register Supabase as an OIDC provider

CipherStash needs to trust your Supabase project as an OIDC issuer before it will accept a Supabase session token. Add the provider once, in the CipherStash dashboard at dashboard.cipherstash.com/workspaces/_/oidc-providers (the _ resolves to whichever workspace you select). A Supabase project's issuer is:

https://<project-ref>.supabase.co/auth/v1

Good to know: the CipherStash dashboard can register this for you in one click while it is connected to your Supabase project over OAuth. Manual OIDC configuration is covered in the auth reference.

Federate the Supabase session

Authenticate the Encryption client with an OidcFederationStrategy. It takes your workspace CRN and a getJwt callback that returns the user's current Supabase access token — the strategy calls it on first use and again on every re-federation, so return a fresh token each time rather than capturing one:

import { createClient } from "@supabase/supabase-js"
import { OidcFederationStrategy } from "@cipherstash/stack"
import { encryptedSupabase } from "@cipherstash/stack-supabase"

const supabaseClient = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!,
)

// Return the current Supabase session token — re-invoked on every re-federation.
const getJwt = async () => {
  const { data: { session } } = await supabaseClient.auth.getSession()
  if (!session) throw new Error("No active Supabase session")
  return session.access_token
}

const federation = OidcFederationStrategy.create(
  process.env.CS_WORKSPACE_CRN!,
  getJwt,
)
if (federation.failure) throw new Error(federation.failure.error.message)

export const db = await encryptedSupabase(supabaseClient, {
  config: {
    authStrategy: federation.data,
  },
})

That's the whole integration. Every db.from(...) query now encrypts and decrypts under the signed-in user's identity, and your Supabase Auth session and RLS policies apply to the underlying request exactly as before.

Identity-bound encryption (lock context)

Federation authenticates as the user. Lock context goes further: it bakes a claim from the user's JWT (by default sub, which for Supabase Auth is the user's UUID) into the data key, so a value can only be decrypted by presenting the same identity. Even your own backend — holding valid workspace credentials — cannot decrypt another user's locked values.

Attach a lock context to any encryptedSupabase query with .withLockContext(). sub is the Supabase user's UUID:

import { db } from "./lib/db"

const lockContext = { identityClaim: ["sub"] }

// Insert — the value is bound to the signed-in user's `sub` claim
await db.from("patients")
  .insert({ email: "[email protected]", name: "Alice Chen" })
  .withLockContext(lockContext)

// Read — the same user must be authenticated
const { data } = await db.from("patients")
  .select("id, email, name")
  .eq("email", "[email protected]")
  .withLockContext(lockContext)

ZeroKMS resolves the claim's value from the token that authenticated the request — the federated Supabase identity — so no separate identify step or per-operation token is needed. Reading a locked value without a matching context, or as a different user, fails with an encryption error regardless of what RLS allows.

Where it fits

• Per-user data (a user's own medical history, messages, documents): lock to sub. The row is useless to anyone but its owner — including operators with database access and your own service role.
• Shared / tenant data (a support queue, org-wide records): don't lock it, or you'll be unable to decrypt it outside a user session. Federation alone still authenticates access as the user; RLS scopes which rows they see.
• Server-side jobs that must read locked data need the owning user's session — by design. If a background job must read a field, that field shouldn't be identity-locked.

Errors

Both federation and lock context surface failures as values, not throws.

The strategy's own factory and token errors follow the @cipherstash/auth Result shape (failure.type); see the auth reference.

Where to next