@kybernesis/identity 0.1.1 → 0.2.0

package/README.md

@@ -1,31 +1,35 @@
 # @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.
+Give an eve agent its `.agent` name.
 
-No daemon. No socket. No private key in your deployment.
+ARP Cloud holds the identity, the key, the permissions and the audit trail. This
+package is the thin end that lives inside the agent: it lets the owner connect
+the agent from the console with one click, accepts the messages ARP Cloud
+delivers, and turns paired agents into tools.
 
-## Install
+No daemon. No socket. No private key in your deployment. No environment
+variables to copy.
 
-```bash
-eve add @kybernesis/identity-channel   # agent/channels/arp.ts
-eve add @kybernesis/identity-peers     # agent/tools/arp-peers.ts
-```
+## For owners
 
-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:
+1. Register your name at [agent.arp.run](https://agent.arp.run).
+2. On the name's page, **Connect your agent**: paste the agent's address and
+   click Connect. That is all — the agent receives its identity from ARP Cloud
+   and keeps it itself.
+3. **Pair** with another agent from the same page; paired agents show up as
+   `ask_<name>_agent` tools on the agent's next turn.
 
-```
-ARP_ISSUER=https://gateway.arp.run
-ARP_AGENT_DID=did:web:<name>.agent
-ARP_AGENT_CREDENTIAL=<shown once>
-AGENTID_CHALLENGE=<from the attach step>
+Agents built with Kybernesis tooling ship with this package already wired in.
+For any other eve agent, the developer does the one-time setup below.
+
+## For developers (one-time)
+
+```bash
+eve add @kybernesis/identity-channel   # agent/channels/arp.ts   → identityChannel()
+eve add @kybernesis/identity-peers     # agent/tools/arp-peers.ts → arpPeers()
 ```
 
-Add `arpAuth()` to your eve channel's auth walk so deliveries are accepted:
+Then let deliveries in, on the eve channel:
 
 ```ts
 // agent/channels/eve.ts
@@ -34,23 +38,32 @@ import { localDev } from "eve/channels/auth";
 import { arpAuth } from "@kybernesis/identity";
 
 export default eveChannel({ auth: [arpAuth(), localDev()] });
+// with @kybernesis/dispatch: dispatchChannel({ ..., extraAuth: [arpAuth(), ...] })
 ```
 
-(With `@kybernesis/dispatch`: `dispatchChannel({ trustedPeers, extraAuth: [arpAuth()] })`.)
+Optionally append `ARP_INSTRUCTIONS` to the agent's instructions. Deploy once.
+From here on the owner connects, pairs and revokes in the console; nothing in
+the codebase changes.
+
+## How connect works
+
+`POST /eve/v1/arp/connect` receives a short-lived ES256 token from ARP Cloud,
+verifies it against `https://gateway.arp.run/.well-known/jwks.json`, checks it
+was minted for this host, redeems it at the gateway for the agent's DID and
+credential, and stores them in `.eve/arp-identity.json` (0600; path override
+`ARP_IDENTITY_FILE`). `arpAuth()` and `arpPeers()` read that file per request,
+so the connect takes effect without a restart.
+
+An identity file written for another issuer is never overwritten; the owner
+disconnects there first. Hosts without a writable disk (some serverless
+platforms) keep the environment-variable path: `ARP_ISSUER`, `ARP_AGENT_DID`,
+`ARP_AGENT_CREDENTIAL`, `AGENTID_CHALLENGE` (env always wins over the file).
 
 ## 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>_agent` tools (the `_agent` suffix keeps them distinct from
-  control-plane peers, which are `ask_<peer>`). 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.
+- `identityChannel()` — `/eve/v1/arp/connect`, `/eve/v1/arp/.well-known/agentid-verification` (`{ did, challenge }`) and `/eve/v1/arp/health`.
+- `arpAuth()` — route auth for deliveries: an ES256 token signed by ARP Cloud, verified offline, naming this agent as audience and the paired peer as subject. Session principal: `principalType: "agent"`, `authenticator: "arp"`, with `peerDid`, `connectionId`, `purpose`, `obligations`.
+- `arpPeers()` — on every turn, lists active connections and exposes `ask_<name>_agent` tools (the `_agent` suffix keeps them distinct from control-plane peers, which are `ask_<name>`).
+- `ARP_INSTRUCTIONS` — text to append to your instructions.
+
+Degrades, never throws at boot: with no identity there are no peer tools and the auth entry skips to the next one.

