@kontrolia/db 2.1.5 → 2.2.0

package/migrations/0043_permissions_last_synced_at.sql

@@ -0,0 +1,15 @@
+-- Tracks the last time an application's own deploy pipeline included this
+-- permission in a POST /api/applications/sync call. Lets admin-panel flag
+-- permissions an app has stopped declaring (its sibling permissions synced
+-- more recently than this one did) so a platform admin can review and
+-- prune them explicitly — sync itself never deletes, by design, since a
+-- partial/broken deploy shouldn't silently revoke a permission a role
+-- already grants.
+--
+-- Backfilled to now() rather than left null: every existing permission
+-- predates this column, and leaving them null would make the entire
+-- pre-existing catalog look "never synced" the moment this migration
+-- lands, even though most of it is actively in use. now() means nothing
+-- looks stale until an app's sync pattern actually diverges after today.
+alter table kontrolia_auth.permissions
+  add column last_synced_at timestamptz not null default now();

package/migrations/0044_plans_and_subscriptions.sql

@@ -0,0 +1,524 @@
+-- Plans, subscriptions and usage limits — the "entitlements" layer.
+--
+-- A plan belongs to an application and describes a commercial tier: what it
+-- unlocks (plan_permissions — a subset of the app's own permission catalog)
+-- and how much of it can be consumed (plan_limits — numeric quotas per
+-- period). A subscription ties ONE organization to ONE plan of ONE
+-- application. Organizations, not users, subscribe: the tenant is what pays,
+-- a person can belong to several tenants with different roles, and per-seat
+-- pricing is just a limit ("members" = 5) rather than per-user subscriptions.
+--
+-- Effective access = role permissions ∩ plan permissions. The access-token
+-- hook below applies that intersection, but only for applications that opt
+-- in with plans_required = true — every existing application keeps working
+-- exactly as before until an operator flips that flag.
+--
+-- Payments themselves never live here: KontrolIA Auth brokers Stripe
+-- (Checkout + Customer Portal + webhooks) and only stores the resulting
+-- state and the provider's ids. Subscriptions can also be assigned
+-- manually (free tiers, trials, enterprise customers billed by invoice).
+
+alter table kontrolia_auth.applications
+  add column plans_required boolean not null default false,
+  add column past_due_grace_days integer not null default 7 check (past_due_grace_days >= 0);
+
+comment on column kontrolia_auth.applications.plans_required is
+  'When true, a member only keeps the permissions of this application that the organization''s live subscription plan includes. False = plans are informational only, access is governed by roles alone.';
+comment on column kontrolia_auth.applications.past_due_grace_days is
+  'Days after a failed renewal (status past_due) during which the organization keeps access before the subscription stops counting as live.';
+
+-- ---------------------------------------------------------------------------
+-- Plans
+-- ---------------------------------------------------------------------------
+
+create table kontrolia_auth.plans (
+  id uuid primary key default gen_random_uuid(),
+  application_id uuid not null references kontrolia_auth.applications (id) on delete cascade,
+  slug text not null check (slug ~ '^[a-z0-9]+(?:-[a-z0-9]+)*$'),
+  name text not null,
+  description text,
+  -- Minor units (centavos/cents), never floats.
+  price_amount integer not null default 0 check (price_amount >= 0),
+  currency text not null default 'MXN' check (currency ~ '^[A-Z]{3}$'),
+  billing_interval text not null default 'month' check (billing_interval in ('month', 'year', 'one_time')),
+  trial_days integer not null default 0 check (trial_days >= 0),
+  -- Free-form marketing bullets ("Hasta 5 usuarios", "Soporte prioritario").
+  features jsonb not null default '[]'::jsonb check (jsonb_typeof(features) = 'array'),
+  is_active boolean not null default true,
+  -- Assigned automatically (as a manual subscription) when an organization
+  -- enables the application — the "free tier". At most one per application.
+  is_default boolean not null default false,
+  sort_order integer not null default 0,
+  stripe_product_id text,
+  stripe_price_id text,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique (application_id, slug)
+);
+
+create unique index plans_one_default_per_application on kontrolia_auth.plans (application_id) where is_default;
+create index plans_application_id_idx on kontrolia_auth.plans (application_id);
+
+comment on table kontrolia_auth.plans is 'Commercial tiers of an application (Startup / Pro / ...). What each unlocks lives in plan_permissions; quotas in plan_limits.';
+
+create table kontrolia_auth.plan_permissions (
+  plan_id uuid not null references kontrolia_auth.plans (id) on delete cascade,
+  permission_id uuid not null references kontrolia_auth.permissions (id) on delete cascade,
+  primary key (plan_id, permission_id)
+);
+
+comment on table kontrolia_auth.plan_permissions is 'Which of the application''s permissions a plan unlocks. Effective access for a member = role permissions ∩ this set (when the app has plans_required).';
+
+-- A plan can only reference permissions of its own application.
+create or replace function kontrolia_auth.enforce_plan_permission_same_application()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  plan_app uuid;
+  permission_app uuid;
+begin
+  select application_id into plan_app from kontrolia_auth.plans where id = new.plan_id;
+  select application_id into permission_app from kontrolia_auth.permissions where id = new.permission_id;
+  if plan_app is distinct from permission_app then
+    raise exception 'El permiso % no pertenece a la aplicación del plan %', new.permission_id, new.plan_id
+      using errcode = 'check_violation';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger plan_permissions_same_application
+  before insert or update on kontrolia_auth.plan_permissions
+  for each row execute function kontrolia_auth.enforce_plan_permission_same_application();
+
+create table kontrolia_auth.plan_limits (
+  plan_id uuid not null references kontrolia_auth.plans (id) on delete cascade,
+  -- Namespaced by the application itself, e.g. "facturas.emitidas", "miembros".
+  limit_key text not null check (limit_key ~ '^[a-z0-9_.-]+$'),
+  -- NULL = unlimited for this plan (still counted, never exceeded).
+  limit_value integer check (limit_value is null or limit_value >= 0),
+  period text not null default 'month' check (period in ('day', 'month', 'year', 'lifetime')),
+  description text,
+  primary key (plan_id, limit_key)
+);
+
+comment on table kontrolia_auth.plan_limits is 'Numeric quotas of a plan ("up to 100 invoices per month"). NULL limit_value = unlimited.';
+
+-- ---------------------------------------------------------------------------
+-- Subscriptions
+-- ---------------------------------------------------------------------------
+
+create table kontrolia_auth.subscriptions (
+  id uuid primary key default gen_random_uuid(),
+  organization_id uuid not null references kontrolia_auth.organizations (id) on delete cascade,
+  application_id uuid not null references kontrolia_auth.applications (id) on delete cascade,
+  -- restrict: a plan with subscriptions can't be deleted, only deactivated.
+  plan_id uuid not null references kontrolia_auth.plans (id) on delete restrict,
+  status text not null check (status in ('trialing', 'active', 'past_due', 'canceled', 'expired')),
+  current_period_start timestamptz,
+  -- NULL = open-ended (manual subscriptions, one-time purchases).
+  current_period_end timestamptz,
+  cancel_at_period_end boolean not null default false,
+  provider text not null default 'manual' check (provider in ('manual', 'stripe')),
+  provider_customer_id text,
+  provider_subscription_id text,
+  created_by uuid,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+-- One live subscription per (organization, application). Canceled/expired
+-- rows stay as history.
+create unique index subscriptions_one_live_per_org_app on kontrolia_auth.subscriptions (organization_id, application_id)
+  where status in ('trialing', 'active', 'past_due');
+create unique index subscriptions_provider_subscription_id on kontrolia_auth.subscriptions (provider, provider_subscription_id)
+  where provider_subscription_id is not null;
+create index subscriptions_org_app_idx on kontrolia_auth.subscriptions (organization_id, application_id);
+
+comment on table kontrolia_auth.subscriptions is 'An organization''s subscription to one plan of one application. Provider-managed (Stripe) or manual.';
+
+-- Single definition of "does this subscription currently grant access",
+-- shared by the token hook, the entitlements API and RLS. past_due keeps
+-- access for the application's grace window, measured from the end of the
+-- period whose renewal failed.
+create or replace function kontrolia_auth.subscription_is_live(s kontrolia_auth.subscriptions, grace_days integer)
+returns boolean
+language sql
+stable
+set search_path = ''
+as $$
+  select case
+    when s.status in ('trialing', 'active') then (s.current_period_end is null or s.current_period_end > now())
+    when s.status = 'past_due' then now() < coalesce(s.current_period_end, s.updated_at) + make_interval(days => coalesce(grace_days, 0))
+    else false
+  end
+$$;
+
+-- The live subscription of an organization for an application, if any.
+create or replace function kontrolia_auth.live_subscription(org_id uuid, app_id uuid)
+returns kontrolia_auth.subscriptions
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select s.*
+  from kontrolia_auth.subscriptions s
+  join kontrolia_auth.applications a on a.id = s.application_id
+  where s.organization_id = org_id
+    and s.application_id = app_id
+    and s.status in ('trialing', 'active', 'past_due')
+    and kontrolia_auth.subscription_is_live(s, a.past_due_grace_days)
+  limit 1
+$$;
+
+-- Enabling an application for an organization automatically subscribes it
+-- to the application's default plan (the free tier), so plans_required apps
+-- work from the first login instead of starting locked out. A trigger, not
+-- route code, because admin-panel enables apps with a direct client insert.
+create or replace function kontrolia_auth.subscribe_default_plan_on_enable()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  default_plan uuid;
+begin
+  select id into default_plan
+  from kontrolia_auth.plans
+  where application_id = new.application_id and is_default and is_active;
+
+  if default_plan is not null and not exists (
+    select 1 from kontrolia_auth.subscriptions
+    where organization_id = new.organization_id
+      and application_id = new.application_id
+      and status in ('trialing', 'active', 'past_due')
+  ) then
+    insert into kontrolia_auth.subscriptions (organization_id, application_id, plan_id, status, provider)
+    values (new.organization_id, new.application_id, default_plan, 'active', 'manual');
+  end if;
+  return new;
+end;
+$$;
+
+create trigger application_organizations_subscribe_default_plan
+  after insert on kontrolia_auth.application_organizations
+  for each row execute function kontrolia_auth.subscribe_default_plan_on_enable();
+
+create table kontrolia_auth.subscription_events (
+  id uuid primary key default gen_random_uuid(),
+  subscription_id uuid references kontrolia_auth.subscriptions (id) on delete set null,
+  organization_id uuid references kontrolia_auth.organizations (id) on delete set null,
+  application_id uuid references kontrolia_auth.applications (id) on delete set null,
+  type text not null,
+  provider text not null default 'manual',
+  -- Stripe event id; the unique index is what makes webhook delivery
+  -- idempotent (a redelivered event inserts nothing and is skipped).
+  provider_event_id text,
+  payload jsonb,
+  created_at timestamptz not null default now()
+);
+
+-- Plain (not partial) unique index: NULLs are distinct, so manual events
+-- without a provider id never collide, and PostgREST upserts with
+-- ignoreDuplicates can target it (partial indexes can't be an ON CONFLICT
+-- target without their predicate).
+create unique index subscription_events_provider_event_id on kontrolia_auth.subscription_events (provider, provider_event_id);
+create index subscription_events_org_app_idx on kontrolia_auth.subscription_events (organization_id, application_id, created_at desc);
+
+-- ---------------------------------------------------------------------------
+-- Usage
+-- ---------------------------------------------------------------------------
+
+create table kontrolia_auth.usage_counters (
+  organization_id uuid not null references kontrolia_auth.organizations (id) on delete cascade,
+  application_id uuid not null references kontrolia_auth.applications (id) on delete cascade,
+  limit_key text not null,
+  -- First day of the counting window; '1970-01-01' for lifetime limits.
+  period_start date not null,
+  used integer not null default 0 check (used >= 0),
+  updated_at timestamptz not null default now(),
+  primary key (organization_id, application_id, limit_key, period_start)
+);
+
+create table kontrolia_auth.usage_events (
+  id uuid primary key default gen_random_uuid(),
+  organization_id uuid not null references kontrolia_auth.organizations (id) on delete cascade,
+  application_id uuid not null references kontrolia_auth.applications (id) on delete cascade,
+  limit_key text not null,
+  amount integer not null,
+  idempotency_key text,
+  created_at timestamptz not null default now()
+);
+
+create unique index usage_events_idempotency on kontrolia_auth.usage_events (application_id, idempotency_key);
+
+create or replace function kontrolia_auth.usage_period_start(period text, moment timestamptz default now())
+returns date
+language sql
+stable
+set search_path = ''
+as $$
+  select case period
+    when 'day' then (moment at time zone 'UTC')::date
+    when 'month' then date_trunc('month', moment at time zone 'UTC')::date
+    when 'year' then date_trunc('year', moment at time zone 'UTC')::date
+    else date '1970-01-01'
+  end
+$$;
+
+-- Atomic usage report. Resolves the organization's live plan for the app,
+-- finds the limit (NULL limit = unlimited, still counted under a monthly
+-- window so it can be reported), increments the counter in one statement,
+-- and returns the resulting state. Idempotent per (application,
+-- idempotency_key): a retried report returns the current state without
+-- counting twice. Never blocks on its own — `exceeded` is information for
+-- the application to act on.
+create or replace function kontrolia_auth.record_usage(
+  org_id uuid,
+  app_id uuid,
+  key text,
+  amount integer default 1,
+  idempotency text default null
+)
+returns table (used integer, limit_value integer, period text, period_start date, exceeded boolean, plan_slug text)
+language plpgsql
+security definer
+set search_path = ''
+as $$
+-- The OUT columns share names with usage_counters columns; inside SQL
+-- statements (notably the ON CONFLICT target) the column must win.
+#variable_conflict use_column
+declare
+  live kontrolia_auth.subscriptions;
+  resolved_period text := 'month';
+  resolved_limit integer := null;
+  resolved_plan_slug text := null;
+  window_start date;
+  already_recorded boolean := false;
+  new_used integer;
+begin
+  if amount < 0 then
+    raise exception 'amount debe ser >= 0' using errcode = 'check_violation';
+  end if;
+
+  live := kontrolia_auth.live_subscription(org_id, app_id);
+  if live.id is not null then
+    select pl.period, pl.limit_value, p.slug
+      into resolved_period, resolved_limit, resolved_plan_slug
+    from kontrolia_auth.plans p
+    left join kontrolia_auth.plan_limits pl on pl.plan_id = p.id and pl.limit_key = key
+    where p.id = live.plan_id;
+    resolved_period := coalesce(resolved_period, 'month');
+  end if;
+
+  window_start := kontrolia_auth.usage_period_start(resolved_period);
+
+  if idempotency is not null then
+    insert into kontrolia_auth.usage_events (organization_id, application_id, limit_key, amount, idempotency_key)
+    values (org_id, app_id, key, amount, idempotency)
+    on conflict (application_id, idempotency_key) do nothing;
+    already_recorded := not found;
+  else
+    insert into kontrolia_auth.usage_events (organization_id, application_id, limit_key, amount)
+    values (org_id, app_id, key, amount);
+  end if;
+
+  if already_recorded or amount = 0 then
+    select c.used into new_used
+    from kontrolia_auth.usage_counters c
+    where c.organization_id = org_id and c.application_id = app_id and c.limit_key = key and c.period_start = window_start;
+    new_used := coalesce(new_used, 0);
+  else
+    insert into kontrolia_auth.usage_counters as c (organization_id, application_id, limit_key, period_start, used)
+    values (org_id, app_id, key, window_start, amount)
+    on conflict (organization_id, application_id, limit_key, period_start)
+      do update set used = c.used + excluded.used, updated_at = now()
+    returning c.used into new_used;
+  end if;
+
+  return query select
+    new_used,
+    resolved_limit,
+    resolved_period,
+    window_start,
+    (resolved_limit is not null and new_used > resolved_limit),
+    resolved_plan_slug;
+end;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- RLS
+-- ---------------------------------------------------------------------------
+
+alter table kontrolia_auth.plans enable row level security;
+alter table kontrolia_auth.plan_permissions enable row level security;
+alter table kontrolia_auth.plan_limits enable row level security;
+alter table kontrolia_auth.subscriptions enable row level security;
+alter table kontrolia_auth.subscription_events enable row level security;
+alter table kontrolia_auth.usage_counters enable row level security;
+alter table kontrolia_auth.usage_events enable row level security;
+
+-- Pricing is public by nature (an app shows it to prospects) — same breadth
+-- as the application catalog itself. All writes go through auth-server's
+-- service-role routes (platform admin), never from a client session.
+create policy "authenticated users can browse plans" on kontrolia_auth.plans
+  for select to authenticated using (true);
+create policy "authenticated users can browse plan permissions" on kontrolia_auth.plan_permissions
+  for select to authenticated using (true);
+create policy "authenticated users can browse plan limits" on kontrolia_auth.plan_limits
+  for select to authenticated using (true);
+
+create policy "org members can view their subscriptions" on kontrolia_auth.subscriptions
+  for select to authenticated
+  using (kontrolia_auth.is_org_member(organization_id) or kontrolia_auth.is_platform_admin());
+
+create policy "org admins can view their subscription events" on kontrolia_auth.subscription_events
+  for select to authenticated
+  using ((organization_id is not null and kontrolia_auth.is_org_admin(organization_id)) or kontrolia_auth.is_platform_admin());
+
+create policy "org members can view their usage" on kontrolia_auth.usage_counters
+  for select to authenticated
+  using (kontrolia_auth.is_org_member(organization_id) or kontrolia_auth.is_platform_admin());
+
+create policy "org admins can view their usage events" on kontrolia_auth.usage_events
+  for select to authenticated
+  using (kontrolia_auth.is_org_admin(organization_id) or kontrolia_auth.is_platform_admin());
+
+-- Migration 0008's default privileges already grant authenticated/service_role
+-- table access (RLS above is what actually scopes it); the token hook runs
+-- as supabase_auth_admin and needs its own grants on everything it reads.
+grant select on kontrolia_auth.applications to supabase_auth_admin;
+grant select on kontrolia_auth.plans to supabase_auth_admin;
+grant select on kontrolia_auth.plan_permissions to supabase_auth_admin;
+grant select on kontrolia_auth.subscriptions to supabase_auth_admin;
+
+-- ---------------------------------------------------------------------------
+-- Token hook: intersect with the live plan, expose the plans claim
+-- ---------------------------------------------------------------------------
+
+create or replace function kontrolia_auth.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  claims jsonb;
+  target_user_id uuid;
+  active_org_id uuid;
+  active_membership_id uuid;
+  role_names text[];
+  permission_keys text[];
+  platform_admin boolean;
+  plan_claims jsonb;
+begin
+  claims := coalesce(event->'claims', '{}'::jsonb);
+  target_user_id := (event->>'user_id')::uuid;
+
+  select active_organization_id into active_org_id
+  from kontrolia_auth.sessions_context
+  where user_id = target_user_id;
+
+  if active_org_id is null then
+    select organization_id into active_org_id
+    from kontrolia_auth.memberships
+    where user_id = target_user_id and status = 'active'
+    order by created_at asc
+    limit 1;
+  end if;
+
+  if active_org_id is not null then
+    select id into active_membership_id
+    from kontrolia_auth.memberships
+    where user_id = target_user_id
+      and organization_id = active_org_id
+      and status = 'active';
+  end if;
+
+  if active_membership_id is not null then
+    select coalesce(array_agg(distinct r.slug), '{}')
+      into role_names
+    from kontrolia_auth.membership_roles mr
+    join kontrolia_auth.roles r on r.id = mr.role_id
+    where mr.membership_id = active_membership_id and r.is_system_role;
+
+    select coalesce(array_agg(distinct p.key), '{}')
+      into permission_keys
+    from (
+      select p.id, p.key
+      from kontrolia_auth.membership_roles mr
+      join kontrolia_auth.role_permissions rp on rp.role_id = mr.role_id
+      join kontrolia_auth.permissions p on p.id = rp.permission_id
+      where mr.membership_id = active_membership_id
+      union
+      select p.id, p.key
+      from kontrolia_auth.user_permissions up
+      join kontrolia_auth.permissions p on p.id = up.permission_id
+      where up.membership_id = active_membership_id and up.effect = 'allow'
+    ) p
+    where not exists (
+      select 1 from kontrolia_auth.user_permissions up_deny
+      where up_deny.membership_id = active_membership_id
+        and up_deny.permission_id = p.id
+        and up_deny.effect = 'deny'
+    );
+
+    -- Plan gate: for applications that require a plan, keep only the
+    -- permissions the organization's live subscription plan includes.
+    -- Applications without plans_required pass through untouched.
+    select coalesce(array_agg(pk), '{}')
+      into permission_keys
+    from unnest(permission_keys) pk
+    join kontrolia_auth.permissions p on p.key = pk
+    join kontrolia_auth.applications a on a.id = p.application_id
+    where not a.plans_required
+       or exists (
+         select 1
+         from kontrolia_auth.subscriptions s
+         join kontrolia_auth.plan_permissions pp on pp.plan_id = s.plan_id and pp.permission_id = p.id
+         where s.organization_id = active_org_id
+           and s.application_id = a.id
+           and s.status in ('trialing', 'active', 'past_due')
+           and kontrolia_auth.subscription_is_live(s, a.past_due_grace_days)
+       );
+
+    -- { "<app slug>": "<plan slug>" } for every live subscription of the
+    -- active organization — enough for an app to show "Plan Pro" without a
+    -- round trip; limits and usage are deliberately NOT here (they change
+    -- with every use — see GET /api/entitlements).
+    select coalesce(jsonb_object_agg(a.slug, p.slug), '{}'::jsonb)
+      into plan_claims
+    from kontrolia_auth.subscriptions s
+    join kontrolia_auth.applications a on a.id = s.application_id
+    join kontrolia_auth.plans p on p.id = s.plan_id
+    where s.organization_id = active_org_id
+      and s.status in ('trialing', 'active', 'past_due')
+      and kontrolia_auth.subscription_is_live(s, a.past_due_grace_days);
+  else
+    role_names := '{}';
+    permission_keys := '{}';
+    plan_claims := '{}'::jsonb;
+  end if;
+
+  select exists(select 1 from kontrolia_auth.platform_admins where user_id = target_user_id) into platform_admin;
+
+  claims := jsonb_set(claims, '{organization_id}', coalesce(to_jsonb(active_org_id), 'null'::jsonb));
+  claims := jsonb_set(claims, '{roles}', to_jsonb(coalesce(role_names, '{}')));
+  claims := jsonb_set(claims, '{permissions}', to_jsonb(coalesce(permission_keys, '{}')));
+  claims := jsonb_set(claims, '{plans}', coalesce(plan_claims, '{}'::jsonb));
+  claims := jsonb_set(claims, '{is_platform_admin}', to_jsonb(coalesce(platform_admin, false)));
+
+  event := jsonb_set(event, '{claims}', claims);
+  return event;
+end;
+$$;
+
+grant execute on function kontrolia_auth.subscription_is_live(kontrolia_auth.subscriptions, integer) to supabase_auth_admin, authenticated, service_role;
+grant execute on function kontrolia_auth.live_subscription(uuid, uuid) to authenticated, service_role;
+grant execute on function kontrolia_auth.record_usage(uuid, uuid, text, integer, text) to service_role;

package/migrations/0045_grant_plan_columns_select.sql

@@ -0,0 +1,8 @@
+-- 0032 replaced authenticated's table-level SELECT on applications with an
+-- explicit column list (to hide api_key_hash), and 0037 had to add
+-- oauth_client_id to it for the same reason: any column added afterwards
+-- is invisible to authenticated until it's granted explicitly, and
+-- Postgres reports that as "permission denied for table applications"
+-- on any query that names it — which is what PATCH /api/applications/[id]
+-- and GET /api/applications hit after 0044 added these two.
+grant select (plans_required, past_due_grace_days) on kontrolia_auth.applications to authenticated;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontrolia/db",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "license": "MIT",
   "description": "KontrolIA Auth database layer: SQL migrations for the `kontrolia` schema (organizations, RBAC, Custom Access Token Hook) and a connection-string-agnostic migration runner.",
   "keywords": [