meyi-cost-server 1.0.0

package/src/services/budget.service.js

@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+import { CostBudget } from "../models/budget.model.js";
+
+export class BudgetService {
+  constructor({ repository }) {
+    this.repository = repository;
+  }
+
+  async list(tenantId) {
+    const budgets = await this.repository.list(tenantId);
+    return budgets.map((item) => new CostBudget({ id: item.id, name: item.name, amount: item.amount, currency: item.currency, period: item.period, spent: item.spent, alertThreshold: item.alert_threshold, createdAt: item.created_at, updatedAt: item.updated_at }));
+  }
+
+  async create(tenantId, payload = {}) {
+    const id = randomUUID();
+    const name = String(payload.name || "").trim();
+    const limit = Number(payload.amount);
+    const alertThreshold = Number(payload.alert_threshold ?? 80);
+    if (!name || !Number.isFinite(limit) || limit <= 0 || !Number.isFinite(alertThreshold) || alertThreshold < 1 || alertThreshold > 100) {
+      const error = new Error("name, a positive amount, and an alert threshold from 1 to 100 are required");
+      error.statusCode = 400;
+      throw error;
+    }
+    const period = String(payload.period || "monthly");
+    await this.repository.create({ id, tenantId, name, amount: limit, currency: "USD", period, alertThreshold });
+    return new CostBudget({ id, name, amount: limit, currency: "USD", period, spent: 0, alertThreshold, createdAt: new Date().toISOString() });
+  }
+
+  async delete(tenantId, id) {
+    await this.repository.delete(tenantId, id);
+  }
+}

package/src/services/cost-explorer.service.js

@@ -0,0 +1,27 @@
+import { GetCostAndUsageCommand } from "@aws-sdk/client-cost-explorer";
+import { grossCostFilter } from "../lib/cost-utils.js";
+
+export class CostExplorerService {
+  async grouped(client, accounts, range, dimension, granularity = "MONTHLY", selections = {}) {
+    const dimensions = Array.isArray(dimension) ? dimension : [dimension];
+    const periods = new Map();
+    let token;
+    do {
+      const response = await client.send(new GetCostAndUsageCommand({
+        TimePeriod: range,
+        Granularity: granularity,
+        Metrics: ["UnblendedCost"],
+        Filter: grossCostFilter(accounts.map((item) => item.id), selections),
+        GroupBy: dimensions.map((item) => ({ Type: item.startsWith("tag:") ? "TAG" : "DIMENSION", Key: item.replace(/^tag:/, "") })),
+        NextPageToken: token,
+      }));
+      for (const period of response.ResultsByTime || []) {
+        const key = period.TimePeriod?.Start || String(periods.size);
+        if (!periods.has(key)) periods.set(key, { ...period, Groups: [] });
+        periods.get(key).Groups.push(...(period.Groups || []));
+      }
+      token = response.NextPageToken;
+    } while (token);
+    return [...periods.values()];
+  }
+}

package/src/services/cur-provider.service.js

