@useatlas/create 0.0.5 → 0.0.7

package/templates/docker/src/api/routes/semantic.ts

@@ -0,0 +1,179 @@
+/**
+ * Public semantic layer API routes.
+ *
+ * Mounted at /api/v1/semantic. Available to all authenticated users (not admin-gated).
+ * Provides read-only access to entity metadata, enabling the schema explorer UI.
+ * Returns all entities defined in the semantic layer YAML files on disk.
+ */
+
+import * as path from "path";
+import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
+import { Effect } from "effect";
+import { runEffect } from "@atlas/api/lib/effect/hono";
+import { RequestContext } from "@atlas/api/lib/effect/services";
+import { validationHook } from "./validation-hook";
+import { createLogger } from "@atlas/api/lib/logger";
+import {
+  getSemanticRoot,
+  isValidEntityName,
+  readYamlFile,
+  discoverEntities,
+  findEntityFile,
+} from "@atlas/api/lib/semantic/files";
+import { ErrorSchema } from "./shared-schemas";
+import { standardAuth, requestContext, type AuthEnv } from "./middleware";
+
+const log = createLogger("semantic-routes");
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const EntitiesListResponseSchema = z.object({
+  entities: z.array(z.object({
+    table: z.string(),
+    description: z.string(),
+    columnCount: z.number(),
+    joinCount: z.number(),
+    type: z.string(),
+  })),
+  warnings: z.array(z.string()).optional(),
+});
+
+const EntityDetailResponseSchema = z.object({
+  entity: z.unknown(),
+});
+
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const listEntitiesRoute = createRoute({
+  method: "get",
+  path: "/entities",
+  tags: ["Semantic"],
+  summary: "List semantic entities",
+  description:
+    "Returns a summary of all entity definitions from the semantic layer YAML files. Each entity includes table name, description, column count, join count, and type.",
+  responses: {
+    200: {
+      description: "List of entity summaries",
+      content: { "application/json": { schema: EntitiesListResponseSchema } },
+    },
+    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 } },
+    },
+  },
+});
+
+const getEntityRoute = createRoute({
+  method: "get",
+  path: "/entities/{name}",
+  tags: ["Semantic"],
+  summary: "Get entity details",
+  description:
+    "Returns the full parsed YAML content for a single semantic entity, including all dimensions, measures, joins, and query patterns.",
+  request: {
+    params: z.object({
+      name: z.string().openapi({ param: { name: "name", in: "path" }, example: "orders" }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Full entity content",
+      content: { "application/json": { schema: EntityDetailResponseSchema } },
+    },
+    400: {
+      description: "Invalid entity name",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    403: {
+      description: "Access denied (path traversal attempt)",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    404: {
+      description: "Entity not found",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      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 } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+
+export const semantic = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
+
+semantic.use(standardAuth);
+semantic.use(requestContext);
+
+// GET /entities — list all entities (public summary: drops measureCount, connection, source)
+semantic.openapi(listEntitiesRoute, async (c) => {
+  return runEffect(c, Effect.sync(() => {
+    const root = getSemanticRoot();
+    const discovered = discoverEntities(root);
+    const entities = discovered.entities.map(({ table, description, columnCount, joinCount, type }) => ({
+      table, description, columnCount, joinCount, type: type ?? "",
+    }));
+    return c.json({
+      entities,
+      ...(discovered.warnings.length > 0 && { warnings: discovered.warnings }),
+    }, 200);
+  }), { label: "load entity list" });
+});
+
+// GET /entities/{name} — full entity detail
+semantic.openapi(getEntityRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+
+    const { name } = c.req.valid("param");
+
+    if (!isValidEntityName(name)) {
+      log.warn({ requestId, name }, "Rejected invalid entity name");
+      return c.json({ error: "invalid_request", message: "Invalid entity name." }, 400);
+    }
+
+    const root = getSemanticRoot();
+    const filePath = findEntityFile(root, name);
+    if (!filePath) {
+      return c.json({ error: "not_found", message: `Entity "${name}" not found.` }, 404);
+    }
+
+    // Defense-in-depth: verify resolved path is within semantic root
+    const resolved = path.resolve(filePath);
+    if (!resolved.startsWith(path.resolve(root))) {
+      log.error({ requestId, name, resolved, root }, "Resolved entity path escaped semantic root");
+      return c.json({ error: "forbidden", message: "Access denied.", requestId }, 403);
+    }
+
+    const raw = readYamlFile(filePath);
+    return c.json({ entity: raw }, 200);
+  }), { label: "parse entity file" });
+});

package/templates/docker/src/api/routes/sessions.ts

@@ -0,0 +1,210 @@
+/**
+ * User self-service session routes.
+ *
+ * Mounted at /api/v1/sessions. Authenticated users can list and revoke
+ * their own sessions (not other users'). Admin session management is
+ * handled separately in the admin routes.
+ */
+
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { Effect } from "effect";
+import { runEffect } from "@atlas/api/lib/effect/hono";
+import { RequestContext, AuthContext } from "@atlas/api/lib/effect/services";
+import { validationHook } from "./validation-hook";
+import { z } from "zod";
+import { createLogger } from "@atlas/api/lib/logger";
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { detectAuthMode } from "@atlas/api/lib/auth/detect";
+import { ErrorSchema } from "./shared-schemas";
+import { standardAuth, requestContext, type AuthEnv } from "./middleware";
+
+const log = createLogger("sessions-routes");
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+
+const SessionSchema = z.object({
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  expiresAt: z.string(),
+  ipAddress: z.string().nullable(),
+  userAgent: z.string().nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const listSessionsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Sessions"],
+  summary: "List current user's sessions",
+  description:
+    "Returns all sessions for the authenticated user. Requires managed auth mode and an internal database.",
+  responses: {
+    200: {
+      description: "List of user sessions",
+      content: {
+        "application/json": {
+          schema: z.object({ sessions: z.array(SessionSchema) }),
+        },
+      },
+    },
+    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()) } },
+    },
+    404: {
+      description: "Session management requires managed auth mode",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    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 } },
+    },
+  },
+});
+
+const revokeSessionRoute = createRoute({
+  method: "delete",
+  path: "/{id}",
+  tags: ["Sessions"],
+  summary: "Revoke a session",
+  description:
+    "Revokes one of the current user's sessions. Cannot revoke another user's session.",
+  request: {
+    params: z.object({
+      id: z.string().openapi({ param: { name: "id", in: "path" }, example: "session-id" }),
+    }),
+  },
+  responses: {
+    200: {
+      description: "Session revoked",
+      content: {
+        "application/json": {
+          schema: z.object({ success: z.boolean() }),
+        },
+      },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: z.record(z.string(), z.unknown()) } },
+    },
+    403: {
+      description: "Cannot revoke another user's session",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    404: {
+      description: "Session not found or not in managed auth mode",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    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 } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+
+const sessions = new OpenAPIHono<AuthEnv>({ defaultHook: validationHook });
+
+sessions.use(standardAuth);
+sessions.use(requestContext);
+
+// GET / — list the current user's sessions
+sessions.openapi(listSessionsRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { user } = yield* AuthContext;
+
+    if (!hasInternalDB() || detectAuthMode() !== "managed" || !user) {
+      return c.json({ error: "not_available", message: "Session management requires managed auth mode.", requestId }, 404);
+    }
+
+    const userId = user.id;
+
+    const rows = yield* Effect.promise(() => internalQuery<{
+      id: string;
+      createdAt: string;
+      updatedAt: string;
+      expiresAt: string;
+      ipAddress: string | null;
+      userAgent: string | null;
+    }>(
+      `SELECT id, "createdAt", "updatedAt", "expiresAt", "ipAddress", "userAgent"
+       FROM session
+       WHERE "userId" = $1
+       ORDER BY "updatedAt" DESC
+       LIMIT 100`,
+      [userId],
+    ));
+
+    return c.json({
+      sessions: rows.map((r) => ({
+        id: r.id,
+        createdAt: r.createdAt,
+        updatedAt: r.updatedAt,
+        expiresAt: r.expiresAt,
+        ipAddress: r.ipAddress,
+        userAgent: r.userAgent,
+      })),
+    }, 200);
+  }), { label: "list sessions" });
+});
+
+// DELETE /:id — revoke one of the current user's sessions
+sessions.openapi(revokeSessionRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { requestId } = yield* RequestContext;
+    const { user } = yield* AuthContext;
+
+    if (!hasInternalDB() || detectAuthMode() !== "managed" || !user) {
+      return c.json({ error: "not_available", message: "Session management requires managed auth mode.", requestId }, 404);
+    }
+
+    const userId = user.id;
+    const { id: sessionId } = c.req.valid("param");
+
+    // Atomic delete scoped to the current user — returns empty if
+    // the session doesn't exist or belongs to another user.
+    const deleted = yield* Effect.promise(() => internalQuery<{ id: string }>(
+      `DELETE FROM session WHERE id = $1 AND "userId" = $2 RETURNING id`,
+      [sessionId, userId],
+    ));
+    if (deleted.length === 0) {
+      // Distinguish "not found" from "wrong user" for a clear error message
+      const exists = yield* Effect.promise(() => internalQuery<{ userId: string }>(
+        `SELECT "userId" FROM session WHERE id = $1`,
+        [sessionId],
+      ));
+      if (exists.length === 0) {
+        return c.json({ error: "not_found", message: "Session not found." }, 404);
+      }
+      return c.json({ error: "forbidden", message: "Cannot revoke another user's session.", requestId }, 403);
+    }
+
+    log.info({ requestId, sessionId, userId }, "User revoked own session");
+    return c.json({ success: true }, 200);
+  }), { label: "revoke session" });
+});
+
+export { sessions };

