@zackbart/connecta 0.7.9 → 0.8.1

package/src/retired-toolkits.ts

@@ -0,0 +1,14 @@
+const hasOwn = (value: object, key: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/** Fail loudly when JavaScript callers pass the retired audience-scoping keys. */
+export function assertNoRetiredToolkitOptions(
+  source: string,
+  options: object,
+): void {
+  if (!hasOwn(options, "toolkits") && !hasOwn(options, "unscoped")) return;
+  throw new Error(
+    `${source} options \`toolkits\` and \`unscoped\` were removed in issue ` +
+      "#178. Deploy one connecta instance per audience instead; see ethos.md.",
+  );
+}

package/src/routes/activity.ts

@@ -0,0 +1,215 @@
+import {
+  InvalidActivityCursorError,
+  type ActivityActor,
+  type ActivityPage,
+  type ActivityReadPage,
+} from "../activity.js";
+import type { InboundAuth } from "../types.js";
+import {
+  activityActorNamespace,
+  authorize,
+  privateJson,
+  type RouteContext,
+} from "./shared.js";
+
+const ACTIVITY_LABEL_CONCURRENCY = 8;
+const ACTIVITY_LABEL_PAGE_BUDGET_MS = 1_500;
+const ACTIVITY_LABEL_MAX_LENGTH = 160;
+
+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 entry = queue[next++];
+        if (!entry) return;
+        const [key, identity] = entry;
+        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,
+      };
+    }),
+  };
+}
+
+export async function routeActivity(
+  context: RouteContext,
+): Promise<Response | null> {
+  const { path, request, url, baseUrl, opts } = context;
+  if (path !== "/ui/activity") return null;
+  if (request.method !== "GET") {
+    return privateJson({ error: "method not allowed" }, { status: 405 });
+  }
+  const authz = await authorize(request, baseUrl, opts.auth);
+  if (!authz.ok) return authz.response;
+  if (
+    opts.activityReadGate &&
+    !(await opts.activityReadGate(authz.actor))
+  ) {
+    return privateJson({ error: "forbidden" }, { status: 403 });
+  }
+  if (!opts.activity?.list) {
+    return privateJson(
+      { error: "activity history is not configured" },
+      { status: 404 },
+    );
+  }
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+  if (cursor && cursor.length > 500) {
+    return privateJson({ error: "invalid cursor" }, { status: 400 });
+  }
+  const requestedLimit = Number(url.searchParams.get("limit") ?? "50");
+  const limit = Number.isFinite(requestedLimit)
+    ? Math.min(100, Math.max(1, Math.trunc(requestedLimit)))
+    : 50;
+  try {
+    const page = await opts.activity.list({
+      ...(cursor !== undefined ? { cursor } : {}),
+      limit,
+    });
+    return privateJson(await enrichActivityActorLabels(page, opts.auth));
+  } catch (error) {
+    if (error instanceof InvalidActivityCursorError) {
+      return privateJson({ error: error.message }, { status: 400 });
+    }
+    opts.logger.error("[connecta] activity read failed", error);
+    return privateJson(
+      { error: "activity history is temporarily unavailable" },
+      { status: 503 },
+    );
+  }
+}

package/src/routes/credentials.ts

