@kya-os/contracts 1.7.25 → 1.7.31

package/dist/agent-deployment-utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Managed Agent Deployment Utilities
+ *
+ * Crypto-dependent functions (didToSlug, didToFlyApp) isolated here
+ * to keep the main schema module (agent-deployment.ts) free of Node.js
+ * dependencies. This ensures pure Zod schemas like DidStringSchema and
+ * FlyRegionSchema remain portable across all runtimes.
+ *
+ * **Node.js only** — uses `crypto.createHash`. See JSDoc on each function.
+ *
+ * @package @kya-os/contracts/agent-deployment
+ */
+/**
+ * Derive a short, deterministic, DNS-safe slug from an agent DID.
+ *
+ * Format: "kya-{first 16 chars of SHA-256 hex}"
+ * Example: did:key:z6MkhaXg... -> "kya-a3f2b1c9d4e5f6a7"
+ *
+ * Collision probability: ~1 in 4.3 billion (16 hex chars = 64 bits, birthday bound).
+ * Safe for millions of agents.
+ *
+ * **Note**: Uses Node.js `crypto.createHash` intentionally. This function runs
+ * server-side only (AgentShield + deploy services), never in browser or edge runtimes.
+ * If edge support is needed in the future, swap to Web Crypto `subtle.digest`.
+ *
+ * @param did - The agent DID string (must start with "did:")
+ * @returns DNS-safe slug matching /^kya-[a-f0-9]{16}$/ (20 chars total)
+ * @throws {Error} If `did` is empty or does not start with "did:"
+ */
+export declare function didToSlug(did: string): string;
+/**
+ * Derive Fly app name from agent DID.
+ * Fly app names must be: lowercase, alphanumeric + hyphens, 1-30 chars.
+ * Our slugs are 20 chars — well within the limit.
+ *
+ * **Note**: Uses Node.js `crypto.createHash` via `didToSlug`. See `didToSlug` JSDoc
+ * for portability notes.
+ *
+ * @param did - The agent DID string (must start with "did:")
+ * @throws {Error} If `did` is empty or does not start with "did:"
+ */
+export declare function didToFlyApp(did: string): string;
+/**
+ * Derive a readable, DNS-safe Fly app name from an agent name + DID.
+ *
+ * Format: "kya-{name[:19]}-{first 6 hex chars of SHA-256 of DID}"
+ * Example: ("researcher", "did:key:z6Mk...") → "kya-researcher-a3f2b1"
+ *
+ * Constraints:
+ *   "kya-" (4) + name[:19] (≤19) + "-" (1) + hash[:6] (6) = ≤30 chars
+ *   Fly app name hard limit: 30 chars ✓
+ *
+ * Uniqueness: 6 hex chars = 24 bits → birthday collision at ~4,096 agents
+ * sharing the exact same human name. Safe for production scale.
+ *
+ * Node.js only — same crypto constraint as didToSlug.
+ *
+ * @param name - Human-readable agent name from the deploy request
+ * @param did  - The agent DID string (must start with "did:")
+ * @throws {Error} If DID is invalid or name sanitizes to empty string
+ */
+export declare function nameToFlySlug(name: string, did: string): string;

package/dist/agent-deployment-utils.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Managed Agent Deployment Utilities
+ *
+ * Crypto-dependent functions (didToSlug, didToFlyApp) isolated here
+ * to keep the main schema module (agent-deployment.ts) free of Node.js
+ * dependencies. This ensures pure Zod schemas like DidStringSchema and
+ * FlyRegionSchema remain portable across all runtimes.
+ *
+ * **Node.js only** — uses `crypto.createHash`. See JSDoc on each function.
+ *
+ * @package @kya-os/contracts/agent-deployment
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didToSlug = didToSlug;
+exports.didToFlyApp = didToFlyApp;
+exports.nameToFlySlug = nameToFlySlug;
+const crypto_1 = require("crypto");
+/**
+ * Derive a short, deterministic, DNS-safe slug from an agent DID.
+ *
+ * Format: "kya-{first 16 chars of SHA-256 hex}"
+ * Example: did:key:z6MkhaXg... -> "kya-a3f2b1c9d4e5f6a7"
+ *
+ * Collision probability: ~1 in 4.3 billion (16 hex chars = 64 bits, birthday bound).
+ * Safe for millions of agents.
+ *
+ * **Note**: Uses Node.js `crypto.createHash` intentionally. This function runs
+ * server-side only (AgentShield + deploy services), never in browser or edge runtimes.
+ * If edge support is needed in the future, swap to Web Crypto `subtle.digest`.
+ *
+ * @param did - The agent DID string (must start with "did:")
+ * @returns DNS-safe slug matching /^kya-[a-f0-9]{16}$/ (20 chars total)
+ * @throws {Error} If `did` is empty or does not start with "did:"
+ */
+function didToSlug(did) {
+    if (!did || typeof did !== "string" || !did.startsWith("did:")) {
+        throw new Error('didToSlug: expected a valid DID string starting with "did:"');
+    }
+    const hash = (0, crypto_1.createHash)("sha256").update(did).digest("hex");
+    return `kya-${hash.substring(0, 16)}`;
+}
+/**
+ * Derive Fly app name from agent DID.
+ * Fly app names must be: lowercase, alphanumeric + hyphens, 1-30 chars.
+ * Our slugs are 20 chars — well within the limit.
+ *
+ * **Note**: Uses Node.js `crypto.createHash` via `didToSlug`. See `didToSlug` JSDoc
+ * for portability notes.
+ *
+ * @param did - The agent DID string (must start with "did:")
+ * @throws {Error} If `did` is empty or does not start with "did:"
+ */
+function didToFlyApp(did) {
+    return didToSlug(did);
+}
+/**
+ * Derive a readable, DNS-safe Fly app name from an agent name + DID.
+ *
+ * Format: "kya-{name[:19]}-{first 6 hex chars of SHA-256 of DID}"
+ * Example: ("researcher", "did:key:z6Mk...") → "kya-researcher-a3f2b1"
+ *
+ * Constraints:
+ *   "kya-" (4) + name[:19] (≤19) + "-" (1) + hash[:6] (6) = ≤30 chars
+ *   Fly app name hard limit: 30 chars ✓
+ *
+ * Uniqueness: 6 hex chars = 24 bits → birthday collision at ~4,096 agents
+ * sharing the exact same human name. Safe for production scale.
+ *
+ * Node.js only — same crypto constraint as didToSlug.
+ *
+ * @param name - Human-readable agent name from the deploy request
+ * @param did  - The agent DID string (must start with "did:")
+ * @throws {Error} If DID is invalid or name sanitizes to empty string
+ */
+function nameToFlySlug(name, did) {
+    if (!did || typeof did !== "string" || !did.startsWith("did:")) {
+        throw new Error('nameToFlySlug: expected a valid DID string starting with "did:"');
+    }
+    const hash = (0, crypto_1.createHash)("sha256").update(did).digest("hex").substring(0, 6);
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-") // non-alphanumeric → hyphen
+        .replace(/-{2,}/g, "-") // collapse consecutive hyphens
+        .replace(/^-+|-+$/g, "") // strip leading/trailing hyphens
+        .substring(0, 19)
+        .replace(/-+$/, ""); // strip trailing hyphens after truncation
+    if (!slug) {
+        throw new Error("nameToFlySlug: name sanitized to empty string");
+    }
+    return `kya-${slug}-${hash}`;
+}