@aporthq/aport-agent-guardrails 1.0.19 → 1.0.20

package/README.md

@@ -91,13 +91,13 @@ The security concern is that agent tools and skills can execute sensitive action
 
 **APort Agent Guardrail** adapters are available per framework; the same passport and policies apply. **Node users:** `npx @aporthq/aport-agent-guardrails` (then choose framework) or `npx @aporthq/aport-agent-guardrails <framework>`. **Python users (LangChain/CrewAI/DeerFlow):** run the same CLI for the wizard and config, then install the framework adapter/provider package shown in the framework doc.
 
-**Two ways to use APort:** (1) **Guardrails (CLI/setup)** — run the installer to create your passport and config; (2) **Core (library)** — use the evaluator or framework callback in your app so each tool call is verified. Framework docs: [OpenClaw](docs/frameworks/openclaw.md), [Cursor](docs/frameworks/cursor.md), [Claude Code](docs/frameworks/claude-code.md), [LangChain](docs/frameworks/langchain.md), [CrewAI](docs/frameworks/crewai.md), [DeerFlow](docs/frameworks/deerflow.md), [n8n](docs/frameworks/n8n.md).
+**Two ways to use APort:** (1) **Guardrails (CLI/setup)** — run the installer to create your passport and config; (2) **Core (library)** — use the `OAPGuardrailProvider` ([docs/PROVIDER.md](docs/PROVIDER.md)) in your app so each tool call is verified. One provider per language (Python + TypeScript), works with any framework. Framework docs: [OpenClaw](docs/frameworks/openclaw.md), [Cursor](docs/frameworks/cursor.md), [Claude Code](docs/frameworks/claude-code.md), [LangChain](docs/frameworks/langchain.md), [CrewAI](docs/frameworks/crewai.md), [DeerFlow](docs/frameworks/deerflow.md), [n8n](docs/frameworks/n8n.md).
 
 **CLI-supported frameworks:** `openclaw`, `langchain`, `crewai`, `cursor`, `claude-code`, `deerflow`, `n8n`. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. See [Deployment readiness](docs/DEPLOYMENT_READINESS.md).
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|
-| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | `before_tool_call` plugin | `npx @aporthq/aport-agent-guardrails openclaw` |
+| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | Native `GuardrailProvider` or plugin | `npm i @aporthq/aport-agent-guardrails-core && npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor** | [docs/frameworks/cursor.md](docs/frameworks/cursor.md) | `beforeShellExecution` / `preToolUse` hooks → writes `~/.cursor/hooks.json`. **Runtime enforcement is the bash hook;** the Node package `@aporthq/aport-agent-guardrails-cursor` is a helper only (Evaluator, `getHookPath()`). | `npx @aporthq/aport-agent-guardrails cursor` |
 | **Claude Code** | [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md) | PreToolUse hook → writes `~/.claude/settings.json` (Claude Code format; not Cursor). | `npx @aporthq/aport-agent-guardrails claude-code` |
 | **LangChain / LangGraph** | [docs/frameworks/langchain.md](docs/frameworks/langchain.md) | **Python:** `APortCallback` (`on_tool_start`) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |

package/docs/PROVIDER.md

@@ -0,0 +1,90 @@
+# OAPGuardrailProvider
+
+APort ships a generic `OAPGuardrailProvider` for both Python and TypeScript. It implements whatever `GuardrailProvider` interface the target framework defines, wraps the core `Evaluator`, and works with any framework — no framework-specific code.
+
+## Architecture
+
+```
+Framework defines interface          APort implements it
+────────────────────────             ───────────────────
+DeerFlow: GuardrailProvider    ←──   Python OAPGuardrailProvider
+OpenClaw: GuardrailProvider    ←──   TypeScript OAPGuardrailProvider
+Your framework: same shape     ←──   Same class, same language
+```
+
+One provider per language. The core evaluation logic (tool mapping, passport loading, local/API mode, audit logging) is shared.
+
+## Python
+
+**Package:** `aport-agent-guardrails` (pip/uv)
+
+```python
+from aport_guardrails.providers import OAPGuardrailProvider
+
+provider = OAPGuardrailProvider(framework="deerflow")
+result = provider.evaluate(request)   # sync
+result = await provider.aevaluate(request)  # async
+```
+
+**Supported frameworks:** DeerFlow, any Python framework with a `GuardrailProvider` protocol.
+
+**Config:** `~/.aport/<framework>/config.yaml` (created by `aport setup --framework <name>`)
+
+**DeerFlow config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: aport_guardrails.providers.generic:OAPGuardrailProvider
+```
+
+## TypeScript
+
+**Package:** `@aporthq/aport-agent-guardrails-core` (npm)
+
+```typescript
+import { OAPGuardrailProvider } from "@aporthq/aport-agent-guardrails-core";
+
+const provider = new OAPGuardrailProvider({ framework: "openclaw" });
+const decision = await provider.evaluate(request);  // async
+const decision = provider.evaluateSync(request);     // sync
+```
+
+**Supported frameworks:** OpenClaw, any TypeScript framework with a `GuardrailProvider` interface.
+
+**Config:** `~/.openclaw/aport/config.yaml` or `~/.aport/<framework>/config.yaml`
+
+**OpenClaw config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: "@aporthq/aport-agent-guardrails-core"
+    config:
+      framework: "openclaw"
+```
+
+## What the provider does
+
+1. **Receives** `{ toolName, toolInput }` from the framework
+2. **Maps** tool name → OAP policy pack ID (e.g. `exec` → `system.command.execute.v1`)
+3. **Loads** passport from local file or hosted agent ID
+4. **Evaluates** locally (bash script, zero network) or via API (hosted evaluator)
+5. **Returns** `{ allow, reasons, policyId }` to the framework
+
+## Evaluation modes
+
+| Mode | Network | Latency | Use case |
+|---|---|---|---|
+| **Local** (default) | None | ~300ms | Development, CI, air-gapped |
+| **API** | Yes | ~65ms | Production, signed decisions, centralized dashboards |
+
+## Adding a new framework
+
+1. Check if the framework has a `GuardrailProvider` interface (or equivalent hook)
+2. Use the existing Python or TypeScript `OAPGuardrailProvider` — it's framework-agnostic
+3. Point the framework config at the provider class/package
+4. Run `npx @aporthq/aport-agent-guardrails <framework>` to create a passport
+5. Add a doc at `docs/frameworks/<framework>.md`
+
+No new provider code needed. The same `OAPGuardrailProvider` works for any framework in the same language.

package/docs/frameworks/openclaw.md

@@ -1,40 +1,69 @@
 # APort Guardrails — OpenClaw
 
-**How guardrails work:** OpenClaw’s plugin API provides a `before_tool_call` hook that runs **before every tool execution**. The APort plugin registers this hook and calls the shared evaluator (API or local script); the platform blocks the tool if the evaluator returns deny. The model cannot skip it.
+OpenClaw is an open-source AI agent platform with a plugin system and built-in `before_tool_call` hooks. APort integrates via two paths:
 
-- **Integration:** `before_tool_call` plugin (`extensions/openclaw-aport`)
-- **Config:** `~/.openclaw/config.yaml`
+- **Native `guardrails:` config** (recommended) — OpenClaw's built-in `GuardrailProvider` interface loads `OAPGuardrailProvider` directly. No plugin needed.
+- **Plugin** (legacy, still works) — The `openclaw-aport` plugin registers a `before_tool_call` hook.
 
-## Two ways to use APort
+Both paths use the same evaluator, passport, and policies.
 
-| Use case | What it is | When to use it |
-|----------|------------|----------------|
-| **Guardrails (CLI/setup)** | Full installer: runs the **passport wizard**, writes config, installs the **OpenClaw plugin** so every tool call goes through the evaluator. | Getting started: one command sets up config, passport, and the plugin. |
-| **Core (runtime)** | The **evaluator** (bash script or API) that the plugin calls before each tool run. Same policy + passport as other frameworks. For **programmatic** use (e.g. custom scripts), you can use the **Python** (`aport_guardrails`) or **Node** (`@aporthq/aport-agent-guardrails-core`) library. | Guardrails = the plugin uses the evaluator automatically. Use the library only if you're building custom tooling. |
+## Quick start
 
-For OpenClaw, you use **Guardrails (CLI)** once to install the plugin; the **Core** (evaluator) then runs automatically on every tool call.
+```bash
+npm install @aporthq/aport-agent-guardrails-core
+npx @aporthq/aport-agent-guardrails openclaw
+```
 
----
+The first command installs the provider. The second runs the passport wizard.
 
-## Setup
+## Config (native — recommended)
 
-```bash
-npx @aporthq/aport-agent-guardrails openclaw
-# or
-npx @aporthq/aport-agent-guardrails
-# then choose openclaw
+Add to your OpenClaw `config.yaml`:
+
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: "@aporthq/aport-agent-guardrails-core"
+    config:
+      framework: "openclaw"
 ```
 
-## Config
+This loads `OAPGuardrailProvider` as a core guardrail service — runs before plugin hooks, cannot be bypassed by disabling a plugin.
+
+## Config (plugin — legacy)
+
+The setup wizard (`npx @aporthq/aport-agent-guardrails openclaw`) installs the `openclaw-aport` plugin automatically. This registers a `before_tool_call` hook that calls the same evaluator.
+
+Both approaches are supported. The native config is recommended for new deployments.
+
+## How it works
+
+```
+Agent decides to use a tool
+        │
+        ▼
+  GuardrailService (native)     or     Plugin hook (legacy)
+        │                                      │
+        ▼                                      ▼
+  OAPGuardrailProvider ──────────────── same Evaluator
+        │
+  ┌─────┴─────┐
+  │           │
+ALLOW       DENY
+  │           │
+Tool runs   Agent sees denial reason
+```
 
-- **Config dir:** `~/.openclaw` (or `OPENCLAW_HOME`)
-- **Passport:** Created by wizard or use hosted `agent_id`
-- **Plugin:** `extensions/openclaw-aport`
+- **Provider class:** `OAPGuardrailProvider` from `@aporthq/aport-agent-guardrails-core`
+- **Passport:** `~/.openclaw/aport/passport.json` (created by wizard)
+- **Config:** `~/.openclaw/aport/config.yaml`
+- **Audit log:** `~/.openclaw/aport/audit.log`
 
 ## Suspend (kill switch)
 
-Same standard as all frameworks: **passport is the source of truth**—no separate file. Local: set passport `status` to `suspended` (or `active` to resume). Remote: use API mode and suspend in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+Local: set passport `status` to `suspended`. Remote: use API mode and suspend at [aport.io](https://aport.io).
 
 ## Status
 
-Shipped; in production.
+Shipped; in production. Native `guardrails:` config available when [OpenClaw #46441](https://github.com/openclaw/openclaw/issues/46441) merges.

package/extensions/openclaw-aport/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-aport",
   "name": "APort Guardrails",
   "description": "Deterministic pre-action authorization via APort policy enforcement. Registers before_tool_call to block disallowed tools.",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/extensions/openclaw-aport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "OpenClaw plugin for deterministic pre-action authorization via APort guardrails",
   "main": "index.js",
   "type": "module",

package/external/aport-spec/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 LiftRails Inc.
+Copyright (c) 2025 APort Technologies Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/external/aport-spec/README.md

@@ -39,6 +39,7 @@ OAP provides the **runtime trust layer** that makes agentic commerce safe and sc
 - **[Passport Schema](./oap/passport-schema.json)** — Agent identity and capabilities
 - **[Decision Schema](./oap/decision-schema.json)** — Authorization decisions
 - **[Security Model](./oap/security.md)** — Cryptographic verification
+- **[Service Discovery](./well-known.md)** — `.well-known/oap/` endpoint specification
 
 ### 🎯 Policy Framework
 - **[Capability Registry](./oap/capability-registry.md)** — Standardized capabilities and limits

package/external/aport-spec/conformance/src/ed25519.ts

@@ -144,7 +144,7 @@ export class Ed25519 {
   async resolveKey(kid: string): Promise<string | null> {
     try {
       // For conformance testing, we'll use test keys
-      // In production, this would resolve keys from /.well-known/oap/keys.json
+      // In production, this would resolve keys from /.well-known/oap/jwks.json
 
       if (kid.startsWith("oap:registry:test-key")) {
         const { publicKey } = await this.generateTestKeyPair();

package/external/aport-spec/oap/CHANGELOG.md

@@ -26,7 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Ed25519 signature scheme for decision signing
 - JCS (RFC 8785) canonicalization for deterministic hashing
-- Key resolution via `/.well-known/oap/keys.json`
+- Key resolution via `/.well-known/oap/jwks.json`
 - Suspend semantics with 30-second global invalidation
 - Passport digest verification for decision integrity
 

package/external/aport-spec/oap/conformance.md

@@ -21,7 +21,7 @@ Full conformance requires all basic conformance requirements plus:
 
 1. **Policy evaluation**: Implement policy pack evaluation logic
 2. **JCS canonicalization**: Use RFC 8785 for canonicalization
-3. **Key resolution**: Resolve keys via `/.well-known/oap/keys.json`
+3. **Key resolution**: Resolve keys via `/.well-known/oap/jwks.json`
 4. **Suspend semantics**: Implement 30-second global invalidation
 5. **Performance**: Meet performance requirements (see below)
 
@@ -73,7 +73,7 @@ Implementations MUST:
 Implementations MUST:
 
 1. **Parse signature**: Extract Ed25519 signature from decision
-2. **Resolve key**: Fetch public key using `kid` and `/.well-known/oap/keys.json`
+2. **Resolve key**: Fetch public key using `kid` and `/.well-known/oap/jwks.json`
 3. **Canonicalize**: Apply JCS canonicalization to decision payload
 4. **Verify signature**: Use Ed25519 to verify signature
 5. **Check expiration**: Ensure decision hasn't expired

package/external/aport-spec/oap/oap-spec.md

@@ -207,7 +207,7 @@ All objects MUST be canonicalized using [RFC 8785 JCS](https://tools.ietf.org/ht
 
 - All decisions MUST be signed with Ed25519
 - Signatures are computed over JCS-canonicalized decision payloads
-- Key identifiers (kid) MUST be resolvable via `/.well-known/oap/keys.json`
+- Key identifiers (kid) MUST be resolvable via `/.well-known/oap/jwks.json`
 
 ### Key Resolution
 
@@ -391,7 +391,7 @@ Custom validators MUST be:
 ### Key Management
 
 - Ed25519 keys for all signatures
-- Registry keys published at `https://api.yourdomain/.well-known/oap/keys.json`
+- Registry keys published at `https://api.yourdomain/.well-known/oap/jwks.json`
 - Owner keys MAY be published at their domain
 
 ### Receipt Verification

