fix(runtime): harden boundaries and simplify tooling (oomol-lab#169)

## Summary

- fail closed across runtime auth, DNS validation, provider egress, and
proxy errors
- coalesce concurrent OAuth refreshes and remove the MCP
connection-summary N+1 reads
- preserve provider schema fields and tighten Twitter media action
contracts
- replace hand-written CLI parsing and remove implementation-detail web
tests

## Verification

- `npm run generate:catalog`
- `npm run fix-check`
- `npm test` (507 tests)
- `npm run build:web`
- `git diff --check`

Author: hyrious

examples/local-http/client.ts

@@ -11,10 +11,9 @@ function bearerHeaders(token: string | undefined, headers: HeadersInit): Headers
     return headers;
   }
 
-  return {
-    ...headers,
-    authorization: `Bearer ${token}`,
-  };
+  const authenticatedHeaders = new Headers(headers);
+  authenticatedHeaders.set("authorization", `Bearer ${token}`);
+  return authenticatedHeaders;
 }
 
 export async function fetchJson<T>(url: string, init: RequestInit = {}): Promise<T> {

scripts/runtime-data.ts

@@ -1,78 +1,58 @@
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
 import { createSecretCodec } from "../src/server/secrets/secret-codec.ts";
 import { SqliteRuntimeDatabase } from "../src/server/storage/sqlite-runtime-store.ts";
 
-const command = process.argv[2];
-const options = parseOptions(process.argv.slice(3));
-const dataDir = resolve(options.dataDir ?? process.env.OOMOL_CONNECT_DATA_DIR ?? join(process.cwd(), "data"));
-const databasePath = join(dataDir, "connect.sqlite");
-const secretCodec = createSecretCodec(process.env.OOMOL_CONNECT_ENCRYPTION_KEY);
+const { positionals, values: options } = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    "data-dir": { type: "string" },
+    plain: { type: "boolean" },
+    yes: { type: "boolean" },
+  },
+  strict: true,
+});
+const [command] = positionals;
 
