@zackbart/connecta 0.7.6 → 0.7.7

package/src/server.ts

@@ -5,7 +5,9 @@ import { registerMetaTools } from "./meta-tools.js";
 import { CONNECTA_INSTRUCTIONS } from "./skills.js";
 import type {
   ActivityActor,
+  ActivityPage,
   ActivityReadGate,
+  ActivityReadPage,
   ActivityRequestContext,
   ActivityStore,
 } from "./activity.js";
@@ -26,6 +28,7 @@ import type {
   ConnectorContext,
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
+  ConnectorStatus,
   ConnectaBranding,
   Executor,
   InboundAuth,
@@ -43,10 +46,16 @@ import {
   buildUiData,
   CONNECTA_FAVICON_SVG,
   credentialManagementCapability,
+  isSafeHttpUrl,
   operatorPageForPath,
   resolveBranding,
   renderUiHtml,
 } from "./ui.js";
+import { oauthValueStorageKey } from "./auth/downstream-oauth.js";
+import {
+  closeConnectorScope,
+  type DeferredWork,
+} from "./connector-scope.js";
 
 const CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
@@ -263,11 +272,15 @@ async function authorize(
         );
         return { ok: false, response: unusableBinding() };
       }
+      const actorNamespace = activityActorNamespace(provider);
       return {
         ok: true,
         actor: {
           kind: provider.kind,
           ...(subjectId ? { id: subjectId } : {}),
+          ...(subjectId && actorNamespace
+            ? { namespace: actorNamespace }
+            : {}),
         },
         ...(result.userId && provider.uiAuth?.kind === "clerk"
           ? { uiAdminEligible: true }
@@ -446,10 +459,11 @@ async function authorizeUiAdmin(
   baseUrl: string,
   auth: InboundAuth[],
   logger: Logger,
+  purpose = "credential management",
 ): Promise<{ ok: true; userId: string } | { ok: false; response: Response }> {
-  // Credential mutation is intentionally narrower than /mcp and /ui/data: only
+  // Operator mutation is intentionally narrower than /mcp and /ui/data: only
   // an interactive Clerk provider may admit it. A static bearer token is useful
-  // for headless tool calls but must not become a vault-admin key.
+  // for headless tool calls but must not become a deployment-admin key.
   //
   // EVERY Clerk provider gets a turn, the way the /mcp gate does, because the
   // documented per-team pattern is several `clerkAuth(...)`s that differ only in
@@ -465,7 +479,7 @@ async function authorizeUiAdmin(
     return {
       ok: false,
       response: privateJson(
-        { error: "credential management requires Clerk authentication" },
+        { error: `${purpose} requires Clerk authentication` },
         { status: 403 },
       ),
     };
@@ -490,7 +504,7 @@ async function authorizeUiAdmin(
     );
     if (!binding.ok) {
       logger.warn(
-        `[connecta] refused a credential-API request admitted by inbound auth ` +
+        `[connecta] refused an operator-mutation request admitted by inbound auth ` +
           `provider "${provider.kind}" with 403: ${binding.reason}.`,
       );
       lastResponse = unusableBinding();
@@ -732,7 +746,7 @@ async function handleCredentialRequest(
               input.input.values,
               admin.userId,
             );
-      opts.registry.invalidate(connectorId);
+      await opts.registry.invalidateStored(connectorId);
       // The credential the last verdict judged is gone; judging its replacement
       // is the next check's job, not this one's.
       await opts.registry.clearCredentialHealth(connectorId);
@@ -744,7 +758,7 @@ async function handleCredentialRequest(
 
   if (request.method === "DELETE") {
     await opts.credentialVault.delete(connectorId);
-    opts.registry.invalidate(connectorId);
+    await opts.registry.invalidateStored(connectorId);
     await opts.registry.clearCredentialHealth(connectorId);
     return new Response(null, {
       status: 204,
@@ -758,6 +772,105 @@ async function handleCredentialRequest(
   return privateJson({ error: "method not allowed" }, { status: 405 });
 }
 
+async function handleOAuthManagementRequest(
+  request: Request,
+  connectorId: string,
+  opts: ServerOptions,
+  baseUrl: string,
+  defer?: DeferredWork,
+): Promise<Response> {
+  if (!isSameOrigin(request, baseUrl)) {
+    return privateJson(
+      { error: "same-origin request required" },
+      { status: 403 },
+    );
+  }
+  const admin = await authorizeUiAdmin(
+    request,
+    baseUrl,
+    opts.auth,
+    opts.logger,
+    "OAuth management",
+  );
+  if (!admin.ok) return admin.response;
+
+  const connector = opts.registry.getConnector(connectorId);
+  if (!connector?.disconnectAuth || !connector.startAuth) {
+    return privateJson(
+      { error: "unknown OAuth connector" },
+      { status: 404 },
+    );
+  }
+  if (request.method !== "DELETE" && request.method !== "POST") {
+    return privateJson({ error: "method not allowed" }, { status: 405 });
+  }
+
+  const requestScope = {};
+  const ctx = opts.registry.contextFor(connectorId, baseUrl, requestScope);
+  try {
+    let result: ConnectorStatus | undefined;
+    let operationError: unknown;
+    try {
+      if (request.method === "DELETE") {
+        await connector.disconnectAuth(ctx);
+      } else {
+        result = await connector.startAuth(ctx, { force: true });
+      }
+    } catch (error) {
+      operationError = error;
+    }
+
+    // The old grant and its catalog verdict are invalid after either operation,
+    // including a partially failed physical cleanup whose epoch fence succeeded.
+    try {
+      await opts.registry.invalidateStored(connectorId);
+      await opts.registry.clearCredentialHealth(connectorId);
+    } catch (error) {
+      operationError ??= error;
+    }
+    if (operationError) {
+      return privateJson({ error: msg(operationError) }, { status: 400 });
+    }
+
+    if (request.method === "DELETE") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          "Cache-Control": "no-store",
+          "Referrer-Policy": "no-referrer",
+        },
+      });
+    }
+
+    const authorizationUrl = isSafeHttpUrl(result!.authorizationUrl)
+      ? result!.authorizationUrl
+      : undefined;
+    if (result!.state === "error") {
+      return privateJson(
+        { error: result!.message || "OAuth authorization could not start" },
+        { status: 502 },
+      );
+    }
+    if (result!.state === "auth_required" && !authorizationUrl) {
+      return privateJson(
+        {
+          error:
+            result!.message ||
+            "OAuth authorization requires consent but no safe URL is available",
+        },
+        { status: 502 },
+      );
+    }
+    return privateJson({
+      state: result!.state,
+      ...(result!.message ? { message: result!.message } : {}),
+      ...(authorizationUrl ? { authorizationUrl } : {}),
+    });
+  } finally {
+    await closeConnectorScope(connector, ctx, defer);
+  }
+}
+
 /** Length beyond which a rejected toolkit name is not echoed back. */
 const MAX_ECHOED_TOOLKIT_NAME = 64;
 
@@ -823,6 +936,165 @@ function identityLabel(actor: ActivityActor): string {
   return actor.id ? `${actor.kind} ${loggableValue(actor.id)}` : actor.kind;
 }
 
+const ACTIVITY_ACTOR_NAMESPACE_RE = /^[\x21-\x7e]{1,256}$/;
+const ACTIVITY_LABEL_CONCURRENCY = 8;
+const ACTIVITY_LABEL_PAGE_BUDGET_MS = 1_500;
+const ACTIVITY_LABEL_MAX_LENGTH = 160;
+
+function activityActorNamespace(
+  provider: InboundAuth,
+): string | undefined {
+  return typeof provider.activityActorNamespace === "string" &&
+    ACTIVITY_ACTOR_NAMESPACE_RE.test(provider.activityActorNamespace)
+    ? provider.activityActorNamespace
+    : undefined;
+}
+
+function cleanActivityActorLabel(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const compact = value.replace(/\s+/gu, " ").trim();
+  if (!compact) return undefined;
+  return Array.from(compact).slice(0, ACTIVITY_LABEL_MAX_LENGTH).join("");
+}
+
+async function boundedActivityActorLabel(
+  hook: NonNullable<InboundAuth["activityActorLabel"]>,
+  id: string,
+  budgetMs: number,
+): Promise<string | undefined> {
+  let timer: number | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve(hook(id))
+        .then(cleanActivityActorLabel)
+        .catch(() => undefined),
+      new Promise<undefined>((resolve) => {
+        timer = setTimeout(resolve, budgetMs);
+      }),
+    ]);
+  } catch {
+    return undefined;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * Add display-only actor labels to one authorized activity page. Resolution is
+ * best-effort, bounded, and read-time only: stored events retain stable ids and
+ * a profile-provider outage falls back to those ids without failing the page.
+ */
+async function enrichActivityActorLabels(
+  page: ActivityPage,
+  auth: readonly InboundAuth[],
+): Promise<ActivityReadPage> {
+  const identities = new Map<
+    string,
+    { kind: string; id: string; namespace?: string }
+  >();
+  for (const event of page.events) {
+    if (!event.actor.id) continue;
+    identities.set(JSON.stringify([
+      event.actor.kind,
+      event.actor.namespace,
+      event.actor.id,
+    ]), {
+      kind: event.actor.kind,
+      id: event.actor.id,
+      ...(event.actor.namespace
+        ? { namespace: event.actor.namespace }
+        : {}),
+    });
+  }
+  const queue = [...identities.entries()];
+  const labels = new Map<string, string>();
+  let next = 0;
+  const deadline = Date.now() + ACTIVITY_LABEL_PAGE_BUDGET_MS;
+  const workers = Array.from(
+    { length: Math.min(ACTIVITY_LABEL_CONCURRENCY, queue.length) },
+    async () => {
+      while (next < queue.length) {
+        const [key, identity] = queue[next++];
+        const sameKindProviders = auth
+          .map((provider, index) => ({ provider, index }))
+          .filter(({ provider }) => provider.kind === identity.kind);
+        const candidates = sameKindProviders.filter(({ provider }) =>
+          Boolean(provider.activityActorLabel),
+        );
+        const eligible = identity.namespace
+          ? candidates.filter(
+              ({ provider }) =>
+                activityActorNamespace(provider) === identity.namespace,
+            )
+          : (() => {
+              const directoryKey = ({
+                provider,
+                index,
+              }: (typeof sameKindProviders)[number]) => {
+                const namespace = activityActorNamespace(provider);
+                return namespace === undefined
+                  ? `provider:${index}`
+                  : `namespace:${namespace}`;
+              };
+              // Every same-kind provider participates in the ambiguity check,
+              // even if it cannot resolve labels. Otherwise a legacy ID owned
+              // by a provider without a resolver could be disclosed to a
+              // different provider that happens to have one.
+              const directories = new Set(
+                sameKindProviders.map(directoryKey),
+              );
+              if (directories.size !== 1) return [];
+              const [directory] = directories;
+              return candidates.filter(
+                (candidate) => directoryKey(candidate) === directory,
+              );
+            })();
+        // One namespace is one directory. Use its first configured resolver so
+        // duplicate gate adapters over the same Clerk instance do not multiply
+        // the provider-level concurrency cap.
+        const provider = eligible[0]?.provider;
+        if (!provider) continue;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) return;
+        const label = await boundedActivityActorLabel(
+          provider.activityActorLabel!.bind(provider),
+          identity.id,
+          remaining,
+        );
+        if (label) {
+          labels.set(key, label);
+        }
+      }
+    },
+  );
+  await Promise.all(workers);
+  return {
+    ...page,
+    events: page.events.map((event) => {
+      const resolved = event.actor.id
+        ? labels.get(JSON.stringify([
+            event.actor.kind,
+            event.actor.namespace,
+            event.actor.id,
+          ]))
+        : undefined;
+      // Never trust or echo a `label` supplied by storage. The persisted event
+      // schema has no label; only this authenticated read path may add one.
+      const actor: ActivityActor = {
+        kind: event.actor.kind,
+        ...(event.actor.id ? { id: event.actor.id } : {}),
+        ...(event.actor.namespace
+          ? { namespace: event.actor.namespace }
+          : {}),
+      };
+      return {
+        ...event,
+        actor: resolved ? { ...actor, label: resolved } : actor,
+      };
+    }),
+  };
+}
+
 /**
  * Resolve `?toolkit=<name>` into the registry view this connection may see,
  * enforcing the caller's toolkit binding (docs/toolkits.md) on the way.
@@ -1026,17 +1298,16 @@ async function serveMcp(
  * paths that would otherwise pay nothing.
  *
  * Identical bodies do not hide a connector id if the clock still sorts them.
- * `KvOAuthProvider.verifyState` reads `oauth:state` before it can fail, so a
- * configured id costs one storage round trip — on the Workers deployment shape
- * that is a real KV read, tens of milliseconds cold — while an id that names
- * nothing used to return having touched no I/O at all. That gap is an oracle:
- * sample the two and a wordlist recovers the connector list the flat 400 was
- * meant to withhold. So the zero-I/O refusals read the same key in the same
- * `conn:<id>:` namespace, which for an unconfigured id is simply a miss.
+ * `KvOAuthProvider.verifyState` reads `oauth:state` and its generation before
+ * it can reject a mismatched value, so a configured id costs two storage round
+ * trips on the ordinary path while an id naming nothing used to touch no I/O.
+ * That gap is an oracle: sample the two and a wordlist recovers the connector
+ * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
+ * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
  *
  * This is deliberately *not* a constant-time claim, and docs/connectors.md says
  * so in prose: a hit and a miss are not identical in a KV store, and a connector
- * shipping its own `verifyState` may do more or less work than one read. What it
+ * shipping its own `verifyState` may do more or less work. What it
  * removes is the order-of-magnitude "no I/O versus a round trip" difference,
  * which is the only part of the signal that makes enumeration cheap.
  *
@@ -1046,7 +1317,10 @@ async function serveMcp(
  */
 async function equalizeRefusalCost(context: ConnectorContext): Promise<void> {
   try {
-    await context.storage.get("oauth:state");
+    const generation = await context.storage.get("oauth:generation");
+    await context.storage.get(
+      oauthValueStorageKey("oauth:state", generation),
+    );
   } catch {
     // Deliberately ignored — see above.
   }
@@ -1253,6 +1527,20 @@ export function createFetchHandler(
           baseUrl,
         );
       }
+      const oauthManagementMatch =
+        /^\/ui\/oauth\/([a-z0-9_-]+)$/.exec(path);
+      if (oauthManagementMatch) {
+        if (request.method === "OPTIONS") {
+          return privateJson({ error: "method not allowed" }, { status: 405 });
+        }
+        return handleOAuthManagementRequest(
+          request,
+          oauthManagementMatch[1],
+          opts,
+          baseUrl,
+          defer,
+        );
+      }
 
       if (request.method === "OPTIONS") {
         for (const a of auth) {
@@ -1404,6 +1692,7 @@ export function createFetchHandler(
           credentialManagement,
           opts.toolkits,
           defer,
+          eligibleClerkOperator,
         );
         return privateJson(data);
       }
@@ -1438,7 +1727,8 @@ export function createFetchHandler(
           ? Math.min(100, Math.max(1, Math.trunc(requestedLimit)))
           : 50;
         try {
-          return privateJson(await opts.activity.list({ cursor, limit }));
+          const page = await opts.activity.list({ cursor, limit });
+          return privateJson(await enrichActivityActorLabels(page, auth));
         } catch (error) {
           if (error instanceof InvalidActivityCursorError) {
             return privateJson({ error: error.message }, { status: 400 });

package/src/storage/file.ts

@@ -72,6 +72,13 @@ export function fileStorage(
     }
   }
   const persist = () => {
+    // Physical expiry rides on an operation that was already going to write.
+    // A read must not flush this instance's load-once snapshot: another live
+    // instance may have written newer unrelated values since we loaded it.
+    const now = Date.now();
+    for (const [key, entry] of Object.entries(data)) {
+      if (entry.exp && now > entry.exp) delete data[key];
+    }
     const dir = dirname(path);
     if (dir) mkdirSync(dir, { recursive: true, mode: 0o700 });
     const tmp = `${path}.tmp`;

package/src/types.ts

@@ -214,6 +214,12 @@ export interface Connector {
     ctx: ConnectorContext,
     opts?: { force?: boolean },
   ): Promise<ConnectorStatus>;
+  /**
+   * Optional: remove every stored downstream OAuth credential and pending flow
+   * without immediately starting a replacement flow. Present only on
+   * connectors whose authorization can be managed by the operator UI.
+   */
+  disconnectAuth?(ctx: ConnectorContext): Promise<void>;
   /**
    * Verify the OAuth `state` returned to /oauth/callback/<id> against the value
    * this connector generated when it started the flow. Required whenever
@@ -431,6 +437,23 @@ export interface ConnectaBranding {
 /** An inbound authentication provider (bearer token, Clerk, ...). */
 export interface InboundAuth {
   kind: string;
+  /**
+   * Stable, non-secret namespace of the identity directory behind
+   * `activityActorLabel`. Stored with new activity actors so two providers with
+   * the same `kind` never receive each other's ids. Legacy actors without a
+   * namespace are resolved only when exactly one directory is unambiguous.
+   * Must be 1–256 printable, non-space ASCII characters; invalid values are
+   * treated as an unknown directory and are not persisted.
+   */
+  activityActorNamespace?: string;
+  /**
+   * Best-effort friendly label for a stable activity actor id. Called only
+   * while serving an authorized activity read, never during tool admission or
+   * event writes. The result is display-only and cannot grant access.
+   */
+  activityActorLabel?(
+    subjectId: string,
+  ): string | undefined | Promise<string | undefined>;
   /**
    * Optional browser sign-in configuration. When present, operator pages use it
    * provider instead of asking the operator to paste a static bearer secret.