Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (150 loc) · 4.7 KB

AGENTS.md

File metadata and controls

184 lines (150 loc) · 4.7 KB

trusted-agentic-commerce-protocol

This file provides context for AI coding assistants working with this repository.

Repository Overview

A secure authentication and data encryption protocol for AI agents, merchants and merchant vendors.

Tech Stack: Node.js, TypeScript, Python

Build System

The project uses npm for JavaScript/TypeScript and pip for Python. Key commands:

  • JavaScript/TypeScript: 
    npm install
npm run build
  • Python: 
    pip install -r requirements.txt

Essential Workflows

Initial Setup

  1. Clone the repository
  2. For JavaScript/TypeScript SDK: 
    cd sdk/javascript  # or sdk/typescript
npm install
  3. For Python SDK: 
    cd sdk/python
pip install -r requirements.txt

Making Code Changes

  1. Create a new branch for your changes
  2. Make your code changes
  3. Run linters:
    • JavaScript/TypeScript: npm run lint
    • Python: make lint
  4. Run tests (see "Running Tests" section)
  5. Commit your changes and create a pull request

Running Tests

  • JavaScript/TypeScript: 
    npm test
  • Python: 
    make test

Project Structure

📁 examples/
  📄 voice_assistant_travel.json
📁 schema/
  📁 2025-08-27/
    📄 schema.json
    📄 schema.ts
  📁 2025-11-12/
    📄 schema.json
    📄 schema.ts
📁 sdk/
  📁 javascript/
    📁 src/
    📁 tests/
    📄 .prettierignore
    📄 .prettierrc
    📄 README.md
    📄 eslint.config.js
    📄 package-lock.json
    📄 package.json
  📁 python/
    📁 src/
    📁 tests/
    📄 .flake8
    📄 Makefile
    📄 README.md
    📄 pyproject.toml
    📄 requirements-dev.txt
    📄 requirements.txt
    📄 setup.py
  📁 typescript/
    📁 src/
    📁 tests/
    📄 .prettierignore
    📄 .prettierrc
    📄 README.md
    📄 eslint.config.js
    📄 package-lock.json
    📄 package.json
    📄 tsconfig.json
📄 .gitignore
📄 LICENSE
📄 README.md
📄 SECURITY.md

Critical Patterns

  1. Use JWS+JWE for authentication and confidentiality
  2. Support both RSA and Elliptic Curve (P-256/384/521) keys
  3. Implement JSON Web Key Sets (JWKS) for key distribution
  4. Follow the schema versions in the schema/ directory
  5. Implement SDK functionality in the respective language directories under sdk/

Common Pitfalls to Avoid

  1. Mixing up schema versions - always refer to the correct schema version
  2. Forgetting to update all SDK implementations when making changes
  3. Not properly handling key generation and management
  4. Neglecting to validate inputs according to the schema

Security Guidelines (CRITICAL - Forter Standards)

Must Follow:

  • ❌ NEVER hardcode secrets, API keys, or credentials
  • ❌ NEVER log sensitive data (PII, tokens, passwords)
  • ❌ NEVER commit .env files or secrets
  • ✅ Use environment variables for all secrets
  • ✅ Validate and sanitize all user inputs
  • ✅ Follow the principle of least privilege

Additional Security Considerations:

  • Ensure proper key management and rotation
  • Implement secure key generation practices as outlined in the README
  • Use strong encryption algorithms and key sizes
  • Regularly update dependencies to patch security vulnerabilities

Before Committing

  1. Run linters:
    • JavaScript/TypeScript: npm run lint
    • Python: make lint
  2. Run tests:
    • JavaScript/TypeScript: npm test
    • Python: make test
  3. Ensure all new code is properly documented
  4. Verify that no sensitive information is being committed
  5. Check that all changes comply with the current schema version

Debugging Tips

  • Use the debug package for Node.js/TypeScript debugging
  • For Python, use the built-in logging module
  • Set up proper error handling and logging in all SDK implementations
  • Use breakpoints in your IDE for step-through debugging

Dependency Management

  • For JavaScript/TypeScript:
    • Use npm install <package> to add new dependencies
    • Update package.json and package-lock.json when adding/updating dependencies
  • For Python:
    • Use pip install <package> and update requirements.txt
    • Consider using a virtual environment for isolation

Testing Strategies

  • Write unit tests for all new functionality
  • Implement integration tests to ensure proper interaction between components
  • Use mocking for external dependencies
  • Aim for high test coverage, especially for critical security-related functions

Key Architectural Decisions

  1. Multi-language SDK support (JavaScript, TypeScript, Python)
  2. Versioned schema approach for backwards compatibility
  3. Use of industry-standard cryptographic practices (JWS, JWE, JWKS)
  4. Separation of concerns between schema definition and SDK implementation

Generated by Forter AI Platform