@kmmao/happy-agent 0.7.0 → 0.7.2

package/dist/index.d.cts

@@ -45,6 +45,27 @@ declare const MachineMetadataSchema: z.ZodObject<{
     happyLibDir: z.ZodString;
 }, z.core.$strip>;
 type MachineMetadata = z.infer<typeof MachineMetadataSchema>;
+declare const TailscaleInfoSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        connected: "connected";
+        disconnected: "disconnected";
+        "not-installed": "not-installed";
+    }>;
+    ipv4: z.ZodOptional<z.ZodString>;
+    ipv6: z.ZodOptional<z.ZodString>;
+    hostname: z.ZodOptional<z.ZodString>;
+    tailnetName: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    serves: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        port: z.ZodNumber;
+        path: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodString;
+        target: z.ZodString;
+        funnel: z.ZodBoolean;
+        hostname: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type TailscaleInfo = z.infer<typeof TailscaleInfoSchema>;
 declare const TunnelEntrySchema: z.ZodObject<{
     provider: z.ZodString;
     localPort: z.ZodNumber;
@@ -384,8 +405,8 @@ declare const ResolvedRuntimeProfileSchema: z$1.ZodObject<{
     }, z$1.core.$strip>>>;
     modelMappings: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
     defaultSessionType: z$1.ZodOptional<z$1.ZodEnum<{
-        simple: "simple";
         worktree: "worktree";
+        simple: "simple";
     }>>;
     defaultPermissionMode: z$1.ZodOptional<z$1.ZodEnum<{
         default: "default";
@@ -508,10 +529,46 @@ declare function getOrCreateMachine(config: Config, creds: Credentials, metadata
  */
 declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
 
+/**
+ * Outcome of a decrypt attempt.
+ *
+ * The low-level {@link decrypt} returns `unknown | null`, fusing "could not
+ * decrypt" (wrong key, tampered bytes, wrong variant, non-JSON plaintext)
+ * with a value that legitimately decrypted to something falsy.
+ * `DecryptResult` splits those apart: `{ ok: false }` is an authentication or
+ * parse failure, while `{ ok: true, value }` carries the recovered plaintext.
+ * Callers branch on `ok` instead of guessing from a collapsed `null`.
+ */
+type DecryptResult = {
+    ok: true;
+    value: any;
+} | {
+    ok: false;
+};
+/**
+ * A Cipher binds one AccessKey + encryption variant into a small interface.
+ *
+ * It is the single seam every transport client encrypts/decrypts through:
+ * hand it a value and get a wire-ready base64 string, or hand it a base64
+ * wire string and get a {@link DecryptResult}. The variant choice (legacy
+ * NaCl secretbox vs AES-256-GCM dataKey) and the base64 framing live behind
+ * this interface, so call sites never thread `(key, variant)` or call
+ * `encode`/`decodeBase64` themselves — a wrong-variant or wrong-key bug can
+ * only originate at the one `createCipher` call, not at the dozens of places
+ * that used to repeat the pattern.
+ */
+interface Cipher {
+    /** Encrypt a JSON-serializable value, returning a base64 wire string. */
+    encrypt(data: any): string;
+    /** Decode + decrypt a base64 wire string. Never throws. */
+    decrypt(data: string): DecryptResult;
+}
+
 /**
  * Common RPC types and interfaces for both session and machine clients.
  * Mirrors happy-cli/src/api/rpc/types.ts
  */
+
 /**
  * Generic RPC handler function type
  */
@@ -528,8 +585,7 @@ interface RpcRequest {
  */
 interface RpcHandlerConfig {
     scopePrefix: string;
-    encryptionKey: Uint8Array;
-    encryptionVariant: "legacy" | "dataKey";
+    cipher: Cipher;
     logger?: (message: string, data?: unknown) => void;
 }
 
@@ -544,8 +600,7 @@ interface RpcHandlerConfig {
 declare class RpcHandlerManager {
     private handlers;
     private readonly scopePrefix;
-    private readonly encryptionKey;
-    private readonly encryptionVariant;
+    private readonly cipher;
     private readonly logger;
     private socket;
     private reregisterInterval;
@@ -556,7 +611,18 @@ declare class RpcHandlerManager {
      */
     registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
     /**
-     * Handle an incoming RPC request
+     * Route a decrypted RPC call to its handler. This is the plaintext core of
+     * the manager: it knows nothing about the wire (no base64, no cipher), so it
+     * is TOTAL — an unknown method or a throwing handler both resolve to an
+     * `{ error }` value rather than rejecting. That makes it the test surface for
+     * routing behaviour, exercised without any crypto setup.
+     */
+    dispatch(method: string, params: unknown): Promise<unknown>;
+    /**
+     * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+     * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+     * failure the handler is still dispatched with `null` params (preserving the
+     * previous behaviour where a corrupt payload decrypted to `null`).
      */
     handleRequest(request: RpcRequest): Promise<string>;
     onSocketConnect(socket: Socket): void;
@@ -640,30 +706,6 @@ declare class SessionClient extends EventEmitter {
     private setupSocketListeners;
 }
 
-/**
- * Tailscale detection utility for happy-agent.
- *
- * Adapted from happy-cli/src/utils/tailscale.ts — keep in sync.
- */
-type TailscaleStatus = "connected" | "disconnected" | "not-installed";
-type TailscaleServeEntry = {
-    port: number;
-    path: string;
-    protocol: string;
-    target: string;
-    funnel: boolean;
-    hostname: string;
-};
-type TailscaleInfo = {
-    status: TailscaleStatus;
-    ipv4?: string;
-    ipv6?: string;
-    hostname?: string;
-    tailnetName?: string;
-    version?: string;
-    serves?: TailscaleServeEntry[];
-};
-
 /**
  * Tunnel Provider abstraction — unified interface for all tunnel backends.
  *

package/dist/index.d.mts

@@ -45,6 +45,27 @@ declare const MachineMetadataSchema: z.ZodObject<{
     happyLibDir: z.ZodString;
 }, z.core.$strip>;
 type MachineMetadata = z.infer<typeof MachineMetadataSchema>;
+declare const TailscaleInfoSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        connected: "connected";
+        disconnected: "disconnected";
+        "not-installed": "not-installed";
+    }>;
+    ipv4: z.ZodOptional<z.ZodString>;
+    ipv6: z.ZodOptional<z.ZodString>;
+    hostname: z.ZodOptional<z.ZodString>;
+    tailnetName: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    serves: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        port: z.ZodNumber;
+        path: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodString;
+        target: z.ZodString;
+        funnel: z.ZodBoolean;
+        hostname: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type TailscaleInfo = z.infer<typeof TailscaleInfoSchema>;
 declare const TunnelEntrySchema: z.ZodObject<{
     provider: z.ZodString;
     localPort: z.ZodNumber;
@@ -384,8 +405,8 @@ declare const ResolvedRuntimeProfileSchema: z$1.ZodObject<{
     }, z$1.core.$strip>>>;
     modelMappings: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
     defaultSessionType: z$1.ZodOptional<z$1.ZodEnum<{
-        simple: "simple";
         worktree: "worktree";
+        simple: "simple";
     }>>;
     defaultPermissionMode: z$1.ZodOptional<z$1.ZodEnum<{
         default: "default";
@@ -508,10 +529,46 @@ declare function getOrCreateMachine(config: Config, creds: Credentials, metadata
  */
 declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
 
+/**
+ * Outcome of a decrypt attempt.
+ *
+ * The low-level {@link decrypt} returns `unknown | null`, fusing "could not
+ * decrypt" (wrong key, tampered bytes, wrong variant, non-JSON plaintext)
+ * with a value that legitimately decrypted to something falsy.
+ * `DecryptResult` splits those apart: `{ ok: false }` is an authentication or
+ * parse failure, while `{ ok: true, value }` carries the recovered plaintext.
+ * Callers branch on `ok` instead of guessing from a collapsed `null`.
+ */
+type DecryptResult = {
+    ok: true;
+    value: any;
+} | {
+    ok: false;
+};
+/**
+ * A Cipher binds one AccessKey + encryption variant into a small interface.
+ *
+ * It is the single seam every transport client encrypts/decrypts through:
+ * hand it a value and get a wire-ready base64 string, or hand it a base64
+ * wire string and get a {@link DecryptResult}. The variant choice (legacy
+ * NaCl secretbox vs AES-256-GCM dataKey) and the base64 framing live behind
+ * this interface, so call sites never thread `(key, variant)` or call
+ * `encode`/`decodeBase64` themselves — a wrong-variant or wrong-key bug can
+ * only originate at the one `createCipher` call, not at the dozens of places
+ * that used to repeat the pattern.
+ */
+interface Cipher {
+    /** Encrypt a JSON-serializable value, returning a base64 wire string. */
+    encrypt(data: any): string;
+    /** Decode + decrypt a base64 wire string. Never throws. */
+    decrypt(data: string): DecryptResult;
+}
+
 /**
  * Common RPC types and interfaces for both session and machine clients.
  * Mirrors happy-cli/src/api/rpc/types.ts
  */
+
 /**
  * Generic RPC handler function type
  */
@@ -528,8 +585,7 @@ interface RpcRequest {
  */
 interface RpcHandlerConfig {
     scopePrefix: string;
-    encryptionKey: Uint8Array;
-    encryptionVariant: "legacy" | "dataKey";
+    cipher: Cipher;
     logger?: (message: string, data?: unknown) => void;
 }
 
@@ -544,8 +600,7 @@ interface RpcHandlerConfig {
 declare class RpcHandlerManager {
     private handlers;
     private readonly scopePrefix;
-    private readonly encryptionKey;
-    private readonly encryptionVariant;
+    private readonly cipher;
     private readonly logger;
     private socket;
     private reregisterInterval;
@@ -556,7 +611,18 @@ declare class RpcHandlerManager {
      */
     registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
     /**
-     * Handle an incoming RPC request
+     * Route a decrypted RPC call to its handler. This is the plaintext core of
+     * the manager: it knows nothing about the wire (no base64, no cipher), so it
+     * is TOTAL — an unknown method or a throwing handler both resolve to an
+     * `{ error }` value rather than rejecting. That makes it the test surface for
+     * routing behaviour, exercised without any crypto setup.
+     */
+    dispatch(method: string, params: unknown): Promise<unknown>;
+    /**
+     * Handle an incoming wire RPC request: decrypt params, dispatch in plaintext,
+     * encrypt the result. The Cipher is the only encryption seam; on a decrypt
+     * failure the handler is still dispatched with `null` params (preserving the
+     * previous behaviour where a corrupt payload decrypted to `null`).
      */
     handleRequest(request: RpcRequest): Promise<string>;
     onSocketConnect(socket: Socket): void;
@@ -640,30 +706,6 @@ declare class SessionClient extends EventEmitter {
     private setupSocketListeners;
 }
 
-/**
- * Tailscale detection utility for happy-agent.
- *
- * Adapted from happy-cli/src/utils/tailscale.ts — keep in sync.
- */
-type TailscaleStatus = "connected" | "disconnected" | "not-installed";
-type TailscaleServeEntry = {
-    port: number;
-    path: string;
-    protocol: string;
-    target: string;
-    funnel: boolean;
-    hostname: string;
-};
-type TailscaleInfo = {
-    status: TailscaleStatus;
-    ipv4?: string;
-    ipv6?: string;
-    hostname?: string;
-    tailnetName?: string;
-    version?: string;
-    serves?: TailscaleServeEntry[];
-};
-
 /**
  * Tunnel Provider abstraction — unified interface for all tunnel backends.
  *