This document outlines the security model, authorization policies, and permission requirements for the Z.ai Code Review GitHub Action.

All /zai commands are restricted to repository collaborators with write access:

Rationale: Preventing unauthorized users from invoking AI-powered commands mitigates:

• Abuse of API quotas
• Potential injection of malicious prompts
• Unintended information disclosure

• Auto-review on PR open/sync: This passive review runs automatically for all PRs as it only reads diff content and posts a non-interactive review. No command execution is involved.
• Interactive commands: All /zai prefix commands require collaborator authentication via GitHub's permission system.

PRs originating from forks (fork PRs) present unique security considerations because:

1. The fork author may not be a collaborator
2. The base repository owner has limited visibility into fork actions
3. Malicious actors could attempt to extract sensitive information via bot interactions

The action must verify:

1. github.event.pull_request.head.repo.fork — detects fork origin
2. Comment author's permission level via github.rest.teams.checkPermissionsForUser or github.rest.repos.getCollaboratorPermission

The bot supports a finite, safe command set only:

/zai help      - Display available commands
/zai ask       - Answer questions about code
/zai review    - Review specific files
/zai explain   - Explain code sections
/zai describe  - Generate PR description
/zai impact    - Analyze change impact

The following are never executed, regardless of user input:

• Shell or terminal command execution
• File system operations beyond reading PR diff
• Environment variable exposure or modification
• API key or secret retrieval/changes
• Repository content modification (except comments)
• Webhook or workflow trigger manipulation
• SQL or database operations
• Network calls to external services (except Z.ai API)

When a user attempts an unknown or disallowed command:

🤖 I'm sorry, I can only execute authorized commands.
   See /zai help for available commands.

Never expose:

• Internal error details
• Stack traces
• API keys or tokens
• Internal function names or paths

permissions:
  contents: read
  pull-requests: write
  # Optional: if checking org membership
  # members: read

• Never log or expose tokens — Use core.setSecret() for any sensitive values
• Use GitHub-provided token — Default github.token has appropriate scopes
• Rotate regularly — If using a personal access token, rotate per organization policy

To prevent abuse and protect API quotas:

• Track command invocations in action logs (not persisted across runs)
• When limit exceeded:

🤖 Rate limit exceeded. Please try again later.
   Limit: 10 commands per hour per user.

All user-facing error messages must be sanitized:

Action logs (visible to repository admins only) may contain:

• Full error details for debugging
• API response metadata (without secrets)
• Command invocations with user IDs

Logs are never visible to PR authors unless explicitly shared by a maintainer.

If you discover a security vulnerability in this action, please:

1. Do not open a public issue
2. Email the maintainer directly or use GitHub's private vulnerability reporting
3. Provide details: affected version, reproduction steps, potential impact

┌─────────────────────────────────────────────────────────────┐
│                     Incoming Request                        │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  1. Detect: Fork PR? Non-collaborator?                     │
│     → If fork + non-collaborator: BLOCK                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Authenticate: Is user a collaborator?                    │
│     → If no: BLOCK                                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Validate: Is command in whitelist?                      │
│     → If no: REJECT with safe message                       │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Rate Limit: Has user/PR exceeded limits?                │
│     → If yes: REJECT with rate limit message                │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  5. Execute: Call Z.ai API, format response                 │
│     → Sanitize all outputs                                  │
└─────────────────────────────────────────────────────────────┘

• 2025-02-23: Initial security policy document