adfinem 0.0.0 → 0.1.1

package/src/config/environments.ts

@@ -0,0 +1,193 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { config as loadDotEnv } from "dotenv";
+import YAML from "yaml";
+
+export interface EnvironmentConfig {
+  name: string;
+  apiBaseUrl?: string;
+  apiTlsInsecure?: boolean;
+  oracle: {
+    user?: string;
+    password?: string;
+    connectString?: string;
+  };
+  sshHosts: Record<string, {
+    host?: string;
+    username?: string;
+    password?: string;
+    privateKeyPath?: string;
+    shell?: string;
+    loginShell?: boolean;
+  }>;
+}
+
+export interface EditableEnvironmentConfig {
+  apiBaseUrl?: string;
+  apiTlsInsecure?: boolean;
+  oracle?: {
+    user?: string;
+    password?: string;
+    connectString?: string;
+  };
+  sshHosts?: Record<string, {
+    host?: string;
+    username?: string;
+    password?: string;
+    privateKeyPath?: string;
+    shell?: string;
+    loginShell?: boolean;
+  }>;
+}
+
+export type EnvironmentFile = Record<string, EditableEnvironmentConfig>;
+
+export function getEnvironment(name?: string, rootDir = process.cwd()): EnvironmentConfig {
+  loadWorkspaceDotEnv(rootDir);
+  const resolvedName = name || process.env.ADFINEM_ENV || "local";
+  const raw = readFileSync(environmentConfigPath(rootDir), "utf8");
+  const configs = interpolateEnv(YAML.parse(raw)) as Record<string, EnvironmentConfig>;
+  const config = configs[resolvedName];
+
+  if (!config) {
+    const available = Object.keys(configs).filter((key) => key && typeof configs[key] === "object");
+    const suffix = available.length
+      ? ` Available: ${available.join(", ")}.`
+      : " No environments are defined yet.";
+    throw new Error(`Unknown environment '${resolvedName}'.${suffix} Add it to config/environments.yaml or pass --env.`);
+  }
+
+  return {
+    name: resolvedName,
+    apiBaseUrl: blankToUndefined(config.apiBaseUrl),
+    apiTlsInsecure: booleanValue(config.apiTlsInsecure),
+    oracle: {
+      user: blankToUndefined(config.oracle?.user),
+      password: blankToUndefined(config.oracle?.password),
+      connectString: blankToUndefined(config.oracle?.connectString)
+    },
+    sshHosts: Object.fromEntries(Object.entries(config.sshHosts ?? {}).map(([hostRef, host]) => [hostRef, {
+      host: blankToUndefined(host.host),
+      username: blankToUndefined(host.username),
+      password: blankToUndefined(host.password),
+      privateKeyPath: blankToUndefined(host.privateKeyPath),
+      shell: blankToUndefined(host.shell),
+      loginShell: booleanValue(host.loginShell)
+    }]))
+  };
+}
+
+export function listEnvironmentNames(rootDir = process.cwd()): string[] {
+  try {
+    return Object.keys(loadEnvironmentFile(rootDir));
+  } catch {
+    return [];
+  }
+}
+
+export function environmentConfigPath(rootDir = process.cwd()): string {
+  return join(rootDir, "config", "environments.yaml");
+}
+
+export function loadEnvironmentFile(rootDir = process.cwd()): EnvironmentFile {
+  loadWorkspaceDotEnv(rootDir);
+  const raw = readFileSync(environmentConfigPath(rootDir), "utf8");
+  const parsed = YAML.parse(raw) as Record<string, unknown> | null;
+  if (!parsed || typeof parsed !== "object") return {};
+  return Object.fromEntries(
+    Object.entries(parsed)
+      .filter(([name, value]) => name && value && typeof value === "object" && !Array.isArray(value))
+      .map(([name, value]) => [name, normalizeEditableEnvironment(value as Record<string, unknown>)])
+  );
+}
+
+export async function writeEnvironmentFile(rootDir: string, environments: EnvironmentFile): Promise<void> {
+  const outputPath = environmentConfigPath(rootDir);
+  const normalized = Object.fromEntries(
+    Object.entries(environments)
+      .filter(([name]) => isValidEnvironmentName(name))
+      .map(([name, config]) => [name, normalizeEditableEnvironment(config as Record<string, unknown>)])
+  );
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, YAML.stringify(normalized, { defaultKeyType: "PLAIN", defaultStringType: "QUOTE_DOUBLE" }), "utf8");
+}
+
+export function isValidEnvironmentName(name: string): boolean {
+  return /^[A-Za-z][A-Za-z0-9_-]*$/.test(name);
+}
+
+export function assertValidEnvironmentName(name: string): void {
+  if (!isValidEnvironmentName(name)) {
+    throw new Error("Environment name must start with a letter and contain only letters, numbers, underscore, or hyphen.");
+  }
+}
+
+function interpolateEnv(value: unknown): unknown {
+  if (typeof value === "string") {
+    return value.replace(/\$\{([A-Za-z0-9_]+)\}/g, (_match, name: string) => process.env[name] ?? "");
+  }
+  if (Array.isArray(value)) return value.map(interpolateEnv);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, interpolateEnv(entry)]));
+  }
+  return value;
+}
+
+function loadWorkspaceDotEnv(rootDir: string): void {
+  loadDotEnv({ path: join(rootDir, ".env"), override: true });
+}
+
+function blankToUndefined(value: string | undefined): string | undefined {
+  return value && value.trim() ? value : undefined;
+}
+
+function normalizeEditableEnvironment(value: Record<string, unknown>): EditableEnvironmentConfig {
+  const oracle = objectValue(value.oracle);
+  const sshHosts = objectValue(value.sshHosts);
+  return {
+    apiBaseUrl: optionalString(value.apiBaseUrl),
+    apiTlsInsecure: optionalBoolean(value.apiTlsInsecure),
+    oracle: {
+      user: optionalString(oracle?.user),
+      password: optionalString(oracle?.password),
+      connectString: optionalString(oracle?.connectString)
+    },
+    sshHosts: Object.fromEntries(
+      Object.entries(sshHosts ?? {})
+        .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
+        .map(([hostRef, entry]) => {
+          const host = entry as Record<string, unknown>;
+          return [hostRef, {
+            host: optionalString(host.host),
+            username: optionalString(host.username),
+            password: optionalString(host.password),
+            privateKeyPath: optionalString(host.privateKeyPath),
+            shell: optionalString(host.shell),
+            loginShell: optionalBoolean(host.loginShell)
+          }];
+        })
+    )
+  };
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return value === undefined || value === null ? undefined : String(value);
+}
+
+function optionalBoolean(value: unknown): boolean | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "boolean") return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return undefined;
+}
+
+function booleanValue(value: unknown): boolean | undefined {
+  return optionalBoolean(value);
+}

