@intx/db 0.2.2 → 0.4.0

package/dist/parse-row.js

@@ -1,12 +1,40 @@
 import { type } from "arktype";
-import { Capability, CredentialRequirement, GrantRequirement, grantEffects, grantOrigins, ModelProviderPlugin, ModelRequirements, } from "@intx/types";
-import { RepoAction } from "@intx/types/sidecar";
+import { Capability, CredentialBinding, GrantRequirement, grantEffects, grantOrigins, InvokerModelPreferences, ModelProviderPlugin, ModelRequirements, principalKinds, principalStatuses, signalKinds, TenantConfig, workflowDefinitionStatuses, workflowDefinitionVersionStatuses, } from "@intx/types";
+import { WireGrantRule } from "@intx/types/grant-wire";
+import { FrozenApprovalBundle, RepoAction } from "@intx/types/sidecar";
 import { ToolPackagePinArray } from "@intx/types/tool-packages";
 const JSONObject = type("Record<string, unknown>");
+const StringArray = type("string[]");
+const WireGrantRuleArray = WireGrantRule.array();
 const GrantEffectValidator = type.enumerated(...grantEffects);
 const GrantOriginValidator = type.enumerated(...grantOrigins);
-const agentVersionStatuses = ["active", "inactive", "failed"];
-const AgentVersionStatusValidator = type.enumerated(...agentVersionStatuses);
+const approvalScopes = ["once", "always"];
+const ApprovalScopeValidator = type.enumerated(...approvalScopes);
+const approvalStatuses = [
+    "pending",
+    "approved",
+    "rejected",
+    "timeout",
+    "expired",
+];
+const ApprovalStatusValidator = type.enumerated(...approvalStatuses);
+const SignalKindValidator = type.enumerated(...signalKinds);
+const workflowRunStatuses = [
+    "deployed",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+];
+const WorkflowRunStatusValidator = type.enumerated(...workflowRunStatuses);
+const WorkflowRunDispatchStatusValidator = type.enumerated("pending", "acknowledged", "settled", "failed");
+const WorkflowRunDispatchKindValidator = type.enumerated("mail", "signal");
+const WorkflowDefinitionStatusValidator = type.enumerated(...workflowDefinitionStatuses);
+const WorkflowDefinitionVersionStatusValidator = type.enumerated(...workflowDefinitionVersionStatuses);
+const PrincipalKindValidator = type.enumerated(...principalKinds);
+const PrincipalStatusValidator = type.enumerated(...principalStatuses);
+const principalKeyStatuses = ["active", "retired"];
+const PrincipalKeyStatusValidator = type.enumerated(...principalKeyStatuses);
 const credentialTypes = [
     "api_key",
     "oauth_token",
@@ -31,35 +59,36 @@ const turnPartTypes = [
     "file",
     "error",
     "refusal",
+    "safety_rating",
     "step-start",
     "step-finish",
     "snapshot",
     "patch",
 ];
 const TurnPartTypeValidator = type.enumerated(...turnPartTypes);
-export function parseAgentRow(row) {
+export function parseWorkflowDefinitionRow(row) {
     return {
         ...row,
-        contextConfig: row.contextConfig !== null ? JSONObject.assert(row.contextConfig) : null,
-        initialState: row.initialState !== null ? JSONObject.assert(row.initialState) : null,
-        modelConfig: row.modelConfig !== null ? JSONObject.assert(row.modelConfig) : null,
-        capabilities: row.capabilities !== null ? JSONObject.assert(row.capabilities) : null,
-        credentialRequirements: row.credentialRequirements !== null
-            ? CredentialRequirement.array().assert(row.credentialRequirements)
+        status: WorkflowDefinitionStatusValidator.assert(row.status),
+        grantRequirements: row.grantRequirements !== null
+            ? GrantRequirement.array().assert(row.grantRequirements)
             : null,
         modelRequirements: row.modelRequirements !== null
             ? ModelRequirements.assert(row.modelRequirements)
             : null,
-        grantRequirements: row.grantRequirements !== null
-            ? GrantRequirement.array().assert(row.grantRequirements)
-            : null,
-        toolPackages: ToolPackagePinArray.assert(row.toolPackages),
+        // Nullable jsonb: `null` on a real drizzle row, `undefined` only on a
+        // partial row-shaped test stub that predates the column. Both mean "no
+        // bindings" -- treat them alike rather than asserting `undefined` as an
+        // array.
+        credentialBindings: row.credentialBindings === null || row.credentialBindings === undefined
+            ? null
+            : CredentialBinding.array().assert(row.credentialBindings),
     };
 }
-export function parseAgentVersionRow(row) {
+export function parseWorkflowDefinitionVersionRow(row) {
     return {
         ...row,
-        status: AgentVersionStatusValidator.assert(row.status),
+        status: WorkflowDefinitionVersionStatusValidator.assert(row.status),
     };
 }
 export function parseGrantRow(row) {
@@ -70,6 +99,75 @@ export function parseGrantRow(row) {
         conditions: row.conditions !== null ? JSONObject.assert(row.conditions) : null,
     };
 }
+export function parseApprovalRow(row) {
+    return {
+        ...row,
+        scope: row.scope !== null ? ApprovalScopeValidator.assert(row.scope) : null,
+        status: ApprovalStatusValidator.assert(row.status),
+        toolDefinition: JSONObject.assert(row.toolDefinition),
+        toolArguments: JSONObject.assert(row.toolArguments),
+    };
+}
+export function parsePrincipalRow(row) {
+    return {
+        ...row,
+        kind: PrincipalKindValidator.assert(row.kind),
+        status: PrincipalStatusValidator.assert(row.status),
+    };
+}
+export function parsePrincipalKeyRow(row) {
+    return {
+        ...row,
+        status: PrincipalKeyStatusValidator.assert(row.status),
+    };
+}
+export function parseSignalCorrelationRow(row) {
+    return {
+        ...row,
+        kind: SignalKindValidator.assert(row.kind),
+    };
+}
+export function parseWorkflowRunRow(row) {
+    return {
+        ...row,
+        status: WorkflowRunStatusValidator.assert(row.status),
+        modelPreferences: row.modelPreferences !== null
+            ? InvokerModelPreferences.assert(row.modelPreferences)
+            : null,
+    };
+}
+export function parseWorkflowRunLaunchSpecRow(row) {
+    const sourceOfferingIds = StringArray.assert(row.sourceOfferingIds);
+    assertLaunchSpecSources(sourceOfferingIds, row.defaultSourceOfferingId);
+    return {
+        ...row,
+        frozenApprovalBundle: FrozenApprovalBundle.assert(row.frozenApprovalBundle),
+        sourceOfferingIds,
+        deployContent: JSONObject.assert(row.deployContent),
+        toolPackagePins: row.toolPackagePins !== null
+            ? ToolPackagePinArray.assert(row.toolPackagePins)
+            : null,
+    };
+}
+export function parseWorkflowRunDispatchRow(row) {
+    return {
+        ...row,
+        kind: WorkflowRunDispatchKindValidator.assert(row.kind),
+        status: WorkflowRunDispatchStatusValidator.assert(row.status),
+        stepGrants: WireGrantRuleArray.assert(row.stepGrants),
+    };
+}
+function assertLaunchSpecSources(sourceOfferingIds, defaultSourceOfferingId) {
+    if (sourceOfferingIds.length === 0) {
+        throw new Error("workflow launch spec requires at least one source offering");
+    }
+    if (new Set(sourceOfferingIds).size !== sourceOfferingIds.length) {
+        throw new Error("workflow launch spec source offering ids must be unique");
+    }
+    if (!sourceOfferingIds.includes(defaultSourceOfferingId)) {
+        throw new Error(`workflow launch spec default source ${defaultSourceOfferingId} is not in its source offering ids`);
+    }
+}
 export function parseOfferingRow(row) {
     return {
         ...row,
@@ -101,12 +199,13 @@ export function parseModelOfferingRow(row) {
     return {
         ...row,
         capabilities: Capability.array().assert(row.capabilities),
+        quirks: row.quirks !== null ? JSONObject.assert(row.quirks) : null,
     };
 }
 export function parseTenantRow(row) {
     return {
         ...row,
-        config: row.config !== null ? JSONObject.assert(row.config) : null,
+        config: row.config !== null ? TenantConfig.assert(row.config) : null,
     };
 }
 export function parseWalletRow(row) {

package/dist/principal-key-store.d.ts

@@ -0,0 +1,51 @@
+import type { CredentialCipher } from "@intx/types";
+import type { DB, DBExecutor } from "./client.js";
+type DBHandle = DB["db"];
+export type CreatePrincipalKeyStoreDeps = {
+    db: DBHandle;
+    /**
+     * Seals the private key seed at rest. Production supplies a real env-key
+     * cipher under `PRINCIPAL_KEY_ENCRYPTION_KEY`; tests and local dev may supply
+     * the noop cipher, which stores the seed as plaintext.
+     */
+    cipher: CredentialCipher;
+};
+/**
+ * Store for the `principal_key` table -- a principal's Ed25519 signing key.
+ *
+ * The hub custodies the private key: it mints, seals, and signs with it on the
+ * principal's behalf. A signature therefore ATTRIBUTES an action to a principal
+ * but is NOT non-repudiable against the hub operator, who holds the key. See
+ * docs/AUTH.md.
+ *
+ * The store owns the one-active-key-per-principal invariant end to end: `sign`
+ * and `getPublicKey` resolve the single active row, and `generate` inserts a new
+ * active key that the table's partial unique index rejects if the principal
+ * already has one. The private seed never leaves this module -- `sign` decrypts,
+ * signs, and discards it; no method returns private material.
+ */
+export declare function createPrincipalKeyStore({ db, cipher, }: CreatePrincipalKeyStoreDeps): {
+    /**
+     * Mint a fresh active signing key for a principal. Generates an Ed25519 key
+     * pair, seals the hex-encoded 32-byte seed with the cipher bound to the
+     * key's row and column, and inserts it. A principal that already holds an
+     * active key trips the partial unique index and this throws. Returns the
+     * hex-encoded public key; never returns private material.
+     */
+    generate(principalId: string, tx?: DBExecutor): Promise<string>;
+    /**
+     * Sign a message with the principal's active key. Decrypts the sealed seed,
+     * produces the raw 64-byte Ed25519 signature, and discards the seed. Throws
+     * when the principal has no active key. The seed stays a local that goes out
+     * of scope; it is never returned or logged.
+     */
+    sign(principalId: string, message: Uint8Array, tx?: DBExecutor): Promise<Uint8Array>;
+    /**
+     * The hex-encoded public key of a principal's active signing key. Throws
+     * when the principal has no active key rather than defaulting, so a missing
+     * key surfaces at the call site instead of downstream.
+     */
+    getPublicKey(principalId: string, tx?: DBExecutor): Promise<string>;
+};
+export type PrincipalKeyStore = ReturnType<typeof createPrincipalKeyStore>;
+export {};

package/dist/principal-key-store.js

@@ -0,0 +1,82 @@
+import { and, eq } from "drizzle-orm";
+import { generateKeyPair, signEd25519 } from "@intx/crypto";
+import { hexDecode, hexEncode, principalKeyAad } from "@intx/types";
+import { generateId } from "@intx/hub-common";
+import { principalKey } from "./schema/principal-keys.js";
+/**
+ * Store for the `principal_key` table -- a principal's Ed25519 signing key.
+ *
+ * The hub custodies the private key: it mints, seals, and signs with it on the
+ * principal's behalf. A signature therefore ATTRIBUTES an action to a principal
+ * but is NOT non-repudiable against the hub operator, who holds the key. See
+ * docs/AUTH.md.
+ *
+ * The store owns the one-active-key-per-principal invariant end to end: `sign`
+ * and `getPublicKey` resolve the single active row, and `generate` inserts a new
+ * active key that the table's partial unique index rejects if the principal
+ * already has one. The private seed never leaves this module -- `sign` decrypts,
+ * signs, and discards it; no method returns private material.
+ */
+export function createPrincipalKeyStore({ db, cipher, }) {
+    async function loadActive(principalId, tx) {
+        const [row] = await (tx ?? db)
+            .select()
+            .from(principalKey)
+            .where(and(eq(principalKey.principalId, principalId), eq(principalKey.status, "active")))
+            .limit(1);
+        return row;
+    }
+    return {
+        /**
+         * Mint a fresh active signing key for a principal. Generates an Ed25519 key
+         * pair, seals the hex-encoded 32-byte seed with the cipher bound to the
+         * key's row and column, and inserts it. A principal that already holds an
+         * active key trips the partial unique index and this throws. Returns the
+         * hex-encoded public key; never returns private material.
+         */
+        async generate(principalId, tx) {
+            const id = generateId("principalKey");
+            const keyPair = await generateKeyPair();
+            const sealedPrivateKey = await cipher.encrypt(hexEncode(keyPair.privateKey), principalKeyAad(id, "private_key"));
+            const publicKey = hexEncode(keyPair.publicKey);
+            const now = new Date();
+            await (tx ?? db).insert(principalKey).values({
+                id,
+                principalId,
+                publicKey,
+                privateKey: sealedPrivateKey,
+                status: "active",
+                createdAt: now,
+                updatedAt: now,
+            });
+            return publicKey;
+        },
+        /**
+         * Sign a message with the principal's active key. Decrypts the sealed seed,
+         * produces the raw 64-byte Ed25519 signature, and discards the seed. Throws
+         * when the principal has no active key. The seed stays a local that goes out
+         * of scope; it is never returned or logged.
+         */
+        async sign(principalId, message, tx) {
+            const row = await loadActive(principalId, tx);
+            if (row === undefined) {
+                throw new Error(`principalKeyStore.sign: principal ${principalId} has no active key`);
+            }
+            const seedHex = await cipher.decrypt(row.privateKey, principalKeyAad(row.id, "private_key"));
+            const seed = hexDecode(seedHex);
+            return signEd25519(seed, message);
+        },
+        /**
+         * The hex-encoded public key of a principal's active signing key. Throws
+         * when the principal has no active key rather than defaulting, so a missing
+         * key surfaces at the call site instead of downstream.
+         */
+        async getPublicKey(principalId, tx) {
+            const row = await loadActive(principalId, tx);
+            if (row === undefined) {
+                throw new Error(`principalKeyStore.getPublicKey: principal ${principalId} has no active key`);
+            }
+            return row.publicKey;
+        },
+    };
+}

package/dist/principal-store.d.ts

@@ -0,0 +1,44 @@
+import type { DB, DBExecutor } from "./client.js";
+import { principal } from "./schema/principals.js";
+import { parsePrincipalRow } from "./parse-row.js";
+import type { PrincipalKeyStore } from "./principal-key-store.js";
+type DBHandle = DB["db"];
+type PrincipalInsert = typeof principal.$inferInsert;
+type ParsedPrincipal = ReturnType<typeof parsePrincipalRow>;
+/**
+ * Store for the `principal` table -- the single owner of principal creation.
+ * Every principal insert in the system routes through this one factory, and
+ * every principal it creates is minted an active signing key in the same
+ * transaction, so a principal never exists without a key.
+ *
+ * Each method accepts an optional transaction handle so the principal row and
+ * its key join the transaction that co-writes the principal's roles and grants.
+ * When no handle is passed the store opens its own transaction, because the
+ * principal insert and the key mint are two writes that must commit together.
+ */
+export declare function createPrincipalStore(db: DBHandle, principalKeyStore: PrincipalKeyStore): {
+    /**
+     * Insert a new principal and mint its signing key, failing loudly on a
+     * natural-key conflict. Callers that have already established the principal
+     * is new (a fresh tenant owner, an invite past its existence pre-check) use
+     * this so a concurrent duplicate surfaces as a unique violation rather than
+     * a silent success.
+     */
+    create(row: PrincipalInsert, tx?: DBExecutor): Promise<ParsedPrincipal>;
+    /**
+     * Idempotent variant of `create` for the run path, where concurrent first
+     * deliveries race to reserve the same principal. On a win it inserts the
+     * principal, mints its key, and returns the parsed row; on a loss it returns
+     * `null` WITHOUT minting -- the winning transaction already minted the one
+     * active key -- so the caller can fall back to the winner's state.
+     *
+     * The conflict target is the natural key `(tenantId, kind, refId)`, NOT the
+     * surrogate `id`: user principals carry a random `generateId("principal")`,
+     * so their only real conflict key is the natural triple. The run path
+     * derives a deterministic id that agrees with the triple, so one target
+     * unifies both callers. Do not switch this to `principal.id`.
+     */
+    createIfAbsent(row: PrincipalInsert, tx?: DBExecutor): Promise<ParsedPrincipal | null>;
+};
+export type PrincipalStore = ReturnType<typeof createPrincipalStore>;
+export {};

package/dist/principal-store.js

@@ -0,0 +1,67 @@
+import { principal } from "./schema/principals.js";
+import { parsePrincipalRow } from "./parse-row.js";
+/**
+ * Store for the `principal` table -- the single owner of principal creation.
+ * Every principal insert in the system routes through this one factory, and
+ * every principal it creates is minted an active signing key in the same
+ * transaction, so a principal never exists without a key.
+ *
+ * Each method accepts an optional transaction handle so the principal row and
+ * its key join the transaction that co-writes the principal's roles and grants.
+ * When no handle is passed the store opens its own transaction, because the
+ * principal insert and the key mint are two writes that must commit together.
+ */
+export function createPrincipalStore(db, principalKeyStore) {
+    return {
+        /**
+         * Insert a new principal and mint its signing key, failing loudly on a
+         * natural-key conflict. Callers that have already established the principal
+         * is new (a fresh tenant owner, an invite past its existence pre-check) use
+         * this so a concurrent duplicate surfaces as a unique violation rather than
+         * a silent success.
+         */
+        async create(row, tx) {
+            const run = async (executor) => {
+                const [inserted] = await executor
+                    .insert(principal)
+                    .values(row)
+                    .returning();
+                if (inserted === undefined) {
+                    throw new Error(`principalStore.create: insert returned no row for ${row.id}`);
+                }
+                await principalKeyStore.generate(inserted.id, executor);
+                return parsePrincipalRow(inserted);
+            };
+            return tx === undefined ? db.transaction(run) : run(tx);
+        },
+        /**
+         * Idempotent variant of `create` for the run path, where concurrent first
+         * deliveries race to reserve the same principal. On a win it inserts the
+         * principal, mints its key, and returns the parsed row; on a loss it returns
+         * `null` WITHOUT minting -- the winning transaction already minted the one
+         * active key -- so the caller can fall back to the winner's state.
+         *
+         * The conflict target is the natural key `(tenantId, kind, refId)`, NOT the
+         * surrogate `id`: user principals carry a random `generateId("principal")`,
+         * so their only real conflict key is the natural triple. The run path
+         * derives a deterministic id that agrees with the triple, so one target
+         * unifies both callers. Do not switch this to `principal.id`.
+         */
+        async createIfAbsent(row, tx) {
+            const run = async (executor) => {
+                const [inserted] = await executor
+                    .insert(principal)
+                    .values(row)
+                    .onConflictDoNothing({
+                    target: [principal.tenantId, principal.kind, principal.refId],
+                })
+                    .returning();
+                if (inserted === undefined)
+                    return null;
+                await principalKeyStore.generate(inserted.id, executor);
+                return parsePrincipalRow(inserted);
+            };
+            return tx === undefined ? db.transaction(run) : run(tx);
+        },
+    };
+}

package/dist/rekey-credential-secrets.d.ts

@@ -0,0 +1,13 @@
+import { type CredentialCipher } from "@intx/types";
+import type { DB } from "./client.js";
+export type RekeyReport = {
+    /** Credential `secret` columns newly encrypted. */
+    credentialSecrets: number;
+    /** Credential `refresh_secret` columns newly encrypted. */
+    credentialRefreshSecrets: number;
+    /** OAuth-client `client_secret` columns newly encrypted. */
+    oauthClientSecrets: number;
+    /** Columns already encrypted and left unchanged. */
+    alreadyEncrypted: number;
+};
+export declare function rekeyCredentialSecrets(db: DB["db"], cipher: CredentialCipher): Promise<RekeyReport>;

package/dist/rekey-credential-secrets.js

@@ -0,0 +1,61 @@
+// Re-key existing credential secrets: encrypt any secret still stored as
+// plaintext, in place, under the given cipher.
+//
+// Ordinarily every secret is encrypted at its write site, so on a database
+// created after encryption-at-rest landed there is nothing to do. This pass
+// exists for the transition: a database whose rows predate encryption still
+// holds plaintext, and the strict read path throws on a non-ciphertext value.
+// Running this once (against a stopped hub, so no write races an un-re-keyed
+// row) brings every row to the encrypted form.
+//
+// Idempotent: a value already a ciphertext is skipped, so the pass is safe to
+// re-run or resume after a partial failure.
+import { eq } from "drizzle-orm";
+import { credentialAad } from "@intx/types";
+import { isCiphertext } from "@intx/crypto";
+import { credential } from "./schema/credentials.js";
+import { oauthClient } from "./schema/oauth-clients.js";
+export async function rekeyCredentialSecrets(db, cipher) {
+    const report = {
+        credentialSecrets: 0,
+        credentialRefreshSecrets: 0,
+        oauthClientSecrets: 0,
+        alreadyEncrypted: 0,
+    };
+    for (const row of await db.select().from(credential)) {
+        const updates = {};
+        if (isCiphertext(row.secret)) {
+            report.alreadyEncrypted += 1;
+        }
+        else {
+            updates.secret = await cipher.encrypt(row.secret, credentialAad(row.id, "secret"));
+            report.credentialSecrets += 1;
+        }
+        if (row.refreshSecret !== null) {
+            if (isCiphertext(row.refreshSecret)) {
+                report.alreadyEncrypted += 1;
+            }
+            else {
+                updates.refreshSecret = await cipher.encrypt(row.refreshSecret, credentialAad(row.id, "refreshSecret"));
+                report.credentialRefreshSecrets += 1;
+            }
+        }
+        if (updates.secret !== undefined || updates.refreshSecret !== undefined) {
+            await db.update(credential).set(updates).where(eq(credential.id, row.id));
+        }
+    }
+    for (const row of await db.select().from(oauthClient)) {
+        if (isCiphertext(row.clientSecret)) {
+            report.alreadyEncrypted += 1;
+            continue;
+        }
+        await db
+            .update(oauthClient)
+            .set({
+            clientSecret: await cipher.encrypt(row.clientSecret, credentialAad(row.id, "clientSecret")),
+        })
+            .where(eq(oauthClient.id, row.id));
+        report.oauthClientSecrets += 1;
+    }
+    return report;
+}