@ankhorage/infra 6.0.0 → 7.1.0

package/src/features/environment-lifecycle/adapters/outbound/createProjectInfraCredentialPort.ts

@@ -0,0 +1,182 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import type { AppEnvironmentId } from '@ankhorage/contracts/environments';
+import type {
+  InfraControlPlaneCredentialRef,
+  InfraCredentialPort,
+  InfraResult,
+} from '@ankhorage/contracts/infra';
+import { isRecord, isRecordOf } from '@ankhorage/utility/object';
+
+import { createInfraFailure } from '../../utils/createInfraFailure.js';
+import { normalizeInfraEnvironmentKey } from '../../utils/normalizeInfraEnvironmentKey.js';
+import { resolveInfraEnvironmentStateDirectory } from '../../utils/resolveInfraEnvironmentStateDirectory.js';
+import { createEnvironmentInfraCredentialPort } from './createEnvironmentInfraCredentialPort.js';
+
+/*** Resolve explicit environment overrides before durable project-local bootstrap credentials. */
+export function createProjectInfraCredentialPort(
+  options: ProjectInfraCredentialPortOptions,
+): InfraCredentialPort {
+  const environmentPort = createEnvironmentInfraCredentialPort(options.processEnvironment);
+  return {
+    findAsync: (reference) => findProjectCredentialAsync(options, environmentPort, reference),
+    async resolveAsync(reference) {
+      const found = await findProjectCredentialAsync(options, environmentPort, reference);
+      if (!found.ok) return found;
+      if (found.value !== null) {
+        return { ok: true, value: found.value, diagnostics: found.diagnostics };
+      }
+      return missingCredential(reference.name);
+    },
+    async persistAsync(reference, values) {
+      if (!isStringRecord(values)) {
+        return createInfraFailure(
+          'infra-control-plane-credential-invalid',
+          `Control-plane credential ${reference.name} must contain only string fields.`,
+        );
+      }
+      return writeStoredCredentialAsync(options, reference, values);
+    },
+  };
+}
+
+interface ProjectInfraCredentialPortOptions {
+  readonly projectPath: string;
+  readonly environment: AppEnvironmentId;
+  readonly processEnvironment: Readonly<Record<string, string | undefined>>;
+}
+
+interface StoredCredentialBundle {
+  readonly schemaVersion: 1;
+  readonly name: string;
+  readonly values: Readonly<Record<string, string>>;
+}
+
+/*** Resolve environment precedence before falling through to project-local state. */
+async function findProjectCredentialAsync(
+  options: ProjectInfraCredentialPortOptions,
+  environmentPort: InfraCredentialPort,
+  reference: InfraControlPlaneCredentialRef,
+): Promise<InfraResult<Readonly<Record<string, string>> | null>> {
+  const overridden = await environmentPort.findAsync(reference);
+  if (!overridden.ok || overridden.value !== null) return overridden;
+  return readStoredCredentialAsync(options, reference);
+}
+
+/*** Read one exact credential bundle without enumerating or exposing sibling credentials. */
+async function readStoredCredentialAsync(
+  options: ProjectInfraCredentialPortOptions,
+  reference: InfraControlPlaneCredentialRef,
+): Promise<InfraResult<Readonly<Record<string, string>> | null>> {
+  const credentialPath = resolveCredentialPath(options, reference.name);
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(credentialPath, 'utf8'));
+    if (!isStoredCredentialBundle(parsed) || parsed.name !== reference.name) {
+      return invalidCredentialStore(reference.name);
+    }
+    return { ok: true, value: parsed.values, diagnostics: [] };
+  } catch (error) {
+    if (isMissingFile(error)) return { ok: true, value: null, diagnostics: [] };
+    if (error instanceof SyntaxError) return invalidCredentialStore(reference.name);
+    return createInfraFailure(
+      'infra-control-plane-credential-store-read-failed',
+      `Control-plane credential ${reference.name} could not be read from project state.`,
+    );
+  }
+}
+
+/*** Persist one opaque bundle atomically with restrictive local-host permissions. */
+async function writeStoredCredentialAsync(
+  options: ProjectInfraCredentialPortOptions,
+  reference: InfraControlPlaneCredentialRef,
+  values: Readonly<Record<string, string>>,
+): Promise<InfraResult<null>> {
+  const credentialPath = resolveCredentialPath(options, reference.name);
+  const directory = path.dirname(credentialPath);
+  const temporaryPath = `${credentialPath}.${process.pid}.${randomUUID()}.tmp`;
+  const stored: StoredCredentialBundle = { schemaVersion: 1, name: reference.name, values };
+  try {
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    await restrictPermissionsAsync(directory, 0o700);
+    await fs.writeFile(temporaryPath, `${JSON.stringify(stored, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    await fs.rename(temporaryPath, credentialPath);
+    await restrictPermissionsAsync(credentialPath, 0o600);
+    return { ok: true, value: null, diagnostics: [] };
+  } catch {
+    await removeTemporaryCredentialAsync(temporaryPath);
+    return createInfraFailure(
+      'infra-control-plane-credential-store-write-failed',
+      `Control-plane credential ${reference.name} could not be persisted to project state.`,
+    );
+  }
+}
+
+/*** Remove an abandoned unique temporary credential file without masking the original write failure. */
+async function removeTemporaryCredentialAsync(temporaryPath: string): Promise<void> {
+  try {
+    await fs.rm(temporaryPath, { force: true });
+  } catch {
+    return;
+  }
+}
+
+/*** Resolve one credential to an opaque hash-named file inside its project/environment scope. */
+function resolveCredentialPath(options: ProjectInfraCredentialPortOptions, name: string): string {
+  const digest = createHash('sha256').update(name).digest('hex');
+  return path.join(
+    resolveInfraEnvironmentStateDirectory(options.projectPath, options.environment),
+    'credentials',
+    `${digest}.json`,
+  );
+}
+
+/*** Apply owner-only permissions where the host platform supports POSIX file modes. */
+async function restrictPermissionsAsync(targetPath: string, mode: number): Promise<void> {
+  if (process.platform !== 'win32') await fs.chmod(targetPath, mode);
+}
+
+/*** Create the canonical missing-credential diagnostic after every trusted source was checked. */
+function missingCredential(name: string): InfraResult<never> {
+  const prefixedName = `ANKH_INFRA_CREDENTIAL_${normalizeInfraEnvironmentKey(name)}`;
+  return createInfraFailure(
+    'infra-control-plane-credential-missing',
+    `Control-plane credential ${name} is unavailable. Set ${name} or ${prefixedName}.`,
+  );
+}
+
+/*** Reject malformed persisted state without exposing or replacing any stored value. */
+function invalidCredentialStore(name: string): InfraResult<never> {
+  return createInfraFailure(
+    'infra-control-plane-credential-store-invalid',
+    `Stored control-plane credential ${name} has an invalid project-state shape.`,
+  );
+}
+
+/*** Recognize the private stored credential record. */
+function isStoredCredentialBundle(value: unknown): value is StoredCredentialBundle {
+  if (!isRecord(value)) return false;
+  return (
+    value.schemaVersion === 1 && typeof value.name === 'string' && isStringRecord(value.values)
+  );
+}
+
+/*** Recognize string-only opaque provider credential bundles. */
+function isStringRecord(value: unknown): value is Readonly<Record<string, string>> {
+  return isRecordOf(value, isString);
+}
+
+/*** Narrow one unknown value to a string. */
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/*** Recognize only the filesystem's absent-file failure. */
+function isMissingFile(error: unknown): boolean {
+  return isRecord(error) && error.code === 'ENOENT';
+}

package/src/features/environment-lifecycle/adapters/outbound/removeStoredInfraCredentialsAsync.ts

@@ -0,0 +1,18 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import type { AppEnvironmentId } from '@ankhorage/contracts/environments';
+
+import { resolveInfraEnvironmentStateDirectory } from '../../utils/resolveInfraEnvironmentStateDirectory.js';
+
+/*** Remove only persisted generated credential state for one explicit project environment. */
+export async function removeStoredInfraCredentialsAsync(
+  projectPath: string,
+  environment: AppEnvironmentId,
+): Promise<void> {
+  const credentialDirectory = path.join(
+    resolveInfraEnvironmentStateDirectory(projectPath, environment),
+    'credentials',
+  );
+  await fs.rm(credentialDirectory, { recursive: true, force: true });
+}

package/src/features/environment-lifecycle/application/use-cases/prepareInfraServicesAsync.ts

@@ -0,0 +1,23 @@
+import type {
+  InfraDiagnostic,
+  InfraExecutionContext,
+  InfraResult,
+  InfraServiceAdapter,
+} from '@ankhorage/contracts/infra';
+
+import { appendInfraFailure } from '../../utils/appendInfraFailure.js';
+
+/*** Run optional mutating service preparation before runtime workload materialization. */
+export async function prepareInfraServicesAsync(
+  context: InfraExecutionContext,
+  services: readonly InfraServiceAdapter[],
+): Promise<InfraResult<null>> {
+  const diagnostics: InfraDiagnostic[] = [];
+  for (const service of services) {
+    if (service.prepareAsync === undefined) continue;
+    const prepared = await service.prepareAsync(context);
+    if (!prepared.ok) return appendInfraFailure(diagnostics, prepared);
+    diagnostics.push(...prepared.diagnostics);
+  }
+  return { ok: true, value: null, diagnostics };
+}

package/src/features/environment-lifecycle/application/use-cases/upInfraEnvironmentAsync.ts

@@ -18,10 +18,11 @@ import { createInfraExecutionContext } from '../../utils/createInfraExecutionCon
 import { createInfraLedger } from '../../utils/createInfraLedger.js';
 import { mergeInfraOutputs } from '../../utils/mergeInfraOutputs.js';
 import { collectInfraWorkloadsAsync } from './collectInfraWorkloadsAsync.js';
+import { prepareInfraServicesAsync } from './prepareInfraServicesAsync.js';
 import { resolveInfraAdaptersAsync } from './resolveInfraAdaptersAsync.js';
 import { validateInfraAdaptersAsync } from './validateInfraAdaptersAsync.js';
 
-/*** Validate and reconcile compute, contributed workloads, runtime and services in dependency order. */
+/*** Validate and reconcile compute, service preparation, workloads, runtime and services in order. */
 export async function upInfraEnvironmentAsync(
   request: InfraUpRequest,
   dependencies: InfraOrchestrationDependencies,
@@ -43,15 +44,18 @@ export async function upInfraEnvironmentAsync(
   const validation = await validateInfraAdaptersAsync(context, adapters.value);
   if (!validation.ok) return appendInfraFailure(diagnostics, validation);
   diagnostics.push(...validation.diagnostics);
-  const workloads = await collectInfraWorkloadsAsync(context, adapters.value.services);
-  if (!workloads.ok) return appendInfraFailure(diagnostics, workloads);
-  diagnostics.push(...workloads.diagnostics);
   const compute = await adapters.value.compute.ensureAsync(
     context,
     environment.value.desired.deployment.compute,
   );
   if (!compute.ok) return appendInfraFailure(diagnostics, compute);
   diagnostics.push(...compute.diagnostics);
+  const preparation = await prepareInfraServicesAsync(context, adapters.value.services);
+  if (!preparation.ok) return appendInfraFailure(diagnostics, preparation);
+  diagnostics.push(...preparation.diagnostics);
+  const workloads = await collectInfraWorkloadsAsync(context, adapters.value.services);
+  if (!workloads.ok) return appendInfraFailure(diagnostics, workloads);
+  diagnostics.push(...workloads.diagnostics);
   const runtimeDesired = {
     selection: environment.value.desired.deployment.runtime,
     targets: compute.value.targets,

package/src/features/environment-lifecycle/composition/createInfraCommandServices.ts

@@ -1,8 +1,9 @@
 import type { InfraCommandServices } from '../../../types/infraCli.js';
-import { createEnvironmentInfraCredentialPort } from '../adapters/outbound/createEnvironmentInfraCredentialPort.js';
 import { createEnvironmentInfraSecretPort } from '../adapters/outbound/createEnvironmentInfraSecretPort.js';
 import { createNodeInfraAdapterPackageResolver } from '../adapters/outbound/createNodeInfraAdapterPackageResolver.js';
+import { createProjectInfraCredentialPort } from '../adapters/outbound/createProjectInfraCredentialPort.js';
 import { readStoredInfraStateAsync } from '../adapters/outbound/readStoredInfraStateAsync.js';
+import { removeStoredInfraCredentialsAsync } from '../adapters/outbound/removeStoredInfraCredentialsAsync.js';
 import { removeStoredInfraStateAsync } from '../adapters/outbound/removeStoredInfraStateAsync.js';
 import { resolveInfraProjectAsync } from '../adapters/outbound/resolveInfraProjectAsync.js';
 import { writeInfraGeneratedArtifactsAsync } from '../adapters/outbound/writeInfraGeneratedArtifactsAsync.js';
@@ -25,6 +26,7 @@ export function createInfraCommandServices(
     readState: overrides.readState ?? readStoredInfraStateAsync,
     writeState: overrides.writeState ?? writeStoredInfraStateAsync,
     removeState: overrides.removeState ?? removeStoredInfraStateAsync,
+    removeCredentials: overrides.removeCredentials ?? removeStoredInfraCredentialsAsync,
     writeArtifacts: overrides.writeArtifacts ?? writeInfraGeneratedArtifactsAsync,
     operations: overrides.operations ?? {
       validate: validateInfraEnvironmentAsync,
@@ -38,9 +40,13 @@ export function createInfraCommandServices(
     },
     createDependencies:
       overrides.createDependencies ??
-      ((context) => ({
+      ((context, scope) => ({
         adapterResolver: createNodeInfraAdapterPackageResolver(),
-        credentials: createEnvironmentInfraCredentialPort(context.env),
+        credentials: createProjectInfraCredentialPort({
+          projectPath: scope.projectPath,
+          environment: scope.environment,
+          processEnvironment: context.env,
+        }),
         secrets: createEnvironmentInfraSecretPort(context.env),
       })),
   };

package/src/features/environment-lifecycle/composition/createProjectInfraLifecycle.ts

@@ -1,9 +1,10 @@
-import type { InfraEnvironmentSpec, InfraManifest } from '@ankhorage/contracts/infra';
+import type { InfraEnvironmentSpec, InfraManifest, InfraResult } from '@ankhorage/contracts/infra';
 
 import { INFRA_PACKAGE_VERSION } from '../../../constants.js';
 import type { InfraOperationRequest, InfraStoredState } from '../../../types/infraOrchestration.js';
 import type {
   CreateProjectInfraLifecycleOptions,
+  ProjectInfraDestroyRequest,
   ProjectInfraLifecycle,
   ProjectInfraOperationRequest,
 } from '../../../types/infraProject.js';
@@ -72,6 +73,9 @@ export function createProjectInfraLifecycle(
     async destroyAsync(request) {
       const state = await services.readState(request.projectPath, request.environment);
       if (state === null) {
+        const safety = validateCredentialStateDestroy(request);
+        if (!safety.ok) return safety;
+        await services.removeCredentials(request.projectPath, request.environment);
         return {
           ok: true,
           value: { environment: request.environment, ledger: null },
@@ -89,9 +93,10 @@ export function createProjectInfraLifecycle(
       );
       if (!result.ok) return result;
       await services.writeArtifacts(request.projectPath, [], prepared.state?.ledger);
-      if (result.value.ledger === null)
+      if (result.value.ledger === null) {
         await services.removeState(request.projectPath, request.environment);
-      else {
+        await services.removeCredentials(request.projectPath, request.environment);
+      } else {
         await services.writeState(request.projectPath, {
           schemaVersion: 1,
           desired: prepared.desired,
@@ -142,10 +147,34 @@ async function prepareProjectOperationAsync(
       ...(state === null ? {} : { previous: state.ledger, previousDesired: state.desired }),
       ...(request.signal === undefined ? {} : { signal: request.signal }),
     },
-    dependencies: services.createDependencies(context),
+    dependencies: services.createDependencies(context, {
+      projectPath: request.projectPath,
+      environment: request.environment,
+    }),
   };
 }
 
+/*** Require exact scope confirmation before deleting orphaned project credential state. */
+function validateCredentialStateDestroy(request: ProjectInfraDestroyRequest): InfraResult<null> {
+  if (
+    request.confirmation.projectId !== request.projectId ||
+    request.confirmation.environment !== request.environment
+  ) {
+    return {
+      ok: false,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'infra-destroy-confirmation-mismatch',
+          message:
+            'Infra destroy confirmation must exactly match the selected project and environment.',
+        },
+      ],
+    };
+  }
+  return { ok: true, value: null, diagnostics: [] };
+}
+
 /*** Read one exact environment without inventing a fallback. */
 function readEnvironment(
   manifest: InfraManifest,

package/src/features/environment-lifecycle/utils/resolveInfraEnvironmentStateDirectory.ts

@@ -0,0 +1,16 @@
+import type { AppEnvironmentId } from '@ankhorage/contracts/environments';
+import { APP_ENVIRONMENT_IDS } from '@ankhorage/contracts/environments';
+import path from 'path';
+
+/*** Build the canonical project-local state directory for one closed Infra environment. */
+export function resolveInfraEnvironmentStateDirectory(
+  projectPath: string,
+  environment: AppEnvironmentId,
+): string {
+  if (!APP_ENVIRONMENT_IDS.includes(environment)) {
+    throw new Error(`Invalid Infra state environment: ${environment}`);
+  }
+  return path.join(projectPath, INFRA_STATE_ROOT, environment);
+}
+
+const INFRA_STATE_ROOT = '.ankh/infra';

package/src/features/environment-lifecycle/utils/resolveInfraStatePath.ts

@@ -1,12 +1,9 @@
-import { APP_ENVIRONMENT_IDS, type AppEnvironmentId } from '@ankhorage/contracts/environments';
+import type { AppEnvironmentId } from '@ankhorage/contracts/environments';
 import path from 'path';
 
-const INFRA_STATE_ROOT = '.ankh/infra';
+import { resolveInfraEnvironmentStateDirectory } from './resolveInfraEnvironmentStateDirectory.js';
 
 /*** Build an exact state-file path from a closed canonical environment identifier. */
 export function resolveInfraStatePath(projectPath: string, environment: AppEnvironmentId): string {
-  if (!APP_ENVIRONMENT_IDS.includes(environment)) {
-    throw new Error(`Invalid Infra state environment: ${environment}`);
-  }
-  return path.join(projectPath, INFRA_STATE_ROOT, environment, 'state.json');
+  return path.join(resolveInfraEnvironmentStateDirectory(projectPath, environment), 'state.json');
 }

package/src/infraUp.test.ts

@@ -27,7 +27,7 @@ const environment = {
 const manifest = { environments: { local: environment }, modules: [] } as const;
 
 describe('environment up orchestration', () => {
-  it('validates before mutation and reconciles compute, runtime and deduplicated services', async () => {
+  it('validates before mutation and prepares services before workload materialization', async () => {
     const calls: string[] = [];
     const observedRuntimeDesired: InfraRuntimeDesiredState[] = [];
     const observedServiceOutputs: InfraOutput[][] = [];
@@ -39,9 +39,11 @@ describe('environment up orchestration', () => {
       'local.validate',
       'supabase.validate',
       'cerbos.validate',
+      'local.ensure',
+      'supabase.prepare',
+      'cerbos.prepare',
       'supabase.workloads',
       'cerbos.workloads',
-      'local.ensure',
       'docker-compose.validate',
       'docker-compose.ensure',
       'supabase.reconcile',
@@ -81,6 +83,27 @@ describe('environment up orchestration', () => {
     expect(calls).toEqual(['local.validate', 'supabase.validate']);
   });
 
+  it('stops before workload materialization when service preparation fails', async () => {
+    const calls: string[] = [];
+    const dependencies = createDependencies(calls, [], [], 'supabase.prepare');
+    const result = await upInfraEnvironmentAsync({ projectId: 'sample', manifest }, dependencies);
+
+    expect(result.ok).toBe(false);
+    expect(result.diagnostics.map(({ code }) => code)).toEqual([
+      'compute-warning',
+      'fixture-failure',
+    ]);
+    expect(calls).toEqual([
+      'local.validate',
+      'supabase.validate',
+      'cerbos.validate',
+      'local.ensure',
+      'supabase.prepare',
+    ]);
+    expect(calls).not.toContain('supabase.workloads');
+    expect(calls).not.toContain('docker-compose.ensure');
+  });
+
   it('does not reconcile services after a runtime failure', async () => {
     const calls: string[] = [];
     const dependencies = createDependencies(calls, [], [], 'docker-compose.ensure');
@@ -100,7 +123,11 @@ function createDependencies(
 ): InfraOrchestrationDependencies {
   return {
     adapterResolver: createResolver(calls, runtimeDesired, serviceOutputs, failure),
-    credentials: { resolveAsync: () => Promise.resolve(success({})) },
+    credentials: {
+      findAsync: () => Promise.resolve(success(null)),
+      resolveAsync: () => Promise.resolve(success({})),
+      persistAsync: () => Promise.resolve(success(null)),
+    },
     secrets: { resolveAsync: () => Promise.resolve(success('secret')) },
   };
 }
@@ -199,6 +226,7 @@ function createService(
     descriptor: descriptor as InfraServiceAdapter['descriptor'],
     validateAsync: () => recordAsync(calls, `${descriptor.id}.validate`, failure, null),
     planAsync: () => Promise.resolve(success([])),
+    prepareAsync: () => recordAsync(calls, `${descriptor.id}.prepare`, failure, null),
     desiredWorkloadsAsync: () =>
       recordAsync(calls, `${descriptor.id}.workloads`, failure, [workload(descriptor.id)]),
     reconcileAsync: (_context, outputs) => {

package/src/prepareInfraServices.test.ts

@@ -0,0 +1,50 @@
+import type {
+  InfraExecutionContext,
+  InfraResult,
+  InfraServiceAdapter,
+} from '@ankhorage/contracts/infra';
+import { INFRA_ADAPTER_CATALOG } from '@ankhorage/contracts/infra';
+import { expect, it } from 'bun:test';
+
+import { prepareInfraServicesAsync } from './features/environment-lifecycle/application/use-cases/prepareInfraServicesAsync';
+
+it('leaves services without preparation unchanged', async () => {
+  const service: InfraServiceAdapter = {
+    descriptor: INFRA_ADAPTER_CATALOG.cerbos,
+    validateAsync: () => success(null),
+    planAsync: () => success([]),
+    desiredWorkloadsAsync: () => success([]),
+    reconcileAsync: () => success({ resources: [], outputs: [] }),
+    statusAsync: () => success([]),
+    destroyAsync: () => success({ resources: [], outputs: [] }),
+  };
+
+  expect(await prepareInfraServicesAsync(createContext(), [service])).toEqual({
+    ok: true,
+    value: null,
+    diagnostics: [],
+  });
+});
+
+function createContext(): InfraExecutionContext {
+  return {
+    projectId: 'fixture',
+    environment: 'local',
+    desired: {
+      deployment: {
+        compute: { provider: 'local' },
+        runtime: { provider: 'docker-compose' },
+      },
+    },
+    credentials: {
+      findAsync: () => success(null),
+      resolveAsync: () => success({}),
+      persistAsync: () => success(null),
+    },
+    secrets: { resolveAsync: () => success('secret') },
+  };
+}
+
+function success<T>(value: T): Promise<InfraResult<T>> {
+  return Promise.resolve({ ok: true, value, diagnostics: [] });
+}