Maverick Cloud Machine CLI (macm)

Deploy and manage domain-agnostic serverless platforms on AWS with a single command.

Maverick Cloud Machine (macm) is a CLI tool that deploys a complete serverless infrastructure using AWS CDK, including authentication, authorization, orchestration, and API management.

🚀 Features

• 🔐 Identity & Auth: AWS Cognito with OAuth2/OIDC (Google, Azure AD)
• 🛡️ Authorization: AWS Verified Permissions with Cedar policies
• 🌐 API Gateway: HTTP API with JWT authentication
• ⚙️ Orchestration: AWS Step Functions (Express + Standard)
• 💾 Storage: S3 + DynamoDB resource directory
• 📡 Events: EventBridge for event-driven architecture
• 🔧 Compute: Lambda functions with Node.js 20.x
• 📊 Monitoring: CloudWatch Logs integration

📦 Installation

npm install -g macm

Verify installation:

macm --version

🏁 Quick Start

1. Initialize a New Project

mkdir my-platform
cd my-platform
macm init

This creates:

• macm.config.json - Configuration file
• README.md - Project documentation

2. Configure

Edit macm.config.json:

{
  "stackName": "MyPlatformStack",
  "region": "us-east-1",
  "cognito": {
    "domainPrefix": "my-unique-prefix",  // ⚠️ REQUIRED & MUST BE GLOBALLY UNIQUE
    "oauthCallbackUrls": ["https://myapp.com/auth/callback"],
    "oauthLogoutUrls": ["https://myapp.com"]
  },
  "cors": {
    "allowOrigins": ["https://myapp.com", "http://localhost:4200"]
  }
}

3. Deploy

macm deploy

4. Check Status

macm status

5. View Logs

# View recent logs
macm logs maverick-auth

# Follow logs in real-time
macm logs maverick-auth --follow

6. Destroy (when done)

macm destroy

📚 Commands

macm init

Initialize a new Maverick Cloud Machine project.

macm init [options]

Options:
  -d, --dir <directory>   Target directory (default: ".")
  -n, --name <name>       Project name

macm deploy

Deploy the Maverick Cloud Machine to AWS.

macm deploy [options]

Options:
  -p, --profile <profile>  AWS profile to use
  -r, --region <region>    AWS region
  -c, --config <path>      Path to config file (default: "./macm.config.json")
  --no-confirm             Skip confirmation prompts

macm status

Show status of your deployed Maverick Cloud Machine.

macm status [options]

Options:
  -p, --profile <profile>  AWS profile to use
  -r, --region <region>    AWS region
  -c, --config <path>      Path to config file

macm logs

View logs from Lambda functions or Step Functions.

macm logs <resource> [options]

Arguments:
  resource                 Resource name (function name or state machine name)

Options:
  -f, --follow            Follow log output
  -t, --tail <lines>      Number of lines to show (default: "50")
  -p, --profile <profile> AWS profile to use
  -r, --region <region>   AWS region

macm destroy

Destroy the Maverick Cloud Machine stack.

macm destroy [options]

Options:
  -p, --profile <profile>  AWS profile to use
  -r, --region <region>    AWS region
  -c, --config <path>      Path to config file
  --force                  Skip confirmation prompt

macm config

Manage configuration.

macm config --show              # Show current configuration
macm config --set key=value     # Set configuration value

⚙️ Configuration

Complete macm.config.json Example

{
  "stackName": "MaverickCloudMachine",
  "region": "us-east-1",
  "profile": "default",
  "resourceNaming": {
    "userPool": "maverick-users",
    "api": "maverick-api",
    "functions": {
      "auth": "maverick-auth",
      "directory": "maverick-directory",
      "policies": "maverick-policies",
      "rights": "maverick-rights",
      "workflow": "maverick-workflow",
      "graph": "maverick-graph",
      "postConfirmation": "maverick-post-confirmation"
    },
    "stateMachines": {
      "express": "maverick-access-control",
      "standard": "maverick-workflow-orchestrator"
    },
    "tables": {
      "resources": "maverick-resources"
    }
  },
  "cors": {
    "allowOrigins": ["http://localhost:4200", "http://localhost:3000"],
    "allowMethods": ["OPTIONS", "POST", "GET", "PUT", "DELETE"],
    "allowHeaders": ["Authorization", "Content-Type", "X-Requested-With"],
    "allowCredentials": true,
    "maxAge": 3600
  },
  "cognito": {
    "domainPrefix": "my-unique-prefix",
    "oauthCallbackUrls": ["http://localhost:4200/auth/callback"],
    "oauthLogoutUrls": ["http://localhost:4200"],
    "postLoginRedirect": "http://localhost:4200/dashboard",
    "postLogoutRedirect": "http://localhost:4200"
  },
  "customDomain": {
    "api": {
      "domainName": "api.myapp.com",
      "certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/...",
      "endpointType": "REGIONAL"
    }
  }
}

