@kybernesis/identity 0.1.0

package/NOTICE

@@ -0,0 +1,2 @@
+@kybernesis/identity
+Copyright 2026 Kybernesis (kybernesis.ai)

package/README.md

@@ -0,0 +1,55 @@
+# @kybernesis/identity
+
+Give an eve agent its `.agent` name. ARP Cloud holds the identity, the key, the
+permissions and the audit trail; this package is the thin end: it verifies the
+tokens ARP Cloud signs when it delivers a message, serves the document ARP Cloud
+checks when you attach the runtime, and turns your paired peers into tools.
+
+No daemon. No socket. No private key in your deployment.
+
+## Install
+
+```bash
+eve add @kybernesis/identity-channel   # agent/channels/arp.ts
+eve add @kybernesis/identity-peers     # agent/tools/arp-peers.ts
+```
+
+Then, in the ARP console (`cloud.arp.run/names/<name>` → Runtime → Attach), give
+it `https://<your-agent-host>/eve/v1/arp`. The console verifies the document this
+package serves and hands you four variables to set on the deployment:
+
+```
+ARP_ISSUER=https://gateway.arp.run
+ARP_AGENT_DID=did:web:<name>.agent
+ARP_AGENT_CREDENTIAL=<shown once>
+AGENTID_CHALLENGE=<from the attach step>
+```
+
+Add `arpAuth()` to your eve channel's auth walk so deliveries are accepted:
+
+```ts
+// agent/channels/eve.ts
+import { eveChannel } from "eve/channels/eve";
+import { localDev } from "eve/channels/auth";
+import { arpAuth } from "@kybernesis/identity";
+
+export default eveChannel({ auth: [arpAuth(), localDev()] });
+```
+
+(With `@kybernesis/dispatch`: `dispatchChannel({ trustedPeers, extraAuth: [arpAuth()] })`.)
+
+## What each piece does
+
+- `arpAuth()` — route auth. A delivery from ARP Cloud carries an ES256 token
+  verified against `https://gateway.arp.run/.well-known/jwks.json`, naming this
+  agent as audience and the paired peer as subject. The session principal is
+  `principalType: "agent"`, `authenticator: "arp"`, with `peerDid`,
+  `connectionId`, `purpose` and `obligations` as attributes.
+- `identityChannel()` — serves `GET /eve/v1/arp/.well-known/agentid-verification`
+  (`{ did, challenge }`) and `/eve/v1/arp/health`.
+- `arpPeers()` — on every turn, lists active connections from ARP Cloud and
+  exposes `ask_<peer>` tools. Pair or revoke in the console; nothing to redeploy.
+- `ARP_INSTRUCTIONS` — append to your instructions so the model uses the tools well.
+
+Degrades, never throws at boot: with no credential there are simply no peer
+tools; with no token the auth entry skips to the next one.

package/dist/arp-auth.d.ts

@@ -0,0 +1,25 @@
+import { type AuthFn } from "eve/channels/auth";
+export interface ArpAuthOptions {
+    /** ARP Cloud gateway origin. Defaults to ARP_ISSUER, then https://gateway.arp.run. */
+    issuer?: string;
+    /** This agent's identity, e.g. `did:web:samantha.agent`. Defaults to ARP_AGENT_DID. */
+    agentDid?: string;
+    /** fetch override (tests). */
+    fetchImpl?: typeof fetch;
+    /** JWKS cache lifetime (ms). Default 5 min. */
+    jwksTtlMs?: number;
+}
+/**
+ * Route auth for messages ARP Cloud delivers to this agent.
+ *
+ * ARP Cloud (the gateway) signs every delivery with an ES256 key published at
+ * `<issuer>/.well-known/jwks.json`; the token names THIS agent as audience and
+ * the paired peer as subject. Policy, obligations and audit were evaluated by
+ * ARP Cloud before delivery, so a verified token is the authorization — the
+ * same offline-verification shape `@kybernesis/enterprise` uses.
+ *
+ * Returns `null` (skip to the next auth entry) for requests without an ARP
+ * token; throws a structured 401 only when the JWKS is unreachable, so a
+ * gateway outage is distinguishable from a bad credential.
+ */
+export declare function arpAuth(options?: ArpAuthOptions): AuthFn<Request>;

package/dist/arp-auth.js

