@intx/db 0.1.2 → 0.3.0

package/dist/catalog-resolution.js

@@ -0,0 +1,151 @@
+import { eq } from "drizzle-orm";
+import { model, modelOffering, modelProvider } from "./schema/catalog.js";
+import { getAncestorChain } from "./tenant-hierarchy.js";
+/**
+ * Lists the models visible to a tenant, walking the ancestor chain
+ * leaf-to-root. The first row to claim a `canonicalName` wins (a
+ * descendant shadows an ancestor). A winning row marked `disabled`
+ * suppresses the name for the tenant and its descendants, so it is
+ * omitted from the result.
+ *
+ * Scoping derives entirely from the ancestor chain; the denormalized
+ * `tenantId` on referencing rows is never the scoping authority.
+ */
+export async function listVisibleModels(db, tenantId) {
+    const chain = await getAncestorChain(db, tenantId);
+    const byKey = new Map();
+    for (const tid of chain) {
+        const rows = await db.query.model.findMany({
+            where: eq(model.tenantId, tid),
+        });
+        for (const row of rows) {
+            if (byKey.has(row.canonicalName))
+                continue;
+            byKey.set(row.canonicalName, {
+                row,
+                origin: { tenantId: tid, direct: tid === tenantId },
+            });
+        }
+    }
+    return Array.from(byKey.values()).filter((entry) => !entry.row.disabled);
+}
+/**
+ * Lists the model providers visible to a tenant. Same leaf-to-root
+ * shadowing and disable-suppression as {@link listVisibleModels},
+ * keyed on the provider `name`.
+ */
+export async function listVisibleProviders(db, tenantId) {
+    const chain = await getAncestorChain(db, tenantId);
+    const byKey = new Map();
+    for (const tid of chain) {
+        const rows = await db.query.modelProvider.findMany({
+            where: eq(modelProvider.tenantId, tid),
+        });
+        for (const row of rows) {
+            if (byKey.has(row.name))
+                continue;
+            byKey.set(row.name, {
+                row,
+                origin: { tenantId: tid, direct: tid === tenantId },
+            });
+        }
+    }
+    return Array.from(byKey.values()).filter((entry) => !entry.row.disabled);
+}
+// A NUL separator cannot collide: it never appears in a Postgres `text`
+// value, so distinct (canonicalName, providerName) pairs never map to the
+// same composite key even when a name contains spaces or punctuation.
+const KEY_SEPARATOR = "\u0000";
+function offeringKey(canonicalName, providerName) {
+    return `${canonicalName}${KEY_SEPARATOR}${providerName}`;
+}
+/**
+ * Lists the offerings visible to a tenant.
+ *
+ * An offering's cross-tenant identity is `(model canonicalName, provider
+ * name)`, not its row ids — a child that shadows a model or provider must
+ * shadow the inherited offerings for that pairing. So each offering's
+ * `modelId`/`providerId` are dereferenced to their canonical identity
+ * (across every tenant in the chain, since the referents may be inherited)
+ * and the chain is walked leaf-to-root with that identity as the key:
+ * first wins, `disabled` suppresses.
+ *
+ * Visibility then cascades from the model/provider passes: an offering
+ * survives only if both its model `canonicalName` and provider `name` are
+ * themselves visible. Disabling a provider therefore removes every
+ * inherited offering against it, even offerings the disabling tenant never
+ * touched. The cascade is applied after the model and provider passes
+ * complete, never interleaved.
+ *
+ * The returned `model`/`provider` are the entries *visible to the
+ * resolving tenant* (resolved by canonicalName/name), so shadowed
+ * configuration applies to inherited offerings.
+ */
+export async function listVisibleOfferings(db, tenantId) {
+    const chain = await getAncestorChain(db, tenantId);
+    const visibleModels = new Map((await listVisibleModels(db, tenantId)).map((m) => [
+        m.row.canonicalName,
+        m,
+    ]));
+    const visibleProviders = new Map((await listVisibleProviders(db, tenantId)).map((p) => [p.row.name, p]));
+    // Dereference offering referents to their canonical identity. The
+    // referents may live on any tenant in the chain (an offering can be
+    // inherited), so the id maps span every tenant, including rows that are
+    // themselves shadowed or disabled — the maps answer "what does this id
+    // name", and the cascade below decides visibility.
+    const modelNameById = new Map();
+    const providerNameById = new Map();
+    for (const tid of chain) {
+        for (const row of await db.query.model.findMany({
+            where: eq(model.tenantId, tid),
+        })) {
+            modelNameById.set(row.id, row.canonicalName);
+        }
+        for (const row of await db.query.modelProvider.findMany({
+            where: eq(modelProvider.tenantId, tid),
+        })) {
+            providerNameById.set(row.id, row.name);
+        }
+    }
+    const byKey = new Map();
+    for (const tid of chain) {
+        const rows = await db.query.modelOffering.findMany({
+            where: eq(modelOffering.tenantId, tid),
+        });
+        for (const row of rows) {
+            const canonicalName = modelNameById.get(row.modelId);
+            const providerName = providerNameById.get(row.providerId);
+            if (canonicalName === undefined || providerName === undefined)
+                continue;
+            const key = offeringKey(canonicalName, providerName);
+            if (byKey.has(key))
+                continue;
+            byKey.set(key, {
+                row,
+                origin: { tenantId: tid, direct: tid === tenantId },
+            });
+        }
+    }
+    const resolved = [];
+    for (const { row, origin } of byKey.values()) {
+        if (row.disabled)
+            continue;
+        const canonicalName = modelNameById.get(row.modelId);
+        const providerName = providerNameById.get(row.providerId);
+        if (canonicalName === undefined || providerName === undefined)
+            continue;
+        const visibleModel = visibleModels.get(canonicalName);
+        const visibleProvider = visibleProviders.get(providerName);
+        // Cascade: the offering survives only if its model and provider are
+        // both visible (a disabled model or provider removes its offerings).
+        if (visibleModel === undefined || visibleProvider === undefined)
+            continue;
+        resolved.push({
+            offering: row,
+            model: visibleModel.row,
+            provider: visibleProvider.row,
+            origin,
+        });
+    }
+    return resolved;
+}

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import * as schema from "./schema/index.js";
+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>;
+    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

