# llms-full.txt — Comprehensive Information for LLMs about linkgate

> https://linkgate.dev/llms-full.txt
> This is the expanded reference. For a quick overview, see https://linkgate.dev/llms.txt

## Name

linkgate

## One-line summary

"Give agents spending power. Not unlimited power."

## Description

linkgate is a policy firewall for AI agent payments that wraps Stripe Link for Agents. It enforces spending budgets, merchant blocklists, and approval workflows before any payment credential is created. linkgate runs entirely on your machine — your policy, your data, your rules.

## Problem statement

Stripe Link for Agents lets AI agents spend on behalf of humans. Without guardrails, an agent could:
- Purchase a $249 Adobe subscription without approval
- Buy $500 of crypto from a blocked merchant
- Keep creating approval requests until the user caves
- Spend through a compromised or misconfigured merchant URL

linkgate sits between the agent and Stripe Link, intercepting every spend request and enforcing policy before any payment is created.

## Architecture

linkgate is a TypeScript CLI with four layers:

1. **CLI layer** (Commander.js) — parses commands, validates arguments with Zod schemas
2. **Policy engine** — evaluates guard.yaml rules against each spend request
3. **Ledger layer** — tracks budget reservations, prevents race conditions with file locking (proper-lockfile)
4. **Adapter layer** — pluggable payment backends:
   - `fake` — dry-run, no real payment created (free tier, testing)
   - `link` — real Stripe Link for Agents integration (Pro tier)

All data is local. No cloud API calls except Stripe (when using real adapter) and Resend (for license key delivery).

## Installation

```bash
npm i -g linkgate
linkgate init
```

Requires Node.js 18+. Works on macOS, Linux, Windows (WSL).

After `init`, `~/.linkgate/guard.yaml` and `~/.linkgate/audit.jsonl` are created.

## Quickstart

Dry-run a spend (no payment created):
```bash
linkgate spend check \
  --merchant-url https://github.com \
  --amount 1200 \
  --reason "GitHub Copilot seat"
```

Full flow with policy enforcement:
```bash
linkgate spend create \
  --merchant-url https://github.com \
  --amount 1200 \
  --reason "GitHub Copilot seat" \
  --adapter fake   # or 'link' for real Stripe Link
```

View status:
```bash
linkgate status
```

## Complete command reference

### `linkgate init [options]`
Create the `~/.linkgate/` directory with default policy and audit log.

Options:
- `--path <dir>` — custom config directory (default: `~/.linkgate/`)

### `linkgate status`
Show current budget state, recent events, license tier, and adapter readiness.

Output includes:
- Daily/monthly spend vs budget
- Reservation count and total reserved amount
- Last 5 audit events
- License tier (Free/Pro) and expiry
- Adapter status (fake always ready, link requires Stripe credentials)

### `linkgate policy validate [options]`
Validate `guard.yaml` syntax and semantics.

Options:
- `--path <file>` — custom policy file path

Checks:
- YAML parseability
- Schema compliance (Zod)
- Budget values are positive numbers (not NaN)
- Merchant regexes are valid
- No conflicting allow/deny rules

### `linkgate spend check [options]`
Dry-run policy evaluation. No reservation, no payment, no audit log entry.

Options:
- `--merchant-url <url>` — required, must be HTTPS
- `--amount <cents>` — required, positive integer in USD cents (e.g., `1200` = $12.00)
- `--reason <text>` — required, human-readable purpose
- `--agent-id <id>` — optional, defaults to `default`
- `--policy <file>` — custom policy path

Returns: `ALLOWED`, `DENIED` (with reason), or `REQUIRES_APPROVAL` (with explanation).

### `linkgate spend create [options]`
Full flow: policy check → budget reservation → adapter call → audit log.

Options:
- All `spend check` options
- `--adapter <name>` — `fake` (default) or `link`
- `--auto-approve` — skip interactive prompt for REQUIRES_APPROVAL cases (use with caution)