package/templates/docker/src/api/routes/shared-domains.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared domain infrastructure — schemas, error mapping, module loading,
+ * and error sanitization used by both admin-domains.ts (workspace) and
+ * platform-domains.ts (platform admin).
+ */
+
+import { z } from "@hono/zod-openapi";
+import { createLogger } from "@atlas/api/lib/logger";
+import type { DomainErrorMapping } from "@atlas/api/lib/effect/hono";
+import { DomainError, type DomainErrorCode } from "@atlas/ee/platform/domains";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+const log = createLogger("domains-shared");
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export const CustomDomainSchema = z.object({
+  id: z.string(),
+  workspaceId: z.string(),
+  domain: z.string(),
+  status: z.enum(["pending", "verified", "failed"]),
+  railwayDomainId: z.string().nullable(),
+  cnameTarget: z.string().nullable(),
+  certificateStatus: z.enum(["PENDING", "ISSUED", "FAILED"]).nullable(),
+  createdAt: z.string(),
+  verifiedAt: z.string().nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+/** Infrastructure error codes whose messages may contain internal details. */
+const SANITIZED_CODES = new Set<DomainErrorCode>([
+  "railway_error",
+  "railway_not_configured",
+  "data_integrity",
+]);
+
+const DOMAIN_ERROR_STATUS: Record<DomainErrorCode, ContentfulStatusCode> = {
+  no_internal_db: 503,
+  invalid_domain: 400,
+  duplicate_domain: 409,
+  domain_not_found: 404,
+  railway_error: 502,
+  railway_not_configured: 503,
+  data_integrity: 500,
+};
+
+export const domainErrors: DomainErrorMapping[] = [
+  [DomainError, DOMAIN_ERROR_STATUS],
+];
+
+// ---------------------------------------------------------------------------
+// Module loader (lazy import — fail gracefully when ee is unavailable)
+// ---------------------------------------------------------------------------
+
+export type DomainsModule = typeof import("@atlas/ee/platform/domains");
+
+export async function loadDomains(): Promise<DomainsModule | null> {
+  try {
+    return await import("@atlas/ee/platform/domains");
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === "MODULE_NOT_FOUND"
+    ) {
+      return null;
+    }
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)) },
+      "Failed to load domains module — unexpected error",
+    );
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error sanitization
+// ---------------------------------------------------------------------------
+
+/**
+ * Sanitize DomainError messages for infrastructure errors before they
+ * reach the client. Railway errors and data integrity errors may contain
+ * internal infrastructure details that should not be exposed.
+ *
+ * User-facing errors (invalid_domain, duplicate_domain, domain_not_found)
+ * pass through unmodified.
+ */
+export function sanitizeDomainError(err: unknown, requestId: string): void {
+  if (err instanceof DomainError && SANITIZED_CODES.has(err.code)) {
+    log.error({ err, code: err.code, requestId }, "Infrastructure domain error");
+    err.message = `Domain service error (ref: ${requestId.slice(0, 8)})`;
+  }
+}

