@aws/nx-plugin 1.1.1 → 1.3.0

package/src/utils/greengrass-constructs/files/cdk/core/greengrass/next-version.ts.template

@@ -0,0 +1,119 @@
+import { Construct } from 'constructs';
+import * as url from 'node:url';
+import { CustomResource, Duration, Stack } from 'aws-cdk-lib';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Code, Function, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { Provider } from 'aws-cdk-lib/custom-resources';
+
+const GreengrassNextVersionProviderKey = '__GreengrassNextVersionProvider__';
+
+export interface GreengrassNextVersionProps {
+  /** Name of the Greengrass component whose next version is resolved. */
+  readonly componentName: string;
+  /** Part of the highest published strict M.m.p version to increment. */
+  readonly strategy: 'patch' | 'minor' | 'major';
+  /** Opaque digest of the submitted recipe and built artifact content. */
+  readonly contentSha256: string;
+  /** Artifact bucket name, which can be a deploy-time CloudFormation token. */
+  readonly bucketName: string;
+}
+
+/**
+ * Share one resolver Lambda and provider across a stack's components.
+ */
+class GreengrassNextVersionProvider extends Construct {
+  static ensure(scope: Construct): GreengrassNextVersionProvider {
+    const stack = Stack.of(scope);
+    return (
+      (stack.node.tryFindChild(
+        GreengrassNextVersionProviderKey,
+      ) as GreengrassNextVersionProvider) ??
+      new GreengrassNextVersionProvider(
+        stack,
+        GreengrassNextVersionProviderKey,
+      )
+    );
+  }
+
+  public readonly serviceToken: string;
+  private readonly onEvent: Function;
+  private readonly componentNames = new Set<string>();
+
+  public allowComponent(componentName: string): void {
+    if (this.componentNames.has(componentName)) {
+      return;
+    }
+    this.componentNames.add(componentName);
+    const stack = Stack.of(this);
+    const componentArn = `arn:${stack.partition}:greengrass:${stack.region}:${stack.account}:components:${componentName}`;
+    this.onEvent.addToRolePolicy(
+      new PolicyStatement({
+        actions: ['greengrass:ListComponentVersions'],
+        resources: [componentArn],
+      }),
+    );
+    this.onEvent.addToRolePolicy(
+      new PolicyStatement({
+        actions: ['greengrass:DescribeComponent'],
+        resources: [`${componentArn}:versions:*`],
+      }),
+    );
+  }
+
+  private constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    this.onEvent = new Function(this, 'OnEvent', {
+      runtime: <%- nodeRuntime %>,
+      handler: 'index.handler',
+      timeout: Duration.minutes(2),
+      code: Code.fromAsset(
+        url.fileURLToPath(
+          new URL('./next-version', <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>),
+        ),
+      ),
+    });
+    const provider = new Provider(this, 'Provider', {
+      onEventHandler: this.onEvent,
+    });
+    this.serviceToken = provider.serviceToken;
+  }
+}
+
+/**
+ * Resolve the version and content identity when its properties change.
+ * Deletion leaves the resolved component version in the registry.
+ */
+export class GreengrassNextVersion extends Construct {
+  /** The deploy-time version resolved from the Greengrass registry. */
+  public readonly version: string;
+
+  /** Bucket-scoped content identity returned by the shared resolver. */
+  public readonly contentKey: string;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: GreengrassNextVersionProps,
+  ) {
+    super(scope, id);
+
+    if (!/^[a-zA-Z0-9-_.]+$/.test(props.componentName)) {
+      throw new Error('componentName must contain only letters, digits, hyphens, underscores and dots.');
+    }
+    const provider = GreengrassNextVersionProvider.ensure(this);
+    provider.allowComponent(props.componentName);
+    const resource = new CustomResource(this, 'Resource', {
+      serviceToken: provider.serviceToken,
+      resourceType: 'Custom::GreengrassNextVersion',
+      properties: {
+        ComponentName: props.componentName,
+        Strategy: props.strategy,
+        ContentSha256: props.contentSha256,
+        BucketName: props.bucketName,
+      },
+    });
+    this.version = resource.getAttString('Version');
+    this.contentKey = resource.getAttString('ContentKey');
+  }
+}

package/src/utils/greengrass-constructs/files/cdk/core/greengrass/recipe.ts.template