package/src/config/registry.ts

@@ -0,0 +1,23 @@
+export interface RegisteredAction {
+  layer: "api" | "db" | "unix" | "engine";
+  supportedVia: string[];
+}
+
+export const registeredActions: Record<string, RegisteredAction> = {
+  db_assert: {
+    layer: "db",
+    supportedVia: ["db"]
+  },
+  db_query: {
+    layer: "db",
+    supportedVia: ["db"]
+  },
+  db_execute: {
+    layer: "db",
+    supportedVia: ["db"]
+  },
+  unix_batch: {
+    layer: "unix",
+    supportedVia: ["unix"]
+  }
+};

package/src/config/secrets.ts

@@ -0,0 +1,128 @@
+import type { EvidenceVisibilityMode } from "../dsl/types.js";
+
+const secretKeyFragments = [
+  "password",
+  "passwd",
+  "pwd",
+  "token",
+  "authorization",
+  "apikey",
+  "api_key",
+  "privatekey",
+  "private_key",
+  "jwt",
+  "secret",
+  "credential",
+  "bearer",
+  "access_token",
+  "refreshtoken",
+  "refresh_token",
+  "servicepassword",
+  "apikey",
+  "session",
+  "cookie",
+  "pin",
+  "cvv",
+  "cvc",
+  "cvv2"
+];
+
+const cardKeyExact = new Set([
+  "pan",
+  "pans",
+  "cardnumber",
+  "cardnumbers",
+  "cardno",
+  "primaryaccountnumber",
+  "primaryaccountnumbers"
+]);
+
+const REDACTED = "<redacted>";
+
+export function redactSecrets<T>(value: T): T {
+  return redact(value) as T;
+}
+
+export function evidenceVisibilityMode(): EvidenceVisibilityMode {
+  return process.env.ADFINEM_EVIDENCE_VISIBILITY?.toLowerCase() === "redacted" ? "redacted" : "raw";
+}
+
+export function applyEvidenceVisibility<T>(value: T, mode: EvidenceVisibilityMode = evidenceVisibilityMode()): T {
+  return mode === "redacted" ? redactSecrets(value) : value;
+}
+
+/**
+ * Heavier redaction intended for shared evidence artifacts.
+ * Combines key-based redaction with inline PAN-pattern scrubbing on every string.
+ */
+export function redactEvidence<T>(value: T): T {
+  return redactDeep(value, true) as T;
+}
+
+export function maskInlinePans(text: string): string {
+  if (!text) return text;
+  return text.replace(/(?<!\d)(\d[\d\s.-]{10,21}\d)(?!\d)/g, (match) => {
+    const digits = match.replace(/\D+/g, "");
+    if (digits.length < 12 || digits.length > 19) return match;
+    if (!isLuhnValid(digits)) return match;
+    return `****${digits.slice(-4)}`;
+  });
+}
+
+export function isLuhnValid(digits: string): boolean {
+  if (!/^\d+$/.test(digits)) return false;
+  let sum = 0;
+  let alt = false;
+  for (let index = digits.length - 1; index >= 0; index--) {
+    let n = digits.charCodeAt(index) - 48;
+    if (alt) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alt = !alt;
+  }
+  return sum > 0 && sum % 10 === 0;
+}
+
+function redact(value: unknown): unknown {
+  return redactDeep(value, false);
+}
+
+function redactDeep(value: unknown, scrubStrings: boolean): unknown {
+  if (typeof value === "string") return scrubStrings ? maskInlinePans(value) : value;
+  if (Array.isArray(value)) return value.map((entry) => redactDeep(entry, scrubStrings));
+  if (!value || typeof value !== "object") return value;
+
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+    const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (secretKeyFragments.some((fragment) => normalized.includes(fragment))) {
+      return [key, REDACTED];
+    }
+    if (cardKeyExact.has(normalized)) {
+      return [key, maskCardLike(entry, scrubStrings)];
+    }
+    return [key, redactDeep(entry, scrubStrings)];
+  }));
+}
+
+function maskCardLike(value: unknown, scrubStrings: boolean): unknown {
+  if (Array.isArray(value)) return value.map((entry) => maskCardLike(entry, scrubStrings));
+  if (typeof value === "string" || typeof value === "number") {
+    return maskPan(String(value));
+  }
+  if (value && typeof value === "object") {
+    return redactDeep(value, scrubStrings);
+  }
+  return value;
+}
+
+function maskPan(value: string): string {
+  const digits = value.replace(/\D+/g, "");
+  if (digits.length < 12) return value;
+  if (digits.length >= 12 && digits.length <= 19) {
+    return `${digits.slice(0, 4)}${"*".repeat(Math.max(4, digits.length - 8))}${digits.slice(-4)}`;
+  }
+  const last4 = digits.slice(-4);
+  return `****${last4}`;
+}

