@resistdesign/voltra 3.0.0-alpha.3 → 3.0.0-alpha.31

package/iac/packs/auth/user-management.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Configuration for adding Cognito user management resources.
+ */
+type AddUserManagementConfigBase = {
+    /**
+     * Base id for Cognito resources.
+     */
+    id: string;
+    /**
+     * IAM role name for authenticated users.
+     */
+    authRoleName: string;
+    /**
+     * IAM role name for unauthenticated users.
+     */
+    unauthRoleName: string;
+    /**
+     * Alias target DNS name for the base domain record.
+     */
+    baseDomainRecordAliasTargetDNSName?: any;
+    /**
+     * API Gateway REST API id for authenticated access.
+     */
+    apiGatewayRESTAPIId?: any;
+    /**
+     * API Gateway stage name for authenticated access.
+     */
+    apiStageName?: any;
+};
+type AddUserManagementConfigWithDomain = AddUserManagementConfigBase & {
+    /**
+     * Enable Cognito Hosted UI/OAuth redirect mode by creating a custom user pool
+     * domain plus Route53 records.
+     *
+     * When enabled, the generated user pool client uses OAuth flows (`code`,
+     * `implicit`) and supports callback/logout/provider configuration.
+     *
+     * Defaults to `true`. Set `false` to opt out of Hosted UI resources and use
+     * SDK/API-based sign-in flows only.
+     */
+    enableUserPoolDomain?: true;
+    /**
+     * Base domain name used to create the auth subdomain.
+     *
+     * The pack creates a Cognito domain at `auth.<domainName>`.
+     */
+    domainName: any;
+    /**
+     * Route53 hosted zone id for DNS records under `domainName`.
+     */
+    hostedZoneId: any;
+    /**
+     * ACM certificate ARN (in `us-east-1`) for the Cognito custom domain.
+     */
+    sslCertificateArn: any;
+    /**
+     * OAuth callback URLs for Hosted UI/federated redirect flows.
+     *
+     * These must be valid redirect URLs accepted by Cognito for the app client.
+     * They are required by Cognito when OAuth flows are enabled.
+     */
+    callbackUrls?: any[];
+    /**
+     * OAuth logout redirect URLs for Hosted UI sign-out.
+     */
+    logoutUrls?: any[];
+    /**
+     * Supported identity providers for Hosted UI/OAuth flows.
+     *
+     * Defaults to `["COGNITO"]`.
+     * Use Cognito provider names such as `"COGNITO"`, `"Google"`,
+     * `"SignInWithApple"`, `"LoginWithAmazon"`, or names for configured OIDC/SAML
+     * providers.
+     */
+    supportedIdentityProviders?: any[];
+};
+type AddUserManagementConfigWithoutDomain = AddUserManagementConfigBase & {
+    /**
+     * Disable Cognito Hosted UI/OAuth redirect configuration.
+     *
+     * In this mode, the generated user pool client disables OAuth hosted-UI flows
+     * (`AllowedOAuthFlowsUserPoolClient: false`) so callback/logout/provider
+     * settings are intentionally disallowed.
+     */
+    enableUserPoolDomain: false;
+    domainName?: never;
+    hostedZoneId?: never;
+    sslCertificateArn?: never;
+    baseDomainRecordAliasTargetDNSName?: never;
+    callbackUrls?: never;
+    logoutUrls?: never;
+    supportedIdentityProviders?: never;
+};
+/**
+ * Configuration for {@link addUserManagement}.
+ */
+export type AddUserManagementConfig = AddUserManagementConfigWithDomain | AddUserManagementConfigWithoutDomain;
+/**
+ * Add Cognito user management resources to a template.
+ *
+ * @param config - User management configuration.
+ * @returns CloudFormation template fragment.
+ * @group Resource Packs
+ */
+export declare const addUserManagement: import("../..").ResourcePackApplier<AddUserManagementConfig>;
+export {};