@@ -0,0 +1,99 @@
+import { createLocalJWKSet, jwtVerify } from "jose";
+import { UnauthenticatedError, extractBearerToken } from "eve/channels/auth";
+/**
+ * Route auth for messages ARP Cloud delivers to this agent.
+ *
+ * ARP Cloud (the gateway) signs every delivery with an ES256 key published at
+ * `<issuer>/.well-known/jwks.json`; the token names THIS agent as audience and
+ * the paired peer as subject. Policy, obligations and audit were evaluated by
+ * ARP Cloud before delivery, so a verified token is the authorization — the
+ * same offline-verification shape `@kybernesis/enterprise` uses.
+ *
+ * Returns `null` (skip to the next auth entry) for requests without an ARP
+ * token; throws a structured 401 only when the JWKS is unreachable, so a
+ * gateway outage is distinguishable from a bad credential.
+ */
+export function arpAuth(options = {}) {
+    const issuer = (options.issuer ?? process.env.ARP_ISSUER ?? "https://gateway.arp.run").replace(/\/+$/, "");
+    const agentDid = options.agentDid ?? process.env.ARP_AGENT_DID ?? "";
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const ttl = options.jwksTtlMs ?? 5 * 60_000;
+    let cached = null;
+    // JWKS via global fetch (stubbable, same as the peers module) with a short
+    // cache; one refetch when a key id is unknown (rotation).
+    async function keySet(force = false) {
+        if (!force && cached && Date.now() - cached.at < ttl)
+            return cached.set;
+        const res = await fetchImpl(`${issuer}/.well-known/jwks.json`, { signal: AbortSignal.timeout(6_000) });
+        if (!res.ok)
+            throw Object.assign(new Error(`jwks ${res.status}`), { code: "ERR_JWKS_FETCH" });
+        const doc = (await res.json());
+        cached = { at: Date.now(), set: createLocalJWKSet(doc) };
+        return cached.set;
+    }
+    return async (request) => {
+        const token = extractBearerToken(request.headers.get("authorization"));
+        if (!token || !agentDid)
+            return null;
+        // Only ARP tokens are ours; anything else falls through to the next entry.
+        let unverified;
+        try {
+            unverified = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+        }
+        catch {
+            return null;
+        }
+        if (unverified.kind !== "arp-push" || unverified.iss !== issuer)
+            return null;
+        let payload;
+        try {
+            try {
+                ({ payload } = await jwtVerify(token, await keySet(), { issuer, audience: agentDid }));
+            }
+            catch (first) {
+                const code = first?.code;
+                if (code === "ERR_JWKS_NO_MATCHING_KEY") {
+                    ({ payload } = await jwtVerify(token, await keySet(true), { issuer, audience: agentDid }));
+                }
+                else {
+                    throw first;
+                }
+            }
+        }
+        catch (error) {
+            const code = error?.code;
+            const name = error?.name;
+            if ((typeof code === "string" && code.startsWith("ERR_JWKS")) || name === "TimeoutError" || name === "AbortError") {
+                throw new UnauthenticatedError({
+                    code: "verification_unavailable",
+                    message: "ARP Cloud's signing keys could not be fetched; try again shortly.",
+                });
+            }
+            return null;
+        }
+        const peerDid = String(payload.sub ?? payload.peer_did ?? "");
+        if (!peerDid)
+            return null;
+        const obligations = Array.isArray(payload.obligations) ? payload.obligations : [];
+        return {
+            authenticator: "arp",
+            issuer,
+            principalId: peerDid,
+            principalType: "agent",
+            subject: `arp:${peerDid}`,
+            attributes: {
+                kind: "arp-push",
+                peerDid,
+                peerName: peerDid.replace(/^did:web:/, "").replace(/\.agent$/, ""),
+                connectionId: String(payload.connection_id ?? ""),
+                msgId: String(payload.msg_id ?? ""),
+                thid: String(payload.thid ?? ""),
+                ...(typeof payload.purpose === "string" ? { purpose: payload.purpose } : {}),
+                obligations: JSON.stringify(obligations),
+                obligationTypes: obligations
+                    .map((o) => (o && typeof o === "object" ? String(o.type ?? "") : ""))
+                    .filter((t) => t.length > 0),
+            },
+        };
+    };
+}

package/dist/channel.d.ts

@@ -0,0 +1,14 @@
+export interface IdentityChannelOptions {
+    /** This agent's identity, e.g. `did:web:samantha.agent`. Defaults to ARP_AGENT_DID. */
+    agentDid?: string;
+    /** The challenge ARP Cloud issued when attaching this runtime. Defaults to AGENTID_CHALLENGE. */
+    challenge?: string;
+}
+export declare const IDENTITY_PREFIX = "/eve/v1/arp";
+/**
+ * Serves the identity verification document ARP Cloud fetches when this
+ * runtime is attached to a name (`<url>/.well-known/agentid-verification`),
+ * plus a health probe. Mount as `agent/channels/arp.ts`; attach the name with
+ * URL `https://<host>/eve/v1/arp`.
+ */
+export declare function identityChannel(options?: IdentityChannelOptions): import("eve/channels").Channel<undefined, Record<string, unknown>, Record<string, unknown>>;