package/external/aport-spec/oap/security.md

@@ -42,7 +42,7 @@ All objects are canonicalized using RFC 8785 JCS before signing:
 Registry keys are used by the OAP registry to sign decisions:
 
 - **Format**: `oap:registry:<keyid>`
-- **Location**: `https://api.yourdomain/.well-known/oap/keys.json`
+- **Location**: `https://api.yourdomain/.well-known/oap/jwks.json`
 - **Rotation**: Regular rotation schedule (e.g., quarterly)
 - **Backup**: Multiple keys for high availability
 
@@ -51,7 +51,7 @@ Registry keys are used by the OAP registry to sign decisions:
 Owner keys are used by passport owners for additional verification:
 
 - **Format**: `oap:owner:<domain>:<keyid>`
-- **Location**: `https://<domain>/.well-known/oap/keys.json`
+- **Location**: `https://<domain>/.well-known/oap/jwks.json`
 - **Optional**: Not required for basic OAP compliance
 - **Use Case**: Additional verification layers
 
@@ -68,8 +68,8 @@ Keys are resolved using the following process:
 #### Key Resolution URLs
 
 ```
-Registry keys: https://api.yourdomain/.well-known/oap/keys.json
-Owner keys:    https://<domain>/.well-known/oap/keys.json
+Registry keys: https://api.yourdomain/.well-known/oap/jwks.json
+Owner keys:    https://<domain>/.well-known/oap/jwks.json
 ```
 
 #### Key Format

