Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(control-api): add Grok subscription grant tables

Jose Gabriel Ramirez Encinas48e2e3bf9316
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 4d871b0c3..7744eb931 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.555",
+ "version": "0.1.556",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.555",
+ "version": "0.1.556",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 2dcf0f57a..c27919fdd 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.555",
+ "version": "0.1.556",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/db.ts b/control-api/src/db.ts
index d2c282feb..f9e391fd9 100644
--- a/control-api/src/db.ts
+++ b/control-api/src/db.ts
@@ -19,6 +19,12 @@ import {
applyGfsUploadFinalizingSchema,
applyGfsUploadSessionSchema,
} from './services/gfsUploadSchema.js'
+import {
+ applyGrokCatalogModelsSchema,
+ applyGrokSubscriptionConnectionSchema,
+ applyGrokSubscriptionOAuthStateSchema,
+ applyLlmProviderAttemptsGrokBrokerSchema,
+} from './services/grokSubscriptionSchema.js'
import {
applyLlmProviderAttemptConnectionIdSchema,
applyLlmProviderAttemptSchema,
@@ -6014,6 +6020,22 @@ export const CONTROL_API_MIGRATIONS: DbMigration[] = [
version: '0108_llm_provider_attempts_sdk_link_on_delete_set_null',
apply: applyLlmProviderAttemptSdkLinkOnDeleteSetNullSchema,
},
+ {
+ version: '0109_grok_subscription_connections',
+ apply: applyGrokSubscriptionConnectionSchema,
+ },
+ {
+ version: '0110_grok_subscription_oauth_states',
+ apply: applyGrokSubscriptionOAuthStateSchema,
+ },
+ {
+ version: '0111_grok_catalog_models',
+ apply: applyGrokCatalogModelsSchema,
+ },
+ {
+ version: '0112_llm_provider_attempts_grok_broker',
+ apply: applyLlmProviderAttemptsGrokBrokerSchema,
+ },
]
async function consolidateWorkflowAllowedUsersToTriggers(db: DbClient): Promise<void> {
diff --git a/control-api/src/services/grokSubscriptionSchema.ts b/control-api/src/services/grokSubscriptionSchema.ts
new file mode 100644
index 000000000..8188790e5
--- /dev/null
+++ b/control-api/src/services/grokSubscriptionSchema.ts
@@ -0,0 +1,185 @@
+import { randomBytes } from 'node:crypto'
+import type { DbClient } from '../db.js'
+
+const CONNECTION_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
+export function generateGrokConnectionKey(): string {
+ return `grok-${randomBytes(8).toString('hex')}`
+}
+
+export function assertGrokConnectionKey(value: string): string {
+ const key = value.trim()
+ if (!CONNECTION_KEY_RE.test(key) || key === 'unassigned' || key === 'deployment-default') {
+ throw new Error(`invalid Grok connection key: ${key}`)
+ }
+ return key
+}
+
+export async function applyGrokSubscriptionConnectionSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS grok_subscription_connections (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ connection_key TEXT NOT NULL,
+ display_name TEXT,
+ created_by TEXT,
+ default_model TEXT,
+ status TEXT NOT NULL CHECK (status IN (
+ 'disconnected', 'connecting', 'connected', 'reauth_required', 'revoked'
+ )),
+ refresh_token_encrypted TEXT,
+ access_token_encrypted TEXT,
+ access_token_expires_at TIMESTAMPTZ,
+ credential_revision BIGINT NOT NULL DEFAULT 1
+ CHECK (credential_revision >= 1),
+ catalog_revision BIGINT NOT NULL DEFAULT 0
+ CHECK (catalog_revision >= 0),
+ account_fingerprint TEXT,
+ catalog_status TEXT NOT NULL DEFAULT 'never_synced'
+ CHECK (catalog_status IN ('never_synced', 'ready', 'auth-rejected', 'unavailable')),
+ catalog_synced_at TIMESTAMPTZ,
+ last_refresh_at TIMESTAMPTZ,
+ last_auth_at TIMESTAMPTZ,
+ refresh_lock_token TEXT,
+ refresh_lock_expires_at TIMESTAMPTZ,
+ revoked_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ CONSTRAINT grok_subscription_connections_key_reserved_check
+ CHECK (connection_key <> 'unassigned' AND connection_key <> 'deployment-default'),
+ CONSTRAINT grok_subscription_connections_ciphertext_when_connected
+ CHECK (
+ status NOT IN ('connected', 'reauth_required')
+ OR (
+ refresh_token_encrypted IS NOT NULL
+ AND account_fingerprint IS NOT NULL
+ )
+ )
+ );
+
+ CREATE UNIQUE INDEX IF NOT EXISTS grok_subscription_connections_active_key
+ ON grok_subscription_connections (connection_key)
+ WHERE revoked_at IS NULL;
+
+ CREATE UNIQUE INDEX IF NOT EXISTS grok_subscription_connections_active_fingerprint
+ ON grok_subscription_connections (account_fingerprint)
+ WHERE revoked_at IS NULL AND account_fingerprint IS NOT NULL;
+
+ REVOKE ALL PRIVILEGES ON TABLE grok_subscription_connections FROM PUBLIC;
+ REVOKE ALL PRIVILEGES ON TABLE grok_subscription_connections
+ FROM trace_maintenance_runtime, workflow_recipes_runtime;
+ GRANT SELECT, INSERT, UPDATE ON TABLE grok_subscription_connections TO control_api_runtime;
+ REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE grok_subscription_connections FROM control_api_runtime;
+ `)
+}
+
+export async function applyGrokSubscriptionOAuthStateSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS grok_subscription_oauth_states (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ state TEXT NOT NULL,
+ connection_key TEXT NOT NULL,
+ flow TEXT NOT NULL CHECK (flow IN ('device')),
+ intent TEXT NOT NULL CHECK (intent IN ('connect', 'reconnect', 'replace')),
+ device_code_encrypted TEXT NOT NULL,
+ status TEXT NOT NULL CHECK (status IN ('pending', 'consumed', 'expired', 'cancelled')),
+ expires_at TIMESTAMPTZ NOT NULL,
+ consumed_at TIMESTAMPTZ,
+ cancelled_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ CONSTRAINT grok_subscription_oauth_states_state_unique UNIQUE (state),
+ CONSTRAINT grok_subscription_oauth_states_lifecycle CHECK (
+ (status = 'pending' AND consumed_at IS NULL AND cancelled_at IS NULL)
+ OR (status = 'consumed' AND consumed_at IS NOT NULL AND cancelled_at IS NULL)
+ OR (status = 'cancelled' AND cancelled_at IS NOT NULL AND consumed_at IS NULL)
+ OR (status = 'expired' AND consumed_at IS NULL)
+ )
+ );
+
+ CREATE INDEX IF NOT EXISTS grok_subscription_oauth_states_pending_expiry_idx
+ ON grok_subscription_oauth_states (expires_at)
+ WHERE status = 'pending';
+
+ REVOKE ALL PRIVILEGES ON TABLE grok_subscription_oauth_states FROM PUBLIC;
+ REVOKE ALL PRIVILEGES ON TABLE grok_subscription_oauth_states
+ FROM trace_maintenance_runtime, workflow_recipes_runtime;
+ GRANT SELECT, INSERT, UPDATE ON TABLE grok_subscription_oauth_states TO control_api_runtime;
+ REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE grok_subscription_oauth_states FROM control_api_runtime;
+ `)
+}
+
+export async function applyGrokCatalogModelsSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS grok_catalog_models (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ connection_id UUID NOT NULL REFERENCES grok_subscription_connections(id),
+ model TEXT NOT NULL,
+ display_name TEXT,
+ context_window_tokens INTEGER,
+ enabled BOOLEAN NOT NULL DEFAULT false,
+ source TEXT NOT NULL CHECK (source IN ('manual', 'discovery')),
+ stale BOOLEAN NOT NULL DEFAULT false,
+ discovered_at TIMESTAMPTZ,
+ last_seen_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ CONSTRAINT grok_catalog_models_connection_model_unique UNIQUE (connection_id, model)
+ );
+
+ REVOKE ALL PRIVILEGES ON TABLE grok_catalog_models FROM PUBLIC;
+ REVOKE ALL PRIVILEGES ON TABLE grok_catalog_models
+ FROM trace_maintenance_runtime, workflow_recipes_runtime;
+ GRANT SELECT, INSERT, UPDATE ON TABLE grok_catalog_models TO control_api_runtime;
+ REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE grok_catalog_models FROM control_api_runtime;
+ `)
+}
+
+export async function applyLlmProviderAttemptsGrokBrokerSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ DO $$
+ DECLARE
+ constraint_name text;
+ BEGIN
+ SELECT c.conname INTO constraint_name
+ FROM pg_constraint c
+ JOIN pg_class t ON t.oid = c.conrelid
+ JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY (c.conkey)
+ WHERE t.relname = 'llm_provider_attempts'
+ AND c.contype = 'c'
+ AND a.attname = 'provider'
+ AND pg_get_constraintdef(c.oid) LIKE '%codex-subscription%'
+ AND pg_get_constraintdef(c.oid) NOT LIKE '%grok-subscription%'
+ LIMIT 1;
+ IF constraint_name IS NOT NULL THEN
+ EXECUTE format('ALTER TABLE llm_provider_attempts DROP CONSTRAINT %I', constraint_name);
+ END IF;
+ END $$;
+
+ ALTER TABLE llm_provider_attempts
+ DROP CONSTRAINT IF EXISTS llm_provider_attempts_provider_check;
+
+ ALTER TABLE llm_provider_attempts
+ ADD CONSTRAINT llm_provider_attempts_provider_check
+ CHECK (provider IN ('codex-subscription', 'grok-subscription'));
+
+ ALTER TABLE llm_provider_attempts
+ ADD CONSTRAINT llm_provider_attempts_grok_connection_id_required
+ CHECK (provider <> 'grok-subscription' OR connection_id IS NOT NULL);
+
+ DO $$
+ DECLARE
+ fk_name text;
+ BEGIN
+ SELECT c.conname INTO fk_name
+ FROM pg_constraint c
+ JOIN pg_class t ON t.oid = c.conrelid
+ JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY (c.conkey)
+ WHERE t.relname = 'llm_provider_attempts'
+ AND c.contype = 'f'
+ AND a.attname = 'connection_id'
+ LIMIT 1;
+ IF fk_name IS NOT NULL THEN
+ EXECUTE format('ALTER TABLE llm_provider_attempts DROP CONSTRAINT %I', fk_name);
+ END IF;
+ END $$;
+ `)
+}
diff --git a/control-api/test/db.grokSubscriptionMigration.test.ts b/control-api/test/db.grokSubscriptionMigration.test.ts
new file mode 100644
index 000000000..34b06a153
--- /dev/null
+++ b/control-api/test/db.grokSubscriptionMigration.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+function runtimeAccessProfile(): Map<string, string> {
+ const source = readFileSync(
+ new URL('../../deploy/scripts/control-api-runtime-access-profiles.tsv', import.meta.url),
+ 'utf8'
+ )
+ return new Map(
+ source
+ .split('\n')
+ .filter(line => line && !line.startsWith('#'))
+ .map(line => line.split('\t') as [string, string])
+ )
+}
+
+describe('0109-0112 Grok subscription persistence', () => {
+ const dbSource = readFileSync(new URL('../src/db.ts', import.meta.url), 'utf8')
+ const schemaSource = readFileSync(
+ new URL('../src/services/grokSubscriptionSchema.ts', import.meta.url),
+ 'utf8'
+ )
+
+ it('registers Grok migrations after the last published attempt-store version', () => {
+ expect(dbSource).toContain("version: '0108_llm_provider_attempts_sdk_link_on_delete_set_null'")
+ expect(dbSource).toContain("version: '0109_grok_subscription_connections'")
+ expect(dbSource).toContain("version: '0110_grok_subscription_oauth_states'")
+ expect(dbSource).toContain("version: '0111_grok_catalog_models'")
+ expect(dbSource).toContain("version: '0112_llm_provider_attempts_grok_broker'")
+ expect(
+ dbSource.indexOf("version: '0108_llm_provider_attempts_sdk_link_on_delete_set_null'")
+ ).toBeLessThan(dbSource.indexOf("version: '0109_grok_subscription_connections'"))
+ expect(dbSource.indexOf("version: '0109_grok_subscription_connections'")).toBeLessThan(
+ dbSource.indexOf("version: '0110_grok_subscription_oauth_states'")
+ )
+ expect(dbSource.indexOf("version: '0111_grok_catalog_models'")).toBeLessThan(
+ dbSource.indexOf("version: '0112_llm_provider_attempts_grok_broker'")
+ )
+ })
+
+ it('creates Grok grant tables without Codex reserved keys or ChatGPT columns', () => {
+ expect(schemaSource).toContain('CREATE TABLE IF NOT EXISTS grok_subscription_connections')
+ expect(schemaSource).toContain('CREATE TABLE IF NOT EXISTS grok_subscription_oauth_states')
+ expect(schemaSource).toContain('CREATE TABLE IF NOT EXISTS grok_catalog_models')
+ expect(schemaSource).toContain("CHECK (flow IN ('device'))")
+ expect(schemaSource).toContain(
+ "connection_key <> 'unassigned' AND connection_key <> 'deployment-default'"
+ )
+ expect(schemaSource).not.toContain('chatgpt_account_id')
+ expect(schemaSource).toContain("attname = 'provider'")
+ expect(schemaSource).toContain(
+ "CHECK (provider IN ('codex-subscription', 'grok-subscription'))"
+ )
+ expect(schemaSource).toContain(
+ "CHECK (provider <> 'grok-subscription' OR connection_id IS NOT NULL)"
+ )
+ expect(schemaSource).toContain("attname = 'connection_id'")
+ expect(schemaSource).toContain(
+ 'GRANT SELECT, INSERT, UPDATE ON TABLE grok_subscription_connections'
+ )
+ })
+
+ it('registers Grok tables in the runtime access TSV as upsert', () => {
+ const profiles = runtimeAccessProfile()
+ expect(profiles.get('grok_subscription_connections')).toBe('upsert')
+ expect(profiles.get('grok_subscription_oauth_states')).toBe('upsert')
+ expect(profiles.get('grok_catalog_models')).toBe('upsert')
+ })
+})
diff --git a/deploy/scripts/control-api-runtime-access-profiles.tsv b/deploy/scripts/control-api-runtime-access-profiles.tsv
index 07c4f9c27..6cbb1641b 100644
--- a/deploy/scripts/control-api-runtime-access-profiles.tsv
+++ b/deploy/scripts/control-api-runtime-access-profiles.tsv
@@ -5,6 +5,9 @@ budget_pending_reservations legacy_dml
codex_subscription_connections upsert
codex_subscription_oauth_states upsert
codex_catalog_models upsert
+grok_subscription_connections upsert
+grok_subscription_oauth_states upsert
+grok_catalog_models upsert
control_admin_deletion_audit legacy_dml
control_admin_email_change_requests legacy_dml
control_admin_invitations legacy_dml