@mettlecast/domain-cli 0.2.59 → 0.2.60

package/src/commands/show-dns.ts

@@ -26,7 +26,7 @@ function toZoneLine(r: DnsRecord): string {
 }
 
 /**
- * tib show-dns [--env dev|staging|prod] [--project-dir <path>]
+ * mc-domain-module show-dns [--env dev|staging|prod] [--project-dir <path>]
  *
  * Reads the scaffold-config.json and prints DNS records that must be added for
  * custom domain wiring: certificate validation CNAMEs (step 1) and traffic
@@ -37,27 +37,27 @@ function toZoneLine(r: DnsRecord): string {
  */
 export async function runShowDns(opts: ShowDnsOptions): Promise<void> {
   const projectDir = opts.projectDir ? path.resolve(opts.projectDir) : process.cwd();
-  const configPath = path.join(projectDir, '.tib', 'scaffold-config.json');
+  const configPath = path.join(projectDir, '.mc', 'scaffold-config.json');
 
   let config: { environments?: Record<string, { dashboardUrl?: string }> };
   try {
     const raw = await readFile(configPath, 'utf-8');
     config = JSON.parse(raw) as typeof config;
   } catch {
-    console.error('[tib] Could not read .mc/scaffold-config.json — run from a TIB project root.');
+    console.error('[mc-domain-module] Could not read .mc/scaffold-config.json — run from a Mettlecast project root.');
     process.exit(1);
   }
 
   const environments = config.environments ?? {};
   if (Object.keys(environments).length === 0) {
-    console.log('[tib] No environments configured. Set a custom domain via `tib show-dns` or the Setup tab.');
+    console.log('[mc-domain-module] No environments configured. Set a custom domain via `npx mc-domain-module show-dns` or the Setup tab.');
     return;
   }
 
   // Try to load CDK outputs for routing records
   let cdkOutputs: Record<string, Record<string, string>> = {};
   try {
-    const outputsPath = path.join(projectDir, '.tib', 'cdk-outputs.json');
+    const outputsPath = path.join(projectDir, '.mc', 'cdk-outputs.json');
     const raw = await readFile(outputsPath, 'utf-8');
     cdkOutputs = JSON.parse(raw) as typeof cdkOutputs;
   } catch {

package/src/commands/upgrade.ts

@@ -251,9 +251,9 @@ function buildPrBody(
     lines.push('### Drift warnings — manual review required');
     lines.push(
       'The following files were locally modified after scaffold installation. ' +
-        'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.'
+        'New versions have been written to `{path}.mc-upgrade` — merge manually then remove the `.mc-upgrade` file.'
     );
-    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.mc-upgrade\``);
     lines.push('');
   }
 
@@ -322,9 +322,9 @@ function buildFrontendComponentsPrBody(
     lines.push('### Drift warnings — manual review required');
     lines.push(
       'The following files were locally modified after scaffold installation. ' +
-        'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.'
+        'New versions have been written to `{path}.mc-upgrade` — merge manually then remove the `.mc-upgrade` file.'
     );
-    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+    for (const r of conflicts) lines.push(`- \`${r.path}\` → \`${r.path}.mc-upgrade\``);
     lines.push('');
   }
 
@@ -512,14 +512,20 @@ export async function runUpgrade(
         continue;
       }
 
-      // Add to results
-      allResults.push({ path: installPath, status: installResult.status, module: mod.id });
-
-      // update-available: do NOT update manifest (file was not written to disk)
+      // update-available: write the proposed new content beside the drifted file
+      // for manual merge, but do NOT update the manifest or overwrite the file.
       if (installResult.status === 'update-available') {
+        if (!opts.dryRun) {
+          await mkdir(dirname(diskPath), { recursive: true });
+          await writeFile(`${diskPath}.mc-upgrade`, newContent, 'utf-8');
+        }
+        allResults.push({ path: installPath, status: 'conflict', module: mod.id });
         continue;
       }
 
+      // Add to results
+      allResults.push({ path: installPath, status: installResult.status, module: mod.id });
+
       // Update manifest if file was not skipped
       const newChecksum = computeChecksumString(newContent);
       upsertManifestFile(updatedManifest, {
@@ -566,7 +572,7 @@ export async function runUpgrade(
   if (conflicts.length > 0) {
     console.log('\nDrift warnings:');
     for (const r of conflicts) {
-      console.log(`  ${r.path} — new version written to ${r.path}.tib-upgrade`);
+      console.log(`  ${r.path} — new version written to ${r.path}.mc-upgrade`);
     }
   }
 
@@ -601,7 +607,7 @@ export async function runUpgrade(
   await writeScaffoldConfig(projectDir, updatedConfig);
 
   // 10. Commit on upgrade branch
-  const branchName = `tib-upgrade/${targetVersion}`;
+  const branchName = `mc-upgrade/${targetVersion}`;
   try {
     execSync(`git -C "${projectDir}" checkout -b "${branchName}"`, {
       stdio: ['pipe', 'pipe', 'pipe'],

package/src/commands/validate.ts

@@ -1,11 +1,32 @@
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import type { RegistryEntry } from '@mettlecast/domain-cdk-packer';
+import type {
+  RegistryEntry,
+  ActionRegistryEntry,
+} from '@mettlecast/domain-cdk-packer';
 import { validRange } from 'semver';
 import type { DomainModuleConfig } from '@mettlecast/domain-runtime/types';
 import { buildRegistry } from '../builder/build-registry.js';
 import { cliLogger } from '../utils/logger.js';
 
+type ActionApiExposureWithDeclaration = {
+  type: 'api';
+  path: string;
+  method: string;
+  auth: 'required' | 'none' | 'service';
+  tenancy: 'required' | 'none' | 'system';
+  roles?: string[];
+  securityException?: { reason: string };
+  authDeclared?: boolean;
+  tenancyDeclared?: boolean;
+};
+
+type ActionRegistryEntryWithDeclaration = ActionRegistryEntry & {
+  backendAccess?: 'private' | 'domain' | 'platform';
+  exposureDeclared?: boolean;
+  exposure: { type: 'internal' } | ActionApiExposureWithDeclaration;
+};
+
 /**
  * A single validation failure.
  */
@@ -116,6 +137,199 @@ async function checkRawPathViolations(
   return [];
 }
 
+/**
+ * Deployment-time security checks (#4662 Task D).
+ *
+ * Mirrors the invariants enforced at CDK synth time by
+ * `SecurityAssertionAspect` in `@mettlecast/domain-cdk-packer`. Running
+ * them at the CLI stage means developers get a structured error code in
+ * their terminal and CI fails on `mc-domain-module validate` BEFORE a
+ * (potentially expensive) `cdk synth` is attempted.
+ *
+ * Each rule maps 1:1 to an aspect annotation code so downstream tooling
+ * can correlate build-time and synth-time failures.
+ *
+ * NOTE on `SECURITY_MISSING_SECURITY_EXCEPTION` for legacy `defineApi`
+ * entries: the registry builder does not propagate `securityException`
+ * from legacy source — that field only exists on action-style API
+ * exposures, which are covered by the existing `AUTH_NONE_REQUIRES_EXCEPTION`
+ * rule in `checkActionFirstSecurity`. The aspect's corresponding check
+ * (`assertAnonymousRoutesHaveException`) catches the legacy case at
+ * synth time so a developer migrating to action-style APIs gets the
+ * right guidance at the right layer.
+ */
+function checkDeploymentSecurity(
+  apis: import('@mettlecast/domain-cdk-packer').ApiRegistryEntry[],
+  actions: ActionRegistryEntry[],
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const api of apis) {
+    // Non-anonymous APIs whose path lacks the tenant placeholder cannot
+    // bind `ctx.tenant.id` from the URL. The aspect surfaces this as
+    // `SECURITY_MISSING_TENANT_PATH`; the CLI version is a faster gate so
+    // CI doesn't pay the synth cost.
+    if (api.authType !== 'none' && !api.path.includes('/v1/tenants/{tenantId}/')) {
+      errors.push({
+        code: 'SECURITY_MISSING_TENANT_PATH',
+        message: `API '${api.id}' (${api.method} ${api.path}) is JWT-protected but its path does not include the canonical '/v1/tenants/{tenantId}/' placeholder. The runtime cannot bind ctx.tenant.id from a path that lacks the placeholder.`,
+      });
+    }
+  }
+
+  // Action API exposures are already covered by `checkActionFirstSecurity`
+  // for `tenancy: 'required'` paths and `auth: 'none'` exceptions. The
+  // codes there (TENANT_API_PATH_REQUIRED, AUTH_NONE_REQUIRES_EXCEPTION)
+  // are kept stable for back-compat — they map to the same aspect codes.
+
+  // Suppress the unused-actions lint while keeping the parameter shape
+  // for the future where actions gain new deployment-time invariants.
+  void actions;
+
+  return errors;
+}
+
+/**
+ * Action-first security validation rules (#4619, Wave 6 Task 6.1).
+ *
+ * These checks enforce the action-first security model on the
+ * serialised DomainRegistry produced by `buildRegistry`. The rules
+ * intentionally mirror the Zod cross-field refinements defined in
+ * `@mettlecast/domain-runtime/primitives/action` (`ApiExposureSchema`)
+ * so violations are caught at build time, not at runtime.
+ *
+ * Each rule emits a structured `ValidationError` whose `code` is the
+ * rule ID listed in the spec (e.g. `ACTION_EXPOSURE_REQUIRED`,
+ * `TENANT_API_PATH_REQUIRED`). Messages include the offending action
+ * or API id and the actionable fix.
+ */
+function checkActionFirstSecurity(actions: ActionRegistryEntry[]): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const action of actions as ActionRegistryEntryWithDeclaration[]) {
+    const id = action.id;
+
+    // ACTION_EXPOSURE_REQUIRED — every action registry entry must have
+    // `exposure` declared in source. The builder defaults missing
+    // exposure to `{ type: 'internal' }` for backwards compatibility,
+    // and flags the entry with `exposureDeclared: false` so the validator
+    // can surface it. Legacy actions that use `visibility` only (no
+    // `backendAccess`) are also allowed to default during migration.
+    if (action.exposureDeclared === false && action.backendAccess !== 'private') {
+      // Only fire for non-private actions: a private action with no
+      // exposure is the natural migration state for legacy
+      // visibility:'private' handlers, and forcing exposure would
+      // produce noisy errors during the migration window.
+      // (When Wave 7+ removes the legacy visibility alias this branch
+      // becomes a hard error for every action.)
+      errors.push({
+        code: 'ACTION_EXPOSURE_REQUIRED',
+        message: `Action '${id}' has no explicit \`exposure\`. New-style actions must declare \`exposure\` (e.g. \`{ type: 'api', path: '...', method: 'POST', auth: 'required', tenancy: 'required' }\`) or \`{ type: 'internal' }\` to opt out of API exposure.`,
+      });
+    }
+
+    if (action.exposure.type === 'api') {
+      errors.push(...checkApiExposureSecurity(action.id, action.exposure));
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a single API-exposed action. Pulled out as a separate helper
+ * so each sub-rule is independently testable and the messages stay short.
+ */
+function checkApiExposureSecurity(actionId: string, exposure: ActionApiExposureWithDeclaration): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // API_EXPOSURE_AUTH_REQUIRED — API-exposed actions must declare auth
+  // explicitly. The builder defaults auth to 'required' when the source
+  // omits it; the validator surfaces the omission so developers are not
+  // silently relying on the safe-default.
+  if (exposure.authDeclared === false) {
+    errors.push({
+      code: 'API_EXPOSURE_AUTH_REQUIRED',
+      message: `Action '${actionId}' has \`exposure.type: 'api'\` but \`exposure.auth\` is not declared. Set \`exposure.auth\` to 'required' | 'none' | 'service' explicitly.`,
+    });
+  }
+
+  // TENANT_API_PATH_REQUIRED — API-exposed actions with `tenancy: 'required'`
+  // must use a path that includes the canonical tenant placeholder so the
+  // runtime can bind `ctx.tenant.id` from the URL.
+  if (exposure.tenancy === 'required' && !exposure.path.includes('/v1/tenants/{tenantId}/')) {
+    errors.push({
+      code: 'TENANT_API_PATH_REQUIRED',
+      message: `Action '${actionId}' declares \`exposure.tenancy: 'required'\` but \`exposure.path\` ('${exposure.path}') does not include the canonical tenant placeholder '/v1/tenants/{tenantId}/'.`,
+    });
+  }
+
+  // AUTH_NONE_REQUIRES_EXCEPTION — `auth: 'none'` (anonymous) routes
+  // must carry an explicit `securityException` with a non-empty reason
+  // so security reviewers can audit the relaxation.
+  if (exposure.auth === 'none') {
+    const reason = exposure.securityException?.reason;
+    if (!reason || reason.trim().length === 0) {
+      errors.push({
+        code: 'AUTH_NONE_REQUIRES_EXCEPTION',
+        message: `Action '${actionId}' has \`exposure.auth: 'none'\` but no \`exposure.securityException.reason\`. Public/anonymous routes must document the security exception with a non-empty reason (and ideally a tracking reference).`,
+      });
+    }
+  }
+
+  // TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — `tenancy: 'none'` on a
+  // public API route must justify the missing tenant context. If the
+  // route is already justified as anonymous via `auth: 'none'` the
+  // same `securityException` may be reused; otherwise an exception is
+  // required for tenancy: 'none' on its own.
+  if (exposure.tenancy === 'none') {
+    const reason = exposure.securityException?.reason;
+    if (!reason || reason.trim().length === 0) {
+      errors.push({
+        code: 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC',
+        message: `Action '${actionId}' has \`exposure.tenancy: 'none'\` but no \`exposure.securityException.reason\`. Routes without tenant context must document the security exception with a non-empty reason.`,
+      });
+    }
+  }
+
+  // SYSTEM_API_REQUIRES_ROLE — `tenancy: 'system'` combined with
+  // `auth: 'required'` must declare non-empty `roles` so the JWT
+  // authorizer can scope the call. Routes that use `auth: 'service'`
+  // are service-only and do not require role narrowing.
+  if (exposure.tenancy === 'system' && exposure.auth === 'required') {
+    if (!Array.isArray(exposure.roles) || exposure.roles.length === 0) {
+      errors.push({
+        code: 'SYSTEM_API_REQUIRES_ROLE',
+        message: `Action '${actionId}' has \`exposure.tenancy: 'system'\` and \`exposure.auth: 'required'\` but no \`exposure.roles\`. System-tenancy routes using user auth must declare at least one required role.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * DEFINE_API_LEGACY_USAGE — the action-first migration replaces
+ * standalone `defineApi` calls with `defineAction` + `exposure.type:
+ * 'api'`. Every `defineApi` call still in the source produces a row in
+ * `registry.apis`; the validator emits one error per legacy API to
+ * enforce the alpha breaking migration. The validate command's fixture
+ * suite intentionally does not use `defineApi`, so this rule does not
+ * break existing unit tests.
+ */
+function checkDefineApiLegacyUsage(apiCount: number, apis: RegistryEntry[]): ValidationError[] {
+  if (apiCount === 0) return [];
+  const errors: ValidationError[] = [];
+  for (const api of apis) {
+    if (api.kind !== 'api') continue;
+    errors.push({
+      code: 'DEFINE_API_LEGACY_USAGE',
+      message: `API '${api.id}' uses legacy \`defineApi\`. Migrate to \`defineAction\` with \`exposure: { type: 'api', path, method, auth, tenancy }\` (#4619).`,
+    });
+  }
+  return errors;
+}
+
 /**
  * Run the validate command: build the registry and perform structural validation.
  * Exits the process with code 1 if validation fails (CI gate usage).
@@ -213,6 +427,17 @@ export async function runValidate(
   const rawPathErrors = await checkRawPathViolations(registry.domainRoot, config);
   errors.push(...rawPathErrors);
 
+  // Wave 6 Task 6.1: action-first security validation gates (#4619).
+  // Runs against the registry built above so the rules see the same
+  // shape the CDK packer will eventually consume.
+  errors.push(...checkActionFirstSecurity(registry.actions));
+  errors.push(...checkDefineApiLegacyUsage(registry.apis.length, registry.apis));
+
+  // Issue #4662 Task D — deployment-time security gates. These mirror
+  // the CDK synth-time `SecurityAssertionAspect` so violations are
+  // caught before any AWS deployment is attempted.
+  errors.push(...checkDeploymentSecurity(registry.apis, registry.actions));
+
   const totalPrimitives = registry.apis.length + registry.webhooks.length +
     registry.subscribers.length + registry.schedules.length +
     registry.jobs.length + registry.actions.length;

package/src/utils/header-inject.ts

@@ -68,7 +68,7 @@ function injectLineCommentHeader(
 ): string {
   const header = [
     `${commentChar} @mc-scaffold: ${moduleId}@${version}`,
-    `${commentChar} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`.`,
+    `${commentChar} This file is managed by TIB scaffold. Manual edits will be flagged during \`npx mc-domain-module upgrade\`.`,
     `${commentChar} To opt out of upgrade management for this file, remove these header lines.`,
     '',
   ].join('\n');
@@ -92,7 +92,7 @@ function injectBlockCommentHeader(
 ): string {
   const header = [
     `${open} @mc-scaffold: ${moduleId}@${version} ${close}`,
-    `${open} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`. ${close}`,
+    `${open} This file is managed by TIB scaffold. Manual edits will be flagged during \`npx mc-domain-module upgrade\`. ${close}`,
     '',
   ].join('\n');
   return header + content;

package/src/utils/install-file.ts

@@ -14,7 +14,7 @@ export interface InstallResult {
  *
  * - managed: always overwrite. Return 'added' if new, 'updated' if existed.
  * - editable: check sha256. If same → 'unchanged'. If different → 'update-available'
- *   (does not write .tib-upgrade or overwrite — user opts in via Updates tab).
+ *   (does not write .mc-upgrade or overwrite — user opts in via Updates tab).
  * - seed: if file exists → 'skipped'. Else write → 'added'.
  */
 export async function installScaffoldFile(

package/src/utils/manifest.ts

@@ -29,10 +29,9 @@ const MANIFEST_PATH = '.mc/manifest.json';
 const SCHEMA_URL = 'https://mc-scaffold.s3.amazonaws.com/schema/manifest.v3.json';
 
 export function inferPolicyFromPath(filePath: string): FilePolicy {
-  // owned: infra/, .mc/infra/, mc-deploy.yml, .github/workflows/
+  // owned: infra/, mc-deploy.yml, .github/workflows/
   if (
     filePath.match(/^infra\//) ||
-    filePath.match(/^\.tib\/infra\//) ||
     filePath === 'mc-deploy.yml' ||
     filePath.match(/^\.github\/workflows\//)
   ) {

package/src/utils/scaffold-config.ts

@@ -92,9 +92,9 @@ export interface ScaffoldConfig {
   awsAccountId: string;
   /** Admin email collected at scaffold time (Cognito seed user). Present only when auth module is enabled. */
   adminEmail?: string;
-  /** Domain IDs added via `tib add-domain` — NOT scaffold-owned, user-managed */
+  /** Domain IDs added via `mc-domain-module add-domain` — NOT scaffold-owned, user-managed */
   domainIds: string[];
-  /** Flow IDs added via `tib add-flow` — user-managed */
+  /** Flow IDs added via `mc-domain-module add-flow` — user-managed */
   flowIds: string[];
   /** S3 bucket used for scaffold fetches (defaults to public TIB bucket) */
   scaffoldBucket: string;
@@ -148,7 +148,7 @@ export async function readScaffoldConfig(projectRoot: string): Promise<ScaffoldC
   if (!raw.scaffoldVersion) {
     // eslint-disable-next-line no-console
     console.warn(
-      '[tib] scaffold-config.json is missing scaffoldVersion — project was created before S3 scaffold migration. Run `tib upgrade` to backfill.'
+      '[mc-domain-module] scaffold-config.json is missing scaffoldVersion — project was created before S3 scaffold migration. Run `npx mc-domain-module upgrade` to backfill.'
     );
   }