@kontrolia/db 1.0.1 → 1.1.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/package.json

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