# Auth Gate Implementation and scope.md Generation Workflow in reverse-skill

> Learn the reverse-skill auth gate implementation workflow. Discover how case-init.ps1 generates scope.md and case-guard.ps1 validates it for secure ACT operations.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-18

---

**The reverse-skill repository enforces a mandatory authentication gate through a two-stage PowerShell workflow: `case-init.ps1` generates the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) authorization document, and `case-guard.ps1` validates it before any ACT operation proceeds.**

This workflow ensures that no offensive security actions execute against a target without explicit written authorization, proper network profiling, and defined asset scope. Below is the complete technical breakdown of how the auth gate functions, including exact file paths, parameter behaviors, and validation logic from the source code.

---

## Overview of the Auth Gate Architecture

The auth gate in `reverse-skill` is implemented as a **state machine** that progresses from "pending" to "granted" status. The gate consists of two core scripts located in `skills/scripts/`:

- **`case-init.ps1`** — Generates the case workspace and the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) authorization contract
- **`case-guard.ps1`** — Performs pre-flight validation before any skill execution

Both scripts operate on a YAML-formatted [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file that serves as the single source of truth for authorization status, network constraints, and in-scope targets.

---

## Step 1: Initialize the Case with `case-init.ps1`

The workflow begins by running `skills/scripts/case-init.ps1`, which creates the case directory structure and populates [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with templated authorization fields.

### Key Operations in `case-init.ps1`

The script performs four critical functions (lines 70–242):

1. **Resolves authentication status** (lines 70–78): Determines `authStatusResolved` based on the `-AuthGranted` switch parameter
2. **Builds the asset list** (lines 91–99): Processes `-TargetUrl` inputs into structured in-scope assets
3. **Decides network mode** (lines 103–119): Validates `authorized_target_only`, `offline`, or other network profiles
4. **Writes the markdown template** (lines 183–242): Generates the complete [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with sections for **meta**, **auth**, **in_scope**, **network_profile**, and **signoff**

### Code Example: Creating a Case

```powershell

# Initialize with pending authentication (default)

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" -CaseName my-case

# Initialize with auth pre-granted and target specified

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" -CaseName my-case `
    -AuthGranted -TargetUrl "https://app.example/" `
    -NetworkProfile authorized_target_only

```

The `-AuthGranted` flag forces `authStatusResolved = 'granted'` at line 71, bypassing the default "pending" state. When this flag is omitted, the generated [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) contains placeholder values requiring manual completion.

---

## Step 2: Authorize via [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) Editing

After initialization, [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) resides at `work/<case>/scope.md` with a templated structure created at lines 197–205 of `case-init.ps1`. The file uses YAML frontmatter with markdown sections.

### Required Fields to Complete

| Section | Field | Purpose |
|---------|-------|---------|
| `auth` | `status` | Must change from `pending` to `granted` |
| `auth` | `granted_by` | Identifier of authorizing party |
| `in_scope` | `assets` | List of authorized target URLs/IPs |
| `network_profile` | `mode` | Network constraints for engagement |
| `signoff` | checklist | Verification items (lines 331–336) |

The checklist under **signoff** displays completion status using markdown checkboxes (`[ ]` → `[x]`). The case is considered **ready for ACT** only when all mandatory checkboxes are marked complete.

---

## Step 3: Re-initialization (Optional Alternative to Manual Edit)

Rather than manually editing [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), you can re-run `case-init.ps1` with authorization parameters to update the file programmatically. This approach is documented in the comment block at lines 5–6 of `case-init.ps1`.

This method is preferred when:
- The initial case was created without `-AuthGranted`
- Additional targets must be added to the asset list
- Network profile requirements have changed

---

## Step 4: Enforce the Gate with `case-guard.ps1`

Before any ACT operation executes, `skills/scripts/case-guard.ps1` performs mandatory validation. The script returns specific exit codes that control workflow continuation:

| Exit Code | Meaning | Behavior |
|-----------|---------|----------|
| `0` | Gate passed | Proceed with primary skill execution |
| `1` | Error | Fatal configuration or parsing error |
| `2` | Not ready | Auth gate conditions not satisfied |

### Validation Logic (lines 51–87)

`case-guard.ps1` parses [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) and enforces four sequential checks:

1. **Authentication status** (lines 52–53): Verifies `auth.status` equals **granted**
2. **Network profile validity** (lines 56–67): Confirms `network_profile.mode` is valid; if `offline`, checks for offline-sample cue existence
3. **Asset presence** (lines 71–82): Validates at least one in-scope asset unless operating in `offline` mode
4. **ACT readiness flag** (line 85): Confirms `ready_for_act: true`

### Exit Handling (lines 88–102)

Any check failure triggers immediate termination with the appropriate exit code. The `-Force` parameter modifies this behavior to emit warnings only and return exit `0`—**not recommended for production engagements**.

### Code Example: Running the Guard

```powershell

# Standard gate verification

powershell -File skills/scripts/case-guard.ps1 `
    -CaseRoot work\my-case

# Force continuation despite warnings (use with caution)

powershell -File skills/scripts/case-guard.ps1 `
    -CaseRoot work\my-case -Force

```

---

## Step 5: Execute the Primary Skill

Upon successful guard validation (exit 0), the workflow extracts the `primary_skill` from the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) header (populated at lines 186–193 of `case-init.ps1`) and executes the designated skill against the authorized assets within the defined network constraints.

---

## Supporting Files and Contracts

| File | Path | Purpose |
|------|------|---------|
| `case-init.ps1` | `skills/scripts/case-init.ps1` | Case initialization and [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) generation |
| `case-guard.ps1` | `skills/scripts/case-guard.ps1` | Pre-ACT authorization validation |
| `verify-routing-coherence.ps1` | `skills/scripts/verify-routing-coherence.ps1` | CI validation of `auth.status` consistency across routing tests |
| [`scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope-contract.md) | [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | Formal specification of required [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) fields |
| [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) | [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Guidance for linking evidence to auth gate |

---

## Summary

- **`case-init.ps1`** creates the authorization contract ([`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md)) with configurable auth status, network profile, and asset scope
- **Manual editing or re-initialization** updates [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) from "pending" to "granted" state with completed checklists
- **`case-guard.ps1`** enforces hard gates on auth status, network validity, asset presence, and readiness flag before any ACT
- **Exit codes 0/1/2** provide deterministic workflow control for CI/CD and manual operations
- **The `-Force` parameter** bypasses gate failures with warnings only—avoid in production

---

## Frequently Asked Questions

### What happens if `auth.status` remains `pending` in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md)?

`case-guard.ps1` will detect the non-granted status at lines 52–53 and exit with code `2` (not ready), preventing any ACT operations. The workflow must pause until authorization is explicitly recorded.

### Can I use `case-init.ps1` to update an existing case without recreating it?

Yes. Re-running `case-init.ps1` with the same `-CaseName` and new parameters (such as `-AuthGranted` or additional `-TargetUrl` values) will regenerate [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with updated values while preserving the existing case directory.

### What is the difference between exit code 1 and exit code 2 from `case-guard.ps1`?

Exit code `1` indicates a **fatal error** such as file parsing failure or missing [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md). Exit code `2` indicates the **gate conditions are not yet satisfied**—the file is valid but authorization is incomplete. This distinction allows automation to differentiate between retryable and non-retryable failures.

### Is the `-Force` parameter safe to use in automated pipelines?

No. The `-Force` parameter (lines 88–102) causes `case-guard.ps1` to emit warnings and return exit `0` regardless of gate status, effectively disabling the auth gate. It should be restricted to local development or testing scenarios with synthetic data.