feat: env var key injection for ephemeral environments (#35)

* feat: env var key injection for ephemeral environments (CAPISCIO_AGENT_PRIVATE_KEY_JWK)

Add support for injecting the agent private key via environment variable
for containerised/serverless deployments where ~/.capiscio is ephemeral.

Key priority: env var > local file > generate new via Init RPC.

On first-run identity generation, a capture hint is logged to stderr
with the compact JSON JWK for the operator to persist in their secrets
manager.

- Add _public_jwk_from_private() and _log_agent_key_capture_hint() helpers
- Add ENV_AGENT_PRIVATE_KEY constant
- Rewrite _init_identity() with three-source priority
- Update from_env() docs
- Add 4 unit tests for env var injection and capture hint

* docs: document CAPISCIO_AGENT_PRIVATE_KEY_JWK and ephemeral deployment

- Add env var table to README with CAPISCIO_AGENT_PRIVATE_KEY_JWK
- Add deployment section with capture hint and docker-compose example
- Add Agent Identity Variables section to configuration guide
- Add ephemeral deployment guidance and key rotation instructions

* fix(docs): correct did:key → did:web for production registry usage

The registry assigns did:web when an API key is used. did:key is only
for local dev mode without a registry.

* fix: use importlib to resolve connect module for patch compatibility

The 'import capiscio_sdk.connect as connect_module' statement resolves
to the CapiscIO.connect classmethod rather than the connect submodule
because capiscio_sdk/__init__.py re-exports 'connect'. This causes
patch.object() to fail on Python 3.10+ when trying to patch module-level
functions like _log_agent_key_capture_hint.

Use importlib.import_module() to ensure we get the actual module object.

Author: beonde

README.md

@@ -117,7 +117,7 @@ from capiscio_sdk import CapiscIO
 agent = CapiscIO.connect(api_key="sk_live_...")
 
 # Agent is now ready
-print(agent.did)    # did:key:z6Mk...
+print(agent.did)    # did:web:registry.capisc.io:agents:...
 print(agent.badge)  # Current badge (auto-renewed)
 print(agent.name)   # Agent name
 ```
@@ -171,11 +171,46 @@ agent = CapiscIO.from_env()
 ```
 
 **Environment Variables:**
-- `CAPISCIO_API_KEY` (required) - Your API key
-- `CAPISCIO_AGENT_NAME` - Agent name for lookup/creation
-- `CAPISCIO_AGENT_ID` - Specific agent UUID
-- `CAPISCIO_SERVER_URL` - Registry URL
-- `CAPISCIO_DEV_MODE` - Enable dev mode (`true`/`false`)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CAPISCIO_API_KEY` | Yes | Your API key |
+| `CAPISCIO_AGENT_NAME` | No | Agent name for lookup/creation |
+| `CAPISCIO_AGENT_ID` | No | Specific agent UUID |
+| `CAPISCIO_SERVER_URL` | No | Registry URL (default: production) |
+| `CAPISCIO_DEV_MODE` | No | Enable dev mode (`true`/`false`) |
+| `CAPISCIO_AGENT_PRIVATE_KEY_JWK` | No | JSON-encoded Ed25519 private JWK for ephemeral environments |
+
+### Deploying to Containers / Serverless
+
+In ephemeral environments (Docker, Lambda, Cloud Run) the local `~/.capiscio/` directory
+doesn't survive restarts. On first run the SDK generates a keypair and logs a capture hint:
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  New agent identity generated — save key for persistence         ║
+╚══════════════════════════════════════════════════════════════════╝
+
+  Add to your secrets manager / .env:
+
+    CAPISCIO_AGENT_PRIVATE_KEY_JWK='{"kty":"OKP","crv":"Ed25519","d":"...","x":"...","kid":"did:key:z6Mk..."}'
+```
+
+Copy that value into your secrets manager and set it as an environment variable.
+On subsequent starts the SDK recovers the same DID without generating a new identity.
+
+**Key resolution priority:** env var → local file → generate new.
+
+```yaml
+# docker-compose.yml
+services:
+  my-agent:
+    environment:
+      CAPISCIO_API_KEY: "sk_live_..."
+      CAPISCIO_AGENT_PRIVATE_KEY_JWK: "${AGENT_KEY_JWK}"  # from secrets
+```
+
+See the [Configuration Guide](https://docs.capisc.io/reference/sdk-python/config/) for full deployment examples.
 
 ## 🎯 Agent Card Validation with CoreValidator
 

capiscio_sdk/connect.py

@@ -38,6 +38,41 @@
 PROD_REGISTRY = "https://registry.capisc.io"
 PROD_DASHBOARD = "https://app.capisc.io"
 
+# Env var for injecting the private key in ephemeral environments
+ENV_AGENT_PRIVATE_KEY = "CAPISCIO_AGENT_PRIVATE_KEY_JWK"
+
+
+# =============================================================================
+# Key injection helpers
+# =============================================================================
+
+
+def _public_jwk_from_private(private_jwk: dict) -> dict:
+    """Derive the public JWK from a private JWK (remove 'd' parameter)."""
+    public = {k: v for k, v in private_jwk.items() if k != "d"}
+    return public
+
+
+def _log_agent_key_capture_hint(agent_id: str, private_jwk: dict) -> None:
+    """Log a one-time hint telling the user how to persist key material."""
+    compact_json = json.dumps(private_jwk, separators=(",", ":"))
+    logger.warning(
+        "\n"
+        "  \u2554" + "\u2550" * 62 + "\u2557\n"
+        "  \u2551  New agent identity generated \u2014 save key for persistence   \u2551\n"
+        "  \u255a" + "\u2550" * 62 + "\u255d\n"
+        "\n"
+        "  If this agent runs in an ephemeral environment (containers,\n"
+        "  serverless, CI) the identity will be lost on restart unless\n"
+        "  you persist the private key.\n"
+        "\n"
+        "  Add to your secrets manager / .env:\n"
+        "\n"
+        "    CAPISCIO_AGENT_PRIVATE_KEY_JWK='" + compact_json + "'\n"
+        "\n"
+        "  The DID will be recovered automatically from the JWK on startup.\n"
+    )
+
 
 # =============================================================================
 # Standalone Helper Functions (for testing and direct use)
@@ -278,6 +313,8 @@ def from_env(cls, **kwargs) -> AgentIdentity:
         - CAPISCIO_AGENT_NAME (optional)
         - CAPISCIO_SERVER_URL (optional, default: production)
         - CAPISCIO_DEV_MODE (optional, default: false)
+        - CAPISCIO_AGENT_PRIVATE_KEY_JWK (optional — JSON-encoded Ed25519
+          private JWK for ephemeral environments; printed on first generation)
         """
         api_key = os.environ.get("CAPISCIO_API_KEY")
         if not api_key:
@@ -568,16 +605,44 @@ def _init_identity(self) -> str:
         
         All cryptographic operations are performed by capiscio-core Go library.
         
-        Identity Recovery:
-        - If keys exist locally (private.jwk + public.jwk), we derive the DID
-          from public.jwk's `kid` field (per RFC-002 §6.1: did:key is self-describing)
-        - No did.txt file is required - it's redundant
-        - If server has a did:web assigned, we use that instead
+        Identity Recovery (priority order):
+        - CAPISCIO_AGENT_PRIVATE_KEY_JWK env var (ephemeral / containerised)
+        - Local keys on disk (private.jwk + public.jwk)
+        - Generate new identity via Init RPC (first run)
         """
         private_key_path = self.keys_dir / "private.jwk"
         public_key_path = self.keys_dir / "public.jwk"
-        
-        # Check if we already have keys (for idempotency)
+
+        # ------------------------------------------------------------------
+        # Source 1: Environment variable (highest priority)
+        # ------------------------------------------------------------------
+        env_jwk_raw = os.environ.get(ENV_AGENT_PRIVATE_KEY)
+        if env_jwk_raw:
+            try:
+                private_jwk = json.loads(env_jwk_raw)
+                did = private_jwk.get("kid")
+                if not did or not did.startswith("did:"):
+                    raise ValueError("JWK is missing a valid 'kid' field with a DID")
+
+                logger.info(f"Loaded agent identity from {ENV_AGENT_PRIVATE_KEY}: {did}")
+
+                # Derive public JWK and persist to disk for subsequent restarts
+                public_jwk = _public_jwk_from_private(private_jwk)
+                self.keys_dir.mkdir(parents=True, exist_ok=True)
+                private_key_path.write_text(json.dumps(private_jwk, indent=2))
+                os.chmod(private_key_path, 0o600)
+                public_key_path.write_text(json.dumps(public_jwk, indent=2))
+
+                # Register with server (idempotent)
+                server_did = self._ensure_did_registered(did, public_jwk)
+                return server_did if server_did else did
+
+            except (json.JSONDecodeError, ValueError) as e:
+                logger.error(f"Invalid {ENV_AGENT_PRIVATE_KEY}: {e} — falling through to local keys")
+
+        # ------------------------------------------------------------------
+        # Source 2: Local keys on disk
+        # ------------------------------------------------------------------
         if private_key_path.exists() and public_key_path.exists():
             logger.debug("Found existing keys - recovering identity")
 
@@ -598,8 +663,9 @@ def _init_identity(self) -> str:
             except (json.JSONDecodeError, IOError) as e:
                 logger.warning(f"Failed to read public.jwk: {e} - regenerating")
 
-        # No valid keys exist - generate new identity via Init RPC
-        # Connect to capiscio-core gRPC
+        # ------------------------------------------------------------------
+        # Source 3: Generate new identity via Init RPC (first run)
+        # ------------------------------------------------------------------
         if not self._rpc_client:
             self._rpc_client = CapiscioRPCClient()
             self._rpc_client.connect()
@@ -625,7 +691,15 @@ def _init_identity(self) -> str:
         logger.info(f"Identity initialized: {did}")
         if result.get("registered"):
             logger.info("DID registered with server")
-        
+
+        # Log capture hint for ephemeral environments
+        if private_key_path.exists():
+            try:
+                private_jwk = json.loads(private_key_path.read_text())
+                _log_agent_key_capture_hint(self.agent_id, private_jwk)
+            except Exception:
+                pass  # Best-effort hint
+
         return did
 
     def _ensure_did_registered(self, did: str, public_jwk: dict) -> Optional[str]:

docs/guides/configuration.md

@@ -631,6 +631,8 @@ os.environ['CAPISCIO_BINARY'] = '/opt/capiscio/v2.4.0/capiscio-core'
 services:
   agent:
     environment:
+      - CAPISCIO_API_KEY=sk_live_...
+      - CAPISCIO_AGENT_PRIVATE_KEY_JWK=${AGENT_KEY_JWK}
       - CAPISCIO_FAIL_MODE=block
       - CAPISCIO_RATE_LIMITING=true
       - CAPISCIO_RATE_LIMIT_RPM=120
@@ -650,8 +652,61 @@ data:
   CAPISCIO_RATE_LIMITING: "true"
   CAPISCIO_RATE_LIMIT_RPM: "200"
   CAPISCIO_TIMEOUT_MS: "5000"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: capiscio-identity
+type: Opaque
+stringData:
+  api-key: "sk_live_..."
+  agent-private-key-jwk: '{"kty":"OKP","crv":"Ed25519","d":"...","x":"...","kid":"did:key:z6Mk..."}'
+```
+
+### Agent Identity Variables (CapiscIO.connect)
+
+These variables are used by `CapiscIO.connect()` and `CapiscIO.from_env()` for agent identity management:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CAPISCIO_API_KEY` | Yes | Registry API key |
+| `CAPISCIO_AGENT_NAME` | No | Agent name for lookup/creation |
+| `CAPISCIO_AGENT_ID` | No | Specific agent UUID |
+| `CAPISCIO_SERVER_URL` | No | Registry URL (default: `https://registry.capisc.io`) |
+| `CAPISCIO_DEV_MODE` | No | Enable dev mode (`true`/`false`) |
+| `CAPISCIO_AGENT_PRIVATE_KEY_JWK` | No | JSON-encoded Ed25519 private JWK for ephemeral environments |
+
+#### Ephemeral Environment Key Injection
+
+In ephemeral environments (Docker, Lambda, Cloud Run) the local `~/.capiscio/` directory doesn't survive restarts. Set `CAPISCIO_AGENT_PRIVATE_KEY_JWK` to inject the agent's Ed25519 private key from your secrets manager.
+
+**Key resolution priority:**
+
+| Priority | Source | When Used |
+|----------|--------|-----------|
+| 1 | `CAPISCIO_AGENT_PRIVATE_KEY_JWK` env var | Containers, serverless, CI |
+| 2 | Local key file (`~/.capiscio/keys/{agent_id}/private.jwk`) | Persistent environments |
+| 3 | Generate new via capiscio-core Init RPC | First run only |
+
+**First-run capture:** On the very first run, the SDK logs a capture hint to stderr with the full JWK. Copy it into your secrets manager:
+
+```
+CAPISCIO_AGENT_PRIVATE_KEY_JWK='{"kty":"OKP","crv":"Ed25519","d":"...","x":"...","kid":"did:key:z6Mk..."}'
 ```
 
+!!! warning "DID Changes on New Key Generation"
+    If neither the env var nor local files are available, the SDK generates a **new** keypair with a **different** DID. Any badges issued to the old DID will no longer be valid. Always persist the key in ephemeral environments.
+
+#### Key Rotation
+
+To rotate the agent identity:
+
+1. Unset `CAPISCIO_AGENT_PRIVATE_KEY_JWK`
+2. Remove local key files (`~/.capiscio/keys/{agent_id}/`)
+3. Restart the agent — a new keypair and DID will be generated
+4. Capture the new JWK from the log hint
+5. Store the new key in your secrets manager
+
 ---
 
 ## Middleware Observability (Auto-Events)