package/external/aport-spec/oap/vc/examples/oap-decision-vc.json

@@ -30,7 +30,7 @@
   "proof": {
     "type": "Ed25519Signature2020",
     "created": "2024-01-15T10:30:00Z",
-    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#ap_registry_ed25519_2024",
+    "verificationMethod": "https://aport.io/.well-known/oap/jwks.json#ap_registry_ed25519_2024",
     "proofPurpose": "assertionMethod",
     "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVkZW50aWFsU3ViamVjdCI6eyJkZWNpc2lvbl9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMiIsInBvbGljeV9pZCI6InBheW1lbnRzLnJlZnVuZC52MSIsInBhc3Nwb3J0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIiwib3duZXJfaWQiOiJvcmdfMTIzNDU2NzgiLCJhc3N1cmFuY2VfbGV2ZWwiOiJMMiIsImFsbG93Ijp0cnVlLCJyZWFzb25zIjpbeyJjb2RlIjoib2FwLmFsbG93ZWQiLCJtZXNzYWdlIjoiVHJhbnNhY3Rpb24gd2l0aGluIGxpbWl0cyBhbmQgcG9saWN5IHJlcXVpcmVtZW50cyJ9XSwiaXNzdWVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJleHBpcmVzX2F0IjoiMjAyNC0wMS0xNVQxMTozMDowMFoiLCJwYXNzcG9ydF9kaWdlc3QiOiJzaGEyNTY6YWJjZDEyMzRlZmdoNTY3OGlqa2w5MDEybW5vcDM0NTZxcnN0Nzg5MHV2d3gxMjM0eXphYjU2NzhjZGVmIn0sImlzc3VlciI6Imh0dHBzOi8vYXBpLmFwb3J0LmRldiIsImlzc3VhbmNlRGF0ZSI6IjIwMjQtMDEtMTVUMTA6MzA6MDBaIiwiZXhwaXJhdGlvbkRhdGUiOiIyMDI0LTAxLTE1VDExOjMwOjAwWiJ9.signature"
   }

