@moxxy/sdk 0.33.0 → 0.34.0

package/src/egress.ts

@@ -0,0 +1,274 @@
+/**
+ * Outbound HTTP egress: corporate proxy support for everything moxxy fetches.
+ *
+ * Node's global `fetch` ignores `HTTPS_PROXY` entirely, and every provider
+ * reaches its API through it (`@anthropic-ai/sdk`, `openai`, and the plain
+ * `fetch` calls in tools). On a network that requires an outbound proxy that
+ * means the first provider call fails with an opaque network error and there is
+ * no setting that fixes it. Installing a global undici dispatcher is the only
+ * way to route global `fetch` through a proxy.
+ *
+ * `undici` is imported DYNAMICALLY and only when a proxy is actually configured,
+ * so `@moxxy/sdk` keeps zero hard runtime dependencies and a host with no proxy
+ * pays nothing. The package is a real dependency of `@moxxy/cli`.
+ *
+ * Not handled here, on purpose: a corporate TLS-terminating CA is Node's job,
+ * via `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in the environment before Node
+ * starts. There is no in-process equivalent, so the doctor surfaces whether it
+ * is set rather than pretending to configure it.
+ */
+
+/** Proxy inputs, already resolved from env and/or config. */
+export interface EgressProxySettings {
+  /** Proxy for `http:` origins. */
+  readonly httpProxy?: string;
+  /** Proxy for `https:` origins. */
+  readonly httpsProxy?: string;
+  /** Raw `NO_PROXY` value: comma/whitespace separated bypass rules. */
+  readonly noProxy?: string;
+}
+
+export interface EgressStatus {
+  /** True when a global dispatcher was installed. */
+  readonly enabled: boolean;
+  /** Credential-redacted proxy in use for `http:`, when set. */
+  readonly httpProxy?: string;
+  /** Credential-redacted proxy in use for `https:`, when set. */
+  readonly httpsProxy?: string;
+  /** Parsed bypass rules. */
+  readonly noProxy?: ReadonlyArray<string>;
+  /** Why nothing was installed, or why installation failed. */
+  readonly reason?: string;
+}
+
+/**
+ * Read proxy settings from an environment. Lowercase wins over uppercase, which
+ * is the de-facto convention (curl, requests, Go): a shell that exports both
+ * usually means the lowercase one was set deliberately and more recently.
+ *
+ * `http_proxy` is deliberately NOT used as a fallback for https origins. Some
+ * environments set only `http_proxy` for a plaintext-only proxy, and silently
+ * tunnelling TLS through it would fail confusingly rather than going direct.
+ */
+export function readProxyEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): EgressProxySettings {
+  const pick = (lower: string, upper: string): string | undefined => {
+    const value = (env[lower] ?? env[upper] ?? '').trim();
+    return value.length > 0 ? value : undefined;
+  };
+  const httpProxy = pick('http_proxy', 'HTTP_PROXY');
+  const httpsProxy = pick('https_proxy', 'HTTPS_PROXY');
+  const noProxy = pick('no_proxy', 'NO_PROXY');
+  return {
+    ...(httpProxy ? { httpProxy } : {}),
+    ...(httpsProxy ? { httpsProxy } : {}),
+    ...(noProxy ? { noProxy } : {}),
+  };
+}
+
+/** Split a `NO_PROXY` value into normalized rules. Separators are commas and
+ *  whitespace; empty entries are dropped and matching is case-insensitive. */
+export function parseNoProxy(value: string | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim().toLowerCase())
+    .filter((rule) => rule.length > 0);
+}
+
+/**
+ * Whether `origin` bypasses the proxy under `rules` (already parsed by
+ * {@link parseNoProxy}).
+ *
+ * Follows the de-facto `NO_PROXY` convention rather than inventing one:
+ *   - `*` bypasses everything.
+ *   - a bare host matches that host exactly, on any port.
+ *   - a leading `.` or `*.` matches the domain and every subdomain, so
+ *     `.corp.example` covers `api.corp.example` AND `corp.example`.
+ *   - an entry carrying `:port` matches only that port; the origin's port is
+ *     resolved from the scheme when the URL omits it.
+ *
+ * A malformed origin never bypasses: failing closed here sends the request
+ * through the proxy, which an operator can observe, rather than silently
+ * leaking it direct.
+ */
+export function shouldBypassProxy(origin: string, rules: ReadonlyArray<string>): boolean {
+  if (rules.length === 0) return false;
+  if (rules.includes('*')) return true;
+
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const port = url.port || (url.protocol === 'https:' ? '443' : '80');
+
+  for (const rule of rules) {
+    const { host: ruleHost, port: rulePort } = splitRule(rule);
+    if (rulePort !== undefined && rulePort !== port) continue;
+    if (ruleHost.length === 0) continue;
+
+    const suffix = ruleHost.startsWith('*.')
+      ? ruleHost.slice(1)
+      : ruleHost.startsWith('.')
+        ? ruleHost
+        : undefined;
+    if (suffix) {
+      // `.corp.example` covers the apex too, matching curl.
+      if (host === suffix.slice(1) || host.endsWith(suffix)) return true;
+      continue;
+    }
+    if (host === ruleHost) return true;
+  }
+  return false;
+}
+
+/**
+ * Split a bypass rule into host and optional port.
+ *
+ * A bare IPv6 literal contains colons of its own, so `::1` must not be read as
+ * host `:` on port `1`. As in a URL, a port qualifier on an IPv6 address
+ * requires brackets (`[::1]:7000`); an unbracketed rule with more than one
+ * colon is therefore an address, never a host:port pair.
+ */
+function splitRule(rule: string): { host: string; port?: string } {
+  if (rule.startsWith('[')) {
+    const end = rule.indexOf(']');
+    if (end === -1) return { host: rule.slice(1) };
+    const host = rule.slice(1, end);
+    const rest = rule.slice(end + 1);
+    return rest.startsWith(':') && /^\d+$/.test(rest.slice(1))
+      ? { host, port: rest.slice(1) }
+      : { host };
+  }
+  const first = rule.indexOf(':');
+  if (first === -1 || first !== rule.lastIndexOf(':')) return { host: rule };
+  const maybePort = rule.slice(first + 1);
+  return /^\d+$/.test(maybePort)
+    ? { host: rule.slice(0, first), port: maybePort }
+    : { host: rule };
+}
+
+/**
+ * A proxy URL with any embedded credentials masked, safe to log or show in
+ * `moxxy doctor`. Proxy URLs routinely carry `user:password@`, and this string
+ * ends up on terminals and in support pastes.
+ */
+export function redactProxyUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    if (!url.username && !url.password) return url.toString();
+    url.username = url.username ? '***' : '';
+    url.password = url.password ? '***' : '';
+    return url.toString();
+  } catch {
+    // Unparseable: reveal nothing rather than echoing a possible secret.
+    return '<invalid proxy url>';
+  }
+}
+
+/** True when at least one proxy is configured, i.e. there is work to do. */
+export function hasProxy(settings: EgressProxySettings): boolean {
+  return Boolean(settings.httpProxy ?? settings.httpsProxy);
+}
+
+interface UndiciModule {
+  readonly Agent: new (opts?: unknown) => UndiciDispatcher;
+  readonly ProxyAgent: new (opts: { uri: string }) => UndiciDispatcher;
+  readonly setGlobalDispatcher: (dispatcher: UndiciDispatcher) => void;
+}
+
+interface UndiciDispatcher {
+  dispatch(opts: { origin?: string | URL }, handler: unknown): boolean;
+  close(): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+export interface InstallEgressProxyOptions {
+  /** Surface for the "configured but unusable" case. Defaults to stderr. */
+  readonly warn?: (message: string) => void;
+  /** Injectable module loader for tests. */
+  readonly loadUndici?: () => Promise<UndiciModule>;
+}
+
+/**
+ * Install a global dispatcher routing outbound requests through the configured
+ * proxy, honouring the bypass rules. No-ops (and reports why) when no proxy is
+ * configured, so this is safe to call unconditionally at boot.
+ *
+ * Never throws: a broken proxy setting must degrade to a loud warning plus
+ * direct connections, not a failed boot.
+ */
+export async function installEgressProxy(
+  settings: EgressProxySettings,
+  opts: InstallEgressProxyOptions = {},
+): Promise<EgressStatus> {
+  if (!hasProxy(settings)) return { enabled: false, reason: 'no proxy configured' };
+
+  const warn = opts.warn ?? ((m: string) => process.stderr.write(`[moxxy] ${m}\n`));
+  for (const [label, value] of [
+    ['http_proxy', settings.httpProxy],
+    ['https_proxy', settings.httpsProxy],
+  ] as const) {
+    if (value === undefined) continue;
+    try {
+      new URL(value);
+    } catch {
+      const reason = `${label} is not a valid URL; continuing without a proxy`;
+      warn(reason);
+      return { enabled: false, reason };
+    }
+  }
+
+  let undici: UndiciModule;
+  try {
+    undici = await (opts.loadUndici ?? defaultLoadUndici)();
+  } catch {
+    const reason =
+      'a proxy is configured but the `undici` package is unavailable; ' +
+      'outbound requests will bypass it and may fail';
+    warn(reason);
+    return { enabled: false, reason };
+  }
+
+  const rules = parseNoProxy(settings.noProxy);
+  const direct = new undici.Agent();
+  const httpProxy = settings.httpProxy ? new undici.ProxyAgent({ uri: settings.httpProxy }) : undefined;
+  const httpsProxy = settings.httpsProxy
+    ? new undici.ProxyAgent({ uri: settings.httpsProxy })
+    : undefined;
+
+  const route = (origin: string | URL | undefined): UndiciDispatcher => {
+    if (origin === undefined) return direct;
+    const href = typeof origin === 'string' ? origin : origin.href;
+    if (shouldBypassProxy(href, rules)) return direct;
+    const secure = href.startsWith('https:');
+    return (secure ? httpsProxy : httpProxy) ?? direct;
+  };
+
+  const all = [direct, httpProxy, httpsProxy].filter(Boolean) as UndiciDispatcher[];
+  const router: UndiciDispatcher = {
+    dispatch: (dispatchOpts, handler) => route(dispatchOpts.origin).dispatch(dispatchOpts, handler),
+    close: async () => {
+      await Promise.all(all.map((d) => d.close()));
+    },
+    destroy: async () => {
+      await Promise.all(all.map((d) => d.destroy()));
+    },
+  };
+  undici.setGlobalDispatcher(router);
+
+  return {
+    enabled: true,
+    ...(settings.httpProxy ? { httpProxy: redactProxyUrl(settings.httpProxy) } : {}),
+    ...(settings.httpsProxy ? { httpsProxy: redactProxyUrl(settings.httpsProxy) } : {}),
+    ...(rules.length > 0 ? { noProxy: rules } : {}),
+  };
+}
+
+async function defaultLoadUndici(): Promise<UndiciModule> {
+  return (await import('undici')) as unknown as UndiciModule;
+}

package/src/events.ts

@@ -1,4 +1,5 @@
 import type { EventId, PluginId, SessionId, SkillId, ToolCallId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
 
 export type EventSource = 'user' | 'model' | 'tool' | 'plugin' | 'system' | 'compactor';
 
@@ -10,6 +11,23 @@ export interface EventBase {
   readonly turnId: TurnId;
   readonly causationId?: EventId;
   readonly source: EventSource;
+  /**
+   * Who the action was taken on behalf of. `source` is a CATEGORY (user, model,
+   * tool, …); this is the SUBJECT, and without it a transcript proves a machine
+   * did something rather than that a person did.
+   *
+   * Stamped on EVERY event, not only turn boundaries, and carrying the whole
+   * principal rather than a reference. That repeats ~55 bytes per event, which
+   * is small against an envelope that already carries three ULIDs, and it buys
+   * the property an audit sink needs: a single record is self-attributing, so
+   * shipping one line to a SIEM requires no fold and no join. This is the same
+   * trade CloudTrail and the Kubernetes audit log make.
+   *
+   * OPTIONAL because the log is append-only and persisted: sessions recorded
+   * before identity existed replay with no actor, and must keep replaying.
+   * Treat absent as "unattributed", never as an error.
+   */
+  readonly actor?: Principal;
 }
 
 export interface UserPromptAttachment {

package/src/fs-utils.test.ts

@@ -1,8 +1,16 @@
-import { mkdtemp, readFile, readdir, stat } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { moxxyHome, moxxyPath, writeFileAtomic, writeFileAtomicSync } from './fs-utils.js';
+import {
+  ensurePrivateDir,
+  ensurePrivateFile,
+  moxxyHome,
+  moxxyPath,
+  pruneStaleTempFiles,
+  writeFileAtomic,
+  writeFileAtomicSync,
+} from './fs-utils.js';
 
 describe('writeFileAtomic', () => {
   let dir: string;
@@ -105,3 +113,91 @@ describe('moxxyHome / moxxyPath', () => {
     expect(moxxyHome().endsWith('/.moxxy')).toBe(true);
   });
 });
+
+// POSIX modes are meaningless on Windows (chmod only toggles the read-only
+// flag), where these helpers are deliberate no-ops. Assert the guarantee only
+// where the platform can actually provide it.
+describe.skipIf(process.platform === 'win32')('ensurePrivateDir / ensurePrivateFile', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-priv-'));
+  });
+
+  it('creates a directory owner-only', async () => {
+    const target = join(dir, 'sessions');
+    await ensurePrivateDir(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o700);
+  });
+
+  it('tightens a directory that already exists with group/other bits', async () => {
+    const target = join(dir, 'legacy');
+    await mkdir(target, { mode: 0o755 });
+    await chmod(target, 0o755); // defeat umask so the pre-state is really loose
+    await ensurePrivateDir(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o700);
+  });
+
+  it('creates a missing file owner-only without truncating an existing one', async () => {
+    const target = join(dir, 'log.jsonl');
+    await ensurePrivateFile(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o600);
+
+    await writeFile(target, 'line\n');
+    await ensurePrivateFile(target);
+    expect(await readFile(target, 'utf8')).toBe('line\n');
+  });
+
+  it('tightens a file that already exists world-readable', async () => {
+    const target = join(dir, 'legacy.jsonl');
+    await writeFile(target, 'secret transcript\n');
+    await chmod(target, 0o644);
+    await ensurePrivateFile(target);
+    expect((await stat(target)).mode & 0o777).toBe(0o600);
+    expect(await readFile(target, 'utf8')).toBe('secret transcript\n');
+  });
+
+  it('creates parent directories', async () => {
+    const target = join(dir, 'a', 'b', 'c');
+    await ensurePrivateDir(target);
+    expect((await stat(target)).isDirectory()).toBe(true);
+  });
+});
+
+describe('pruneStaleTempFiles', () => {
+  let dir: string;
+  const DAY = 24 * 60 * 60 * 1000;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-prune-'));
+  });
+
+  const tmpName = (base: string): string =>
+    `${base}.4242.3f2504e0-4f89-11d3-9a0c-0305e82c3301.tmp`;
+
+  it('removes an abandoned temp file older than a day', async () => {
+    const stale = join(dir, tmpName('schedules.json'));
+    await writeFile(stale, '{}');
+    const removed = await pruneStaleTempFiles([dir], Date.now() + 2 * DAY);
+    expect(removed).toBe(1);
+    expect(await readdir(dir)).toEqual([]);
+  });
+
+  // The guarantee that makes this safe to run while another moxxy process is
+  // mid-write: a live temp file is milliseconds old and can never be selected.
+  it('leaves a freshly-written temp file alone', async () => {
+    const live = join(dir, tmpName('vault.json'));
+    await writeFile(live, '{}');
+    expect(await pruneStaleTempFiles([dir])).toBe(0);
+    expect(await readdir(dir)).toEqual([tmpName('vault.json')]);
+  });
+
+  it('ignores files that merely end in .tmp', async () => {
+    await writeFile(join(dir, 'notes.tmp'), 'user data');
+    await writeFile(join(dir, 'draft.md.tmp'), 'user data');
+    expect(await pruneStaleTempFiles([dir], Date.now() + 2 * DAY)).toBe(0);
+    expect((await readdir(dir)).sort()).toEqual(['draft.md.tmp', 'notes.tmp']);
+  });
+
+  it('never throws on a missing directory', async () => {
+    await expect(pruneStaleTempFiles([join(dir, 'nope')])).resolves.toBe(0);
+  });
+});