package/src/dsl/parser.ts

@@ -0,0 +1,24 @@
+import { readFile } from "node:fs/promises";
+import YAML from "yaml";
+import { scenarioSchema, queryCatalogSchema, batchCatalogSchema, apiOperationsCatalogSchema } from "./schema.js";
+import type { Catalogs, QueryCatalogEntry, Scenario } from "./types.js";
+import { importedOperationsFromCollections, loadApiCollections } from "../adapters/api/api-collections.js";
+import { normalizeQueryCatalog } from "../adapters/db/query-catalog.js";
+
+export async function loadYamlFile<T>(path: string): Promise<T> {
+  const raw = await readFile(path, "utf8");
+  return YAML.parse(raw) as T;
+}
+
+export async function loadScenario(path: string): Promise<Scenario> {
+  const parsed = await loadYamlFile<unknown>(path);
+  return scenarioSchema.parse(parsed) as Scenario;
+}
+
+export async function loadCatalogs(rootDir: string): Promise<Catalogs> {
+  const queries = normalizeQueryCatalog(queryCatalogSchema.parse(await loadYamlFile<unknown>(`${rootDir}/catalogs/queries.yaml`)) as Record<string, QueryCatalogEntry>);
+  const batches = batchCatalogSchema.parse(await loadYamlFile<unknown>(`${rootDir}/catalogs/batches.yaml`));
+  const apiOperations = apiOperationsCatalogSchema.parse(await loadYamlFile<unknown>(`${rootDir}/catalogs/api-operations.yaml`));
+  const importedApiOperations = importedOperationsFromCollections(await loadApiCollections(rootDir));
+  return { queries, batches, apiOperations: { ...apiOperations, ...importedApiOperations } } as Catalogs;
+}

