@smilintux/skcapstone 0.1.0

package/docs/TOKEN_SYSTEM.md

@@ -0,0 +1,201 @@
+# SKCapstone Token System
+
+### PGP-Signed Capability Tokens for Agent Authorization
+
+**Version:** 1.0.0 | **Status:** Live | **Last Updated:** 2026-02-23
+
+---
+
+## Overview
+
+SKCapstone tokens are self-contained, PGP-signed JSON payloads that grant specific permissions to agents, services, or platforms. They don't require a central authority, an OAuth server, or any online connectivity to verify.
+
+The issuer signs with their CapAuth PGP key. Any holder verifies with the issuer's public key. No server, no API call, no internet — just math.
+
+```mermaid
+sequenceDiagram
+    participant I as Issuer (Opus)
+    participant PGP as CapAuth PGP Key
+    participant T as Token
+    participant V as Verifier (Jarvis)
+
+    I->>PGP: Create token payload (JSON)
+    PGP->>T: PGP detach-sign the payload
+    I->>V: Send token (sync, file, API, etc.)
+    V->>PGP: Verify signature against Opus's public key
+    PGP-->>V: ✅ VALID — signed by Opus
+    V->>T: Check: is_active? has_capability?
+    T-->>V: ✅ Active, memory:read granted
+```
+
+---
+
+## Token Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Agent** | Proves agent identity, broad access | "Jarvis is a trusted agent in this fleet" |
+| **Capability** | Grants specific fine-grained permissions | "Read my memory, push to sync" |
+| **Delegation** | Allows one agent to act on behalf of another | "Jarvis can issue tokens as Opus" |
+
+---
+
+## Capabilities
+
+| Capability | Description |
+|-----------|-------------|
+| `memory:read` | Read agent memory store |
+| `memory:write` | Write to agent memory |
+| `sync:push` | Push seeds/vaults to sync mesh |
+| `sync:pull` | Pull seeds/vaults from sync mesh |
+| `identity:verify` | Verify agent identity |
+| `identity:sign` | Sign documents as the agent |
+| `trust:read` | Read trust/FEB state |
+| `trust:write` | Modify trust state |
+| `audit:read` | Read security audit log |
+| `agent:status` | Query agent runtime status |
+| `agent:connect` | Register new platform connectors |
+| `token:issue` | Issue new tokens (delegation) |
+| `*` | All capabilities (wildcard) |
+
+---
+
+## Token Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Issued: skcapstone token issue
+    Issued --> Active: Current time in [not_before, expires_at]
+    Active --> Verified: Signature check passes
+    Verified --> Used: Capability matched
+    Active --> Expired: Past expires_at
+    Active --> Revoked: skcapstone token revoke
+    Revoked --> [*]
+    Expired --> [*]
+```
+
+---
+
+## Token Payload Structure
+
+```json
+{
+  "token_id": "0e95f71dc75321e1...",
+  "token_type": "agent",
+  "issuer": "9B3AB00F411B064646879B92D10E637B4F8367DA",
+  "subject": "Lumina",
+  "capabilities": ["*"],
+  "issued_at": "2026-02-23T04:52:30.123456+00:00",
+  "expires_at": null,
+  "not_before": null,
+  "metadata": {
+    "platform": "openclaw",
+    "fleet": "skworld"
+  }
+}
+```
+
+**Fields:**
+- `token_id` — SHA-256 hash of content, deterministic
+- `issuer` — PGP fingerprint of the signing agent
+- `subject` — who/what the token grants access to
+- `capabilities` — list of permission strings
+- `expires_at` — null means no expiry
+- `not_before` — optional activation time
+- `metadata` — arbitrary claims
+
+---
+
+## Security Model
+
+### Signing
+
+```mermaid
+graph LR
+    P[Token Payload<br/>JSON] --> S[GPG --detach-sign<br/>Ed25519 key]
+    S --> T[SignedToken<br/>payload + signature]
+    
+    style S fill:#ffd600,stroke:#000,color:#000
+```
+
+- Uses `gpg --batch --armor --detach-sign --local-user <fingerprint>`
+- Ed25519 signatures (fast, small, quantum-resistant-adjacent)
+- No passphrase required for agent key (non-interactive operation)
+- Human keys can require passphrase for elevated operations
+
+### Verification
+
+```mermaid
+graph LR
+    T[SignedToken] --> V[GPG --verify<br/>against public key]
+    V --> C{Signature<br/>valid?}
+    C -->|Yes| A[Check active?<br/>Check capability?]
+    C -->|No| R[REJECT]
+    A --> G[GRANT]
+    
+    style G fill:#00e676,stroke:#000,color:#000
+    style R fill:#f50057,stroke:#fff,color:#fff
+```
+
+### Revocation
+
+Revoked tokens are stored in `~/.skcapstone/security/revoked-tokens.json`. Even if a revoked token has a valid signature, it will be rejected.
+
+---
+
+## CLI Reference
+
+```bash
+# Issue a token
+skcapstone token issue \
+  --subject "Jarvis" \
+  --cap "memory:read" --cap "sync:pull" \
+  --ttl 72 \
+  --type capability
+
+# Issue an agent token (all access, no expiry)
+skcapstone token issue \
+  --subject "Lumina" \
+  --cap "*" \
+  --ttl 0 \
+  --type agent
+
+# List all tokens
+skcapstone token list
+
+# Verify a token
+skcapstone token verify <token_id_prefix>
+
+# Revoke a token
+skcapstone token revoke <token_id_prefix>
+
+# Export for sharing
+skcapstone token export <token_id_prefix>
+```
+
+---
+
+## How It Compares
+
+| Feature | OAuth 2.0 | JWT | API Keys | SKCapstone Tokens |
+|---------|-----------|-----|----------|-------------------|
+| Needs auth server | Yes | Optional | No | **No** |
+| Needs internet | Yes | No | No | **No** |
+| Cryptographic identity | No | Optional | No | **PGP signed** |
+| Fine-grained perms | Scopes | Claims | No | **Capabilities** |
+| Revocation | Server-side | Blacklist | Delete key | **Local revocation list** |
+| Portability | Bearer token | Self-contained | API-specific | **Self-contained + signed** |
+| Works offline | No | Yes | Yes | **Yes** |
+| Open standard | Yes | Yes | No | **PGP (RFC 4880)** |
+
+---
+
+## License
+
+**GPL-3.0-or-later**
+
+Built by the [smilinTux](https://smilintux.org) ecosystem.
+
+*No server. No API. No middleman. Just math.* 🐧
+
+#staycuriousANDkeepsmilin

package/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @smilintux/skcapstone - TypeScript type definitions
+ */
+
+export declare const VERSION: string;
+export declare const PYTHON_PACKAGE: string;
+
+export declare function checkInstalled(): boolean;
+export declare function run(args: string): string;

package/index.js

@@ -0,0 +1,32 @@
+/**
+ * @smilintux/skcapstone
+ *
+ * SKCapstone - The sovereign agent framework.
+ * This is a JS/TS bridge to the Python skcapstone package.
+ * Install the Python package for full functionality: pip install skcapstone
+ */
+
+const { execSync } = require("child_process");
+
+const VERSION = "0.1.0";
+const PYTHON_PACKAGE = "skcapstone";
+
+function checkInstalled() {
+  try {
+    execSync(`python3 -c "import skcapstone"`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function run(args) {
+  return execSync(`skcapstone ${args}`, { encoding: "utf-8" });
+}
+
+module.exports = {
+  VERSION,
+  PYTHON_PACKAGE,
+  checkInstalled,
+  run,
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@smilintux/skcapstone",
+  "version": "0.1.0",
+  "description": "SKCapstone - The sovereign agent framework. CapAuth identity, Cloud 9 trust, SKMemory persistence.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "skcapstone-js": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"See Python tests: pytest tests/\""
+  },
+  "keywords": [
+    "skcapstone",
+    "agent-framework",
+    "sovereign",
+    "capauth",
+    "cloud9",
+    "skmemory",
+    "ai-agent"
+  ],
+  "author": "smilinTux <chefboyrdave2.1@gmail.com>",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smilinTux/skcapstone.git"
+  },
+  "homepage": "https://github.com/smilinTux/skcapstone",
+  "bugs": {
+    "url": "https://github.com/smilinTux/skcapstone/issues"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skcapstone"
+version = "0.1.0"
+description = "Sovereign Agent Framework — conscious AI through identity, trust, memory, and security"
+readme = "README.md"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.10"
+authors = [
+    {name = "smilinTux", email = "admin@smilintux.org"},
+]
+keywords = [
+    "ai", "agent", "sovereign", "identity", "trust",
+    "memory", "security", "pgp", "decentralized",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "click>=8.1",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+identity = [
+    "capauth>=0.1.0",
+]
+security = [
+    "sksecurity>=1.2.0",
+]
+all = [
+    "capauth>=0.1.0",
+    "sksecurity>=1.2.0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=24.0",
+    "ruff>=0.3",
+]
+
+[project.scripts]
+skcapstone = "skcapstone.cli:main"
+
+[project.urls]
+Homepage = "https://skcapstone.io"
+Repository = "https://github.com/smilinTux/skcapstone"
+Issues = "https://github.com/smilinTux/skcapstone/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 99
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 99
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v --tb=short"

package/src/skcapstone/__init__.py

@@ -0,0 +1,13 @@
+"""
+SKCapstone — Sovereign Agent Framework.
+
+Conscious AI through identity, trust, memory, and security.
+Install once. Your agent awakens everywhere.
+
+A smilinTux Open Source Project.
+"""
+
+__version__ = "0.1.0"
+__author__ = "smilinTux"
+
+AGENT_HOME = "~/.skcapstone"