Feat/scoped script tokens

[andrewmelchor]

Summary

Add scoped authentication tokens for server-spawned scripts (JavaScript/TypeScript/Python). Instead of passing the main server token
to scripts, the server now generates short-lived, HMAC-signed tokens that are scoped to specific flows and sessions. This implements
the principle of least privilege - script tokens can only:

• Execute requests within their assigned flow/session
• Update session variables for their assigned session
• Read execution results for their assigned flow
• Subscribe to events for their assigned flow

Scripts are blocked from administrative operations (creating/deleting sessions, spawning nested scripts, accessing config, enumerating
workspace files).

Also adds web UI support for running scripts with the same security model.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Chore

How Has This Been Tested?

• Unit tests
• E2E tests
• Manual testing:

Checklist

• I have followed the contributing guidelines
• I have performed a self-review
• I have added tests for my changes
• I have updated documentation if needed
• My changes generate no new warnings

[github-actions]

🚀 Preview Deployment

Your changes have been deployed to:

📖 Docs: https://docs-pr-11.t-req.io

This preview will be automatically removed when the PR is closed.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements scoped script token authentication to enable server-spawned scripts to make authenticated API requests with limited privileges. The implementation adds whitelisted script and test runners with comprehensive security controls.

Key Changes:

• Adds HMAC-SHA256 signed script tokens with 15-minute TTL, JTI-based revocation, and timing-safe validation
• Implements enforceScriptScope authorization that prevents script tokens from spawning nested scripts, listing workspace files, or accessing resources outside their assigned flow and session
• Adds whitelisted runner and test framework detection (bun, node, tsx, ts-node, python, vitest, jest, pytest)
• New /scripts/run and /tests/run endpoints with SSE event streaming for output
• Client library automatically reads TREQ_TOKEN, TREQ_FLOW_ID, and TREQ_SESSION_ID from environment for server-spawned scripts
• Web UI and TUI components for script execution with runner selection dialogs

Security Model:

• Script tokens cannot spawn nested scripts or tests
• Tokens are scoped to specific flowId and sessionId
• Tokens are revoked immediately on script exit
• Only whitelisted runners allowed (no arbitrary command execution)
• Path validation prevents workspace escape

PR Template Issues:

• PR description is completely empty - no summary, related issue, testing information, or checklist completion
• No test files added despite significant new functionality

Confidence Score: 3/5

• This PR implements security-critical authentication functionality with good security design but lacks test coverage and documentation
• Score reflects solid security architecture (timing-safe comparisons, scope enforcement, revocation) and comprehensive authorization checks, but lowered due to completely empty PR description, no test files for critical auth logic, and unnecessary legacy format support adding complexity
• Pay close attention to packages/app/src/server/auth.ts for token validation logic and packages/app/src/server/app.ts for authorization enforcement

Important Files Changed

Filename	Overview
packages/app/src/server/auth.ts	Adds scoped script token system with HMAC-SHA256 signing, timing-safe validation, revocation tracking, and legacy format support
packages/app/src/server/script-runner.ts	New file implementing whitelisted script runner detection and execution with proper path validation and graceful process termination
packages/app/src/server/test-runner.ts	New file implementing whitelisted test framework detection and execution with proper security controls
packages/app/src/server/app.ts	Adds script/test endpoints with comprehensive enforceScriptScope authorization checks preventing privilege escalation
packages/app/src/server/service.ts	Adds script and test execution logic with token generation, proper revocation on exit, and flow/session management
packages/core/src/server-client.ts	Adds support for server-spawned scripts via TREQ_TOKEN, TREQ_FLOW_ID, and TREQ_SESSION_ID environment variables

Sequence Diagram

sequenceDiagram
    participant User
    participant Client as Web UI or TUI
    participant API as API Server
    participant AuthLayer as Authorization
    participant Service
    participant Runner as Script Runner
    participant Script as User Script

    User->>Client: Click Run Script
    Client->>API: Request runners
    AuthLayer->>AuthLayer: Verify user
    API->>Service: getRunners
    Service->>Runner: detectRunner
    Runner-->>Client: runner options
    
    Client->>API: Create flow
    API->>Service: createFlow
    Service-->>Client: flow identifier
    
    Client->>API: Run script request
    AuthLayer->>AuthLayer: Check permissions
    Note over AuthLayer: Prevents nested spawning
    API->>Service: executeScript
    Service->>AuthLayer: Generate limited scope
    AuthLayer-->>Service: temporary access
    Service->>Runner: spawn script
    Runner->>Script: start process
    Runner-->>Client: execution identifier
    
    Client->>API: Subscribe events
    
    Script->>API: Execute HTTP request
    AuthLayer->>AuthLayer: Validate scope
    Note over AuthLayer: Enforces flow and session scope
    API->>Service: process request
    Service-->>Script: HTTP response
    
    Script->>Script: Complete
    Runner->>AuthLayer: Cleanup access
    Runner->>Service: Exit handler
    Service-->>Client: Completion event

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}