package/src/dsl/schema.ts

@@ -0,0 +1,189 @@
+import { z } from "zod";
+
+const value = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const catalogParamType = z.enum(["string", "number", "boolean", "string[]", "number[]", "boolean[]"]);
+const apiMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const apiBodyMode = z.enum(["none", "json", "raw", "formdata", "urlencoded"]);
+const apiRequestSpecSchema = z.object({
+  method: apiMethod.optional(),
+  path: z.string().optional(),
+  headers: z.record(z.string()).optional(),
+  query: z.record(z.unknown()).optional(),
+  body: z.unknown().optional(),
+  rawBody: z.string().optional(),
+  bodyMode: apiBodyMode.optional(),
+  auth: z.unknown().optional(),
+  acceptStatuses: z.array(z.number().int().min(100).max(599)).optional()
+}).strict();
+const apiAssertionSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("status"),
+    operator: z.enum(["in", "="]).optional(),
+    value: z.union([z.number().int().min(100).max(599), z.array(z.number().int().min(100).max(599))])
+  }).strict(),
+  z.object({ type: z.literal("jsonpath_exists"), path: z.string().min(1) }).strict(),
+  z.object({ type: z.literal("jsonpath_equals"), path: z.string().min(1), value: z.unknown() }).strict(),
+  z.object({ type: z.literal("jsonpath_contains"), path: z.string().min(1), value: z.unknown() }).strict(),
+  z.object({ type: z.literal("header_exists"), header: z.string().min(1) }).strict(),
+  z.object({ type: z.literal("header_equals"), header: z.string().min(1), value: z.string() }).strict(),
+  z.object({ type: z.literal("body_contains"), value: z.string() }).strict(),
+  z.object({ type: z.literal("body_not_contains"), value: z.string() }).strict()
+]);
+const expectedOutcomeSchema = z.enum(["positive", "negative", "setup", "teardown"]);
+const parallelJoinModeSchema = z.enum(["all", "any", "fail_fast"]);
+const loopDateFormatSchema = z.enum(["YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY"]);
+const loopDateCursorSchema = z.object({
+  outputName: z.string().min(1).optional(),
+  start: z.string().min(1).optional(),
+  inputFormat: loopDateFormatSchema.optional(),
+  outputFormat: loopDateFormatSchema.optional(),
+  advance: z.object({
+    mode: z.enum(["days", "months", "nth_day_of_month", "first_of_month", "end_of_month"]),
+    amount: z.number().int().positive().optional(),
+    day: z.number().int().min(1).max(31).optional()
+  }).strict().optional()
+}).strict();
+const loopSpecSchema = z.object({
+  mode: z.enum(["count", "foreach"]),
+  count: z.union([z.number().int().nonnegative(), z.string()]).optional(),
+  items: z.unknown().optional(),
+  itemName: z.string().min(1).optional(),
+  maxIterations: z.number().int().positive().optional(),
+  dateCursor: loopDateCursorSchema.optional()
+}).strict();
+const catalogParamSchema = z.object({
+  required: z.boolean().optional(),
+  type: catalogParamType.optional(),
+  pattern: z.string().optional(),
+  luhn: z.boolean().optional()
+}).strict();
+const batchInputFileSchema = z.object({
+  name: z.string().min(1),
+  required: z.boolean().optional(),
+  remotePath: z.string().min(1).optional(),
+  paramName: z.string().min(1).optional(),
+  appendAsArg: z.boolean().optional()
+}).strict();
+const batchOutputFileSchema = z.object({
+  name: z.string().min(1),
+  required: z.boolean().optional(),
+  source: z.enum(["stdout", "stderr", "both", "explicit"]).optional(),
+  pathPattern: z.string().min(1).optional(),
+  remotePath: z.string().min(1).optional(),
+  download: z.boolean().optional(),
+  decrypt: z.object({
+    command: z.string().min(1).optional(),
+    outputRemotePath: z.string().min(1).optional(),
+    required: z.boolean().optional()
+  }).strict().optional()
+}).strict();
+
+export const scenarioStepSchema: z.ZodType<unknown> = z.lazy(() => z.object({
+  id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+  action: z.string().min(1),
+  via: z.string().optional(),
+  retry: z.object({
+    attempts: z.number().int().positive().optional(),
+    delaySeconds: z.number().nonnegative().optional()
+  }).strict().optional(),
+  input: z.record(z.unknown()).optional(),
+  params: z.record(z.unknown()).optional(),
+  query: z.string().optional(),
+  batch: z.string().optional(),
+  request: apiRequestSpecSchema.optional(),
+  assertions: z.array(apiAssertionSchema).optional(),
+  capture: z.record(z.string()).optional(),
+  continueOnFailure: z.boolean().optional(),
+  expectedOutcome: expectedOutcomeSchema.optional(),
+  captureOnFailure: z.boolean().optional(),
+  control: z.enum(["parallel", "loop"]).optional(),
+  branches: z.array(z.object({
+    id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+    label: z.string().min(1).optional(),
+    steps: z.array(scenarioStepSchema)
+  }).strict()).optional(),
+  steps: z.array(scenarioStepSchema).optional(),
+  loop: loopSpecSchema.optional(),
+  join: parallelJoinModeSchema.optional()
+}).strict());
+
+export const scenarioSchema = z.object({
+  id: z.string().min(1).regex(/^[A-Za-z0-9_-]+$/),
+  environment: z.string().min(1),
+  tenant: z.record(z.string()).optional(),
+  variables: z.record(z.union([value, z.array(value), z.record(value)])).optional(),
+  steps: z.array(scenarioStepSchema).min(1)
+}).strict();
+
+export const queryCatalogSchema = z.record(z.object({
+  description: z.string().optional(),
+  mode: z.enum(["query", "execute"]).optional(),
+  sql: z.string().min(1),
+  params: z.record(catalogParamSchema).optional(),
+  expect: z.object({
+    type: z.enum(["number", "string", "boolean", "rowCount"]),
+    column: z.string().optional(),
+    operator: z.enum(["=", "!=", ">", ">=", "<", "<=", "contains"]),
+    value: z.unknown()
+  }).strict()
+    .refine((expect) => expect.type === "rowCount" || Boolean(expect.column), {
+      message: "expect.column is required when expect.type is not rowCount."
+    })
+    .optional(),
+  captures: z.record(z.string()).optional(),
+  maxRows: z.number().int().positive().optional()
+}).strict());
+
+export const batchCatalogSchema = z.record(z.object({
+  description: z.string().optional(),
+  hostRef: z.string().min(1),
+  command: z.string().min(1).refine((value) => !/[\r\n]/.test(value), {
+    message: "command must be a single executable token; put arguments in fixedArgs."
+  }),
+  fixedArgs: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
+  workingDirectory: z.string().min(1).optional(),
+  useWorkingDirectory: z.boolean().optional(),
+  environment: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  args: z.array(z.object({
+    name: z.string().min(1),
+    required: z.boolean().optional(),
+    type: catalogParamType.optional(),
+    pattern: z.string().optional(),
+    luhn: z.boolean().optional()
+  }).strict()).optional(),
+  inputFiles: z.array(batchInputFileSchema).optional(),
+  outputFiles: z.array(batchOutputFileSchema).optional(),
+  timeoutSeconds: z.number().int().positive().optional(),
+  success: z.object({
+    exitCodes: z.array(z.number().int()).optional(),
+    requiredOutput: z.array(z.string()).optional()
+  }).strict().optional(),
+  captures: z.record(z.string()).optional()
+}).strict());
+
+export const apiOperationsCatalogSchema = z.record(z.object({
+  description: z.string().optional(),
+  type: z.enum(["rest", "soap"]),
+  method: apiMethod.optional(),
+  path: z.string().optional(),
+  headers: z.record(z.string()).optional(),
+  query: z.record(z.unknown()).optional(),
+  body: z.unknown().optional(),
+  rawBody: z.string().optional(),
+  bodyMode: apiBodyMode.optional(),
+  auth: z.unknown().optional(),
+  params: z.record(catalogParamSchema).optional(),
+  assertions: z.array(apiAssertionSchema).optional(),
+  requestTemplate: z.string().optional(),
+  captures: z.record(z.string()).optional(),
+  acceptStatuses: z.array(z.number().int().min(100).max(599)).optional(),
+  idempotent: z.boolean().optional(),
+  source: z.object({
+    collectionId: z.string().optional(),
+    collectionName: z.string().optional(),
+    requestId: z.string().optional(),
+    folderPath: z.array(z.string()).optional()
+  }).strict().optional()
+}).strict());
+
+export { apiRequestSpecSchema, apiAssertionSchema };