@kontrolia/db 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KontrolIA Auth Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @kontrolia/db
+
+Migraciones SQL del schema `kontrolia` (organizaciones, RBAC jerárquico, invitaciones, dispositivos, audit log) y el Custom Access Token Hook que enriquece el JWT con `organization_id`, `roles` y `permissions` de la organización activa del usuario.
+
+Diseñado para aplicarse igual sobre:
+- un proyecto Supabase **existente** (Cloud o self-hosted) — solo aísla sus tablas en el schema `kontrolia`, no toca `public`;
+- un proyecto Supabase **nuevo** levantado localmente por `docker/docker-compose.yml`.
+
+## Uso
+
+```bash
+DATABASE_URL="postgres://postgres:postgres@localhost:5432/postgres" pnpm --filter @kontrolia/db migrate
+```
+
+## Activar el hook
+
+- **Self-hosted**: variable de entorno de GoTrue `GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI=pg-functions://postgres/kontrolia/custom_access_token_hook` (ver `docker/docker-compose.yml`).
+- **Supabase Cloud**: paso manual en el Dashboard → Authentication → Hooks → Custom Access Token → seleccionar `kontrolia.custom_access_token_hook`. No automatizable por API pública.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { migrate } from "./migrate.js";
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) {
+    console.error("[kontrolia-db] DATABASE_URL is not set. Point it at your existing Supabase project's Postgres connection string, or at the local docker-compose Postgres.");
+    process.exit(1);
+}
+migrate({ connectionString, verbose: true })
+    .then(() => {
+    console.log("[kontrolia-db] migrations applied successfully.");
+})
+    .catch((error) => {
+    console.error("[kontrolia-db] migration failed:", error);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { migrate, type MigrateOptions } from "./migrate.js";
+export { registerApplication, type RegisterApplicationOptions, type RegisteredApplication, type PermissionInput, } from "./register-application.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { migrate } from "./migrate.js";
+export { registerApplication, } from "./register-application.js";

package/dist/migrate.d.ts

@@ -0,0 +1,14 @@
+export interface MigrateOptions {
+    /** Postgres connection string. Works against a fresh self-hosted instance
+     * or an existing Supabase project (Cloud or self-hosted) — the migrations
+     * only ever touch the `kontrolia` schema. */
+    connectionString: string;
+    /** Print each statement before running it. */
+    verbose?: boolean;
+}
+/**
+ * Applies every .sql file under migrations/ that hasn't run yet, in
+ * filename order, inside its own transaction. Safe to re-run.
+ */
+export declare function migrate({ connectionString, verbose }: MigrateOptions): Promise<void>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,cAAc;IAC7B;;iDAE6C;IAC7C,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"}

package/dist/migrate.js

@@ -0,0 +1,48 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "pg";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATIONS_DIR = join(__dirname, "..", "migrations");
+async function ensureMigrationsTable(client) {
+    await client.query(`
+    create table if not exists kontrolia_migrations (
+      filename text primary key,
+      applied_at timestamptz not null default now()
+    )
+  `);
+}
+/**
+ * Applies every .sql file under migrations/ that hasn't run yet, in
+ * filename order, inside its own transaction. Safe to re-run.
+ */
+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 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) {
+            if (appliedSet.has(file))
+                continue;
+            const sql = await readFile(join(MIGRATIONS_DIR, file), "utf8");
+            if (verbose)
+                console.log(`[kontrolia-db] applying ${file}`);
+            await client.query("begin");
+            try {
+                await client.query(sql);
+                await client.query("insert into kontrolia_migrations (filename) values ($1)", [file]);
+                await client.query("commit");
+            }
+            catch (error) {
+                await client.query("rollback");
+                throw new Error(`Migration ${file} failed: ${error.message}`, { cause: error });
+            }
+        }
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/register-application.d.ts

@@ -0,0 +1,28 @@
+export interface PermissionInput {
+    resource: string;
+    action: string;
+    description?: string;
+}
+export interface RegisterApplicationOptions {
+    /** Postgres connection string — same one migrate() uses. */
+    connectionString: string;
+    name: string;
+    slug: string;
+    environment: "development" | "staging" | "production";
+    permissions: PermissionInput[];
+}
+export interface RegisteredApplication {
+    applicationId: string;
+    permissionKeys: string[];
+}
+/**
+ * Inserts an application and its permission catalog directly against
+ * Postgres. kontrolia.applications/permissions have no insert policy for
+ * regular users (see migrations/0010_rls_policies.sql — writes are meant to
+ * go through a platform-admin path) and no such admin API exists yet, 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.
+ */
+export declare function registerApplication(options: RegisterApplicationOptions): Promise<RegisteredApplication>;
+//# sourceMappingURL=register-application.d.ts.map

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

@@ -0,0 +1 @@
+{"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;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgC7G"}

package/dist/register-application.js

@@ -0,0 +1,34 @@
+import { Client } from "pg";
+/**
+ * Inserts an application and its permission catalog directly against
+ * Postgres. kontrolia.applications/permissions have no insert policy for
+ * regular users (see migrations/0010_rls_policies.sql — writes are meant to
+ * go through a platform-admin path) and no such admin API exists yet, 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.
+ */
+export async function registerApplication(options) {
+    const client = new Client({ connectionString: options.connectionString });
+    await client.connect();
+    try {
+        const { rows: [application], } = await client.query(`insert into kontrolia.applications (name, slug, environment)
+       values ($1, $2, $3)
+       on conflict (slug) do update set name = excluded.name, environment = excluded.environment
+       returning id`, [options.name, options.slug, options.environment]);
+        if (!application)
+            throw new Error(`Failed to upsert application "${options.slug}"`);
+        const permissionKeys = [];
+        for (const permission of options.permissions) {
+            const key = `${options.slug}.${permission.resource}.${permission.action}`;
+            await client.query(`insert into kontrolia.permissions (application_id, resource, action, key, description)
+         values ($1, $2, $3, $4, $5)
+         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 };
+    }
+    finally {
+        await client.end();
+    }
+}

package/migrations/0001_schema_and_extensions.sql

@@ -0,0 +1,10 @@
+-- KontrolIA Auth — bootstrap schema
+-- All KontrolIA tables live in a dedicated `kontrolia` schema so this migration
+-- is safe to run against a Supabase project that already has application
+-- tables in `public` (existing-project install path).
+
+create schema if not exists kontrolia;
+
+create extension if not exists pgcrypto with schema public;
+
+comment on schema kontrolia is 'KontrolIA Auth — organizations, RBAC and application registry. Isolated from the host project public schema.';

package/migrations/0002_organizations.sql

@@ -0,0 +1,12 @@
+create table kontrolia.organizations (
+  id uuid primary key default gen_random_uuid(),
+  name text not null,
+  slug text not null unique,
+  settings jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+comment on table kontrolia.organizations is 'Tenants. A user can belong to many organizations via kontrolia.memberships.';
+
+create index organizations_slug_idx on kontrolia.organizations (slug);

package/migrations/0003_applications_and_permissions.sql

@@ -0,0 +1,41 @@
+-- An "application" (Facturación, CRM, Inventarios...) declares its own
+-- permission catalog when registered. Organizations can only assign, in their
+-- roles, permissions from applications they have enabled.
+
+create table kontrolia.applications (
+  id uuid primary key default gen_random_uuid(),
+  name text not null,
+  slug text not null unique,
+  owner_organization_id uuid references kontrolia.organizations (id) on delete set null,
+  environment text not null default 'production' check (environment in ('development', 'staging', 'production')),
+  redirect_urls text[] not null default '{}',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+comment on table kontrolia.applications is 'Registered client applications. oauth_clients (v2) attach real OAuth2 credentials to a row here.';
+
+create table kontrolia.application_organizations (
+  application_id uuid not null references kontrolia.applications (id) on delete cascade,
+  organization_id uuid not null references kontrolia.organizations (id) on delete cascade,
+  enabled_at timestamptz not null default now(),
+  primary key (application_id, organization_id)
+);
+
+comment on table kontrolia.application_organizations is 'Which organizations have which applications enabled — gates which permissions can be assigned in that org''s roles.';
+
+create table kontrolia.permissions (
+  id uuid primary key default gen_random_uuid(),
+  application_id uuid not null references kontrolia.applications (id) on delete cascade,
+  resource text not null,
+  action text not null,
+  key text not null unique,
+  description text,
+  created_at timestamptz not null default now(),
+  unique (application_id, resource, action)
+);
+
+comment on table kontrolia.permissions is 'Hierarchical permission catalog, e.g. key = "facturacion.facturas.crear" (resource = "facturas", action = "crear").';
+
+create index permissions_application_id_idx on kontrolia.permissions (application_id);
+create index permissions_key_idx on kontrolia.permissions (key);

package/migrations/0004_roles.sql

@@ -0,0 +1,30 @@
+-- organization_id = null marks a system role (Owner/Admin/Member), seeded once
+-- and assignable in every organization. Non-null organization_id marks a
+-- custom role scoped to that organization only.
+
+create table kontrolia.roles (
+  id uuid primary key default gen_random_uuid(),
+  organization_id uuid references kontrolia.organizations (id) on delete cascade,
+  name text not null,
+  slug text not null,
+  is_system_role boolean not null default false,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique (organization_id, slug)
+);
+
+comment on table kontrolia.roles is 'organization_id NULL = system role (Owner/Admin/Member), shared across all orgs. Non-null = org-custom role.';
+
+create table kontrolia.role_permissions (
+  role_id uuid not null references kontrolia.roles (id) on delete cascade,
+  permission_id uuid not null references kontrolia.permissions (id) on delete cascade,
+  primary key (role_id, permission_id)
+);
+
+-- Seed the three system roles KontrolIA ships out of the box.
+insert into kontrolia.roles (organization_id, name, slug, is_system_role)
+values
+  (null, 'Owner', 'owner', true),
+  (null, 'Admin', 'admin', true),
+  (null, 'Member', 'member', true)
+on conflict do nothing;

package/migrations/0005_memberships.sql

@@ -0,0 +1,42 @@
+create table kontrolia.memberships (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  organization_id uuid not null references kontrolia.organizations (id) on delete cascade,
+  status text not null default 'active' check (status in ('active', 'invited', 'suspended')),
+  invited_by uuid references auth.users (id) on delete set null,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique (user_id, organization_id)
+);
+
+comment on table kontrolia.memberships is 'A user''s membership in one organization. A user can hold many memberships (multi-org).';
+
+create index memberships_user_id_idx on kontrolia.memberships (user_id);
+create index memberships_organization_id_idx on kontrolia.memberships (organization_id);
+
+create table kontrolia.membership_roles (
+  membership_id uuid not null references kontrolia.memberships (id) on delete cascade,
+  role_id uuid not null references kontrolia.roles (id) on delete cascade,
+  primary key (membership_id, role_id)
+);
+
+-- Point-in-time allow/deny overrides on top of the roles' permissions,
+-- e.g. granting one extra permission to a Member without creating a new role.
+create table kontrolia.user_permissions (
+  membership_id uuid not null references kontrolia.memberships (id) on delete cascade,
+  permission_id uuid not null references kontrolia.permissions (id) on delete cascade,
+  effect text not null check (effect in ('allow', 'deny')),
+  primary key (membership_id, permission_id)
+);
+
+comment on table kontrolia.user_permissions is 'Per-membership overrides. "deny" always wins over any role-granted permission.';
+
+-- Which organization is "active" for a user's current session — the Custom
+-- Access Token Hook reads this to decide which org''s roles/permissions to
+-- embed in the JWT. switchOrganization() in the SDK updates this row and
+-- forces a session refresh.
+create table kontrolia.sessions_context (
+  user_id uuid primary key references auth.users (id) on delete cascade,
+  active_organization_id uuid references kontrolia.organizations (id) on delete set null,
+  updated_at timestamptz not null default now()
+);

package/migrations/0006_invitations_devices_audit.sql

@@ -0,0 +1,41 @@
+create table kontrolia.invitations (
+  id uuid primary key default gen_random_uuid(),
+  organization_id uuid not null references kontrolia.organizations (id) on delete cascade,
+  email text not null,
+  role_id uuid references kontrolia.roles (id) on delete set null,
+  token text not null unique default encode(gen_random_bytes(24), 'hex'),
+  invited_by uuid references auth.users (id) on delete set null,
+  accepted_at timestamptz,
+  expires_at timestamptz not null default (now() + interval '7 days'),
+  created_at timestamptz not null default now()
+);
+
+create index invitations_organization_id_idx on kontrolia.invitations (organization_id);
+create index invitations_email_idx on kontrolia.invitations (email);
+
+create table kontrolia.devices (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  session_id uuid,
+  label text,
+  user_agent text,
+  ip inet,
+  last_seen_at timestamptz not null default now(),
+  created_at timestamptz not null default now()
+);
+
+create index devices_user_id_idx on kontrolia.devices (user_id);
+
+create table kontrolia.audit_logs (
+  id uuid primary key default gen_random_uuid(),
+  organization_id uuid references kontrolia.organizations (id) on delete cascade,
+  actor_user_id uuid references auth.users (id) on delete set null,
+  action text not null,
+  target_type text,
+  target_id text,
+  metadata jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+
+create index audit_logs_organization_id_idx on kontrolia.audit_logs (organization_id);
+create index audit_logs_created_at_idx on kontrolia.audit_logs (created_at desc);

package/migrations/0007_custom_access_token_hook.sql

@@ -0,0 +1,93 @@
+-- Custom Access Token Hook: runs inside GoTrue's own transaction whenever a
+-- JWT is issued (login, refresh). Embeds organization_id, roles and
+-- permissions for the user's *active* organization only — never for every
+-- organization the user belongs to, to keep the token small and avoid
+-- leaking permissions across tenants. switchOrganization() in the SDK
+-- updates kontrolia.sessions_context and triggers a session refresh so this
+-- hook re-runs with the new active organization.
+
+create or replace function kontrolia.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[];
+begin
+  claims := coalesce(event->'claims', '{}'::jsonb);
+  target_user_id := (event->>'user_id')::uuid;
+
+  select active_organization_id into active_org_id
+  from kontrolia.sessions_context
+  where user_id = target_user_id;
+
+  if active_org_id is null then
+    select organization_id into active_org_id
+    from kontrolia.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.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.membership_roles mr
+    join kontrolia.roles r on r.id = mr.role_id
+    where mr.membership_id = active_membership_id;
+
+    select coalesce(array_agg(distinct p.key), '{}')
+      into permission_keys
+    from (
+      select p.id, p.key
+      from kontrolia.membership_roles mr
+      join kontrolia.role_permissions rp on rp.role_id = mr.role_id
+      join kontrolia.permissions p on p.id = rp.permission_id
+      where mr.membership_id = active_membership_id
+      union
+      select p.id, p.key
+      from kontrolia.user_permissions up
+      join kontrolia.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.user_permissions up_deny
+      where up_deny.membership_id = active_membership_id
+        and up_deny.permission_id = p.id
+        and up_deny.effect = 'deny'
+    );
+  else
+    role_names := '{}';
+    permission_keys := '{}';
+  end if;
+
+  -- to_jsonb(NULL::uuid) is SQL NULL, not a jsonb null — and jsonb_set is
+  -- strict, so passing it straight through would collapse the whole
+  -- function's result to NULL for any user without an organization yet
+  -- (i.e. every brand-new signup). coalesce() converts that to a real
+  -- jsonb null instead.
+  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, '{}')));
+
+  event := jsonb_set(event, '{claims}', claims);
+  return event;
+end;
+$$;
+
+comment on function kontrolia.custom_access_token_hook is 'Supabase Auth Custom Access Token Hook. Wire via GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI=pg-functions://postgres/kontrolia/custom_access_token_hook (self-hosted) or Dashboard > Authentication > Hooks (Supabase Cloud — manual step, cannot be automated by the CLI).';

package/migrations/0008_grants_and_hook_permissions.sql

@@ -0,0 +1,33 @@
+-- Least-privilege wiring for the hook, per Supabase's guidance: only
+-- supabase_auth_admin (GoTrue's own role) may execute it.
+
+grant usage on schema kontrolia to supabase_auth_admin;
+grant execute on function kontrolia.custom_access_token_hook(jsonb) to supabase_auth_admin;
+revoke execute on function kontrolia.custom_access_token_hook(jsonb) from authenticated, anon, public;
+
+-- The hook reads these tables inside the SECURITY DEFINER function above, so
+-- supabase_auth_admin needs SELECT even though end users never query them
+-- directly (RLS below blocks that path).
+grant select on kontrolia.sessions_context to supabase_auth_admin;
+grant select on kontrolia.memberships to supabase_auth_admin;
+grant select on kontrolia.membership_roles to supabase_auth_admin;
+grant select on kontrolia.roles to supabase_auth_admin;
+grant select on kontrolia.role_permissions to supabase_auth_admin;
+grant select on kontrolia.permissions to supabase_auth_admin;
+grant select on kontrolia.user_permissions to supabase_auth_admin;
+
+-- Expose the schema to PostgREST for authenticated/anon access, gated by RLS.
+grant usage on schema kontrolia to authenticated, anon;
+grant select, insert, update, delete on all tables in schema kontrolia to authenticated;
+grant select on all tables in schema kontrolia to anon;
+alter default privileges in schema kontrolia grant select, insert, update, delete on tables to authenticated;
+
+-- service_role bypasses RLS (Supabase grants it BYPASSRLS), but table-level
+-- and schema-level GRANTs are separate from RLS and still apply — without
+-- these, server-only code using the service-role key (e.g. the invitation
+-- acceptance flow, which must read/write before the visitor is even
+-- authenticated) gets "permission denied for schema kontrolia" from
+-- PostgREST.
+grant usage on schema kontrolia to service_role;
+grant select, insert, update, delete on all tables in schema kontrolia to service_role;
+alter default privileges in schema kontrolia grant select, insert, update, delete on tables to service_role;

package/migrations/0009_helper_functions.sql

@@ -0,0 +1,39 @@
+-- Helpers reused by RLS policies below. security definer + fixed search_path
+-- so they can safely read kontrolia tables regardless of the caller's RLS.
+
+create or replace function kontrolia.is_org_member(org_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from kontrolia.memberships m
+    where m.organization_id = org_id
+      and m.user_id = auth.uid()
+      and m.status = 'active'
+  );
+$$;
+
+create or replace function kontrolia.is_org_admin(org_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1
+    from kontrolia.memberships m
+    join kontrolia.membership_roles mr on mr.membership_id = m.id
+    join kontrolia.roles r on r.id = mr.role_id
+    where m.organization_id = org_id
+      and m.user_id = auth.uid()
+      and m.status = 'active'
+      and r.slug in ('owner', 'admin')
+  );
+$$;
+
+grant execute on function kontrolia.is_org_member(uuid) to authenticated;
+grant execute on function kontrolia.is_org_admin(uuid) to authenticated;

package/migrations/0010_rls_policies.sql

@@ -0,0 +1,103 @@
+alter table kontrolia.organizations enable row level security;
+alter table kontrolia.applications enable row level security;
+alter table kontrolia.application_organizations enable row level security;
+alter table kontrolia.permissions enable row level security;
+alter table kontrolia.roles enable row level security;
+alter table kontrolia.role_permissions enable row level security;
+alter table kontrolia.memberships enable row level security;
+alter table kontrolia.membership_roles enable row level security;
+alter table kontrolia.user_permissions enable row level security;
+alter table kontrolia.invitations enable row level security;
+alter table kontrolia.sessions_context enable row level security;
+alter table kontrolia.devices enable row level security;
+alter table kontrolia.audit_logs enable row level security;
+
+-- organizations
+create policy "members can view their organizations" on kontrolia.organizations
+  for select using (kontrolia.is_org_member(id));
+create policy "authenticated users can create organizations" on kontrolia.organizations
+  for insert to authenticated with check (true);
+create policy "org admins can update their organization" on kontrolia.organizations
+  for update using (kontrolia.is_org_admin(id));
+
+-- applications / catalog: platform-level, managed via service_role from the
+-- auth-server admin API (which enforces its own platform-admin check).
+create policy "anyone can view applications enabled for their org" on kontrolia.applications
+  for select using (
+    exists (
+      select 1 from kontrolia.application_organizations ao
+      where ao.application_id = id and kontrolia.is_org_member(ao.organization_id)
+    )
+  );
+create policy "org members can view enabled applications" on kontrolia.application_organizations
+  for select using (kontrolia.is_org_member(organization_id));
+create policy "org members can view permissions of their enabled apps" on kontrolia.permissions
+  for select using (
+    exists (
+      select 1 from kontrolia.application_organizations ao
+      where ao.application_id = permissions.application_id and kontrolia.is_org_member(ao.organization_id)
+    )
+  );
+
+-- roles
+create policy "org members can view roles" on kontrolia.roles
+  for select using (organization_id is null or kontrolia.is_org_member(organization_id));
+create policy "org admins can manage custom roles" on kontrolia.roles
+  for insert to authenticated with check (organization_id is not null and kontrolia.is_org_admin(organization_id));
+create policy "org admins can update custom roles" on kontrolia.roles
+  for update using (organization_id is not null and kontrolia.is_org_admin(organization_id));
+create policy "org admins can delete custom roles" on kontrolia.roles
+  for delete using (organization_id is not null and kontrolia.is_org_admin(organization_id));
+
+create policy "org members can view role permissions" on kontrolia.role_permissions
+  for select using (
+    exists (
+      select 1 from kontrolia.roles r
+      where r.id = role_id and (r.organization_id is null or kontrolia.is_org_member(r.organization_id))
+    )
+  );
+create policy "org admins manage role permissions" on kontrolia.role_permissions
+  for all using (
+    exists (select 1 from kontrolia.roles r where r.id = role_id and r.organization_id is not null and kontrolia.is_org_admin(r.organization_id))
+  );
+
+-- memberships
+create policy "members can view memberships in their orgs" on kontrolia.memberships
+  for select using (user_id = auth.uid() or kontrolia.is_org_member(organization_id));
+create policy "org admins manage memberships" on kontrolia.memberships
+  for insert to authenticated with check (kontrolia.is_org_admin(organization_id));
+create policy "org admins update memberships" on kontrolia.memberships
+  for update using (kontrolia.is_org_admin(organization_id));
+create policy "org admins remove memberships" on kontrolia.memberships
+  for delete using (kontrolia.is_org_admin(organization_id));
+
+create policy "org members can view membership roles" on kontrolia.membership_roles
+  for select using (
+    exists (select 1 from kontrolia.memberships m where m.id = membership_id and (m.user_id = auth.uid() or kontrolia.is_org_member(m.organization_id)))
+  );
+create policy "org admins manage membership roles" on kontrolia.membership_roles
+  for all using (
+    exists (select 1 from kontrolia.memberships m where m.id = membership_id and kontrolia.is_org_admin(m.organization_id))
+  );
+
+create policy "org admins manage user permission overrides" on kontrolia.user_permissions
+  for all using (
+    exists (select 1 from kontrolia.memberships m where m.id = membership_id and kontrolia.is_org_admin(m.organization_id))
+  );
+
+-- invitations — org admins only; invited-user acceptance flow goes through
+-- the auth-server API (service role), not direct table access.
+create policy "org admins manage invitations" on kontrolia.invitations
+  for all using (kontrolia.is_org_admin(organization_id));
+
+-- sessions_context — a user only ever sees/updates their own active org
+create policy "users manage their own session context" on kontrolia.sessions_context
+  for all using (user_id = auth.uid()) with check (user_id = auth.uid());
+
+-- devices
+create policy "users manage their own devices" on kontrolia.devices
+  for all using (user_id = auth.uid()) with check (user_id = auth.uid());
+
+-- audit_logs — read-only for org admins, writes come from service_role only
+create policy "org admins can view audit logs" on kontrolia.audit_logs
+  for select using (organization_id is not null and kontrolia.is_org_admin(organization_id));

package/migrations/0011_org_owner_bootstrap_trigger.sql

@@ -0,0 +1,32 @@
+-- Bootstraps the chicken-and-egg problem of RLS-gated membership writes:
+-- creating an organization has no admin membership yet to satisfy
+-- kontrolia.is_org_admin(). Instead, the creator is auto-enrolled as Owner
+-- via trigger, in the same transaction as the insert.
+
+create or replace function kontrolia.handle_new_organization()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  owner_role_id uuid;
+  new_membership_id uuid;
+begin
+  select id into owner_role_id from kontrolia.roles where slug = 'owner' and organization_id is null;
+
+  insert into kontrolia.memberships (user_id, organization_id, status)
+  values (auth.uid(), new.id, 'active')
+  returning id into new_membership_id;
+
+  insert into kontrolia.membership_roles (membership_id, role_id)
+  values (new_membership_id, owner_role_id);
+
+  return new;
+end;
+$$;
+
+create trigger on_organization_created
+  after insert on kontrolia.organizations
+  for each row
+  execute function kontrolia.handle_new_organization();

package/migrations/0012_devices_and_session_revoke.sql

@@ -0,0 +1,37 @@
+-- One device row per session, upserted on each login/touch.
+alter table kontrolia.devices add constraint devices_session_id_key unique (session_id);
+
+-- Revokes one specific Supabase session (device) for the calling user.
+--
+-- There is no supabase-js admin method to revoke an arbitrary session by
+-- session_id — signOut() only affects the caller's own current/other
+-- sessions. The documented approach is to correlate the JWT's session_id
+-- claim with auth.sessions.id and delete that row directly: access tokens
+-- already issued stay valid until they expire (short-lived, see
+-- GOTRUE_JWT_EXP / config.toml's auth.jwt_expiry), but the session can no
+-- longer be refreshed once its auth.sessions row is gone.
+--
+-- SECURITY DEFINER is what makes touching auth.sessions from an
+-- `authenticated`-role caller possible at all; ownership is checked
+-- explicitly inside the function since RLS doesn't apply here.
+create or replace function kontrolia.revoke_session(target_session_id uuid)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  if not exists (
+    select 1 from kontrolia.devices
+    where session_id = target_session_id and user_id = auth.uid()
+  ) then
+    raise exception 'not authorized to revoke this session';
+  end if;
+
+  delete from auth.sessions where id = target_session_id;
+  delete from kontrolia.devices where session_id = target_session_id;
+end;
+$$;
+
+grant execute on function kontrolia.revoke_session(uuid) to authenticated;
+revoke execute on function kontrolia.revoke_session(uuid) from anon, public;

package/migrations/0013_audit_log_triggers.sql

@@ -0,0 +1,133 @@
+-- Trigger-based audit logging: writes happen inside the database, not
+-- because application code remembered to also call an "insertAuditLog()"
+-- helper. That's the entire point of an audit trail — it has to keep
+-- recording even when a future API route forgets to, or a change comes
+-- from Studio/psql directly.
+--
+-- actor_user_id is auth.uid() where available. Some of these writes go
+-- through service-role code paths (e.g. invitation acceptance, which needs
+-- to run before the visitor even has an org membership) where auth.uid()
+-- isn't meaningful — those fall back to the affected row's own user_id, or
+-- are left null when there truly isn't one to infer.
+
+create or replace function kontrolia.log_organization_created()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+  values (new.id, auth.uid(), 'organization.created', 'organization', new.id::text, jsonb_build_object('name', new.name, 'slug', new.slug));
+  return new;
+end;
+$$;
+
+create trigger audit_organization_created
+  after insert on kontrolia.organizations
+  for each row execute function kontrolia.log_organization_created();
+
+create or replace function kontrolia.log_membership_change()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  if tg_op = 'INSERT' then
+    insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+    values (new.organization_id, coalesce(auth.uid(), new.user_id), 'membership.created', 'membership', new.id::text, jsonb_build_object('user_id', new.user_id, 'status', new.status));
+    return new;
+  else
+    insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+    values (old.organization_id, auth.uid(), 'membership.removed', 'membership', old.id::text, jsonb_build_object('user_id', old.user_id));
+    return old;
+  end if;
+end;
+$$;
+
+create trigger audit_membership_change
+  after insert or delete on kontrolia.memberships
+  for each row execute function kontrolia.log_membership_change();
+
+create or replace function kontrolia.log_invitation_created()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+  values (new.organization_id, auth.uid(), 'invitation.created', 'invitation', new.id::text, jsonb_build_object('email', new.email));
+  return new;
+end;
+$$;
+
+create trigger audit_invitation_created
+  after insert on kontrolia.invitations
+  for each row execute function kontrolia.log_invitation_created();
+
+create or replace function kontrolia.log_invitation_accepted()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  if old.accepted_at is null and new.accepted_at is not null then
+    insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+    values (new.organization_id, auth.uid(), 'invitation.accepted', 'invitation', new.id::text, jsonb_build_object('email', new.email));
+  end if;
+  return new;
+end;
+$$;
+
+create trigger audit_invitation_accepted
+  after update on kontrolia.invitations
+  for each row execute function kontrolia.log_invitation_accepted();
+
+create or replace function kontrolia.log_role_assignment_change()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  target_membership record;
+begin
+  select organization_id, user_id into target_membership
+  from kontrolia.memberships
+  where id = coalesce(new.membership_id, old.membership_id);
+
+  if tg_op = 'INSERT' then
+    insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+    values (target_membership.organization_id, coalesce(auth.uid(), target_membership.user_id), 'role.assigned', 'membership_role', new.membership_id::text, jsonb_build_object('role_id', new.role_id));
+    return new;
+  else
+    insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+    values (target_membership.organization_id, auth.uid(), 'role.unassigned', 'membership_role', old.membership_id::text, jsonb_build_object('role_id', old.role_id));
+    return old;
+  end if;
+end;
+$$;
+
+create trigger audit_role_assignment_change
+  after insert or delete on kontrolia.membership_roles
+  for each row execute function kontrolia.log_role_assignment_change();
+
+create or replace function kontrolia.log_device_revoked()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  insert into kontrolia.audit_logs (organization_id, actor_user_id, action, target_type, target_id, metadata)
+  values (null, coalesce(auth.uid(), old.user_id), 'device.revoked', 'device', old.session_id::text, jsonb_build_object('label', old.label));
+  return old;
+end;
+$$;
+
+create trigger audit_device_revoked
+  after delete on kontrolia.devices
+  for each row execute function kontrolia.log_device_revoked();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kontrolia/db",
+  "version": "1.0.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": [
+    "kontrolia",
+    "auth",
+    "postgres",
+    "supabase",
+    "migrations",
+    "rbac"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rauldolores/auth.git",
+    "directory": "packages/db"
+  },
+  "homepage": "https://github.com/rauldolores/auth#readme",
+  "bugs": "https://github.com/rauldolores/auth/issues",
+  "author": "KontrolIA",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "kontrolia-db-migrate": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "dependencies": {
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10",
+    "eslint": "^9.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "@kontrolia/config": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "migrate": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rimraf dist"
+  }
+}