package/src/fs-utils.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, promises as fsp, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -11,6 +11,19 @@ export interface WriteFileAtomicOptions {
   readonly encoding?: BufferEncoding;
 }
 
+/**
+ * The private-path helpers below dispatch through `fs.promises` rather than
+ * destructured `node:fs/promises` bindings so the framework keeps ONE mockable
+ * filesystem boundary: a destructured binding is captured at import time and no
+ * longer observable, which silently blinds the regression guards that count
+ * `fs.open` / `fs.mkdir` calls (persistence.ready.test.ts).
+ */
+
+/** Owner-only directory: no group/other bits, so nobody else can even traverse in. */
+export const PRIVATE_DIR_MODE = 0o700;
+/** Owner-only file. */
+export const PRIVATE_FILE_MODE = 0o600;
+
 /**
  * Crash-atomic file write: write a unique sibling temp file, then `rename` it
  * over the target. POSIX `rename` is atomic on the same filesystem, so a crash
@@ -84,3 +97,109 @@ export function moxxyHome(): string {
 export function moxxyPath(...segments: string[]): string {
   return join(moxxyHome(), ...segments);
 }
+
+/**
+ * POSIX permission bits are meaningless on Windows (`chmod` only toggles the
+ * read-only flag; access is governed by ACLs), so the tightening helpers below
+ * are no-ops there rather than pretending to enforce something they cannot.
+ */
+const POSIX_PERMS = process.platform !== 'win32';
+
+/** Group/other bits. Their presence is what makes a path readable by another
+ *  local account, and is the only condition worth a `chmod` syscall. */
+const GROUP_OTHER = 0o077;
+
+/**
+ * `mkdir -p` a directory that must stay owner-only, tightening it when it
+ * already exists with looser bits.
+ *
+ * The tightening pass is what makes this safe to adopt mid-life: installs
+ * created before this was enforced have a `0755` directory on disk, and
+ * `mkdir` is a no-op on an existing path, so mode alone would never fix them.
+ *
+ * Best-effort by design: a permission error (a directory owned by another user,
+ * an exotic filesystem, a network mount) must never take down a boot whose only
+ * problem is that a chmod did not stick. Directory CREATION still throws, since
+ * failing to create the state directory is a real failure.
+ */
+export async function ensurePrivateDir(dir: string): Promise<void> {
+  await fsp.mkdir(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+  await tightenIfLoose(dir, PRIVATE_DIR_MODE);
+}
+
+/**
+ * Create-if-absent a file that must stay owner-only, tightening it when it
+ * already exists with looser bits. `open(path, 'a')` creates with
+ * `0o666 & ~umask` (typically `0644`), so an append-only log needs the mode
+ * applied explicitly and retroactively.
+ */
+export async function ensurePrivateFile(file: string): Promise<void> {
+  const handle = await fsp.open(file, 'a', PRIVATE_FILE_MODE);
+  await handle.close();
+  await tightenIfLoose(file, PRIVATE_FILE_MODE);
+}
+
+async function tightenIfLoose(target: string, mode: number): Promise<void> {
+  if (!POSIX_PERMS) return;
+  try {
+    const st = await fsp.stat(target);
+    if ((st.mode & GROUP_OTHER) === 0) return;
+    await fsp.chmod(target, mode);
+  } catch {
+    /* best-effort: never fail a boot over a chmod */
+  }
+}
+
+/**
+ * The temp-file shape {@link writeFileAtomic} renames from:
+ * `<target>.<pid>.<uuid>.tmp`. Anchored, and specific enough that a user file
+ * that merely ends in `.tmp` can never match.
+ */
+const ATOMIC_TMP = /\.\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i;
+
+/** Age past which an atomic-write temp file is certainly abandoned. A live
+ *  write is sub-second; anything a day old outlived the process that made it. */
+const STALE_TMP_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Delete abandoned {@link writeFileAtomic} temp files in `dirs`.
+ *
+ * `writeFileAtomic` unlinks its temp file when the write throws, but it cannot
+ * when the process is `SIGKILL`ed mid-write, so residue accumulates for the
+ * life of the install (six such files, the oldest a month old, prompted this).
+ *
+ * Two properties keep this safe against a CONCURRENT moxxy process writing to
+ * the same directory: only the exact `.<pid>.<uuid>.tmp` shape is considered,
+ * and only entries older than {@link STALE_TMP_AGE_MS}. A temp file that is
+ * still live is milliseconds old and can never be selected.
+ *
+ * Non-recursive and fully best-effort: it returns the number removed and never
+ * throws, so callers can fire it detached at boot without guarding it.
+ */
+export async function pruneStaleTempFiles(
+  dirs: ReadonlyArray<string>,
+  now = Date.now(),
+): Promise<number> {
+  let removed = 0;
+  for (const dir of dirs) {
+    let names: string[];
+    try {
+      names = await fsp.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!ATOMIC_TMP.test(name)) continue;
+      const full = join(dir, name);
+      try {
+        const st = await fsp.stat(full);
+        if (now - st.mtimeMs < STALE_TMP_AGE_MS) continue;
+        await fsp.rm(full, { force: true });
+        removed++;
+      } catch {
+        /* raced with another pruner, or not ours to delete */
+      }
+    }
+  }
+  return removed;
+}