-if (!command || !["reset", "rotate-key"].includes(command)) {
+if (positionals.length !== 1 || (command !== "reset" && command !== "rotate-key")) {
   printUsageAndExit();
 }
 
-await mkdir(dataDir, { recursive: true });
-
+const nextEncryptionKey = process.env.OOMOL_CONNECT_NEW_ENCRYPTION_KEY;
 if (command === "rotate-key") {
-  const nextEncryptionKey = process.env.OOMOL_CONNECT_NEW_ENCRYPTION_KEY;
-  if (!nextEncryptionKey && options.plain !== "true") {
-    throw new Error("rotate-key requires OOMOL_CONNECT_NEW_ENCRYPTION_KEY unless --plain is set.");
+  if (options.yes) {
+    throw new Error("--yes is only valid with reset.");
   }
-  const database = new SqliteRuntimeDatabase(databasePath, { secretCodec });
-  try {
-    await database.rotateSecretCodec(createSecretCodec(options.plain === "true" ? undefined : nextEncryptionKey));
-    console.log(`Rotated runtime secret encryption in ${databasePath}.`);
-  } finally {
-    database.close();
+  if (!nextEncryptionKey && !options.plain) {
+    throw new Error("rotate-key requires OOMOL_CONNECT_NEW_ENCRYPTION_KEY unless --plain is set.");
   }
 } else {
-  const database = new SqliteRuntimeDatabase(databasePath, { secretCodec });
-  try {
-    if (options.yes !== "true") {
-      throw new Error("reset requires --yes.");
-    }
-    database.resetRuntimeData();
-    console.log(`Reset runtime data in ${databasePath}.`);
-  } finally {
-    database.close();
+  if (options.plain) {
+    throw new Error("--plain is only valid with rotate-key.");
+  }
+  if (!options.yes) {
+    throw new Error("reset requires --yes.");
   }
 }
 
-type RuntimeDataCommandOptions = {
-  dataDir?: string;
-  plain?: string;
-  yes?: string;
-};
-
-function parseOptions(args: string[]): RuntimeDataCommandOptions {
-  const options: RuntimeDataCommandOptions = {};
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--yes") {
-      options.yes = "true";
-      continue;
-    }
-    if (arg === "--plain") {
-      options.plain = "true";
-      continue;
-    }
-
-    const value = args[index + 1];
-    if (!value) {
-      throw new Error(`${arg} requires a value.`);
-    }
+const dataDir = resolve(options["data-dir"] ?? process.env.OOMOL_CONNECT_DATA_DIR ?? join(process.cwd(), "data"));
+const databasePath = join(dataDir, "connect.sqlite");
+const secretCodec = createSecretCodec(process.env.OOMOL_CONNECT_ENCRYPTION_KEY);
+await mkdir(dataDir, { recursive: true });
 
-    if (arg === "--data-dir") {
-      options.dataDir = value;
-    } else {
-      throw new Error(`Unknown option: ${arg}.`);
-    }
-    index += 1;
+const database = new SqliteRuntimeDatabase(databasePath, { secretCodec });
+try {
+  if (command === "rotate-key") {
+    await database.rotateSecretCodec(createSecretCodec(options.plain ? undefined : nextEncryptionKey));
+    console.log(`Rotated runtime secret encryption in ${databasePath}.`);
+  } else {
+    database.resetRuntimeData();
+    console.log(`Reset runtime data in ${databasePath}.`);
   }
-
-  return options;
+} finally {
+  database.close();
 }
 
 function printUsageAndExit(): never {

scripts/search-actions.ts

@@ -1,56 +1,34 @@
+import { parseArgs } from "node:util";
 import { loadCatalog } from "../src/catalog-store.ts";
 import { DEFAULT_ACTION_SEARCH_LIMIT, buildActionSearchIndex, searchActions } from "../src/core/action-search.ts";
 
-const options = parseOptions(process.argv.slice(2));
+const { values: options } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    limit: { type: "string" },
+    query: { type: "string", short: "q" },
+    service: { type: "string" },
+  },
+  strict: true,
+});
 if (!options.query) {
   printUsageAndExit();
 }
 
+const limit = options.limit == null ? DEFAULT_ACTION_SEARCH_LIMIT : Number(options.limit);
+if (!Number.isInteger(limit) || limit < 1) {
+  throw new Error("--limit must be a positive integer.");
+}
+
 const catalog = await loadCatalog();
 const index = buildActionSearchIndex(catalog.actions);
 const results = searchActions(index, options.query, {
   service: options.service,
-  limit: options.limit ?? DEFAULT_ACTION_SEARCH_LIMIT,
+  limit,
 });
 
 console.log(JSON.stringify(results, null, 2));
 
-interface SearchActionOptions {
-  query?: string;
-  service?: string;
-  limit?: number;
-}
-
-function parseOptions(args: string[]): SearchActionOptions {
-  const options: SearchActionOptions = {};
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    const value = args[index + 1];
-    if (arg === "--query" || arg === "-q") {
-      options.query = requireValue(arg, value);
-    } else if (arg === "--service") {
-      options.service = requireValue(arg, value);
-    } else if (arg === "--limit") {
-      const limit = Number(requireValue(arg, value));
-      if (!Number.isInteger(limit) || limit < 1) {
-        throw new Error("--limit must be a positive integer.");
-      }
-      options.limit = limit;
-    } else {
-      throw new Error(`Unknown option: ${arg}`);
-    }
-    index += 1;
-  }
-  return options;
-}
-
-function requireValue(option: string, value: string | undefined): string {
-  if (!value) {
-    throw new Error(`${option} requires a value.`);
-  }
-  return value;
-}
-
 function printUsageAndExit(): never {
   console.error(`Usage:
   node scripts/search-actions.ts --query "send mail gmail" [--service gmail] [--limit 10]`);

src/connection-service.test.ts

@@ -490,6 +490,46 @@ describe("ConnectionService", () => {
     );
   });
 
+  it("shares an in-flight OAuth refresh across concurrent requests", async () => {
+    const store = new MemoryConnectionStore();
+    const oauthClientConfigs = createOAuthClientConfigs([oauthProvider]);
+    const service = createService([oauthProvider], {
+      oauthCredentials: new OAuthCredentialRefreshService(oauthClientConfigs),
+      store,
+    });
+    await oauthClientConfigs.upsertConfig({
+      service: "example",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+    });
+    await store.set("example", "default", {
+      authType: "oauth2",
+      accessToken: "expired-token",
+      tokenType: "Bearer",
+      refreshToken: "refresh-token",
+      expiresAt: "2026-01-01T00:00:00.000Z",
+      profile: testProfile,
+      metadata: {},
+    });
+
+    const fetcher = vi.fn(async () =>
+      Response.json({
+        access_token: "fresh-token",
+        expires_in: 3600,
+        token_type: "Bearer",
+      }),
+    );
+    vi.stubGlobal("fetch", fetcher);
+
+    const credentials = await Promise.all([service.getCredential("example"), service.getCredential("example")]);
+
+    expect(credentials).toEqual([
+      expect.objectContaining({ accessToken: "fresh-token" }),
+      expect.objectContaining({ accessToken: "fresh-token" }),
+    ]);
+    expect(fetcher).toHaveBeenCalledOnce();
+  });
+
   it("does not overwrite a connection recreated during OAuth refresh", async () => {
     const store = new MemoryConnectionStore();
     const oauthClientConfigs = createOAuthClientConfigs([oauthProvider]);

src/connection-service.ts

@@ -107,6 +107,7 @@ interface PreviousCredentialRuntimeData {
 }
 
 type CredentialValidatorCall = () => Promise<CredentialValidationResult | void> | undefined;
+type OAuthCredential = Extract<ResolvedCredential, { authType: "oauth2" }>;
 
 /**
  * Coordinates local provider connection state.
@@ -116,6 +117,7 @@ type CredentialValidatorCall = () => Promise<CredentialValidationResult | void>
  */
 export class ConnectionService {
   private readonly catalog: CatalogStore;
+  private readonly oauthCredentialRefreshes = new Map<string, Promise<OAuthCredential>>();
   private readonly oauthCredentials?: IOAuthCredentialRefresher;
   private readonly providerLoader: IProviderLoader;
   private readonly store: IConnectionStore;
@@ -492,9 +494,9 @@ export class ConnectionService {
 
   private async resolveOAuthCredential(
     connection: StoredConnection,
-    credential: Extract<ResolvedCredential, { authType: "oauth2" }>,
-  ): Promise<Extract<ResolvedCredential, { authType: "oauth2" }>> {
-    const { id, service, connectionName } = connection;
+    credential: OAuthCredential,
+  ): Promise<OAuthCredential> {
+    const service = connection.service;
     if (!isOAuthCredentialExpired(credential)) {
       return credential;
     }
@@ -513,7 +515,29 @@ export class ConnectionService {
       );
     }
 
-    const nextCredential = await this.oauthCredentials.refresh(service, credential);
+    const currentRefresh = this.oauthCredentialRefreshes.get(connection.id);
+    if (currentRefresh) {
+      return currentRefresh;
+    }
+
+    const refresh = this.refreshOAuthCredential(connection, credential, this.oauthCredentials);
+    this.oauthCredentialRefreshes.set(connection.id, refresh);
+    try {
+      return await refresh;
+    } finally {
+      if (this.oauthCredentialRefreshes.get(connection.id) === refresh) {
+        this.oauthCredentialRefreshes.delete(connection.id);
+      }
+    }
+  }
+
+  private async refreshOAuthCredential(
+    connection: StoredConnection,
+    credential: OAuthCredential,
+    refresher: IOAuthCredentialRefresher,
+  ): Promise<OAuthCredential> {
+    const { id, service, connectionName } = connection;
+    const nextCredential = await refresher.refresh(service, credential);
     const updated = await this.store.updateCredential({ id, service, connectionName, credential: nextCredential });
     if (!updated) {
       throw new ConnectionError(

src/core/guarded-fetch.test.ts

@@ -407,6 +407,14 @@ describe("createGuardedFetch resolved-address validation", () => {
     expect(calls).toHaveLength(0);
   });
 
+  it("fails closed when an enabled lookup returns no addresses", async () => {
+    const { transport, calls } = createTransport([]);
+    const guarded = createGuardedFetch({ fetch: transport, lookup: async () => [] });
+
+    await expect(guarded("https://unresolved.example.com/")).rejects.toThrow(/could not be resolved/u);
+    expect(calls).toHaveLength(0);
+  });
+
   it("re-validates resolved addresses for every redirect hop", async () => {
     const { transport, calls } = createTransport([redirectTo("https://metadata.attacker.com/creds")]);
     const guarded = createGuardedFetch({

src/core/guarded-fetch.ts

@@ -297,6 +297,9 @@ async function assertResolvedAddressesAllowed(
   if (!Array.isArray(results)) {
     throw policy.createError(`${fieldName} could not be resolved for validation`);
   }
+  if (results.length === 0) {
+    throw policy.createError(`${fieldName} could not be resolved for validation`);
+  }
   for (const entry of results) {
     if (entry && typeof entry.address === "string" && isBlockedIpAddress(entry.address, policy.allowPrivateNetwork)) {
       throw policy.createError(`${fieldName} must not resolve to private or reserved IP addresses`);

src/core/json-schema.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { jsonSchema } from "./json-schema.ts";
+
+describe("jsonSchema.looseObject", () => {
+  it("keeps properties whose names overlap schema option names", () => {
+    expect(
+      jsonSchema.looseObject(
+        "A provider payload.",
+        {
+          default: jsonSchema.boolean("Whether this is the default item."),
+          description: jsonSchema.string("The provider description."),
+          format: jsonSchema.string("The provider format."),
+        },
+        { default: {} },
+      ),
+    ).toEqual({
+      type: "object",
+      properties: {
+        default: { type: "boolean", description: "Whether this is the default item." },
+        description: { type: "string", description: "The provider description." },
+        format: { type: "string", description: "The provider format." },
+      },
+      additionalProperties: true,
+      description: "A provider payload.",
+      default: {},
+    });
+  });
+});

src/core/json-schema.ts

@@ -273,14 +273,12 @@ export const jsonSchema = {
   ): JsonSchema {
     const properties =
       typeof propertiesOrDescription === "string"
-        ? isJsonSchemaOptions(optionsOrProperties)
-          ? {}
-          : optionsOrProperties
+        ? (optionsOrProperties as Record<string, JsonSchema>)
         : propertiesOrDescription;
     const resolvedOptions =
       typeof propertiesOrDescription === "string"
         ? {
-            ...(isJsonSchemaOptions(optionsOrProperties) ? optionsOrProperties : maybeOptions),
+            ...maybeOptions,
             description: propertiesOrDescription,
           }
         : (optionsOrProperties as JsonSchemaOptions);
@@ -351,7 +349,3 @@ function withOptions(schema: JsonSchema, options: JsonSchemaOptions): JsonSchema
   if (options.format) schema.format = options.format;
   return schema;
 }
-
-function isJsonSchemaOptions(value: JsonSchemaOptions | Record<string, JsonSchema>): value is JsonSchemaOptions {
-  return "description" in value || "default" in value || "format" in value;
-}