package/dist/arp-auth.js

@@ -1,5 +1,6 @@
 import { createLocalJWKSet, jwtVerify } from "jose";
 import { UnauthenticatedError, extractBearerToken } from "eve/channels/auth";
+import { resolveIdentity } from "./store.js";
 /**
  * Route auth for messages ARP Cloud delivers to this agent.
  *
@@ -14,14 +15,15 @@ import { UnauthenticatedError, extractBearerToken } from "eve/channels/auth";
  * 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 ?? "";
+    // Identity is resolved per request (options → env → identity file) so a
+    // "Connect your agent" that lands mid-life takes effect without a restart.
+    const identity = () => resolveIdentity({ ...(options.issuer ? { issuer: options.issuer } : {}), ...(options.agentDid ? { agentDid: options.agentDid } : {}) });
     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) {
+    async function keySet(issuer, 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) });
@@ -33,6 +35,7 @@ export function arpAuth(options = {}) {
     }
     return async (request) => {
         const token = extractBearerToken(request.headers.get("authorization"));
+        const { did: agentDid, issuer } = identity();
         if (!token || !agentDid)
             return null;
         // Only ARP tokens are ours; anything else falls through to the next entry.
@@ -48,12 +51,12 @@ export function arpAuth(options = {}) {
         let payload;
         try {
             try {
-                ({ payload } = await jwtVerify(token, await keySet(), { issuer, audience: agentDid }));
+                ({ payload } = await jwtVerify(token, await keySet(issuer), { 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 }));
+                    ({ payload } = await jwtVerify(token, await keySet(issuer, true), { issuer, audience: agentDid }));
                 }
                 else {
                     throw first;

package/dist/channel.d.ts

@@ -1,14 +1,19 @@
-export interface IdentityChannelOptions {
-    /** This agent's identity, e.g. `did:web:samantha.agent`. Defaults to ARP_AGENT_DID. */
+import { type ConnectOptions } from "./connect.js";
+export interface IdentityChannelOptions extends ConnectOptions {
+    /** This agent's identity, e.g. `did:web:samantha.agent`. Defaults to ARP_AGENT_DID, then the identity file. */
     agentDid?: string;
-    /** The challenge ARP Cloud issued when attaching this runtime. Defaults to AGENTID_CHALLENGE. */
+    /** The challenge ARP Cloud issued when attaching this runtime. Defaults to AGENTID_CHALLENGE, then the identity file. */
     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`.
+ * This agent's .agent identity surface:
+ *
+ *   POST /eve/v1/arp/connect                              — "Connect your agent" (ARP Cloud calls it)
+ *   GET  /eve/v1/arp/.well-known/agentid-verification     — { did, challenge } ARP Cloud checks
+ *   GET  /eve/v1/arp/health                                — { ok, did, store }
+ *
+ * Mount as `agent/channels/arp.ts`. Deliveries from paired agents arrive on
+ * the eve channel (add `arpAuth()` there), not here.
  */
 export declare function identityChannel(options?: IdentityChannelOptions): import("eve/channels").Channel<undefined, Record<string, unknown>, Record<string, unknown>>;

package/dist/channel.js

@@ -1,26 +1,41 @@
-import { defineChannel, GET } from "eve/channels";
+import { defineChannel, GET, POST } from "eve/channels";
+import { handleConnect, requestHostOf } from "./connect.js";
+import { resolveIdentity, storeKind } from "./store.js";
 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`.
+ * This agent's .agent identity surface:
+ *
+ *   POST /eve/v1/arp/connect                              — "Connect your agent" (ARP Cloud calls it)
+ *   GET  /eve/v1/arp/.well-known/agentid-verification     — { did, challenge } ARP Cloud checks
+ *   GET  /eve/v1/arp/health                                — { ok, did, store }
+ *
+ * Mount as `agent/channels/arp.ts`. Deliveries from paired agents arrive on
+ * the eve channel (add `arpAuth()` there), not here.
  */
 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: [
+            POST(IDENTITY_PREFIX + "/connect", async (req) => {
+                let body = {};
+                try {
+                    body = (await req.json());
+                }
+                catch { /* bad json → 400 below */ }
+                const { status, body: out } = await handleConnect(body, requestHostOf(req), options);
+                return Response.json(out, { status, headers: { "cache-control": "no-store" } });
+            }),
             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 });
