@agent-native/core 0.86.0 → 0.87.0

package/corpus/templates/analytics/server/db/schema.ts

@@ -234,6 +234,33 @@ export const analyticsAlertIncidents = table("analytics_alert_incidents", {
   orgId: text("org_id"),
 });
 
+/**
+ * Admin-only registry of external agent-native app databases that Analytics can
+ * inspect. Secret values live in app_secrets; this table stores metadata and
+ * secret keys scoped to the active organization.
+ */
+export const analyticsDbAdminConnections = table(
+  "analytics_db_admin_connections",
+  {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    appId: text("app_id"),
+    appUrl: text("app_url"),
+    databaseUrlSecretKey: text("database_url_secret_key").notNull(),
+    databaseAuthTokenSecretKey: text("database_auth_token_secret_key"),
+    createdBy: text("created_by").notNull(),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+    orgId: text("org_id").notNull(),
+  },
+  (connection) => ({
+    orgUpdatedIdx: index("analytics_db_admin_connections_org_updated_idx").on(
+      connection.orgId,
+      connection.updatedAt,
+    ),
+  }),
+);
+
 /**
  * Session replay summaries recorded through the first-party analytics replay
  * endpoint. Raw replay chunks live in session_replay_chunks and are only read

package/corpus/templates/analytics/server/lib/db-admin-connections.ts

@@ -0,0 +1,458 @@
+import { randomUUID } from "node:crypto";
+
+import { createDbExec, getDbExec, type Dialect } from "@agent-native/core/db";
+import type { DbAdminRuntime } from "@agent-native/core/db-admin";
+import { getOrgContext } from "@agent-native/core/org";
+import {
+  deleteAppSecret,
+  getAppSecretMeta,
+  readAppSecret,
+  writeAppSecret,
+} from "@agent-native/core/secrets";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+  getSession,
+  runWithRequestContext,
+} from "@agent-native/core/server";
+import type { H3Event } from "h3";
+
+const CONNECTIONS_TABLE = "analytics_db_admin_connections";
+const SECRET_PREFIX = "analytics-db-admin";
+
+export interface DbAdminConnection {
+  id: string;
+  name: string;
+  appId: string | null;
+  appUrl: string | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  orgId: string;
+  databaseUrlLast4: string | null;
+  hasDatabaseAuthToken: boolean;
+  databaseAuthTokenLast4: string | null;
+}
+
+export interface DbAdminAdminContext {
+  userEmail: string;
+  orgId: string;
+  role: "owner" | "admin";
+}
+
+export class DbAdminConnectionError extends Error {
+  constructor(
+    readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "DbAdminConnectionError";
+  }
+}
+
+function isAdminRole(value: unknown): value is "owner" | "admin" {
+  return value === "owner" || value === "admin";
+}
+
+function readString(
+  row: Record<string, unknown>,
+  ...keys: string[]
+): string | null {
+  for (const key of keys) {
+    const value = row[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return null;
+}
+
+async function resolveOrgRole(
+  userEmail: string,
+  orgId: string,
+): Promise<string | null> {
+  try {
+    const { rows } = await getDbExec().execute({
+      sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+      args: [orgId, userEmail.toLowerCase()],
+    });
+    return readString((rows[0] ?? {}) as Record<string, unknown>, "role");
+  } catch {
+    return null;
+  }
+}
+
+export async function requireDbAdminContextFromRequest(input?: {
+  userEmail?: string;
+  orgId?: string | null;
+}): Promise<DbAdminAdminContext> {
+  const userEmail = input?.userEmail ?? getRequestUserEmail();
+  const orgId = input?.orgId ?? getRequestOrgId() ?? null;
+  if (!userEmail) {
+    throw new DbAdminConnectionError(401, "Sign in to manage app databases.");
+  }
+  if (!orgId) {
+    throw new DbAdminConnectionError(
+      403,
+      "An active organization is required to manage app databases.",
+    );
+  }
+  const role = await resolveOrgRole(userEmail, orgId);
+  if (!isAdminRole(role)) {
+    throw new DbAdminConnectionError(
+      403,
+      "Only organization owners and admins can access connected app databases.",
+    );
+  }
+  return { userEmail, orgId, role };
+}
+
+export async function requireDbAdminContextFromEvent(
+  event: H3Event,
+): Promise<DbAdminAdminContext> {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    throw new DbAdminConnectionError(401, "Sign in to manage app databases.");
+  }
+  const org = await getOrgContext(event).catch(() => null);
+  if (!org?.orgId) {
+    throw new DbAdminConnectionError(
+      403,
+      "An active organization is required to manage app databases.",
+    );
+  }
+  if (!isAdminRole(org.role)) {
+    throw new DbAdminConnectionError(
+      403,
+      "Only organization owners and admins can access connected app databases.",
+    );
+  }
+  return { userEmail: session.email, orgId: org.orgId, role: org.role };
+}
+
+export async function runWithDbAdminEventContext<T>(
+  event: H3Event,
+  fn: (ctx: DbAdminAdminContext) => Promise<T>,
+): Promise<T> {
+  const ctx = await requireDbAdminContextFromEvent(event);
+  return runWithRequestContext(
+    { userEmail: ctx.userEmail, orgId: ctx.orgId },
+    () => fn(ctx),
+  );
+}
+
+function secretKey(connectionId: string, kind: "url" | "auth-token"): string {
+  return `${SECRET_PREFIX}:${connectionId}:${kind}`;
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function normalizeDatabaseUrl(value: unknown): string {
+  const raw = normalizeOptionalString(value);
+  if (!raw) {
+    throw new DbAdminConnectionError(400, "Database URL is required.");
+  }
+  const lower = raw.toLowerCase();
+  if (
+    !lower.startsWith("postgres://") &&
+    !lower.startsWith("postgresql://") &&
+    !lower.startsWith("libsql://")
+  ) {
+    throw new DbAdminConnectionError(
+      400,
+      "Use a Postgres, PostgreSQL, or libSQL database URL.",
+    );
+  }
+  return raw;
+}
+
+function dialectForDatabaseUrl(url: string): Dialect {
+  const lower = url.toLowerCase();
+  if (lower.startsWith("postgres://") || lower.startsWith("postgresql://")) {
+    return "postgres";
+  }
+  return "sqlite";
+}
+
+function rowToConnection(
+  row: Record<string, unknown>,
+  secretMeta: {
+    databaseUrlLast4: string | null;
+    hasDatabaseAuthToken: boolean;
+    databaseAuthTokenLast4: string | null;
+  },
+): DbAdminConnection {
+  return {
+    id: readString(row, "id") ?? "",
+    name: readString(row, "name") ?? "Connected app",
+    appId: readString(row, "appId", "app_id"),
+    appUrl: readString(row, "appUrl", "app_url"),
+    createdBy: readString(row, "createdBy", "created_by") ?? "",
+    createdAt: readString(row, "createdAt", "created_at") ?? "",
+    updatedAt: readString(row, "updatedAt", "updated_at") ?? "",
+    orgId: readString(row, "orgId", "org_id") ?? "",
+    ...secretMeta,
+  };
+}
+
+async function secretMetadata(
+  ctx: DbAdminAdminContext,
+  row: Record<string, unknown>,
+) {
+  const urlSecretKey = readString(
+    row,
+    "databaseUrlSecretKey",
+    "database_url_secret_key",
+  );
+  const authSecretKey = readString(
+    row,
+    "databaseAuthTokenSecretKey",
+    "database_auth_token_secret_key",
+  );
+  const databaseUrlMeta = urlSecretKey
+    ? await getAppSecretMeta({
+        key: urlSecretKey,
+        scope: "org",
+        scopeId: ctx.orgId,
+      })
+    : null;
+  const databaseAuthTokenMeta = authSecretKey
+    ? await getAppSecretMeta({
+        key: authSecretKey,
+        scope: "org",
+        scopeId: ctx.orgId,
+      })
+    : null;
+  return {
+    databaseUrlLast4: databaseUrlMeta?.last4 ?? null,
+    hasDatabaseAuthToken: Boolean(databaseAuthTokenMeta),
+    databaseAuthTokenLast4: databaseAuthTokenMeta?.last4 ?? null,
+  };
+}
+
+export async function listDbAdminConnections(
+  ctx: DbAdminAdminContext,
+): Promise<DbAdminConnection[]> {
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT id, name, app_id AS "appId", app_url AS "appUrl",
+                 database_url_secret_key AS "databaseUrlSecretKey",
+                 database_auth_token_secret_key AS "databaseAuthTokenSecretKey",
+                 created_by AS "createdBy", created_at AS "createdAt",
+                 updated_at AS "updatedAt", org_id AS "orgId"
+          FROM ${CONNECTIONS_TABLE}
+          WHERE org_id = ?
+          ORDER BY updated_at DESC, name ASC`,
+    args: [ctx.orgId],
+  });
+  return Promise.all(
+    rows.map(async (row) =>
+      rowToConnection(
+        row as Record<string, unknown>,
+        await secretMetadata(ctx, row as Record<string, unknown>),
+      ),
+    ),
+  );
+}
+
+export async function saveDbAdminConnection(
+  ctx: DbAdminAdminContext,
+  input: {
+    id?: string | null;
+    name: string;
+    appId?: string | null;
+    appUrl?: string | null;
+    databaseUrl: string;
+    databaseAuthToken?: string | null;
+  },
+): Promise<DbAdminConnection> {
+  const name = normalizeOptionalString(input.name);
+  if (!name)
+    throw new DbAdminConnectionError(400, "Connection name is required.");
+  const databaseUrl = normalizeDatabaseUrl(input.databaseUrl);
+  const authToken = normalizeOptionalString(input.databaseAuthToken);
+  const id = normalizeOptionalString(input.id) ?? randomUUID();
+  const databaseUrlSecretKey = secretKey(id, "url");
+  const databaseAuthTokenSecretKey = authToken
+    ? secretKey(id, "auth-token")
+    : null;
+  const now = new Date().toISOString();
+
+  await writeAppSecret({
+    key: databaseUrlSecretKey,
+    scope: "org",
+    scopeId: ctx.orgId,
+    value: databaseUrl,
+    description: `${name} database URL`,
+  });
+  if (authToken) {
+    await writeAppSecret({
+      key: databaseAuthTokenSecretKey!,
+      scope: "org",
+      scopeId: ctx.orgId,
+      value: authToken,
+      description: `${name} database auth token`,
+    });
+  } else {
+    await deleteAppSecret({
+      key: secretKey(id, "auth-token"),
+      scope: "org",
+      scopeId: ctx.orgId,
+    }).catch(() => false);
+  }
+
+  await getDbExec().execute({
+    sql: `INSERT INTO ${CONNECTIONS_TABLE}
+            (id, name, app_id, app_url, database_url_secret_key,
+             database_auth_token_secret_key, created_by, created_at, updated_at, org_id)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET
+            name = excluded.name,
+            app_id = excluded.app_id,
+            app_url = excluded.app_url,
+            database_url_secret_key = excluded.database_url_secret_key,
+            database_auth_token_secret_key = excluded.database_auth_token_secret_key,
+            updated_at = excluded.updated_at
+          WHERE ${CONNECTIONS_TABLE}.org_id = excluded.org_id`,
+    args: [
+      id,
+      name,
+      normalizeOptionalString(input.appId),
+      normalizeOptionalString(input.appUrl),
+      databaseUrlSecretKey,
+      databaseAuthTokenSecretKey,
+      ctx.userEmail,
+      now,
+      now,
+      ctx.orgId,
+    ],
+  });
+
+  const connection = await getDbAdminConnection(ctx, id);
+  if (!connection) {
+    throw new DbAdminConnectionError(404, "Connection not found.");
+  }
+  return connection;
+}
+
+export async function deleteDbAdminConnection(
+  ctx: DbAdminAdminContext,
+  id: string,
+): Promise<{ deleted: boolean }> {
+  const target = await getConnectionRow(ctx, id);
+  if (!target) return { deleted: false };
+
+  await getDbExec().execute({
+    sql: `DELETE FROM ${CONNECTIONS_TABLE} WHERE id = ? AND org_id = ?`,
+    args: [id, ctx.orgId],
+  });
+  await deleteAppSecret({
+    key: readString(target, "databaseUrlSecretKey", "database_url_secret_key")!,
+    scope: "org",
+    scopeId: ctx.orgId,
+  }).catch(() => false);
+  const authKey = readString(
+    target,
+    "databaseAuthTokenSecretKey",
+    "database_auth_token_secret_key",
+  );
+  if (authKey) {
+    await deleteAppSecret({
+      key: authKey,
+      scope: "org",
+      scopeId: ctx.orgId,
+    }).catch(() => false);
+  }
+  return { deleted: true };
+}
+
+async function getConnectionRow(
+  ctx: DbAdminAdminContext,
+  id: string,
+): Promise<Record<string, unknown> | null> {
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT id, name, app_id AS "appId", app_url AS "appUrl",
+                 database_url_secret_key AS "databaseUrlSecretKey",
+                 database_auth_token_secret_key AS "databaseAuthTokenSecretKey",
+                 created_by AS "createdBy", created_at AS "createdAt",
+                 updated_at AS "updatedAt", org_id AS "orgId"
+          FROM ${CONNECTIONS_TABLE}
+          WHERE id = ? AND org_id = ?
+          LIMIT 1`,
+    args: [id, ctx.orgId],
+  });
+  return (rows[0] as Record<string, unknown> | undefined) ?? null;
+}
+
+export async function getDbAdminConnection(
+  ctx: DbAdminAdminContext,
+  id: string,
+): Promise<DbAdminConnection | null> {
+  const row = await getConnectionRow(ctx, id);
+  if (!row) return null;
+  return rowToConnection(row, await secretMetadata(ctx, row));
+}
+
+export async function withDbAdminConnectionRuntime<T>(
+  ctx: DbAdminAdminContext,
+  id: string,
+  fn: (runtime: DbAdminRuntime, connection: DbAdminConnection) => Promise<T>,
+): Promise<T> {
+  const row = await getConnectionRow(ctx, id);
+  if (!row) throw new DbAdminConnectionError(404, "Connection not found.");
+
+  const databaseUrlSecretKey = readString(
+    row,
+    "databaseUrlSecretKey",
+    "database_url_secret_key",
+  );
+  if (!databaseUrlSecretKey) {
+    throw new DbAdminConnectionError(
+      500,
+      "Connection is missing database URL metadata.",
+    );
+  }
+  const databaseUrl = await readAppSecret({
+    key: databaseUrlSecretKey,
+    scope: "org",
+    scopeId: ctx.orgId,
+  });
+  if (!databaseUrl?.value) {
+    throw new DbAdminConnectionError(400, "Database URL secret is missing.");
+  }
+
+  const authSecretKey = readString(
+    row,
+    "databaseAuthTokenSecretKey",
+    "database_auth_token_secret_key",
+  );
+  const authToken = authSecretKey
+    ? await readAppSecret({
+        key: authSecretKey,
+        scope: "org",
+        scopeId: ctx.orgId,
+      })
+    : null;
+
+  const exec = await createDbExec({
+    url: databaseUrl.value,
+    authToken: authToken?.value,
+  });
+  try {
+    return await fn(
+      {
+        db: exec,
+        dialect: dialectForDatabaseUrl(databaseUrl.value),
+      },
+      rowToConnection(row, await secretMetadata(ctx, row)),
+    );
+  } finally {
+    await exec.close?.().catch(() => {});
+  }
+}
+
+export function redactDbAdminError(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  return message
+    .replace(/(postgres(?:ql)?:\/\/[^:\s/]+:)[^@\s]+@/gi, "$1[redacted]@")
+    .replace(/(libsql:\/\/[^?\s]+[?&]authToken=)[^&\s]+/gi, "$1[redacted]");
+}

package/corpus/templates/analytics/server/lib/session-replay-agent-context.ts

@@ -1,12 +1,14 @@
 import {
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  createScopedAgentAccessGrant,
   getRequestContext,
-  signShortLivedToken,
-  verifyShortLivedToken,
+  verifyScopedAgentAccessToken,
 } from "@agent-native/core/server";
 
 import {
   SESSION_REPLAY_AGENT_ACCESS_PARAM,
-  sessionReplayAgentAccessTokenResourceId,
+  SESSION_REPLAY_AGENT_ACCESS_TOKEN_PREFIX,
 } from "../../shared/session-replay-agent-access.js";
 import {
   isFailedSessionReplayNetworkStatus,
@@ -70,17 +72,6 @@ function appOrigin(explicitOrigin?: string): string {
   }
 }
 
-function absoluteUrl(path: string, origin?: string): string {
-  return `${appOrigin(origin)}${appBasePath()}${path}`;
-}
-
-function appendAgentToken(path: string, token: string): string {
-  const sep = path.includes("?") ? "&" : "?";
-  return `${path}${sep}${SESSION_REPLAY_AGENT_ACCESS_PARAM}=${encodeURIComponent(
-    token,
-  )}`;
-}
-
 function replayStartedAt(events: AgentReplayEvent[]): number {
   const first = events.find((event) =>
     Number.isFinite(Number(event.timestamp)),
@@ -616,10 +607,10 @@ export function verifySessionReplayAgentAccess(
   recordingId: string,
   token: string,
 ): boolean {
-  return verifyShortLivedToken(
-    token,
-    sessionReplayAgentAccessTokenResourceId(recordingId),
-  ).ok;
+  return verifyScopedAgentAccessToken(token, {
+    resourceKind: SESSION_REPLAY_AGENT_ACCESS_TOKEN_PREFIX,
+    resourceId: recordingId,
+  }).ok;
 }
 
 export async function createSessionReplayAgentLink({
@@ -632,31 +623,32 @@ export async function createSessionReplayAgentLink({
   origin?: string;
 }) {
   const recording = await getSessionReplaySummary(recordingId, scope);
-  const token = signShortLivedToken({
-    resourceId: sessionReplayAgentAccessTokenResourceId(recording.id),
+  const grant = createScopedAgentAccessGrant({
+    resourceKind: SESSION_REPLAY_AGENT_ACCESS_TOKEN_PREFIX,
+    resourceId: recording.id,
     viewerEmail: scope.userEmail,
     ttlSeconds: SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS,
   });
-  const expiresAt = new Date(
-    Date.now() + SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS * 1000,
-  ).toISOString();
-  const sessionPath = appendAgentToken(
-    `/sessions/${encodeURIComponent(recording.id)}`,
-    token,
-  );
-  const contextPath = appendAgentToken(
-    `/api/session-replay/agent-context.json?id=${encodeURIComponent(
-      recording.id,
-    )}`,
-    token,
-  );
+  const resolvedOrigin = appOrigin(origin);
+  const basePath = appBasePath();
 
   return {
     recordingId: recording.id,
-    url: absoluteUrl(sessionPath, origin),
-    contextUrl: absoluteUrl(contextPath, origin),
-    expiresAt,
-    ttlSeconds: SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS,
+    url: buildAgentAccessUrl({
+      path: `/sessions/${encodeURIComponent(recording.id)}`,
+      origin: resolvedOrigin,
+      basePath,
+      token: grant.token,
+    }),
+    contextUrl: buildAgentAccessApiUrl({
+      endpoint: "/api/session-replay/agent-context.json",
+      resourceId: recording.id,
+      origin: resolvedOrigin,
+      basePath,
+      token: grant.token,
+    }),
+    expiresAt: grant.expiresAt,
+    ttlSeconds: grant.ttlSeconds,
   };
 }
 
@@ -679,28 +671,36 @@ export async function buildSessionReplayAgentContext({
   }
 
   const recording = await getSessionReplayTokenizedSummary(recordingId);
-  const contextPath = appendAgentToken(
-    `/api/session-replay/agent-context.json?id=${encodeURIComponent(
-      recording.id,
-    )}`,
+  const resolvedOrigin = appOrigin(origin);
+  const basePath = appBasePath();
+  const contextUrl = buildAgentAccessApiUrl({
+    endpoint: "/api/session-replay/agent-context.json",
+    resourceId: recording.id,
+    origin: resolvedOrigin,
+    basePath,
     token,
-  );
-  const eventsPath = appendAgentToken(
-    `/api/session-replay/agent-events.json?id=${encodeURIComponent(
-      recording.id,
-    )}&limit=10000`,
+  });
+  const eventsUrl = buildAgentAccessApiUrl({
+    endpoint: "/api/session-replay/agent-events.json",
+    resourceId: recording.id,
+    origin: resolvedOrigin,
+    basePath,
     token,
-  );
-  const diagnosticsPath = appendAgentToken(
-    `/api/session-replay/agent-diagnostics.json?id=${encodeURIComponent(
-      recording.id,
-    )}`,
+    extraParams: [["limit", 10000]],
+  });
+  const diagnosticsUrl = buildAgentAccessApiUrl({
+    endpoint: "/api/session-replay/agent-diagnostics.json",
+    resourceId: recording.id,
+    origin: resolvedOrigin,
+    basePath,
     token,
-  );
-  const pagePath = appendAgentToken(
-    `/sessions/${encodeURIComponent(recording.id)}`,
+  });
+  const pageUrl = buildAgentAccessUrl({
+    path: `/sessions/${encodeURIComponent(recording.id)}`,
+    origin: resolvedOrigin,
+    basePath,
     token,
-  );
+  });
 
   const eventsResponse = includeTimeline
     ? await getSessionReplayTokenizedEvents(recording.id, { limit: 10000 })
@@ -735,16 +735,16 @@ export async function buildSessionReplayAgentContext({
     ],
     recording: compactSessionRecordingSummary(recording),
     apis: {
-      page: { method: "GET", url: absoluteUrl(pagePath, origin) },
-      context: { method: "GET", url: absoluteUrl(contextPath, origin) },
+      page: { method: "GET", url: pageUrl },
+      context: { method: "GET", url: contextUrl },
       events: {
         method: "GET",
-        url: absoluteUrl(eventsPath, origin),
+        url: eventsUrl,
         note: "Returns bounded sanitized replay events; storage/provider URLs stay private.",
       },
       diagnostics: {
         method: "GET",
-        url: absoluteUrl(diagnosticsPath, origin),
+        url: diagnosticsUrl,
         note: "Returns bounded console/network diagnostics. Params: kind=console|network|all, level=log|info|warn|error|debug, limit (default 200, max 500), offset (page with N-entry skip), fromMs/toMs (inclusive offsetMs window around a timeline marker). offset/fromMs/toMs force strictly chronological pagination for full enumeration; totals reflect the filtered population and hasMore/truncated show whether more entries remain.",
       },
     },