package/templates/docker/src/api/routes/shared-schemas.ts

@@ -0,0 +1,139 @@
+import { z } from "@hono/zod-openapi";
+import type { Context } from "hono";
+
+/**
+ * Standard error response schema used across all API routes.
+ * Includes optional requestId for log correlation on server errors.
+ */
+export const ErrorSchema = z.object({
+  error: z.string(),
+  message: z.string(),
+  requestId: z.string().optional(),
+});
+
+/**
+ * Auth error schema for Better Auth responses.
+ * Better Auth returns dynamic shapes, so we use a permissive record type.
+ */
+export const AuthErrorSchema = z.record(z.string(), z.unknown());
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+/**
+ * Permissive Zod schema for OpenAPI route declarations.
+ * Accepts the widest bounds any route allows; individual routes enforce
+ * stricter limits at runtime via {@link parsePagination}.
+ */
+export const PaginationQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(500).default(50).optional(),
+  offset: z.coerce.number().int().min(0).default(0).optional(),
+});
+
+/**
+ * Parse limit/offset from query params with clamped bounds.
+ * Values <= 0 or non-numeric fall back to the default limit.
+ * Values above maxLimit are clamped. Offset below 0 defaults to 0.
+ * Defaults: limit=50, maxLimit=200, offset=0.
+ */
+export function parsePagination(
+  c: Context,
+  defaults?: { limit?: number; maxLimit?: number },
+): { limit: number; offset: number } {
+  const maxLimit = defaults?.maxLimit ?? 200;
+  const defaultLimit = defaults?.limit ?? 50;
+  const rawLimit = parseInt(c.req.query("limit") ?? "", 10);
+  const rawOffset = parseInt(c.req.query("offset") ?? "", 10);
+  return {
+    limit: Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, maxLimit) : defaultLimit,
+    offset: Number.isFinite(rawOffset) && rawOffset >= 0 ? rawOffset : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ID validation
+// ---------------------------------------------------------------------------
+
+/** Max length for path-param IDs (roles, SSO providers, SCIM connections, etc.). */
+export const MAX_ID_LENGTH = 128;
+
+/** Type guard: checks that id is a non-empty string within MAX_ID_LENGTH characters. */
+export function isValidId(id: string | undefined): id is string {
+  return !!id && id.length > 0 && id.length <= MAX_ID_LENGTH;
+}
+
+// ---------------------------------------------------------------------------
+// OpenAPI schema factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a path parameter schema for an entity ID.
+ * Enforces min(1), max(MAX_ID_LENGTH), and includes `.openapi()` metadata.
+ */
+export function createIdParamSchema(example?: string) {
+  return z.object({
+    id: z.string().min(1).max(MAX_ID_LENGTH).openapi({
+      param: { name: "id", in: "path" },
+      example: example ?? "abc123",
+    }),
+  });
+}
+
+/**
+ * Create a path parameter schema for a named parameter (e.g. "userId", "collectionId").
+ * Same validation as {@link createIdParamSchema} but with a custom param name.
+ */
+export function createParamSchema<K extends string>(name: K, example?: string) {
+  return z.object({
+    [name]: z.string().min(1).max(MAX_ID_LENGTH).openapi({
+      param: { name, in: "path" },
+      example: example ?? "abc123",
+    }),
+  }) as z.ZodObject<Record<K, z.ZodString>>;
+}
+
+/**
+ * Create a list response schema with `{ [fieldName]: T[], total: number }`.
+ * Covers the common admin listing pattern. Pass `extra` for additional fields
+ * (e.g. limit, offset, callerIP).
+ */
+export function createListResponseSchema<T extends z.ZodTypeAny>(
+  fieldName: string,
+  itemSchema: T,
+  extra?: z.ZodRawShape,
+) {
+  return z.object({
+    [fieldName]: z.array(itemSchema),
+    total: z.number().openapi({ description: "Total count" }),
+    ...extra,
+  });
+}
+
+/**
+ * Create a success response schema with a boolean field.
+ * Defaults to `{ success: boolean, message?: string }`.
+ */
+export function createSuccessResponseSchema() {
+  return z.object({
+    success: z.boolean(),
+    message: z.string().optional(),
+  });
+}
+
+/** Standard `{ deleted: boolean }` response schema. */
+export const DeletedResponseSchema = z.object({
+  deleted: z.boolean(),
+});
+
+/**
+ * Create a standard error response schema.
+ * Equivalent to {@link ErrorSchema} but as a factory for symmetry.
+ */
+export function createErrorResponseSchema() {
+  return z.object({
+    error: z.string(),
+    message: z.string(),
+    requestId: z.string().optional(),
+  });
+}