+                const id = resolveIdentity(options);
+                if (!id.did || !id.challenge) {
+                    return Response.json({ error: "not_configured", hint: "connect this agent to its name in the ARP console" }, { status: 404 });
                 }
-                return Response.json({ did, challenge }, { headers: { "cache-control": "no-store" } });
+                return Response.json({ did: id.did, challenge: id.challenge }, { headers: { "cache-control": "no-store" } });
+            }),
+            GET(IDENTITY_PREFIX + "/health", async () => {
+                const id = resolveIdentity(options);
+                return Response.json({ ok: true, did: id.did || null, source: id.source, store: storeKind() });
             }),
-            GET(IDENTITY_PREFIX + "/health", async () => Response.json({ ok: true, did: options.agentDid ?? process.env.ARP_AGENT_DID ?? null })),
         ],
     });
 }

package/dist/connect.d.ts

@@ -0,0 +1,25 @@
+export interface ConnectOptions {
+    /** Issuers this runtime accepts connect tokens from. Default: ARP_ISSUER or https://gateway.arp.run. */
+    issuers?: string[];
+    fetchImpl?: typeof fetch;
+}
+export interface ConnectRequest {
+    token?: string;
+    issuer?: string;
+}
+/**
+ * "Connect your agent" — the runtime's half.
+ *
+ * ARP Cloud posts a short-lived ES256 connect token here. We verify it
+ * against the issuer's JWKS (offline trust, no shared secret), check it was
+ * minted for THIS host, redeem it at `<issuer>/agent-api/bootstrap` for the
+ * agent's DID + credential, and keep those in the identity file. From then
+ * on `arpAuth()` accepts deliveries and `arpPeers()` can call peers — with
+ * no environment variable and no restart.
+ */
+export declare function handleConnect(body: ConnectRequest, requestHost: string | null, options?: ConnectOptions): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+}>;
+/** Host of the incoming request (proxy-aware), for the audience check. */
+export declare function requestHostOf(req: Request): string | null;

package/dist/connect.js

