@edcalderon/auth 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.2.2] - 2026-03-19
+
+### Added
+
+- Added `packages/auth/supabase/` SQL templates for a vendor-independent `public.users` table and optional Supabase Auth sync trigger.
+
+### Fixed
+
+- Hardened the OIDC upsert migration so identity writes require a trusted server-side caller instead of the `anon` role.
+- Preserved existing user profile fields when optional claims are omitted during upserts or Supabase sync updates.
+
 ## [1.2.1] - 2026-03-02
 
 ### Changed

package/README.md

@@ -11,12 +11,16 @@ Swap between Supabase, Firebase, Hybrid, or any custom provider without changing
 
 ---
 
-## 📋 Latest Changes (v1.2.1)
+## 📋 Latest Changes (v1.2.2)
 
-### Changed
+### Added
 
-- 🎨 Upgraded README badges and title to `for-the-badge` style with gold (#C8A84E) / dark (#0d1117) Alternun brand colors
-- 🔗 Added Web3 SIWE|SIWS badge linking to Supabase docs
+- Added `packages/auth/supabase/` SQL templates for a vendor-independent `public.users` table and optional Supabase Auth sync trigger.
+
+### Fixed
+
+- Hardened the OIDC upsert migration so identity writes require a trusted server-side caller instead of the `anon` role.
+- Preserved existing user profile fields when optional claims are omitted during upserts or Supabase sync updates.
 
 For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
 
@@ -68,6 +72,13 @@ pnpm add firebase
 pnpm add react-native
 ```
 
+### Supabase SQL Templates
+
+If you want an application-owned user table instead of coupling your identity model to `auth.users`, copy the reference SQL templates in `packages/auth/supabase/` into your Supabase project and apply them with `supabase db push`.
+
+- `001_create_app_users.sql`: vendor-independent `public.users` table plus secure server-side OIDC upsert RPC
+- `002_sync_auth_users_to_app_users.sql`: optional trigger and backfill for projects using Supabase Auth
+
 ---
 
 ## Subpath Exports (Crucial for RN/Next.js compatibility)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edcalderon/auth",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "A universal, provider-agnostic authentication package (Web + Next.js + Expo/React Native)",
   "exports": {
     ".": {

package/supabase/README.md

@@ -0,0 +1,65 @@
+# @edcalderon/auth Supabase SQL Templates
+
+Copy these files into your own Supabase project. They are reference migrations for projects using @edcalderon/auth, not runtime imports.
+
+## Quick Setups
+
+| Use case | Apply | Result |
+| --- | --- | --- |
+| Supabase Auth quick setup | `001` + `002` | Vendor-independent `public.users` plus automatic `auth.users -> public.users` sync |
+| External OIDC only | `001` | Vendor-independent `public.users` plus a secure server-side upsert RPC |
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `migrations/001_create_app_users.sql` | Creates `public.users`, timestamps trigger, and `upsert_oidc_user()` |
+| `migrations/002_sync_auth_users_to_app_users.sql` | Optional trigger/backfill for projects that use Supabase Auth |
+
+## What You Get
+
+- A vendor-independent `public.users` table keyed by `(sub, iss)`.
+- A clean migration path away from Supabase Auth later.
+- An optional trigger that mirrors Supabase Auth users automatically.
+- Safe default behavior for optional profile fields so missing claims do not erase stored data.
+
+## Security Model
+
+`upsert_oidc_user()` is intentionally not callable by the `anon` role.
+
+- Supabase Auth users are synced automatically by migration `002`.
+- External OIDC users should be written by a trusted server or Edge Function after token verification.
+- Optional fields such as `email`, `name`, `picture`, and `provider` only overwrite stored values when a non-null value is provided.
+
+## Apply
+
+```bash
+# Copy into your project
+cp packages/auth/supabase/migrations/*.sql your-project/supabase/migrations/
+
+# Apply them with the Supabase CLI
+supabase db push
+```
+
+If you only want the vendor-independent table and are not using Supabase Auth as a provider, apply only `001_create_app_users.sql`.
+
+## Suggested External OIDC Flow
+
+1. Verify the provider token in your server or Edge Function.
+2. Extract `sub`, `iss`, and optional claims.
+3. Call `upsert_oidc_user()` with the service-role key.
+4. Use the returned `public.users.id` as your application user identifier.
+
+## Why `(sub, iss)`
+
+The `(sub, iss)` pair follows the OIDC identity model and allows multiple providers to coexist safely:
+
+| Provider | `sub` | `iss` |
+| --- | --- | --- |
+| Supabase Auth | `auth.users.id` | `supabase` |
+| Authentik | provider UUID | issuer URL |
+| Auth0 | provider user id | issuer URL |
+| Firebase | provider uid | issuer URL |
+| Custom OIDC | JWT `sub` | JWT `iss` |
+
+That gives you a stable application-owned identity layer even if you later replace the auth provider.

package/supabase/migrations/001_create_app_users.sql

@@ -0,0 +1,147 @@
+-- ============================================================================
+-- 001_create_app_users.sql
+-- Vendor-independent user registry for projects using @edcalderon/auth.
+--
+-- This creates an application-owned public.users table keyed by (sub, iss)
+-- and a secure upsert RPC intended for trusted server-side use.
+-- ============================================================================
+
+create extension if not exists pgcrypto;
+
+create table if not exists public.users (
+  id             uuid        primary key default gen_random_uuid(),
+  sub            text        not null,
+  iss            text        not null,
+  email          text,
+  email_verified boolean     not null default false,
+  name           text,
+  picture        text,
+  provider       text,
+  raw_claims     jsonb       not null default '{}'::jsonb,
+  created_at     timestamptz not null default timezone('utc', now()),
+  updated_at     timestamptz not null default timezone('utc', now()),
+
+  constraint users_sub_iss_uq unique (sub, iss),
+  constraint users_sub_len_chk check (char_length(sub) <= 256),
+  constraint users_iss_len_chk check (char_length(iss) <= 512),
+  constraint users_email_len_chk check (
+    email is null or char_length(email) <= 320
+  )
+);
+
+create index if not exists users_email_idx
+  on public.users (lower(email))
+  where email is not null;
+
+create index if not exists users_provider_idx
+  on public.users (provider)
+  where provider is not null;
+
+create or replace function public.users_set_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at = timezone('utc', now());
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_users_set_updated_at on public.users;
+
+create trigger trg_users_set_updated_at
+before update on public.users
+for each row
+execute function public.users_set_updated_at();
+
+create or replace function public.upsert_oidc_user(
+  p_sub            text,
+  p_iss            text,
+  p_email          text          default null,
+  p_email_verified boolean       default false,
+  p_name           text          default null,
+  p_picture        text          default null,
+  p_provider       text          default null,
+  p_raw_claims     jsonb         default '{}'::jsonb
+)
+returns public.users
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  v_claims jsonb := coalesce(
+    nullif(current_setting('request.jwt.claims', true), ''),
+    '{}'
+  )::jsonb;
+  v_role text := coalesce(nullif(v_claims ->> 'role', ''), 'unknown');
+  v_user public.users;
+begin
+  if v_role <> 'service_role' then
+    raise exception 'upsert_oidc_user() requires a trusted server-side caller';
+  end if;
+
+  if nullif(trim(p_sub), '') is null or nullif(trim(p_iss), '') is null then
+    raise exception 'upsert_oidc_user() requires non-empty p_sub and p_iss';
+  end if;
+
+  insert into public.users (
+    sub,
+    iss,
+    email,
+    email_verified,
+    name,
+    picture,
+    provider,
+    raw_claims
+  )
+  values (
+    trim(p_sub),
+    trim(p_iss),
+    nullif(trim(p_email), ''),
+    p_email_verified,
+    nullif(trim(p_name), ''),
+    nullif(trim(p_picture), ''),
+    nullif(trim(p_provider), ''),
+    coalesce(p_raw_claims, '{}'::jsonb)
+  )
+  on conflict (sub, iss) do update
+    set email = coalesce(excluded.email, public.users.email),
+        email_verified = public.users.email_verified or excluded.email_verified,
+        name = coalesce(excluded.name, public.users.name),
+        picture = coalesce(excluded.picture, public.users.picture),
+        provider = coalesce(excluded.provider, public.users.provider),
+        raw_claims = case
+          when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+          else public.users.raw_claims || excluded.raw_claims
+        end,
+        updated_at = timezone('utc', now())
+  returning * into v_user;
+
+  return v_user;
+end;
+$$;
+
+revoke all on function public.upsert_oidc_user(
+  text,
+  text,
+  text,
+  boolean,
+  text,
+  text,
+  text,
+  jsonb
+) from public, anon, authenticated;
+
+grant execute on function public.upsert_oidc_user(
+  text,
+  text,
+  text,
+  boolean,
+  text,
+  text,
+  text,
+  jsonb
+) to service_role;
+
+alter table public.users enable row level security;

package/supabase/migrations/002_sync_auth_users_to_app_users.sql

@@ -0,0 +1,101 @@
+-- ============================================================================
+-- 002_sync_auth_users_to_app_users.sql
+-- Optional trigger for projects that use Supabase Auth.
+-- Keeps auth.users mirrored into public.users and backfills existing users.
+-- ============================================================================
+
+create or replace function public.sync_auth_user_to_app_users()
+returns trigger
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  if new.is_anonymous then
+    return new;
+  end if;
+
+  insert into public.users (
+    sub,
+    iss,
+    email,
+    email_verified,
+    name,
+    picture,
+    provider,
+    raw_claims
+  )
+  values (
+    new.id::text,
+    'supabase',
+    new.email,
+    new.email_confirmed_at is not null,
+    coalesce(
+      new.raw_user_meta_data ->> 'name',
+      new.raw_user_meta_data ->> 'full_name',
+      split_part(coalesce(new.email, ''), '@', 1)
+    ),
+    new.raw_user_meta_data ->> 'avatar_url',
+    coalesce(new.raw_app_meta_data ->> 'provider', 'email'),
+    coalesce(new.raw_user_meta_data, '{}'::jsonb)
+  )
+  on conflict (sub, iss) do update
+    set email = coalesce(excluded.email, public.users.email),
+        email_verified = public.users.email_verified or excluded.email_verified,
+        name = coalesce(excluded.name, public.users.name),
+        picture = coalesce(excluded.picture, public.users.picture),
+        provider = coalesce(excluded.provider, public.users.provider),
+        raw_claims = case
+          when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+          else public.users.raw_claims || excluded.raw_claims
+        end,
+        updated_at = timezone('utc', now());
+
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_auth_users_sync_to_app_users on auth.users;
+
+create trigger trg_auth_users_sync_to_app_users
+after insert or update of email_confirmed_at, email, raw_user_meta_data, raw_app_meta_data
+on auth.users
+for each row
+execute function public.sync_auth_user_to_app_users();
+
+insert into public.users (
+  sub,
+  iss,
+  email,
+  email_verified,
+  name,
+  picture,
+  provider,
+  raw_claims
+)
+select
+  u.id::text,
+  'supabase',
+  u.email,
+  u.email_confirmed_at is not null,
+  coalesce(
+    u.raw_user_meta_data ->> 'name',
+    u.raw_user_meta_data ->> 'full_name',
+    split_part(coalesce(u.email, ''), '@', 1)
+  ),
+  u.raw_user_meta_data ->> 'avatar_url',
+  coalesce(u.raw_app_meta_data ->> 'provider', 'email'),
+  coalesce(u.raw_user_meta_data, '{}'::jsonb)
+from auth.users u
+where not u.is_anonymous
+on conflict (sub, iss) do update
+  set email = coalesce(excluded.email, public.users.email),
+      email_verified = public.users.email_verified or excluded.email_verified,
+      name = coalesce(excluded.name, public.users.name),
+      picture = coalesce(excluded.picture, public.users.picture),
+      provider = coalesce(excluded.provider, public.users.provider),
+      raw_claims = case
+        when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+        else public.users.raw_claims || excluded.raw_claims
+      end,
+      updated_at = timezone('utc', now());