@agentic-kit/db-tools 0.2.0

package/esm/tools/add-policies.js

@@ -0,0 +1,94 @@
+import { buildNodeData, getPolicyFieldDefaults, getPolicyProvisioningConfig } from '@agentic-kit/harness';
+import { z } from 'zod';
+import { resolveProjectContext } from '../context';
+import { addPoliciesToExistingTable } from '../policy/add-policies-to-table';
+import { resolveSchema, resolveTable } from '../schema-resolve';
+const DEFAULT_ROLE = 'authenticated';
+const CrudOperationSchema = z.enum(['create', 'read', 'update', 'delete']);
+const PolicyEntrySchema = z.object({
+    policy_type: z
+        .string()
+        .describe('Policy type id. Supported: AuthzAllowAll, AuthzDenyAll, AuthzAppMembership, AuthzDirectOwner, AuthzEntityMembership, AuthzOrgHierarchy, AuthzPublishable (these auto-create columns via their Data* node), AuthzRelatedMemberList, AuthzRelatedEntityMembership. Not supported (use the policies UI): AuthzDirectOwnerAny, AuthzMemberList, AuthzTemporal, AuthzComposite.'),
+    operations: z
+        .array(CrudOperationSchema)
+        .min(1)
+        .describe('CRUD operations the policy applies to: any subset of ["create","read","update","delete"].'),
+    role_name: z
+        .string()
+        .describe('PostgreSQL role the policy applies to. Defaults to "authenticated".')
+        .optional(),
+    is_permissive: z
+        .boolean()
+        .describe('PERMISSIVE (default true) vs RESTRICTIVE — most policies should be permissive.')
+        .optional(),
+    data: z
+        .record(z.string(), z.unknown())
+        .describe('Type-specific shared data. AuthzDirectOwner: { entity_field: "owner_id" }. AuthzAppMembership: { permission?, is_admin?, is_owner? }. Empty object {} for AuthzAllowAll / AuthzDenyAll.')
+        .optional(),
+    node_data: z
+        .record(z.string(), z.unknown())
+        .describe('Optional data for the underlying Data* node (has-module policies only).')
+        .optional(),
+});
+const AddPoliciesZod = z.object({
+    table_name: z
+        .string()
+        .describe('Name of the existing table to attach the policies to. Use describe_schema first to verify it exists.'),
+    policies: z
+        .array(PolicyEntrySchema)
+        .min(1)
+        .describe('One or more policies to add. Each entry becomes one secure_table_provision call.'),
+});
+function buildOperations(roleName, isPermissive) {
+    const config = { roleName, isPermissive, policyData: {}, isCustomized: false };
+    return { create: config, read: config, update: config, delete: config };
+}
+export const addPoliciesTool = {
+    name: 'add_policies',
+    label: 'Add policies',
+    description: 'Add one or more RLS policies to an existing table. Has-module policies (AuthzDirectOwner, AuthzEntityMembership, AuthzOrgHierarchy, AuthzPublishable) auto-create the columns they need — call directly, do not add columns first.',
+    promptSnippet: 'add_policies: attach RLS policies to an existing table (one call can add many). Gated.',
+    parameters: AddPoliciesZod,
+    async execute(params, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context) {
+            return {
+                content: [{ type: 'text', text: resolved.reason }],
+                details: { success: false, message: resolved.reason },
+            };
+        }
+        const { modules, databaseId, schemaId } = resolved.context;
+        try {
+            const schema = await resolveSchema(resolved.context);
+            const table = resolveTable(schema, params.table_name);
+            const policies = params.policies.map((entry) => {
+                const config = getPolicyProvisioningConfig(entry.policy_type);
+                const defaults = getPolicyFieldDefaults(entry.policy_type);
+                const mergedData = { ...defaults, ...(entry.data ?? {}) };
+                const nodeData = entry.node_data ?? buildNodeData(entry.policy_type, mergedData);
+                return {
+                    policyType: entry.policy_type,
+                    dataNodeType: config?.dataNodeType,
+                    nodeData,
+                    sharedPolicyData: mergedData,
+                    operations: buildOperations(entry.role_name ?? DEFAULT_ROLE, entry.is_permissive ?? true),
+                    enabledOperations: entry.operations,
+                };
+            });
+            await addPoliciesToExistingTable({
+                client: modules,
+                databaseId,
+                schemaId,
+                tableId: table.id,
+                policies,
+            });
+            const count = params.policies.length;
+            const message = `Added ${count} ${count === 1 ? 'policy' : 'policies'} to ${params.table_name}`;
+            return { content: [{ type: 'text', text: message }], details: { success: true, message } };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to add policies';
+            return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+        }
+    },
+};