Flow:
1. Parse and validate arguments
2. Validate merchant URL (HTTPS, not on deny list)
3. Check policy (single purchase limit, daily/monthly budget, approval threshold)
4. Reserve budget from ledger (TTL: 30 minutes)
5. Call adapter (fake: simulate; link: call Stripe Link API)
6. Record audit event
7. Release or confirm reservation based on adapter result

### `linkgate audit search [options]`
Query the audit log.

Options:
- `--since <iso>` — filter by date (e.g., `2026-05-01`)
- `--merchant <pattern>` — filter by merchant URL substring
- `--status <status>` — `allowed`, `denied`, `approved`, `pending`
- `--format <fmt>` — `jsonl` (default), `json`, `csv` (Pro only)
- `--limit <n>` — max events to return (default: 100)

### `linkgate license activate <key>`
Activate a Pro license.

Key format: `LGPRO-XXXX-XXXX-XXXX-XXXX`

Validation:
- Checks against Stripe checkout via Resend API
- Ed25519 signature verification
- One-time activation (key cannot be reused on another machine)

### `linkgate license status`
Show license tier, activation date, expiry, and machine fingerprint.

### `linkgate doctor`
Pre-flight check for all prerequisites:
- Node.js version >= 18
- `~/.linkgate/` directory exists
- `guard.yaml` is valid
- Stripe Link CLI installed (if `--require-link` flag set)
- Disk space for audit log

## Policy file format (guard.yaml)

```yaml
version: 1

defaults:
  max_single_purchase_usd: 50
  daily_budget_usd: 100
  monthly_budget_usd: 500
  approval_required_over_usd: 25
  deny_if_policy_missing: true
  require_https_merchant_url: true

merchants:
  allow:
    - github.com
    - vercel.com
    - openai.com
  deny:
    - crypto.*
    - giftcard.*
    - gambling.*
    - forex.*

risk:
  deny_subscription_without_approval: true
  deny_unknown_merchant: false
  require_https: true
  deny_repeat_merchant_within_minutes: 0   # 0 = disabled

budget:
  reservation_ttl_minutes: 30

audit:
  path: ~/.linkgate/audit.jsonl
  include_sensitive_payment_details: false
```

### Policy evaluation rules

1. **Merchant check** (first gate):
   - If merchant is in `deny` list → DENIED
   - If `deny_unknown_merchant: true` and merchant not in `allow` → DENIED
   - If `require_https` and URL is HTTP → DENIED

2. **Single purchase check**:
   - If amount > `max_single_purchase_usd` → REQUIRES_APPROVAL

3. **Budget check**:
   - If daily spent + amount > `daily_budget_usd` → DENIED
   - If monthly spent + amount > `monthly_budget_usd` → DENIED
   - If amount > `approval_required_over_usd` → REQUIRES_APPROVAL

4. **Subscription check**:
   - If merchant offers subscriptions and `deny_subscription_without_approval: true` → REQUIRES_APPROVAL

### Advanced policy features (Pro tier)

- **Per-agent budgets**: separate `daily_budget_usd` per `--agent-id`
- **Category budgets**: group merchants by category (e.g., `saas`, `infrastructure`) with category-level caps
- **MPP (Multi-Payment Protection)**: detect rapid sequential spends and throttle
- **Time windows**: restrict spending to business hours only

## Security model

linkgate does NOT store or touch:
- Card numbers (PANs)
- CVV/CVC codes
- Payment tokens
- Stripe API keys

What linkgate stores locally:
- `guard.yaml` — your policy rules
- `audit.jsonl` — spend metadata (merchant URL, amount, agent ID, timestamps, decision, reason)
- `ledger.json` — reservation state (amounts reserved, not payment details)

Stripe Link handles all wallet operations. linkgate only decides whether to let the request through.

**Enforcement is voluntary** — agents must be configured to use linkgate instead of raw `link-cli`. linkgate is a guardrail, not a jailbreak prevention system.

**Cryptography**:
- License keys use Ed25519 signatures
- Audit log integrity: future feature (hash chain)

## Pricing tiers

