@ts-cloud/core 0.2.3 → 0.2.4

package/dist/modules/auth.d.ts

@@ -0,0 +1,262 @@
+import type { CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoIdentityPool, CognitoIdentityPoolRoleAttachment, IAMRole } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface UserPoolOptions {
+    slug: string;
+    environment: EnvironmentType;
+    userPoolName?: string;
+    aliasAttributes?: ('email' | 'phone_number')[];
+    autoVerifiedAttributes?: ('email' | 'phone_number')[];
+    passwordPolicy?: PasswordPolicyOptions;
+    mfaConfiguration?: 'OFF' | 'ON' | 'OPTIONAL';
+    emailConfiguration?: EmailConfigurationOptions;
+    smsConfiguration?: SmsConfigurationOptions;
+    lambdaTriggers?: LambdaTriggersOptions;
+    userPoolAddOns?: {
+        advancedSecurityMode?: 'OFF' | 'AUDIT' | 'ENFORCED';
+    };
+    accountRecoverySetting?: {
+        recoveryMechanisms: Array<{
+            Name: 'verified_email' | 'verified_phone_number' | 'admin_only';
+            Priority: number;
+        }>;
+    };
+}
+export interface PasswordPolicyOptions {
+    minimumLength?: number;
+    requireLowercase?: boolean;
+    requireUppercase?: boolean;
+    requireNumbers?: boolean;
+    requireSymbols?: boolean;
+    temporaryPasswordValidityDays?: number;
+}
+export interface EmailConfigurationOptions {
+    emailSendingAccount?: 'COGNITO_DEFAULT' | 'DEVELOPER';
+    from?: string;
+    replyToEmailAddress?: string;
+    sourceArn?: string;
+    configurationSet?: string;
+}
+export interface SmsConfigurationOptions {
+    externalId: string;
+    snsCallerArn: string;
+}
+export interface LambdaTriggersOptions {
+    preSignUp?: string;
+    postConfirmation?: string;
+    preAuthentication?: string;
+    postAuthentication?: string;
+    customMessage?: string;
+    defineAuthChallenge?: string;
+    createAuthChallenge?: string;
+    verifyAuthChallengeResponse?: string;
+    preTokenGeneration?: string;
+    userMigration?: string;
+}
+export interface UserPoolClientOptions {
+    slug: string;
+    environment: EnvironmentType;
+    clientName?: string;
+    generateSecret?: boolean;
+    refreshTokenValidity?: number;
+    accessTokenValidity?: number;
+    idTokenValidity?: number;
+    tokenValidityUnits?: {
+        RefreshToken?: 'seconds' | 'minutes' | 'hours' | 'days';
+        AccessToken?: 'seconds' | 'minutes' | 'hours' | 'days';
+        IdToken?: 'seconds' | 'minutes' | 'hours' | 'days';
+    };
+    readAttributes?: string[];
+    writeAttributes?: string[];
+    explicitAuthFlows?: string[];
+    preventUserExistenceErrors?: 'ENABLED' | 'LEGACY';
+    enableTokenRevocation?: boolean;
+    callbackURLs?: string[];
+    logoutURLs?: string[];
+    allowedOAuthFlows?: ('code' | 'implicit' | 'client_credentials')[];
+    allowedOAuthScopes?: string[];
+    allowedOAuthFlowsUserPoolClient?: boolean;
+    supportedIdentityProviders?: string[];
+}
+export interface UserPoolDomainOptions {
+    slug: string;
+    environment: EnvironmentType;
+    domain: string;
+    customDomainConfig?: {
+        CertificateArn: string;
+    };
+}
+export interface IdentityPoolOptions {
+    slug: string;
+    environment: EnvironmentType;
+    identityPoolName?: string;
+    allowUnauthenticatedIdentities?: boolean;
+    cognitoIdentityProviders?: Array<{
+        ClientId: string;
+        ProviderName: string;
+        ServerSideTokenCheck?: boolean;
+    }>;
+    supportedLoginProviders?: Record<string, string>;
+    samlProviderARNs?: string[];
+    openIdConnectProviderARNs?: string[];
+}
+export interface IdentityPoolRoleAttachmentOptions {
+    slug: string;
+    environment: EnvironmentType;
+    authenticatedRole: string;
+    unauthenticatedRole?: string;
+    roleMappings?: Record<string, {
+        Type: 'Token' | 'Rules';
+        AmbiguousRoleResolution?: 'AuthenticatedRole' | 'Deny';
+        RulesConfiguration?: {
+            Rules: Array<{
+                Claim: string;
+                MatchType: 'Equals' | 'Contains' | 'StartsWith' | 'NotEqual';
+                Value: string;
+                RoleARN: string;
+            }>;
+        };
+    }>;
+}
+/**
+ * Authentication Module - Cognito
+ * Provides clean API for user authentication and identity management
+ */
+export declare class Auth {
+    /**
+     * Create a Cognito User Pool
+     */
+    static createUserPool(options: UserPoolOptions): {
+        userPool: CognitoUserPool;
+        logicalId: string;
+    };
+    /**
+     * Create a Cognito User Pool Client
+     */
+    static createUserPoolClient(userPoolLogicalId: string, options: UserPoolClientOptions): {
+        client: CognitoUserPoolClient;
+        logicalId: string;
+    };
+    /**
+     * Create a Cognito User Pool Domain
+     */
+    static createUserPoolDomain(userPoolLogicalId: string, options: UserPoolDomainOptions): {
+        domain: CognitoUserPoolDomain;
+        logicalId: string;
+    };
+    /**
+     * Create a Cognito Identity Pool
+     */
+    static createIdentityPool(options: IdentityPoolOptions): {
+        identityPool: CognitoIdentityPool;
+        logicalId: string;
+    };
+    /**
+     * Create an Identity Pool Role Attachment
+     */
+    static createIdentityPoolRoleAttachment(identityPoolLogicalId: string, options: IdentityPoolRoleAttachmentOptions): {
+        attachment: CognitoIdentityPoolRoleAttachment;
+        logicalId: string;
+    };
+    /**
+     * Create IAM role for authenticated users
+     */
+    static createAuthenticatedRole(options: {
+        slug: string;
+        environment: EnvironmentType;
+        identityPoolLogicalId: string;
+    }): {
+        role: IAMRole;
+        logicalId: string;
+    };
+    /**
+     * Create IAM role for unauthenticated users
+     */
+    static createUnauthenticatedRole(options: {
+        slug: string;
+        environment: EnvironmentType;
+        identityPoolLogicalId: string;
+    }): {
+        role: IAMRole;
+        logicalId: string;
+    };
+    /**
+     * Common password policies
+     */
+    static readonly PasswordPolicies: {
+        /**
+         * Relaxed password policy for development
+         */
+        readonly relaxed: () => PasswordPolicyOptions;
+        /**
+         * Standard password policy
+         */
+        readonly standard: () => PasswordPolicyOptions;
+        /**
+         * Strict password policy for production
+         */
+        readonly strict: () => PasswordPolicyOptions;
+    };
+    /**
+     * Common authentication flows
+     */
+    static readonly AuthFlows: {
+        /**
+         * Standard auth flows (SRP, refresh token)
+         */
+        readonly standard: readonly ["ALLOW_USER_SRP_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"];
+        /**
+         * Admin auth flows (for server-side authentication)
+         */
+        readonly admin: readonly ["ALLOW_ADMIN_USER_PASSWORD_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"];
+        /**
+         * Custom auth flows
+         */
+        readonly custom: readonly ["ALLOW_CUSTOM_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"];
+        /**
+         * All auth flows (not recommended for production)
+         */
+        readonly all: readonly ["ALLOW_USER_SRP_AUTH", "ALLOW_USER_PASSWORD_AUTH", "ALLOW_ADMIN_USER_PASSWORD_AUTH", "ALLOW_CUSTOM_AUTH", "ALLOW_REFRESH_TOKEN_AUTH"];
+    };
+    /**
+     * Common OAuth scopes
+     */
+    static readonly OAuthScopes: {
+        /**
+         * Basic OAuth scopes
+         */
+        readonly basic: readonly ["openid", "email", "profile"];
+        /**
+         * All standard scopes
+         */
+        readonly all: readonly ["openid", "email", "profile", "phone", "aws.cognito.signin.user.admin"];
+    };
+    /**
+     * Common use cases
+     */
+    static readonly UseCases: {
+        /**
+         * Create a basic user pool for web application
+         */
+        readonly webApp: (slug: string, environment: EnvironmentType, callbackUrl: string) => {
+            userPool: CognitoUserPool;
+            poolId: string;
+            client: CognitoUserPoolClient;
+            clientId: string;
+        };
+        /**
+         * Create a user pool with identity pool for mobile app
+         */
+        readonly mobileApp: (slug: string, environment: EnvironmentType) => {
+            userPool: CognitoUserPool;
+            poolId: string;
+            client: CognitoUserPoolClient;
+            clientId: string;
+            identityPool: CognitoIdentityPool;
+            identityPoolId: string;
+            authRole: IAMRole;
+            authRoleId: string;
+            attachment: CognitoIdentityPoolRoleAttachment;
+            attachmentId: string;
+        };
+    };
+}

