agents-chain 0.0.2 → 0.0.3

package/README.md

@@ -1,13 +1,29 @@
 # agents-chain
 
-Lightweight identity, authentication, and audit layer for AI agent SDKs.
+**v0.0.3** — A zero-dependency security layer that wraps any app, service object, or AI SDK with Ed25519 identity, JWT-gated capability enforcement, constraint validation, and an encrypted audit trail.
 
-Wrap your OpenAI or Anthropic client with `agents-chain` to get:
+Drop it in front of your billing service, a third-party API client, or an OpenAI/Anthropic SDK — every call is signed, verified, scoped, and logged without touching your existing code.
 
-- **Ed25519 key-pair identity** per agent instance
-- **JWT-based capability tokens** — every API call is signed and verified
-- **Encrypted in-memory audit log** — AES-256-GCM, queryable at runtime
-- **Zero network calls** — everything runs locally, no external service required
+---
+
+## What it does
+
+- **Host + Agent identity** — Ed25519 keypairs with JWK thumbprints as stable IDs. Hosts sign agent registration JWTs; agents sign scoped capability tokens.
+- **9-step JWT verification** — Every capability call mints a fresh 60-second single-use token. Sub, iss, aud, signature, expiry, and JTI replay are all verified before the call proceeds.
+- **Capability registry + app wrapper** — Register named capabilities on any service object. A JavaScript Proxy intercepts method calls by name and gates them through the full auth pipeline.
+- **Constraint enforcement** — Grants can carry `max`, `min`, `in`, `not_in`, or exact-equality constraints on call arguments, enforced before execution.
+- **Encrypted audit log** — AES-256-GCM in-memory log of every call (success, denied, error). Drain to any HTTP endpoint or custom exporter on a schedule or at shutdown.
+- **Adapter interfaces** — Plug in your own Redis client for JTI replay protection across restarts. Plug in your own grant resolver to read active grants from your DB. The package ships no Redis client.
+- **Well-known discovery** — Serve `GET /.well-known/agent-configuration` with one call. Agents discover your capabilities, endpoints, and supported algorithms automatically.
+- **Zero mandatory dependencies** — In-memory defaults for everything. Redis, databases, and HTTP clients are injected by you.
+
+---
+
+## Package overview
+
+![Package overview — all modules and how they connect](https://raw.githubusercontent.com/Brian-Mwangi-developer/agentchain/main/docs/overview1.jpeg)
+
+The package has six layers. **HostIdentity** and **AgentIdentity** hold Ed25519 keypairs. **TokenBuilder** mints scoped JWTs; **TokenVerifier** runs the 9-step verification pipeline. **CapabilityRegistry** maps method names to capability definitions; **wrapApp()** turns any object into a secured Proxy using that registry. **AuditLog** records every call into an AES-256-GCM encrypted store and can drain to any **AuditExporter**. All state lives in **EncryptedStore** — there is no network I/O by default.
 
 ---
 
@@ -23,7 +39,90 @@ pnpm add agents-chain
 
 ---
 
-## Quick start
+## Wrapping any app — AppChain
+
+`AppChain` is the main entry point for wrapping your own services or third-party clients.
+
+### Integration flow
+
+![Integration flow — AppChain.create() through chain.wrap() to a secured Proxy](https://raw.githubusercontent.com/Brian-Mwangi-developer/agentchain/main/docs/flow1.jpeg)
+
+```ts
+import { AppChain, HttpAuditExporter } from 'agents-chain';
+
+const chain = await AppChain.create({
+  providerName: 'billing-service',
+  issuer: 'https://billing.mycompany.com',
+  capabilities: [
+    {
+      name: 'createInvoice',
+      description: 'Create a new invoice for a customer',
+      inputSchema: {
+        type: 'object',
+        required: ['customerId', 'amount'],
+        properties: {
+          customerId: { type: 'string' },
+          amount: { type: 'number' },
+        },
+      },
+      outputSchema: { type: 'object' },
+      execute: async (args, ctx) => {
+        // ctx carries agentId, hostId, and active permissions
+        return billingDb.createInvoice(args.customerId, args.amount);
+      },
+    },
+  ],
+
+  // Optional: resolve grants from your DB instead of in-memory
+  grantResolver: async (agentId, capability) => myDb.getGrant(agentId, capability),
+
+  // Optional: drain audit log to a hosted endpoint
+  auditExporter: new HttpAuditExporter({
+    endpoint: 'https://audit.yourservice.com/ingest',
+    apiKey: process.env.AUDIT_API_KEY,
+  }),
+});
+
+// Serve capability discovery
+app.get('/.well-known/agent-configuration', (req, res) =>
+  res.json(chain.getWellKnownConfig())
+);
+
+// Wrap any object — every registered method is now capability-gated
+const secured = chain.wrap(billingService, agentGrants);
+const invoice = await secured.createInvoice({ customerId: 'c1', amount: 500 });
+
+// Flush audit log on shutdown
+process.on('SIGTERM', () => chain.drain());
+```
+
+---
+
+## Per-call security pipeline
+
+Every intercepted call goes through this verification pipeline before your code runs.
+
+![Per-call security flow — 9-step JWT verification pipeline](https://raw.githubusercontent.com/Brian-Mwangi-developer/agentchain/main/docs/agent-flow1.jpeg)
+
+| Step | Check | Error on failure |
+|------|-------|-----------------|
+| 1–2 | Decode JWT header + payload, confirm `typ = "agent+jwt"` | `token_invalid` |
+| 3 | `sub` matches registered `agentId` | `agent_not_found` |
+| 4 | `iss` matches registered public key thumbprint | `token_invalid` |
+| 5 | `aud` matches the requested capability name | `capability_denied` |
+| 6 | Ed25519 signature is valid | `token_invalid` |
+| 7 | `exp`/`iat` temporal check + 30s clock skew tolerance | `token_expired` / `token_invalid` |
+| 8 | JTI not seen in 90-second replay window | `token_replayed` |
+| 9 | Agent holds an `active` grant for the capability | `capability_denied` |
+| 9b | Call arguments satisfy all grant constraints | `constraint_violated` |
+
+All failures throw `ChainAuthError` and are recorded in the audit log as `result: "denied"`.
+
+---
+
+## Wrapping AI SDKs — AgentsChain
+
+For OpenAI and Anthropic clients, use `AgentsChain` instead. It maps SDK method paths to capability strings automatically.
 
 ### OpenAI
 
@@ -41,10 +140,8 @@ const ai = chain.openai(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
 
 const response = await ai.chat.completions.create({
   model: 'gpt-4o',
-  messages: [{ role: 'user', content: 'Summarize the water cycle in one sentence.' }],
+  messages: [{ role: 'user', content: 'Summarize the water cycle.' }],
 });
-
-console.log(response.choices[0].message.content);
 ```
 
 ### Anthropic
@@ -64,24 +161,85 @@ const ai = chain.anthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY
 const response = await ai.messages.create({
   model: 'claude-sonnet-4-6',
   max_tokens: 256,
-  messages: [{ role: 'user', content: 'Classify this text as positive or negative: "I love it!"' }],
+  messages: [{ role: 'user', content: 'Classify: "I love it!"' }],
 });
+```
+
+### Capability names
+
+#### OpenAI
+
+| SDK method | Capability string |
+|-----------|------------------|
+| `ai.chat.completions.create()` | `"chat.completion"` |
+| `ai.embeddings.create()` | `"embedding"` |
+| `ai.images.generate()` | `"image.generation"` |
+| `ai.audio.transcriptions.create()` | `"audio.transcription"` |
+| `ai.audio.speech.create()` | `"audio.speech"` |
+| `ai.moderations.create()` | `"moderation"` |
+| `ai.responses.create()` | `"response"` |
+
+#### Anthropic
+
+| SDK method | Capability string |
+|-----------|------------------|
+| `ai.messages.create()` | `"message"` |
+| `ai.messages.stream()` | `"message.stream"` |
+| `ai.messages.countTokens()` | `"message.count_tokens"` |
+| `ai.completions.create()` | `"completion"` |
+| `ai.beta.messages.create()` | `"message.beta"` |
+
+Any method not in these tables passes through without interception.
+
+---
+
+## Grant constraints
+
+Constrain what an agent is allowed to pass in call arguments:
 
-console.log(response.content[0]);
+```ts
+const grants = [
+  {
+    capability: 'createInvoice',
+    status: 'active',
+    constraints: {
+      amount: { max: 1000 },              // amount <= 1000
+      currency: { in: ['USD', 'EUR'] },   // currency must be one of these
+    },
+    expiresAt: Date.now() + 86_400_000,   // expires in 24h
+  },
+];
+
+const secured = chain.wrap(billingService, grants);
+
+// This passes
+await secured.createInvoice({ customerId: 'c1', amount: 500, currency: 'USD' });
+
+// This throws ChainAuthError("constraint_violated")
+await secured.createInvoice({ customerId: 'c1', amount: 2000, currency: 'USD' });
 ```
 
+Supported operators: `max`, `min`, `in`, `not_in`, exact primitive equality.
+
 ---
 
-## Configuration
+## Persistent JTI replay protection
+
+By default, JTI replay protection is in-memory and resets on restart. For shared deployments, plug in your own Redis client:
 
 ```ts
-const chain = await AgentsChain.create({
-  agentName: string;      // Human-readable name for this agent
-  hostname: string;       // Used to build the agentId: "<hostname>-agent-<32hex>"
-  capabilities: string[]; // List of capability strings this agent is allowed to use
-  encryptionKey?: string; // Optional 64-char hex (32-byte) AES-256-GCM key.
-                          // Omit to generate a random key per session.
-                          // Provide to persist and reload audit logs across restarts.
+import { AppChain } from 'agents-chain';
+
+const redisAdapter = {
+  has: (key) => redis.exists(key).then(Boolean),
+  set: (key, ttlMs) => redis.set(key, '1', 'PX', ttlMs).then(() => {}),
+};
+
+const chain = await AppChain.create({
+  providerName: 'my-service',
+  issuer: 'https://myservice.com',
+  capabilities: [...],
+  jtiAdapter: redisAdapter,
 });
 ```
 
@@ -89,67 +247,89 @@ const chain = await AgentsChain.create({
 
 ## Audit log
 
-Every API call through a wrapped client is recorded in an encrypted in-memory log.
+Every call is recorded in an AES-256-GCM encrypted in-memory log.
 
 ```ts
 // Get all entries (decrypted)
 const entries = chain.getAuditLog();
 
-// Full snapshot with metadata
-const snapshot = chain.exportAudit();
-// { agentId, entries, exportedAt }
-
 // Summary counts
 const stats = chain.getStats();
 // { agentId, agentName, hostname, totalCalls, successfulCalls, deniedCalls, errorCalls, registeredAt }
+
+// Export and clear — call periodically or on shutdown
+await chain.drain();                               // uses auditExporter from config
+await chain.drain(new ConsoleAuditExporter());     // override exporter
 ```
 
 Each `AuditEntry` contains:
 
 | Field | Type | Description |
-|---|---|---|
+|-------|------|-------------|
 | `id` | `string` | Unique entry ID |
-| `agentId` | `string` | The agent that made the call |
-| `capability` | `string` | Capability used |
+| `agentId` | `string` | Agent that made the call |
+| `agentName` | `string` | Human-readable agent name |
+| `capability` | `string` | Capability requested |
+| `args` | `object` | Sanitized call arguments (secrets redacted) |
 | `result` | `"success" \| "denied" \| "error"` | Outcome |
+| `denialReason` | `string?` | Set when `result === "denied"` |
+| `jti` | `string` | JWT ID used |
 | `timestamp` | `number` | Unix ms |
-| `meta` | `Record<string, unknown>` | Provider-specific metadata |
+| `durationMs` | `number` | Execution time in ms |
+
+Argument keys matching `key`, `secret`, `token`, `password`, `auth`, `credential`, or `bearer` are automatically replaced with `"[REDACTED]"` before logging.
 
 ---
 
-## Capability names
+## Host identity
 
-`agents-chain` maps SDK method paths to short capability strings. You must use these exact strings in the `capabilities` array when calling `AgentsChain.create()` — otherwise the call will be blocked with a `ChainAuthError`.
+`HostIdentity` is the user's anchor for signing agent registration JWTs against an agent-auth server.
 
-### OpenAI
+```ts
+// chain.host is a HostIdentity instance
+const hostJwt = await chain.host.signJwt();
+const registrationJwt = await chain.host.signAgentRegistrationJwt(agentPublicKeyJwk);
 
-| SDK method | Capability string |
-|---|---|
-| `ai.chat.completions.create()` | `"chat.completion"` |
-| `ai.embeddings.create()` | `"embedding"` |
-| `ai.images.generate()` | `"image.generation"` |
-| `ai.audio.transcriptions.create()` | `"audio.transcription"` |
-| `ai.audio.speech.create()` | `"audio.speech"` |
-| `ai.moderations.create()` | `"moderation"` |
-| `ai.responses.create()` | `"response"` |
+// Stable identity across restarts — export and reload the private key
+const privateKeyJwk = await chain.host.exportPrivateKeyJwk();
+// persist privateKeyJwk securely
 
-### Anthropic
+// On next startup:
+const host = await HostIdentity.fromKeyPair(savedPrivateKeyJwk, savedPublicKeyJwk, config);
+```
 
-| SDK method | Capability string |
-|---|---|
-| `ai.messages.create()` | `"message"` |
-| `ai.messages.stream()` | `"message.stream"` |
-| `ai.messages.countTokens()` | `"message.count_tokens"` |
-| `ai.completions.create()` | `"completion"` |
-| `ai.beta.messages.create()` | `"message.beta"` |
+---
 
-Any SDK method not in these tables passes through without interception.
+## Well-known discovery
+
+```ts
+// Returns AgentConfiguration — serve at GET /.well-known/agent-configuration
+chain.getWellKnownConfig();
+
+// {
+//   version: "1.0-draft",
+//   provider_name: "billing-service",
+//   issuer: "https://billing.mycompany.com",
+//   algorithms: ["Ed25519"],
+//   modes: ["delegated", "autonomous"],
+//   approval_methods: ["device_authorization"],
+//   endpoints: {
+//     register: "/agent/register",
+//     capabilities: "/capability/list",
+//     execute: "/capability/execute",
+//     status: "/agent/status",
+//     revoke: "/agent/revoke",
+//     ...
+//   },
+//   default_capabilities: ["createInvoice", ...]
+// }
+```
 
 ---
 
-## Identity & crypto utilities
+## Crypto utilities
 
-Low-level utilities are exported if you need direct access:
+Low-level Ed25519 utilities are exported if you need them directly:
 
 ```ts
 import {
@@ -170,6 +350,12 @@ import {
 
 ---
 
+## Full architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for Mermaid diagrams covering the package internals, integration flow, per-call security pipeline, Host JWT flow, well-known discovery, and persistence adapter swap-in points.
+
+---
+
 ## License
 
 MIT — [brianmwangidev](https://www.npmjs.com/~brianmwangidev)

package/dist/app/app-wrapper.d.ts

@@ -0,0 +1,43 @@
+/**
+ * wrapApp — wraps any object with capability-gated security.
+ *
+ * This is the generic version of the AI SDK wrappers (openai-wrapper, anthropic-wrapper).
+ * Instead of a hardcoded path→capability map, it uses a CapabilityRegistry.
+ *
+ * For every method call on the wrapped object:
+ *   1. Look up capability by method name in the registry
+ *   2. If not in registry → call through without any gating (pass-through)
+ *   3. If in registry:
+ *      a. Verify the agent holds an active grant for this capability
+ *      b. Enforce any constraints on the call arguments
+ *      c. Call capability.execute(args, agentContext) — NOT the raw target method
+ *      d. Record in audit log (success / denied / error)
+ *
+ * Note: The Proxy only intercepts direct method calls (not nested paths).
+ * Use the AI SDK wrappers for nested path interception (e.g. client.chat.completions.create).
+ * This wrapper is designed for flat service objects where method names are unique.
+ */
+import type { CapabilityRegistry } from "./capability-registry.js";
+import type { AuditLog } from "../audit/audit-log.js";
+import type { TokenBuilder } from "../auth/token-builder.js";
+import type { TokenVerifier } from "../auth/token-verifier.js";
+import type { AgentIdentity } from "../identity/agent-identity.js";
+import type { ResolvedGrant } from "../types/protocol.js";
+export type AppInterceptContext = {
+    identity: AgentIdentity;
+    builder: TokenBuilder;
+    verifier: TokenVerifier;
+    log: AuditLog;
+    grants: ResolvedGrant[];
+};
+/**
+ * Wrap any object with capability-gated security.
+ *
+ * @param target    The object to wrap (e.g. a service instance)
+ * @param registry  Capability registry — defines what methods are gated
+ * @param ctx       Intercept context — identity, auth, audit, grants
+ * @returns         A Proxy with the same type as target
+ */
+export declare function wrapApp<T extends object>(target: T, registry: CapabilityRegistry, ctx: AppInterceptContext): T;
+export declare function attachRegistry(ctx: AppInterceptContext, registry: CapabilityRegistry): void;
+//# sourceMappingURL=app-wrapper.d.ts.map

package/dist/app/app-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-wrapper.d.ts","sourceRoot":"","sources":["../../src/app/app-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,aAAa,CAAC;IACxB,GAAG,EAAE,QAAQ,CAAC;IACd,MAAM,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EACpC,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,mBAAmB,GACzB,CAAC,CAgBH;AAuFD,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAE3F"}

package/dist/app/app-wrapper.js

@@ -0,0 +1,122 @@
+/**
+ * wrapApp — wraps any object with capability-gated security.
+ *
+ * This is the generic version of the AI SDK wrappers (openai-wrapper, anthropic-wrapper).
+ * Instead of a hardcoded path→capability map, it uses a CapabilityRegistry.
+ *
+ * For every method call on the wrapped object:
+ *   1. Look up capability by method name in the registry
+ *   2. If not in registry → call through without any gating (pass-through)
+ *   3. If in registry:
+ *      a. Verify the agent holds an active grant for this capability
+ *      b. Enforce any constraints on the call arguments
+ *      c. Call capability.execute(args, agentContext) — NOT the raw target method
+ *      d. Record in audit log (success / denied / error)
+ *
+ * Note: The Proxy only intercepts direct method calls (not nested paths).
+ * Use the AI SDK wrappers for nested path interception (e.g. client.chat.completions.create).
+ * This wrapper is designed for flat service objects where method names are unique.
+ */
+import { ChainAuthError } from "../errors/chain-error.js";
+import { enforceConstraints } from "../auth/constraints.js";
+/**
+ * Wrap any object with capability-gated security.
+ *
+ * @param target    The object to wrap (e.g. a service instance)
+ * @param registry  Capability registry — defines what methods are gated
+ * @param ctx       Intercept context — identity, auth, audit, grants
+ * @returns         A Proxy with the same type as target
+ */
+export function wrapApp(target, registry, ctx) {
+    return new Proxy(target, {
+        get(obj, prop) {
+            if (typeof prop !== "string")
+                return Reflect.get(obj, prop);
+            const capability = registry.get(prop);
+            const value = Reflect.get(obj, prop);
+            // Not a registered capability — pass through without gating
+            if (capability === undefined || typeof value !== "function") {
+                return value;
+            }
+            return createInterceptedMethod(capability.name, ctx);
+        },
+    });
+}
+function createInterceptedMethod(capabilityName, ctx) {
+    return async (...args) => {
+        const callArgs = (args[0] ?? {});
+        let jti = "unknown";
+        try {
+            // Build + verify the single-use JWT
+            const { token, claims } = await ctx.builder.build(capabilityName);
+            jti = claims.jti;
+            const verified = await ctx.verifier.verify(token, capabilityName, ctx.grants);
+            // Enforce grant constraints against call arguments
+            const grant = ctx.grants.find((g) => g.capability === capabilityName && g.status === "active");
+            if (grant?.constraints) {
+                enforceConstraints(grant.constraints, callArgs);
+            }
+            // Build agent context for capability.execute()
+            const agentContext = {
+                agentId: verified.agentId,
+                hostId: verified.hostId ?? "",
+                permissions: ctx.grants
+                    .filter((g) => g.status === "active")
+                    .map((g) => g.capability),
+            };
+            // Get the registered capability and execute it
+            const registryEntry = getCapabilityFromCtx(capabilityName, ctx);
+            if (!registryEntry) {
+                throw new ChainAuthError("capability_denied", `Capability "${capabilityName}" not found in registry`);
+            }
+            const start = Date.now();
+            let result;
+            try {
+                result = await registryEntry.execute(callArgs, agentContext);
+            }
+            catch (execErr) {
+                ctx.log.recordCall({
+                    context: verified,
+                    args: callArgs,
+                    result: "error",
+                    durationMs: Date.now() - start,
+                    errorMessage: execErr instanceof Error ? execErr.message : String(execErr),
+                });
+                throw execErr;
+            }
+            ctx.log.recordCall({
+                context: verified,
+                args: callArgs,
+                result: "success",
+                durationMs: Date.now() - start,
+            });
+            return result;
+        }
+        catch (err) {
+            if (err instanceof ChainAuthError) {
+                ctx.log.recordDenied({
+                    agentId: ctx.identity.agentId,
+                    agentName: ctx.identity.registration.agentName,
+                    hostname: ctx.identity.registration.hostname,
+                    capability: capabilityName,
+                    args: callArgs,
+                    reason: err.message,
+                    jti,
+                });
+                throw err;
+            }
+            throw err;
+        }
+    };
+}
+// Helper — we need registry access at intercept time.
+// We store it on the context via a symbol to keep the type clean.
+const REGISTRY_SYM = Symbol("registry");
+export function attachRegistry(ctx, registry) {
+    ctx[REGISTRY_SYM] = registry;
+}
+function getCapabilityFromCtx(name, ctx) {
+    const registry = ctx[REGISTRY_SYM];
+    return registry?.get(name);
+}
+//# sourceMappingURL=app-wrapper.js.map

package/dist/app/app-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-wrapper.js","sourceRoot":"","sources":["../../src/app/app-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAiB5D;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACnB,MAAS,EACT,QAA4B,EAC5B,GAAwB;IAExB,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;QACrB,GAAG,CAAC,GAAG,EAAE,IAAI;YACT,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAE5D,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAErC,4DAA4D;YAC5D,IAAI,UAAU,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;gBAC1D,OAAO,KAAK,CAAC;YACjB,CAAC;YAED,OAAO,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzD,CAAC;KACJ,CAAM,CAAC;AACZ,CAAC;AAED,SAAS,uBAAuB,CAC5B,cAAsB,EACtB,GAAwB;IAExB,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAA4B,CAAC;QAE5D,IAAI,GAAG,GAAG,SAAS,CAAC;QACpB,IAAI,CAAC;YACD,oCAAoC;YACpC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YAClE,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;YACjB,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAE9E,mDAAmD;YACnD,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,cAAc,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAClE,CAAC;YACF,IAAI,KAAK,EAAE,WAAW,EAAE,CAAC;gBACrB,kBAAkB,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;YACpD,CAAC;YAED,+CAA+C;YAC/C,MAAM,YAAY,GAAiB;gBAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE;gBAC7B,WAAW,EAAE,GAAG,CAAC,MAAM;qBAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;qBACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;aAChC,CAAC;YAEF,+CAA+C;YAC/C,MAAM,aAAa,GAAG,oBAAoB,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;YAChE,IAAI,CAAC,aAAa,EAAE,CAAC;gBACjB,MAAM,IAAI,cAAc,CACpB,mBAAmB,EACnB,eAAe,cAAc,yBAAyB,CACzD,CAAC;YACN,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACD,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YACjE,CAAC;YAAC,OAAO,OAAO,EAAE,CAAC;gBACf,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;oBACf,OAAO,EAAE,QAAQ;oBACjB,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,OAAO;oBACf,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;oBAC9B,YAAY,EAAE,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;iBAC7E,CAAC,CAAC;gBACH,MAAM,OAAO,CAAC;YAClB,CAAC;YAED,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;gBACf,OAAO,EAAE,QAAQ;gBACjB,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,SAAS;gBACjB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aACjC,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAChC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;oBACjB,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO;oBAC7B,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,SAAS;oBAC9C,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,QAAQ;oBAC5C,UAAU,EAAE,cAAc;oBAC1B,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,GAAG,CAAC,OAAO;oBACnB,GAAG;iBACN,CAAC,CAAC;gBACH,MAAM,GAAG,CAAC;YACd,CAAC;YACD,MAAM,GAAG,CAAC;QACd,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAED,sDAAsD;AACtD,kEAAkE;AAClE,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAExC,MAAM,UAAU,cAAc,CAAC,GAAwB,EAAE,QAA4B;IAChF,GAA+B,CAAC,YAAY,CAAC,GAAG,QAAQ,CAAC;AAC9D,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY,EAAE,GAAwB;IAChE,MAAM,QAAQ,GAAI,GAA+B,CAAC,YAAY,CAAmC,CAAC;IAClG,OAAO,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/app/capability-registry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CapabilityRegistry — registers Capability objects and generates well-known config.
+ *
+ * When building an AppChain, you register all capabilities the app exposes.
+ * The registry is then used by the app-wrapper Proxy to gate calls and by
+ * well-known.ts to generate the discovery config.
+ */
+import type { Capability } from "../types/capabilities.js";
+import type { AgentConfiguration } from "../types/protocol.js";
+export declare class CapabilityRegistry {
+    private readonly caps;
+    /**
+     * Register a capability. Chainable.
+     * Throws if a capability with the same name is already registered.
+     */
+    register<TIn, TOut>(cap: Capability<TIn, TOut>): this;
+    get(name: string): Capability | undefined;
+    list(): Capability[];
+    has(name: string): boolean;
+    get size(): number;
+    /**
+     * Build an AgentConfiguration object suitable for serving at
+     * GET /.well-known/agent-configuration.
+     *
+     * @param issuer         The base URL of the server (e.g. "https://billing.mycompany.com")
+     * @param providerName   Short name for the app (e.g. "billing-service")
+     * @param endpointPrefix Optional prefix for endpoint paths (default: "")
+     */
+    buildWellKnownConfig(issuer: string, providerName: string, endpointPrefix?: string): AgentConfiguration;
+}
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/app/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../src/app/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IAEtD;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI;IAQrD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzC,IAAI,IAAI,UAAU,EAAE;IAIpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;OAOG;IACH,oBAAoB,CAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,cAAc,SAAK,GACpB,kBAAkB;CAqBxB"}

package/dist/app/capability-registry.js

@@ -0,0 +1,65 @@
+/**
+ * CapabilityRegistry — registers Capability objects and generates well-known config.
+ *
+ * When building an AppChain, you register all capabilities the app exposes.
+ * The registry is then used by the app-wrapper Proxy to gate calls and by
+ * well-known.ts to generate the discovery config.
+ */
+export class CapabilityRegistry {
+    constructor() {
+        this.caps = new Map();
+    }
+    /**
+     * Register a capability. Chainable.
+     * Throws if a capability with the same name is already registered.
+     */
+    register(cap) {
+        if (this.caps.has(cap.name)) {
+            throw new Error(`CapabilityRegistry: capability "${cap.name}" is already registered`);
+        }
+        this.caps.set(cap.name, cap);
+        return this;
+    }
+    get(name) {
+        return this.caps.get(name);
+    }
+    list() {
+        return Array.from(this.caps.values());
+    }
+    has(name) {
+        return this.caps.has(name);
+    }
+    get size() {
+        return this.caps.size;
+    }
+    /**
+     * Build an AgentConfiguration object suitable for serving at
+     * GET /.well-known/agent-configuration.
+     *
+     * @param issuer         The base URL of the server (e.g. "https://billing.mycompany.com")
+     * @param providerName   Short name for the app (e.g. "billing-service")
+     * @param endpointPrefix Optional prefix for endpoint paths (default: "")
+     */
+    buildWellKnownConfig(issuer, providerName, endpointPrefix = "") {
+        return {
+            version: "1.0-draft",
+            provider_name: providerName,
+            issuer,
+            algorithms: ["Ed25519"],
+            modes: ["delegated", "autonomous"],
+            approval_methods: ["device_authorization"],
+            endpoints: {
+                register: `${endpointPrefix}/agent/register`,
+                capabilities: `${endpointPrefix}/capability/list`,
+                execute: `${endpointPrefix}/capability/execute`,
+                status: `${endpointPrefix}/agent/status`,
+                reactivate: `${endpointPrefix}/agent/reactivate`,
+                revoke: `${endpointPrefix}/agent/revoke`,
+                rotate_key: `${endpointPrefix}/agent/rotate-key`,
+                request_capability: `${endpointPrefix}/agent/request-capability`,
+            },
+            default_capabilities: Array.from(this.caps.keys()),
+        };
+    }
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/app/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../../src/app/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,OAAO,kBAAkB;IAA/B;QACqB,SAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IA+D1D,CAAC;IA7DG;;;OAGG;IACH,QAAQ,CAAY,GAA0B;QAC1C,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,IAAI,yBAAyB,CAAC,CAAC;QAC1F,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAiB,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI;QACA,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,oBAAoB,CAChB,MAAc,EACd,YAAoB,EACpB,cAAc,GAAG,EAAE;QAEnB,OAAO;YACH,OAAO,EAAE,WAAW;YACpB,aAAa,EAAE,YAAY;YAC3B,MAAM;YACN,UAAU,EAAE,CAAC,SAAS,CAAC;YACvB,KAAK,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;YAClC,gBAAgB,EAAE,CAAC,sBAAsB,CAAC;YAC1C,SAAS,EAAE;gBACP,QAAQ,EAAE,GAAG,cAAc,iBAAiB;gBAC5C,YAAY,EAAE,GAAG,cAAc,kBAAkB;gBACjD,OAAO,EAAE,GAAG,cAAc,qBAAqB;gBAC/C,MAAM,EAAE,GAAG,cAAc,eAAe;gBACxC,UAAU,EAAE,GAAG,cAAc,mBAAmB;gBAChD,MAAM,EAAE,GAAG,cAAc,eAAe;gBACxC,UAAU,EAAE,GAAG,cAAc,mBAAmB;gBAChD,kBAAkB,EAAE,GAAG,cAAc,2BAA2B;aACnE;YACD,oBAAoB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SACrD,CAAC;IACN,CAAC;CACJ"}