@@ -0,0 +1,254 @@
+import {
+  credentialTestRule,
+  describeCredentialTestMismatch,
+  storedCredentialShape,
+} from "../credentials.js";
+import type {
+  ConnectorCredentialConfig,
+  ConnectorCredentialValues,
+} from "../types.js";
+import {
+  authorizeUiAdmin,
+  isSameOrigin,
+  msg,
+  privateJson,
+  type RouteContext,
+} from "./shared.js";
+
+type CredentialInput =
+  | { kind: "single"; value: string }
+  | { kind: "multiple"; values: ConnectorCredentialValues };
+
+async function readCredentialInput(
+  request: Request,
+  config: ConnectorCredentialConfig,
+): Promise<
+  { ok: true; input: CredentialInput } | { ok: false; response: Response }
+> {
+  if (
+    !request.headers
+      .get("content-type")
+      ?.toLowerCase()
+      .startsWith("application/json")
+  ) {
+    return {
+      ok: false,
+      response: privateJson(
+        { error: "Content-Type must be application/json" },
+        { status: 415 },
+      ),
+    };
+  }
+  const raw = await request.text();
+  if (raw.length > 20_000) {
+    return {
+      ok: false,
+      response: privateJson(
+        { error: "request body is too large" },
+        { status: 413 },
+      ),
+    };
+  }
+  try {
+    const body = JSON.parse(raw) as {
+      value?: unknown;
+      values?: unknown;
+    };
+    if (!config.fields?.length) {
+      if (typeof body.value !== "string" || !body.value.trim()) {
+        return {
+          ok: false,
+          response: privateJson(
+            { error: "value must be a non-empty string" },
+            { status: 400 },
+          ),
+        };
+      }
+      return { ok: true, input: { kind: "single", value: body.value } };
+    }
+    if (
+      !body.values ||
+      typeof body.values !== "object" ||
+      Array.isArray(body.values)
+    ) {
+      return {
+        ok: false,
+        response: privateJson(
+          { error: "values must be an object" },
+          { status: 400 },
+        ),
+      };
+    }
+    const rawValues = body.values as Record<string, unknown>;
+    const expected = new Set(config.fields.map((field) => field.name));
+    const unexpected = Object.keys(rawValues).find(
+      (field) => !expected.has(field),
+    );
+    if (unexpected) {
+      return {
+        ok: false,
+        response: privateJson(
+          { error: `unexpected credential field "${unexpected}"` },
+          { status: 400 },
+        ),
+      };
+    }
+    const values: ConnectorCredentialValues = {};
+    for (const field of config.fields) {
+      const value = rawValues[field.name];
+      if (typeof value !== "string" || !value.trim()) {
+        return {
+          ok: false,
+          response: privateJson(
+            { error: `${field.name} must be a non-empty string` },
+            { status: 400 },
+          ),
+        };
+      }
+      values[field.name] = value;
+    }
+    return { ok: true, input: { kind: "multiple", values } };
+  } catch {
+    return {
+      ok: false,
+      response: privateJson({ error: "invalid JSON body" }, { status: 400 }),
+    };
+  }
+}
+
+async function handleCredentialRequest(
+  context: RouteContext,
+  connectorId: string,
+  action: string | undefined,
+): Promise<Response> {
+  const { request, baseUrl, opts } = context;
+  if (!opts.credentialVault) {
+    return privateJson(
+      { error: "credential storage is not configured" },
+      { status: 503 },
+    );
+  }
+  if (!isSameOrigin(request, baseUrl)) {
+    return privateJson(
+      { error: "same-origin request required" },
+      { status: 403 },
+    );
+  }
+  const admin = await authorizeUiAdmin(
+    request,
+    baseUrl,
+    opts.auth,
+  );
+  if (!admin.ok) return admin.response;
+
+  const connector = opts.registry.getConnector(connectorId);
+  if (!connector?.credential) {
+    return privateJson({ error: "unknown credential slot" }, { status: 404 });
+  }
+
+  if (action === "test") {
+    if (request.method !== "POST") {
+      return privateJson({ error: "method not allowed" }, { status: 405 });
+    }
+    // The declared credential shape picks the hook — the same single rule the
+    // Credentials page asks for its Test affordance, so a shown button reaches
+    // that reads the shape the credential was stored in.
+    const rule = credentialTestRule(connector);
+    if (!rule.mode) {
+      return privateJson(
+        {
+          error: rule.mismatch
+            ? "this connector cannot test its credential: " +
+              describeCredentialTestMismatch(rule.mismatch)
+            : "this connector does not support credential testing",
+        },
+        { status: 400 },
+      );
+    }
+    try {
+      const values = await opts.credentialVault.getAll(connectorId);
+      const shape = storedCredentialShape(connector.credential, values);
+      if (shape.state === "missing") {
+        return privateJson(
+          {
+            error:
+              rule.mode === "multiple"
+                ? "configure the credentials before testing them"
+                : "configure the credential before testing it",
+          },
+          { status: 409 },
+        );
+      }
+      if (shape.state === "mismatch") {
+        return privateJson({ error: shape.message }, { status: 409 });
+      }
+      const storedValues = values!;
+      const ctx = opts.registry.contextFor(connectorId, baseUrl);
+      const result =
+        rule.mode === "multiple"
+          ? await connector.testCredentials!(storedValues, ctx)
+          : await connector.testCredential!(
+              // The single-value shape check above guarantees this key.
+              storedValues.value!,
+              ctx,
+            );
+      return privateJson(result);
+    } catch (err) {
+      return privateJson({ ok: false, message: msg(err) });
+    }
+  }
+
+  if (action) {
+    return privateJson({ error: "not found" }, { status: 404 });
+  }
+  if (request.method === "PUT") {
+    const input = await readCredentialInput(request, connector.credential);
+    if (!input.ok) return input.response;
+    try {
+      const metadata =
+        input.input.kind === "single"
+          ? await opts.credentialVault.set(
+              connectorId,
+              input.input.value,
+              admin.userId,
+            )
+          : await opts.credentialVault.setAll(
+              connectorId,
+              input.input.values,
+              admin.userId,
+            );
+      await opts.registry.invalidateStored(connectorId);
+      return privateJson({ credential: metadata });
+    } catch (err) {
+      return privateJson({ error: msg(err) }, { status: 400 });
+    }
+  }
+  if (request.method === "DELETE") {
+    await opts.credentialVault.delete(connectorId);
+    await opts.registry.invalidateStored(connectorId);
+    return new Response(null, {
+      status: 204,
+      headers: {
+        "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer",
+      },
+    });
+  }
+  return privateJson({ error: "method not allowed" }, { status: 405 });
+}
+
+export async function routeCredentials(
+  context: RouteContext,
+): Promise<Response | null> {
+  const match =
+    /^\/ui\/credentials\/([a-z0-9_-]+)(?:\/([a-z]+))?$/.exec(context.path);
+  if (!match) return null;
+  const connectorId = match[1];
+  if (!connectorId) return null;
+  // Never opt these mutation routes into the server's wildcard CORS
+  // preflight behavior.
+  if (context.request.method === "OPTIONS") {
+    return privateJson({ error: "method not allowed" }, { status: 405 });
+  }
+  return handleCredentialRequest(context, connectorId, match[2]);
+}