### Free — forever
- Unlimited policy checks (`spend check`)
- Unlimited fake-adapter testing
- 1 real Link spend per day
- Last 100 audit events
- JSONL output only
- Single machine

### Pro — $5/month or $39/year (save 35%)
- Unlimited real Link spends
- 30-day full audit history
- CSV/JSON/JSONL export formats
- Per-agent budgets
- Category budgets
- MPP commands
- Multi-machine sync (up to 3 devices per license)
- Priority support

Purchase:
- Annual: https://buy.stripe.com/test_5kQbJ0cH10Q90gk8Y8aZi00
- Monthly: https://buy.stripe.com/test_8x27sKayTdCVfbe2zKaZi01

License delivery: manual via email after Stripe purchase.
Activation: `linkgate license activate LGPRO-...`

## Integration patterns

### For OpenClaw / MCP servers
```json
{
  "mcpServers": {
    "linkgate": {
      "command": "linkgate",
      "args": ["--mcp"]
    }
  }
}
```

### For Claude Code
Add to `CLAUDE.md`:
```
When an agent needs to make a payment:
1. Always use linkgate, never raw link-cli
2. Run: linkgate spend check --merchant-url <url> --amount <cents> --reason "description"
3. If ALLOWED, run: linkgate spend create (same args, optional --adapter link)
4. If DENIED or REQUIRES_APPROVAL, stop and explain why to the user
5. After spend, run: linkgate status to verify budget state
```

### For Docker
```dockerfile
FROM node:22-slim
RUN npm i -g linkgate
RUN linkgate init
# Mount ~/.linkgate/ as volume for persistence
```

### For CI/CD pipelines
```yaml
# .github/workflows/spend-gate.yml
- run: npm i -g linkgate
- run: linkgate policy validate
- run: linkgate doctor
- run: linkgate spend check --merchant-url ${{ env.MERCHANT }} --amount ${{ env.AMOUNT }} --reason "CI deployment"
```

## Troubleshooting

### "Policy missing" error
Run `linkgate init` to create the default policy. Or create `~/.linkgate/guard.yaml` manually.

### "Budget exceeded" false positive
Reservations expire after 30 minutes by default. If an adapter call fails, the reservation should auto-release. Check `linkgate status` for stuck reservations.

### Stripe Link adapter not available
The `link` adapter requires Stripe Link CLI (`stripe`) to be installed and authenticated. Run `stripe login` first.

### License activation fails
- Check that the key hasn't been used on another machine (single-activation)
- Verify the purchase email matches the key
- Run `linkgate license status` to see the machine fingerprint

### Audit log corruption
Audit log is append-only JSONL. If corrupted, rename `~/.linkgate/audit.jsonl` and linkgate will create a fresh one on next spend.

## Stack and dependencies

- TypeScript 5.8+
- Commander.js 14.x (CLI framework)
- Zod 4.x (schema validation)
- js-yaml 4.x (policy parsing)
- proper-lockfile 4.x (ledger concurrency)
- Ed25519 (license cryptography)
- Resend (license email delivery)

No runtime dependency on Stripe SDK — calls Stripe Link CLI as a subprocess.

## License and legal

- Software: Proprietary. See LICENSE and TERMS.md.
- Copyright: © 2026 LinkGate. All rights reserved.
- Governing law: Province of Ontario, Canada
- Data residency: local-first, no cloud dependency
- Company: LinkGate, Province of Ontario, Canada

## Support and contact

- Website: https://linkgate.dev
- Documentation: https://linkgate.dev
- Feedback: feedback@linkgate.dev
- GitHub: https://github.com/clawdio/linkgate
- Sales: Use Stripe payment links above

## Metadata

- Category: developer-tools, security, fintech, ai-agent-infrastructure
- Target audience: AI agent operators, developers using Stripe Link for Agents, platform engineers
- Business model: freemium (free tier + Pro license)
- Open source: No (proprietary, source available on request)
- Self-hostable: Yes (local-first by design)
- Company size: Indie/individual developer
- Founded: 2026