{
  "markdown": "# Transmit Security IDO Journey Builder for Gemini CLI\n\nA [Gemini CLI](https://geminicli.com/) extension that enables AI-assisted generation of [Transmit Security Identity Orchestration (IDO) Journey](https://developer.transmitsecurity.com/guides/orchestration/getting-started/journey101/) JSON configurations. Leverages the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) to provide comprehensive context, validation tools, and automated fixes for creating production-ready authentication and identity workflows.\n\n## Overview\n\nThis extension transforms Gemini CLI into an expert IDO Journey architect by providing:\n\n1. **Comprehensive Context**: Journey generation instructions, node definitions, patterns, and best practices loaded into every session\n2. **Validation Tools**: Eight specialized MCP tools for validating journey structure, metadata, expressions, variables, and required fields\n3. **Working Examples**: On-demand access to complete working journey examples (loops, authentication, password reset, registration)\n4. **Automated Fixes**: Auto-correction of common journey issues including UUID format, timestamps, field initialization, and more\n5. **JSON Output**: Generates complete, importable journey JSON files ready for Transmit Security's Mosaic platform\n\n### What are IDO Journeys?\n\nIdentity Orchestration (IDO) Journeys are workflow definitions for authentication and identity management flows in Transmit Security's Mosaic platform. They define:\n\n- **Authentication flows**: Password login, passkey authentication, multi-factor authentication (MFA)\n- **Registration flows**: User signup, credential enrollment, email/phone verification\n- **Account management**: Password reset, credential management, profile updates\n- **Risk-based flows**: Conditional authentication, step-up authentication, fraud detection integration\n\nThe [Mosaic platform](https://developer.transmitsecurity.com/) is Transmit Security's unified identity management solution that combines identity, fraud prevention, and verification services with drag-and-drop journey design tools and AI-driven security measures.\n\n## Features\n\n- **AI-Guided Generation**: Gemini uses extensive context to generate valid, importable journey JSON matching platform requirements\n- **Working Examples On-Demand**: Access complete working journey examples only when needed, reducing context overhead by 50%\n- **Multi-Layer Validation**: Six specialized validators checking structure, metadata, expressions, variables, and required fields\n- **Automated Corrections**: Common issues (UUID format, timestamps, field initialization) are automatically fixed\n- **Platform Integration**: Generated journeys can be imported into Transmit Security's Mosaic platform\n\n## Prerequisites\n\n1. **Python 3**: Required for validation scripts\n   - Verify installation: `python3 --version`\n   - Download from [python.org](https://www.python.org/downloads/) if needed\n\n2. **Node.js**: Required for the MCP server\n   - Verify installation: `node --version`\n   - Download from [nodejs.org](https://nodejs.org/) if needed\n\n3. **Gemini CLI**: Install the Gemini CLI tool\n   - Follow the installation guide at [https://geminicli.com/](https://geminicli.com/)\n\n## Installation\n\nInstall the extension using the Gemini CLI:\n\n```bash\ngemini extensions install https://github.com/TransmitSecurity/transmit-security-journey-builder\n```\n\nAfter installation, install the required npm packages for the MCP server:\n\n```bash\ncd ~/.gemini/extensions/transmit-security-journey-builder/mcp\nnpm install\n```\n\nIf Gemini CLI is already running, restart it after installation.\n\n## Configuration\n\nThe extension is configured via `gemini-extension.json`:\n\n```json\n{\n  \"name\": \"transmit-security-journey-builder\",\n  \"version\": \"1.0.0\",\n  \"contextFileName\": \"instructions.md\",\n  \"mcpServers\": {\n    \"journey-tools\": {\n      \"command\": \"node\",\n      \"args\": [\"${extensionPath}${/}mcp${/}server.js\"],\n      \"env\": {\n        \"WORKSPACE_FOLDER\": \"${workspaceFolder}\",\n        \"EXTENSION_PATH\": \"${extensionPath}\"\n      }\n    }\n  },\n  \"excludeTools\": [\n    \"run_shell_command(gemini)\"\n  ]\n}\n```\n\n**Key Configuration Elements:**\n\n- `contextFileName`: Points to `instructions.md` - the comprehensive instruction set loaded into every Gemini session\n- `mcpServers`: Defines the Node.js MCP server that exposes validation and fixing tools\n- `excludeTools`: Security restriction to prevent certain command executions\n\n## Usage\n\nOnce installed, start the Gemini CLI:\n\n```bash\ngemini\n```\n\nThe extension automatically loads `instructions.md` context, making Gemini an expert in IDO Journey generation.\n\n### Example: Generate a Password Login Journey\n\n```\nYou: Create a simple password authentication journey with email login\n\nGemini: [Uses instructions.md context to understand:]\n        - Required journey structure with exports array\n        - Proper UUID format (hexadecimal only)\n        - login_form node with password escape link\n        - transmit_platform_password_authentication node\n        - auth_pass terminal node\n        - All required metadata and timestamps\n        \n        [Generates complete journey JSON]\n        [Saves to file]\n        [Automatically runs journey_fixes tool]\n        [Runs validation tools to verify correctness]\n        [Returns validated, importable <journey>.json]\n```\n\n### Example: Generate MFA Journey\n\n```\nYou: Create an MFA journey with password and TOTP authentication\n\nGemini: [Generates journey with:]\n        - login_form node with password escape link\n        - Password authentication node\n        - Conditional check for TOTP enrollment\n        - TOTP authentication node\n        - Registration flow for new TOTP users\n        - Proper variable management throughout\n        \n        [Validates and fixes automatically]\n```\n\n### Importing to Mosaic Platform\n\nOnce your journey JSON is generated and validated:\n\n1. Open Transmit Security's Mosaic platform\n2. Navigate to Tools > Journey Tools > Import/Export\n\n![Import/Export](images/import_export.png)\n\n3. Select the Import tab, and then Upload to choose the file\n\n![Import Tab](images/import.png)\n\n4. Once the file is uploaded press the Import button\n\n![Import Button](images/import_button.png)\n\n5. Navigate to Solutions > B2C Identity  > Journeys and select the just imported Journey to review and deploy it\n\n![Journeys](images/journeys.png)\n\n## Available Tools\n\nThe extension provides eight MCP tools accessible during journey generation:\n\n### 1. `journey_fixes`\nPerforms common auto-fixes after generation. **Always run first after generating a journey.**\n\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 2. `validate_journey_metadata`\nChecks journey-level metadata: type, version_id, state, timestamps.\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 3. `validate_journey_structure`\nValidates structural integrity and reachability.\n\n**Validates:**\n- UUID formats (node IDs, workflow ID)\n- All nodes reachable from head node\n- Proper loop and block nesting\n- Link structure completeness\n- No orphaned nodes\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 4. `validate_journey_required_fields`\nChecks that all required fields are present for each node type.\n\n**Validates:**\n- Platform node required fields (user_identifier, password, etc.)\n- Action node required fields (text, button_text, etc.)\n- Form schema structure\n- Condition node structure\n- JSON data format\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 5. `validate_journey_expressions`\nValidates expression syntax and formatting.\n\n**Validates:**\n- Template literal syntax (backticks, ${} interpolation)\n- Expression escaping (quotes inside backticks)\n- AuthScript-style rules compliance\n- Loop and condition expressions\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 6. `validate_journey_variables`\nChecks variable definition and usage.\n\n**Validates:**\n- Variables defined before use\n- Proper variable scoping in loops\n- Variable initialization structure\n- Field access matches initialization\n\n**Input:** \n- `journey_json_path`: Path to the journey JSON file\n\n### 7. `stringify_json_field`\nStringifies JSON schema and inserts it into fields requiring stringified JSON with literal `\\n` and `\\\"`.\n\n**Use Cases:**\n- `action/form_schema/value` in `get_information` nodes\n- `links/N/data_json_schema/value` in `login_form` escape links\n\n**Input:**\n- `json_path`: Path to the JSON file to stringify\n- `journey_json_path`: Path to the journey JSON file\n- `field_name`: Field path starting with NODE_ID (e.g., `node-abc-123/action/form_schema/value`)\n\n### 8. `display_journey_examples`\nDisplays complete working journey examples with explanations and JSON. Provides on-demand access to reference patterns without loading all examples into context.\n\n**Available Patterns:**\n- `loop`: Password authentication retry loop (up to 5 attempts) with phone deregistration\n- `email_otp_authentication`: Email OTP authentication with username lookup and email verification\n- `password_reset`: Email OTP password reset with optional passkey registration\n- `registration`: Complete registration with risk assessment, IDV, device and passkey setup\n- `all`: Display all available examples\n\n**Input:**\n- `pattern`: The type of example to display (one of the patterns above)\n- `include_explanation`: (Optional) Whether to include explanations (default: true). Set to false for JSON only.\n\n**Example Usage:**\n```javascript\ndisplay_journey_examples({ pattern: \"loop\" })\ndisplay_journey_examples({ pattern: \"registration\", include_explanation: false })\n```\n\n## Journey Generation Context\n\nThe extension provides comprehensive context through `instructions.md` \n\n### Content Includes\n\n- **Node Type Catalog**: Definitions for 70+ node types with required fields, examples, and patterns\n- **Expression Syntax**: Template literals, @std functions, variable access patterns\n- **Variable Management**: Initialization patterns, scoping rules, field access\n- **Link Types**: Proper usage of `child`, `escape`, `error`, and `conditional` links\n- **Complete Journey Structure**: Required exports array format, metadata fields, constraints\n- **Common Patterns**: Authentication flows, registration flows, conditional logic, loops, forms\n- **Working Examples**: Complete journey examples accessible on-demand via `display_journey_examples` tool\n- **Error Prevention**: Common mistakes and how to avoid them\n\n## Extension Structure\n\n```\ngemini_cli_extension/\n├── README.md                         # This file\n├── images/                           # Images used for this file\n├── LICENSE                           # Apache 2.0 License\n├── gemini-extension.json             # Extension configuration\n├── instructions.md                   # Comprehensive instructions (50% smaller!)\n└── mcp/                              # MCP server and validators\n    ├── package.json                  # Node.js dependencies\n    ├── server.js                     # Node.js MCP server\n    ├── security_validator.py         # Security validation module\n    ├── journey_fixes.py              # Auto-fix common issues\n    ├── journey_validator_base.py     # Base validator class\n    ├── validate_journey_metadata.py  # Metadata validator\n    ├── validate_journey_structure.py # Structure validator\n    ├── validate_journey_required_fields.py # Required fields validator\n    ├── validate_journey_expressions.py # Expression syntax validator\n    ├── validate_journey_variables.py # Variable usage validator\n    ├── stringify_json_field.py       # JSON stringification tool\n    ├── node_definitions.json         # Node type definitions\n    └── examples/                     # Working journey examples\n        ├── loop_example.md\n        ├── email_otp_authentication_example.md\n        ├── password_reset_example.md\n        └── registration_with_protection_example.md\n```\n\n## Development\n\n### Running the MCP Server Standalone\n\n```bash\ncd mcp\nnode server.js\n```\n\n### Testing Validators Directly\n\nIf you wish, it is possible to run the validation scripts manually on a journey json file:\n\n```bash\ncd mcp\npython3 journey_fixes.py /path/to/journey.json\npython3 validate_journey_metadata.py /path/to/journey.json\npython3 validate_journey_structure.py /path/to/journey.json\n# ... etc\n```\n\n### Modifying Generation Instructions\n\nEdit `instructions.md` to update:\n- Node type patterns and examples\n- Generation rules and best practices\n- Expression syntax guidelines\n- Variable management patterns\n\nChanges take effect on next Gemini CLI session.\n\n### Adding New Validators\n\n1. Create new Python script in `mcp/` directory inheriting from `JourneyValidatorBase`\n2. Add tool definition in `server.js` `ListToolsRequestSchema` handler\n3. Add script mapping in `validator_scripts` object\n4. Add handler in `CallToolRequestSchema`\n5. Update this README\n\n### Extending Node Definitions\n\nEdit `mcp/node_definitions.json` to add or update node type definitions. The validators use this file to check required fields for each node type.\n\n## Troubleshooting\n\n### Common Issues\n\n**MCP Server Connection Failed**\n\nIf the extension fails to connect, the MCP server is missing npm dependencies:\n\n```bash\ncd ~/.gemini/extensions/ts-ido-journey-builder/mcp\nnpm install\n```\n\nThen restart Gemini CLI.\n\n**Validation Issues**\n\n- Ensure Python 3 is installed and available as `python3`\n- Check that journey JSON file path is correct and readable\n- Review specific validation error messages\n\n\n## Security\n\nThis extension implements multiple security layers to protect your workspace:\n\n### Built-in Security Features\n\n1. **Path Validation**: All file operations are restricted to allowed directories:\n   - Your current working directory (where you invoked `gemini`)\n   - The extension workspace folder\n   - Path traversal attacks (e.g., `../../../etc/passwd`) are blocked\n\n2. **File Type Restrictions**: Only `.json` files can be accessed or modified by the extension tools.\n\n3. **File Size Limits**: Files are limited to 10MB to prevent resource exhaustion attacks.\n\n4. **Input Sanitization**: All user inputs are validated and sanitized to prevent injection attacks.\n\n5. **Error Message Sanitization**: Error messages do not expose full filesystem paths, only filenames.\n\n6. **Command Restrictions**: The extension excludes `run_shell_command` to prevent arbitrary command execution.\n\n### Usage Guidelines\n\n> **Local Development Only**: This extension is designed for local development. The MCP server runs locally and only accesses files within your workspace.\n\n> **Review Generated Code**: Always review generated journey configurations before deploying to production. Ensure they align with your organization's security and compliance requirements.\n\n> **Platform Validation**: Transmit Security's Mosaic platform performs additional validation during journey import. Generated JSON must pass both this extension's validation and the platform's import checks.\n\n## About Transmit Security\n\n[Transmit Security](https://transmitsecurity.com/) provides a unified identity and fraud prevention platform. The Mosaic platform enables organizations to design customer identity journeys using visual tools, natural language prompts, and AI-driven security measures. It combines:\n\n- **Identity Management**: Authentication, authorization, session management\n- **Fraud Prevention**: Risk-based authentication, behavioral analytics, bot detection\n- **Identity Verification**: Document verification, biometric authentication, liveness detection\n\nFor more information, visit the [Transmit Security Developer Documentation](https://developer.transmitsecurity.com/guides/orchestration).\n\n## License\n\nApache License 2.0 - See [LICENSE](LICENSE) file for details.\n\nCopyright © 2025 Transmit Security\n\n## Support\n\nFor issues, questions, or contributions:\n\n- **Bug Reports**: Create an issue in the project repository\n- **Documentation**: Consult the [Transmit Security Documentation](https://developer.transmitsecurity.com/guides/orchestration) for comprehensive journey generation guidance\n- **Platform Issues**: Contact Transmit Security support for Mosaic platform questions\n\n## Related Resources\n\n- [Transmit Security Documentation](https://developer.transmitsecurity.com/guides/orchestration)\n- [IDO Journey Overview](https://developer.transmitsecurity.com/guides/orchestration/journeys)\n- [Model Context Protocol](https://modelcontextprotocol.io/introduction)\n- [Gemini CLI Documentation](https://geminicli.com/docs/extensions/)\n\n---\n\n**Version:** 1.0.0  \n**Last Updated:** November 2025\n",
  "bytes": 16609,
  "sha": "65f33054c8ba78321053779a50bd16db3ccec839daeef30c2d714b1519112e9e",
  "repo_slug": "transmitsecurity/transmit-security-journey-builder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_transmitsecurity_transmit_security_journ_e371aef7/readme"
}