@@ -0,0 +1,91 @@
+import { CurDataStatus } from "../models/cur-data-status.model.js";
+import { getCurDataStatus } from "./cur.service.js";
+
+export class CurProviderService {
+  constructor({ athenaContextService, logger = console, env = process.env } = {}) {
+    this.athenaContextService = athenaContextService;
+    this.logger = logger;
+    this.statusCache = new Map();
+    this.statusCacheMs = Math.max(Number(env.COST_CUR_STATUS_CACHE_MS || 300000), 0);
+  }
+
+  async run(customerContext, action) {
+    const context = this.athenaContextService.resolve(customerContext);
+    if (!context.config.enabled) {
+      if (!context.config.required) return null;
+      const readiness = await this.status(customerContext);
+      const error = new Error(readiness.message || "CUR data is not ready for this tenant.");
+      error.name = "CurDataNotReadyError";
+      error.statusCode = 503;
+      throw error;
+    }
+    try {
+      const readiness = await this.status(customerContext);
+      if (!readiness.ready) {
+        if (!context.config.required) return null;
+        const error = new Error(readiness.message || "CUR data is not ready for this tenant.");
+        error.name = "CurDataNotReadyError";
+        error.statusCode = 503;
+        throw error;
+      }
+      return await action(context.client, context.config);
+    } catch (error) {
+      if (context.config.required) throw error;
+      this.logger.warn?.("[Cost] CUR/Athena unavailable; falling back to Cost Explorer", error.message);
+      return null;
+    }
+  }
+
+  async status(customerContext) {
+    const context = this.athenaContextService.resolve(customerContext);
+    if (!context.config.enabled) {
+      const discovery = customerContext.meta?.curDiscovery || null;
+      return new CurDataStatus({
+        configured: false,
+        required: context.config.required,
+        credentialMode: context.credentialMode,
+        ingestionMode: context.ingestion.mode,
+        sourceConfigured: context.ingestion.sourceConfigured,
+        state: discovery?.status ? String(discovery.status).toLowerCase() : undefined,
+        discovery,
+        message: context.config.disabledReason || (discovery
+          ? "Central CUR discovery is still in progress for this tenant."
+          : "Central CUR/Athena is not configured."),
+      });
+    }
+    const cacheKey = `${customerContext.tenant}:${context.config.tenantPartition}`;
+    const cached = this.statusCache.get(cacheKey);
+    if (cached && Date.now() - cached.createdAt < this.statusCacheMs) return cached.status;
+    try {
+      const result = await getCurDataStatus({ client: context.client, config: context.config, tenant: customerContext.tenant });
+      const status = new CurDataStatus({
+        configured: true,
+        required: context.config.required,
+        ready: result.recordCount > 0,
+        state: result.recordCount > 0 ? "ready" : "pending_data",
+        credentialMode: context.credentialMode,
+        ingestionMode: context.ingestion.mode,
+        sourceConfigured: context.ingestion.sourceConfigured,
+        lastDataAt: result.lastDataAt,
+        recordCount: result.recordCount,
+        message: result.recordCount > 0 ? null : "The central CUR table is configured but no rows are available for this tenant.",
+        discovery: customerContext.meta?.curDiscovery || null,
+      });
+      this.statusCache.set(cacheKey, { createdAt: Date.now(), status });
+      return status;
+    } catch (error) {
+      if (context.config.required) throw error;
+      this.logger.warn?.("[Cost] CUR readiness check failed", error.message);
+      return new CurDataStatus({
+        configured: true,
+        required: false,
+        state: "unavailable",
+        credentialMode: context.credentialMode,
+        ingestionMode: context.ingestion.mode,
+        sourceConfigured: context.ingestion.sourceConfigured,
+        message: "Central CUR data is currently unavailable; Cost Explorer fallback remains active.",
+        discovery: customerContext.meta?.curDiscovery || null,
+      });
+    }
+  }
+}

package/src/services/cur.service.js

