@stacksjs/ts-cloud-core 0.1.3 → 0.1.7

package/README.md

@@ -6,13 +6,13 @@
 <!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
 <!-- [![Codecov][codecov-src]][codecov-href] -->
 
-# ts-cloud
+# @stacksjs/ts-cloud
 
 > Zero-dependency AWS infrastructure as TypeScript. Deploy production-ready cloud infrastructure without AWS SDK or CLI.
 
 ## Overview
 
-ts-cloud is a modern infrastructure-as-code framework that lets you define AWS infrastructure using TypeScript configuration files. Unlike AWS CDK or Terraform, ts-cloud:
+@stacksjs/ts-cloud is a modern infrastructure-as-code framework that lets you define AWS infrastructure using TypeScript configuration files. Unlike AWS CDK or Terraform, @stacksjs/ts-cloud:
 
 - **Zero AWS Dependencies** - No AWS SDK, no AWS CLI. Direct AWS API calls only.
 - **Type-Safe Configuration** - Full TypeScript types for all AWS resources
@@ -55,6 +55,23 @@ Complete CloudFormation template builders for:
 - **Monitoring** - CloudWatch dashboards, alarms, and log groups
 - **Security** - ACM certificates, WAF rules, security groups
 
+### 🔒 Pre-Deployment Security Scanning
+
+Built-in secret detection to prevent accidental credential exposure:
+
+- **35+ Secret Patterns** - AWS keys, API tokens, private keys, database credentials
+- **Automatic Scanning** - Runs before every deployment
+- **Configurable Severity** - Block on critical, high, medium, or low findings
+- **CI/CD Ready** - Integrate security checks into your pipeline
+
+```bash
+# Scan for secrets before deploying
+cloud deploy:security-scan --source ./dist
+
+# Deploy with automatic security scanning
+cloud deploy  # Scans automatically before deployment
+```
+
 ### ☁️ Direct AWS Integration
 
 No SDK, no CLI - pure AWS Signature V4 API calls:
@@ -69,7 +86,7 @@ No SDK, no CLI - pure AWS Signature V4 API calls:
 ### Installation
 
 ```bash
-bun add ts-cloud
+bun add @stacksjs/ts-cloud
 ```
 
 ### Your First Deployment
@@ -77,7 +94,7 @@ bun add ts-cloud
 Create a `cloud.config.ts`:
 
 ```typescript
-import { createStaticSitePreset } from 'ts-cloud/presets'
+import { createStaticSitePreset } from '@stacksjs/ts-cloud/presets'
 
 export default createStaticSitePreset({
   name: 'My Website',
@@ -104,7 +121,7 @@ That's it! You now have:
 #### Full-Stack Application
 
 ```typescript
