@kontrolia/db 1.0.1 → 1.2.0

package/dist/api-key.d.ts

@@ -0,0 +1,5 @@
+/** Generates a new plaintext application sync API key. Shown once, never stored. */
+export declare function generateApplicationApiKey(): string;
+/** sha256 hex digest — what actually gets stored in kontrolia.applications.api_key_hash. */
+export declare function hashApplicationApiKey(plaintext: string): string;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAIA,oFAAoF;AACpF,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/api-key.js

@@ -0,0 +1,10 @@
+import { createHash, randomBytes } from "node:crypto";
+const API_KEY_PREFIX = "kapp_";
+/** Generates a new plaintext application sync API key. Shown once, never stored. */
+export function generateApplicationApiKey() {
+    return `${API_KEY_PREFIX}${randomBytes(24).toString("base64url")}`;
+}
+/** sha256 hex digest — what actually gets stored in kontrolia.applications.api_key_hash. */
+export function hashApplicationApiKey(plaintext) {
+    return createHash("sha256").update(plaintext).digest("hex");
+}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AACnC,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { migrate } from "./migrate.js";
 export { registerApplication, } from "./register-application.js";
+export { generateApplicationApiKey, hashApplicationApiKey } from "./api-key.js";

package/dist/register-application.d.ts

@@ -14,15 +14,23 @@ 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
  * 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.
+ * 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.
  */
 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":"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"}
+{"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"}

package/dist/register-application.js

@@ -1,21 +1,23 @@
 import { Client } from "pg";
+import { generateApplicationApiKey, hashApplicationApiKey } from "./api-key.js";
 /**
  * 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.
+ * 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.
  */
 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)
+        const candidateApiKey = generateApplicationApiKey();
+        const { rows: [application], } = await client.query(`insert into kontrolia.applications (name, slug, environment, api_key_hash)
+       values ($1, $2, $3, $4)
        on conflict (slug) do update set name = excluded.name, environment = excluded.environment
-       returning id`, [options.name, options.slug, options.environment]);
+       returning id, (xmax = 0) as inserted`, [options.name, options.slug, options.environment, hashApplicationApiKey(candidateApiKey)]);
         if (!application)
             throw new Error(`Failed to upsert application "${options.slug}"`);
         const permissionKeys = [];
@@ -26,7 +28,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 };
+        return { applicationId: application.id, permissionKeys, apiKey: application.inserted ? candidateApiKey : null };
     }
     finally {
         await client.end();

package/migrations/0015_application_api_key.sql

@@ -0,0 +1,11 @@
+-- Lets an already-registered application authenticate its own catalog-sync
+-- calls (POST /api/applications/sync on auth-server) without needing direct
+-- database access — the same "declare your own permissions" pattern Auth0's
+-- Resource Servers / Stripe's API keys use. Only a hash is ever stored; the
+-- plaintext key is generated once, shown to the operator, and never
+-- persisted anywhere.
+
+alter table kontrolia.applications add column api_key_hash text;
+
+comment on column kontrolia.applications.api_key_hash is
+  'sha256 hex digest of the application''s sync API key. Null for applications registered before this column existed, or that opted out — those can only be updated by re-running the CLI/registerApplication() directly against the database.';

package/migrations/0016_platform_admins.sql

@@ -0,0 +1,117 @@
+-- A "platform admin" needs to see across every organization (support/ops
+-- consoles, cross-tenant monitoring) — something the rest of the model
+-- deliberately can't do, since roles/permissions are always scoped to one
+-- active organization at a time (see custom_access_token_hook). Rather than
+-- have every app invent its own "<app>.admin.ver_todo" escape hatch, this
+-- is one reserved claim outside the app-permission-key namespace, backed by
+-- its own table so it's a single source of truth across the whole install.
+--
+-- No self-service UI/API for granting this on purpose — same "manual step
+-- for now" pattern as application_organizations enablement. Grant with:
+--   insert into kontrolia.platform_admins (user_id) values ('<user-uuid>');
+
+create table kontrolia.platform_admins (
+  user_id uuid primary key references auth.users (id) on delete cascade,
+  granted_by uuid references auth.users (id) on delete set null,
+  granted_at timestamptz not null default now()
+);
+
+comment on table kontrolia.platform_admins is 'Users who can see across every organization — a single reserved claim (is_platform_admin), not an app-defined permission. Granted by inserting directly, no UI yet.';
+
+alter table kontrolia.platform_admins enable row level security;
+
+-- Only platform admins can even see who else is one — nobody self-grants
+-- via RLS (writes require direct database access, same as this table's own
+-- comment says).
+create policy "platform admins can view the platform admin list" on kontrolia.platform_admins
+  for select using (exists (select 1 from kontrolia.platform_admins pa where pa.user_id = auth.uid()));
+
+grant select on kontrolia.platform_admins to authenticated;
+
+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[];
+  platform_admin boolean;
+begin
+  claims := coalesce(event->'claims', '{}'::jsonb);
+  target_user_id := (event->>'user_id')::uuid;
+
+  select exists(select 1 from kontrolia.platform_admins where user_id = target_user_id) into platform_admin;
+
+  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, '{}')));
+  claims := jsonb_set(claims, '{is_platform_admin}', to_jsonb(coalesce(platform_admin, false)));
+
+  event := jsonb_set(event, '{claims}', claims);
+  return event;
+end;
+$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontrolia/db",
-  "version": "1.0.1",
+  "version": "1.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": [