@intx/db 0.2.2 → 0.4.0

package/README.md

@@ -31,12 +31,23 @@ const row = await db.query.agent.findFirst({
 });
 ```
 
-The `parseRow` functions (`parseAgentRow`, `parseGrantRow`, and so
-on) validate each table's `jsonb` columns once and return fully
+The `parseRow` functions (`parseWorkflowDefinitionRow`, `parseGrantRow`,
+and so on) validate each table's `jsonb` columns once and return fully
 typed values; downstream code uses those values without
 re-casting. See `CONVENTIONS.md` for the project-wide rule against
 cast-at-callsite in DB consumers.
 
+Connections created by `createDB` set PostgreSQL's `statement_timeout` to
+60,000 milliseconds. Override it with `statementTimeoutMs` in `DBConfig`
+(a positive integer up to 2,147,483,647 milliseconds). The Hub and the
+`bin/` database scripts read this override from `DB_STATEMENT_TIMEOUT_MS`.
+
+PostgreSQL cancels statements that exceed the deadline, including time
+waiting for locks. An uncaught timeout rolls back the enclosing transaction.
+This bounds individual statements once they reach PostgreSQL; pool waits,
+network stalls, and time between statements in an open transaction remain
+outside that deadline. Migration clients use their own connection settings.
+
 ## Model catalog
 
 The `model`, `model_provider`, `model_offering`, and `model_pricing`

package/dist/approval-store.d.ts

@@ -0,0 +1,59 @@
+import type { DB, DBExecutor } from "./client.js";
+import { approval } from "./schema/approvals.js";
+import { parseApprovalRow } from "./parse-row.js";
+type DBHandle = DB["db"];
+type ApprovalRow = typeof approval.$inferSelect;
+type ApprovalInsert = typeof approval.$inferInsert;
+type ParsedApproval = ReturnType<typeof parseApprovalRow>;
+type ApprovalResolution = Exclude<ApprovalRow["status"], "pending">;
+type ApprovalScope = NonNullable<ApprovalRow["scope"]>;
+export type ResolveApprovalArgs = {
+    status: ApprovalResolution;
+    scope?: ApprovalScope;
+    resolvedAt: Date;
+};
+/**
+ * Store for the `approval` table backing the approval round-trip. Each method
+ * accepts an optional transaction handle so the resolver can flip the approval
+ * and its signal correlation in a single `db.transaction`; when omitted the
+ * method runs against the store's own connection.
+ */
+export declare function createApprovalStore(db: DBHandle): {
+    create(row: ApprovalInsert, tx?: DBExecutor): Promise<ParsedApproval>;
+    /**
+     * Idempotent variant of `create`. On a `correlationId` unique conflict the
+     * insert is a no-op and this returns `null` rather than throwing, so a
+     * redelivered register frame (sidecar reconnect, workflow-log replay,
+     * supervisor restart re-emitting) does not fail the co-write. Conflicts
+     * on `correlationId` -- not the `id` primary key -- because the register
+     * co-write mints a fresh `id` per frame while the correlation is the stable
+     * dedup key. Returns the parsed row only when this call performed the
+     * insert.
+     */
+    createIfAbsent(row: ApprovalInsert, tx?: DBExecutor): Promise<ParsedApproval | null>;
+    findByCorrelationId(correlationId: string, tx?: DBExecutor): Promise<ParsedApproval | null>;
+    /**
+     * Look up an approval by its primary key. The resolve/reject routes key on
+     * the `approvalId` path parameter, which is the row's `id`, so they need a
+     * by-id read distinct from the by-correlation read the register co-write
+     * uses. Returns null when no row carries the id.
+     */
+    findById(id: string, tx?: DBExecutor): Promise<ParsedApproval | null>;
+    /**
+     * List a run's approvals, newest first, scoped by `tenantId` so one
+     * tenant's approvals never leak into another's view. Serves the run
+     * approvals list route; callers apply whatever status/scope predicate they
+     * need over the result.
+     */
+    listByRunId(tenantId: string, runId: string, tx?: DBExecutor): Promise<ParsedApproval[]>;
+    /**
+     * Conditionally resolve a pending approval. The `WHERE status = 'pending'`
+     * guard makes resolution terminal at the database: the first caller to
+     * resolve a given correlation gets the updated row back; any later caller
+     * (a duplicate delivery, a timeout racing an approval) matches no row and
+     * receives null.
+     */
+    resolve(correlationId: string, args: ResolveApprovalArgs, tx?: DBExecutor): Promise<ParsedApproval | null>;
+};
+export type ApprovalStore = ReturnType<typeof createApprovalStore>;
+export {};

package/dist/approval-store.js

@@ -0,0 +1,92 @@
+import { and, eq } from "drizzle-orm";
+import { approval } from "./schema/approvals.js";
+import { parseApprovalRow } from "./parse-row.js";
+/**
+ * Store for the `approval` table backing the approval round-trip. Each method
+ * accepts an optional transaction handle so the resolver can flip the approval
+ * and its signal correlation in a single `db.transaction`; when omitted the
+ * method runs against the store's own connection.
+ */
+export function createApprovalStore(db) {
+    return {
+        async create(row, tx) {
+            const [inserted] = await (tx ?? db)
+                .insert(approval)
+                .values(row)
+                .returning();
+            if (inserted === undefined) {
+                throw new Error(`approvalStore.create: insert returned no row for ${row.id}`);
+            }
+            return parseApprovalRow(inserted);
+        },
+        /**
+         * Idempotent variant of `create`. On a `correlationId` unique conflict the
+         * insert is a no-op and this returns `null` rather than throwing, so a
+         * redelivered register frame (sidecar reconnect, workflow-log replay,
+         * supervisor restart re-emitting) does not fail the co-write. Conflicts
+         * on `correlationId` -- not the `id` primary key -- because the register
+         * co-write mints a fresh `id` per frame while the correlation is the stable
+         * dedup key. Returns the parsed row only when this call performed the
+         * insert.
+         */
+        async createIfAbsent(row, tx) {
+            const [inserted] = await (tx ?? db)
+                .insert(approval)
+                .values(row)
+                .onConflictDoNothing({ target: approval.correlationId })
+                .returning();
+            return inserted === undefined ? null : parseApprovalRow(inserted);
+        },
+        async findByCorrelationId(correlationId, tx) {
+            const row = await (tx ?? db).query.approval.findFirst({
+                where: eq(approval.correlationId, correlationId),
+            });
+            return row === undefined ? null : parseApprovalRow(row);
+        },
+        /**
+         * Look up an approval by its primary key. The resolve/reject routes key on
+         * the `approvalId` path parameter, which is the row's `id`, so they need a
+         * by-id read distinct from the by-correlation read the register co-write
+         * uses. Returns null when no row carries the id.
+         */
+        async findById(id, tx) {
+            const row = await (tx ?? db).query.approval.findFirst({
+                where: eq(approval.id, id),
+            });
+            return row === undefined ? null : parseApprovalRow(row);
+        },
+        /**
+         * List a run's approvals, newest first, scoped by `tenantId` so one
+         * tenant's approvals never leak into another's view. Serves the run
+         * approvals list route; callers apply whatever status/scope predicate they
+         * need over the result.
+         */
+        async listByRunId(tenantId, runId, tx) {
+            const rows = await (tx ?? db).query.approval.findMany({
+                where: and(eq(approval.tenantId, tenantId), eq(approval.runId, runId)),
+                orderBy: (a, { desc }) => desc(a.createdAt),
+            });
+            return rows.map(parseApprovalRow);
+        },
+        /**
+         * Conditionally resolve a pending approval. The `WHERE status = 'pending'`
+         * guard makes resolution terminal at the database: the first caller to
+         * resolve a given correlation gets the updated row back; any later caller
+         * (a duplicate delivery, a timeout racing an approval) matches no row and
+         * receives null.
+         */
+        async resolve(correlationId, args, tx) {
+            const [updated] = await (tx ?? db)
+                .update(approval)
+                .set({
+                status: args.status,
+                scope: args.scope ?? null,
+                resolvedAt: args.resolvedAt,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(approval.correlationId, correlationId), eq(approval.status, "pending")))
+                .returning();
+            return updated === undefined ? null : parseApprovalRow(updated);
+        },
+    };
+}

package/dist/asset-resolution.d.ts

@@ -23,8 +23,8 @@ export declare function resolveAssetByName(db: DB["db"], tenantId: string, kind:
     createdAt: Date;
     updatedAt: Date;
     tenantId: string;
-    creatorPrincipalId: string | null;
     displayName: string | null;
+    creatorPrincipalId: string | null;
 } | null>;
 /**
  * Resolves an asset by ID, validating that it belongs to the given
@@ -38,8 +38,8 @@ export declare function resolveAssetById(db: DB["db"], tenantId: string, assetId
     createdAt: Date;
     updatedAt: Date;
     tenantId: string;
-    creatorPrincipalId: string | null;
     displayName: string | null;
+    creatorPrincipalId: string | null;
 } | null>;
 /**
  * Lists assets visible to the tenant, including those inherited from

package/dist/backfill-principal-keys.d.ts

@@ -0,0 +1,9 @@
+import type { DB } from "./client.js";
+import type { PrincipalKeyStore } from "./principal-key-store.js";
+export type BackfillPrincipalKeysReport = {
+    /** Principals that were keyless and received a fresh active key. */
+    keysGenerated: number;
+    /** Principals that already held an active key and were left untouched. */
+    alreadyKeyed: number;
+};
+export declare function backfillPrincipalKeys(db: DB["db"], principalKeyStore: PrincipalKeyStore): Promise<BackfillPrincipalKeysReport>;

package/dist/backfill-principal-keys.js

@@ -0,0 +1,51 @@
+// Backfill per-principal signing keys onto the principals that predate the
+// feature.
+//
+// Minting a key lives only in the principal-creation owner, so every principal
+// CREATED after that landed already has an active key. This one-shot pass keys
+// the pre-existing population so the whole non-agent principal set matches the
+// invariant "every non-agent principal has an active key".
+//
+// Scope is every `user` and `workflow` principal REGARDLESS of status, not just
+// active ones. A status flip (e.g. an invite moving from `invited` to `active`)
+// reuses the same principal row and does not re-mint, so an active-only pass
+// would leave a pre-existing `invited`/`suspended` principal keyless and turn it
+// into a keyless ACTIVE principal the moment it is activated. `agent` is a
+// legacy/inert kind that is never keyed at creation either, so it is skipped to
+// keep the populations consistent.
+//
+// Idempotent: a principal that already holds an active key is skipped, so the
+// pass is safe to re-run or resume after a partial failure. Each principal is
+// keyed in its own autocommit, so a partial failure leaves the earlier
+// principals keyed. Safe to run against a LIVE hub -- nothing reads principal
+// keys yet, the hub only mints for newly-created principals (disjoint from this
+// pass's pre-existing set), and the `principal_key` active-key unique index
+// blocks a double active key.
+import { and, eq, inArray } from "drizzle-orm";
+import { principal } from "./schema/principals.js";
+import { principalKey } from "./schema/principal-keys.js";
+const BACKFILLED_KINDS = ["user", "workflow"];
+export async function backfillPrincipalKeys(db, principalKeyStore) {
+    // The left join is scoped to the active key, so `activeKeyId` is null exactly
+    // when the principal has no active key -- a principal holding only a retired
+    // key counts as keyless and is re-keyed. The active-key unique index makes at
+    // most one active row per principal, so each principal appears once.
+    const rows = await db
+        .select({ principalId: principal.id, activeKeyId: principalKey.id })
+        .from(principal)
+        .leftJoin(principalKey, and(eq(principalKey.principalId, principal.id), eq(principalKey.status, "active")))
+        .where(inArray(principal.kind, [...BACKFILLED_KINDS]));
+    const report = {
+        keysGenerated: 0,
+        alreadyKeyed: 0,
+    };
+    for (const row of rows) {
+        if (row.activeKeyId !== null) {
+            report.alreadyKeyed += 1;
+            continue;
+        }
+        await principalKeyStore.generate(row.principalId);
+        report.keysGenerated += 1;
+    }
+    return report;
+}

package/dist/client.d.ts

@@ -1,9 +1,44 @@
+import type { ExtractTablesWithRelations } from "drizzle-orm";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
 import * as schema from "./schema/index.js";
+/**
+ * A drizzle database over the hub schema, typed against the driver-agnostic
+ * `PgDatabase` base rather than a single driver. `createDB` builds one over
+ * postgres-js; a caller can equally build one over pglite -- `drizzle(handle,
+ * { schema })` from `drizzle-orm/pglite`, with the schema re-exported from
+ * `@intx/db/schema` -- and pass it to the store factories. The required
+ * `$client` keeps a bare `PgTransaction` unassignable (a transaction carries no
+ * `$client`), so a parameter typed against this still rejects a tx where only a
+ * top-level database belongs.
+ */
+export type AnyPgDatabase = PgDatabase<PgQueryResultHKT, typeof schema, ExtractTablesWithRelations<typeof schema>> & {
+    $client: unknown;
+};
+/**
+ * The hub database handle: the database itself, plus `transaction` and
+ * `close`. `createDB` returns the postgres-js instantiation, but the handle is
+ * typed against `AnyPgDatabase` so the stores accept any pg driver -- a
+ * caller-built pglite database included.
+ */
+export interface DB {
+    db: AnyPgDatabase;
+    transaction: AnyPgDatabase["transaction"];
+    close: () => Promise<void>;
+}
 export declare function createDB(raw: unknown): {
     db: import("drizzle-orm/postgres-js").PostgresJsDatabase<typeof schema> & {
         $client: import("postgres").Sql<{}>;
     };
-    transaction: <T>(transaction: (tx: import("drizzle-orm/pg-core").PgTransaction<import("drizzle-orm/postgres-js").PostgresJsQueryResultHKT, typeof schema, import("drizzle-orm").ExtractTablesWithRelations<typeof schema>>) => Promise<T>, config?: import("drizzle-orm/pg-core").PgTransactionConfig) => Promise<T>;
+    transaction: <T>(transaction: (tx: import("drizzle-orm/pg-core").PgTransaction<import("drizzle-orm/postgres-js").PostgresJsQueryResultHKT, typeof schema, ExtractTablesWithRelations<typeof schema>>) => Promise<T>, config?: import("drizzle-orm/pg-core").PgTransactionConfig) => Promise<T>;
     close: () => Promise<void>;
 };
-export type DB = ReturnType<typeof createDB>;
+/**
+ * A handle that can execute queries: either the top-level `db` or a
+ * transaction handle passed into a `db.transaction` callback. Store methods
+ * that accept an optional `tx` type it against this so a caller can hand in
+ * the transaction object and have the write join the surrounding transaction.
+ * `DB["db"]` alone rejects a `PgTransaction` (it lacks the `$client` field the
+ * top-level database carries), so a bare `DB["db"]` parameter cannot accept a
+ * tx.
+ */
+export type DBExecutor = DB["db"] | Parameters<Parameters<DB["db"]["transaction"]>[0]>[0];

package/dist/client.js

@@ -16,3 +16,9 @@ export function createDB(raw) {
         close: () => sql.end(),
     };
 }
+// `createDB` returns the concrete postgres-js handle so its own callers keep
+// the driver's precise result types (e.g. a typed `db.execute`). This assures
+// at the definition site that the concrete handle still satisfies `DB`, the
+// driver-agnostic contract the stores consume.
+const _createDBReturnsDB = createDB;
+void _createDBReturnsDB;

package/dist/config.d.ts

@@ -6,6 +6,7 @@ export declare const DBConfig: import("arktype/internal/variants/object.ts").Obj
     database: string;
     ssl?: boolean;
     max?: number;
+    statementTimeoutMs?: number;
     schema?: string;
 }, {}>;
 export type DBConfig = typeof DBConfig.infer;

package/dist/config.js

@@ -7,6 +7,8 @@ export const DBConfig = type({
     database: "string",
     "ssl?": "boolean",
     "max?": "number.integer > 0",
+    // PostgreSQL statement deadline in milliseconds. Defaults to 60 seconds.
+    "statementTimeoutMs?": "0 < number.integer <= 2147483647",
     // Postgres schema name. When set, the connection's `search_path` is
     // pinned to this schema and migrations apply into it. This is the
     // mechanism the integration-test harness uses to give each spawned

package/dist/connection.js

@@ -11,13 +11,17 @@ export function createConnection(config) {
         database: config.database,
         max: config.max ?? 10,
         ...(config.ssl !== undefined && { ssl: config.ssl }),
-        ...(config.schema !== undefined && {
-            // Pin the connection's search_path so unqualified table
-            // references resolve to the caller's schema. The migration
-            // runner emits SQL with the schema baked into FK references,
-            // but ORM-issued queries bind table names without a schema
-            // qualifier and rely on this setting.
-            connection: { search_path: quoteIdentifier(config.schema) },
-        }),
+        connection: {
+            TimeZone: "UTC",
+            statement_timeout: config.statementTimeoutMs ?? 60_000,
+            ...(config.schema !== undefined && {
+                // Pin the connection's search_path so unqualified table
+                // references resolve to the caller's schema. The migration
+                // runner emits SQL with the schema baked into FK references,
+                // but ORM-issued queries bind table names without a schema
+                // qualifier and rely on this setting.
+                search_path: quoteIdentifier(config.schema),
+            }),
+        },
     });
 }

package/dist/credential-resolution.d.ts

@@ -1,4 +1,95 @@
+import type { CredentialBinding, CredentialCipher } from "@intx/types";
+import type { CredentialDelivery, CredentialMaterialEntry } from "@intx/types/sidecar";
 import type { DB } from "./client.js";
+/**
+ * Thrown by `resolveCredentialRequirement` when more than one credential
+ * matches a requirement and no name disambiguates them. A distinct type so
+ * callers can catch *this* condition (a launch-blocking configuration error)
+ * without also swallowing the DB reads the resolver performs first -- an
+ * infrastructure failure must surface, not be mislabeled as ambiguity.
+ */
+export declare class AmbiguousCredentialError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a referenced credential is not a tenant-owned credential the given
+ * tenant can use -- it does not exist, is not reachable in the tenant's ancestor
+ * chain, or is principal-owned. A distinct type so a caller can map a client's
+ * bad credential reference to a 4xx (a launch-blocking configuration error),
+ * separate from the infrastructure faults the resolvers otherwise surface.
+ */
+export declare class CredentialUnauthorizedError extends Error {
+    readonly credentialId: string;
+    readonly tenantId: string;
+    constructor(credentialId: string, tenantId: string);
+}
+/**
+ * Resolve a credential USABLE by the launching tenant purely through ownership:
+ * it exists, is reachable in the tenant's ancestor chain, and is tenant-owned
+ * (`principalId IS NULL`). Returns the row -- the proof of authority -- or null.
+ *
+ * This is the one "usable by ownership" resolver: a tenant may use what it (or
+ * an ancestor) owns, and descendants inherit; a principal-owned credential is
+ * never usable this way, its delegation flowing from its owner instead. It
+ * wraps `resolveCredentialById` (the ancestor-chain check) with the tenant-owned
+ * gate, so callers do not re-implement the predicate. `buildSource` expands it
+ * inline only to distinguish an unresolved reference from a principal-owned one.
+ */
+export declare function resolveTenantOwnedCredentialById(db: DB["db"], tenantId: string, credentialId: string): Promise<{
+    id: string;
+    name: string;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date | null;
+    providerId: string;
+    tenantId: string;
+    status: "active" | "error" | "expired" | "revoked";
+    principalId: string | null;
+    description: string | null;
+    scopes: string[] | null;
+    metadata: unknown;
+    oauthClientId: string | null;
+    type: "api_key" | "oauth_token" | "certificate" | "other";
+    secret: string;
+    refreshSecret: string | null;
+} | null>;
+/**
+ * Resolve a set of inference-source credentialIds into the credential material
+ * delivered on a run's unified credential-material cell. An inference source
+ * references its credential by id only; for each DISTINCT id this resolves the
+ * secret under the SAME tenant-ownership authority `buildSource` uses -- the
+ * credential must exist, be reachable in the tenant's ancestor chain, and be
+ * tenant-owned (`principalId IS NULL`) -- then decrypts it at the single point of
+ * use. `providerKey`/`origin` come from the credential's own provider row
+ * (`provider.plugin` / `provider.apiBaseUrl`), so the material describes the
+ * credential itself, independent of any caller-supplied source fields.
+ *
+ * Fails CLOSED, by throwing, on the first credentialId that is unresolved, not
+ * tenant-owned, references a missing provider, or whose provider has no API
+ * origin to pin -- a secret is never dropped nor delivered without an origin. The
+ * single resolver for every inference source credentialId -> material, shared by
+ * the deploy composition (top-level + inline body sources) and any other caller
+ * that must materialize inference credentials for the cell.
+ */
+export declare function resolveInferenceMaterials(db: DB["db"], tenantId: string, credentialIds: Iterable<string>, credentialCipher: CredentialCipher): Promise<CredentialMaterialEntry[]>;
+/**
+ * Re-resolve the CURRENT material for a set of already-authorized credentialIds,
+ * for the reconnect resync. Unlike `resolveInferenceMaterials`, a credential
+ * that no longer exists or is `revoked` is DROPPED (omitted) rather than
+ * throwing: the resync reflects credential lifecycle, so a dead id is simply
+ * absent from the reconciled delivery and the child evicts it.
+ *
+ * A credential that IS alive but whose material cannot be resolved (its provider
+ * vanished or has no API base URL) is NOT a lifecycle removal, so it throws --
+ * the caller aborts the whole reconcile rather than delivering a partial set
+ * paired with a spurious revoke. A rotated secret is picked up because the row's
+ * current secret is decrypted here.
+ *
+ * Ids are looked up by primary key (globally unique) and come from the
+ * deployment's own persisted delivery, so no re-authorization is performed --
+ * this reflects lifecycle only.
+ */
+export declare function reresolveCurrentMaterials(db: DB["db"], credentialIds: Iterable<string>, credentialCipher: CredentialCipher): Promise<CredentialMaterialEntry[]>;
 /**
  * Resolves a provider by name, walking up the tenant hierarchy.
  * Returns the first match (child shadows parent).
@@ -10,6 +101,7 @@ export declare function resolveProviderByName(db: DB["db"], tenantId: string, na
     updatedAt: Date;
     tenantId: string;
     plugin: string;
+    apiBaseUrl: string | null;
     authorizationUrl: string | null;
     tokenUrl: string | null;
     userInfoUrl: string | null;
@@ -45,9 +137,9 @@ export declare function resolveCredentialByName(db: DB["db"], tenantId: string,
     expiresAt: Date | null;
     providerId: string;
     tenantId: string;
-    status: "active" | "expired" | "revoked" | "error";
-    description: string | null;
+    status: "active" | "error" | "expired" | "revoked";
     principalId: string | null;
+    description: string | null;
     scopes: string[] | null;
     metadata: unknown;
     oauthClientId: string | null;
@@ -67,9 +159,9 @@ export declare function resolveCredentialById(db: DB["db"], tenantId: string, cr
     expiresAt: Date | null;
     providerId: string;
     tenantId: string;
-    status: "active" | "expired" | "revoked" | "error";
-    description: string | null;
+    status: "active" | "error" | "expired" | "revoked";
     principalId: string | null;
+    description: string | null;
     scopes: string[] | null;
     metadata: unknown;
     oauthClientId: string | null;
@@ -90,21 +182,90 @@ type CredentialRequirement = {
  * catalog, not this path).
  */
 export declare function resolveCredentialRequirement(db: DB["db"], tenantId: string, requirement: CredentialRequirement, creatorPrincipalId: string | null, invokerPrincipalId: string | null): Promise<{
-    id: string;
-    name: string;
-    createdAt: Date;
-    updatedAt: Date;
-    expiresAt: Date | null;
-    providerId: string;
-    tenantId: string;
-    status: "active" | "expired" | "revoked" | "error";
-    description: string | null;
-    principalId: string | null;
-    scopes: string[] | null;
-    metadata: unknown;
-    oauthClientId: string | null;
-    type: "api_key" | "oauth_token" | "certificate" | "other";
-    secret: string;
-    refreshSecret: string | null;
+    credential: {
+        id: string;
+        name: string;
+        createdAt: Date;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        providerId: string;
+        tenantId: string;
+        status: "active" | "error" | "expired" | "revoked";
+        principalId: string | null;
+        description: string | null;
+        scopes: string[] | null;
+        metadata: unknown;
+        oauthClientId: string | null;
+        type: "api_key" | "oauth_token" | "certificate" | "other";
+        secret: string;
+        refreshSecret: string | null;
+    };
+    provider: {
+        id: string;
+        name: string;
+        createdAt: Date;
+        updatedAt: Date;
+        tenantId: string;
+        plugin: string;
+        apiBaseUrl: string | null;
+        authorizationUrl: string | null;
+        tokenUrl: string | null;
+        userInfoUrl: string | null;
+        scopes: string[] | null;
+        metadata: unknown;
+    };
 } | null>;
+/**
+ * A launch-blocking CONFIGURATION failure for one binding: a binding no
+ * credential resolves, a provider with no API origin (can't pin an http
+ * handle), or an ambiguous match. Distinct from an infrastructure failure (a DB
+ * read fault), which `buildCredentialDelivery` THROWS rather than returning --
+ * so a caller never mistakes a transient fault for revocation.
+ */
+export type CredentialDeliveryFailure = {
+    code: "unresolved" | "no_origin" | "ambiguous";
+    binding: {
+        provider: string;
+        package: string;
+        handle: string;
+    };
+    message: string;
+};
+/**
+ * Outcome of `buildCredentialDelivery`. `ok: true` carries the material +
+ * descriptors delivered to the tools; `delivery` is `undefined` when there are
+ * no bindings. `ok: false` carries the first launch-blocking configuration
+ * failure for the caller to map to a fail-closed response.
+ */
+export type BuildCredentialDeliveryResult = {
+    ok: true;
+    delivery: CredentialDelivery | undefined;
+} | {
+    ok: false;
+    reason: CredentialDeliveryFailure;
+};
+/**
+ * Resolve a definition's credential bindings into the material + per-handle
+ * descriptors delivered to its tools. Each credential's secret is decrypted
+ * once, keyed by credentialId (a credential backing several handles is
+ * decrypted once).
+ *
+ * This path delivers credential material only; it does not mint, stamp, or
+ * carry any grant. Credential-use authorization is enforced by a separate grant
+ * layer.
+ *
+ * The workflow-deploy path (`deployCodeSourcedWorkflow`) is the only caller
+ * today, using `delivery`. Returning a discriminated result rather than an HTTP
+ * response keeps it safe to call off the request path: a configuration failure
+ * is `ok: false`, and a transient DB read fault THROWS so the caller surfaces it
+ * rather than silently dropping a still-valid credential.
+ */
+export declare function buildCredentialDelivery(args: {
+    db: DB["db"];
+    tenantId: string;
+    bindings: readonly CredentialBinding[];
+    creatorPrincipalId: string | null;
+    invokerPrincipalId: string | null;
+    credentialCipher: CredentialCipher;
+}): Promise<BuildCredentialDeliveryResult>;
 export {};