@useatlas/create 0.0.6 → 0.0.7

package/templates/docker/src/api/routes/admin-audit-retention.ts

@@ -0,0 +1,405 @@
+/**
+ * Admin audit retention management routes.
+ *
+ * Mounted under /api/v1/admin/audit/retention. All routes require admin role AND
+ * enterprise license (enforced within the retention service layer).
+ *
+ * Provides:
+ * - GET  /                — current retention policy
+ * - PUT  /                — update retention policy
+ * - POST /export          — compliance export (CSV or JSON)
+ * - POST /purge           — manually trigger soft-delete purge
+ * - POST /hard-delete     — manually trigger hard-delete cleanup
+ */
+
+import { Effect } from "effect";
+import { createRoute, z } from "@hono/zod-openapi";
+import { RetentionError } from "@atlas/ee/audit/retention";
+import { runEffect } from "@atlas/api/lib/effect/hono";
+import { AuthContext } from "@atlas/api/lib/effect/services";
+import { ErrorSchema, AuthErrorSchema } from "./shared-schemas";
+import { createAdminRouter, requireOrgContext } from "./admin-router";
+
+const RETENTION_ERROR_STATUS = { validation: 400, not_found: 404 } as const;
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const RetentionPolicySchema = z.object({
+  orgId: z.string(),
+  retentionDays: z.number().nullable(),
+  hardDeleteDelayDays: z.number(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+  lastPurgeAt: z.string().nullable(),
+  lastPurgeCount: z.number().nullable(),
+});
+
+const UpdateRetentionBodySchema = z.object({
+  retentionDays: z.number().nullable().openapi({
+    example: 90,
+    description: "Number of days to retain audit entries. null = unlimited. Minimum 7.",
+  }),
+  hardDeleteDelayDays: z.number().optional().openapi({
+    example: 30,
+    description: "Days after soft-delete before permanent deletion. Default 30.",
+  }),
+});
+
+const ExportBodySchema = z.object({
+  format: z.enum(["csv", "json"]).openapi({
+    example: "csv",
+    description: "Export format: csv or json",
+  }),
+  startDate: z.string().optional().openapi({
+    example: "2026-01-01",
+    description: "Start date for export range (ISO 8601)",
+  }),
+  endDate: z.string().optional().openapi({
+    example: "2026-03-22",
+    description: "End date for export range (ISO 8601)",
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+const getRetentionRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Audit Retention"],
+  summary: "Get audit retention policy",
+  description:
+    "Returns the current audit retention policy for the admin's active organization. Returns null policy if no retention is configured (unlimited).",
+  responses: {
+    200: {
+      description: "Current retention policy",
+      content: {
+        "application/json": {
+          schema: z.object({ policy: RetentionPolicySchema.nullable() }),
+        },
+      },
+    },
+    400: {
+      description: "No active organization",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    403: {
+      description: "Forbidden — admin role or enterprise license required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    404: {
+      description: "Internal database not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const updateRetentionRoute = createRoute({
+  method: "put",
+  path: "/",
+  tags: ["Admin — Audit Retention"],
+  summary: "Update audit retention policy",
+  description:
+    "Sets or updates the audit retention policy. Retention period must be at least 7 days or null (unlimited).",
+  request: {
+    body: {
+      required: true,
+      content: {
+        "application/json": { schema: UpdateRetentionBodySchema },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Updated retention policy",
+      content: {
+        "application/json": {
+          schema: z.object({ policy: RetentionPolicySchema }),
+        },
+      },
+    },
+    400: {
+      description: "Invalid retention configuration or no active organization",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    403: {
+      description: "Forbidden — admin role or enterprise license required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    404: {
+      description: "Internal database not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const exportRoute = createRoute({
+  method: "post",
+  path: "/export",
+  tags: ["Admin — Audit Retention"],
+  summary: "Export audit log for compliance",
+  description:
+    "Exports audit log entries in CSV or JSON format with optional date range filtering. SOC2-ready format. Enterprise feature.",
+  request: {
+    body: {
+      required: true,
+      content: {
+        "application/json": { schema: ExportBodySchema },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Exported audit data (CSV or JSON download)",
+      content: {
+        "text/csv": { schema: z.string() },
+        "application/json": { schema: z.record(z.string(), z.unknown()) },
+      },
+    },
+    400: {
+      description: "Invalid export parameters or no active organization",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    403: {
+      description: "Forbidden — admin role or enterprise license required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    404: {
+      description: "Internal database not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const purgeRoute = createRoute({
+  method: "post",
+  path: "/purge",
+  tags: ["Admin — Audit Retention"],
+  summary: "Trigger audit log purge",
+  description:
+    "Manually triggers soft-delete of audit log entries past the retention window. Normally runs automatically on a daily schedule.",
+  responses: {
+    200: {
+      description: "Purge results",
+      content: {
+        "application/json": {
+          schema: z.object({
+            results: z.array(z.object({
+              orgId: z.string(),
+              softDeletedCount: z.number(),
+            })),
+          }),
+        },
+      },
+    },
+    400: {
+      description: "No active organization",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    403: {
+      description: "Forbidden — admin role or enterprise license required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    404: {
+      description: "Internal database not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+const hardDeleteRoute = createRoute({
+  method: "post",
+  path: "/hard-delete",
+  tags: ["Admin — Audit Retention"],
+  summary: "Trigger permanent deletion of purged entries",
+  description:
+    "Permanently deletes audit log entries that were soft-deleted longer ago than the hard-delete delay. Normally runs automatically on a daily schedule.",
+  responses: {
+    200: {
+      description: "Hard delete results",
+      content: {
+        "application/json": {
+          schema: z.object({ deletedCount: z.number() }),
+        },
+      },
+    },
+    401: {
+      description: "Authentication required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    403: {
+      description: "Forbidden — admin role or enterprise license required",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    404: {
+      description: "Internal database not configured",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+    429: {
+      description: "Rate limit exceeded",
+      content: { "application/json": { schema: AuthErrorSchema } },
+    },
+    500: {
+      description: "Internal server error",
+      content: { "application/json": { schema: ErrorSchema } },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+
+const adminAuditRetention = createAdminRouter();
+
+adminAuditRetention.use(requireOrgContext());
+
+// GET / — get current retention policy
+adminAuditRetention.openapi(getRetentionRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    const { getRetentionPolicy } = yield* Effect.promise(() => import("@atlas/ee/audit/retention"));
+    const policy = yield* Effect.promise(() => getRetentionPolicy(orgId!));
+    return c.json({ policy }, 200);
+  }), { label: "get retention policy", domainErrors: [[RetentionError, RETENTION_ERROR_STATUS]] });
+});
+
+// PUT / — update retention policy
+adminAuditRetention.openapi(updateRetentionRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId, user } = yield* AuthContext;
+
+    const body = c.req.valid("json");
+
+    const { setRetentionPolicy } = yield* Effect.promise(() => import("@atlas/ee/audit/retention"));
+    const policy = yield* Effect.promise(() => setRetentionPolicy(
+      orgId!,
+      {
+        retentionDays: body.retentionDays,
+        hardDeleteDelayDays: body.hardDeleteDelayDays,
+      },
+      user?.id ?? null,
+    ));
+    return c.json({ policy }, 200);
+  }), { label: "update retention policy", domainErrors: [[RetentionError, RETENTION_ERROR_STATUS]] });
+});
+
+// POST /export — compliance export
+adminAuditRetention.openapi(exportRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    const body = c.req.valid("json");
+
+    const { exportAuditLog } = yield* Effect.promise(() => import("@atlas/ee/audit/retention"));
+    const result = yield* Effect.promise(() => exportAuditLog({
+      orgId: orgId!,
+      format: body.format,
+      startDate: body.startDate,
+      endDate: body.endDate,
+    }));
+
+    if (result.format === "csv") {
+      const filename = `audit-log-${orgId}-${new Date().toISOString().slice(0, 10)}.csv`;
+      return new Response(result.content, {
+        headers: {
+          "Content-Type": "text/csv; charset=utf-8",
+          "Content-Disposition": `attachment; filename="${filename}"`,
+          ...(result.truncated && {
+            "X-Export-Truncated": "true",
+            "X-Export-Total": String(result.totalAvailable),
+          }),
+        },
+      });
+    }
+
+    // JSON format
+    const filename = `audit-log-${orgId}-${new Date().toISOString().slice(0, 10)}.json`;
+    return new Response(result.content, {
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Disposition": `attachment; filename="${filename}"`,
+        ...(result.truncated && {
+          "X-Export-Truncated": "true",
+          "X-Export-Total": String(result.totalAvailable),
+        }),
+      },
+    });
+  }), { label: "export audit log", domainErrors: [[RetentionError, RETENTION_ERROR_STATUS]] });
+});
+
+// POST /purge — manual soft-delete purge
+adminAuditRetention.openapi(purgeRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    const { purgeExpiredEntries } = yield* Effect.promise(() => import("@atlas/ee/audit/retention"));
+    const results = yield* Effect.promise(() => purgeExpiredEntries(orgId!));
+    return c.json({ results }, 200);
+  }), { label: "purge audit log entries", domainErrors: [[RetentionError, RETENTION_ERROR_STATUS]] });
+});
+
+// POST /hard-delete — manual hard-delete cleanup
+adminAuditRetention.openapi(hardDeleteRoute, async (c) => {
+  return runEffect(c, Effect.gen(function* () {
+    const { orgId } = yield* AuthContext;
+
+    const { hardDeleteExpired } = yield* Effect.promise(() => import("@atlas/ee/audit/retention"));
+    const result = yield* Effect.promise(() => hardDeleteExpired(orgId!));
+    return c.json(result, 200);
+  }), { label: "hard-delete audit log entries", domainErrors: [[RetentionError, RETENTION_ERROR_STATUS]] });
+});
+
+export { adminAuditRetention };

package/templates/docker/src/api/routes/admin-auth.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared admin authentication preamble.
+ *
+ * Extracted from admin.ts to avoid duplication across sub-routers
+ * (admin-orgs.ts, admin-learned-patterns.ts, etc.).
+ */
+
+import { HTTPException } from "hono/http-exception";
+import { createLogger } from "@atlas/api/lib/logger";
+import type { AuthResult } from "@atlas/api/lib/auth/types";
+import {
+  authenticateRequest,
+  checkRateLimit,
+  getClientIP,
+} from "@atlas/api/lib/auth/middleware";
+
+const log = createLogger("admin-auth");
+
+/** Known auth error messages that indicate an expired session or token. */
+const EXPIRED_AUTH_ERRORS = new Set([
+  "Session expired",
+  "Session expired (idle timeout)",
+  "Invalid or expired token",
+  "Session data is invalid",
+]);
+
+export function authErrorCode(error: string): "session_expired" | "auth_error" {
+  return EXPIRED_AUTH_ERRORS.has(error) ? "session_expired" : "auth_error";
+}
+
+/**
+ * Authenticate the request and enforce admin role. Returns either:
+ * - `{ error, status, headers? }` on failure (401/403/429/500)
+ * - `{ authResult }` on success (authenticated admin user)
+ *
+ * All error objects include `requestId` for log correlation.
+ * The `headers` field is only present for 429 rate-limit responses.
+ */
+export async function adminAuthPreamble(req: Request, requestId: string) {
+  let authResult: AuthResult;
+  try {
+    authResult = await authenticateRequest(req);
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)), requestId },
+      "Auth dispatch failed",
+    );
+    return { error: { error: "auth_error", message: "Authentication system error", requestId }, status: 500 as const };
+  }
+  if (!authResult.authenticated) {
+    log.warn({ requestId, status: authResult.status }, "Authentication failed");
+    const code = authErrorCode(authResult.error);
+    const errorBody: Record<string, unknown> = { error: code, message: authResult.error, requestId };
+    if (authResult.ssoRedirectUrl) {
+      errorBody.ssoRedirectUrl = authResult.ssoRedirectUrl;
+    }
+    return { error: errorBody, status: authResult.status as 401 | 403 | 500 };
+  }
+
+  // Enforce admin role — when auth mode is "none" (no auth configured, e.g.
+  // local dev), treat the request as an implicit admin since there is no
+  // identity boundary to enforce.
+  if (authResult.mode !== "none" && (!authResult.user || (authResult.user.role !== "admin" && authResult.user.role !== "owner" && authResult.user.role !== "platform_admin"))) {
+    log.warn({ requestId, userId: authResult.user?.id, role: authResult.user?.role }, "Non-admin access attempt");
+    return { error: { error: "forbidden_role", message: "Admin role required.", requestId }, status: 403 as const };
+  }
+
+  const ip = getClientIP(req);
+  const rateLimitKey = authResult.user?.id ?? (ip ? `ip:${ip}` : "anon");
+  const rateCheck = checkRateLimit(rateLimitKey);
+  if (!rateCheck.allowed) {
+    const retryAfterSeconds = Math.ceil((rateCheck.retryAfterMs ?? 60000) / 1000);
+    return {
+      error: { error: "rate_limited", message: "Too many requests. Please wait before trying again.", retryAfterSeconds, requestId },
+      status: 429 as const,
+      headers: { "Retry-After": String(retryAfterSeconds) },
+    };
+  }
+
+  // IP allowlist check — enterprise feature, after auth so we have org context
+  const orgId = authResult.user?.activeOrganizationId;
+  if (orgId) {
+    let checkIPAllowlist: ((orgId: string, clientIP: string | null) => Promise<{ allowed: boolean }>) | undefined;
+    try {
+      ({ checkIPAllowlist } = await import("@atlas/ee/auth/ip-allowlist"));
+    } catch {
+      // ee module not installed — IP allowlist feature unavailable, skip
+    }
+    if (checkIPAllowlist) {
+      const ipCheck = await checkIPAllowlist(orgId, ip);
+      if (!ipCheck.allowed) {
+        log.warn({ requestId, orgId, ip }, "IP not in workspace allowlist");
+        return {
+          error: { error: "ip_not_allowed", message: "Your IP address is not in the workspace's allowlist.", requestId },
+          status: 403 as const,
+        };
+      }
+    }
+  }
+
+  return { authResult };
+}
+
+type AdminPreambleResult = Awaited<ReturnType<typeof adminAuthPreamble>>;
+
+/**
+ * Assert that the admin auth preamble succeeded.
+ * Throws HTTPException with a JSON response on failure, so the handler
+ * can destructure `{ authResult }` directly after calling this.
+ */
+export function requireAdminAuth(
+  preamble: AdminPreambleResult,
+): asserts preamble is Extract<AdminPreambleResult, { authResult: unknown }> {
+  if ("error" in preamble) {
+    throw new HTTPException(preamble.status, {
+      res: Response.json(preamble.error, {
+        status: preamble.status,
+        headers: preamble.headers,
+      }),
+    });
+  }
+}