@@ -0,0 +1,18 @@
+import { type } from "arktype";
+import { drizzle } from "drizzle-orm/postgres-js";
+import { DBConfig } from "./config.js";
+import { createConnection } from "./connection.js";
+import * as schema from "./schema/index.js";
+export function createDB(raw) {
+    const config = DBConfig(raw);
+    if (config instanceof type.errors) {
+        throw new Error(`Invalid database config: ${config.summary}`);
+    }
+    const sql = createConnection(config);
+    const db = drizzle(sql, { schema });
+    return {
+        db,
+        transaction: db.transaction.bind(db),
+        close: () => sql.end(),
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export declare const DBConfig: import("arktype/internal/variants/object.ts").ObjectType<{
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    ssl?: boolean;
+    max?: number;
+    schema?: string;
+}, {}>;
+export type DBConfig = typeof DBConfig.infer;

package/dist/config.js

@@ -0,0 +1,16 @@
+import { type } from "arktype";
+export const DBConfig = type({
+    host: "string",
+    port: "number.integer > 0",
+    user: "string",
+    password: "string",
+    database: "string",
+    "ssl?": "boolean",
+    "max?": "number.integer > 0",
+    // 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
+    // hub a dedicated, droppable schema. When unset, the connection uses
+    // postgres' default `search_path` (which begins with `public`).
+    "schema?": "string",
+});

package/dist/connection.d.ts

@@ -0,0 +1,3 @@
+import postgres from "postgres";
+import type { DBConfig } from "./config.js";
+export declare function createConnection(config: DBConfig): postgres.Sql<{}>;

package/dist/connection.js

@@ -0,0 +1,26 @@
+import postgres from "postgres";
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export function createConnection(config) {
+    return postgres({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        max: config.max ?? 10,
+        ...(config.ssl !== undefined && { ssl: config.ssl }),
+        connection: {
+            TimeZone: "UTC",
+            ...(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

@@ -0,0 +1,222 @@
+import type { CredentialBinding, CredentialCipher } from "@intx/types";
+import type { CredentialDelivery } 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);
+}
+/**
+ * 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";
+    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;
+} | null>;
+/**
+ * Resolves a provider by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export declare function resolveProviderByName(db: DB["db"], tenantId: string, name: string): Promise<{
+    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>;
+/**
+ * Resolves an OAuth client for a provider, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export declare function resolveOAuthClient(db: DB["db"], tenantId: string, providerId: string): Promise<{
+    id: string;
+    name: string;
+    createdAt: Date;
+    updatedAt: Date;
+    providerId: string;
+    tenantId: string;
+    metadata: unknown;
+    clientId: string;
+    clientSecret: string;
+    redirectUris: string[] | null;
+    defaultScopes: string[] | null;
+} | null>;
+/**
+ * Resolves a credential by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export declare function resolveCredentialByName(db: DB["db"], tenantId: string, name: string): Promise<{
+    id: string;
+    name: string;
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date | null;
+    providerId: string;
+    tenantId: string;
+    status: "active" | "error" | "expired" | "revoked";
+    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;
+} | null>;
+/**
+ * Resolves a credential by ID, validating that it belongs to the
+ * given tenant or one of its ancestors.
+ */
+export declare function resolveCredentialById(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";
+    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;
+} | null>;
+type CredentialRequirement = {
+    providerName: string;
+    scopes?: string[];
+    source: "tenant" | "creator" | "invoker";
+    name?: string;
+};
+/**
+ * Resolves a credential matching an agent definition requirement.
+ * Used at agent launch time by the control plane to satisfy a definition's
+ * tool and integration credentials (inference sources resolve through the
+ * catalog, not this path).
+ */
+export declare function resolveCredentialRequirement(db: DB["db"], tenantId: string, requirement: CredentialRequirement, creatorPrincipalId: string | null, invokerPrincipalId: string | null): Promise<{
+    credential: {
+        id: string;
+        name: string;
+        createdAt: Date;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        providerId: string;
+        tenantId: string;
+        status: "active" | "error" | "expired" | "revoked";
+        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;
+    };
+    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 {};