package/esm/tools/add-records.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+export type AddRecordsDetails = {
+    success: boolean;
+    message: string;
+    tableName?: string;
+    columns?: string[];
+    rows?: Record<string, unknown>[];
+    createdCount?: number;
+    asOf?: string;
+    needsAuth?: boolean;
+};
+declare const AddRecordsZod: z.ZodObject<{
+    table_name: z.ZodString;
+    records: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const addRecordsTool: HarnessTool<typeof AddRecordsZod, AddRecordsDetails>;
+export {};

package/esm/tools/add-records.js

@@ -0,0 +1,122 @@
+import { buildPostGraphileCreate, toCamelCaseSingular, toCreateMutationName, } from '@constructive-io/graphql-query/generators';
+import { objects } from '@constructive-io/sdk';
+import { z } from 'zod';
+import { resolveDataToken, resolveProjectContext } from '../context';
+import { cleanTable, findMetaTable, META_QUERY } from '../records/meta';
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+function needsAuth(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message, needsAuth: true },
+    };
+}
+// Mirror @constructive-io/data's prepareCreateInput (create semantics): drop
+// undefined/null/empty-string so server defaults apply; keep false/0/[]/objects.
+function stripForCreate(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+const AddRecordsZod = z.object({
+    table_name: z
+        .string()
+        .describe('Name of the table to insert rows into (snake_case, singular or plural).'),
+    records: z
+        .array(z.record(z.string(), z.unknown()))
+        .describe('Rows to insert. Each is an object of column → value (camelCase or snake_case column names).'),
+});
+export const addRecordsTool = {
+    name: 'add_records',
+    label: 'Add records',
+    description: "Insert one or more rows into a table in the project's app database.",
+    promptSnippet: 'add_records: insert rows into an existing table. Gated.',
+    parameters: AddRecordsZod,
+    async execute(params, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { dataEndpoint } = resolved.context;
+        if (!dataEndpoint) {
+            return fail('Cannot resolve the app data endpoint (DATABASE_NAME missing from .env). Re-provision the database, then retry.');
+        }
+        if (params.records.length === 0)
+            return fail('No records provided.');
+        const token = await resolveDataToken(resolved.context);
+        if (!token.token)
+            return needsAuth(token.reason ?? 'Sign in to the database to insert records.');
+        const adapter = new objects.FetchAdapter(dataEndpoint, {
+            Authorization: `Bearer ${token.token}`,
+        });
+        let tables;
+        try {
+            const meta = await adapter.execute(META_QUERY);
+            if (!meta.ok) {
+                return fail(`Failed to read schema from the app database: ${meta.errors.map((e) => e.message).join('; ')}`);
+            }
+            tables = (meta.data._meta?.tables ?? []).filter((t) => Boolean(t));
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to query the app database schema.');
+        }
+        const rawTable = findMetaTable(tables, params.table_name);
+        if (!rawTable) {
+            return fail(`Table "${params.table_name}" was not found in the app database.`);
+        }
+        const table = cleanTable(rawTable);
+        const allTables = tables.map(cleanTable);
+        const mutation = buildPostGraphileCreate(table, allTables).toString();
+        const mutationName = toCreateMutationName(table.name, table);
+        const singularName = toCamelCaseSingular(table.name, table);
+        // Constructive app tables scope rows by entityId (the owning user's id). The
+        // create input requires it, but callers won't know it — backfill it with the
+        // signed-in user's id from the Preview session when the table has the column
+        // and the record omits it.
+        const hasEntityId = table.fields.some((f) => f.name === 'entityId');
+        const created = [];
+        const errors = [];
+        for (const record of params.records) {
+            const prepared = hasEntityId && token.userId && record.entityId == null && record.entity_id == null
+                ? { ...record, entityId: token.userId }
+                : record;
+            const variables = { input: { [singularName]: stripForCreate(prepared) } };
+            try {
+                const result = await adapter.execute(mutation, variables);
+                if (!result.ok) {
+                    errors.push(result.errors.map((e) => e.message).join('; '));
+                    continue;
+                }
+                const payload = result.data[mutationName];
+                const row = payload?.[singularName] ?? {};
+                created.push(row);
+            }
+            catch (err) {
+                errors.push(err instanceof Error ? err.message : 'Unknown error');
+            }
+        }
+        if (created.length === 0) {
+            return fail(`Failed to insert into "${params.table_name}": ${errors.join('; ') || 'unknown error'}`);
+        }
+        const columns = table.fields.map((f) => f.name);
+        const message = errors.length > 0
+            ? `Inserted ${created.length} of ${params.records.length} row(s) into ${params.table_name} (${errors.length} failed).`
+            : `Inserted ${created.length} row(s) into ${params.table_name}.`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: true,
+                message,
+                tableName: rawTable.name,
+                columns,
+                rows: created,
+                createdCount: created.length,
+                asOf: new Date().toISOString(),
+            },
+        };
+    },
+};