-import { createFullStackAppPreset } from 'ts-cloud/presets'
+import { createFullStackAppPreset } from '@stacksjs/ts-cloud/presets'
 
 export default createFullStackAppPreset({
   name: 'My App',
@@ -125,7 +142,7 @@ Includes:
 #### Serverless API
 
 ```typescript
-import { createApiBackendPreset } from 'ts-cloud/presets'
+import { createApiBackendPreset } from '@stacksjs/ts-cloud/presets'
 
 export default createApiBackendPreset({
   name: 'My API',
@@ -148,7 +165,7 @@ Includes:
 You can extend any preset with custom configuration:
 
 ```typescript
-import { createNodeJsServerPreset, extendPreset } from 'ts-cloud/presets'
+import { createNodeJsServerPreset, extendPreset } from '@stacksjs/ts-cloud/presets'
 
 export default extendPreset(
   createNodeJsServerPreset({
@@ -175,7 +192,7 @@ export default extendPreset(
 Combine multiple presets:
 
 ```typescript
-import { composePresets, createStaticSitePreset, createApiBackendPreset } from 'ts-cloud/presets'
+import { composePresets, createStaticSitePreset, createApiBackendPreset } from '@stacksjs/ts-cloud/presets'
 
 export default composePresets(
   createStaticSitePreset({ name: 'Frontend', slug: 'frontend', domain: 'example.com' }),
@@ -198,7 +215,7 @@ export default composePresets(
 Generate templates programmatically:
 
 ```typescript
-import { CloudFormationBuilder } from 'ts-cloud/cloudformation'
+import { CloudFormationBuilder } from '@stacksjs/ts-cloud/cloudformation'
 
 const builder = new CloudFormationBuilder(config)
 const template = builder.build()
@@ -211,7 +228,7 @@ console.log(JSON.stringify(template, null, 2))
 Use the AWS clients directly:
 
 ```typescript
-import { CloudFormationClient, S3Client, CloudFrontClient } from 'ts-cloud/aws'
+import { CloudFormationClient, S3Client, CloudFrontClient } from '@stacksjs/ts-cloud/aws'
 
 // CloudFormation
 const cfn = new CloudFormationClient('us-east-1')
@@ -236,6 +253,74 @@ await cloudfront.createInvalidation({
 })
 ```
 
+## DNS Providers
+
+@stacksjs/ts-cloud supports multiple DNS providers for domain management and SSL certificate validation:
+
+### Cloudflare
+
+1. Log in to your [Cloudflare Dashboard](https://dash.cloudflare.com/)
+2. Go to **My Profile** → **API Tokens** (or visit https://dash.cloudflare.com/profile/api-tokens)
+3. Click **Create Token**
+4. Use the **Edit zone DNS** template, or create a custom token with:
+   - **Permissions**: Zone → DNS → Edit
+   - **Zone Resources**: Include → All zones (or specific zones)
+5. Copy the generated token
+
+```bash
+export CLOUDFLARE_API_TOKEN="your-api-token-here"
+```
+
+### Porkbun
+
+1. Log in to your [Porkbun Dashboard](https://porkbun.com/account/api)
+2. Enable API access for your domain(s)
+3. Generate an API key pair
+
+```bash
+export PORKBUN_API_KEY="your-api-key"
+export PORKBUN_SECRET_KEY="your-secret-key"
+```
+
+### GoDaddy
+
+1. Log in to [GoDaddy Developer Portal](https://developer.godaddy.com/)
+2. Create a new API key
+3. Note both the key and secret
+
+```bash
+export GODADDY_API_KEY="your-api-key"
+export GODADDY_API_SECRET="your-api-secret"
+export GODADDY_ENVIRONMENT="production"  # or "ote" for testing
+```
+
+### Route53
+
+Uses AWS credentials from environment or ~/.aws/credentials:
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_REGION="us-east-1"
+export AWS_HOSTED_ZONE_ID="Z1234567890"  # Optional
+```
+
+### CLI Usage
+
+```bash
+# List domains
+cloud domain:list --provider cloudflare
+
+# List DNS records
+cloud dns:records example.com --provider cloudflare
+
+# Add a DNS record
+cloud dns:add example.com A 192.168.1.1 --name api --provider cloudflare
+
+# Generate SSL certificate with DNS validation
+cloud domain:ssl example.com --provider cloudflare
+```
+
 ## Development
 
 ```bash
@@ -264,7 +349,7 @@ bun run typecheck
 
 ### No Dependencies
 
-ts-cloud uses **zero external dependencies** for AWS operations:
+@stacksjs/ts-cloud uses **zero external dependencies** for AWS operations:
 
 - **AWS Signature V4** - Manual request signing for authentication
 - **Direct HTTPS** - Native `fetch()` for API calls
@@ -312,8 +397,8 @@ The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
 Made with 💙
 
 <!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/ts-cloud?style=flat-square
-[npm-version-href]: https://npmjs.com/package/ts-cloud
+[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/ts-cloud?style=flat-square
+[npm-version-href]: https://npmjs.com/package/@stacksjs/ts-cloud
 [github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/ts-cloud/ci.yml?style=flat-square&branch=main
 [github-actions-href]: https://github.com/stacksjs/ts-cloud/actions?query=workflow%3Aci
 

package/dist/aws/cloudformation.d.ts

@@ -0,0 +1,69 @@
+import type { AWSCredentials } from './credentials';
+export declare interface CloudFormationStack {
+  StackName: string
+  StackId?: string
+  StackStatus?: string
+  CreationTime?: string
+  LastUpdatedTime?: string
+  StackStatusReason?: string
+  Description?: string
+  Parameters?: Array<{ ParameterKey: string, ParameterValue: string }>
+  Outputs?: Array<{ OutputKey: string, OutputValue: string, Description?: string }>
+  Tags?: Array<{ Key: string, Value: string }>
+}
+export declare interface CreateStackOptions {
+  stackName: string
+  templateBody?: string
+  templateURL?: string
+  parameters?: Record<string, string>
+  capabilities?: string[]
+  tags?: Record<string, string>
+  timeoutInMinutes?: number
+  onFailure?: 'DO_NOTHING' | 'ROLLBACK' | 'DELETE'
+}
+export declare interface UpdateStackOptions {
+  stackName: string
+  templateBody?: string
+  templateURL?: string
+  parameters?: Record<string, string>
+  capabilities?: string[]
+  tags?: Record<string, string>
+}
+export declare interface StackEvent {
+  EventId: string
+  StackName: string
+  LogicalResourceId: string
+  PhysicalResourceId?: string
+  ResourceType: string
+  Timestamp: string
+  ResourceStatus: string
+  ResourceStatusReason?: string
+}
+/**
+ * CloudFormation API Client
+ */
+export declare class CloudFormationClient {
+  private credentials: AWSCredentials | null;
+  private region: string;
+  private readonly profile?: string;
+  constructor(region?: string, profile?: string);
+  init(): Promise<void>;
+  private ensureCredentials(): Promise<AWSCredentials>;
+  private request(action: string, params: Record<string, any>): Promise<any>;
+  createStack(options: CreateStackOptions): Promise<string>;
+  updateStack(options: UpdateStackOptions): Promise<string>;
+  deleteStack(stackName: string): Promise<void>;
+  describeStack(stackName: string): Promise<CloudFormationStack>;
+  listStacks(statusFilter?: string[]): Promise<CloudFormationStack[]>;
+  describeStackEvents(stackName: string): Promise<StackEvent[]>;
+  waitForStack(stackName: string, desiredStates: string[], onProgress?: (event: StackEvent) => void): Promise<CloudFormationStack>;
+  createChangeSet(options: {
+    stackName: string
+    changeSetName: string
+    templateBody?: string
+    templateURL?: string
+    parameters?: Record<string, string>
+    capabilities?: string[]
+  }): Promise<string>;
+  executeChangeSet(changeSetName: string, stackName: string): Promise<void>;
+}

package/dist/aws/cloudfront.d.ts

@@ -0,0 +1,21 @@
+import type { AWSCredentials } from './credentials';
+export declare interface InvalidationOptions {
+  distributionId: string
+  paths: string[]
+  callerReference?: string
+}
+/**
+ * CloudFront API Client
+ */
+export declare class CloudFrontClient {
+  private credentials: AWSCredentials | null;
+  private readonly profile?: string;
+  constructor(profile?: string);
+  init(): Promise<void>;
+  private ensureCredentials(): Promise<AWSCredentials>;
+  createInvalidation(options: InvalidationOptions): Promise<string>;
+  getInvalidation(distributionId: string, invalidationId: string): Promise<any>;
+  listInvalidations(distributionId: string): Promise<any[]>;
+  waitForInvalidation(distributionId: string, invalidationId: string, maxAttempts?: number, pollInterval?: number): Promise<void>;
+  invalidateAll(distributionId: string): Promise<string>;
+}

package/dist/aws/credentials.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Get credentials from environment variables
+ * Checks: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+ */
+export declare function fromEnvironment(): AWSCredentials | null;
+/**
+ * Get credentials from shared credentials file (~/.aws/credentials)
+ */
+export declare function fromSharedCredentials(options?: CredentialProviderOptions): AWSCredentials | null;
+/**
+ * Get credentials from EC2 instance metadata service (IMDSv2)
+ */
+export declare function fromEC2Metadata(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials from ECS task metadata
+ */
+export declare function fromECSMetadata(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials from web identity token (for Kubernetes/IRSA)
+ */
+export declare function fromWebIdentity(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials using the default credential chain
+ * Tries providers in order: Environment -> Shared Credentials -> Web Identity -> ECS -> EC2
+ */
+export declare function getCredentials(options?: CredentialProviderOptions): Promise<AWSCredentials>;
+/**
+ * Create a credential provider that caches and auto-refreshes credentials
+ */
+export declare function createCredentialProvider(options?: CredentialProviderOptions): () => Promise<AWSCredentials>;
+/**
+ * Resolve AWS credentials from various sources
+ * @deprecated Use getCredentials() instead
+ */
+export declare function resolveCredentials(profile?: string): Promise<AWSCredentials>;
+/**
+ * Resolve AWS region from environment or config
+ */
+export declare function resolveRegion(profile?: string): string;
+/**
+ * Get AWS account ID using STS GetCallerIdentity
+ */
+export declare function getAccountId(credentials?: AWSCredentials): Promise<string>;
+export declare interface AWSCredentials {
+  accessKeyId: string
+  secretAccessKey: string
+  sessionToken?: string
+  expiration?: Date
+  region?: string
+}
+export declare interface CredentialProviderOptions {
+  profile?: string
+  credentialsFile?: string
+  configFile?: string
+  timeout?: number
+}
+// ============================================================================
+// Backwards Compatibility Exports
+// ============================================================================
+export declare interface AWSProfile {
+  name: string
+  accessKeyId: string
+  secretAccessKey: string
+  sessionToken?: string
+  region?: string
+}

package/{src/aws/index.ts → dist/aws/index.d.ts}

@@ -1,4 +1,35 @@
-// AWS Signature V4
+export type {
+  SignatureOptions,
+  SignedRequest,
+  PresignedUrlOptions,
+  RetryOptions,
+} from './signature';
+export type {
+  AWSCredentials,
+  AWSProfile,
+  CredentialProviderOptions,
+} from './credentials';
+export type {
+  CloudFormationStack,
+  CreateStackOptions,
+  UpdateStackOptions,
+  StackEvent,
+} from './cloudformation';
+export type {
+  S3ClientOptions,
+  GetObjectOptions,
+  PutObjectOptions,
+  ListObjectsOptions,
+  ListObjectsResult,
+  S3Object,
+  HeadObjectResult,
+  CopyObjectOptions,
+  MultipartUploadOptions,
+  MultipartProgress,
+} from './s3';
+export type {
+  InvalidationOptions,
+} from './cloudfront';
 export {
   signRequest,
   signRequestAsync,
@@ -14,16 +45,7 @@ export {
   parseJSONResponse,
   isNodeCryptoAvailable,
   isWebCryptoAvailable,
-} from './signature'
-
-export type {
-  SignatureOptions,
-  SignedRequest,
-  PresignedUrlOptions,
-  RetryOptions,
-} from './signature'
-
-// AWS Credentials
+} from './signature';
 export {
   // New credential providers
   fromEnvironment,
@@ -37,51 +59,15 @@ export {
   resolveCredentials,
   resolveRegion,
   getAccountId,
-} from './credentials'
-
-export type {
-  AWSCredentials,
-  AWSProfile,
-  CredentialProviderOptions,
-} from './credentials'
-
-// CloudFormation Client
+} from './credentials';
 export {
   CloudFormationClient,
-} from './cloudformation'
-
-export type {
-  CloudFormationStack,
-  CreateStackOptions,
-  UpdateStackOptions,
-  StackEvent,
-} from './cloudformation'
-
-// S3 Client (High-Level API)
+} from './cloudformation';
 export {
   S3Client,
   S3Error,
   createS3Client,
-} from './s3'
-
-export type {
-  S3ClientOptions,
-  GetObjectOptions,
-  PutObjectOptions,
-  ListObjectsOptions,
-  ListObjectsResult,
-  S3Object,
-  HeadObjectResult,
-  CopyObjectOptions,
-  MultipartUploadOptions,
-  MultipartProgress,
-} from './s3'
-
-// CloudFront Client
+} from './s3';
 export {
   CloudFrontClient,
-} from './cloudfront'
-
-export type {
-  InvalidationOptions,
-} from './cloudfront'
+} from './cloudfront';

package/dist/aws/s3.d.ts

@@ -0,0 +1,130 @@
+import { getCredentials } from './credentials';
+/**
+ * Convenience function to create an S3 client
+ */
+export declare function createS3Client(options?: S3ClientOptions): S3Client;
+export declare interface S3ClientOptions {
+  region?: string
+  endpoint?: string
+  forcePathStyle?: boolean
+  credentials?: AWSCredentials
+  credentialOptions?: CredentialProviderOptions
+  retryOptions?: RetryOptions
+}
+export declare interface GetObjectOptions {
+  range?: string
+  ifModifiedSince?: Date
+  ifMatch?: string
+  ifNoneMatch?: string
+  responseContentType?: string
+  responseContentDisposition?: string
+}
+export declare interface PutObjectOptions {
+  contentType?: string
+  contentEncoding?: string
+  cacheControl?: string
+  contentDisposition?: string
+  metadata?: Record<string, string>
+  storageClass?: string
+  serverSideEncryption?: string
+  acl?: string
+  tagging?: string
+}
+export declare interface ListObjectsOptions {
+  prefix?: string
+  delimiter?: string
+  maxKeys?: number
+  continuationToken?: string
+  startAfter?: string
+}
+export declare interface ListObjectsResult {
+  contents: S3Object[]
+  commonPrefixes: string[]
+  isTruncated: boolean
+  continuationToken?: string
+  nextContinuationToken?: string
+  keyCount: number
+  maxKeys: number
+  prefix?: string
+  delimiter?: string
+}
+export declare interface S3Object {
+  key: string
+  lastModified: Date
+  etag: string
+  size: number
+  storageClass: string
+}
+export declare interface HeadObjectResult {
+  contentLength: number
+  contentType: string
+  etag: string
+  lastModified: Date
+  metadata: Record<string, string>
+  storageClass?: string
+  serverSideEncryption?: string
+}
+export declare interface CopyObjectOptions {
+  metadataDirective?: 'COPY' | 'REPLACE'
+  metadata?: Record<string, string>
+  contentType?: string
+  storageClass?: string
+  acl?: string
+}
+export declare interface MultipartUploadOptions extends PutObjectOptions {
+  partSize?: number
+  concurrency?: number
+  onProgress?: (progress: MultipartProgress) => void
+}
+export declare interface MultipartProgress {
+  loaded: number
+  total: number
+  part: number
+  totalParts: number
+}
+export declare interface PresignedUrlOptions {
+  expiresIn?: number
+  method?: string
+}
+/**
+ * S3 Client for high-level S3 operations
+ */
+export declare class S3Client {
+  private region: string;
+  private endpoint: string;
+  private forcePathStyle: boolean;
+  private credentials?: AWSCredentials;
+  private credentialOptions?: CredentialProviderOptions;
+  private retryOptions: RetryOptions;
+  constructor(options?: S3ClientOptions);
+  private getCredentials(): Promise<AWSCredentials>;
+  private buildUrl(bucket: string, key?: string): string;
+  get(bucket: string, key: string, options?: GetObjectOptions): Promise<Response>;
+  getText(bucket: string, key: string, options?: GetObjectOptions): Promise<string>;
+  getJSON<T = unknown>(bucket: string, key: string, options?: GetObjectOptions): Promise<T>;
+  getBuffer(bucket: string, key: string, options?: GetObjectOptions): Promise<ArrayBuffer>;
+  put(bucket: string, key: string, body: string | ArrayBuffer | Uint8Array | Blob | ReadableStream, options?: PutObjectOptions): Promise<{ etag: string }>;
+  private putSimple(bucket: string, key: string, body: string | ArrayBuffer | Uint8Array | Blob, size: number, options: PutObjectOptions): Promise<{ etag: string }>;
+  delete(bucket: string, key: string): Promise<void>;
+  deleteMany(bucket: string, keys: string[]): Promise<{ deleted: string[], errors: Array<{ key: string, error: string }> }>;
+  list(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
+  listAll(bucket: string, options?: Omit<ListObjectsOptions, 'continuationToken'>): AsyncGenerator<S3Object>;
+  head(bucket: string, key: string): Promise<HeadObjectResult | null>;
+  exists(bucket: string, key: string): Promise<boolean>;
+  copy(sourceBucket: string, sourceKey: string, destBucket: string, destKey: string, options?: CopyObjectOptions): Promise<{ etag: string }>;
+  getPresignedUrl(bucket: string, key: string, options?: PresignedUrlOptions): Promise<string>;
+  uploadMultipart(bucket: string, key: string, body: ReadableStream | Blob | ArrayBuffer | Uint8Array, options?: MultipartUploadOptions): Promise<{ etag: string }>;
+  private initiateMultipartUpload(bucket: string, key: string, options: PutObjectOptions): Promise<string>;
+  private uploadParts(bucket: string, key: string, uploadId: string, stream: ReadableStream<Uint8Array>, partSize: number, credentials: AWSCredentials, totalSize: number | undefined, concurrency: number, onProgress?: (progress: MultipartProgress) => void): Promise<Array<{ partNumber: number, etag: string }>>;
+  private completeMultipartUpload(bucket: string, key: string, uploadId: string, parts: Array<{ partNumber: number, etag: string }>): Promise<{ etag: string }>;
+  abortMultipartUpload(bucket: string, key: string, uploadId: string): Promise<void>;
+}
+/**
+ * S3 Error class
+ */
+export declare class S3Error extends Error {
+  public statusCode: number;
+  public bucket: string;
+  public key?: string;
+  constructor(message: string, statusCode: number, bucket: string, key?: string);
+}