@@ -0,0 +1,355 @@
+import {
+  AthenaClient,
+  GetQueryExecutionCommand,
+  GetQueryResultsCommand,
+  StartQueryExecutionCommand,
+} from "@aws-sdk/client-athena";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const round = (value) => Math.round((Number(value) + Number.EPSILON) * 100) / 100;
+const amount = (value) => Number(value || 0);
+const sqlString = (value) => `'${String(value).replaceAll("'", "''")}'`;
+
+function identifier(value, label, allowHyphen = false) {
+  const pattern = allowHyphen ? /^[a-zA-Z0-9_-]+$/ : /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+  if (!pattern.test(String(value || ""))) throw new Error(`Invalid CUR ${label}`);
+  return String(value);
+}
+
+export function getCurConfig(env = process.env, metadata = {}) {
+  const database = String(metadata.curDatabase || env.COST_CUR_DATABASE || "").trim();
+  const outputLocation = String(metadata.curOutputLocation || env.COST_CUR_OUTPUT_LOCATION || "").trim();
+  const tableName = String(env.COST_CUR_TABLE || metadata.curTable || "").trim();
+  const mode = String(env.COST_DATA_SOURCE || "auto").trim().toLowerCase();
+  return {
+    enabled: Boolean(database && tableName && outputLocation) && mode !== "cost-explorer",
+    required: mode === "cur",
+    database: database ? identifier(database, "database", true) : "",
+    table: tableName ? identifier(tableName, "table", true) : "",
+    outputLocation,
+    region: String(metadata.curRegion || env.COST_CUR_REGION || env.AWS_REGION || "us-east-1"),
+    workgroup: identifier(metadata.curWorkgroup || env.COST_CUR_WORKGROUP || "meyi-cost", "workgroup", true),
+    tenantColumn: identifier(metadata.curTenantColumn || env.COST_CUR_TENANT_COLUMN || "tenant_id", "tenant column"),
+    tenantPartition: String(metadata.curTenantPartition || env.COST_CUR_TENANT_PARTITION || "").trim(),
+    maxRows: Math.min(Math.max(Number(env.COST_CUR_MAX_ROWS || 1000), 1), 5000),
+  };
+}
+
+export const createCurClient = ({ config, credentials }) => new AthenaClient({
+  region: config.region,
+  credentials,
+});
+
+async function execute(client, config, query) {
+  const started = await client.send(new StartQueryExecutionCommand({
+    QueryString: query,
+    QueryExecutionContext: { Database: config.database },
+    ResultConfiguration: { OutputLocation: config.outputLocation },
+    WorkGroup: config.workgroup,
+  }));
+  const id = started.QueryExecutionId;
+  if (!id) throw new Error("Athena did not return a query execution ID");
+
+  let delay = 300;
+  const deadline = Date.now() + 90_000;
+  while (Date.now() < deadline) {
+    const execution = await client.send(new GetQueryExecutionCommand({ QueryExecutionId: id }));
+    const state = execution.QueryExecution?.Status?.State;
+    if (state === "SUCCEEDED") break;
+    if (state === "FAILED" || state === "CANCELLED") {
+      const error = new Error(execution.QueryExecution?.Status?.StateChangeReason || `Athena query ${state.toLowerCase()}`);
+      error.name = "AthenaQueryError";
+      throw error;
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 1.5, 2_000);
+  }
+  if (Date.now() >= deadline) throw new Error("Athena query timed out after 90 seconds");
+
+  const rawRows = [];
+  let token;
+  do {
+    const page = await client.send(new GetQueryResultsCommand({ QueryExecutionId: id, NextToken: token, MaxResults: 1000 }));
+    rawRows.push(...(page.ResultSet?.Rows || []));
+    token = page.NextToken;
+  } while (token);
+
+  if (!rawRows.length) return [];
+  const headers = (rawRows[0].Data || []).map((item) => item.VarCharValue || "");
+  return rawRows.slice(1).map((row) => Object.fromEntries(headers.map((header, index) => [header, row.Data?.[index]?.VarCharValue ?? null])));
+}
+
+function table(config) {
+  return `"${config.database}"."${config.table}"`;
+}
+
+function tenantWhere(config, tenant) {
+  const partition = config.tenantPartition || tenant;
+  return `"${config.tenantColumn}" = ${sqlString(partition)}`;
+}
+
+export async function getCurDataStatus({ client, config, tenant }) {
+  const statusRows = await execute(client, config, `
+    SELECT
+      CAST(COUNT(*) AS BIGINT) AS record_count,
+      CAST(MAX(CAST(line_item_usage_start_date AS TIMESTAMP)) AS VARCHAR) AS last_data_at
+    FROM ${table(config)}
+    WHERE ${tenantWhere(config, tenant)}
+  `);
+  const status = statusRows[0] || {};
+  return {
+    recordCount: Number(status.record_count || 0),
+    lastDataAt: status.last_data_at || null,
+  };
+}
+
+function rangeWhere(range) {
+  return `CAST(line_item_usage_start_date AS TIMESTAMP) >= TIMESTAMP ${sqlString(`${range.Start} 00:00:00`)}
+    AND CAST(line_item_usage_start_date AS TIMESTAMP) < TIMESTAMP ${sqlString(`${range.End} 00:00:00`)}`;
+}
+
+function inCondition(column, values = []) {
+  if (!values.length) return "";
+  return `AND CAST("${column}" AS VARCHAR) IN (${values.map(sqlString).join(", ")})`;
+}
+
+function cur2TagExpression(tagKey) {
+  const key = String(tagKey || "Name").trim();
+  if (!key) throw new Error("Invalid CUR tag key");
+  return `COALESCE(element_at(resource_tags, ${sqlString(`user:${key.replace(/^user:/, "")}`)}), element_at(resource_tags, ${sqlString(key.replace(/^user:/, ""))}))`;
+}
+
+function inExpression(expression, values = []) {
+  if (!values.length) return "";
+  return `AND CAST(${expression} AS VARCHAR) IN (${values.map(sqlString).join(", ")})`;
+}
+
+function filterWhere(filters = {}) {
+  const conditions = [
+    inCondition("product_product_name", filters.services),
+    inCondition("product_region_code", filters.regions),
+    inCondition("line_item_usage_account_id", filters.accountIds),
+  ];
+  if (filters.tagKey && filters.tagValues?.length) {
+    conditions.push(inExpression(cur2TagExpression(filters.tagKey), filters.tagValues));
+  }
+  return conditions.filter(Boolean).join("\n      ");
+}
+
+function dimensionExpression(groupBy, tagKey) {
+  const dimensions = {
+    service: "product_product_name",
+    account: "line_item_usage_account_id",
+    region: "product_region_code",
+    resource: "line_item_resource_id",
+  };
+  if (groupBy === "tag") return cur2TagExpression(tagKey);
+  return dimensions[groupBy] ? `"${dimensions[groupBy]}"` : undefined;
+}
+
+function summarize(periods, accountNames = new Map()) {
+  const totals = new Map();
+  for (const period of periods) totals.set(period.key, (totals.get(period.key) || 0) + period.amount);
+  const total = [...totals.values()].reduce((sum, value) => sum + value, 0);
+  return [...totals.entries()]
+    .map(([key, value]) => ({
+      key,
+      label: accountNames.get(key) || key,
+      accountId: accountNames.has(key) || /^\d{12}$/.test(key) ? key : undefined,
+      amount: round(value),
+      percentage: total ? round(value / total * 100) : 0,
+    }))
+    .sort((a, b) => b.amount - a.amount);
+}
+
+export async function getCurReport({ client, config, tenant, range, groupBy, granularity = "MONTHLY", tagKey, accountNames = new Map(), filters = {}, includeBreakdown = false }) {
+  const column = dimensionExpression(groupBy, tagKey);
+  if (!column) throw new Error("Unsupported CUR report group");
+  const bucket = granularity === "DAILY" ? "day" : "month";
+  const limit = groupBy === "resource" ? `LIMIT ${config.maxRows}` : "";
+  const query = `
+    SELECT
+      CAST(date_trunc('${bucket}', CAST(line_item_usage_start_date AS TIMESTAMP)) AS VARCHAR) AS period_start,
+      COALESCE(NULLIF(CAST(${column} AS VARCHAR), ''), 'Unallocated') AS item_key,
+      CAST(SUM(line_item_unblended_cost) AS DOUBLE) AS amount
+    FROM ${table(config)}
+    WHERE ${tenantWhere(config, tenant)}
+      AND ${rangeWhere(range)}
+      AND line_item_unblended_cost > 0
+      ${filterWhere(filters)}
+    GROUP BY 1, 2
+    ORDER BY 1, 3 DESC
+    ${limit}
+  `;
+  const rows = await execute(client, config, query);
+  const periods = rows.map((row) => ({ start: String(row.period_start).slice(0, 10), key: row.item_key || "Unallocated", amount: amount(row.amount) }));
+  let summary = summarize(periods, accountNames);
+  if (includeBreakdown && groupBy !== "resource") {
+    const relationQuery = `
+      SELECT
+        COALESCE(NULLIF(CAST(${column} AS VARCHAR), ''), 'Unallocated') AS item_key,
+        COALESCE(NULLIF(CAST(line_item_usage_account_id AS VARCHAR), ''), 'Unallocated') AS account_key,
+        COALESCE(NULLIF(CAST(product_region_code AS VARCHAR), ''), 'GLOBAL') AS region_key,
+        CAST(SUM(line_item_unblended_cost) AS DOUBLE) AS amount
+      FROM ${table(config)}
+      WHERE ${tenantWhere(config, tenant)}
+        AND ${rangeWhere(range)}
+        AND line_item_unblended_cost > 0
+        ${filterWhere(filters)}
+      GROUP BY 1, 2, 3
+    `;
+    const relationRows = await execute(client, config, relationQuery);
+    const accountsByItem = new Map();
+    const regionsByItem = new Map();
+    for (const row of relationRows) {
+      const key = row.item_key || "Unallocated";
+      const add = (target, relationKey) => {
+        if (!target.has(key)) target.set(key, new Map());
+        const values = target.get(key);
+        values.set(relationKey, (values.get(relationKey) || 0) + amount(row.amount));
+      };
+      add(accountsByItem, row.account_key || "Unallocated");
+      add(regionsByItem, row.region_key || "GLOBAL");
+    }
+    const relations = (target, key, type) => [...(target.get(key) || new Map()).entries()].map(([value, cost]) => ({ key: value, label: type === "account" ? accountNames.get(value) || value : value, amount: round(cost) })).sort((a, b) => b.amount - a.amount);
+    summary = summary.map((item) => ({ ...item, accounts: relations(accountsByItem, item.key, "account"), regions: relations(regionsByItem, item.key, "region") }));
+  }
+  const byPeriod = new Map();
+  for (const item of periods) {
+    if (!byPeriod.has(item.start)) byPeriod.set(item.start, []);
+    byPeriod.get(item.start).push(item);
+  }
+  const timeline = [...byPeriod.entries()].map(([start, items]) => ({
+    start,
+    end: start,
+    total: round(items.reduce((sum, item) => sum + item.amount, 0)),
+    groups: summarize(items, accountNames),
+  }));
+  return {
+    groupBy,
+    range,
+    currency: "USD",
+    totalCost: round(summary.reduce((sum, item) => sum + item.amount, 0)),
+    count: summary.length,
+    summary,
+    timeline,
+    dataSource: "aws-cur-athena",
+    accessMode: "cur-readonly",
+    costBasis: "gross-positive-unblended",
+    message: groupBy === "resource" && rows.length >= config.maxRows ? `Showing the first ${config.maxRows} resource rows.` : undefined,
+  };
+}
+
+export async function getCurOverview({ client, config, tenant, range, trendRange = range, trendMode = "monthly", accountNames = new Map() }) {
+  const metricsQuery = `
+    SELECT
+      CAST(SUM(CASE WHEN line_item_unblended_cost > 0 THEN line_item_unblended_cost ELSE 0 END) AS DOUBLE) AS gross_cost,
+      CAST(SUM(line_item_unblended_cost) AS DOUBLE) AS net_cost,
+      CAST(COUNT(DISTINCT CASE WHEN line_item_unblended_cost > 0 AND line_item_resource_id IS NOT NULL AND line_item_resource_id <> '' THEN line_item_resource_id END) AS BIGINT) AS active_resources
+    FROM ${table(config)}
+    WHERE ${tenantWhere(config, tenant)} AND ${rangeWhere(range)}
+  `;
+  const [metricsRows, services, accounts, regions, trendReport] = await Promise.all([
+    execute(client, config, metricsQuery),
+    getCurReport({ client, config, tenant, range, groupBy: "service", accountNames }),
+    getCurReport({ client, config, tenant, range, groupBy: "account", accountNames }),
+    getCurReport({ client, config, tenant, range, groupBy: "region", accountNames }),
+    getCurReport({ client, config, tenant, range: trendRange, groupBy: "service", accountNames }),
+  ]);
+  const metrics = metricsRows[0] || {};
+  const grossCost = round(amount(metrics.gross_cost));
+  const netCost = round(amount(metrics.net_cost));
+  const resolvedAccounts = accounts.summary.map((item) => ({ id: item.accountId || item.key, name: item.label, region: "global", status: "active" }));
+  let trends = trendReport.timeline.map((item) => ({ month: item.start, amount: item.total, currency: "USD" }));
+  if (trendMode === "yearly") {
+    const years = new Map();
+    for (const item of trends) {
+      const year = String(item.month || "").slice(0, 4);
+      years.set(year, round((years.get(year) || 0) + item.amount));
+    }
+    const firstYear = new Date(`${trendRange.Start}T00:00:00Z`).getUTCFullYear();
+    const trendEnd = new Date(`${trendRange.End}T00:00:00Z`); trendEnd.setUTCDate(trendEnd.getUTCDate() - 1);
+    const lastYear = trendEnd.getUTCFullYear();
+    trends = Array.from({ length: lastYear - firstYear + 1 }, (_, offset) => {
+      const year = String(firstYear + offset);
+      return { month: `${year}-01-01`, amount: years.get(year) || 0, currency: "USD" };
+    });
+  }
+  return {
+    tenantId: tenant,
+    accounts: resolvedAccounts,
+    currency: "USD",
+    period: range,
+    totalCost: grossCost,
+    grossCost,
+    netCost,
+    creditsAndAdjustments: round(netCost - grossCost),
+    forecast: null,
+    activeAccounts: resolvedAccounts.length,
+    activeResources: Number(metrics.active_resources || 0),
+    trends,
+    topServices: services.summary.slice(0, 10),
+    topAccounts: accounts.summary.slice(0, 10),
+    topRegions: regions.summary.slice(0, 10),
+    topResources: [],
+    dataSource: "aws-cur-athena",
+    accessMode: "cur-readonly",
+    costBasis: "gross-positive-unblended",
+  };
+}
+
+export async function getCurTags({ client, config, tenant }) {
+  if (!tenant) throw new Error("A tenant is required to list CUR tags");
+  const query = `
+    SELECT DISTINCT tag_key
+    FROM ${table(config)}
+    CROSS JOIN UNNEST(map_keys(resource_tags)) AS tags(tag_key)
+    WHERE ${tenantWhere(config, tenant)}
+      AND tag_key IS NOT NULL
+      AND TRIM(tag_key) <> ''
+    ORDER BY tag_key
+  `;
+  const rows = await execute(client, config, query);
+  return rows.map((row) => String(row.tag_key || "").replace(/^user:/, "")).filter(Boolean);
+}
+
+export async function getCurFilterOptions({ client, config, tenant, range, tagKey, accountNames = new Map() }) {
+  const distinct = async (column) => execute(client, config, `
+    SELECT DISTINCT CAST("${column}" AS VARCHAR) AS value
+    FROM ${table(config)}
+    WHERE ${tenantWhere(config, tenant)}
+      AND ${rangeWhere(range)}
+      AND line_item_unblended_cost > 0
+      AND "${column}" IS NOT NULL
+      AND TRIM(CAST("${column}" AS VARCHAR)) <> ''
+    ORDER BY 1
+  `);
+  const [services, regions, accounts, tags] = await Promise.all([
+    distinct("product_product_name"),
+    distinct("product_region_code"),
+    distinct("line_item_usage_account_id"),
+    getCurTags({ client, config, tenant }),
+  ]);
+  let tagValues = [];
+  if (tagKey) {
+    tagValues = (await execute(client, config, `
+      SELECT DISTINCT CAST(${cur2TagExpression(tagKey)} AS VARCHAR) AS value
+      FROM ${table(config)}
+      WHERE ${tenantWhere(config, tenant)}
+        AND ${rangeWhere(range)}
+        AND line_item_unblended_cost > 0
+        AND ${cur2TagExpression(tagKey)} IS NOT NULL
+      ORDER BY 1
+    `)).map((row) => row.value).filter(Boolean);
+  }
+  const options = (items, type) => items.map((item) => ({ value: item.value, label: type === "account" ? accountNames.get(item.value) || item.value : item.value }));
+  return {
+    services: options(services),
+    regions: options(regions),
+    accounts: options(accounts, "account"),
+    tagKeys: tagKey ? [] : tags,
+    tagValues,
+    dataSource: "aws-cur-athena",
+    accessMode: "cur-readonly",
+  };
+}