@@ -0,0 +1,90 @@
+import yaml from 'js-yaml';
+
+/**
+ * The artifact fields read or rewritten during component publication.
+ */
+export interface GreengrassRecipeArtifact {
+  readonly Uri: string;
+  readonly [key: string]: unknown;
+}
+
+export interface GreengrassRecipeManifest {
+  readonly Artifacts?: readonly GreengrassRecipeArtifact[];
+  readonly [key: string]: unknown;
+}
+
+export interface GreengrassRecipeSummary {
+  readonly componentName: string;
+  readonly componentVersion: string;
+  /**
+   * Parsed recipe; artifact URI substitution preserves all other fields.
+   */
+  readonly raw: { Manifests?: GreengrassRecipeManifest[]; [key: string]: unknown };
+}
+
+/**
+ * Read the recipe's required ComponentName and ComponentVersion strings.
+ */
+export const readRecipeSummary = (
+  yamlSource: string,
+  recipePath: string,
+): GreengrassRecipeSummary => {
+  const raw = yaml.load(yamlSource);
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`"${recipePath}" is not a Greengrass recipe document`);
+  }
+  const { ComponentName, ComponentVersion } = raw as {
+    ComponentName?: unknown;
+    ComponentVersion?: unknown;
+  };
+  if (typeof ComponentName !== 'string' || ComponentName.length === 0) {
+    throw new Error(`"${recipePath}" is missing ComponentName`);
+  }
+  if (typeof ComponentVersion !== 'string' || ComponentVersion.length === 0) {
+    throw new Error(`"${recipePath}" is missing ComponentVersion`);
+  }
+  return {
+    componentName: ComponentName,
+    componentVersion: ComponentVersion,
+    raw: raw as GreengrassRecipeSummary['raw'],
+  };
+};
+
+/**
+ * GDK placeholder prefix identifying artifacts managed by this construct.
+ */
+const PLACEHOLDER_PREFIX = 's3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/';
+
+export interface ArtifactUriSubstitution {
+  readonly bucketName: string;
+  /**
+   * Uploaded artifact key prefix, including the trailing slash.
+   */
+  readonly keyPrefix: string;
+}
+
+/**
+ * Substitute managed artifact URIs in place, leaving other fields untouched.
+ * Return archive basenames; CDK resolves embedded bucket tokens at deployment.
+ */
+export const substituteArtifactUris = (
+  raw: GreengrassRecipeSummary['raw'],
+  substitution: ArtifactUriSubstitution,
+): string[] => {
+  const { bucketName, keyPrefix } = substitution;
+  const replacementPrefix = `s3://${bucketName}/${keyPrefix}`;
+  const substitutedBasenames: string[] = [];
+
+  for (const manifest of raw.Manifests ?? []) {
+    for (const artifact of manifest.Artifacts ?? []) {
+      const mutableArtifact = artifact as { Uri: string };
+      if (mutableArtifact.Uri.startsWith(PLACEHOLDER_PREFIX)) {
+        const basename = mutableArtifact.Uri.slice(PLACEHOLDER_PREFIX.length);
+        substitutedBasenames.push(basename);
+        mutableArtifact.Uri = `${replacementPrefix}${basename}`;
+      }
+    }
+  }
+
+  return substitutedBasenames;
+};

package/src/utils/greengrass-constructs/files/next-version/__nextVersionFileName__.template

