@moxxy/sdk 0.32.0 → 0.34.0

package/src/secret-provider.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a named secret comes from: a swappable block, like every other.
+ *
+ * The built-in vault (AES-256-GCM under `~/.moxxy/vault.json`, unlocked via the
+ * OS keychain) is a good design for one machine and unusable for a fleet: there
+ * is no central issuance, no rotation, and no way to revoke a single
+ * workstation. Every organisation already runs something that does those three
+ * things, so the answer is to let them plug it in rather than to reimplement it.
+ *
+ * Deliberately ONE block rather than two. A host-scoped credential (a token for
+ * an internal registry or a GitHub Enterprise host) is a named secret with a
+ * naming convention on top; splitting it into a second `CredentialProvider`
+ * registry would leave two overlapping abstractions to keep in sync for no
+ * gain.
+ */
+
+export interface SecretProviderScope {
+  readonly cwd: string;
+}
+
+export interface SecretProviderSession {
+  /**
+   * Resolve a secret by name, or null when this provider does not hold it.
+   *
+   * Returning null rather than throwing is what makes providers composable: the
+   * host tries the active provider and falls back to the local vault, so
+   * adopting an external store does not require migrating every secret on day
+   * one.
+   *
+   * MUST NOT throw for an ordinary miss. A genuine failure (the store is
+   * unreachable, the token expired) SHOULD throw, because silently reporting
+   * "no such secret" for an outage would send the caller down a
+   * missing-credential path and hide the real cause.
+   */
+  get(name: string): Promise<string | null>;
+  close(): Promise<void>;
+}
+
+export interface SecretProviderDef {
+  readonly name: string;
+  readonly description?: string;
+  open(scope: SecretProviderScope): SecretProviderSession;
+}
+
+/** Freeze a secret-provider spec, mirroring the other `defineX` factories. */
+export function defineSecretProvider(def: SecretProviderDef): SecretProviderDef {
+  return Object.freeze({ ...def });
+}
+
+/**
+ * The canonical secret name holding a credential for `host`.
+ *
+ * A host credential is a named secret plus a convention, which is exactly why
+ * there is no separate `CredentialProvider` registry: whatever store an
+ * organisation already plugged in for secrets serves these too.
+ *
+ * `github.example.com` becomes `MOXXY_CREDENTIAL_GITHUB_EXAMPLE_COM`. The
+ * derivation mirrors the provider-key convention (upper-snake, non-alphanumerics
+ * to `_`) so an operator who has seen one can predict the other, and a port is
+ * dropped because a credential belongs to the host, not to a socket.
+ *
+ * Accepts a bare host or a full URL; anything unparseable yields null rather
+ * than a name derived from garbage, so a caller cannot accidentally look up a
+ * secret keyed on a typo.
+ */
+export function hostCredentialName(hostOrUrl: string): string | null {
+  const raw = hostOrUrl.trim();
+  if (raw.length === 0) return null;
+  let host = raw;
+  if (raw.includes('://')) {
+    try {
+      host = new URL(raw).hostname;
+    } catch {
+      return null;
+    }
+  } else {
+    // Strip a port or a path if the caller passed `host:443/x`.
+    host = raw.split('/')[0]!.split(':')[0]!;
+  }
+  host = host.replace(/^\[|\]$/g, '').trim();
+  if (host.length === 0 || /\s/.test(host)) return null;
+  const slug = host.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return slug.length > 0 ? `MOXXY_CREDENTIAL_${slug}` : null;
+}

package/src/server.ts

@@ -20,7 +20,24 @@ export {
   writeFileAtomicSync,
   moxxyHome,
   moxxyPath,
+  ensurePrivateDir,
+  ensurePrivateFile,
+  pruneStaleTempFiles,
+  PRIVATE_DIR_MODE,
+  PRIVATE_FILE_MODE,
 } from './fs-utils.js';
+// The local OS account as a Principal (node:os). The type and its pure helpers
+// ride the main barrel.
+export { resolveOsPrincipal } from './principal-os.js';
+// Outbound proxy support for global `fetch` (dynamic `undici` import). Node-only.
+export {
+  installEgressProxy,
+  readProxyEnv,
+  parseNoProxy,
+  shouldBypassProxy,
+  redactProxyUrl,
+  hasProxy,
+} from './egress.js';
 // Cross-process "fire exactly once" lock (node:fs). Value lives here; its
 // options type is re-exported from the main barrel like other erased types.
 export { CrossProcessFireLock } from './cross-process-lock.js';

package/src/session-like.ts

@@ -6,6 +6,7 @@ import type { ApprovalResolver, ModeBadge } from './mode.js';
 import type { PermissionResolver } from './permission.js';
 import type { ModelDescriptor, ProviderKeyValidation } from './provider.js';
 import type { PluginSetupSpec } from './schemas.js';
+import type { ToolIcon } from './tool-icon.js';
 import type { ToolCompactPresentation } from './tool.js';
 
 /**
@@ -80,6 +81,8 @@ export interface ToolInfo {
   readonly description: string;
   /** Compact presentation hint (plain data - crosses the wire intact). */
   readonly compact?: ToolCompactPresentation;
+  /** Declared icon, so a surface renders the tool's own choice, not a guess. */
+  readonly icon?: ToolIcon;
 }
 
 /** Serializable skill metadata. */

package/src/signature.ts

