@kontrolia/db 2.1.4 → 2.2.0

package/dist/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,cAAc;IAC7B;;sDAEkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAWD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,EAAE,gBAAgB,EAAE,OAAe,EAAE,EAAE,cAAc,iBAgClF"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,cAAc;IAC7B;;sDAEkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAsCD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,EAAE,gBAAgB,EAAE,OAAe,EAAE,EAAE,cAAc,iBAgClF"}

package/dist/migrate.js

@@ -4,13 +4,34 @@ import { fileURLToPath } from "node:url";
 import { Client } from "pg";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const MIGRATIONS_DIR = join(__dirname, "..", "migrations");
+/**
+ * Bootstraps (and self-heals the location of) the migration-tracking
+ * table, then returns its schema-qualified name for the rest of migrate()
+ * to use. On a genuinely fresh database neither `kontrolia` nor
+ * `kontrolia_auth` exists yet — migration 0001 is what creates the former,
+ * 0020 renames it to the latter — so this table has nowhere but `public`
+ * to start out in. Once `kontrolia_auth` exists (every subsequent run,
+ * fresh or not), it belongs there instead: an install that ran migrate()
+ * before this fix shipped may still have it sitting in `public`, so this
+ * relocates it once, idempotently, rather than leaving two copies around.
+ */
 async function ensureMigrationsTable(client) {
+    const { rows: schemaRows } = await client.query(`select exists (select 1 from information_schema.schemata where schema_name = 'kontrolia_auth') as exists`);
+    const kontroliaAuthExists = schemaRows[0]?.exists ?? false;
+    if (kontroliaAuthExists) {
+        const { rows: publicRows } = await client.query(`select exists (select 1 from information_schema.tables where table_schema = 'public' and table_name = 'kontrolia_migrations') as exists`);
+        if (publicRows[0]?.exists) {
+            await client.query("alter table public.kontrolia_migrations set schema kontrolia_auth");
+        }
+    }
+    const schema = kontroliaAuthExists ? "kontrolia_auth" : "public";
     await client.query(`
-    create table if not exists kontrolia_migrations (
+    create table if not exists ${schema}.kontrolia_migrations (
       filename text primary key,
       applied_at timestamptz not null default now()
     )
   `);
+    return schema;
 }
 /**
  * Applies every .sql file under migrations/ that hasn't run yet, in
@@ -20,8 +41,8 @@ export async function migrate({ connectionString, verbose = false }) {
     const client = new Client({ connectionString });
     await client.connect();
     try {
-        await ensureMigrationsTable(client);
-        const { rows: applied } = await client.query("select filename from kontrolia_migrations");
+        const migrationsTable = `${await ensureMigrationsTable(client)}.kontrolia_migrations`;
+        const { rows: applied } = await client.query(`select filename from ${migrationsTable}`);
         const appliedSet = new Set(applied.map((r) => r.filename));
         const files = (await readdir(MIGRATIONS_DIR)).filter((f) => f.endsWith(".sql")).sort();
         for (const file of files) {
@@ -33,7 +54,7 @@ export async function migrate({ connectionString, verbose = false }) {
             await client.query("begin");
             try {
                 await client.query(sql);
-                await client.query("insert into kontrolia_migrations (filename) values ($1)", [file]);
+                await client.query(`insert into ${migrationsTable} (filename) values ($1)`, [file]);
                 await client.query("commit");
             }
             catch (error) {

package/dist/register-application.d.ts

@@ -14,14 +14,6 @@ export interface RegisterApplicationOptions {
 export interface RegisteredApplication {
     applicationId: string;
     permissionKeys: string[];
-    /**
-     * The plaintext sync API key (see POST /api/applications/sync on
-     * auth-server) — only present the first time this slug is registered.
-     * Only the hash is stored; there is no way to recover it later, so the
-     * caller must surface it to the operator immediately. `null` means the
-     * application already existed and its key (if any) was left untouched.
-     */
-    apiKey: string | null;
 }
 /**
  * Inserts an application and its permission catalog directly against
@@ -30,7 +22,15 @@ export interface RegisteredApplication {
  * go through a platform-admin path), so this is that path: a direct,
  * service-role-equivalent write, the same way migrate() bypasses RLS to
  * apply schema changes. Safe to re-run — the slug and permission key are
- * both upserted, and re-running never rotates an existing api_key_hash.
+ * both upserted.
+ *
+ * Does NOT generate a sync API key — migration 0040 moved keys off
+ * `applications` onto the org-scoped `application_api_keys` table, and at
+ * the point this runs (typically during install, before any organization
+ * necessarily exists or has enabled the app) there's no organization to
+ * scope one to. Generate the first key afterward from admin-panel
+ * (Aplicaciones → tu app → API Keys), once at least one organization has
+ * enabled the application.
  */
 export declare function registerApplication(options: RegisterApplicationOptions): Promise<RegisteredApplication>;
 //# sourceMappingURL=register-application.d.ts.map

package/dist/register-application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-application.d.ts","sourceRoot":"","sources":["../src/register-application.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;IACtD,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkC7G"}
+{"version":3,"file":"register-application.d.ts","sourceRoot":"","sources":["../src/register-application.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;IACtD,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgC7G"}

package/dist/register-application.js

@@ -1,5 +1,4 @@
 import { Client } from "pg";
-import { generateApplicationApiKey, hashApplicationApiKey } from "./api-key.js";
 /**
  * Inserts an application and its permission catalog directly against
  * Postgres. kontrolia_auth.applications/permissions have no insert policy for
@@ -7,17 +6,24 @@ import { generateApplicationApiKey, hashApplicationApiKey } from "./api-key.js";
  * go through a platform-admin path), so this is that path: a direct,
  * service-role-equivalent write, the same way migrate() bypasses RLS to
  * apply schema changes. Safe to re-run — the slug and permission key are
- * both upserted, and re-running never rotates an existing api_key_hash.
+ * both upserted.
+ *
+ * Does NOT generate a sync API key — migration 0040 moved keys off
+ * `applications` onto the org-scoped `application_api_keys` table, and at
+ * the point this runs (typically during install, before any organization
+ * necessarily exists or has enabled the app) there's no organization to
+ * scope one to. Generate the first key afterward from admin-panel
+ * (Aplicaciones → tu app → API Keys), once at least one organization has
+ * enabled the application.
  */
 export async function registerApplication(options) {
     const client = new Client({ connectionString: options.connectionString });
     await client.connect();
     try {
-        const candidateApiKey = generateApplicationApiKey();
-        const { rows: [application], } = await client.query(`insert into kontrolia_auth.applications (name, slug, environment, api_key_hash)
-       values ($1, $2, $3, $4)
+        const { rows: [application], } = await client.query(`insert into kontrolia_auth.applications (name, slug, environment)
+       values ($1, $2, $3)
        on conflict (slug) do update set name = excluded.name, environment = excluded.environment
-       returning id, (xmax = 0) as inserted`, [options.name, options.slug, options.environment, hashApplicationApiKey(candidateApiKey)]);
+       returning id`, [options.name, options.slug, options.environment]);
         if (!application)
             throw new Error(`Failed to upsert application "${options.slug}"`);
         const permissionKeys = [];
@@ -28,7 +34,7 @@ export async function registerApplication(options) {
          on conflict (key) do update set description = excluded.description`, [application.id, permission.resource, permission.action, key, permission.description ?? null]);
             permissionKeys.push(key);
         }
-        return { applicationId: application.id, permissionKeys, apiKey: application.inserted ? candidateApiKey : null };
+        return { applicationId: application.id, permissionKeys };
     }
     finally {
         await client.end();

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.4",
+  "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": [