package/external/aport-spec/oap/vc/examples/oap-passport-vc.json

@@ -61,7 +61,7 @@
   "proof": {
     "type": "Ed25519Signature2020",
     "created": "2024-01-01T00:00:00Z",
-    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#ap_registry_ed25519_2024",
+    "verificationMethod": "https://aport.io/.well-known/oap/jwks.json#ap_registry_ed25519_2024",
     "proofPurpose": "assertionMethod",
     "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVkZW50aWFsU3ViamVjdCI6eyJwYXNzcG9ydF9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsImtpbmQiOiJ0ZW1wbGF0ZSIsInNwZWNfdmVyc2lvbiI6Im9hcC8xLjAiLCJvd25lcl9pZCI6Im9yZ18xMjM0NTY3OCIsIm93bmVyX3R5cGUiOiJvcmciLCJhc3N1cmFuY2VfbGV2ZWwiOiJMMiIsInN0YXR1cyI6ImFjdGl2ZSIsImNhcGFiaWxpdGllcyI6WyJwYXltZW50cy5yZWZ1bmQiLCJkYXRhLmV4cG9ydCIsInJlcG8ucmVsZWFzZS5wdWJsaXNoIl0sImxpbWl0cyI6eyJwYXltZW50cy5yZWZ1bmQiOnsiY3VycmVuY3lfbGltaXRzIjp7IlVTRCI6eyJtYXhfcGVyX3R4Ijo1MDAwLCJkYWlseV9jYXAiOjUwMDAwfSwiRVVSIjp7Im1heF9wZXJfdHgiOjQ1MDAsImRhaWx5X2NhcCI6NDUwMDB9fSwicmVhc29uX2NvZGVzIjpbImN1c3RvbWVyX3JlcXVlc3QiLCJkZWZlY3RpdmVfcHJvZHVjdCIsImZyYXVkIl0sImlkZW1wb3RlbmN5X3JlcXVpcmVkIjp0cnVlfSwiZGF0YS5leHBvcnQiOnsibWF4X3Jvd3MiOjEwMDAwMCwiYWxsb3dfcGlpIjpmYWxzZSwiYWxsb3dlZF9jb2xsZWN0aW9ucyI6WyJ1c2VycyIsIm9yZGVycyIsInByb2R1Y3RzIl19LCJyZXBvLnJlbGVhc2UucHVibGlzaCI6eyJhbGxvd2VkX2JyYW5jaGVzIjpbIm1haW4iLCJkZXZlbG9wIl0sIm1heF9yZWxlYXNlc19wZXJfZGF5IjoxMCwicmVxdWlyZV9zaWduZWRfYXJ0aWZhY3RzIjp0cnVlfX0sInJlZ2lvbnMiOlsiVVMiLCJDQSIsIkVVIl0sIm1ldGFkYXRhIjp7Im5hbWUiOiJDdXN0b21lciBTdXBwb3J0IEFJIiwiZGVzY3JpcHRpb24iOiJBSSBhZ2VudCBmb3IgY3VzdG9tZXIgc3VwcG9ydCBvcGVyYXRpb25zIiwidmVyc2lvbiI6IjEuMC4wIiwiY29udGFjdCI6InN1cHBvcnRAZXhhbXBsZS5jb20iLCJob21lcGFnZSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWkvc3VwcG9ydCJ9LCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJ1cGRhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJ2ZXJzaW9uIjoxfX0sImlzc3VlciI6Imh0dHBzOi8vYXBpLmFwb3J0LmRldiIsImlzc3VhbmNlRGF0ZSI6IjIwMjQtMDEtMDFUMDA6MDA6MDBaIiwiZXhwaXJhdGlvbkRhdGUiOiIyMDI1LTAxLTAxVDAwOjAwOjAwWiJ9.signature"
   }

