@intx/db 0.1.2 → 0.2.2

package/dist/connection.js

@@ -0,0 +1,23 @@
+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 }),
+        ...(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) },
+        }),
+    });
+}

package/dist/credential-resolution.d.ts

@@ -0,0 +1,110 @@
+import type { DB } from "./client.js";
+/**
+ * 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;
+    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" | "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;
+} | 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" | "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;
+} | 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<{
+    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;
+} | null>;
+export {};

package/dist/credential-resolution.js

@@ -0,0 +1,116 @@
+import { eq, and, isNull } from "drizzle-orm";
+import { credential } from "./schema/credentials.js";
+import { oauthClient } from "./schema/oauth-clients.js";
+import { provider } from "./schema/providers.js";
+import { getAncestorChain } from "./tenant-hierarchy.js";
+/**
+ * Resolves a provider by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveProviderByName(db, tenantId, name) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.provider.findFirst({
+            where: and(eq(provider.tenantId, tid), eq(provider.name, name)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves an OAuth client for a provider, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveOAuthClient(db, tenantId, providerId) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.oauthClient.findFirst({
+            where: and(eq(oauthClient.tenantId, tid), eq(oauthClient.providerId, providerId)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves a credential by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveCredentialByName(db, tenantId, name) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.credential.findFirst({
+            where: and(eq(credential.tenantId, tid), eq(credential.name, name)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves a credential by ID, validating that it belongs to the
+ * given tenant or one of its ancestors.
+ */
+export async function resolveCredentialById(db, tenantId, credentialId) {
+    const row = await db.query.credential.findFirst({
+        where: eq(credential.id, credentialId),
+    });
+    if (!row)
+        return null;
+    const chain = await getAncestorChain(db, tenantId);
+    if (!chain.includes(row.tenantId))
+        return null;
+    return row;
+}
+/**
+ * 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 async function resolveCredentialRequirement(db, tenantId, requirement, creatorPrincipalId, invokerPrincipalId) {
+    const resolvedProvider = await resolveProviderByName(db, tenantId, requirement.providerName);
+    if (!resolvedProvider)
+        return null;
+    const chain = await getAncestorChain(db, tenantId);
+    const principalFilter = requirement.source === "tenant"
+        ? null
+        : requirement.source === "creator"
+            ? creatorPrincipalId
+            : invokerPrincipalId;
+    for (const tid of chain) {
+        const conditions = [
+            eq(credential.tenantId, tid),
+            eq(credential.providerId, resolvedProvider.id),
+            eq(credential.status, "active"),
+        ];
+        if (principalFilter === null) {
+            conditions.push(isNull(credential.principalId));
+        }
+        else if (principalFilter) {
+            conditions.push(eq(credential.principalId, principalFilter));
+        }
+        if (requirement.name) {
+            conditions.push(eq(credential.name, requirement.name));
+        }
+        const rows = await db.query.credential.findMany({
+            where: and(...conditions),
+        });
+        const matching = rows.filter((row) => {
+            if (!requirement.scopes || requirement.scopes.length === 0)
+                return true;
+            const rowScopes = row.scopes ?? [];
+            return requirement.scopes.every((s) => rowScopes.includes(s));
+        });
+        const [sole] = matching;
+        if (matching.length === 1 && sole)
+            return sole;
+        if (matching.length > 1) {
+            throw new Error(`Ambiguous credential match: ${matching.length} credentials match ` +
+                `provider=${requirement.providerName} source=${requirement.source} ` +
+                `in tenant ${tid}. Specify a name to disambiguate.`);
+        }
+    }
+    return null;
+}

package/dist/grant-store.d.ts

@@ -0,0 +1,3 @@
+import type { GrantStore } from "@intx/types/authz";
+import type { DB } from "./client.js";
+export declare function createGrantStore(db: DB["db"]): GrantStore;

package/dist/grant-store.js

@@ -0,0 +1,37 @@
+import { eq, and, or, isNull, gt, inArray } from "drizzle-orm";
+import { grant } from "./schema/grants.js";
+import { principalRole } from "./schema/roles.js";
+import { parseGrantRow } from "./parse-row.js";
+function toGrantRule(row) {
+    const parsed = parseGrantRow(row);
+    return {
+        id: parsed.id,
+        resource: parsed.resource,
+        action: parsed.action,
+        effect: parsed.effect,
+        origin: parsed.origin,
+        conditions: parsed.conditions,
+        expiresAt: parsed.expiresAt,
+        roleId: parsed.roleId,
+        principalId: parsed.principalId,
+    };
+}
+export function createGrantStore(db) {
+    return {
+        async collectGrants(principalId, tenantId) {
+            const roleAssignments = await db.query.principalRole.findMany({
+                where: eq(principalRole.principalId, principalId),
+            });
+            const roleIds = roleAssignments.map((a) => a.roleId);
+            const now = new Date();
+            const ownership = [eq(grant.principalId, principalId)];
+            if (roleIds.length > 0) {
+                ownership.push(inArray(grant.roleId, roleIds));
+            }
+            const rows = await db.query.grant.findMany({
+                where: and(eq(grant.tenantId, tenantId), or(...ownership), or(isNull(grant.expiresAt), gt(grant.expiresAt, now))),
+            });
+            return rows.map(toGrantRule);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createDB, type DB } from "./client.js";
+export { pgErrorCode, PG_UNIQUE_VIOLATION, PG_FOREIGN_KEY_VIOLATION, } from "./pg-error.js";
+export type { DBConfig } from "./config.js";
+export { runMigrations, dropSchema } from "./migrate.js";
+export { createGrantStore } from "./grant-store.js";
+export { getAncestorChain, getDescendantTenants } from "./tenant-hierarchy.js";
+export { resolveActivePrice, type ModelPricingRow } from "./pricing.js";
+export { resolveProviderByName, resolveOAuthClient, resolveCredentialByName, resolveCredentialById, resolveCredentialRequirement, } from "./credential-resolution.js";
+export { resolveAssetByName, resolveAssetById, listAssetsForTenant, type AssetRow, type AssetWithOrigin, } from "./asset-resolution.js";
+export { listVisibleModels, listVisibleProviders, listVisibleOfferings, type ModelRow, type ModelProviderRow, type ModelOfferingRow, type Origin, type VisibleModel, type VisibleProvider, type ResolvedOffering, } from "./catalog-resolution.js";
+export { resolveModelSources, resolveInstanceModelSources, type CatalogSourceResolution, type SourceSkip, } from "./model-source-resolution.js";
+export { parseAgentRow, parseAgentVersionRow, parseGrantRow, parseOfferingRow, parseCredentialRow, parseProviderRow, parseTenantRow, parseWalletRow, parseTransactionRow, parseOAuthClientRow, parseGitTokenRow, parseTurnPartType, } from "./parse-row.js";
+export * as schema from "./schema/index.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { createDB } from "./client.js";
+export { pgErrorCode, PG_UNIQUE_VIOLATION, PG_FOREIGN_KEY_VIOLATION, } from "./pg-error.js";
+export { runMigrations, dropSchema } from "./migrate.js";
+export { createGrantStore } from "./grant-store.js";
+export { getAncestorChain, getDescendantTenants } from "./tenant-hierarchy.js";
+export { resolveActivePrice } from "./pricing.js";
+export { resolveProviderByName, resolveOAuthClient, resolveCredentialByName, resolveCredentialById, resolveCredentialRequirement, } from "./credential-resolution.js";
+export { resolveAssetByName, resolveAssetById, listAssetsForTenant, } from "./asset-resolution.js";
+export { listVisibleModels, listVisibleProviders, listVisibleOfferings, } from "./catalog-resolution.js";
+export { resolveModelSources, resolveInstanceModelSources, } from "./model-source-resolution.js";
+export { parseAgentRow, parseAgentVersionRow, parseGrantRow, parseOfferingRow, parseCredentialRow, parseProviderRow, parseTenantRow, parseWalletRow, parseTransactionRow, parseOAuthClientRow, parseGitTokenRow, parseTurnPartType, } from "./parse-row.js";
+export * as schema from "./schema/index.js";

package/dist/migrate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rewrite drizzle-generated schema-qualified references like
+ * `REFERENCES "public"."<table>"` so they point at the target
+ * schema. The pattern matches `"public".` only when followed by
+ * another quoted identifier, leaving bare `"public"` inside string
+ * literals alone.
+ */
+export declare function rewriteSchemaQualifiedReferences(sql: string, schemaIdent: string): string;
+/**
+ * Apply the drizzle-generated migration SQL into the given postgres
+ * schema. The schema is created if absent; nothing else is dropped.
+ *
+ * The migration source files reference the destination schema
+ * literally (e.g. `"public"."user"` in FK constraints). To make the
+ * same source apply cleanly into an arbitrary schema, we substitute
+ * the literal token `"public"` with the quoted target schema before
+ * executing each file. This is a textual substitution rather than a
+ * postgres-side `search_path` trick because the FK references are
+ * fully qualified; `search_path` would not redirect them.
+ *
+ * The substitution is bounded: the migration source is
+ * machine-generated and never contains the string `"public"` other
+ * than in schema-qualified identifiers, so there is no ambiguity to
+ * worry about. The substitution is a no-op when the target schema is
+ * literally `public`, which is the common case.
+ */
+export declare function runMigrations(configRaw: unknown, options: {
+    schema: string;
+}): Promise<void>;
+/**
+ * Drop the given schema along with everything in it. Used by the
+ * integration-test harness to tear down per-test schemas.
+ */
+export declare function dropSchema(configRaw: unknown, options: {
+    schema: string;
+}): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,135 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { type } from "arktype";
+import postgres from "postgres";
+import { DBConfig } from "./config.js";
+// Resolution of the migrations directory: the package layout pins
+// the drizzle-generated SQL at `<pkgRoot>/migrations`. This file
+// lives at `<pkgRoot>/src/migrate.ts`, so the directory is one level
+// up from `__dirname`. Resolving via `import.meta` keeps the runtime
+// honest about where it is reading SQL from instead of relying on a
+// cwd-relative path that breaks under callers that change `cwd`.
+const MIGRATIONS_DIR = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "migrations");
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Rewrite drizzle-generated schema-qualified references like
+ * `REFERENCES "public"."<table>"` so they point at the target
+ * schema. The pattern matches `"public".` only when followed by
+ * another quoted identifier, leaving bare `"public"` inside string
+ * literals alone.
+ */
+export function rewriteSchemaQualifiedReferences(sql, schemaIdent) {
+    return sql.replace(/"public"\.(?=")/g, `${schemaIdent}.`);
+}
+/**
+ * Construct the single-connection postgres client used by the
+ * migration and teardown entry points. Both paths share the same SSL
+ * passthrough and suppress NOTICE-level diagnostics (cascade reports,
+ * "schema already exists") that postgres.js logs by default but are
+ * informational only in this harness context. The optional `searchPath`
+ * pins `search_path` on connection-open so unqualified `CREATE TABLE`
+ * statements land in the caller's schema.
+ */
+function createMigrationClient(config, searchPath) {
+    return postgres({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        max: 1,
+        onnotice: () => undefined,
+        ...(config.ssl !== undefined && { ssl: config.ssl }),
+        ...(searchPath !== undefined && {
+            connection: { search_path: searchPath },
+        }),
+    });
+}
+/**
+ * Apply the drizzle-generated migration SQL into the given postgres
+ * schema. The schema is created if absent; nothing else is dropped.
+ *
+ * The migration source files reference the destination schema
+ * literally (e.g. `"public"."user"` in FK constraints). To make the
+ * same source apply cleanly into an arbitrary schema, we substitute
+ * the literal token `"public"` with the quoted target schema before
+ * executing each file. This is a textual substitution rather than a
+ * postgres-side `search_path` trick because the FK references are
+ * fully qualified; `search_path` would not redirect them.
+ *
+ * The substitution is bounded: the migration source is
+ * machine-generated and never contains the string `"public"` other
+ * than in schema-qualified identifiers, so there is no ambiguity to
+ * worry about. The substitution is a no-op when the target schema is
+ * literally `public`, which is the common case.
+ */
+export async function runMigrations(configRaw, options) {
+    const config = DBConfig(configRaw);
+    if (config instanceof type.errors) {
+        throw new Error(`Invalid database config: ${config.summary}`);
+    }
+    const { schema } = options;
+    if (schema.length === 0) {
+        throw new Error("runMigrations: schema name must not be empty");
+    }
+    const schemaIdent = quoteIdentifier(schema);
+    // Pin search_path on the migration connection so unqualified
+    // `CREATE TABLE "name"` statements land in the target schema.
+    // The FK references in the source SQL are already schema-qualified
+    // (`"public"."user"`); we rewrite those to the target schema
+    // below. Together these two mechanisms route every object the
+    // migration touches into the caller's schema.
+    const sql = createMigrationClient(config, schemaIdent);
+    try {
+        // The CREATE SCHEMA must run on a connection that does not
+        // require the schema to already exist for search_path to be
+        // applied. postgres.js sets the GUC after connection-open, so
+        // CREATE SCHEMA IF NOT EXISTS here is the first statement and
+        // creates the schema before search_path matters.
+        await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${schemaIdent}`);
+        const files = (await readdir(MIGRATIONS_DIR))
+            .filter((f) => f.endsWith(".sql"))
+            .sort();
+        if (files.length === 0) {
+            throw new Error(`runMigrations: no .sql files found in ${MIGRATIONS_DIR}`);
+        }
+        for (const file of files) {
+            const raw = await readFile(path.join(MIGRATIONS_DIR, file), "utf-8");
+            const rendered = rewriteSchemaQualifiedReferences(raw, schemaIdent);
+            // drizzle emits multi-statement files separated by its own
+            // statement-breakpoint marker. Split on it and execute each
+            // statement individually so a syntax error in one statement
+            // surfaces with the right context.
+            const statements = rendered
+                .split("--> statement-breakpoint")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            for (const stmt of statements) {
+                await sql.unsafe(stmt);
+            }
+        }
+    }
+    finally {
+        await sql.end();
+    }
+}
+/**
+ * Drop the given schema along with everything in it. Used by the
+ * integration-test harness to tear down per-test schemas.
+ */
+export async function dropSchema(configRaw, options) {
+    const config = DBConfig(configRaw);
+    if (config instanceof type.errors) {
+        throw new Error(`Invalid database config: ${config.summary}`);
+    }
+    const sql = createMigrationClient(config);
+    try {
+        const schemaIdent = quoteIdentifier(options.schema);
+        await sql.unsafe(`DROP SCHEMA IF EXISTS ${schemaIdent} CASCADE`);
+    }
+    finally {
+        await sql.end();
+    }
+}

package/dist/model-source-resolution.d.ts

@@ -0,0 +1,69 @@
+import { type ModelRequirement, type ProviderPreference } from "@intx/types";
+import type { InferenceSource } from "@intx/types/runtime";
+import type { DB } from "./client.js";
+/**
+ * Why a single offering could not be turned into a launchable source.
+ * `wallet_backed` providers are storable in the catalog but not launchable
+ * in this credential-backed-only release.
+ */
+export type SourceSkip = {
+    reason: "wallet_backed";
+    provider: string;
+} | {
+    reason: "credential_unresolved";
+    provider: string;
+} | {
+    reason: "provider_misconfigured";
+    provider: string;
+};
+/**
+ * Outcome of resolving an agent's model requirements to an ordered set of
+ * inference sources. The order is the routing order: the head is the
+ * default, the tail is the failover chain.
+ *
+ * `model_unavailable.skips` enumerates the offerings that were eligible for
+ * the model but could not produce a launchable source (wallet-backed, or an
+ * unresolvable credential). It is empty when no offering was eligible at all
+ * — the model is absent from the tenant catalog, or the capability and
+ * preference filters excluded every offering — a case the launch path can
+ * distinguish from a populated `skips` when explaining the failure.
+ */
+export type CatalogSourceResolution = {
+    ok: true;
+    sources: InferenceSource[];
+} | {
+    ok: false;
+    reason: "no_requirements";
+} | {
+    ok: false;
+    reason: "model_unavailable";
+    model: string;
+    skips: SourceSkip[];
+};
+/**
+ * Resolves an agent's model requirements against the tenant catalog into an
+ * ordered `InferenceSource[]` for the harness.
+ *
+ * For each requirement, the tenant-visible offerings for the named model are
+ * filtered by the required capabilities, ordered by catalog priority, then
+ * reordered by the creator preference and finally the invoker preference
+ * (invoker preferences key on the canonical model name). Each surviving
+ * offering is resolved to a credential-backed source; offerings that cannot
+ * produce one are skipped. A required model that yields no source makes the
+ * agent unlaunchable.
+ */
+export declare function resolveModelSources(db: DB["db"], tenantId: string, requirements: ModelRequirement[], opts?: {
+    invokerPreferences?: Record<string, ProviderPreference>;
+}): Promise<CatalogSourceResolution>;
+/**
+ * Resolves the ordered sources for a running instance from persisted state:
+ * the agent definition's model requirements and the invoker's launch-time
+ * preferences stored on the instance row. Launch, credential-rotation push,
+ * and sidecar reconnect all resolve through this, so a running instance's
+ * source list is a pure function of persisted state — re-resolution
+ * reproduces the launch ordering, including the invoker's reorder/restrict.
+ */
+export declare function resolveInstanceModelSources(db: DB["db"], tenantId: string, instance: {
+    agentId: string;
+    modelPreferences: unknown;
+}): Promise<CatalogSourceResolution>;