Metadata-Version: 2.4
Name: agentauth-py
Version: 0.2.0
Summary: AI Agent session management SDK
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: browser-cookie3>=0.19.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

AgentAuth

# AgentAuth

**Persistent auth for AI agents. Works on any site, today.**

No website integration required. No OAuth adoption needed. Just secure session management that works.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/agentauth-py.svg)](https://pypi.org/project/agentauth-py/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Dev.to](https://img.shields.io/badge/read-blog%20post-black?logo=dev.to)](https://dev.to/jacobgadek/reverse-engineering-chromes-cookie-encryption-to-authenticate-ai-agents-212i)

[Quick Start](#quick-start) • [LangChain](#langchain-integration) • [n8n](#n8n-integration) • [Chrome Extension](#how-it-works) • [Roadmap](#roadmap)

---

## The Problem

```python
# What every agent developer does today
cookies = {"session_id": "abc123..."}  # Hardcoded. Breaks constantly. Security nightmare.
```

Sessions expire. Cookies leak into git history. No audit trail. No access control.

## The Solution

```python
from agent_auth import Vault

vault = Vault()
vault.unlock("password")
cookies = vault.get_session("linkedin.com")  # Encrypted. Scoped. Audited.
```

```bash
pip install agentauth-py
```

**Works on sites as they exist today.** No website changes. No OAuth adoption. No waiting for the ecosystem.

---

## See It In Action

![Automatically log into any site with stored sessions](https://raw.githubusercontent.com/jacobgadek/agent-auth/main/docs/images/agentex3.gif)

*Agent automatically authenticates using stored session—no manual login, no hardcoded cookies.*

---

## How It Works

![AgentAuth Chrome Extension](https://raw.githubusercontent.com/jacobgadek/agent-auth/main/docs/images/extension.png)

![Export cookies](https://raw.githubusercontent.com/jacobgadek/agent-auth/main/docs/images/agentex1.gif)

![Agent retrieves session](https://raw.githubusercontent.com/jacobgadek/agent-auth/main/docs/images/agentex2.gif)

1. **Export cookies** with the Chrome extension while logged into any site
2. **Store them** in an encrypted vault (`agent-auth add linkedin.com`)
3. **Your agent retrieves them** securely on-demand

---

## Quick Start

### 1. Initialize your vault

```bash
agent-auth init
```

### 2. Create an agent with scoped access

```bash
agent-auth create-agent sales-bot --scopes linkedin.com,gmail.com
```

### 3. Store a session

Export cookies with the [Chrome extension](#how-it-works), then:

```bash
agent-auth add linkedin.com
# Paste exported cookies
```

### 4. Use in your agent

```python
from agent_auth import Agent, AgentAuthClient

agent = Agent.load("sales-bot")
client = AgentAuthClient(agent)
session = client.get_session("linkedin.com")

import requests
response = requests.get("https://linkedin.com/feed", cookies=session)
```

---

## Why AgentAuth?

| Without AgentAuth | With AgentAuth |
|---|---|
| Hardcoded cookies in code | Encrypted vault storage |
| Sessions in git history | Secrets separate from code |
| Any code can access anything | Scoped access per agent |
| No idea what accessed what | Full audit logging |
| Sessions break silently | Expiration notifications |

---

## LangChain Integration

```python
from langchain_openai import ChatOpenAI
from langchain.agents import initialize_agent, AgentType
from agent_auth.langchain import get_agentauth_tools

tools = get_agentauth_tools(
    agent_name="sales-bot",
    vault_password="your-vault-password"
)

llm = ChatOpenAI(model="gpt-4", temperature=0)
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# Agent automatically uses stored sessions
response = agent.run("Get my LinkedIn notifications")
```

**Available tools:**
- `authenticated_request` — Make HTTP requests with stored session cookies
- `get_session_cookies` — Retrieve cookies for custom requests

---

## n8n Integration

Use AgentAuth in your n8n workflows with our community node.

```bash
npm install n8n-nodes-agentauth
```

The node lets you:
- Store and retrieve session cookies in n8n workflows
- Use authenticated sessions with HTTP Request nodes
- Build automation flows that require login

📦 [View on npm](https://www.npmjs.com/package/n8n-nodes-agentauth) | [GitHub](https://github.com/jacobgadek/n8n-nodes-agentauth)

---

## Playwright Integration

```python
from playwright.sync_api import sync_playwright
from agent_auth import Vault

vault = Vault()
vault.unlock("password")
cookies = vault.get_session("github.com")

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()
    context.add_cookies(cookies)
    
    page = context.new_page()
    page.goto("https://github.com/notifications")
    # Already authenticated!
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `agent-auth init` | Initialize encrypted vault |
| `agent-auth add <domain>` | Add session for a domain |
| `agent-auth list` | List stored sessions |
| `agent-auth create-agent <n> --scopes <domains>` | Create scoped agent |
| `agent-auth agents` | List registered agents |

---

## Security

- **AES-256 encryption** with PBKDF2 key derivation (100k iterations)
- **Ed25519 keypairs** for agent identity
- **Scoped access** — agents only access approved domains
- **Audit logging** — every access logged with timestamp
- **SQLite storage** — encrypted database at `~/.agent-auth/vault.db`

---

## Roadmap

- [x] Chrome extension for cookie export
- [x] Encrypted local vault
- [x] Playwright integration
- [x] LangChain integration
- [x] **n8n integration** — [n8n-nodes-agentauth](https://github.com/jacobgadek/n8n-nodes-agentauth)
- [ ] Firefox extension
- [ ] Selenium examples
- [ ] Cloud vault sync

---

## Examples

Working demos available in the [`examples/`](./examples) folder.

### GitHub Agent Demo

**Setup:**

```bash
# 1. Create the agent
agent-auth create-agent github-agent --scopes github.com

# 2. Export cookies from github.com using Chrome extension

# 3. Add the session
agent-auth add github.com
```

**Run:**

```bash
PYTHONPATH=. python examples/github_agent.py
```

---

## Contributing

PRs welcome. Check out the [issues](https://github.com/jacobgadek/agent-auth/issues) for feature requests.

---

## License

MIT

⭐ **Star us if AgentAuth helps your agents authenticate!**