package/iac/packs/auth.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Configuration for the auth pack.
+ */
+type AddAuthConfigBase = {
+    /**
+     * Cognito user pool resource id.
+     */
+    userManagementId: string;
+    /**
+     * IAM role name for authenticated users.
+     */
+    authRoleName: string;
+    /**
+     * IAM role name for unauthenticated users.
+     */
+    unauthRoleName: string;
+    /**
+     * API Gateway REST API id for the backend.
+     */
+    apiCloudFunctionGatewayId: string;
+    /**
+     * API Gateway stage name for the backend.
+     */
+    apiStageName: string;
+    /**
+     * Resource id for the admin group.
+     */
+    adminGroupId: string;
+    /**
+     * Cognito group name for admins.
+     */
+    userManagementAdminGroupName: string;
+};
+type AddAuthConfigWithUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Enable Cognito Hosted UI/OAuth redirect mode by creating a custom user pool
+     * domain plus Route53 records.
+     *
+     * When enabled, the generated user pool client uses OAuth flows (`code`,
+     * `implicit`) and supports callback/logout URL configuration.
+     *
+     * Defaults to `true`. Set `false` to opt out of Hosted UI resources and use
+     * SDK/API-based sign-in flows only.
+     */
+    enableUserPoolDomain?: true;
+    /**
+     * Parameter name for the Route53 hosted zone id that owns `domainName`.
+     *
+     * Required when `enableUserPoolDomain` is not `false`.
+     */
+    hostedZoneIdParameterName: string;
+    /**
+     * Parameter name for the base domain used for the auth subdomain.
+     *
+     * The pack creates a Cognito domain at `auth.<base-domain>`.
+     * Required when `enableUserPoolDomain` is not `false`.
+     */
+    domainNameParameterName: string;
+    /**
+     * ACM certificate resource id (in `us-east-1`) for the Cognito custom
+     * domain.
+     *
+     * Required when `enableUserPoolDomain` is not `false`.
+     */
+    sslCertificateId: string;
+    /**
+     * CloudFront distribution resource id used as the base-domain alias target.
+     *
+     * This is used for the root/base domain record before creating the auth
+     * subdomain record.
+     */
+    mainCDNCloudFrontId: string;
+    /**
+     * OAuth callback URLs for Hosted UI/federated redirect flows.
+     *
+     * These must be valid redirect URLs accepted by Cognito for the app client.
+     * They are required by Cognito when OAuth flows are enabled.
+     */
+    callbackUrls: any[];
+    /**
+     * OAuth logout redirect URLs for Hosted UI sign-out.
+     *
+     * These should match the application routes users are redirected to after
+     * logout.
+     */
+    logoutUrls: any[];
+    /**
+     * Supported identity providers for Hosted UI/OAuth flows.
+     *
+     * Defaults to `["COGNITO"]`.
+     * Use Cognito provider names such as `"COGNITO"`, `"Google"`,
+     * `"SignInWithApple"`, `"LoginWithAmazon"`, or names for configured OIDC/SAML
+     * providers.
+     */
+    supportedIdentityProviders?: any[];
+};
+type AddAuthConfigWithoutUserPoolDomain = AddAuthConfigBase & {
+    /**
+     * Disable Cognito Hosted UI/OAuth redirect configuration.
+     *
+     * In this mode, the generated user pool client disables OAuth hosted-UI flows
+     * (`AllowedOAuthFlowsUserPoolClient: false`) so callback/logout/provider
+     * settings are intentionally disallowed.
+     */
+    enableUserPoolDomain: false;
+    hostedZoneIdParameterName?: never;
+    domainNameParameterName?: never;
+    sslCertificateId?: never;
+    mainCDNCloudFrontId?: never;
+    callbackUrls?: never;
+    logoutUrls?: never;
+    supportedIdentityProviders?: never;
+};
+/**
+ * Configuration for {@link addAuth}.
+ */
+export type AddAuthConfig = AddAuthConfigWithUserPoolDomain | AddAuthConfigWithoutUserPoolDomain;
+/**
+ * Add auth resources including user management and an admin group.
+ *
+ * @group Resource Packs
+ */
+export declare const addAuth: import("..").ResourcePackApplier<AddAuthConfig>;
+export {};