package/esm/tools/add-relation-schema.d.ts

@@ -0,0 +1,29 @@
+import type { BlueprintDefinition } from '@agentic-kit/harness';
+import { z } from 'zod';
+export declare const DeleteAction: z.ZodEnum<{
+    c: "c";
+    r: "r";
+    n: "n";
+    a: "a";
+    d: "d";
+}>;
+export declare const AddRelationZod: z.ZodObject<{
+    relation_type: z.ZodOptional<z.ZodEnum<{
+        belongs_to: "belongs_to";
+        many_to_many: "many_to_many";
+    }>>;
+    source_table: z.ZodString;
+    target_table: z.ZodString;
+    field_name: z.ZodOptional<z.ZodString>;
+    junction_table_name: z.ZodOptional<z.ZodString>;
+    delete_action: z.ZodOptional<z.ZodEnum<{
+        c: "c";
+        r: "r";
+        n: "n";
+        a: "a";
+        d: "d";
+    }>>;
+    is_required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AddRelationParams = z.infer<typeof AddRelationZod>;
+export declare function buildRelation(params: AddRelationParams): BlueprintDefinition['relations'];

package/esm/tools/add-relation-schema.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+// delete_action is intentionally always sent: the backend REJECTS a
+// RelationBelongsTo whose delete_action is absent ("PROVISION_RELATION:
+// delete_action is required"). We default it to 'a' (NO ACTION) so the model
+// never has to supply it.
+export const DeleteAction = z
+    .enum(['c', 'r', 'n', 'a', 'd'])
+    .describe('FK delete action: c=CASCADE, r=RESTRICT, n=SET NULL, a=NO ACTION (default), d=SET DEFAULT');
+export const AddRelationZod = z.object({
+    relation_type: z
+        .enum(['belongs_to', 'many_to_many'])
+        .describe('belongs_to adds an FK column on the source table; many_to_many adds a junction table. Defaults to belongs_to.')
+        .optional(),
+    source_table: z.string().describe('Existing source table name (snake_case).'),
+    target_table: z.string().describe('Existing target table name (snake_case).'),
+    field_name: z
+        .string()
+        .describe('belongs_to only: FK column name to add on the source table, e.g. "author_id".')
+        .optional(),
+    junction_table_name: z
+        .string()
+        .describe('many_to_many only: name of the junction table to create, e.g. "post_tags".')
+        .optional(),
+    delete_action: DeleteAction.optional(),
+    is_required: z
+        .boolean()
+        .describe('belongs_to only: make the FK NOT NULL. Defaults to false — a NOT NULL FK fails if the source table already has rows.')
+        .optional(),
+});
+// Build a relation-only blueprint definition (no tables): the spike proved
+// constructBlueprint applies relations to PRE-EXISTING tables without recreating
+// them, as long as delete_action is supplied.
+export function buildRelation(params) {
+    const deleteAction = params.delete_action ?? 'a';
+    if ((params.relation_type ?? 'belongs_to') === 'many_to_many') {
+        return [
+            {
+                $type: 'RelationManyToMany',
+                source_table: params.source_table,
+                target_table: params.target_table,
+                junction_table_name: params.junction_table_name,
+                delete_action: deleteAction,
+            },
+        ];
+    }
+    return [
+        {
+            $type: 'RelationBelongsTo',
+            source_table: params.source_table,
+            target_table: params.target_table,
+            field_name: params.field_name,
+            delete_action: deleteAction,
+            is_required: params.is_required ?? false,
+        },
+    ];
+}

package/esm/tools/add-relation.d.ts

@@ -0,0 +1,10 @@
+import { type HarnessTool } from '@agentic-kit/harness';
+import { AddRelationZod } from './add-relation-schema';
+export type AddRelationDetails = {
+    success: boolean;
+    message: string;
+    sourceTable?: string;
+    targetTable?: string;
+    fieldName?: string;
+};
+export declare const addRelationTool: HarnessTool<typeof AddRelationZod, AddRelationDetails>;

package/esm/tools/add-relation.js

@@ -0,0 +1,91 @@
+import { expandBlueprintDefaults } from '@agentic-kit/harness';
+import { resolveProjectContext } from '../context';
+import { resolveSchema, resolveTable } from '../schema-resolve';
+import { AddRelationZod, buildRelation } from './add-relation-schema';
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+export const addRelationTool = {
+    name: 'add_relation',
+    label: 'Add relation',
+    description: 'Add a relation between two EXISTING tables without recreating them: belongs_to adds a foreign-key column on the source table; many_to_many creates a junction table. Use this for relations discovered after the tables were provisioned. For brand-new related tables, prefer a single provision_blueprint call.',
+    promptSnippet: 'add_relation: link two existing tables (belongs_to FK column, or many_to_many junction). Gated.',
+    parameters: AddRelationZod,
+    async execute(params, ctx) {
+        const type = params.relation_type ?? 'belongs_to';
+        if (type === 'belongs_to' && !params.field_name) {
+            return fail('field_name is required for a belongs_to relation (the FK column name on the source table).');
+        }
+        if (type === 'many_to_many' && !params.junction_table_name) {
+            return fail('junction_table_name is required for a many_to_many relation.');
+        }
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { modules, databaseId, schemaId, ownerId } = resolved.context;
+        if (!ownerId)
+            return fail('Not authenticated (missing OWNER_ID in .env).');
+        // Validate both tables exist before constructing — a clearer error than the
+        // backend's, and avoids a no-op blueprint.
+        let schema;
+        try {
+            schema = await resolveSchema(resolved.context);
+            resolveTable(schema, params.source_table);
+            resolveTable(schema, params.target_table);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to resolve schema.');
+        }
+        const definition = expandBlueprintDefaults({ tables: [], relations: buildRelation(params) });
+        const uniqueName = `add_relation_${Date.now()}`;
+        try {
+            const created = await modules.blueprint
+                .create({
+                data: {
+                    ownerId,
+                    databaseId,
+                    name: uniqueName,
+                    displayName: `${params.source_table} → ${params.target_table}`,
+                    description: `Add ${type} relation`,
+                    definition,
+                },
+                select: { id: true },
+            })
+                .unwrap();
+            const blueprintId = created.createBlueprint?.blueprint?.id;
+            if (!blueprintId)
+                throw new Error('Failed to create relation blueprint');
+            const constructResult = await modules.mutation
+                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
+                .unwrap();
+            if (!constructResult.constructBlueprint?.result) {
+                const constructions = await modules.blueprintConstruction
+                    .findMany({
+                    where: { blueprintId: { equalTo: blueprintId } },
+                    orderBy: ['ID_DESC'],
+                    first: 1,
+                    select: { status: true, errorDetails: true },
+                })
+                    .unwrap();
+                const error = constructions?.blueprintConstructions?.nodes?.[0]?.errorDetails ?? 'Unknown error';
+                return fail(`Failed to add relation: ${typeof error === 'string' ? error : JSON.stringify(error)}`);
+            }
+        }
+        catch (err) {
+            return fail(`Failed to add relation: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const message = type === 'many_to_many'
+            ? `Created junction table "${params.junction_table_name}" linking ${params.source_table} ↔ ${params.target_table}.`
+            : `Added FK "${params.field_name}" on ${params.source_table} → ${params.target_table}.`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: true,
+                message,
+                sourceTable: params.source_table,
+                targetTable: params.target_table,
+                fieldName: params.field_name,
+            },
+        };
+    },
+};

package/esm/tools/create-api-key.d.ts

@@ -0,0 +1,25 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+declare const CreateApiKeyZod: z.ZodObject<{
+    key_name: z.ZodString;
+    principal_name: z.ZodOptional<z.ZodString>;
+    entity_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    read_only: z.ZodOptional<z.ZodBoolean>;
+    expires_in_days: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CreateApiKeyDetails = {
+    success: boolean;
+    message: string;
+    keyId?: string;
+    envVar?: string;
+    expiresAt?: string;
+    principalId?: string;
+    principalName?: string;
+    scope?: string;
+    needsAuth?: boolean;
+};
+export declare function toEnvVar(keyName: string): string;
+export declare function isStepUpError(messages: string[]): boolean;
+export declare function describeScope(entityIds: string[] | undefined, readOnly: boolean): string;
+export declare const createApiKeyTool: HarnessTool<typeof CreateApiKeyZod, CreateApiKeyDetails>;
+export {};

package/esm/tools/create-api-key.js

@@ -0,0 +1,214 @@
+import { auth } from '@constructive-io/sdk';
+import { z } from 'zod';
+import { deriveSubdomainEndpoint, resolveDataToken, resolveProjectContext } from '../context';
+import { getHost } from '../host';
+const CreateApiKeyZod = z.object({
+    key_name: z
+        .string()
+        .describe('Name for the API key (e.g. "deploy bot"). The .env variable name derives from it (UPPER_SNAKE + _API_KEY).'),
+    principal_name: z
+        .string()
+        .describe('Machine identity (principal) that owns the key. Defaults to key_name. An existing principal with this name is reused for unscoped keys.')
+        .optional(),
+    entity_ids: z
+        .array(z.string())
+        .describe('Entity row UUIDs to scope the principal to. Omit for a personal (unscoped) key that acts as the signed-in app user.')
+        .optional(),
+    read_only: z
+        .boolean()
+        .describe('Restrict the principal and key to read-only operations.')
+        .optional(),
+    expires_in_days: z
+        .number()
+        .int()
+        .positive()
+        .describe('Key lifetime in days. Default 90.')
+        .optional(),
+});
+function fail(message, extra) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message, ...extra },
+    };
+}
+export function toEnvVar(keyName) {
+    const base = keyName
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return base.endsWith('_API_KEY') ? base : `${base}_API_KEY`;
+}
+export function isStepUpError(messages) {
+    return messages.some((m) => /step[\s_-]?up/i.test(m));
+}
+export function describeScope(entityIds, readOnly) {
+    const parts = [];
+    parts.push(entityIds?.length
+        ? `scoped to ${entityIds.length} entit${entityIds.length === 1 ? 'y' : 'ies'}`
+        : 'unscoped (acts as the signed-in app user)');
+    if (readOnly)
+        parts.push('read-only');
+    return parts.join(', ');
+}
+async function rawGraphql(endpoint, token, query, variables) {
+    const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ query, variables }),
+    });
+    return (await res.json());
+}
+async function createPrincipalInputFields(endpoint) {
+    const probe = await rawGraphql(endpoint, undefined, '{ __type(name: "CreatePrincipalInput") { inputFields { name } } }');
+    const type = probe.data?.__type;
+    return new Set((type?.inputFields ?? []).map((f) => f.name));
+}
+export const createApiKeyTool = {
+    name: 'create_api_key',
+    label: 'Create API key',
+    description: 'Mint an API key for the project database, owned by a machine principal. Optionally scope it to specific entity rows and/or read-only. The human confirms the mint, completes MFA step-up in the app when required, and receives the key via .env + a one-time reveal — the plaintext key never appears in this conversation. Requires the user to be signed in to their app in the Preview.',
+    promptSnippet: 'create_api_key: mint an entity-scoped API key for the project database. Gated; the plaintext goes to .env + a one-time reveal, never into the chat — reference it as its env var.',
+    parameters: CreateApiKeyZod,
+    async execute(params, ctx) {
+        const keyName = params.key_name?.trim();
+        if (!keyName)
+            return fail('create_api_key requires "key_name".');
+        const resolved = await resolveProjectContext(ctx.cwd, { plane: 'data' });
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { databaseId, databaseName, apiEndpoint } = resolved.context;
+        if (!databaseName) {
+            return fail('Cannot resolve the app auth endpoint (DATABASE_NAME missing from .env). Re-provision the database, then retry.');
+        }
+        const host = getHost();
+        if (!host.deliverSecret) {
+            return fail('This host cannot deliver secrets (no .env write + reveal flow), so no key was minted. Create the key from a host that supports secret delivery.');
+        }
+        const token = await resolveDataToken(resolved.context);
+        if (!token.token) {
+            return fail(token.reason ?? 'Sign in to the app database to create an API key.', {
+                needsAuth: true,
+            });
+        }
+        const authEndpoint = deriveSubdomainEndpoint(apiEndpoint, `auth-${databaseName}`);
+        if (!authEndpoint)
+            return fail('Cannot derive the app auth endpoint.');
+        const scoped = Boolean(params.entity_ids?.length) || params.read_only === true;
+        try {
+            if (scoped) {
+                const fields = await createPrincipalInputFields(authEndpoint);
+                const missing = [
+                    ...(params.entity_ids?.length && !fields.has('entityIds') ? ['entityIds'] : []),
+                    ...(params.read_only === true && !fields.has('isReadOnly') ? ['isReadOnly'] : []),
+                ];
+                if (missing.length) {
+                    return fail(`This deployment does not support scoping a principal at create time (no ${missing.join(', ')} on createPrincipal). No key was minted. If an unscoped key that acts as the signed-in user is acceptable, ask for one explicitly.`);
+                }
+            }
+            const dbAuth = auth.createClient({
+                endpoint: authEndpoint,
+                headers: { Authorization: `Bearer ${token.token}` },
+            });
+            const principalName = params.principal_name?.trim() || keyName;
+            const existing = await dbAuth.principal
+                .findFirst({
+                where: { name: { equalTo: principalName } },
+                select: { id: true, name: true, userId: true, isReadOnly: true },
+            })
+                .unwrap();
+            // createApiKey (like createPrincipal.result) takes the principal's
+            // identity userId; principal_entity.principalId references the row id.
+            let principalId = existing.principal?.userId;
+            if (existing.principal && scoped) {
+                return fail(`Principal "${principalName}" already exists, and its scope cannot be verified against the requested one. No key was minted. Use a new principal_name for a scoped key, or mint an unscoped key on the existing principal explicitly.`);
+            }
+            if (existing.principal) {
+                const scopeRow = await dbAuth.principalEntity
+                    .findFirst({
+                    where: { principalId: { equalTo: existing.principal.id } },
+                    select: { id: true },
+                })
+                    .unwrap();
+                if (scopeRow.principalEntity || existing.principal?.isReadOnly) {
+                    return fail(`Principal "${principalName}" already exists with a narrower scope (entity-scoped or read-only), so a key minted under it would not act as the signed-in user. No key was minted. Use a new principal_name for an unscoped key.`);
+                }
+            }
+            if (!principalId) {
+                // The SDK's PrincipalModel.create sends a nested {principal} input, but
+                // the live CreatePrincipalInput is flat and its payload only exposes
+                // `result: UUID` — raw GraphQL is the only working surface.
+                const created = await rawGraphql(authEndpoint, token.token, 'mutation ($input: CreatePrincipalInput!) { createPrincipal(input: $input) { result } }', {
+                    input: {
+                        name: principalName,
+                        ...(params.entity_ids?.length && { entityIds: params.entity_ids }),
+                        ...(params.read_only !== undefined && { isReadOnly: params.read_only }),
+                    },
+                });
+                if (created.errors?.length) {
+                    return fail(`createPrincipal failed: ${created.errors.map((e) => e.message).join('; ')}`);
+                }
+                const payload = created.data?.createPrincipal;
+                principalId = payload?.result;
+                if (!principalId)
+                    return fail('createPrincipal returned no principal id.');
+            }
+            const mint = () => dbAuth.mutation
+                .createApiKey({
+                input: {
+                    principalId: principalId,
+                    keyName,
+                    ...(params.read_only && { accessLevel: 'read_only' }),
+                    expiresIn: { days: params.expires_in_days ?? 90 },
+                },
+            }, { select: { result: { select: { apiKey: true, keyId: true, expiresAt: true } } } })
+                .execute();
+            let minted = await mint();
+            if (!minted.ok && isStepUpError(minted.errors.map((e) => e.message))) {
+                if (!host.requestStepUp) {
+                    return fail('Creating this key requires MFA step-up, and this host has no step-up flow. Complete step-up in the app (verify your password), then retry.');
+                }
+                const verified = await host.requestStepUp({ databaseId, databaseName, apiEndpoint });
+                if (!verified)
+                    return fail('Step-up verification was not completed. No key was minted.');
+                minted = await mint();
+            }
+            if (!minted.ok) {
+                return fail(`createApiKey failed: ${minted.errors.map((e) => e.message).join('; ')}`);
+            }
+            const record = minted.data?.createApiKey?.result;
+            if (!record?.apiKey || !record.keyId)
+                return fail('createApiKey returned no key.');
+            const envVar = toEnvVar(keyName);
+            await host.deliverSecret({
+                databaseId,
+                cwd: ctx.cwd,
+                envVar,
+                plaintext: record.apiKey,
+                keyId: record.keyId,
+                expiresAt: record.expiresAt ?? undefined,
+            });
+            const scope = describeScope(params.entity_ids, params.read_only === true);
+            const message = `Created API key "${keyName}" (keyId: ${record.keyId}) for principal "${principalName}" — ${scope}. The key was written to .env as ${envVar} and revealed once to the user; it is not in this conversation. Reference it as ${envVar}.${record.expiresAt ? ` Expires ${record.expiresAt}.` : ''}`;
+            return {
+                content: [{ type: 'text', text: message }],
+                details: {
+                    success: true,
+                    message,
+                    keyId: record.keyId,
+                    envVar,
+                    expiresAt: record.expiresAt ?? undefined,
+                    principalId,
+                    principalName,
+                    scope,
+                },
+            };
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to create the API key.');
+        }
+    },
+};