package/src/hooks.ts

@@ -3,6 +3,7 @@ import type { EventLogReader } from './log.js';
 import type { PendingToolCall } from './permission.js';
 import type { ProviderRequest } from './provider.js';
 import type { SessionId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
 import type { ServiceRegistry } from './services.js';
 
 export interface AppContext {
@@ -10,6 +11,13 @@ export interface AppContext {
   readonly cwd: string;
   readonly log: EventLogReader;
   readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Who the session is attributed to, when the surface could establish it.
+   * This is what lets a policy or audit hook answer "who is asking" instead of
+   * only "what is being asked". Absent means unattributed: a hook that gates on
+   * identity must fail closed on `undefined` rather than assuming an admin.
+   */
+  readonly actor?: Principal;
   /**
    * Inter-plugin service registry — publish a service in `onInit` for sibling
    * plugins to consume in theirs. See {@link ServiceRegistry}.

package/src/host-credential.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { hostCredentialName } from './secret-provider.js';
+
+describe('hostCredentialName', () => {
+  it('upper-snakes a host, mirroring the provider-key convention', () => {
+    expect(hostCredentialName('github.example.com')).toBe('MOXXY_CREDENTIAL_GITHUB_EXAMPLE_COM');
+  });
+
+  it('accepts a full URL and uses only its host', () => {
+    expect(hostCredentialName('https://registry.example.internal/moxxy/index.json')).toBe(
+      'MOXXY_CREDENTIAL_REGISTRY_EXAMPLE_INTERNAL',
+    );
+  });
+
+  // A credential belongs to the host, not to a socket, so the same secret
+  // serves the mirror whether or not the URL happens to name a port.
+  it('ignores the port', () => {
+    expect(hostCredentialName('registry.internal:8443')).toBe(hostCredentialName('registry.internal'));
+    expect(hostCredentialName('https://registry.internal:8443/x')).toBe(
+      hostCredentialName('registry.internal'),
+    );
+  });
+
+  it('collapses runs of non-alphanumerics and trims the edges', () => {
+    expect(hostCredentialName('my--host..internal')).toBe('MOXXY_CREDENTIAL_MY_HOST_INTERNAL');
+  });
+
+  it('handles an IPv6 literal', () => {
+    expect(hostCredentialName('https://[::1]:9000/x')).toBe('MOXXY_CREDENTIAL_1');
+  });
+
+  // Deriving a name from garbage would silently look up the wrong secret, which
+  // reads as "no credential configured" rather than as the typo it is.
+  it('returns null rather than a name derived from nonsense', () => {
+    for (const bad of ['', '   ', 'not a host', 'https://', '://x']) {
+      expect(hostCredentialName(bad)).toBeNull();
+    }
+  });
+});

package/src/index.ts

@@ -42,6 +42,50 @@ export type {
 
 export type { EventLogReader } from './log.js';
 
+// Identity. The type + pure helpers ride the main barrel; the OS resolver needs
+// `node:os` and is exported from `@moxxy/sdk/server`.
+export type { Principal } from './principal.js';
+export { samePrincipal, formatPrincipal } from './principal.js';
+
+export { verifyEd25519 } from './signature.js';
+
+export { TOOL_ICONS, isToolIcon, type ToolIcon } from './tool-icon.js';
+
+export type {
+  AuditExporterDef,
+  AuditExportBatch,
+  AuditExportContext,
+  AuditExportResource,
+} from './audit-export.js';
+export { defineAuditExporter } from './audit-export.js';
+
+// Audit trail: the tamper-evident receipt, distinct from the event log.
+export type {
+  AuditAction,
+  AuditRecord,
+  AuditSinkDef,
+  AuditSinkScope,
+  AuditSinkSession,
+  UnchainedAuditRecord,
+} from './audit.js';
+export { defineAuditSink, auditActionOf } from './audit.js';
+
+// Where a named secret comes from (external store instead of the local vault).
+export type {
+  SecretProviderDef,
+  SecretProviderScope,
+  SecretProviderSession,
+} from './secret-provider.js';
+export { defineSecretProvider, hostCredentialName } from './secret-provider.js';
+
+// Secret redaction for anything leaving the process.
+export {
+  isSecretKey,
+  redactSecrets,
+  redactSecretText,
+  REDACTED_PLACEHOLDER,
+} from './redact.js';
+
 export type {
   RunTurnOptions,
   SessionLogReader,
@@ -217,6 +261,11 @@ export {
   type ResolvedProviderTools,
 } from './provider-tool-utils.js';
 export type { WriteFileAtomicOptions } from './fs-utils.js';
+export type {
+  EgressProxySettings,
+  EgressStatus,
+  InstallEgressProxyOptions,
+} from './egress.js';
 export type { ChannelRunStatus } from './channel-status.js';
 export type { CrossProcessFireLock, CrossProcessFireLockOptions } from './cross-process-lock.js';
 export { createMutex, type Mutex } from './mutex.js';