@useatlas/create 0.0.6 → 0.0.7

package/templates/nextjs-standalone/src/api/routes/tables.ts

@@ -0,0 +1,67 @@
+/**
+ * Public tables API route.
+ *
+ * Mounted at /api/v1/tables. Available to all authenticated users (not admin-gated).
+ * Returns a simplified view of semantic layer entities with column details,
+ * enabling SDK consumers to discover queryable tables.
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { runHandler } from "@atlas/api/lib/effect/hono";
+import { validationHook } from "./validation-hook";
+import { z } from "zod";
+import { getSemanticRoot, discoverTables } from "@atlas/api/lib/semantic/files";
+import { ErrorSchema } from "./shared-schemas";
+import { standardAuth, requestContext, type AuthEnv } from "./middleware";
+
+const TablesResponseSchema = z.object({
+  tables: z.array(z.record(z.string(), z.unknown())),
+  warnings: z.array(z.string()).optional(),
+});
+
+
+const tablesRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Tables"],
+  summary: "List queryable tables",
+  description:
+    "Returns a simplified view of semantic layer entities with column details, enabling SDK consumers to discover queryable tables.",
+  responses: {
+    200: {
+      description: "List of tables with columns",
+      content: { "application/json": { schema: TablesResponseSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Forbidden — insufficient permissions",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+export const tables = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
+
+tables.use(standardAuth);
+tables.use(requestContext);
+
+// GET / — list all tables with columns
+tables.openapi(tablesRoute, async (c) => runHandler(c, "load table list", async () => {
+  const root = getSemanticRoot();
+  const result = discoverTables(root);
+  return c.json({
+    tables: result.tables,
+    ...(result.warnings.length > 0 && { warnings: result.warnings }),
+  }, 200);
+}));

package/templates/nextjs-standalone/src/api/routes/teams.ts

@@ -0,0 +1,222 @@
+/**
+ * Teams integration OAuth routes.
+ *
+ * - GET /api/v1/teams/install   — Redirect to Azure AD admin consent
+ * - GET /api/v1/teams/callback  — Handle admin consent callback
+ *
+ * Unlike Slack, Teams uses Azure AD admin consent. The app credentials
+ * (TEAMS_APP_ID, TEAMS_APP_PASSWORD) are platform-level env vars.
+ * What changes per-org is the tenant authorization — proof that a
+ * workspace admin consented to the bot in their tenant.
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { z } from "zod";
+import { createLogger } from "@atlas/api/lib/logger";
+import { saveTeamsInstallation } from "@atlas/api/lib/teams/store";
+import { saveOAuthState, consumeOAuthState } from "@atlas/api/lib/auth/oauth-state";
+import { ErrorSchema } from "./shared-schemas";
+import { validationHook } from "./validation-hook";
+
+const log = createLogger("teams");
+
+const teams = new OpenAPIHono({ defaultHook: validationHook });
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const installRoute = createRoute({
+  method: "get",
+  path: "/install",
+  tags: ["Teams"],
+  summary: "Teams OAuth install redirect",
+  description:
+    "Redirects to the Azure AD admin consent page. Requires TEAMS_APP_ID to be configured.",
+  responses: {
+    302: {
+      description: "Redirect to Azure AD admin consent page",
+    },
+    501: {
+      description: "Teams not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const callbackRoute = createRoute({
+  method: "get",
+  path: "/callback",
+  tags: ["Teams"],
+  summary: "Teams OAuth callback",
+  description:
+    "Handles the admin consent callback from Azure AD. Saves the tenant authorization " +
+    "and returns HTML on success or failure.",
+  request: {
+    query: z.object({
+      state: z.string().openapi({ description: "CSRF state parameter" }),
+      tenant: z.string().optional().openapi({ description: "Azure AD tenant ID (absent on denial)" }),
+      admin_consent: z.string().optional().openapi({ description: "Whether admin consent was granted" }),
+      error: z.string().optional().openapi({ description: "Error code from Azure AD on denial" }),
+      error_description: z.string().optional().openapi({ description: "Human-readable error from Azure AD" }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Installation successful (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    400: {
+      description: "Invalid or expired state, or consent not granted",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    500: {
+      description: "Installation failed (HTML response)",
+      content: { "text/html": { schema: z.string() } },
+    },
+    501: {
+      description: "Teams not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+// --- GET /api/v1/teams/install ---
+
+teams.openapi(installRoute, async (c) => {
+  const appId = process.env.TEAMS_APP_ID;
+  if (!appId) {
+    return c.json({ error: "teams_not_configured", message: "Teams not configured" }, 501);
+  }
+
+  // Extract orgId from session if available (admin clicking "Connect to Teams")
+  let orgId: string | undefined;
+  try {
+    const authResult = c.get("authResult" as never) as
+      | { user?: { activeOrganizationId?: string } }
+      | undefined;
+    orgId = authResult?.user?.activeOrganizationId ?? undefined;
+  } catch (err) {
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "authResult not available on Teams install route",
+    );
+  }
+
+  const nonce = crypto.randomUUID();
+  try {
+    await saveOAuthState(nonce, { orgId, provider: "teams" });
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Failed to save OAuth state for Teams install",
+    );
+    return c.json(
+      { error: "state_save_failed", message: "Could not initiate OAuth flow. Please try again." },
+      500,
+    );
+  }
+
+  const origin = new URL(c.req.url).origin;
+  const redirectUri = `${origin}/api/v1/teams/callback`;
+  const url =
+    `https://login.microsoftonline.com/common/adminconsent` +
+    `?client_id=${encodeURIComponent(appId)}` +
+    `&state=${encodeURIComponent(nonce)}` +
+    `&redirect_uri=${encodeURIComponent(redirectUri)}`;
+  return c.redirect(url);
+});
+
+// --- GET /api/v1/teams/callback ---
+
+teams.openapi(callbackRoute, async (c) => {
+  const appId = process.env.TEAMS_APP_ID;
+  if (!appId) {
+    return c.json({ error: "teams_not_configured", message: "Teams not configured" }, 501);
+  }
+
+  const requestId = crypto.randomUUID();
+
+  const nonce = c.req.query("state");
+  if (!nonce) {
+    return c.json({ error: "invalid_state", message: "Invalid or expired state parameter." }, 400);
+  }
+
+  let oauthState: Awaited<ReturnType<typeof consumeOAuthState>>;
+  try {
+    oauthState = await consumeOAuthState(nonce);
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), requestId },
+      "Failed to validate OAuth state — internal database may be unavailable",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Could not validate the authorization. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  if (!oauthState) {
+    return c.json({ error: "invalid_state", message: "Invalid or expired state parameter. Please start the installation again." }, 400);
+  }
+
+  if (oauthState.provider !== "teams") {
+    log.warn({ expected: "teams", got: oauthState.provider, requestId }, "OAuth state provider mismatch");
+    return c.json({ error: "invalid_state", message: "Invalid state parameter." }, 400);
+  }
+
+  // Azure AD returns error/error_description when consent is denied
+  const errorCode = c.req.query("error");
+  if (errorCode) {
+    const errorDesc = c.req.query("error_description") ?? "Admin consent was not granted";
+    log.info({ errorCode, errorDesc }, "Teams admin consent denied");
+    return c.json(
+      { error: "consent_denied", message: errorDesc },
+      400,
+    );
+  }
+
+  const tenantId = c.req.query("tenant");
+  if (!tenantId) {
+    return c.json({ error: "missing_tenant", message: "Missing tenant parameter" }, 400);
+  }
+
+  // Azure AD tenant IDs are UUIDs — reject malformed values
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(tenantId)) {
+    return c.json({ error: "invalid_tenant", message: "Invalid tenant ID format" }, 400);
+  }
+
+  const adminConsent = c.req.query("admin_consent");
+  if (adminConsent !== "True") {
+    return c.json(
+      { error: "consent_denied", message: "Admin consent was not granted" },
+      400,
+    );
+  }
+
+  try {
+    const orgId = oauthState.orgId;
+    await saveTeamsInstallation(tenantId, { orgId });
+    log.info({ tenantId, orgId }, "Teams installation saved");
+  } catch (saveErr) {
+    log.error(
+      { err: saveErr instanceof Error ? saveErr.message : String(saveErr), tenantId, requestId },
+      "Failed to save Teams installation",
+    );
+    return c.html(
+      `<html><body><h1>Installation Failed</h1><p>Could not save the installation. Please try again. (ref: ${requestId.slice(0, 8)})</p></body></html>`,
+      500,
+    );
+  }
+
+  return c.html(
+    "<html><body><h1>Atlas installed!</h1><p>You can now use Atlas in your Teams workspace.</p></body></html>",
+  );
+});
+
+export { teams };

package/templates/nextjs-standalone/src/api/routes/validate-sql.ts

@@ -0,0 +1,188 @@
+/**
+ * SQL validation endpoint — validate SQL without executing it.
+ *
+ * POST /api/v1/validate-sql accepts a SQL string, runs the full validation
+ * pipeline (empty check → regex guard → AST parse → table whitelist), and
+ * returns structured results with the failing layer, error messages, and
+ * referenced tables.
+ *
+ * Does NOT execute the query against any database.
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { validationHook } from "./validation-hook";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { Parser } from "node-sql-parser";
+import { createLogger } from "@atlas/api/lib/logger";
+import { validateSQL, parserDatabase } from "@atlas/api/lib/tools/sql";
+import { connections, detectDBType } from "@atlas/api/lib/db/connection";
+import { ErrorSchema } from "./shared-schemas";
+import { standardAuth, requestContext, type AuthEnv } from "./middleware";
+
+const log = createLogger("validate-sql");
+const parser = new Parser();
+
+export const ValidateSQLRequestSchema = z.object({
+  sql: z.string().trim().min(1, "sql must not be empty"),
+  connectionId: z.string().optional(),
+});
+
+/** Validation layer identifiers returned in the `errors` array. */
+type ValidationLayer =
+  | "empty_check"
+  | "connection"
+  | "regex_guard"
+  | "ast_parse"
+  | "table_whitelist";
+
+/**
+ * Map the error message from validateSQL() in lib/tools/sql.ts to the
+ * validation layer that produced it. If those messages change, update the
+ * matchers below accordingly.
+ */
+function inferLayer(error: string): ValidationLayer {
+  if (error === "Empty query") return "empty_check";
+  if (error.startsWith("Connection") || error.startsWith("No valid datasource")) return "connection";
+  if (error.startsWith("Forbidden SQL operation")) return "regex_guard";
+  if (
+    error.includes("not in the allowed list") ||
+    error.includes("Could not verify table")
+  ) return "table_whitelist";
+  // Fallthrough: parse failures, non-SELECT, multiple statements.
+  // Log so we notice when new error formats are added to validateSQL().
+  log.warn({ error }, "inferLayer: unrecognized error message, defaulting to ast_parse");
+  return "ast_parse";
+}
+
+const ValidateSQLResponseSchema = z.object({
+  valid: z.boolean(),
+  errors: z.array(z.object({
+    layer: z.enum(["empty_check", "connection", "regex_guard", "ast_parse", "table_whitelist"]),
+    message: z.string(),
+  })),
+  tables: z.array(z.string()),
+});
+
+
+const validateRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Validate SQL"],
+  summary: "Validate SQL without executing",
+  description:
+    "Runs the full SQL validation pipeline (empty check, regex guard, AST parse, table whitelist) and returns structured results. Does NOT execute the query.",
+  request: {
+    body: {
+      content: { "application/json": { schema: ValidateSQLRequestSchema } },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      description: "Validation result",
+      content: { "application/json": { schema: ValidateSQLResponseSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Forbidden — insufficient permissions",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    422: {
+      description: "Validation error (invalid request body)",
+      content: {
+        "application/json": {
+          schema: ErrorSchema.extend({ details: z.array(z.unknown()).optional() }),
+        },
+      },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+  },
+});
+
+export const validateSqlRoute = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
+
+validateSqlRoute.use(standardAuth);
+validateSqlRoute.use(requestContext);
+
+// Normalize JSON parse errors from @hono/zod-openapi into the standard API error format.
+// The framework throws HTTPException(400) for unparseable JSON bodies; this preserves
+// the original { error: "invalid_request", message: "Invalid JSON body." } contract.
+validateSqlRoute.onError((err, c) => {
+  if (err instanceof HTTPException) {
+    if (err.res) return err.res;
+    if (err.status === 400) {
+      return c.json({ error: "invalid_request", message: "Invalid JSON body." }, 400);
+    }
+  }
+  throw err;
+});
+
+validateSqlRoute.openapi(
+  validateRoute,
+  async (c) => {
+    const { sql, connectionId } = c.req.valid("json");
+
+    const result = validateSQL(sql, connectionId);
+
+    if (!result.valid) {
+      return c.json({
+        valid: false,
+        errors: [{ layer: inferLayer(result.error!), message: result.error! }],
+        tables: [],
+      }, 200);
+    }
+
+    // Extract referenced tables from the valid query.
+    // getDBType/detectDBType are outside the catch — operational errors
+    // (missing connection, bad config) should propagate, not be swallowed.
+    let tables: string[] = [];
+    let dbType: string;
+    if (connectionId) {
+      dbType = connections.getDBType(connectionId);
+    } else {
+      dbType = detectDBType();
+    }
+    const trimmed = sql.trim().replace(/;\s*$/, "");
+    try {
+      const tableRefs = parser.tableList(trimmed, {
+        database: parserDatabase(dbType, connectionId),
+      });
+      tables = [
+        ...new Set(
+          tableRefs
+            .map((ref) => {
+              // tableList returns "action::schema::table" format
+              const parts = ref.split("::");
+              const table = parts[2]?.toLowerCase() ?? "";
+              const schema = parts[1]?.toLowerCase();
+              if (!table) return "";
+              return schema && schema !== "null" ? `${schema}.${table}` : table;
+            })
+            .filter(Boolean),
+        ),
+      ];
+    } catch (err) {
+      log.warn(
+        { err: err instanceof Error ? err : new Error(String(err)), sql: trimmed },
+        "Table extraction failed for valid query",
+      );
+    }
+
+    return c.json({ valid: true, errors: [], tables }, 200);
+  },
+  (result, c) => {
+    if (!result.success) {
+      return c.json(
+        { error: "validation_error", message: "Invalid request body.", details: result.error.issues },
+        422,
+      );
+    }
+  },
+);

package/templates/nextjs-standalone/src/api/routes/validation-hook.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared defaultHook for @hono/zod-openapi routers.
+ *
+ * Uses the `target` field from the validation result to generate
+ * context-appropriate error messages instead of a blanket
+ * "Invalid JSON body" for all validation failures.
+ *
+ * Must be passed as `defaultHook` to each OpenAPIHono instance —
+ * Hono does NOT cascade defaultHook to sub-routers.
+ */
+
+import type { Context, Env } from "hono";
+import type { ZodError } from "zod";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("validation");
+
+/** Maps validation target keys to human-readable descriptions. */
+const targetLabels: Record<string, string> = {
+  json: "Invalid request body",
+  form: "Invalid form data",
+  query: "Invalid query parameters",
+  param: "Invalid path parameters",
+  header: "Invalid request headers",
+  cookie: "Invalid cookie values",
+};
+
+type HookResult =
+  | { target: string; success: true; data: unknown }
+  | { target: string; success: false; error: ZodError };
+
+/**
+ * Shared defaultHook that returns 422 with an accurate message
+ * describing which part of the request failed validation.
+ *
+ * Drop-in replacement for per-route defaultHook closures.
+ *
+ * @example
+ * ```ts
+ * const app = new OpenAPIHono({ defaultHook: validationHook });
+ * ```
+ */
+export function validationHook<E extends Env = Env>(
+  result: HookResult,
+  c: Context<E, string>,
+): Response | undefined {
+  if (result.success) return undefined;
+
+  const message =
+    targetLabels[result.target] ?? `Validation error (${result.target})`;
+
+  log.debug({ target: result.target, issues: result.error.issues.length }, "Request validation failed: %s", message);
+
+  return c.json(
+    {
+      error: "validation_error",
+      message,
+      details: result.error.issues,
+    },
+    422,
+  );
+}