@intx/db 0.1.2

package/src/grant-store.ts

@@ -0,0 +1,51 @@
+import { eq, and, or, isNull, gt, inArray } from "drizzle-orm";
+
+import type { GrantRule, GrantStore } from "@intx/types/authz";
+
+import type { DB } from "./client";
+import { grant } from "./schema/grants";
+import { principalRole } from "./schema/roles";
+import { parseGrantRow } from "./parse-row";
+
+function toGrantRule(row: typeof grant.$inferSelect): GrantRule {
+  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: DB["db"]): GrantStore {
+  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/src/index.ts

@@ -0,0 +1,32 @@
+export { createDB, type DB } from "./client";
+export type { DBConfig } from "./config";
+export { runMigrations, dropSchema } from "./migrate";
+export { createGrantStore } from "./grant-store";
+export { getAncestorChain } from "./tenant-hierarchy";
+export {
+  resolveProviderByName,
+  resolveOAuthClient,
+  resolveCredentialByName,
+  resolveCredentialById,
+  resolveCredentialRequirement,
+  resolveOneCredential,
+  resolveInstanceSources,
+  type CredentialOutcome,
+  ProviderMetadata,
+} from "./credential-resolution";
+export {
+  parseAgentRow,
+  parseAgentVersionRow,
+  parseGrantRow,
+  parseOfferingRow,
+  parseCredentialRow,
+  parseProviderRow,
+  parseTenantRow,
+  parseWalletRow,
+  parseTransactionRow,
+  parseOAuthClientRow,
+  parseGitTokenRow,
+  parseSidecarStatus,
+  parseTurnPartType,
+} from "./parse-row";
+export * as schema from "./schema";

package/src/migrate.test.ts

@@ -0,0 +1,35 @@
+import { describe, test, expect } from "bun:test";
+
+import { rewriteSchemaQualifiedReferences } from "./migrate";
+
+describe('migration "public" substitution', () => {
+  test("rewrites schema-qualified references", () => {
+    const sql =
+      'ALTER TABLE "x" ADD CONSTRAINT "fk" FOREIGN KEY ("u") REFERENCES "public"."user"("id");';
+    expect(rewriteSchemaQualifiedReferences(sql, '"test_schema"')).toBe(
+      'ALTER TABLE "x" ADD CONSTRAINT "fk" FOREIGN KEY ("u") REFERENCES "test_schema"."user"("id");',
+    );
+  });
+
+  test("leaves bare quoted public in string literals alone", () => {
+    const sql = `INSERT INTO "x" VALUES ('"public"');`;
+    expect(rewriteSchemaQualifiedReferences(sql, '"t"')).toBe(sql);
+  });
+
+  test("substitutes multiple occurrences on a single line", () => {
+    const sql = 'REFERENCES "public"."a"("id"), "public"."b"("id")';
+    expect(rewriteSchemaQualifiedReferences(sql, '"s"')).toBe(
+      'REFERENCES "s"."a"("id"), "s"."b"("id")',
+    );
+  });
+
+  test("no-op when target schema is public", () => {
+    const sql = 'REFERENCES "public"."user"("id")';
+    expect(rewriteSchemaQualifiedReferences(sql, '"public"')).toBe(sql);
+  });
+
+  test("does not match a trailing apostrophe (bare reference)", () => {
+    const sql = `SELECT '"public"' AS literal;`;
+    expect(rewriteSchemaQualifiedReferences(sql, '"s"')).toBe(sql);
+  });
+});

package/src/migrate.ts

@@ -0,0 +1,168 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { type } from "arktype";
+import postgres from "postgres";
+
+import { DBConfig } from "./config";
+
+// 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: string): string {
+  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: string,
+  schemaIdent: string,
+): string {
+  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: DBConfig,
+  searchPath?: string,
+): ReturnType<typeof postgres> {
+  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: unknown,
+  options: { schema: string },
+): Promise<void> {
+  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: unknown,
+  options: { schema: string },
+): Promise<void> {
+  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/src/parse-row.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+
+import { RepoAction } from "@intx/types/sidecar";
+
+import { GitTokenKindValidator, parseGitTokenRow } from "./parse-row";
+import type { gitToken } from "./schema";
+
+type GitTokenRow = typeof gitToken.$inferSelect;
+
+function makeRow(overrides: Partial<GitTokenRow> = {}): GitTokenRow {
+  const now = new Date();
+  return {
+    id: "gtk_0123456789abcdef0123456789abcdef",
+    tenantId: null,
+    userId: "user_alice",
+    principalId: null,
+    name: "laptop",
+    kind: "pat",
+    tokenHashSha256: new Uint8Array(32),
+    resource: "agent-state:ins_test",
+    refPattern: "refs/heads/*",
+    actions: ["receivePack", "createPack", "resolveRef"],
+    expiresAt: new Date("2027-01-01T00:00:00Z"),
+    revokedAt: null,
+    createdAt: now,
+    ...overrides,
+  };
+}
+
+describe("parseGitTokenRow", () => {
+  test("round-trips a personal pat with concrete repo scope", () => {
+    const row = makeRow();
+    const parsed = parseGitTokenRow(row);
+
+    expect(parsed.id).toBe(row.id);
+    expect(parsed.tenantId).toBeNull();
+    expect(parsed.userId).toBe(row.userId);
+    expect(parsed.principalId).toBeNull();
+    expect(parsed.name).toBe(row.name);
+    expect(parsed.kind).toBe("pat");
+    expect(parsed.tokenHashSha256).toBe(row.tokenHashSha256);
+    expect(parsed.actions).toEqual(["receivePack", "createPack", "resolveRef"]);
+    expect(parsed.resource).toBe("agent-state:ins_test");
+    expect(parsed.refPattern).toBe("refs/heads/*");
+    expect(parsed.expiresAt).toBe(row.expiresAt);
+    expect(parsed.revokedAt).toBeNull();
+    expect(parsed.createdAt).toBe(row.createdAt);
+  });
+
+  test("round-trips a tenant-restricted pat", () => {
+    const row = makeRow({
+      tenantId: "tnt_acme",
+      name: "acme-only",
+    });
+    const parsed = parseGitTokenRow(row);
+
+    expect(parsed.kind).toBe("pat");
+    expect(parsed.tenantId).toBe("tnt_acme");
+    expect(parsed.principalId).toBeNull();
+  });
+
+  test("round-trips a tenant-bound svc token", () => {
+    const row = makeRow({
+      kind: "svc",
+      tenantId: "tnt_acme",
+      principalId: "prn_tenant_user",
+      name: "ci-runner",
+      actions: ["createPack", "resolveRef"],
+      resource: "asset:def_skill_xyz",
+      refPattern: "refs/tags/v*",
+    });
+    const parsed = parseGitTokenRow(row);
+
+    expect(parsed.kind).toBe("svc");
+    expect(parsed.tenantId).toBe("tnt_acme");
+    expect(parsed.principalId).toBe("prn_tenant_user");
+    expect(parsed.actions).toEqual(["createPack", "resolveRef"]);
+    expect(parsed.resource).toBe("asset:def_skill_xyz");
+    expect(parsed.refPattern).toBe("refs/tags/v*");
+  });
+
+  test("preserves revokedAt for soft-revoked rows", () => {
+    const revoked = new Date("2026-01-15T00:00:00Z");
+    const row = makeRow({ revokedAt: revoked });
+    const parsed = parseGitTokenRow(row);
+
+    expect(parsed.revokedAt).toBe(revoked);
+  });
+
+  test("preserves expiresAt", () => {
+    const expires = new Date("2027-01-01T00:00:00Z");
+    const row = makeRow({ expiresAt: expires });
+    const parsed = parseGitTokenRow(row);
+
+    expect(parsed.expiresAt).toBe(expires);
+  });
+
+  test("rejects an unknown kind", () => {
+    expect(() => GitTokenKindValidator.assert("rogue")).toThrow();
+  });
+
+  test("rejects an unknown action in the actions array", () => {
+    expect(() =>
+      RepoAction.array().assert(["receivePack", "fly-the-helicopter"]),
+    ).toThrow();
+  });
+
+  test("accepts an empty actions array", () => {
+    const row = makeRow({ actions: [] });
+    const parsed = parseGitTokenRow(row);
+    expect(parsed.actions).toEqual([]);
+  });
+});

package/src/parse-row.ts

@@ -0,0 +1,185 @@
+import { type } from "arktype";
+
+import {
+  CredentialRequirement,
+  GrantRequirement,
+  grantEffects,
+  grantOrigins,
+  sidecarStatuses,
+} from "@intx/types";
+import { RepoAction } from "@intx/types/sidecar";
+
+import type {
+  agent,
+  agentVersion,
+  credential,
+  gitToken,
+  grant,
+  oauthClient,
+  offering,
+  provider,
+  tenant,
+  transaction,
+  turnPart,
+  wallet,
+} from "./schema";
+
+const JSONObject = type("Record<string, unknown>");
+
+const GrantEffectValidator = type.enumerated(...grantEffects);
+const GrantOriginValidator = type.enumerated(...grantOrigins);
+
+const agentVersionStatuses = ["active", "inactive", "failed"] as const;
+const AgentVersionStatusValidator = type.enumerated(...agentVersionStatuses);
+
+const credentialTypes = [
+  "api_key",
+  "oauth_token",
+  "certificate",
+  "other",
+] as const;
+const CredentialTypeValidator = type.enumerated(...credentialTypes);
+
+const credentialStatuses = ["active", "expired", "revoked", "error"] as const;
+const CredentialStatusValidator = type.enumerated(...credentialStatuses);
+
+const walletBackendTypes = ["crypto", "fiat", "credits"] as const;
+const WalletBackendTypeValidator = type.enumerated(...walletBackendTypes);
+
+const transactionDirections = ["inbound", "outbound"] as const;
+const TransactionDirectionValidator = type.enumerated(...transactionDirections);
+
+const transactionStatuses = ["pending", "completed", "failed"] as const;
+const TransactionStatusValidator = type.enumerated(...transactionStatuses);
+
+const SidecarStatusValidator = type.enumerated(...sidecarStatuses);
+
+const gitTokenKinds = ["pat", "svc"] as const;
+export const GitTokenKindValidator = type.enumerated(...gitTokenKinds);
+
+const turnPartTypes = [
+  "text",
+  "reasoning",
+  "tool",
+  "file",
+  "error",
+  "refusal",
+  "step-start",
+  "step-finish",
+  "snapshot",
+  "patch",
+] as const;
+const TurnPartTypeValidator = type.enumerated(...turnPartTypes);
+
+export function parseAgentRow(row: typeof agent.$inferSelect) {
+  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)
+        : null,
+    grantRequirements:
+      row.grantRequirements !== null
+        ? GrantRequirement.array().assert(row.grantRequirements)
+        : null,
+  };
+}
+
+export function parseAgentVersionRow(row: typeof agentVersion.$inferSelect) {
+  return {
+    ...row,
+    status: AgentVersionStatusValidator.assert(row.status),
+  };
+}
+
+export function parseGrantRow(row: typeof grant.$inferSelect) {
+  return {
+    ...row,
+    effect: GrantEffectValidator.assert(row.effect),
+    origin: GrantOriginValidator.assert(row.origin),
+    conditions:
+      row.conditions !== null ? JSONObject.assert(row.conditions) : null,
+  };
+}
+
+export function parseOfferingRow(row: typeof offering.$inferSelect) {
+  return {
+    ...row,
+    pricing: row.pricing !== null ? JSONObject.assert(row.pricing) : null,
+    schema: row.schema !== null ? JSONObject.assert(row.schema) : null,
+  };
+}
+
+export function parseCredentialRow(row: typeof credential.$inferSelect) {
+  return {
+    ...row,
+    type: CredentialTypeValidator.assert(row.type),
+    status: CredentialStatusValidator.assert(row.status),
+    metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+  };
+}
+
+export function parseProviderRow(row: typeof provider.$inferSelect) {
+  return {
+    ...row,
+    metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+  };
+}
+
+export function parseTenantRow(row: typeof tenant.$inferSelect) {
+  return {
+    ...row,
+    config: row.config !== null ? JSONObject.assert(row.config) : null,
+  };
+}
+
+export function parseWalletRow(row: typeof wallet.$inferSelect) {
+  return {
+    ...row,
+    backendType: WalletBackendTypeValidator.assert(row.backendType),
+    config: row.config !== null ? JSONObject.assert(row.config) : null,
+  };
+}
+
+export function parseTransactionRow(row: typeof transaction.$inferSelect) {
+  return {
+    ...row,
+    direction: TransactionDirectionValidator.assert(row.direction),
+    status: TransactionStatusValidator.assert(row.status),
+  };
+}
+
+export function parseOAuthClientRow(row: typeof oauthClient.$inferSelect) {
+  return {
+    ...row,
+    metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+  };
+}
+
+export function parseGitTokenRow(row: typeof gitToken.$inferSelect) {
+  return {
+    ...row,
+    kind: GitTokenKindValidator.assert(row.kind),
+    actions: RepoAction.array().assert(row.actions),
+  };
+}
+
+export function parseSidecarStatus(
+  status: string,
+): "online" | "offline" | "error" {
+  return SidecarStatusValidator.assert(status);
+}
+
+export function parseTurnPartType(
+  partType: string,
+): (typeof turnPart.$inferInsert)["type"] {
+  return TurnPartTypeValidator.assert(partType);
+}

