@agentidentity/sdk 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/** The API returned a non-2xx response. Carries the server's own error fields. */
+export declare class AidApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string;
+    readonly retryable: boolean;
+    constructor(status: number, body: unknown);
+}
+/**
+ * The request never reached the API — DNS failure, connection refused, TLS error, or the
+ * request deadline elapsing.
+ *
+ * Without this, these surface as `TypeError: fetch failed`, which names neither the URL nor the
+ * underlying problem (undici hides it on `.cause`). Distinguishing "the server said no" from
+ * "I never reached the server" is the difference between fixing your request and checking your
+ * network, so the two cases get distinct types.
+ */
+export declare class AidConnectionError extends Error {
+    /** The originating error, e.g. an undici `ECONNREFUSED`/`ENOTFOUND`, or a timeout abort. */
+    readonly cause: unknown;
+    readonly method: string;
+    readonly url: string;
+    /** True when the client's own deadline elapsed rather than the connection failing outright. */
+    readonly timedOut: boolean;
+    constructor(method: string, url: string, cause: unknown, timedOut: boolean);
+}

package/dist/errors.js

@@ -0,0 +1,55 @@
+function unwrapWireError(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    if ("error" in body)
+        return body.error;
+    return body;
+}
+/** The API returned a non-2xx response. Carries the server's own error fields. */
+export class AidApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryable;
+    constructor(status, body) {
+        const wire = unwrapWireError(body);
+        super(wire?.message ?? `request failed with status ${status}`);
+        this.name = "AidApiError";
+        this.status = status;
+        this.code = wire?.code ?? "unknown";
+        this.requestId = wire?.request_id ?? "";
+        this.retryable = wire?.retryable ?? false;
+    }
+}
+/**
+ * The request never reached the API — DNS failure, connection refused, TLS error, or the
+ * request deadline elapsing.
+ *
+ * Without this, these surface as `TypeError: fetch failed`, which names neither the URL nor the
+ * underlying problem (undici hides it on `.cause`). Distinguishing "the server said no" from
+ * "I never reached the server" is the difference between fixing your request and checking your
+ * network, so the two cases get distinct types.
+ */
+export class AidConnectionError extends Error {
+    /** The originating error, e.g. an undici `ECONNREFUSED`/`ENOTFOUND`, or a timeout abort. */
+    cause;
+    method;
+    url;
+    /** True when the client's own deadline elapsed rather than the connection failing outright. */
+    timedOut;
+    constructor(method, url, cause, timedOut) {
+        const detail = cause instanceof Error && cause.cause instanceof Error
+            ? cause.cause.message
+            : cause instanceof Error
+                ? cause.message
+                : String(cause);
+        super(timedOut
+            ? `${method} ${url} timed out before the API responded`
+            : `${method} ${url} could not reach the API: ${detail}`);
+        this.name = "AidConnectionError";
+        this.cause = cause;
+        this.method = method;
+        this.url = url;
+        this.timedOut = timedOut;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export { generateVaultKeypair, vaultEncrypt, vaultDecrypt } from "./vault-crypto.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export { generateVaultKeypair, vaultEncrypt, vaultDecrypt } from "./vault-crypto.js";

package/dist/vault-crypto.d.ts

@@ -0,0 +1,11 @@
+export interface VaultKeypair {
+    publicKey: string;
+    privateKey: string;
+}
+export interface VaultCiphertext {
+    ciphertext: string;
+    ephemeralPublicKey: string;
+}
+export declare function generateVaultKeypair(): VaultKeypair;
+export declare function vaultEncrypt(plaintext: Buffer, recipientPublicKey: string): VaultCiphertext;
+export declare function vaultDecrypt(envelope: VaultCiphertext, recipientPublicKey: string, recipientPrivateKey: string): Buffer;

package/dist/vault-crypto.js

@@ -0,0 +1,55 @@
+// X25519 + AES-256-GCM envelope encryption for vault secrets. This lives in the SDK rather than
+// a separate package because it runs on the *client* side: plaintext never reaches the API, so
+// anyone talking to the vault needs these primitives locally. Node built-ins only, no deps.
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, } from "node:crypto";
+const HKDF_INFO = Buffer.from("aid-vault-v2");
+const HKDF_SALT = Buffer.alloc(0);
+function publicKeyObject(publicKeyB64url) {
+    return createPublicKey({ key: { kty: "OKP", crv: "X25519", x: publicKeyB64url }, format: "jwk" });
+}
+function privateKeyObject(publicKeyB64url, privateKeyB64url) {
+    return createPrivateKey({
+        key: { kty: "OKP", crv: "X25519", x: publicKeyB64url, d: privateKeyB64url },
+        format: "jwk",
+    });
+}
+function deriveAesKey(sharedSecret) {
+    return Buffer.from(hkdfSync("sha256", sharedSecret, HKDF_SALT, HKDF_INFO, 32));
+}
+export function generateVaultKeypair() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519");
+    const pubJwk = publicKey.export({ format: "jwk" });
+    const privJwk = privateKey.export({ format: "jwk" });
+    return { publicKey: pubJwk.x, privateKey: privJwk.d };
+}
+export function vaultEncrypt(plaintext, recipientPublicKey) {
+    const ephemeral = generateKeyPairSync("x25519");
+    const sharedSecret = diffieHellman({
+        privateKey: ephemeral.privateKey,
+        publicKey: publicKeyObject(recipientPublicKey),
+    });
+    const aesKey = deriveAesKey(sharedSecret);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", aesKey, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const ephPubJwk = ephemeral.publicKey.export({ format: "jwk" });
+    return {
+        ciphertext: [iv, authTag, encrypted].map((buf) => buf.toString("base64")).join("."),
+        ephemeralPublicKey: ephPubJwk.x,
+    };
+}
+export function vaultDecrypt(envelope, recipientPublicKey, recipientPrivateKey) {
+    const sharedSecret = diffieHellman({
+        privateKey: privateKeyObject(recipientPublicKey, recipientPrivateKey),
+        publicKey: publicKeyObject(envelope.ephemeralPublicKey),
+    });
+    const aesKey = deriveAesKey(sharedSecret);
+    const [ivB64, tagB64, dataB64] = envelope.ciphertext.split(".");
+    if (!ivB64 || !tagB64 || !dataB64) {
+        throw new Error("malformed vault envelope");
+    }
+    const decipher = createDecipheriv("aes-256-gcm", aesKey, Buffer.from(ivB64, "base64"));
+    decipher.setAuthTag(Buffer.from(tagB64, "base64"));
+    return Buffer.concat([decipher.update(Buffer.from(dataB64, "base64")), decipher.final()]);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agentidentity/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript client for Agent Identity \u2014 give an agent its own email address, durable event stream, and encrypted secret vault.",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "email",
+    "identity",
+    "webhooks",
+    "events",
+    "sdk"
+  ],
+  "homepage": "https://github.com/ALPHACOD3RS/agent-identity#readme",
+  "bugs": "https://github.com/ALPHACOD3RS/agent-identity/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ALPHACOD3RS/agent-identity.git",
+    "directory": "packages/sdk-ts"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "dotenv": "^16.4.5"
+  }
+}