@@ -0,0 +1,34 @@
+import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+/**
+ * Ed25519 detached-signature verification over exact bytes.
+ *
+ * Lives in the SDK rather than beside its first caller because two different
+ * things now depend on it, and one of them is policy. Policy has to bind on a
+ * machine with no plugins installed at all, so the verifier it uses cannot sit
+ * inside a plugin: a control that a user can disable by uninstalling something
+ * is not a control.
+ *
+ * Verifies over the bytes as received, never over a re-serialisation of the
+ * parsed object. Canonicalising first would let two different documents share a
+ * signature whenever the parser and the serialiser disagree about anything,
+ * which is how signature-verification bypasses usually happen.
+ *
+ * Returns false rather than throwing on a malformed key or signature: to a
+ * caller "this did not verify" and "this could not be parsed" warrant the same
+ * response, and a throw here would tempt a try/catch that swallows both into a
+ * success path.
+ */
+export function verifyEd25519(
+  bytes: Uint8Array,
+  signatureB64: string,
+  publicKeyPem: string,
+): boolean {
+  if (!publicKeyPem || !signatureB64) return false;
+  try {
+    const key = createPublicKey(publicKeyPem);
+    return cryptoVerify(null, Buffer.from(bytes), key, Buffer.from(signatureB64, 'base64'));
+  } catch {
+    return false;
+  }
+}

package/src/tool-icon.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { TOOL_ICONS, isToolIcon } from './tool-icon.js';
+import { defineTool } from './define.js';
+import { z } from 'zod';
+
+describe('tool icons', () => {
+  it('is a closed vocabulary, so a surface can map it exhaustively', () => {
+    expect(isToolIcon('terminal')).toBe(true);
+    // The whole reason the field is not a free string: a name no surface owns
+    // would render as nothing anywhere.
+    expect(isToolIcon('sparkles-v2')).toBe(false);
+    expect(isToolIcon('')).toBe(false);
+    expect(isToolIcon(undefined)).toBe(false);
+  });
+
+  it('has no duplicates, which would make a surface map ambiguous', () => {
+    expect(new Set(TOOL_ICONS).size).toBe(TOOL_ICONS.length);
+  });
+
+  it('always offers a neutral choice for a tool that fits nothing else', () => {
+    expect(TOOL_ICONS).toContain('wrench');
+  });
+
+  it('carries a declared icon through defineTool onto the def', () => {
+    const tool = defineTool({
+      name: 'thing',
+      description: 'does a thing',
+      icon: 'workflow',
+      inputSchema: z.object({}),
+      handler: () => undefined,
+    });
+
+    expect(tool.icon).toBe('workflow');
+  });
+
+  it('leaves icon undefined when a tool does not declare one', () => {
+    const tool = defineTool({
+      name: 'thing',
+      description: 'does a thing',
+      inputSchema: z.object({}),
+      handler: () => undefined,
+    });
+
+    expect(tool.icon).toBeUndefined();
+  });
+});

package/src/tool-icon.ts

@@ -0,0 +1,46 @@
+/**
+ * What a tool looks like, as a semantic name rather than a glyph.
+ *
+ * A CLOSED vocabulary on purpose. Surfaces render wildly differently: the
+ * desktop draws SVG, the TUI prints a character, a future web surface might do
+ * something else again. If this were a free string, a plugin could name an icon
+ * no surface owns and every surface would have to guess, so in practice
+ * everything would fall back and the field would be decorative. A fixed set
+ * means each surface maps it exhaustively and a plugin's choice actually
+ * survives to the screen.
+ *
+ * The names describe WHAT THE TOOL TOUCHES, not what it looks like, so a
+ * surface is free to change its artwork without every plugin becoming wrong.
+ *
+ * Adding a member is a breaking change for surfaces (their maps stop being
+ * exhaustive and stop compiling), which is the intended cost: a new icon should
+ * be a deliberate decision across surfaces, not a silent fallback to a wrench.
+ */
+export const TOOL_ICONS = [
+  'file',
+  'folder',
+  'search',
+  'edit',
+  'diff',
+  'terminal',
+  'globe',
+  'chat',
+  'workflow',
+  'agent',
+  'settings',
+  'lock',
+  'plug',
+  'mic',
+  'speaker',
+  'smartphone',
+  'workspace',
+  'clipboard',
+  'spark',
+  'wrench',
+] as const;
+
+export type ToolIcon = (typeof TOOL_ICONS)[number];
+
+export function isToolIcon(value: unknown): value is ToolIcon {
+  return typeof value === 'string' && (TOOL_ICONS as ReadonlyArray<string>).includes(value);
+}

package/src/tool.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { EventLogReader } from './log.js';
+import type { ToolIcon } from './tool-icon.js';
 import type { PermissionRule } from './permission.js';
 import type { SessionId, ToolCallId, TurnId } from './ids.js';
 import type { SubagentSpawner } from './subagent.js';
@@ -191,6 +192,13 @@ export interface ToolDef {
   readonly handler: (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown;
   /** Opt-in presentation hint. See `ToolCompactPresentation`. */
   readonly compact?: ToolCompactPresentation;
+  /**
+   * What this tool touches, so surfaces can show it. Without this a surface can
+   * only guess from the NAME, which works for the handful of built-ins it was
+   * written against and gives every plugin-contributed tool the same generic
+   * fallback. See {@link ToolIcon}.
+   */
+  readonly icon?: ToolIcon;
   /**
    * Optional capability declaration. Advisory unless the user enables
    * `@moxxy/plugin-security`, at which point the active `Isolator`