@@ -0,0 +1,91 @@
+import { createLocalJWKSet, jwtVerify } from "jose";
+import { DEFAULT_ISSUER, readIdentityFile, saveIdentity, storeKind } from "./store.js";
+/**
+ * "Connect your agent" — the runtime's half.
+ *
+ * ARP Cloud posts a short-lived ES256 connect token here. We verify it
+ * against the issuer's JWKS (offline trust, no shared secret), check it was
+ * minted for THIS host, redeem it at `<issuer>/agent-api/bootstrap` for the
+ * agent's DID + credential, and keep those in the identity file. From then
+ * on `arpAuth()` accepts deliveries and `arpPeers()` can call peers — with
+ * no environment variable and no restart.
+ */
+export async function handleConnect(body, requestHost, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const allowed = (options.issuers ?? [process.env.ARP_ISSUER ?? DEFAULT_ISSUER]).map((i) => i.replace(/\/+$/, ""));
+    const issuer = (body.issuer ?? "").replace(/\/+$/, "");
+    const token = body.token ?? "";
+    if (!token || !issuer)
+        return { status: 400, body: { ok: false, error: "bad_request" } };
+    if (!allowed.includes(issuer))
+        return { status: 403, body: { ok: false, error: "unknown_issuer" } };
+    // First bind wins: an identity file written by another issuer is not
+    // overwritten (the owner disconnects there first).
+    const bound = readIdentityFile();
+    if (bound.did && bound.issuer && bound.issuer.replace(/\/+$/, "") !== issuer) {
+        return { status: 409, body: { ok: false, error: "bound_to_another_issuer" } };
+    }
+    let payload;
+    try {
+        const res = await fetchImpl(`${issuer}/.well-known/jwks.json`, { signal: AbortSignal.timeout(6_000) });
+        if (!res.ok)
+            throw new Error(`jwks ${res.status}`);
+        const jwks = createLocalJWKSet((await res.json()));
+        ({ payload } = await jwtVerify(token, jwks, { issuer }));
+    }
+    catch (err) {
+        return { status: 401, body: { ok: false, error: "invalid_token", detail: err.message } };
+    }
+    if (payload.kind !== "arp-connect" || typeof payload.did !== "string")
+        return { status: 401, body: { ok: false, error: "invalid_token" } };
+    // The token names the host it was minted for; refuse one minted for a different origin.
+    const aud = Array.isArray(payload.aud) ? payload.aud[0] : payload.aud;
+    if (requestHost && aud) {
+        let audHost = "";
+        try {
+            audHost = new URL(aud).host;
+        }
+        catch {
+            audHost = aud;
+        }
+        if (audHost.toLowerCase() !== requestHost.toLowerCase())
+            return { status: 401, body: { ok: false, error: "audience_mismatch", detail: `token is for ${audHost}` } };
+    }
+    if (storeKind() === "none" && !process.env.ARP_AGENT_CREDENTIAL) {
+        return { status: 503, body: { ok: false, error: "store_unwritable", store: "none" } };
+    }
+    let cfg;
+    let redeem;
+    try {
+        redeem = await fetchImpl(`${issuer}/agent-api/bootstrap`, { method: "POST", headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(10_000) });
+        cfg = (await redeem.json().catch(() => ({})));
+    }
+    catch (err) {
+        return { status: 502, body: { ok: false, error: "issuer_unreachable", detail: err.message } };
+    }
+    if (!redeem.ok || !cfg.did || !cfg.credential || !cfg.challenge) {
+        return { status: 502, body: { ok: false, error: cfg.error ?? "bootstrap_failed" } };
+    }
+    try {
+        saveIdentity({ did: cfg.did, issuer: cfg.issuer ?? issuer, credential: cfg.credential, challenge: cfg.challenge });
+    }
+    catch (err) {
+        return { status: 503, body: { ok: false, error: "store_unwritable", store: "none", detail: err.message } };
+    }
+    return { status: 200, body: { ok: true, did: cfg.did, store: "file" } };
+}
+/** Host of the incoming request (proxy-aware), for the audience check. */
+export function requestHostOf(req) {
+    const fwd = req.headers.get("x-forwarded-host");
+    if (fwd)
+        return fwd.split(",")[0].trim();
+    const host = req.headers.get("host");
+    if (host)
+        return host;
+    try {
+        return new URL(req.url).host;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -2,3 +2,5 @@ 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";
+export { resolveIdentity, readIdentityFile, saveIdentity, storeKind, identityFilePath, DEFAULT_ISSUER, type Identity } from "./store.js";
+export { handleConnect, requestHostOf, type ConnectOptions, type ConnectRequest } from "./connect.js";

package/dist/index.js

@@ -2,3 +2,5 @@ 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";
+export { resolveIdentity, readIdentityFile, saveIdentity, storeKind, identityFilePath, DEFAULT_ISSUER } from "./store.js";
+export { handleConnect, requestHostOf } from "./connect.js";

package/dist/instructions.js

@@ -5,7 +5,7 @@ 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>_agent\` tools (the name is their .agent name); use them when a request belongs to that
+with you appear as \`ask_<name>_agent\` tools (the name is their .agent name; a plain \`ask_<name>\` tool, if present, is a different, non-network peer); 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

package/dist/peers.js

@@ -1,10 +1,13 @@
 import { defineDynamic, defineTool } from "eve/tools";
 import { z } from "zod";
+import { resolveIdentity } from "./store.js";
 const cache = new Map();
 function config(options) {
+    // Per call, so a "Connect your agent" takes effect on the next turn.
+    const id = resolveIdentity({ ...(options.issuer ? { issuer: options.issuer } : {}), ...(options.credential ? { credential: options.credential } : {}) });
     return {
-        issuer: (options.issuer ?? process.env.ARP_ISSUER ?? "https://gateway.arp.run").replace(/\/+$/, ""),
-        credential: options.credential ?? process.env.ARP_AGENT_CREDENTIAL ?? "",
+        issuer: id.issuer,
+        credential: id.credential,
         cacheMs: options.cacheMs ?? 60_000,
         timeoutMs: options.timeoutMs ?? 120_000,
         fetchImpl: options.fetchImpl ?? globalThis.fetch,

package/dist/store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where this runtime keeps its .agent identity.
+ *
+ * Resolution order, per read: explicit options → environment (`ARP_AGENT_DID`,
+ * `ARP_ISSUER`, `ARP_AGENT_CREDENTIAL`, `AGENTID_CHALLENGE`) → the identity
+ * file. The file is what "Connect your agent" writes, so an owner never
+ * touches environment variables; env stays for hosts without a writable disk.
+ */
+export interface Identity {
+    did: string;
+    issuer: string;
+    credential: string;
+    challenge: string;
+    /** Where the identity came from. */
+    source: "options" | "env" | "file" | "none";
+}
+export declare const DEFAULT_ISSUER = "https://gateway.arp.run";
+export declare function identityFilePath(): string;
+/** The identity file as written by "Connect your agent" ({} when absent). */
+export declare function readIdentityFile(): Partial<Identity>;
+/** Current identity. Never throws; missing pieces are empty strings. */
+export declare function resolveIdentity(options?: {
+    agentDid?: string;
+    issuer?: string;
+    credential?: string;
+    challenge?: string;
+}): Identity;
+/** Persist a connected identity. Throws when the store is not writable. */
+export declare function saveIdentity(identity: {
+    did: string;
+    issuer: string;
+    credential: string;
+    challenge: string;
+}): string;
+/** Can this host keep an identity on disk? */
+export declare function storeKind(): "file" | "none";

package/dist/store.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const DEFAULT_ISSUER = "https://gateway.arp.run";
+export function identityFilePath() {
+    return process.env.ARP_IDENTITY_FILE ?? join(process.cwd(), ".eve", "arp-identity.json");
+}
+let cache = null;
+/** The identity file as written by "Connect your agent" ({} when absent). */
+export function readIdentityFile() {
+    const path = identityFilePath();
+    try {
+        const mtimeMs = statSync(path).mtimeMs;
+        if (cache && cache.path === path && cache.mtimeMs === mtimeMs)
+            return cache.value;
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        cache = { path, mtimeMs, value };
+        return value;
+    }
+    catch {
+        cache = null;
+        return {};
+    }
+}
+/** Current identity. Never throws; missing pieces are empty strings. */
+export function resolveIdentity(options = {}) {
+    const env = {
+        did: process.env.ARP_AGENT_DID ?? "",
+        issuer: process.env.ARP_ISSUER ?? "",
+        credential: process.env.ARP_AGENT_CREDENTIAL ?? "",
+        challenge: process.env.AGENTID_CHALLENGE ?? "",
+    };
+    const file = readIdentityFile();
+    const pick = (opt, e, f) => opt ? [opt, "options"] : e ? [e, "env"] : f ? [f, "file"] : ["", "none"];
+    const [did, didSource] = pick(options.agentDid, env.did, file.did);
+    const [issuer] = pick(options.issuer, env.issuer, file.issuer);
+    const [credential] = pick(options.credential, env.credential, file.credential);
+    const [challenge] = pick(options.challenge, env.challenge, file.challenge);
+    return { did, issuer: (issuer || DEFAULT_ISSUER).replace(/\/+$/, ""), credential, challenge, source: didSource };
+}
+/** Persist a connected identity. Throws when the store is not writable. */
+export function saveIdentity(identity) {
+    const path = identityFilePath();
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ ...identity, connected_at: new Date().toISOString() }, null, 2) + "\n", { mode: 0o600 });
+    cache = null;
+    return path;
+}
+/** Can this host keep an identity on disk? */
+export function storeKind() {
+    const path = identityFilePath();
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const probe = join(dir, `.arp-probe-${process.pid}`);
+        writeFileSync(probe, "", { mode: 0o600 });
+        try {
+            unlinkSync(probe);
+        }
+        catch { /* ignore */ }
+        return "file";
+    }
+    catch {
+        return "none";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/identity",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Give an eve agent its .agent identity: verify ARP Cloud push tokens, serve the verification document, and reach paired peers as tools \u2014 no daemon, no socket, no key in the bundle.",
   "type": "module",
   "license": "Apache-2.0",