package/dist/modules/cache.d.ts

@@ -0,0 +1,108 @@
+import type { ElastiCacheCluster, ElastiCacheParameterGroup, ElastiCacheReplicationGroup, ElastiCacheSubnetGroup } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface RedisOptions {
+    slug: string;
+    environment: EnvironmentType;
+    nodeType?: string;
+    engineVersion?: string;
+    port?: number;
+    subnetIds?: string[];
+    securityGroupIds?: string[];
+    numCacheClusters?: number;
+    automaticFailover?: boolean;
+    multiAz?: boolean;
+    clusterMode?: boolean;
+    numNodeGroups?: number;
+    replicasPerNodeGroup?: number;
+    atRestEncryption?: boolean;
+    transitEncryption?: boolean;
+    authToken?: string;
+    kmsKeyId?: string;
+    snapshotRetentionDays?: number;
+    snapshotWindow?: string;
+    maintenanceWindow?: string;
+}
+export interface MemcachedOptions {
+    slug: string;
+    environment: EnvironmentType;
+    nodeType?: string;
+    engineVersion?: string;
+    port?: number;
+    numCacheNodes?: number;
+    subnetIds?: string[];
+    securityGroupIds?: string[];
+    azMode?: 'single-az' | 'cross-az';
+    preferredAzs?: string[];
+    maintenanceWindow?: string;
+}
+/**
+ * Cache Module - ElastiCache (Redis + Memcached)
+ * Provides clean API for creating Redis and Memcached clusters
+ */
+export declare class Cache {
+    /**
+     * Create a Redis cluster
+     */
+    static createRedis(options: RedisOptions): {
+        replicationGroup: ElastiCacheReplicationGroup;
+        subnetGroup?: ElastiCacheSubnetGroup;
+        logicalId: string;
+        subnetGroupId?: string;
+    };
+    /**
+     * Create a Memcached cluster
+     */
+    static createMemcached(options: MemcachedOptions): {
+        cluster: ElastiCacheCluster;
+        subnetGroup?: ElastiCacheSubnetGroup;
+        logicalId: string;
+        subnetGroupId?: string;
+    };
+    /**
+     * Enable cluster mode for Redis (returns new configuration)
+     */
+    static enableClusterMode(replicationGroup: ElastiCacheReplicationGroup, numNodeGroups?: number, replicasPerNodeGroup?: number): ElastiCacheReplicationGroup;
+    /**
+     * Create a parameter group for Redis
+     */
+    static createRedisParameterGroup(version: string, options: {
+        slug: string;
+        environment: EnvironmentType;
+        parameters?: Record<string, string>;
+    }): {
+        parameterGroup: ElastiCacheParameterGroup;
+        logicalId: string;
+    };
+    /**
+     * Create a parameter group for Memcached
+     */
+    static createMemcachedParameterGroup(version: string, options: {
+        slug: string;
+        environment: EnvironmentType;
+        parameters?: Record<string, string>;
+    }): {
+        parameterGroup: ElastiCacheParameterGroup;
+        logicalId: string;
+    };
+    /**
+     * Common ElastiCache node types
+     */
+    static readonly NodeTypes: {
+        readonly T3_Micro: "cache.t3.micro";
+        readonly T3_Small: "cache.t3.small";
+        readonly T3_Medium: "cache.t3.medium";
+        readonly T4g_Micro: "cache.t4g.micro";
+        readonly T4g_Small: "cache.t4g.small";
+        readonly T4g_Medium: "cache.t4g.medium";
+        readonly M5_Large: "cache.m5.large";
+        readonly M5_XLarge: "cache.m5.xlarge";
+        readonly M5_2XLarge: "cache.m5.2xlarge";
+        readonly R5_Large: "cache.r5.large";
+        readonly R5_XLarge: "cache.r5.xlarge";
+        readonly R5_2XLarge: "cache.r5.2xlarge";
+        readonly R5_4XLarge: "cache.r5.4xlarge";
+        readonly R6g_Large: "cache.r6g.large";
+        readonly R6g_XLarge: "cache.r6g.xlarge";
+        readonly R6g_2XLarge: "cache.r6g.2xlarge";
+    };
+}