package/src/services/customer-aws-context.service.js

@@ -0,0 +1,62 @@
+import { CostExplorerClient } from "@aws-sdk/client-cost-explorer";
+import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";
+import { CustomerAwsContext } from "../models/customer-aws-context.model.js";
+import { truthy } from "../lib/cost-utils.js";
+
+export class CustomerAwsContextService {
+  constructor({ repository, defaultTenant, env = process.env, credentialProvider = fromTemporaryCredentials, clientFactory = (options) => new CostExplorerClient(options) }) {
+    this.repository = repository;
+    this.defaultTenant = defaultTenant;
+    this.env = env;
+    this.credentialProvider = credentialProvider;
+    this.clientFactory = clientFactory;
+  }
+
+  tenantId(req) {
+    return String(req.user?.tenant_id || req.user?.tenantId || req.headers["x-tenant-id"] || this.defaultTenant).trim() || this.defaultTenant;
+  }
+
+  async resolve(req) {
+    const tenant = this.tenantId(req);
+    const stored = await this.repository.findCostAccess(tenant);
+    let accounts = stored.accounts;
+    const meta = stored.meta;
+    const roleArn = meta.payerRoleArn || meta.crossAccountRoleArn || meta.roleArn || this.env.COST_EXPLORER_ROLE_ARN;
+    const allowEnvCredentials = truthy(this.env.COST_EXPLORER_ALLOW_ENV_CREDENTIALS);
+    const allowRuntimeIdentity = truthy(this.env.COST_EXPLORER_ALLOW_RUNTIME_IDENTITY);
+    const hasEnvCredentials = Boolean(this.env.AWS_ACCESS_KEY_ID && this.env.AWS_SECRET_ACCESS_KEY);
+    const preferEnvCredentials = allowEnvCredentials && hasEnvCredentials && truthy(this.env.COST_EXPLORER_PREFER_ENV_CREDENTIALS);
+    const configuredAccountIds = String(this.env.COST_EXPLORER_ACCOUNT_IDS || "").split(",").map((value) => value.trim()).filter(Boolean);
+
+    if (!accounts.length && allowEnvCredentials && configuredAccountIds.length) {
+      accounts = configuredAccountIds.map((id) => ({ id, name: id, region: "global", status: "testing" }));
+    }
+
+    const credentials = roleArn && !preferEnvCredentials ? this.credentialProvider({
+      params: {
+        RoleArn: roleArn,
+        RoleSessionName: `meyi-cost-${tenant}`.slice(0, 64),
+        ExternalId: meta.externalId || this.env.COST_EXPLORER_EXTERNAL_ID || undefined,
+      },
+    }) : undefined;
+    const client = this.clientFactory({ region: "us-east-1", credentials });
+    const queryEnabled = Boolean(roleArn) || (allowEnvCredentials && hasEnvCredentials) || allowRuntimeIdentity;
+    const accessMode = preferEnvCredentials
+      ? "environment-credentials"
+      : roleArn
+        ? "assumed-customer-role"
+        : allowEnvCredentials && hasEnvCredentials
+          ? "environment-credentials"
+          : allowRuntimeIdentity
+            ? "customer-runtime-identity"
+            : "not-configured";
+
+    return new CustomerAwsContext({ tenant, accounts, client, credentials, meta, roleArn, queryEnabled, accessMode });
+  }
+
+  async recordCurStatus(tenant, status) {
+    if (typeof this.repository.updateCurStatus === "function") {
+      await this.repository.updateCurStatus(tenant, status);
+    }
+  }
+}

