@fjall/components-infrastructure 4.2.0 → 4.3.0

package/dist/lib/config/aws/oidcConnector.d.ts

@@ -1,4 +1,5 @@
 import { type GovernancePreset } from "@fjall/generator";
+import { type AccountTier } from "@fjall/util";
 import { Construct } from "constructs";
 export interface OidcConnectorProps {
     fjallOrgId: string;
@@ -19,6 +20,18 @@ export interface OidcConnectorProps {
      * other stage ⇒ deploy role only.
      */
     accountStage?: string;
+    /**
+     * Account TIER of the connected account (organisation | platform | account) —
+     * the structural TIER axis, from the account stack's polymorphic
+     * `deployRoleAccountTier()`; NEVER the wire `environment` / stage axis (that is
+     * `accountStage`). Drives the §4.4a deploy-trust governance expand: a
+     * governance tier (organisation/platform) plus the synth account id widens the
+     * `FjallDeploy` machine subject to ALSO accept the account-scoped literal
+     * `org:{orgId}:acct:{awsAccountId}` (StringEquals array = OR of exact
+     * literals), so per-account deploy issuance can later flip. App-tier
+     * ("account") or absent ⇒ generic-only scalar (unchanged, fail-safe).
+     */
+    accountTier?: AccountTier;
 }
 export declare class OidcConnector extends Construct {
     readonly deployRoleArn: string;

package/dist/lib/config/aws/oidcConnector.js

@@ -115,10 +115,15 @@ export class OidcConnector extends Construct {
                 statements: SECURITY_TIER_TO_BOUNDARY[props.securityTier].map((statement) => iam.PolicyStatement.fromJson(statement))
             })
             : undefined;
+        // Concrete when env.account is set, a token otherwise — both render. Feeds
+        // the governance-expand machine subject and the dev-tier surface below.
+        const accountId = Stack.of(this).account;
         const trustParams = {
             fjallOrgId: props.fjallOrgId,
             providerArn,
-            issuerDomain
+            issuerDomain,
+            accountId,
+            ...(props.accountTier !== undefined && { accountTier: props.accountTier })
         };
         const deployRole = new Role(this, "DeployRole", {
             roleName: `FjallDeploy${props.fjallOrgId}`,
@@ -141,7 +146,6 @@ export class OidcConnector extends Construct {
         // with the Quick-Create yaml's IsDevelopmentStage-conditional resources
         // and the webapp dev-gate-remediate pass).
         if (props.accountStage === "development") {
-            const accountId = Stack.of(this).account;
             new ManagedPolicy(this, "DevBoundary", {
                 managedPolicyName: DEV_BOUNDARY_POLICY_NAME,
                 description: "Fjall dev-tier permissions boundary — ceiling for the per-slot task roles the dev provisioner creates",

package/dist/lib/patterns/aws/account.d.ts

@@ -13,6 +13,7 @@ import type { ConfigRecorderProps } from "../../config/aws/configRecorder.js";
 import type { ConfigRulePresetProps } from "../../config/aws/configRulePreset.js";
 import type { OrganisationType } from "./interfaces/organisation.js";
 import { type GovernancePreset } from "@fjall/generator";
+import { type AccountTier } from "@fjall/util";
 export interface AccountProps extends StackProps {
     accountId?: string;
     region?: string;
@@ -47,6 +48,19 @@ export declare class Account extends Stack {
      * independent, and Platform must take one but not the other.
      */
     protected receivesDeployRole(): boolean;
+    /**
+     * Account TIER passed to this account's `OidcConnector` for the §4.4a
+     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
+     * `organisationType` field: the connector is instantiated in THIS base
+     * constructor, and subclass field initialisers run AFTER `super()`, so
+     * `this.organisationType` would read "account" for every subclass here (the
+     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
+     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
+     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
+     * machine subject; kept in lockstep with `organisationType` by the
+     * Platform-synth deploy-trust parity test.
+     */
+    protected deployRoleAccountTier(): AccountTier;
     /**
      * Whether this account creates the default-ECR-image helper (the CodeBuild
      * project that seeds a placeholder application image). App-hosting accounts

package/dist/lib/patterns/aws/account.js

@@ -81,6 +81,7 @@ export class Account extends Stack {
             new OidcConnector(this, "OidcConnector", {
                 fjallOrgId,
                 accountStage: environment,
+                accountTier: this.deployRoleAccountTier(),
                 ...(props.securityTier !== undefined && {
                     securityTier: props.securityTier
                 })
@@ -146,6 +147,21 @@ export class Account extends Stack {
     receivesDeployRole() {
         return this.constructor === Account;
     }
+    /**
+     * Account TIER passed to this account's `OidcConnector` for the §4.4a
+     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
+     * `organisationType` field: the connector is instantiated in THIS base
+     * constructor, and subclass field initialisers run AFTER `super()`, so
+     * `this.organisationType` would read "account" for every subclass here (the
+     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
+     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
+     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
+     * machine subject; kept in lockstep with `organisationType` by the
+     * Platform-synth deploy-trust parity test.
+     */
+    deployRoleAccountTier() {
+        return "account";
+    }
     /**
      * Whether this account creates the default-ECR-image helper (the CodeBuild
      * project that seeds a placeholder application image). App-hosting accounts

package/dist/lib/patterns/aws/organisation.d.ts

@@ -5,6 +5,7 @@ import { type IdentityCentreConfig } from "../../config/aws/identityCentreConfig
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import type { ScpPresetProps } from "../../config/aws/scpPreset.js";
 import { OrganisationResource } from "../../resources/aws/organisation/index.js";
+import { type AccountTier } from "@fjall/util";
 export type AccountsConfig = {
     readonly [key: string]: readonly string[] | string | AccountsConfig;
 };
@@ -58,6 +59,14 @@ export declare class Organisation extends Account {
      * gate, so no `OidcConnector` is synthesised on the root stack.
      */
     protected receivesDeployRole(): boolean;
+    /**
+     * Account TIER = organisation (the AWS Organizations management account). The
+     * root never instantiates an `OidcConnector` (`receivesDeployRole()` is false
+     * — its deploy trust is owned by the Quick-Create template), so this override
+     * is not reached on the CDK path today; it keeps `deployRoleAccountTier()`
+     * honest with `organisationType` for any future caller.
+     */
+    protected deployRoleAccountTier(): AccountTier;
     /**
      * The organisation root runs no application workloads, so it needs no
      * default-ECR-image helper.

package/dist/lib/patterns/aws/organisation.js

@@ -125,6 +125,16 @@ export class Organisation extends Account {
     receivesDeployRole() {
         return false;
     }
+    /**
+     * Account TIER = organisation (the AWS Organizations management account). The
+     * root never instantiates an `OidcConnector` (`receivesDeployRole()` is false
+     * — its deploy trust is owned by the Quick-Create template), so this override
+     * is not reached on the CDK path today; it keeps `deployRoleAccountTier()`
+     * honest with `organisationType` for any future caller.
+     */
+    deployRoleAccountTier() {
+        return "organisation";
+    }
     /**
      * The organisation root runs no application workloads, so it needs no
      * default-ECR-image helper.

package/dist/lib/patterns/aws/platform.d.ts

@@ -4,6 +4,7 @@ import { type AccountsConfig } from "./organisation.js";
 import { SecurityServicesAdmin } from "../../config/aws/securityServicesAdmin.js";
 import type { SecurityServicesAdminProps } from "../../config/aws/securityServicesAdmin.js";
 import type { OrganisationType } from "./interfaces/organisation.js";
+import { type AccountTier } from "@fjall/util";
 export interface PlatformProps extends AccountProps {
     accounts?: AccountsConfig;
 }
@@ -11,5 +12,6 @@ export declare class Platform extends Account {
     readonly organisationType: OrganisationType;
     constructor(scope: Construct, id: string, props: PlatformProps);
     protected receivesDeployRole(): boolean;
+    protected deployRoleAccountTier(): AccountTier;
     enableSecurityServicesAdmin(props: SecurityServicesAdminProps): SecurityServicesAdmin;
 }

package/dist/lib/patterns/aws/platform.js

@@ -26,6 +26,9 @@ export class Platform extends Account {
     receivesDeployRole() {
         return true;
     }
+    deployRoleAccountTier() {
+        return "platform";
+    }
     enableSecurityServicesAdmin(props) {
         return new SecurityServicesAdmin(this, "SecurityServicesAdmin", props);
     }

package/dist/lib/utils/engineCompat.d.ts

@@ -0,0 +1,37 @@
+import { type EngineCompat } from "@fjall/util/manifest/schemas";
+/**
+ * The constructs' own package version — the assembly's `synthesisedBy`.
+ * `undefined` only when the package layout is broken enough that the upward
+ * walk finds no matching `package.json`.
+ */
+export declare const CONSTRUCTS_VERSION: string | undefined;
+/**
+ * Pure core of the emitter: derive the `engineCompat` block from a given
+ * version string (or undefined). Both the absent/empty guard and the
+ * `${major}.0.0` non-integer-major derivation live here — the single source of
+ * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
+ * `buildEngineCompat` — so the fail-safe and malformed-version paths are
+ * unit-testable directly, without mocking module-load state. Returns undefined
+ * when the version is absent, empty, or has no valid integer major (fail-safe:
+ * the caller stamps no block).
+ */
+export declare function buildEngineCompatFrom(version: string | undefined): EngineCompat | undefined;
+/**
+ * The compatible deploy-engine floor for assemblies this constructs version
+ * synthesises: `${major}.0.0`, derived from `CONSTRUCTS_VERSION`. `undefined`
+ * when the version is unresolved or has a non-integer major (in which case
+ * `buildEngineCompat` stamps no block — fail-safe).
+ */
+export declare const MINIMUM_ENGINE_VERSION: string | undefined;
+/**
+ * Build the `engineCompat` block to stamp into the manifest, or `undefined`
+ * when the constructs' own version cannot be resolved (fail-safe: the caller
+ * stamps no block and the deploy degrades to a constraint-free proceed).
+ *
+ * Phase 1 emits only the two required fields. The verdict classification of the
+ * emitted floor is proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
+ * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
+ * emitted shape matches that floor and reads back through the gate's reader.
+ */
+export declare function buildEngineCompat(): EngineCompat | undefined;

package/dist/lib/utils/engineCompat.js

@@ -0,0 +1,118 @@
+/**
+ * Synth-time engine-compatibility stamp (the contract's self-honest emitter).
+ *
+ * The constructs package is the one place that knows which deploy engine can
+ * safely deploy the assembly THIS version of the constructs produced, so it is
+ * the correct emitter of the engine ↔ assembly version contract. At synth,
+ * `writeManifest` stamps the `engineCompat` block this module builds into
+ * `cdk.out/fjall-manifest.json`; the deploy engine (`@fjall/deploy-core`) reads
+ * it back at deploy-start (`readEngineCompatEnvelope` + `evaluateEngineCompat`)
+ * and refuses an incompatible pairing before any build / push / CloudFormation
+ * mutation. Both the CLI and the webapp worker inherit that one chokepoint.
+ *
+ * `synthesisedBy` is the constructs' OWN package version — audit/diagnostics
+ * only, never a gate input. It is resolved at module load by the same upward
+ * `package.json` walk `@fjall/deploy-core`'s `DEPLOY_CORE_VERSION` uses: the
+ * source layout (`lib/utils/engineCompat.ts`) and the compiled layout
+ * (`dist/lib/utils/engineCompat.js`) sit at different depths from the package
+ * root, so a fixed relative path would resolve the wrong file in one of them;
+ * matching on `name` finds the right `package.json` from both, and skips any
+ * unrelated `package.json` higher up (e.g. a consuming app's).
+ *
+ * `minimumEngineVersion` is the PRIMARY refuse gate. Under Lerna FIXED lockstep
+ * every `@fjall/*` package shares one version, so the compatible engine floor
+ * is this constructs major with a zeroed minor/patch (`${major}.0.0`) — DERIVED,
+ * never hardcoded, so it advances to `5.0.0` on the next major with no
+ * hand-edit. A same-major-or-newer engine proceeds; an older-major engine
+ * hard-refuses.
+ *
+ * The optional `maximumEngineMajor` / `minimumAwsCdkCli` bounds are deliberately
+ * NOT emitted in Phase 1 — they are ADR open question Q5 (engine-ahead cap) and
+ * the Phase-2 FM1 aws-cdk floor graft respectively, both unresolved and
+ * deferred. This emitter stamps only the two required fields.
+ *
+ * Fail-safe: if the constructs' own version cannot be resolved (a broken
+ * package layout), `buildEngineCompat` returns undefined and the caller stamps
+ * NO block — degrading to the constraint-free "proceed" behaviour that predates
+ * this contract rather than breaking synth. A resolution failure is logged, not
+ * silently swallowed.
+ */
+import { fileURLToPath } from "url";
+import { dirname, join, parse } from "path";
+import { existsSync, readFileSync } from "fs";
+import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
+import { FjallLogger } from "./validationLogger.js";
+const PACKAGE_NAME = "@fjall/components-infrastructure";
+function resolveConstructsVersion() {
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        const { root } = parse(dir);
+        for (;;) {
+            const candidate = join(dir, "package.json");
+            if (existsSync(candidate)) {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === PACKAGE_NAME &&
+                    typeof pkg.version === "string" &&
+                    pkg.version.length > 0) {
+                    return pkg.version;
+                }
+            }
+            if (dir === root)
+                return undefined;
+            dir = dirname(dir);
+        }
+    }
+    catch (error) {
+        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} version for engineCompat: ` +
+            maskSensitiveOutput(getErrorMessage(error)));
+        return undefined;
+    }
+}
+/**
+ * The constructs' own package version — the assembly's `synthesisedBy`.
+ * `undefined` only when the package layout is broken enough that the upward
+ * walk finds no matching `package.json`.
+ */
+export const CONSTRUCTS_VERSION = resolveConstructsVersion();
+/**
+ * Pure core of the emitter: derive the `engineCompat` block from a given
+ * version string (or undefined). Both the absent/empty guard and the
+ * `${major}.0.0` non-integer-major derivation live here — the single source of
+ * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
+ * `buildEngineCompat` — so the fail-safe and malformed-version paths are
+ * unit-testable directly, without mocking module-load state. Returns undefined
+ * when the version is absent, empty, or has no valid integer major (fail-safe:
+ * the caller stamps no block).
+ */
+export function buildEngineCompatFrom(version) {
+    if (version === undefined || version.length === 0)
+        return undefined;
+    const major = Number(version.split(".")[0]);
+    if (!Number.isInteger(major) || major < 0)
+        return undefined;
+    return {
+        synthesisedBy: version,
+        minimumEngineVersion: `${major}.0.0`
+    };
+}
+/**
+ * The compatible deploy-engine floor for assemblies this constructs version
+ * synthesises: `${major}.0.0`, derived from `CONSTRUCTS_VERSION`. `undefined`
+ * when the version is unresolved or has a non-integer major (in which case
+ * `buildEngineCompat` stamps no block — fail-safe).
+ */
+export const MINIMUM_ENGINE_VERSION = buildEngineCompatFrom(CONSTRUCTS_VERSION)?.minimumEngineVersion;
+/**
+ * Build the `engineCompat` block to stamp into the manifest, or `undefined`
+ * when the constructs' own version cannot be resolved (fail-safe: the caller
+ * stamps no block and the deploy degrades to a constraint-free proceed).
+ *
+ * Phase 1 emits only the two required fields. The verdict classification of the
+ * emitted floor is proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
+ * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
+ * emitted shape matches that floor and reads back through the gate's reader.
+ */
+export function buildEngineCompat() {
+    return buildEngineCompatFrom(CONSTRUCTS_VERSION);
+}

package/dist/lib/utils/manifestWriter.js

@@ -19,6 +19,7 @@ import { createHash } from "crypto";
 import { buildConstructMap, constructMapToRecord, ACCOUNT_CONSTRUCT_GROUPS } from "@fjall/util/constructMap";
 import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
 import { FJALL_MANIFEST_FILENAME, MANIFEST_SCHEMA_VERSION, FjallManifestSchema } from "@fjall/util/manifest/schemas";
+import { buildEngineCompat } from "./engineCompat.js";
 import { FjallLogger } from "./validationLogger.js";
 /**
  * Collected manifest data during synthesis.
@@ -170,6 +171,12 @@ export function writeManifest(assembly, collector) {
     const stacks = computeStackHashes(cdkOutPath);
     // Build resource map from CDK manifest metadata
     const constructMap = buildConstructMap(cdkOutPath, collector.getConstructGroups());
+    const engineCompat = buildEngineCompat();
+    if (engineCompat === undefined) {
+        FjallLogger.warn("Could not determine constructs version — manifest stamped with no " +
+            "engineCompat block; the deploy engine will proceed without a " +
+            "version-compatibility gate.");
+    }
     const manifest = {
         version: MANIFEST_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
@@ -177,6 +184,7 @@ export function writeManifest(assembly, collector) {
         services: collector.getServices(),
         lambdas: collector.getLambdas(),
         stacks,
+        ...(engineCompat !== undefined ? { engineCompat } : {}),
         ...(constructMap.size > 0
             ? { resourceMap: constructMapToRecord(constructMap) }
             : {})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^4.2.0",
-    "@fjall/util": "^4.2.0",
+    "@fjall/generator": "^4.3.0",
+    "@fjall/util": "^4.3.0",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "c06f7ad6b4b63a99cc8e2fcf4f216ff1c14748c6"
+  "gitHead": "8a3ae096f9d15c47dc8c277c9bddfa40e4168c19"
 }