feat: add support for linked Security Profile API keys, additional tests

[jroberts2600]

Description

This PR enhances the PANW Prisma AIRS guardrail plugin with additional error handling, comprehensive test coverage, and support for additional configuration parameters.

Key Changes:

• Implemented test suite with proper HTTP mocking for deterministic, reliable tests
• Added support for profile_id, app_name, and timeout parameters in the manifest
• Made profile_name optional to support profiles linked directly to API keys in Strata Cloud Manager
• Ensured proper environment variable isolation in tests to prevent side effects

Motivation

• Missing support for AIRS features like linked Security Profiles to API keys and custom application names
• Additional tracking parameters (app_name, profile_id) enable better observability in Prisma AIRS

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)

How Has This Been Tested?

• Unit Tests
• Integration Tests
• Manual Testing

Screenshots (if applicable)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Related Issues

N/A

[matter-code-review]

Description

Summary By MatterAI

🔄 What Changed

Added support for Portkey's x-portkey-trace-id header as the AIRS tr_id (AI Session ID) in the PANW Prisma AIRS plugin. Implemented fallback logic using crypto.randomUUID() or timestamp-based ID generation if the header is missing. Enhanced test coverage with a dedicated unit test to validate trace ID propagation.

🔍 Impact of the Change

Enables consistent AI session tracking across Portkey and PANW Prisma AIRS by propagating trace context. Ensures observability and auditability of AI interactions. Improves debugging and monitoring capabilities through stable session correlation.

📁 Total Files Changed

File	ChangeLog
Trace ID Support intercept.ts	Extract x-portkey-trace-id from request headers and use as tr_id; fallback to generated ID
Test Suite panw.airs.test.ts	Added test to verify tr_id is correctly set from header value

🧪 Test Added/Recommended

Added

• Test validating tr_id is populated from x-portkey-trace-id header when present
• Verification that the generated payload contains the correct trace ID

🔒 Security Vulnerabilities

No security vulnerabilities detected. Trace ID extraction is read-only and does not introduce injection risks.

⏳ Estimated code review effort

LOW (~7 minutes)

Tip

Quality Recommendations

1. Ensure crypto.randomUUID() fallback is only used in secure contexts (HTTPS) to prevent entropy issues

2. Add type safety for headers to avoid implicit any on ctx.request.headers

♫ Tanka Poem

Trace flows through code,
UUIDs guard the session path.
Headers light the way,
No lost calls in transit's maze,
Logs bloom with context today. 🌐🔍

Sequence Diagram

sequenceDiagram
    participant U as User
    participant P as Portkey Gateway
    participant A as PANW Prisma AIRS

    Note over U,P: Trace ID Propagation

    U->>P: Request with x-portkey-trace-id
    P->>P: Extract traceId from headers
    P->>P: Build payload with tr_id
    P->>A: POST /airs/analyze {tr_id, metadata}
    A-->>P: {action: 'allow'}
    P-->>U: Response

    alt Missing trace header
        U->>P: Request without x-portkey-trace-id
        P->>P: Generate fallback traceId
        P->>A: POST /airs/analyze {tr_id}
        A-->>P: {action: 'allow'}
        P-->>U: Response
    end

Loading

[matter-code-review]

✅ Reviewed the changes: Review of PANW Prisma AIRS Guardrail enhancements for API key handling, profile parameters, and test coverage.

[narengogi]

looks good minor change

[narengogi]

you do not need to add this parameter, the gateway uses the x-portkey-timeout header as the parameter for timeout and is provided in the parameters object

[jroberts2600]

thank you! now updated.

[matter-code-review]

✅ Reviewed the changes: This PR introduces support for linked Security Profile API keys and enhances test coverage. Key areas for improvement include type safety and test reliability.

[matter-code-review]

✅ Reviewed the changes: Review of trace ID generation and test coverage for PANW Prisma AIRS integration