package/dist/channel.js

@@ -0,0 +1,26 @@
+import { defineChannel, GET } from "eve/channels";
+export const IDENTITY_PREFIX = "/eve/v1/arp";
+/**
+ * Serves the identity verification document ARP Cloud fetches when this
+ * runtime is attached to a name (`<url>/.well-known/agentid-verification`),
+ * plus a health probe. Mount as `agent/channels/arp.ts`; attach the name with
+ * URL `https://<host>/eve/v1/arp`.
+ */
+export function identityChannel(options = {}) {
+    return defineChannel({
+        // Deliveries from ARP Cloud arrive on the eve channel (POST /eve/v1/session),
+        // not here; this channel only owns the identity's HTTP documents.
+        receive: async ({ message, auth }, { from }) => from("arp:inbox").send(message, { auth }),
+        routes: [
+            GET(IDENTITY_PREFIX + "/.well-known/agentid-verification", async () => {
+                const did = options.agentDid ?? process.env.ARP_AGENT_DID ?? "";
+                const challenge = options.challenge ?? process.env.AGENTID_CHALLENGE ?? "";
+                if (!did || !challenge) {
+                    return Response.json({ error: "not_configured", hint: "set ARP_AGENT_DID and AGENTID_CHALLENGE" }, { status: 404 });
+                }
+                return Response.json({ did, challenge }, { headers: { "cache-control": "no-store" } });
+            }),
+            GET(IDENTITY_PREFIX + "/health", async () => Response.json({ ok: true, did: options.agentDid ?? process.env.ARP_AGENT_DID ?? null })),
+        ],
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { arpAuth, type ArpAuthOptions } from "./arp-auth.js";
+export { identityChannel, IDENTITY_PREFIX, type IdentityChannelOptions } from "./channel.js";
+export { arpPeers, discoverPeers, askPeer, toolName, type ArpPeersOptions, type ArpPeer } from "./peers.js";
+export { ARP_INSTRUCTIONS } from "./instructions.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { arpAuth } from "./arp-auth.js";
+export { identityChannel, IDENTITY_PREFIX } from "./channel.js";
+export { arpPeers, discoverPeers, askPeer, toolName } from "./peers.js";
+export { ARP_INSTRUCTIONS } from "./instructions.js";

package/dist/instructions.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Instructions to append to an agent that carries a .agent identity.
+ */
+export declare const ARP_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,14 @@
+/**
+ * Instructions to append to an agent that carries a .agent identity.
+ */
+export const ARP_INSTRUCTIONS = `
+## Your .agent identity
+
+You have a registered name on the agent network. Other agents that are paired
+with you appear as \`ask_<name>\` tools; use them when a request belongs to that
+agent rather than to you. When a message arrives from a paired agent, the
+caller's identity has already been verified and the message has already been
+checked against what its owner allowed — answer it as you would a trusted
+colleague, and honour any obligations attached (for example, do not include
+fields you were told to redact).
+`.trim();

package/dist/peers.d.ts

@@ -0,0 +1,29 @@
+export interface ArpPeersOptions {
+    /** ARP Cloud gateway origin. Defaults to ARP_ISSUER, then https://gateway.arp.run. */
+    issuer?: string;
+    /** This agent's credential from "Attach runtime". Defaults to ARP_AGENT_CREDENTIAL. */
+    credential?: string;
+    /** Cache the connection list this long (ms). Default 60s. */
+    cacheMs?: number;
+    /** How long to wait for a peer's answer (ms). Default 120s. */
+    timeoutMs?: number;
+    /** fetch override (tests). */
+    fetchImpl?: typeof fetch;
+}
+export interface ArpPeer {
+    connectionId: string;
+    peerDid: string;
+    name: string;
+    purpose: string | null;
+}
+/** Active ARP connections for this agent, from the gateway's agent-API. Degrades to [] on any failure. */
+export declare function discoverPeers(options?: ArpPeersOptions): Promise<ArpPeer[]>;
+/** Send one message to a paired peer through ARP Cloud and return its reply. */
+export declare function askPeer(options: ArpPeersOptions, peer: ArpPeer, message: string): Promise<string>;
+export declare function toolName(peerName: string): string;
+/**
+ * Every agent this one is PAIRED with on ARP, as tools — resolved from ARP
+ * Cloud at the start of each turn. Pair or revoke in the console and the tool
+ * appears or disappears on the next turn; nothing to redeploy.
+ */
+export declare function arpPeers(options?: ArpPeersOptions): import("eve/tools").DynamicSentinel<Record<string, unknown> | null>;

package/dist/peers.js

@@ -0,0 +1,92 @@
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+const cache = new Map();
+function config(options) {
+    return {
+        issuer: (options.issuer ?? process.env.ARP_ISSUER ?? "https://gateway.arp.run").replace(/\/+$/, ""),
+        credential: options.credential ?? process.env.ARP_AGENT_CREDENTIAL ?? "",
+        cacheMs: options.cacheMs ?? 60_000,
+        timeoutMs: options.timeoutMs ?? 120_000,
+        fetchImpl: options.fetchImpl ?? globalThis.fetch,
+    };
+}
+/** Active ARP connections for this agent, from the gateway's agent-API. Degrades to [] on any failure. */
+export async function discoverPeers(options = {}) {
+    const c = config(options);
+    if (!c.credential)
+        return [];
+    const key = `${c.issuer}|${c.credential.slice(0, 8)}`;
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < c.cacheMs)
+        return hit.peers;
+    try {
+        const res = await c.fetchImpl(`${c.issuer}/agent-api/connections`, {
+            headers: { authorization: `Bearer ${c.credential}` },
+            signal: AbortSignal.timeout(6_000),
+        });
+        if (!res.ok)
+            return hit?.peers ?? [];
+        const body = (await res.json());
+        const peers = (body.connections ?? []).map((k) => ({
+            connectionId: k.connection_id,
+            peerDid: k.peer_did,
+            name: k.peer_name,
+            purpose: k.purpose ?? null,
+        }));
+        cache.set(key, { at: Date.now(), peers });
+        return peers;
+    }
+    catch {
+        return hit?.peers ?? [];
+    }
+}
+/** Send one message to a paired peer through ARP Cloud and return its reply. */
+export async function askPeer(options, peer, message) {
+    const c = config(options);
+    const res = await c.fetchImpl(`${c.issuer}/agent-api/send`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${c.credential}` },
+        body: JSON.stringify({ connection_id: peer.connectionId, text: message, wait_ms: c.timeoutMs }),
+        signal: AbortSignal.timeout(c.timeoutMs + 10_000),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (res.status === 403)
+        return `${peer.name} declined: ${body.reason ?? "the message is outside what this connection allows."}`;
+    if (!res.ok || body.ok === false)
+        throw new Error(`${peer.name} could not be reached (${body.error ?? res.status}).`);
+    if (body.timed_out || !body.reply)
+        return `${peer.name} received the message but has not replied yet.`;
+    return body.reply;
+}
+export function toolName(peerName) {
+    return `ask_${peerName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+/**
+ * Every agent this one is PAIRED with on ARP, as tools — resolved from ARP
+ * Cloud at the start of each turn. Pair or revoke in the console and the tool
+ * appears or disappears on the next turn; nothing to redeploy.
+ */
+export function arpPeers(options = {}) {
+    return defineDynamic({
+        events: {
+            "turn.started": async () => {
+                const peers = await discoverPeers(options);
+                if (peers.length === 0)
+                    return null;
+                const tools = {};
+                for (const peer of peers) {
+                    tools[toolName(peer.name)] = defineTool({
+                        description: `Send a message to ${peer.name}, a separate agent paired with you, and get its reply. ` +
+                            (peer.purpose ? `Paired for: ${peer.purpose}. ` : "") +
+                            `Every message is checked against the permissions its owner granted and is logged for both sides.`,
+                        inputSchema: z.object({
+                            message: z.string().describe("What to ask or tell it. It has no view of this conversation."),
+                        }),
+                        execute: (input) => askPeer(options, peer, input.message),
+                    });
+                }
+                return tools;
+            },
+        },
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kybernesis/identity",
+  "version": "0.1.0",
+  "description": "Give an eve agent its .agent identity: verify ARP Cloud push tokens, serve the verification document, and reach paired peers as tools — no daemon, no socket, no key in the bundle.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "eve": ">=0.51.0 <0.52.0"
+  },
+  "dependencies": {
+    "jose": "^5.9.6",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "24.x",
+    "eve": "^0.51.1",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish.mjs",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KybernesisAI/platform",
+    "directory": "packages/identity"
+  }
+}