package/src/schema/agent-assets.ts

@@ -0,0 +1,21 @@
+import { pgTable, text, timestamp, unique } from "drizzle-orm/pg-core";
+
+import { agent } from "./agents";
+import { asset } from "./assets";
+
+export const agentAsset = pgTable(
+  "agent_asset",
+  {
+    id: text("id").primaryKey(),
+    agentId: text("agent_id")
+      .notNull()
+      .references(() => agent.id, { onDelete: "cascade" }),
+    assetId: text("asset_id")
+      .notNull()
+      .references(() => asset.id, { onDelete: "cascade" }),
+    ref: text("ref").notNull(),
+    accessMode: text("access_mode").notNull().default("read-only"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (t) => [unique("agent_asset_agent_asset").on(t.agentId, t.assetId)],
+);

package/src/schema/agents.ts

@@ -0,0 +1,49 @@
+import { jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+import { principal } from "./principals";
+import { tenant } from "./tenants";
+
+export const agent = pgTable("agent", {
+  id: text("id").primaryKey(),
+  tenantId: text("tenant_id")
+    .notNull()
+    .references(() => tenant.id, { onDelete: "cascade" }),
+  // Tracks the definition author's principal for resolving source:"creator"
+  // grant requirements at launch. See AUTH.md § Grant Requirements on Definitions.
+  creatorPrincipalId: text("creator_principal_id")
+    .notNull()
+    .references(() => principal.id),
+  name: text("name").notNull(),
+  description: text("description"),
+  systemPrompt: text("system_prompt"),
+  contextConfig: jsonb("context_config"),
+  initialState: jsonb("initial_state"),
+  modelConfig: jsonb("model_config"),
+  capabilities: jsonb("capabilities"),
+  credentialRequirements: jsonb("credential_requirements"),
+  // Grant requirements manifest — resolved at launch into materialized grants
+  // on the instance principal. See AUTH.md § Grant Requirements on Definitions.
+  grantRequirements: jsonb("grant_requirements"),
+  currentVersion: text("current_version").notNull().default("1"),
+  status: text("status", {
+    enum: ["deployed", "stopped"],
+  })
+    .notNull()
+    .default("deployed"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const agentVersion = pgTable("agent_version", {
+  id: text("id").primaryKey(),
+  agentId: text("agent_id")
+    .notNull()
+    .references(() => agent.id, { onDelete: "cascade" }),
+  version: text("version").notNull(),
+  status: text("status", {
+    enum: ["active", "inactive", "failed"],
+  })
+    .notNull()
+    .default("active"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});

package/src/schema/assets.ts

@@ -0,0 +1,24 @@
+import { pgTable, text, timestamp, unique } from "drizzle-orm/pg-core";
+
+import { principal } from "./principals";
+import { tenant } from "./tenants";
+
+export const asset = pgTable(
+  "asset",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id")
+      .notNull()
+      .references(() => tenant.id, { onDelete: "cascade" }),
+    kind: text("kind").notNull(),
+    name: text("name").notNull(),
+    displayName: text("display_name"),
+    creatorPrincipalId: text("creator_principal_id").references(
+      () => principal.id,
+      { onDelete: "set null" },
+    ),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [unique("asset_tenant_kind_name").on(t.tenantId, t.kind, t.name)],
+);