@openape/apes 0.6.0 → 0.7.1

package/README.md

@@ -0,0 +1,206 @@
+# @openape/apes
+
+The unified OpenApe CLI for interacting with a DDISA Identity Provider — handles authentication, grants, delegations, adapter-based command authorization, and MCP server integration.
+
+Ships three binaries:
+- **`apes`** — main CLI (login, grants, run, admin, etc.)
+- **`ape-shell`** — grant-secured shell wrapper (drop-in replacement for `bash -c`)
+- MCP server mode via `apes mcp`
+
+## Installation
+
+```bash
+pnpm add -g @openape/apes
+# or: npm install -g @openape/apes
+```
+
+After installation you have `apes` and `ape-shell` in your PATH.
+
+## Quick Start
+
+```bash
+# 1. Login to an IdP (opens browser for PKCE flow)
+apes login --idp https://id.example.com
+
+# 2. Check who you are
+apes whoami
+
+# 3. Request a grant and run a command
+apes run -- git status
+# → creates a grant, waits for approval, executes
+
+# 4. List your grants
+apes grants list
+```
+
+## ape-shell: Grant-Secured Shell Wrapper
+
+`ape-shell` is a drop-in shell that routes every command through a DDISA grant. It has two modes:
+
+1. **One-shot mode** (`ape-shell -c "<command>"`) — the historical wrapper. Runs a single command through the grant flow and exits. Used by `$SHELL -c` patterns (e.g. `openclaw tui`, `xargs`, git hooks, sshd non-interactive sessions, etc.).
+2. **Interactive mode** (`ape-shell` with no args, or as a login shell) — a full interactive REPL with a persistent bash backend. Every line the user types is routed through the grant flow **before** bash sees it, and executed in bash's persistent state (so `cd`, `export`, aliases, functions, pipes, TUI apps like `vim`/`less`/`top` all work natively).
+
+### How the one-shot mode works
+
+```
+$SHELL -c "git status"
+  ↓
+ape-shell -c "git status"
+  ↓
+apes run --shell -- bash -c "git status"
+  ↓
+1. Find existing ape-shell session grant (timed/always)
+2. Grant found → execute immediately
+3. No grant → request + wait for human approval → execute
+```
+
+### How the interactive mode works
+
+```
+ape-shell
+  ↓
+┌─ PROMPT ─────────────────────────────────────────┐
+│ apes$ <user types here>                          │
+│   → multi-line detection via `bash -n` dry-parse │
+│   → grant dispatch (adapter or ape-shell session)│
+│   → on approval: write line to persistent bash   │
+│   → stream output, detect prompt marker          │
+└──────────────────────────────────────────────────┘
+```
+
+Every line is audited in `~/.config/apes/audit.jsonl` (session id, line, grant id, exit code).
+
+### Setup for an AI agent session (one-shot mode)
+
+```bash
+# Point the agent's SHELL at ape-shell — each spawned command
+# goes through the one-shot grant flow.
+SHELL=$(which ape-shell) openclaw tui
+```
+
+The first command requests a session grant. After the human approves it (with `grant_type: timed, duration: 8h`), all subsequent commands reuse the same grant without interaction.
+
+### Setup as a login shell (interactive mode)
+
+```bash
+# 1. Register ape-shell as a valid login shell (once per host)
+echo "$(which ape-shell)" | sudo tee -a /etc/shells
+
+# 2. Set it as the login shell for a user (e.g. openclaw)
+sudo chsh -s "$(which ape-shell)" openclaw
+```
+
+After this:
+
+- `ssh openclaw@host` — sshd starts ape-shell as an interactive REPL (sshd passes the login shell with a `-` prefix on argv[0], which ape-shell detects)
+- `ssh openclaw@host "ls"` — sshd invokes `ape-shell -c "ls"`, which still flows through the **one-shot** path (no regression)
+- `su - openclaw` — drops into the interactive REPL
+- Terminal / console login — same as SSH interactive
+
+### Example (one-shot)
+
+```bash
+$ apes login
+$ ape-shell -c "git status"
+ℹ Requesting ape-shell session grant on my-host
+ℹ Grant requested: grant_abc123
+ℹ Waiting for approval...
+# Human approves in browser → command executes
+On branch main
+
+$ ape-shell -c "git log --oneline -5"
+# Grant is reused automatically — no approval prompt
+abc123 Latest commit
+def456 Previous commit
+...
+```
+
+### Example (interactive)
+
+```bash
+$ ape-shell
+apes interactive shell
+Ctrl-D to exit.
+
+apes$ cd /tmp
+# (grant approved, reused for free)
+
+apes$ ls
+# structured adapter grant for `ls` → approve → output
+
+apes$ for i in 1 2 3; do
+>   echo $i
+> done
+# single grant for the whole compound, bash runs it natively
+
+apes$ vim notes.md
+# grant approved → full TUI vim, raw-mode passthrough
+
+apes$ ^D
+Goodbye.
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---|---|
+| `apes login` | PKCE browser login or ed25519 key-based agent login |
+| `apes logout` | Clear stored auth |
+| `apes whoami` | Show current identity |
+| `apes enroll` | Enroll an agent at the IdP |
+| `apes register-user` | Register a new human user |
+
+### Grants
+
+| Command | Description |
+|---|---|
+| `apes grants list` | List all grants |
+| `apes grants inbox` | Show pending approval requests |
+| `apes grants request` | Request a new grant |
+| `apes grants approve <id>` | Approve a grant |
+| `apes grants deny <id>` | Deny a grant |
+| `apes grants revoke <id>` | Revoke an active grant |
+| `apes grants token <id>` | Get the JWT for an approved grant |
+| `apes grants delegate` | Create a delegation grant |
+
+### Execution
+
+| Command | Description |
+|---|---|
+| `apes run -- <cmd>` | Run a command via a shapes adapter grant |
+| `apes run --shell -- bash -c <cmd>` | Shell mode (used by `ape-shell`) |
+| `apes run --as root -- <cmd>` | Elevate via `escapes` (separate binary) |
+| `apes explain -- <cmd>` | Explain what grant a command would need |
+
+### Configuration
+
+Auth and config are stored in `~/.config/apes/`:
+- `auth.json` — access token, email, IdP URL
+- `config.toml` — defaults (idp, agent key path, etc.)
+
+```bash
+apes config get defaults.idp
+apes config set defaults.idp https://id.example.com
+```
+
+## MCP Server
+
+```bash
+apes mcp --transport stdio
+# or
+apes mcp --transport sse --port 3001
+```
+
+Exposes all grant operations as MCP tools so AI agents (Claude Desktop, Cursor, etc.) can request and use grants directly.
+
+## See Also
+
+- [DDISA Protocol](https://github.com/openape-ai/protocol) — the underlying identity and authorization protocol
+- [OpenApe Docs](https://docs.openape.at) — full platform documentation
+- [`escapes`](https://github.com/openape-ai/escapes) — Rust binary for privilege escalation (`apes run --as root`)
+
+## License
+
+MIT © Patrick Hofmann — [Delta Mind GmbH](https://delta-mind.at)

package/dist/auth-lock-SRUFWJC3.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import {
+  CONFIG_DIR
+} from "./chunk-TBYYREL6.js";
+
+// src/auth-lock.ts
+import { open, rm, stat } from "fs/promises";
+import { join } from "path";
+var LOCK_FILE = join(CONFIG_DIR, "auth.json.lock");
+async function acquireAuthLock(opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs ?? 5e3);
+  while (Date.now() < deadline) {
+    try {
+      const handle = await open(LOCK_FILE, "wx");
+      return { handle };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+      try {
+        const s = await stat(LOCK_FILE);
+        if (Date.now() - s.mtimeMs > 3e4)
+          await rm(LOCK_FILE, { force: true });
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  return null;
+}
+async function releaseAuthLock(lock) {
+  try {
+    await lock.handle.close();
+  } finally {
+    await rm(LOCK_FILE, { force: true });
+  }
+}
+export {
+  acquireAuthLock,
+  releaseAuthLock
+};
+//# sourceMappingURL=auth-lock-SRUFWJC3.js.map

package/dist/auth-lock-SRUFWJC3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/auth-lock.ts"],"sourcesContent":["import type { FileHandle } from 'node:fs/promises'\nimport { open, rm, stat } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport { CONFIG_DIR } from './config'\n\nconst LOCK_FILE = join(CONFIG_DIR, 'auth.json.lock')\n\nexport interface AuthLock {\n  handle: FileHandle\n}\n\n/**\n * Best-effort exclusive file lock to serialize concurrent token refreshes\n * between parallel apes / ape-shell invocations. Uses O_CREAT|O_EXCL which\n * is atomic on POSIX. Returns null on timeout so the caller can fall back\n * to \"just re-read auth.json\" (the assumption being that another process\n * successfully refreshed in the meantime).\n *\n * A stale lock older than 30s is considered abandoned (from a crashed\n * process) and is removed so the next acquire can proceed.\n */\nexport async function acquireAuthLock(\n  opts: { timeoutMs?: number } = {},\n): Promise<AuthLock | null> {\n  const deadline = Date.now() + (opts.timeoutMs ?? 5000)\n  while (Date.now() < deadline) {\n    try {\n      const handle = await open(LOCK_FILE, 'wx')\n      return { handle }\n    }\n    catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST')\n        throw err\n      // Stale lock? If the file is older than 30s, remove it and retry.\n      try {\n        const s = await stat(LOCK_FILE)\n        if (Date.now() - s.mtimeMs > 30_000)\n          await rm(LOCK_FILE, { force: true })\n      }\n      catch {\n        // File gone between stat and rm — next iteration will retry the open.\n      }\n      await new Promise(r => setTimeout(r, 100))\n    }\n  }\n  return null\n}\n\nexport async function releaseAuthLock(lock: AuthLock): Promise<void> {\n  try {\n    await lock.handle.close()\n  }\n  finally {\n    await rm(LOCK_FILE, { force: true })\n  }\n}\n"],"mappings":";;;;;;AACA,SAAS,MAAM,IAAI,YAAY;AAC/B,SAAS,YAAY;AAGrB,IAAM,YAAY,KAAK,YAAY,gBAAgB;AAgBnD,eAAsB,gBACpB,OAA+B,CAAC,GACN;AAC1B,QAAM,WAAW,KAAK,IAAI,KAAK,KAAK,aAAa;AACjD,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,WAAW,IAAI;AACzC,aAAO,EAAE,OAAO;AAAA,IAClB,SACO,KAAK;AACV,UAAK,IAA8B,SAAS;AAC1C,cAAM;AAER,UAAI;AACF,cAAM,IAAI,MAAM,KAAK,SAAS;AAC9B,YAAI,KAAK,IAAI,IAAI,EAAE,UAAU;AAC3B,gBAAM,GAAG,WAAW,EAAE,OAAO,KAAK,CAAC;AAAA,MACvC,QACM;AAAA,MAEN;AACA,YAAM,IAAI,QAAQ,OAAK,WAAW,GAAG,GAAG,CAAC;AAAA,IAC3C;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,gBAAgB,MAA+B;AACnE,MAAI;AACF,UAAM,KAAK,OAAO,MAAM;AAAA,EAC1B,UACA;AACE,UAAM,GAAG,WAAW,EAAE,OAAO,KAAK,CAAC;AAAA,EACrC;AACF;","names":[]}