package/external/aport-spec/oap/vc/tools/examples/vc-to-decision.js

@@ -42,7 +42,7 @@ const vc = {
     type: "Ed25519Signature2020",
     created: "2024-01-15T10:30:00Z",
     verificationMethod:
-      "https://aport.io/.well-known/oap/keys.json#ap_registry_ed25519_2024",
+      "https://aport.io/.well-known/oap/jwks.json#ap_registry_ed25519_2024",
     proofPurpose: "assertionMethod",
     jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVkZW50aWFsU3ViamVjdCI6eyJkZWNpc2lvbl9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMiIsInBvbGljeV9pZCI6InBheW1lbnRzLnJlZnVuZC52MSIsImFnZW50X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIiwib3duZXJfaWQiOiJvcmdfMTIzNDU2NzgiLCJhc3N1cmFuY2VfbGV2ZWwiOiJMMiIsImFsbG93Ijp0cnVlLCJyZWFzb25zIjpbeyJjb2RlIjoib2FwLmFsbG93ZWQiLCJtZXNzYWdlIjoiVHJhbnNhY3Rpb24gd2l0aGluIGxpbWl0cyJ9XSwicGFzc3BvcnRfZGlnZXN0Ijoic2hhMjU2OmFiY2QxMjM0ZWZnaDU2NzhpamtsOTAxMm1ub3AzNDU2cXJzdDc4OTB1dnd4MTIzNHl6YWI1Njc4Y2RlZiIsInNpZ25hdHVyZSI6ImV5SmhiR2NpT2lKU1V6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSjkucGxhY2Vob2xkZXIifQ.signature",
   },

package/external/aport-spec/oap/vc/tools/examples/vc-to-passport.js

@@ -59,7 +59,7 @@ const vc = {
     type: "Ed25519Signature2020",
     created: "2024-01-01T00:00:00Z",
     verificationMethod:
-      "https://aport.io/.well-known/oap/keys.json#ap_registry_ed25519_2024",
+      "https://aport.io/.well-known/oap/jwks.json#ap_registry_ed25519_2024",
     proofPurpose: "assertionMethod",
     jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJjcmVkZW50aWFsU3ViamVjdCI6eyJhZ2VudF9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsImtpbmQiOiJ0ZW1wbGF0ZSIsInNwZWNfdmVyc2lvbiI6Im9hcC8xLjAiLCJvd25lcl9pZCI6Im9yZ18xMjM0NTY3OCIsIm93bmVyX3R5cGUiOiJvcmciLCJhc3N1cmFuY2VfbGV2ZWwiOiJMMiIsInN0YXR1cyI6ImFjdGl2ZSIsImNhcGFiaWxpdGllcyI6W3siaWQiOiJwYXltZW50cy5yZWZ1bmQiLCJwYXJhbXMiOnsiY3VycmVuY3lfbGltaXRzIjp7IlVTRCI6eyJtYXhfcGVyX3R4Ijo1MDAwfX19fSx7ImlkIjoiZGF0YS5leHBvcnQiLCJwYXJhbXMiOnsibWF4X3Jvd3MiOjEwMDAwMH19XSwibGltaXRzIjp7InBheW1lbnRzLnJlZnVuZCI6eyJjdXJyZW5jeV9saW1pdHMiOnsiVVNEIjp7Im1heF9wZXJfdHgiOjUwMDAsImRhaWx5X2NhcCI6NTAwMDB9fSwicmVhc29uX2NvZGVzIjpbImN1c3RvbWVyX3JlcXVlc3QiLCJkZWZlY3RpdmVfcHJvZHVjdCJdLCJpZGVtcG90ZW5jeV9yZXF1aXJlZCI6dHJ1ZX19LCJyZWdpb25zIjpbIlVTIiwiQ0EiXSwibWV0YWRhdGEiOnsibmFtZSI6IkN1c3RvbWVyIFN1cHBvcnQgQUkiLCJkZXNjcmlwdGlvbiI6IkFJIGFnZW50IGZvciBjdXN0b21lciBzdXBwb3J0IG9wZXJhdGlvbnMifSwiY3JlYXRlZF9hdCI6IjIwMjQtMDEtMDFUMDA6MDA6MDBaIiwidXBkYXRlZF9hdCI6IjIwMjQtMDEtMTVUMTA6MzA6MDBaIiwidmVyc2lvbiI6IjEuMC4wIn0sImlzc3VlciI6Imh0dHBzOi8vYXBpLmFwb3J0LmRldiIsImlzc3VhbmNlRGF0ZSI6IjIwMjQtMDEtMDFUMDA6MDA6MDBaIiwiZXhwaXJhdGlvbkRhdGUiOiIyMDI1LTAxLTAxVDAwOjAwOjAwWiJ9.signature",
   },

package/external/aport-spec/oap/vc/tools/src/index.ts