@@ -0,0 +1,195 @@
+/**
+ * Resolves a Greengrass component version from the registry at deployment
+ * time from the CDK stack.
+ * It computes a bucket-scoped content key, then inspects only the highest
+ * strict M.m.p version: reuse it only when its key matches and it is
+ * DEPLOYABLE; otherwise create the next version.
+ */
+
+const { createHash } = require('node:crypto');
+
+const NEXT_VERSION_TAG_KEY = 'nx:greengrass:content-sha256';
+const VERSIONING_TAG_KEY = 'nx:greengrass:versioning';
+
+const parseStrictVersion = (version) => {
+  if (typeof version !== 'string') {
+    return undefined;
+  }
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+  if (!match) {
+    return undefined;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+};
+
+const asParsedVersion = (version) =>
+  typeof version === 'string' ? parseStrictVersion(version) : version;
+
+const compareVersions = (left, right) => {
+  const a = asParsedVersion(left);
+  const b = asParsedVersion(right);
+  if (!a || !b) {
+    throw new Error('Versions must be strict M.m.p values');
+  }
+  for (const field of ['major', 'minor', 'patch']) {
+    if (a[field] !== b[field]) {
+      return a[field] - b[field];
+    }
+  }
+  return 0;
+};
+
+const bumpVersion = (version, strategy) => {
+  const parsed = parseStrictVersion(version);
+  if (!parsed) {
+    throw new Error(`Cannot bump non-strict version "${version}"`);
+  }
+  switch (strategy) {
+    case 'patch':
+      return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+    case 'minor':
+      return `${parsed.major}.${parsed.minor + 1}.0`;
+    case 'major':
+      return `${parsed.major + 1}.0.0`;
+    default:
+      throw new Error(`Unsupported version strategy "${strategy}"`);
+  }
+};
+
+const versionFromArn = (versionArn) => versionArn.split(':').at(-1);
+
+const sha256hex = (value) =>
+  createHash('sha256').update(value).digest('hex');
+
+const resolveNextVersion = async (api, input) => {
+  if (!input.componentName) {
+    return { version: '', action: 'none', highest: '', contentKey: '' };
+  }
+
+  const contentKey = sha256hex(`${input.contentSha256}\n${input.bucketName}`);
+  const componentArn = `arn:${input.partition}:greengrass:${input.region}:${input.accountId}:components:${input.componentName}`;
+  const versionArns = await api.listVersions(componentArn);
+  const strictVersions = versionArns
+    .map((arn) => ({ arn, version: versionFromArn(arn) }))
+    .filter(({ version }) => parseStrictVersion(version));
+  const highestEntry = strictVersions.reduce(
+    (highest, candidate) =>
+      !highest || compareVersions(candidate.version, highest.version) > 0
+        ? candidate
+        : highest,
+    undefined,
+  );
+  const highest = highestEntry?.version ?? '';
+
+  if (highestEntry) {
+    const described = await api.describeVersion(highestEntry.arn);
+    if (
+      described.state === 'DEPLOYABLE' &&
+      described.tags?.[NEXT_VERSION_TAG_KEY] === contentKey
+    ) {
+      return { version: highest, action: 'reuse', highest, contentKey };
+    }
+  }
+
+  return {
+    version: highest ? bumpVersion(highest, input.strategy) : '1.0.0',
+    action: 'create',
+    highest,
+    contentKey,
+  };
+};
+
+const createGreengrassApi = ({ region }) => {
+  const {
+    DescribeComponentCommand,
+    GreengrassV2Client,
+    ListComponentVersionsCommand,
+  } = require('@aws-sdk/client-greengrassv2');
+  const client = new GreengrassV2Client({ region });
+
+  return {
+    listVersions: async (componentArn) => {
+      const versions = [];
+      let nextToken;
+      do {
+        const response = await client.send(
+          new ListComponentVersionsCommand({
+            arn: componentArn,
+            nextToken,
+          }),
+        );
+        versions.push(
+          ...(response.componentVersions ?? [])
+            .map((component) => component.arn)
+            .filter(Boolean),
+        );
+        nextToken = response.nextToken;
+      } while (nextToken);
+      return versions;
+    },
+    describeVersion: async (versionArn) => {
+      const response = await client.send(
+        new DescribeComponentCommand({ arn: versionArn }),
+      );
+      return {
+        state: response.status?.componentState,
+        tags: response.tags ?? {},
+      };
+    },
+  };
+};
+
+const stackIdentity = (stackId) => {
+  const fields = String(stackId).split(':');
+  return {
+    partition: fields[1],
+    region: fields[3],
+    accountId: fields[4],
+  };
+};
+
+exports.NEXT_VERSION_TAG_KEY = NEXT_VERSION_TAG_KEY;
+exports.VERSIONING_TAG_KEY = VERSIONING_TAG_KEY;
+exports.parseStrictVersion = parseStrictVersion;
+exports.compareVersions = compareVersions;
+exports.bumpVersion = bumpVersion;
+exports.resolveNextVersion = resolveNextVersion;
+exports.createGreengrassApi = createGreengrassApi;
+
+exports.handler = async (event) => {
+  if (event.RequestType === 'Delete') {
+    return { PhysicalResourceId: event.PhysicalResourceId };
+  }
+
+  const properties = event.ResourceProperties ?? {};
+  const identity = stackIdentity(event.StackId);
+  const input = {
+    componentName: properties.ComponentName,
+    strategy: properties.Strategy,
+    contentSha256: properties.ContentSha256,
+    bucketName: properties.BucketName,
+    region: identity.region,
+    accountId: identity.accountId,
+    partition: identity.partition,
+  };
+  const result = await resolveNextVersion(
+    input.componentName
+      ? createGreengrassApi({ region: process.env.AWS_REGION })
+      : undefined,
+    input,
+  );
+
+  return {
+    PhysicalResourceId: `${properties.ComponentName}/next-version`,
+    Data: {
+      Version: result.version,
+      Action: result.action,
+      Highest: result.highest,
+      ContentKey: result.contentKey,
+    },
+  };
+};

package/src/utils/greengrass-constructs/files/terraform/app/greengrass-component/__componentDirName__/__componentDirName__.tf.template

@@ -0,0 +1,26 @@
+variable "bucket_name" {
+  description = "Name of the shared artifact bucket this component version's artifact is uploaded to - typically the `bucket_name` output of a `core/greengrass/artifact-bucket` module, whose own `depends_on` orders this upload after the bucket is hardened."
+  type        = string
+}
+
+# Publish "<%- componentDisplayName %>" from its <%- componentDirName %>-artifact build.
+# Keep these paths aligned with the host project when editing this module.
+module "component_version" {
+  source = "../../../core/greengrass/component-version"
+
+  recipes_dir   = "${path.module}/../../../../../../../<%- recipesDirFromRoot %>"
+  artifacts_dir = "${path.module}/../../../../../../../<%- artifactsDirFromRoot %>"
+  bucket_name   = var.bucket_name
+}
+
+output "component_name" {
+  value = module.component_version.component_name
+}
+
+output "component_version" {
+  value = module.component_version.component_version
+}
+
+output "arn" {
+  value = module.component_version.arn
+}

package/src/utils/greengrass-constructs/files/terraform/core/greengrass/artifact-bucket/main.tf.template

@@ -0,0 +1,204 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "<%- randomProviderVersion %>"
+    }
+  }
+}
+
+variable "bucket_name" {
+  description = "Physical name for a newly created bucket. Leave unset (null) to derive one from bucket_name_prefix instead. Ignored when existing_bucket_name is set."
+  type        = string
+  default     = null
+}
+
+variable "bucket_name_prefix" {
+  description = "Prefix for the bucket name generated when bucket_name is left unset - typically the owning deployment's own name, so the created bucket carries workspace/deployment identity instead of an opaque AWS-generated name. Ignored when bucket_name or existing_bucket_name is set."
+  type        = string
+  default     = "greengrass-artifacts"
+
+  # Validate the prefix before it becomes part of an S3 bucket name.
+  validation {
+    condition     = can(regex("^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", var.bucket_name_prefix))
+    error_message = "bucket_name_prefix must be lowercase letters, digits and hyphens only, starting and ending with a letter or digit - it becomes the leading segment of an S3 bucket name."
+  }
+}
+
+variable "existing_bucket_name" {
+  description = "Name of an existing S3 bucket to import instead of creating one. When set, every other creation setting on this module is ignored - the imported bucket's encryption, versioning and public-access settings are whatever they already are."
+  type        = string
+  default     = null
+}
+
+variable "token_exchange_role_arn" {
+  description = "ARN of a Greengrass core device token exchange role to grant s3:GetObject on this bucket, scoped to token_exchange_key_prefix. Leave unset to skip the grant - the guide documents the policy to attach by hand."
+  type        = string
+  default     = null
+}
+
+variable "token_exchange_key_prefix" {
+  description = "Key prefix (glob) the token exchange role grant is scoped to. Defaults to the workspace component namespace; override for custom component names. Only used when token_exchange_role_arn is set."
+  type        = string
+  default     = "<%- componentKeyPrefix %>"
+}
+
+variable "tags" {
+  description = "Tags to apply to the created bucket."
+  type        = map(string)
+  default     = {}
+}
+
+locals {
+  creating        = var.existing_bucket_name == null
+  generating_name = local.creating && var.bucket_name == null
+  bucket_name     = local.creating ? aws_s3_bucket.bucket[0].id : var.existing_bucket_name
+  bucket_arn      = local.creating ? aws_s3_bucket.bucket[0].arn : data.aws_s3_bucket.existing[0].arn
+
+  # The account, region and stable random suffix fit within S3's 63-character
+  # limit after truncating the prefix to 20 characters.
+  generated_bucket_name = local.generating_name ? "${trimsuffix(substr(var.bucket_name_prefix, 0, 20), "-")}-${data.aws_caller_identity.current[0].account_id}-${data.aws_region.current[0].region}-${random_string.bucket_suffix[0].result}" : null
+
+  # Derive the imported role name from its ARN.
+  token_exchange_role_name_parts = var.token_exchange_role_arn != null ? split("/", var.token_exchange_role_arn) : []
+  token_exchange_role_name       = length(local.token_exchange_role_name_parts) > 0 ? local.token_exchange_role_name_parts[length(local.token_exchange_role_name_parts) - 1] : null
+}
+
+data "aws_s3_bucket" "existing" {
+  count  = local.creating ? 0 : 1
+  bucket = var.existing_bucket_name
+}
+
+# Read identity only when generating a bucket name.
+data "aws_caller_identity" "current" {
+  count = local.generating_name ? 1 : 0
+}
+
+data "aws_region" "current" {
+  count = local.generating_name ? 1 : 0
+}
+
+resource "random_string" "bucket_suffix" {
+  count   = local.generating_name ? 1 : 0
+  length  = 8
+  special = false
+  upper   = false
+}
+
+# Own one private, versioned, encrypted, TLS-only repository per account and
+# region; import it elsewhere with existing_bucket_name.
+resource "aws_s3_bucket" "bucket" {
+  count = local.creating ? 1 : 0
+  #checkov:skip=CKV_AWS_18:Server access logs are not configured; artifacts are immutable published bytes and reads are auditable through CloudTrail data events
+  #checkov:skip=CKV2_AWS_61:No lifecycle configuration; a published component version's artifact must stay retrievable for as long as any deployment can reference it - see the guide's documented inventory/cleanup policy instead
+  #checkov:skip=CKV2_AWS_62:Event notifications not required for an artifact repository nothing subscribes to
+  #checkov:skip=CKV_AWS_144:Cross-region replication not required - component artifacts are published once per region they are deployed into
+  #checkov:skip=CKV_AWS_145:AES256 (S3-managed) encryption is sufficient for published component artifacts
+  bucket = coalesce(var.bucket_name, local.generated_bucket_name)
+
+  tags = merge(var.tags, { "greengrass-artifact-repository" = "true" })
+
+  # Protect the repository against replacement or teardown. Remove this literal
+  # lifecycle setting only for deliberate cleanup.
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+
+resource "aws_s3_bucket_versioning" "bucket" {
+  count  = local.creating ? 1 : 0
+  bucket = aws_s3_bucket.bucket[0].id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "bucket" {
+  count  = local.creating ? 1 : 0
+  bucket = aws_s3_bucket.bucket[0].id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "bucket" {
+  count  = local.creating ? 1 : 0
+  bucket = aws_s3_bucket.bucket[0].id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_policy" "bucket" {
+  count  = local.creating ? 1 : 0
+  bucket = aws_s3_bucket.bucket[0].id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid       = "DenyInsecureConnections"
+        Effect    = "Deny"
+        Principal = "*"
+        Action    = "s3:*"
+        Resource = [
+          aws_s3_bucket.bucket[0].arn,
+          "${aws_s3_bucket.bucket[0].arn}/*"
+        ]
+        Condition = {
+          Bool = { "aws:SecureTransport" = "false" }
+        }
+      }
+    ]
+  })
+}
+
+# Grant the imported token exchange role read access to the selected key prefix.
+resource "aws_iam_role_policy" "token_exchange_read" {
+  count = var.token_exchange_role_arn != null ? 1 : 0
+
+  name = "greengrass-artifact-read"
+  role = local.token_exchange_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid      = "GreengrassArtifactRead"
+        Effect   = "Allow"
+        Action   = "s3:GetObject"
+        Resource = "${local.bucket_arn}/${var.token_exchange_key_prefix}"
+      }
+    ]
+  })
+}
+
+# Order consumers after the repository's hardening resources.
+output "bucket_name" {
+  value = local.bucket_name
+  depends_on = [
+    aws_s3_bucket_versioning.bucket,
+    aws_s3_bucket_server_side_encryption_configuration.bucket,
+    aws_s3_bucket_public_access_block.bucket,
+    aws_s3_bucket_policy.bucket,
+  ]
+}
+
+output "bucket_arn" {
+  value = local.bucket_arn
+  depends_on = [
+    aws_s3_bucket_versioning.bucket,
+    aws_s3_bucket_server_side_encryption_configuration.bucket,
+    aws_s3_bucket_public_access_block.bucket,
+    aws_s3_bucket_policy.bucket,
+  ]
+}