package/iac/packs/build/utils.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Require at least one key from the provided type.
+ *
+ * @typeParam T - Base object type.
+ * @typeParam U - Helper mapped type.
+ */
+export type AtLeastOne<T, U = {
+    [K in keyof T]: Pick<T, K>;
+}> = Partial<T> & U[keyof U];
+/**
+ * Helper functions for generating CLI commands in build specs.
+ */
+export declare const COMMAND_HELPERS: {
+    updateFunction: ({ cloudFunctionArn, codeZipFilePath, }: {
+        cloudFunctionArn: string;
+        codeZipFilePath: string;
+    }) => string;
+    copyDirectoryToS3: ({ s3Domain, directoryPath, }: {
+        s3Domain: string;
+        directoryPath: string;
+    }) => string;
+    cloudFrontInvalidation: ({ cloudFrontDistributionId, pathsToInvalidate, }: {
+        cloudFrontDistributionId: string;
+        pathsToInvalidate?: string[];
+    }) => string;
+    addNPMTokenWithNPMRC: ({ npmToken }: {
+        npmToken: string;
+    }) => string;
+};
+/**
+ * Linux user name string.
+ */
+export type LinuxUserNameString = string;
+/**
+ * Flag value for yes/no configuration fields.
+ */
+export type YesOrNo = "yes" | "no";
+/**
+ * BuildSpec environment configuration.
+ */
+export interface Env {
+    /**
+     * Shell to use for command execution.
+     */
+    shell?: "bash" | "/bin/sh" | "powershell.exe" | "cmd.exe" | string;
+    /**
+     * Environment variables to expose.
+     */
+    variables?: Record<string, string>;
+    /**
+     * SSM parameter store references.
+     */
+    "parameter-store"?: Record<string, string>;
+    /**
+     * Exported variable names.
+     */
+    "exported-variables"?: string[];
+    /**
+     * Secrets Manager references.
+     */
+    "secrets-manager"?: Record<string, `${string}:${string}:${string}:${string}`>;
+    /**
+     * Whether to enable git credential helper.
+     */
+    "git-credential-helper"?: YesOrNo;
+}
+/**
+ * BuildSpec proxy configuration.
+ */
+export interface Proxy {
+    /**
+     * Whether to upload build artifacts via proxy.
+     */
+    "upload-artifacts"?: YesOrNo;
+    /**
+     * Whether to proxy logs.
+     */
+    logs?: YesOrNo;
+}
+/**
+ * BuildSpec batch build configuration.
+ */
+export interface Batch {
+    /**
+     * Whether to fail fast for batch builds.
+     */
+    "fast-fail"?: boolean;
+    /**
+     * Batch build list config.
+     */
+    "build-list"?: any;
+    /**
+     * Batch build matrix config.
+     */
+    "build-matrix"?: any;
+    /**
+     * Batch build graph config.
+     */
+    "build-graph"?: any;
+    [key: string]: any;
+}
+/**
+ * BuildSpec phase configuration.
+ */
+export interface Phase {
+    /**
+     * Runtime versions for this phase.
+     */
+    "runtime-versions"?: Record<string, any>;
+    /**
+     * User to run commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Behavior when a command fails.
+     */
+    "on-failure"?: "ABORT" | "CONTINUE";
+    /**
+     * Commands to run during the phase.
+     */
+    commands: string[];
+    /**
+     * Commands to always run at the end of the phase.
+     */
+    finally?: string[];
+}
+/**
+ * BuildSpec phase collection (at least one phase required).
+ */
+export type PhaseConfig = AtLeastOne<{
+    install: Phase;
+    pre_build: Phase;
+    build: Phase;
+    post_build: Phase;
+}>;
+/**
+ * Report group configuration for build reports.
+ */
+export interface ReportGroupNameOrArn {
+    /**
+     * Report files to include.
+     */
+    files?: string[];
+    /**
+     * Base directory for report files.
+     */
+    "base-directory"?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Report file format.
+     */
+    "file-format"?: string;
+}
+/**
+ * Reports configuration for BuildSpec.
+ */
+export interface Reports {
+    /**
+     * Report group name or ARN.
+     */
+    "report-group-name-or-arn"?: ReportGroupNameOrArn;
+}
+/**
+ * Artifact identifier configuration.
+ */
+export interface ArtifactIdentifier {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+}
+/**
+ * Secondary artifacts configuration.
+ */
+export interface SecondaryArtifacts {
+    /**
+     * Artifact identifier for secondary artifacts.
+     */
+    artifactIdentifier?: ArtifactIdentifier;
+}
+/**
+ * Artifacts configuration for BuildSpec.
+ */
+export interface Artifacts {
+    /**
+     * Artifact file list.
+     */
+    files?: string[];
+    /**
+     * Artifact name.
+     */
+    name?: string;
+    /**
+     * Whether to discard path prefixes.
+     */
+    "discard-paths"?: string;
+    /**
+     * Base directory for artifact files.
+     */
+    "base-directory"?: string;
+    /**
+     * Paths to exclude from artifacts.
+     */
+    "exclude-paths"?: string;
+    /**
+     * Whether to enable symlinks in artifacts.
+     */
+    "enable-symlinks"?: string;
+    /**
+     * S3 prefix for artifact upload.
+     */
+    "s3-prefix"?: string;
+    /**
+     * Secondary artifacts configuration.
+     */
+    "secondary-artifacts"?: SecondaryArtifacts;
+}
+/**
+ * Cache configuration for BuildSpec.
+ */
+export interface Cache {
+    /**
+     * Cache paths to persist between builds.
+     */
+    paths?: string[];
+}
+/**
+ * BuildSpec configuration object.
+ */
+export interface BuildSpec {
+    /**
+     * Build spec version.
+     */
+    version?: number;
+    /**
+     * User to run build commands as.
+     */
+    "run-as"?: LinuxUserNameString;
+    /**
+     * Environment configuration.
+     */
+    env?: Env;
+    /**
+     * Proxy configuration.
+     */
+    proxy?: Proxy;
+    /**
+     * Batch build configuration.
+     */
+    batch?: Batch;
+    /**
+     * Build phases configuration.
+     */
+    phases: PhaseConfig;
+    /**
+     * Reports configuration.
+     */
+    reports?: Reports;
+    /**
+     * Artifacts configuration.
+     */
+    artifacts?: Artifacts;
+    /**
+     * Cache configuration.
+     */
+    cache?: Cache;
+}
+/**
+ * Create a build spec YAML string for a build pipeline (CI/CD).
+ *
+ * @param config - Build spec configuration.
+ * @returns YAML string for the build spec.
+ */
+export declare const createBuildSpec: ({ version, phases }: BuildSpec) => string;