🏗️ Infrastructure Components

Lambda Functions

• auth: OAuth2 code exchange + session cookie management
• directory: Resource directory with AVP authorization filtering
• policies: CRUD operations for Cedar policies
• rights: Authorization checks via AWS Verified Permissions
• workflow: Workflow orchestration business logic
• graph: Entity/relationship management
• post-confirmation: User onboarding after Cognito signup

Step Functions

• Express State Machine (synchronous, <30s): Access control and directory queries
• Standard State Machine (asynchronous): Case workflow orchestration with Map state

API Endpoints

| Method | Path | Description | |--------|--------------------------|----------------------------------| | POST | /api/access | Check user permissions (sync) | | POST | /api/workflow/execute | Start workflow (async) | | POST | /directory | List resources with AVP filter | | POST | /policies | Manage Cedar policies | | GET | /auth/login | Initiate OAuth2 flow | | GET | /auth/login-callback | Handle OAuth2 callback | | GET | /auth/logout | Sign out | | GET | /auth/me | Get current user session | | GET | /auth/providers | List available identity providers|

🔒 Authorization with Cedar Policies

Maverick Cloud Machine uses AWS Verified Permissions with Cedar policy language.

Example Cedar policy:

permit(
  principal,
  action in [
    QTSystem::Action::"viewCase",
    QTSystem::Action::"editCase"
  ],
  resource
) when {
  resource has owner &&
  resource.owner == principal
};

Manage policies via API:

POST /policies
{
  "operation": "createPolicy",
  "cedarPolicy": "permit(principal, action, resource) when { ... }",
  "description": "My custom policy"
}

🛠️ Prerequisites

• Node.js: >= 18.0.0
• AWS CLI: Configured with credentials
• AWS CDK: >= 2.0.0 (peer dependency)
• AWS Account: With appropriate IAM permissions

Required AWS Permissions

Your IAM user/role needs permissions to create:

• CloudFormation stacks
• Lambda functions
• API Gateway
• Cognito User Pools
• Step Functions
• DynamoDB tables
• S3 buckets
• IAM roles
• EventBridge rules
• Verified Permissions policy stores

🔧 Development

Run Locally

git clone https://github.com/qt-enterprises/qt-system.git
cd qt-system/macm
npm install
npm link
macm --version

Project Structure

macm/
├── bin/
│   └── macm.js              # CLI entry point
├── lib/
│   ├── commands/
│   │   ├── deploy.js         # Deploy command
│   │   ├── destroy.js        # Destroy command
│   │   ├── init.js           # Init command
│   │   ├── status.js         # Status command
│   │   └── logs.js           # Logs command
│   ├── utils/
│   │   └── paths.js          # Path utilities
│   └── config.js             # Configuration management
├── package.json
└── README.md

📖 Examples

Deploy to Production

macm deploy --profile prod --region us-east-1 --no-confirm

Check Status in Different Region

macm status --profile dev --region eu-west-1

Stream Logs from Workflow Function

macm logs maverick-workflow --follow

Deploy with Custom Config

macm deploy --config ./prod.config.json

❓ FAQ

How do I get a unique Cognito domain prefix?

The cognito.domainPrefix must be globally unique across all AWS accounts. Try variations like:

• mycompany-platform-dev
• myapp-auth-prod
• {company}-{project}-{env}

Can I use my own custom domain?

Yes! Add to macm.config.json:

{
  "customDomain": {
    "api": {
      "domainName": "api.myapp.com",
      "certificateArn": "arn:aws:acm:...",
      "endpointType": "REGIONAL"
    }
  }
}

How do I add SSO with Google/Azure?

Set environment variables before deploying:

export GOOGLE_CLIENT_ID="..."
export GOOGLE_CLIENT_SECRET="..."
export AZURE_ISSUER_URL="https://login.microsoftonline.com/{tenant}/v2.0"
export AZURE_CLIENT_ID="..."
export AZURE_CLIENT_SECRET="..."

macm deploy

Where are the logs stored?

CloudWatch Logs under:

• /aws/lambda/{function-name}
• /aws/vendedlogs/states/{state-machine-name}

🤝 Contributing

Contributions welcome! Please open an issue or PR at: https://github.com/qt-enterprises/qt-system

📄 License

MIT © Clinton Jones

Built with ❤️ by QT Enterprises