package/dist/modules/cdn.d.ts

@@ -0,0 +1,305 @@
+import type { CloudFrontDistribution, CloudFrontOriginAccessControl, LambdaFunction, IAMRole } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface DistributionOptions {
+    slug: string;
+    environment: EnvironmentType;
+    origin: OriginConfig;
+    customDomain?: string;
+    certificateArn?: string;
+    errorPages?: ErrorPageMapping[];
+    cachePolicy?: CachePolicyConfig;
+    edgeFunctions?: EdgeFunctionConfig[];
+    http3?: boolean;
+    comment?: string;
+}
+export interface OriginConfig {
+    type?: 's3' | 'alb' | 'custom';
+    id?: string;
+    originId?: string;
+    domainName?: string;
+    originPath?: string;
+    customHeaders?: Record<string, string>;
+    s3OriginAccessControl?: string;
+}
+export interface ErrorPageMapping {
+    errorCode: number;
+    responseCode?: number;
+    responsePagePath?: string;
+}
+export interface CachePolicyConfig {
+    minTTL?: number;
+    maxTTL?: number;
+    defaultTTL?: number;
+}
+export interface EdgeFunctionConfig {
+    event: 'origin-request' | 'origin-response' | 'viewer-request' | 'viewer-response';
+    functionArn: string;
+}
+/**
+ * CDN Module - CloudFront Distribution Management
+ * Provides clean API for creating and configuring CloudFront distributions
+ */
+export declare class CDN {
+    /**
+     * Create a CloudFront distribution
+     */
+    static createDistribution(options: DistributionOptions): {
+        distribution: CloudFrontDistribution;
+        originAccessControl?: CloudFrontOriginAccessControl;
+        logicalId: string;
+    };
+    /**
+     * Set custom domain on a distribution
+     */
+    static setCustomDomain(distribution: CloudFrontDistribution, domain: string, certificateArn: string): CloudFrontDistribution;
+    /**
+     * Set error pages for SPA routing (404 → index.html)
+     */
+    static setErrorPages(distribution: CloudFrontDistribution, mappings: ErrorPageMapping[]): CloudFrontDistribution;
+    /**
+     * Enable HTTP/3 support
+     */
+    static enableHttp3(distribution: CloudFrontDistribution): CloudFrontDistribution;
+    /**
+     * Add Lambda@Edge function
+     */
+    static addEdgeFunction(distribution: CloudFrontDistribution, event: EdgeFunctionConfig['event'], functionArn: string): CloudFrontDistribution;
+    /**
+     * Set cache policy with custom TTL
+     */
+    static setCachePolicy(distribution: CloudFrontDistribution, ttl: {
+        min?: number;
+        max?: number;
+        default?: number;
+    }): CloudFrontDistribution;
+    /**
+     * Create standard SPA (Single Page Application) configuration
+     * Routes all 404/403 errors to index.html
+     */
+    static createSpaDistribution(options: Omit<DistributionOptions, 'errorPages'>): ReturnType<typeof CDN.createDistribution>;
+    /**
+     * Create Lambda@Edge origin request function for docs routing
+     * Handles:
+     * - Pretty URLs (e.g., /guide → /guide.html or /guide/index.html)
+     * - Trailing slashes normalization
+     * - Default document serving (index.html)
+     */
+    static createDocsOriginRequestFunction(options: {
+        slug: string;
+        environment: EnvironmentType;
+    }): {
+        lambdaFunction: LambdaFunction;
+        role: IAMRole;
+        functionLogicalId: string;
+        roleLogicalId: string;
+        versionLogicalId: string;
+    };
+    /**
+     * Create a docs-specific CloudFront distribution
+     * Includes Lambda@Edge for URL rewriting and proper cache settings
+     */
+    static createDocsDistribution(options: {
+        slug: string;
+        environment: EnvironmentType;
+        origin: OriginConfig;
+        customDomain?: string;
+        certificateArn?: string;
+        lambdaEdgeFunctionArn?: string;
+    }): {
+        distribution: CloudFrontDistribution;
+        originAccessControl?: CloudFrontOriginAccessControl;
+        logicalId: string;
+    };
+    /**
+     * Create an API distribution with ALB origin
+     * Optimized for API traffic (no caching by default, all methods allowed)
+     */
+    static createApiDistribution(options: {
+        slug: string;
+        environment: EnvironmentType;
+        albDomainName: string;
+        customDomain?: string;
+        certificateArn?: string;
+        pathPattern?: string;
+        forwardHeaders?: string[];
+        forwardCookies?: 'none' | 'all' | 'whitelist';
+        whitelistedCookies?: string[];
+        customOriginHeaders?: Record<string, string>;
+    }): {
+        distribution: CloudFrontDistribution;
+        logicalId: string;
+    };
+    /**
+     * Create a multi-origin distribution (S3 for static, ALB for API)
+     */
+    static createMultiOriginDistribution(options: {
+        slug: string;
+        environment: EnvironmentType;
+        s3BucketDomainName: string;
+        albDomainName: string;
+        apiPathPattern?: string;
+        customDomain?: string;
+        certificateArn?: string;
+        customOriginHeaders?: Record<string, string>;
+    }): {
+        distribution: CloudFrontDistribution;
+        originAccessControl: CloudFrontOriginAccessControl;
+        logicalId: string;
+        oacLogicalId: string;
+    };
+    /**
+     * Add ALB origin to an existing distribution
+     */
+    static addAlbOrigin(distribution: CloudFrontDistribution, options: {
+        originId: string;
+        domainName: string;
+        pathPattern: string;
+        customHeaders?: Record<string, string>;
+        forwardHeaders?: string[];
+        cacheTtl?: {
+            default: number;
+            max: number;
+            min: number;
+        };
+    }): CloudFrontDistribution;
+    /**
+     * Add a custom origin header (for origin authentication)
+     */
+    static addOriginHeader(distribution: CloudFrontDistribution, originId: string, headerName: string, headerValue: string): CloudFrontDistribution;
+    /**
+     * Lambda@Edge code templates for common use cases
+     */
+    static readonly EdgeFunctionTemplates: {
+        /**
+         * Origin request handler for docs/VitePress routing
+         */
+        docsOriginRequest: string;
+        /**
+         * Viewer response handler for security headers
+         */
+        securityHeaders: string;
+        /**
+         * Viewer request handler for basic auth (staging/preview environments)
+         */
+        basicAuth: (username: string, password: string) => string;
+        /**
+         * Origin request handler for path-based routing (e.g., /api to different origin)
+         */
+        pathBasedRouting: (pathPrefix: string, targetOriginId: string) => string;
+    };
+    /**
+     * CDN Configuration helpers
+     * Provides Stacks configuration parity for CDN options
+     */
+    static readonly Config: {
+        /**
+         * Create TTL configuration
+         */
+        ttl: (options: {
+            min?: number;
+            max?: number;
+            default?: number;
+        }) => {
+            MinTTL: number;
+            MaxTTL: number;
+            DefaultTTL: number;
+        };
+        /**
+         * Cookie behavior configuration
+         */
+        cookies: (behavior: "none" | "all" | "allowList", allowedCookies?: string[]) => {
+            Forward: string;
+            WhitelistedNames?: string[];
+        };
+        /**
+         * Allowed HTTP methods configuration
+         */
+        allowedMethods: (methods: "ALL" | "GET_HEAD" | "GET_HEAD_OPTIONS") => string[];
+        /**
+         * Cached methods configuration
+         */
+        cachedMethods: (methods: "GET_HEAD" | "GET_HEAD_OPTIONS") => string[];
+        /**
+         * Common TTL presets
+         */
+        ttlPresets: {
+            /** Static assets (1 year) */
+            readonly static: {
+                readonly min: 0;
+                readonly max: 31536000;
+                readonly default: 31536000;
+            };
+            /** Dynamic content (no cache) */
+            readonly dynamic: {
+                readonly min: 0;
+                readonly max: 0;
+                readonly default: 0;
+            };
+            /** API responses (1 hour) */
+            readonly api: {
+                readonly min: 0;
+                readonly max: 3600;
+                readonly default: 60;
+            };
+            /** SPA/HTML (1 day) */
+            readonly html: {
+                readonly min: 0;
+                readonly max: 86400;
+                readonly default: 86400;
+            };
+            /** Images (1 week) */
+            readonly images: {
+                readonly min: 0;
+                readonly max: 604800;
+                readonly default: 604800;
+            };
+        };
+        /**
+         * Create cache behavior configuration
+         */
+        cacheBehavior: (options: {
+            ttl?: {
+                min: number;
+                max: number;
+                default: number;
+            };
+            cookies?: "none" | "all" | "allowList";
+            allowedCookies?: string[];
+            allowedMethods?: "ALL" | "GET_HEAD" | "GET_HEAD_OPTIONS";
+            cachedMethods?: "GET_HEAD" | "GET_HEAD_OPTIONS";
+            compress?: boolean;
+            forwardQueryString?: boolean;
+            forwardHeaders?: string[];
+        }) => {
+            MinTTL: number;
+            MaxTTL: number;
+            DefaultTTL: number;
+            Compress: boolean;
+            AllowedMethods: string[];
+            CachedMethods: string[];
+            ForwardedValues: {
+                QueryString: boolean;
+                Headers: string[];
+                Cookies: {
+                    Forward: string;
+                    WhitelistedNames?: string[];
+                };
+            };
+        };
+    };
+    /**
+     * Apply configuration to an existing distribution
+     */
+    static applyConfig(distribution: CloudFrontDistribution, config: {
+        ttl?: {
+            min: number;
+            max: number;
+            default: number;
+        };
+        cookies?: 'none' | 'all' | 'allowList';
+        allowedCookies?: string[];
+        allowedMethods?: 'ALL' | 'GET_HEAD' | 'GET_HEAD_OPTIONS';
+        cachedMethods?: 'GET_HEAD' | 'GET_HEAD_OPTIONS';
+        compress?: boolean;
+    }): CloudFrontDistribution;
+}