package/iac/packs/build.d.ts

@@ -0,0 +1,92 @@
+import { AWS } from "../types/IaCTypes";
+/**
+ * Default repository provider for CodePipeline source actions.
+ */
+export declare const DEFAULT_BUILD_PIPELINE_REPO_PROVIDER = "GitHub";
+/**
+ * Source repository configuration for the build pipeline.
+ */
+export type BuildPipelineRepoConfig = {
+    /**
+     * CodePipeline provider (e.g., GitHub).
+     */
+    provider?: any;
+    /**
+     * Repository owner/organization.
+     */
+    owner: any;
+    /**
+     * Repository name.
+     */
+    repo: any;
+    /**
+     * Repository branch name.
+     */
+    branch: any;
+    /**
+     * OAuth token for source access.
+     */
+    oauthToken: any;
+};
+/**
+ * Helper for custom CodeBuild string literals.
+ */
+export type CustomCodeBuildString<T extends string> = T & {
+    __custom?: never;
+};
+/**
+ * Allowed CodeBuild environment types.
+ */
+export type CodeBuildEnvironmentType = "ARM_CONTAINER" | "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER" | "WINDOWS_SERVER_2022_CONTAINER" | "LINUX_EC2" | "ARM_EC2" | "WINDOWS_EC2" | "MAC_ARM" | CustomCodeBuildString<string>;
+/**
+ * Allowed CodeBuild compute types.
+ */
+export type CodeBuildComputeType = "BUILD_GENERAL1_SMALL" | "BUILD_GENERAL1_MEDIUM" | "BUILD_GENERAL1_LARGE" | "BUILD_GENERAL1_2XLARGE" | "BUILD_GENERAL1_XLARGE" | CustomCodeBuildString<string>;
+/**
+ * Configuration for the build pipeline pack.
+ */
+export type AddBuildPipelineConfig = {
+    /**
+     * Base id for created resources.
+     */
+    id: string;
+    /**
+     * Build spec YAML or JSON.
+     */
+    buildSpec: any;
+    /**
+     * Optional resource dependencies.
+     */
+    dependsOn?: string | string[];
+    /**
+     * CodeBuild environment variables.
+     */
+    environmentVariables?: AWS.CodeBuild.Project.EnvironmentVariable[];
+    /**
+     * Build timeout in minutes.
+     */
+    timeoutInMinutes?: number;
+    /**
+     * CodeBuild environment type.
+     */
+    environmentType?: CodeBuildEnvironmentType;
+    /**
+     * CodeBuild compute type.
+     */
+    environmentComputeType?: CodeBuildComputeType;
+    /**
+     * CodeBuild image to run.
+     */
+    environmentImage?: string;
+    /**
+     * Repository configuration for source stage.
+     */
+    repoConfig: BuildPipelineRepoConfig;
+};
+/**
+ * Add a build pipeline with full permissions.
+ *
+ * @param config - Build pipeline configuration.
+ * @group Resource Packs
+ */
+export declare const addBuildPipeline: import("..").ResourcePackApplier<AddBuildPipelineConfig>;