package/src/services/saas-athena-context.service.js

@@ -0,0 +1,54 @@
+import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";
+import { truthy } from "../lib/cost-utils.js";
+import { SaasCurContext } from "../models/saas-cur-context.model.js";
+import { CurIngestionDescriptor } from "../models/cur-ingestion.model.js";
+import { createCurClient, getCurConfig } from "./cur.service.js";
+
+export class SaasAthenaContextService {
+  constructor({ env = process.env, credentialProvider = fromTemporaryCredentials, clientFactory = createCurClient } = {}) {
+    this.env = env;
+    this.credentialProvider = credentialProvider;
+    this.clientFactory = clientFactory;
+  }
+
+  resolve(customerContext) {
+    const allowTenantCatalog = truthy(this.env.COST_CUR_ALLOW_TENANT_CATALOG);
+    const tenantMeta = customerContext.meta || {};
+    const ingestion = new CurIngestionDescriptor({ tenant: customerContext.tenant, metadata: tenantMeta, env: this.env });
+    const trustedDiscoveryMeta = tenantMeta.curDiscoveredTable
+      ? { curTable: tenantMeta.curDiscoveredTable }
+      : {};
+    const catalogMeta = allowTenantCatalog ? tenantMeta : trustedDiscoveryMeta;
+    const tenantPartition = String(
+      this.env.COST_CUR_TENANT_PARTITION
+      || ingestion.tenantPartition,
+    ).trim();
+    const resolvedConfig = getCurConfig(this.env, { ...catalogMeta, curTenantPartition: tenantPartition });
+    const roleArn = String(this.env.COST_CUR_ROLE_ARN || "").trim();
+    const customerEnvCredentialsEnabled = truthy(this.env.COST_EXPLORER_ALLOW_ENV_CREDENTIALS)
+      && Boolean(this.env.AWS_ACCESS_KEY_ID && this.env.AWS_SECRET_ACCESS_KEY);
+    const unsafeSharedDefaultChain = customerEnvCredentialsEnabled && !roleArn;
+    const config = unsafeSharedDefaultChain
+      ? Object.freeze({
+        ...resolvedConfig,
+        enabled: false,
+        disabledReason: "A dedicated COST_CUR_ROLE_ARN is required while customer test credentials are enabled.",
+      })
+      : resolvedConfig;
+    const credentials = roleArn ? this.credentialProvider({
+      params: {
+        RoleArn: roleArn,
+        RoleSessionName: `meyi-cur-${customerContext.tenant}`.slice(0, 64),
+        ExternalId: this.env.COST_CUR_EXTERNAL_ID || undefined,
+      },
+    }) : undefined;
+    const client = config.enabled ? this.clientFactory({ config, credentials }) : null;
+    return new SaasCurContext({
+      tenant: customerContext.tenant,
+      config,
+      client,
+      credentialMode: roleArn ? "assumed-saas-cur-role" : "saas-runtime-identity",
+      ingestion,
+    });
+  }
+}