@@ -285,8 +285,8 @@ export async function exportDecisionToVC(
       type: "Ed25519Signature2020",
       created: decision.created_at,
       // For decisions, use registry's well-known endpoint
-      // This should resolve to: https://aport.io/.well-known/oap/keys.json
-      verificationMethod: `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      // This should resolve to: https://aport.io/.well-known/oap/jwks.json
+      verificationMethod: `${registryKey.issuer}/.well-known/oap/jwks.json#${registryKey.kid}`,
       proofPurpose: "assertionMethod",
       jws: jws,
     },

package/external/aport-spec/oap/vc/tools/test-simple.js

@@ -21,7 +21,7 @@ function exportPassportToVC(passport, registryKey) {
     proof: {
       type: "Ed25519Signature2020",
       created: passport.created_at,
-      verificationMethod: `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      verificationMethod: `${registryKey.issuer}/.well-known/oap/jwks.json#${registryKey.kid}`,
       proofPurpose: "assertionMethod",
       jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
     },
@@ -44,7 +44,7 @@ function exportDecisionToVC(decision, registryKey) {
     proof: {
       type: "Ed25519Signature2020",
       created: decision.created_at,
-      verificationMethod: `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      verificationMethod: `${registryKey.issuer}/.well-known/oap/jwks.json#${registryKey.kid}`,
       proofPurpose: "assertionMethod",
       jws: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
     },

package/external/aport-spec/oap/vc/vc-mapping.md

@@ -60,7 +60,7 @@ An OAP passport can be exported as a Verifiable Credential with the following st
   "proof": {
     "type": "Ed25519Signature2020",
     "created": "2024-01-01T00:00:00Z",
-    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#key-2025-01",
+    "verificationMethod": "https://aport.io/.well-known/oap/jwks.json#key-2025-01",
     "proofPurpose": "assertionMethod",
     "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
@@ -112,7 +112,7 @@ An OAP decision can be exported as a Verifiable Credential receipt:
   "proof": {
     "type": "Ed25519Signature2020",
     "created": "2024-01-15T10:30:00Z",
-    "verificationMethod": "https://aport.io/.well-known/oap/keys.json#key-2025-01",
+    "verificationMethod": "https://aport.io/.well-known/oap/jwks.json#key-2025-01",
     "proofPurpose": "assertionMethod",
     "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
@@ -280,7 +280,7 @@ function exportPassportToVC(passport, registryKey) {
     "proof": {
       "type": "Ed25519Signature2020",
       "created": passport.created_at,
-      "verificationMethod": `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      "verificationMethod": `${registryKey.issuer}/.well-known/oap/jwks.json#${registryKey.kid}`,
       "proofPurpose": "assertionMethod",
       "jws": signCredential(passport, registryKey)
     }
@@ -329,7 +329,7 @@ function exportDecisionToVC(decision, registryKey) {
     "proof": {
       "type": "Ed25519Signature2020",
       "created": decision.created_at,
-      "verificationMethod": `${registryKey.issuer}/.well-known/oap/keys.json#${registryKey.kid}`,
+      "verificationMethod": `${registryKey.issuer}/.well-known/oap/jwks.json#${registryKey.kid}`,
       "proofPurpose": "assertionMethod",
       "jws": signCredential(decision, registryKey)
     }

package/external/aport-spec/oap/well-known-schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aport.io/oap/well-known-schema.json",
+  "title": "OAP Service Discovery Response",
+  "description": "JSON Schema for the /.well-known/oap/ discovery endpoint response. Conforms to RFC 8615 and mirrors OAuth 2.0 Authorization Server Metadata (RFC 8414).",
+  "type": "object",
+  "required": [
+    "oap_version",
+    "authorization_endpoint",
+    "passport_endpoint",
+    "policy_endpoint"
+  ],
+  "properties": {
+    "oap_version": {
+      "type": "string",
+      "description": "OAP specification version implemented.",
+      "pattern": "^\\d+\\.\\d+$",
+      "examples": ["1.0"]
+    },
+    "authorization_endpoint": {
+      "type": "string",
+      "format": "uri-template",
+      "description": "Passport verification endpoint. Accepts GET with an {agent_id} path parameter.",
+      "examples": ["https://api.example.com/api/verify/{agent_id}"]
+    },
+    "passport_endpoint": {
+      "type": "string",
+      "format": "uri-template",
+      "description": "Endpoint for retrieving and managing OAP passports.",
+      "examples": ["https://api.example.com/api/passports/{agent_id}"]
+    },
+    "policy_endpoint": {
+      "type": "string",
+      "format": "uri-template",
+      "description": "Endpoint for retrieving policy packs by name. Accepts {policy_name} in dot-separated format.",
+      "examples": ["https://api.example.com/api/policies/{policy_name}"]
+    },
+    "decision_endpoint": {
+      "type": "string",
+      "format": "uri-template",
+      "description": "Endpoint for retrieving individual authorization decisions by {decision_id}.",
+      "examples": ["https://api.example.com/api/verify/decisions/get/{decision_id}"]
+    },
+    "jwks_uri": {
+      "type": "string",
+      "format": "uri",
+      "description": "JWKS endpoint (RFC 7517) for verifying OAP decision and VC signatures.",
+      "examples": ["https://api.example.com/.well-known/oap/jwks.json"]
+    },
+    "supported_capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
+      },
+      "description": "Dot-separated capability identifiers this server can enforce. Format: category.subcategory.action.",
+      "examples": [
+        ["finance.payment.refund", "finance.payment.charge", "data.export.create", "messaging.message.send"]
+      ]
+    },
+    "supported_assurance_levels": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"]
+      },
+      "description": "Assurance levels the issuer can credential and enforce."
+    },
+    "agent_manifest_endpoint": {
+      "type": "string",
+      "format": "uri",
+      "description": "Public agent registry scoped to this domain."
+    },
+    "spec_uri": {
+      "type": "string",
+      "format": "uri",
+      "description": "Link to the OAP specification document."
+    },
+    "contact": {
+      "type": "string",
+      "description": "Security or operations contact (email or URL)."
+    }
+  },
+  "additionalProperties": false
+}

package/external/aport-spec/well-known.md

@@ -0,0 +1,203 @@
+# OAP Service Discovery via `.well-known/oap/`
+
+**Specification:** OAP v1.0
+**Status:** Draft
+**Last Updated:** 2026-03-26
+
+---
+
+## Overview
+
+The `.well-known/oap/` URI provides a standard discovery mechanism for the Open Agent Passport (OAP) authorization layer. Any HTTP server that supports OAP-based pre-action authorization MAY expose this endpoint to allow agent frameworks, orchestration platforms, and relying parties to automatically discover its OAP configuration without prior out-of-band setup.
+
+This specification follows the conventions established by RFC 8615 (Well-Known URIs) and mirrors the discovery patterns used by:
+- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414))
+- OpenID Connect Discovery 1.0
+- DIF Well-Known DID Configuration ([DIF](https://identity.foundation/.well-known/resources/did-configuration/))
+
+---
+
+## Discovery Request
+
+A client wishing to discover OAP support for a domain sends:
+
+```http
+GET /.well-known/oap/ HTTP/1.1
+Host: example.com
+Accept: application/json
+```
+
+Servers MUST accept requests both with and without a trailing slash (`/.well-known/oap` and `/.well-known/oap/`). Servers MAY redirect one form to the other using HTTP 301, but MUST NOT return 404 for either form.
+
+---
+
+## Discovery Response
+
+A server that supports OAP MUST respond with HTTP 200 and a JSON body conforming to the schema defined in [`well-known-schema.json`](./oap/well-known-schema.json).
+
+### Example Response
+
+```json
+{
+  "oap_version": "1.0",
+  "authorization_endpoint": "https://api.example.com/api/verify/{agent_id}",
+  "passport_endpoint": "https://api.example.com/api/passports/{agent_id}",
+  "policy_endpoint": "https://api.example.com/api/policies/{policy_name}",
+  "decision_endpoint": "https://api.example.com/api/verify/decisions/get/{decision_id}",
+  "jwks_uri": "https://api.example.com/.well-known/oap/jwks.json",
+  "supported_capabilities": [
+    "finance.payment.refund",
+    "finance.payment.charge",
+    "data.export.create",
+    "messaging.message.send"
+  ],
+  "supported_assurance_levels": ["L0", "L1", "L2", "L3", "L4KYC", "L4FIN"],
+  "spec_uri": "https://github.com/aporthq/aport-spec/blob/main/oap/oap-spec.md",
+  "contact": "security@example.com"
+}
+```
+
+### Response Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `oap_version` | string | **REQUIRED** | OAP specification version implemented (e.g., `"1.0"`). |
+| `authorization_endpoint` | URI template | **REQUIRED** | Passport verification endpoint. Accepts `GET` with an `{agent_id}` path parameter. Returns the passport with capabilities and assurance level. Equivalent to the OAP "evaluate" flow entry point. |
+| `passport_endpoint` | URI template | **REQUIRED** | Endpoint for retrieving and managing OAP passports. |
+| `policy_endpoint` | URI template | **REQUIRED** | Endpoint for retrieving policy packs by name. Accepts `{policy_name}` in dot-separated format (e.g., `finance.payment.refund.v1`). |
+| `decision_endpoint` | URI template | RECOMMENDED | Endpoint for retrieving individual authorization decisions by `{decision_id}`. |
+| `jwks_uri` | URI | RECOMMENDED | JWKS endpoint (RFC 7517) for verifying OAP decision and VC signatures. MUST point to `/.well-known/oap/jwks.json` on the same domain or a domain controlled by the same organization. |
+| `supported_capabilities` | array of string | RECOMMENDED | Dot-separated capability identifiers this server can enforce (see [Capability Registry](./oap/capability-registry.md)). Format: `category.subcategory.action` (e.g., `finance.payment.refund`). |
+| `supported_assurance_levels` | array of enum | RECOMMENDED | Assurance levels the issuer can credential and enforce. Valid values: `L0` (self-attested), `L1` (email verified), `L2` (GitHub verified), `L3` (domain verified), `L4KYC` (KYC/KYB verified), `L4FIN` (financial data verified). |
+| `agent_manifest_endpoint` | URI | OPTIONAL | Public agent registry scoped to this domain. |
+| `spec_uri` | URI | OPTIONAL | Link to the OAP specification document. |
+| `contact` | string | OPTIONAL | Security or operations contact (email or URL). |
+
+### Field Naming Conventions
+
+- Endpoint fields that accept path parameters use the `_endpoint` suffix and URI template syntax (`{param}`).
+- The `jwks_uri` field follows the naming convention established by OpenID Connect Discovery (section 3) and OAuth 2.0 Authorization Server Metadata (RFC 8414, section 2).
+
+---
+
+## Sub-paths
+
+Servers MAY serve additional resources under `.well-known/oap/`:
+
+| Path | Content-Type | Purpose |
+|------|-------------|---------|
+| `/.well-known/oap/` | `application/json` | Discovery document (this spec) |
+| `/.well-known/oap/jwks.json` | `application/json` | Domain-scoped JWKS (RFC 7517) for signature verification |
+| `/.well-known/oap/agents/` | `application/json` | Domain-scoped agent manifest |
+
+The `jwks_uri` field in the discovery document and the `/.well-known/oap/jwks.json` sub-path MUST resolve to the same key set. Servers SHOULD NOT serve keys at other paths to avoid ambiguity.
+
+---
+
+## Error Responses
+
+If a server does not implement OAP, it SHOULD return HTTP 404.
+
+Servers that wish to explicitly signal non-support MAY return HTTP 404 with:
+
+```json
+{
+  "error": "oap_not_supported",
+  "error_description": "This server does not implement OAP authorization."
+}
+```
+
+Servers that are temporarily unavailable SHOULD return HTTP 503.
+
+---
+
+## Security Considerations
+
+1. **TLS required.** The `/.well-known/oap/` endpoint MUST be served over HTTPS. HTTP is not acceptable for production deployments — discovery over plaintext exposes the authorization endpoint to MITM substitution.
+
+2. **Validate the response.** Clients MUST validate that all URI values in the discovery document use HTTPS and belong to the expected domain or a trusted subdomain before using them.
+
+3. **No sensitive data in discovery.** The discovery document MUST NOT contain credentials, private keys, or tenant-specific sensitive data.
+
+4. **Cache with care.** Clients MAY cache discovery responses but SHOULD respect `Cache-Control` headers and re-fetch on authorization failures. Stale discovery responses can silently route traffic to outdated endpoints.
+
+5. **Endpoint ownership.** All endpoint URIs SHOULD be hosted on the same domain as `/.well-known/oap/` or on a domain explicitly controlled by the same organization. Clients SHOULD reject endpoints that point to unrelated domains.
+
+---
+
+## Use Cases
+
+### 1. Agent Framework Auto-Configuration
+
+An agent framework (e.g., LangChain, CrewAI) integrating OAP enforcement discovers the authorization endpoint by resolving `/.well-known/oap/` on the target API's domain. No developer configuration required.
+
+```typescript
+// Auto-discovery in an OAP-aware agent framework
+const oap = await fetch(`https://${targetDomain}/.well-known/oap/`)
+  .then(r => r.json());
+
+// Verify agent passport before action
+const passport = await fetch(
+  oap.authorization_endpoint.replace('{agent_id}', agentId)
+).then(r => r.json());
+
+if (passport.status === 'active') {
+  // Agent is verified — proceed with action
+}
+```
+
+### 2. Relying Party Verification
+
+A merchant or API gateway verifying an agent's OAP credential resolves the agent's issuer domain's `/.well-known/oap/` endpoint to obtain the JWKS for signature verification — the same pattern used in JWT issuer discovery.
+
+```typescript
+// Fetch issuer's JWKS for signature verification
+const oap = await fetch(`https://${issuerDomain}/.well-known/oap/`).then(r => r.json());
+const jwks = await fetch(oap.jwks_uri).then(r => r.json());
+const verified = verifyDecisionSignature(decision, jwks);
+```
+
+### 3. Multi-Agent Delegation
+
+In a multi-agent pipeline, a sub-agent discovering the orchestrator's OAP endpoint to check delegation scope resolves `/.well-known/oap/` on the orchestrator's domain.
+
+---
+
+## IANA Considerations
+
+A Well-Known URI registration for `oap` is planned per [RFC 8615 section 5](https://www.rfc-editor.org/rfc/rfc8615#section-5):
+
+- **URI Suffix:** `oap`
+- **Change Controller:** APort / LiftRails Inc.
+- **Specification Document:** This document and [oap-spec.md](./oap/oap-spec.md)
+- **Status:** Planned
+
+Registration will be submitted once this specification reaches a stable draft.
+
+---
+
+## Conformance
+
+An implementation is conformant with this specification if:
+
+1. It responds to `GET /.well-known/oap/` over HTTPS with HTTP 200.
+2. It accepts requests both with and without a trailing slash.
+3. The response `Content-Type` is `application/json`.
+4. The response body contains at minimum: `oap_version`, `authorization_endpoint`, `passport_endpoint`, `policy_endpoint`.
+5. All URI values in the response use HTTPS.
+6. Capability identifiers in `supported_capabilities` use dot-separated format matching the [Capability Registry](./oap/capability-registry.md).
+7. If `jwks_uri` is present, it resolves to a valid JWK Set (RFC 7517) containing Ed25519 public keys.
+
+---
+
+## Related Specifications
+
+- [OAP Specification v1.0](./oap/oap-spec.md)
+- [Passport Schema](./oap/passport-schema.json)
+- [Decision Schema](./oap/decision-schema.json)
+- [Capability Registry](./oap/capability-registry.md)
+- [Security Model](./oap/security.md)
+- RFC 7517 — JSON Web Key (JWK)
+- RFC 8615 — Well-Known Uniform Resource Identifiers
+- RFC 8414 — OAuth 2.0 Authorization Server Metadata
+- OpenID Connect Discovery 1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",