package/iac/packs/cdn.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration for the CDN pack.
+ */
+export type AddCDNConfig = {
+    /**
+     * CloudFront distribution id.
+     */
+    id: string;
+    /**
+     * Route53 hosted zone id for the domain.
+     */
+    hostedZoneId: any;
+    /**
+     * Domain name to serve.
+     */
+    domainName: any;
+    /**
+     * ACM certificate ARN for the domain.
+     */
+    certificateArn: any;
+    /**
+     * S3 file storage resource id.
+     */
+    fileStorageId: string;
+};
+/**
+ * Add a global cache of static files (a CDN) for things like your front-end, website, etc.
+ * Includes a DNS record for the domain.
+ *
+ * @param config - CDN configuration.
+ * @group Resource Packs
+ * */
+export declare const addCDN: import("..").ResourcePackApplier<AddCDNConfig>;

package/iac/packs/cloud-function.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @packageDocumentation
+ *
+ * Lambda pack that provisions a basic function with an IAM role and optional
+ * environment settings.
+ */
+import { AWS } from "../types/IaCTypes";
+/**
+ * Default inline function code for placeholder Lambda resources.
+ */
+export declare const PLACEHOLDER_FUNCTION_CODE: AWS.Lambda.Function.Code;
+/**
+ * Supported Lambda runtimes for cloud functions.
+ */
+export type CloudFunctionRuntime = "nodejs14.x" | "nodejs16.x" | "nodejs18.x" | "nodejs20.x" | "nodejs22.x" | "nodejs24.x" | "nodejs26.x" | "python3.8" | "python3.9" | "python3.10" | "python3.11" | "python3.12" | "python3.13" | "python3.14" | "python3.15" | "java11" | "java17" | "java21" | "java25" | "dotnet6" | "dotnet8" | "dotnet10" | "go1.x" | "ruby2.7" | "ruby3.2" | "ruby3.3" | "ruby3.4" | "ruby3.5" | "provided" | "provided.al2" | "provided.al2023";
+/**
+ * Configuration for the cloud function pack.
+ */
+export type AddCloudFunctionConfig = {
+    /**
+     * Base id for the function resources.
+     */
+    id: string;
+    /**
+     * Lambda function code.
+     */
+    code?: AWS.Lambda.Function.Code;
+    /**
+     * Lambda environment configuration.
+     */
+    environment?: AWS.Lambda.Function.Environment;
+    /**
+     * Function handler entrypoint.
+     */
+    handler?: any;
+    /**
+     * Lambda runtime.
+     */
+    runtime?: CloudFunctionRuntime;
+    /**
+     * Function timeout in seconds.
+     */
+    timeout?: any;
+    /**
+     * IAM policy statements to attach to the role.
+     */
+    policies?: AWS.IAM.Role.Policy[];
+    /**
+     * Lambda function memory size in MB.
+     *
+     * You can configure memory between 128 MB and 10,240 MB in 1-MB increments.
+     *
+     * @default 128
+     */
+    memorySize?: number;
+};
+/**
+ * Add a serverless cloud function to run part or all of your API (back-end) without always running servers.
+ *
+ * @param config - Cloud function configuration.
+ * */
+/**
+ * Add a cloud function resource with IAM role and configuration.
+ *
+ * @group Resource Packs
+ */
+export declare const addCloudFunction: import("..").ResourcePackApplier<AddCloudFunctionConfig>;