@opengeni/connect 0.2.0-canary.0

package/src/authorization.ts

@@ -0,0 +1,51 @@
+import { pollConnectAttempt } from "./poll";
+import type { ConnectAttempt, ConnectTransport } from "./types";
+
+/** Inject navigation so hosts own routing and this package needs no DOM globals. */
+export type ConnectNavigation = {
+  openPopup(url: string): { close(): void } | null;
+  redirect(url: string): void;
+};
+
+/** Invoke directly from a user gesture for popup mode. Persist the opaque
+ * attempt ID in host-owned state before redirect mode, then recover/poll on
+ * return. Neither URL parameters nor popup messages prove completion. */
+export function authorizeConnectAttempt(
+  transport: Pick<ConnectTransport, "get">,
+  attempt: ConnectAttempt,
+  navigation: ConnectNavigation,
+  options: { mode: "popup" | "redirect"; signal?: AbortSignal; timeoutMs?: number },
+): Promise<ConnectAttempt | null> {
+  options.signal?.throwIfAborted();
+  if (attempt.nextAction.type !== "authorize") {
+    throw new Error("Connect attempt does not require authorization");
+  }
+  const destination = new URL(attempt.nextAction.url);
+  if (destination.protocol !== "https:" || destination.username || destination.password) {
+    throw new Error("Connect authorization requires an HTTPS destination without credentials");
+  }
+  if (
+    !attempt.id ||
+    !attempt.workspaceId ||
+    !Number.isSafeInteger(attempt.revision) ||
+    attempt.revision < 1
+  )
+    throw new Error("Connect authorization requires a scope");
+  if (options.mode === "redirect") {
+    navigation.redirect(attempt.nextAction.url);
+    return Promise.resolve(null);
+  }
+  const popup = navigation.openPopup(attempt.nextAction.url);
+  if (!popup) throw new Error("Connect popup was blocked; retry with redirect mode");
+  return pollConnectAttempt(transport, attempt.workspaceId, attempt.id, {
+    ...options,
+    minimumRevision: attempt.revision,
+  }).finally(() => {
+    // Window cleanup must never replace the authoritative result or failure.
+    try {
+      popup.close();
+    } catch {
+      /* Host navigation may already have disposed it. */
+    }
+  });
+}

package/src/browser-navigation.ts

@@ -0,0 +1,52 @@
+import type { ConnectNavigation } from "./authorization";
+
+/** Structural browser surface so importing Connect never reads DOM globals. */
+export type ConnectBrowserWindow = {
+  open(
+    url: string,
+    target: string,
+    features: string,
+  ): {
+    opener: unknown;
+    location: { replace(url: string): void };
+    close(): void;
+  } | null;
+  location: { assign(url: string): void };
+};
+
+function validateDestination(url: string): void {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+    throw new Error("Connect authorization requires an HTTPS destination without credentials");
+}
+
+/** Pass window from the host's browser entry point. Opens a fresh blank window
+ * synchronously and severs its opener BEFORE any provider content can load.
+ * Never uses a reusable named target or relies on provider window messages.
+ * The caller retains only the close capability for backend-polling cleanup. */
+export function createBrowserConnectNavigation(browser: ConnectBrowserWindow): ConnectNavigation {
+  return {
+    openPopup(url) {
+      validateDestination(url);
+      const popup = browser.open("about:blank", "_blank", "popup,width=520,height=720");
+      if (!popup) return null;
+      try {
+        popup.opener = null;
+        if (popup.opener !== null) throw new Error("Connect popup isolation failed");
+        popup.location.replace(url);
+      } catch {
+        try {
+          popup.close();
+        } catch {
+          /* Preserve the isolated navigation failure. */
+        }
+        throw new Error("Connect popup could not navigate safely; retry with redirect mode");
+      }
+      return { close: () => popup.close() };
+    },
+    redirect(url) {
+      validateDestination(url);
+      browser.location.assign(url);
+    },
+  };
+}

package/src/device.ts

@@ -0,0 +1,109 @@
+/** Shared device-code behavior for model-account domains. These accounts keep
+ * their existing APIs and ownership semantics; they are not generic credentials.
+ * Keep opaque provider state on the host backend when reload recovery is needed. */
+export async function pollDeviceAuthorization<
+  T extends { status: string; intervalSeconds?: number },
+>(options: {
+  poll: () => Promise<T>;
+  expired: T;
+  initialIntervalSeconds: number;
+  expiresAtMs: number;
+  signal: AbortSignal;
+  retryable?: (error: unknown) => boolean;
+  now?: () => number;
+  wait?: (delayMs: number, signal: AbortSignal) => Promise<boolean>;
+  maxRetryDelaySeconds?: number;
+}): Promise<T | null> {
+  const now = options.now ?? Date.now;
+  if (
+    !Number.isFinite(options.expiresAtMs) ||
+    !Number.isFinite(options.initialIntervalSeconds) ||
+    options.initialIntervalSeconds <= 0 ||
+    (options.maxRetryDelaySeconds !== undefined &&
+      (!Number.isFinite(options.maxRetryDelaySeconds) || options.maxRetryDelaySeconds <= 0))
+  )
+    throw new Error("Device authorization requires a finite expiry and polling interval");
+  const wait = options.wait ?? waitForDeviceDelay;
+  const initial = Math.max(1, options.initialIntervalSeconds);
+  const maximum = Math.max(initial, options.maxRetryDelaySeconds ?? 30);
+  let delay = initial;
+  while (!options.signal.aborted) {
+    const remaining = options.expiresAtMs - now();
+    if (remaining <= 0) return options.expired;
+    if (!(await wait(Math.min(delay * 1000, remaining), options.signal)) || options.signal.aborted)
+      return null;
+    if (now() >= options.expiresAtMs) return options.expired;
+    let result: T;
+    try {
+      const observed = await observeDevicePoll(
+        options.poll,
+        options.expiresAtMs - now(),
+        options.signal,
+      );
+      if (observed.kind === "aborted") return null;
+      if (observed.kind === "expired") return options.expired;
+      result = observed.result;
+    } catch (error) {
+      if (!options.retryable?.(error)) throw error;
+      delay = Math.min(maximum, Math.max(initial, delay * 2));
+      continue;
+    }
+    if (options.signal.aborted) return null;
+    if (result.status !== "pending" && result.status !== "slow_down") return result;
+    if (
+      result.intervalSeconds !== undefined &&
+      (!Number.isFinite(result.intervalSeconds) || result.intervalSeconds <= 0)
+    )
+      throw new Error("Provider returned an invalid device polling interval");
+    delay = Math.max(
+      1,
+      result.intervalSeconds ?? (result.status === "slow_down" ? delay + 5 : delay),
+    );
+  }
+  return null;
+}
+
+/** A transport may ignore cancellation. Bound observation without retrying an
+ * in-flight request or treating the loss of observation as provider success. */
+async function observeDevicePoll<T>(
+  poll: () => Promise<T>,
+  remainingMs: number,
+  signal: AbortSignal,
+): Promise<{ kind: "result"; result: T } | { kind: "aborted" } | { kind: "expired" }> {
+  if (signal.aborted) return { kind: "aborted" };
+  if (remainingMs <= 0) return { kind: "expired" };
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let abort: (() => void) | undefined;
+  try {
+    const stopped = new Promise<{ kind: "aborted" } | { kind: "expired" }>((resolve) => {
+      abort = () => resolve({ kind: "aborted" });
+      signal.addEventListener("abort", abort, { once: true });
+      timer = setTimeout(() => resolve({ kind: "expired" }), remainingMs);
+    });
+    return await Promise.race([
+      Promise.resolve()
+        .then(poll)
+        .then((result) => ({ kind: "result" as const, result })),
+      stopped,
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (abort) signal.removeEventListener("abort", abort);
+  }
+}
+
+async function waitForDeviceDelay(delayMs: number, signal: AbortSignal): Promise<boolean> {
+  if (signal.aborted) return false;
+  return new Promise((resolve) => {
+    const abort = () => {
+      clearTimeout(timer);
+      resolve(false);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", abort);
+      resolve(true);
+    }, delayMs);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+}

package/src/index.ts

@@ -0,0 +1,210 @@
+export * from "./types";
+export { pollDeviceAuthorization } from "./device";
+export { findConnectRecoveryAccount } from "./recovery";
+export { pollConnectAttempt } from "./poll";
+export { authorizeConnectAttempt, type ConnectNavigation } from "./authorization";
+export { createBrowserConnectNavigation, type ConnectBrowserWindow } from "./browser-navigation";
+import type { ConnectAdvance, ConnectAttempt, ConnectOwnership, ConnectTransport } from "./types";
+import { pollConnectAttempt } from "./poll";
+
+export type ConnectSnapshot = {
+  attempt: ConnectAttempt | null;
+  busy: boolean;
+  error: Error | null;
+};
+
+/** A transport-injected, framework-neutral view of one durable setup attempt.
+ * OAuth redirects are hints to navigate; completion is read from the backend.
+ * Secret form values are never stored in a snapshot or browser persistence. */
+export class ConnectController {
+  private snapshot: ConnectSnapshot = Object.freeze({ attempt: null, busy: false, error: null });
+  private readonly listeners = new Set<() => void>();
+  private generation = 0;
+  private request: AbortController | null = null;
+  private disposed = false;
+
+  constructor(
+    readonly transport: ConnectTransport,
+    readonly workspaceId: string,
+  ) {
+    if (!workspaceId) throw new Error("Connect requires an explicit workspace");
+  }
+
+  getSnapshot = (): ConnectSnapshot => this.snapshot;
+  subscribe = (listener: () => void): (() => void) => {
+    this.assertActive();
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  begin(input: {
+    providerId: string;
+    ownership: ConnectOwnership;
+    returnUrl: string;
+    idempotencyKey: string;
+    reconnectAccountId?: string;
+    installationTarget?: import("./types").ConnectInstallationTarget;
+  }): Promise<ConnectAttempt> {
+    // Validation must not serialize or decorate the host's exact return string.
+    const url = new URL(input.returnUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) {
+      throw new Error("Connect return URL must be an HTTP(S) destination without credentials");
+    }
+    return this.run((signal) => this.transport.begin(this.workspaceId, input, { signal }), true);
+  }
+
+  recover(attemptId: string): Promise<ConnectAttempt> {
+    if (!attemptId) throw new Error("Connect recovery requires an attempt ID");
+    return this.run(
+      (signal) => this.transport.get(this.workspaceId, attemptId, { signal }),
+      true,
+      attemptId,
+    );
+  }
+
+  refresh(): Promise<ConnectAttempt> {
+    const attempt = this.requireAttempt();
+    if (this.snapshot.busy) throw new Error("A Connect operation is already in progress");
+    return this.run(
+      (signal) => this.transport.get(this.workspaceId, attempt.id, { signal }),
+      false,
+      attempt.id,
+    );
+  }
+
+  advance(action: ConnectAdvance, idempotencyKey: string): Promise<ConnectAttempt> {
+    const attempt = this.requireAttempt();
+    if (this.snapshot.busy) throw new Error("A Connect operation is already in progress");
+    return this.run(
+      (signal) =>
+        this.transport.advance(
+          this.workspaceId,
+          attempt.id,
+          {
+            expectedRevision: attempt.revision,
+            idempotencyKey,
+            action,
+          },
+          { signal },
+        ),
+      false,
+      attempt.id,
+    );
+  }
+
+  /** Observe backend progress without replaying a setup mutation. Disposal or
+   * selecting another attempt aborts the read loop and fences its late result. */
+  waitForAction(options: { timeoutMs?: number } = {}): Promise<ConnectAttempt> {
+    const attempt = this.requireAttempt();
+    if (this.snapshot.busy) throw new Error("A Connect operation is already in progress");
+    return this.run(
+      (signal) =>
+        pollConnectAttempt(this.transport, this.workspaceId, attempt.id, {
+          ...options,
+          signal,
+          minimumRevision: attempt.revision,
+        }),
+      false,
+      attempt.id,
+    );
+  }
+
+  cancel(idempotencyKey: string): Promise<ConnectAttempt> {
+    const attempt = this.requireAttempt();
+    if (this.snapshot.busy) throw new Error("A Connect operation is already in progress");
+    return this.run(
+      (signal) =>
+        this.transport.cancel(
+          this.workspaceId,
+          attempt.id,
+          {
+            expectedRevision: attempt.revision,
+            idempotencyKey,
+          },
+          { signal },
+        ),
+      false,
+      attempt.id,
+    );
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.generation++;
+    this.request?.abort();
+    this.request = null;
+    this.listeners.clear();
+  }
+
+  private assertActive(): void {
+    if (this.disposed) throw new Error("Connect controller is disposed");
+  }
+  private requireAttempt(): ConnectAttempt {
+    this.assertActive();
+    if (!this.snapshot.attempt) throw new Error("No Connect attempt is selected");
+    return this.snapshot.attempt;
+  }
+  private publish(snapshot: ConnectSnapshot): void {
+    this.snapshot = Object.freeze(snapshot);
+    for (const listener of this.listeners) listener();
+  }
+  private async run(
+    operation: (signal: AbortSignal) => Promise<ConnectAttempt>,
+    replace: boolean,
+    expectedId?: string,
+  ): Promise<ConnectAttempt> {
+    this.assertActive();
+    const generation = ++this.generation;
+    this.request?.abort();
+    const request = new AbortController();
+    this.request = request;
+    this.publish({ attempt: replace ? null : this.snapshot.attempt, busy: true, error: null });
+    try {
+      const result = await operation(request.signal);
+      if (generation !== this.generation || this.disposed)
+        throw new Error("Connect operation was superseded");
+      if (result.workspaceId !== this.workspaceId || (expectedId && result.id !== expectedId)) {
+        throw new Error("Connect response scope mismatch");
+      }
+      if (
+        !Number.isSafeInteger(result.revision) ||
+        result.revision < 1 ||
+        (this.snapshot.attempt?.id === result.id &&
+          result.revision < this.snapshot.attempt.revision)
+      ) {
+        throw new Error("Connect response revision is stale");
+      }
+      const attempt = freezeTree(structuredClone(result));
+      this.publish({ attempt, busy: false, error: null });
+      return structuredClone(attempt);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error("Connect operation failed");
+      if (generation === this.generation && !this.disposed) {
+        // Transport errors can retain request bodies, headers, nested causes or
+        // echoed credentials. Keep only a fixed, credential-free UI error in
+        // the long-lived snapshot; direct callers still receive the rejection.
+        this.publish({
+          attempt: this.snapshot.attempt,
+          busy: false,
+          error: Object.freeze(
+            new Error("Connect operation failed; refresh its status before retrying"),
+          ),
+        });
+      }
+      throw error;
+    } finally {
+      if (generation === this.generation) this.request = null;
+    }
+  }
+}
+
+function freezeTree<T>(value: T): T {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) freezeTree(child);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/poll.ts

@@ -0,0 +1,78 @@
+import type { ConnectAttempt, ConnectTransport } from "./types";
+
+/** Read-only continuation. The backend remains authoritative for expiry and
+ * completion; redirects and popup messages are never completion evidence. */
+export async function pollConnectAttempt(
+  transport: Pick<ConnectTransport, "get">,
+  workspaceId: string,
+  attemptId: string,
+  options: { signal?: AbortSignal; timeoutMs?: number; minimumRevision?: number } = {},
+): Promise<ConnectAttempt> {
+  const timeoutMs = options.timeoutMs ?? 120_000;
+  if (
+    !workspaceId ||
+    !attemptId ||
+    !Number.isFinite(timeoutMs) ||
+    timeoutMs < 1 ||
+    timeoutMs > 600_000 ||
+    !Number.isSafeInteger(options.minimumRevision ?? 1) ||
+    (options.minimumRevision ?? 1) < 1
+  ) {
+    throw new Error("Connect polling requires a scope and a bounded timeout");
+  }
+  const abort = new AbortController();
+  const cancel = () => abort.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", cancel, { once: true });
+  if (options.signal?.aborted) cancel();
+  const timer = setTimeout(() => abort.abort(new Error("Connect polling timed out")), timeoutMs);
+  let revision = options.minimumRevision ?? 1;
+  try {
+    while (true) {
+      abort.signal.throwIfAborted();
+      const result = await abortable(
+        transport.get(workspaceId, attemptId, { signal: abort.signal }),
+        abort.signal,
+      );
+      if (
+        result.workspaceId !== workspaceId ||
+        result.id !== attemptId ||
+        !Number.isSafeInteger(result.revision) ||
+        result.revision < Math.max(1, revision)
+      ) {
+        throw new Error("Connect polling response scope or revision mismatch");
+      }
+      revision = result.revision;
+      if (
+        ["complete", "cancelled", "expired", "failed", "uncertain"].includes(result.state) ||
+        !["authorize", "wait"].includes(result.nextAction.type)
+      )
+        return result;
+      const requested = result.nextAction.type === "wait" ? result.nextAction.pollAfterMs : 1000;
+      const delay = Number.isFinite(requested) ? Math.min(60_000, Math.max(250, requested)) : 1000;
+      await new Promise<void>((resolve, reject) => {
+        const stop = () => {
+          clearTimeout(wait);
+          reject(abort.signal.reason);
+        };
+        const wait = setTimeout(() => {
+          abort.signal.removeEventListener("abort", stop);
+          resolve();
+        }, delay);
+        abort.signal.addEventListener("abort", stop, { once: true });
+        if (abort.signal.aborted) stop();
+      });
+    }
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", cancel);
+  }
+}
+
+function abortable<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const stop = () => reject(signal.reason);
+    signal.addEventListener("abort", stop, { once: true });
+    if (signal.aborted) stop();
+    pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop));
+  });
+}

package/src/recovery.ts

@@ -0,0 +1,16 @@
+import type { ConnectAccount } from "./types";
+
+/** A provider/domain match is not account identity. Never silently substitute
+ * another account when the original connection has disappeared. */
+export function findConnectRecoveryAccount(
+  accounts: readonly ConnectAccount[],
+  connectionId: string | null | undefined,
+): ConnectAccount | null {
+  if (!connectionId) return null;
+  const matches = accounts.filter(
+    (account) => account.id === connectionId || account.id === `social:${connectionId}`,
+  );
+  if (matches.length > 1)
+    throw new Error("Connection recovery is ambiguous; choose the exact account.");
+  return matches[0] ?? null;
+}

package/src/types.ts

@@ -0,0 +1,134 @@
+export type ConnectOwnership = "personal" | "workspace";
+export type ConnectProvider = {
+  id: string;
+  label: string;
+  family: string;
+  readiness: "available" | "needs_configuration" | "operator_only" | "unsupported";
+  reason?: string;
+  ownership: ConnectOwnership[];
+  setup: Array<
+    "none" | "oauth" | "credentials" | "device" | "installation" | "openapi" | "graphql"
+  >;
+};
+export type ConnectAccount = {
+  id: string;
+  providerId: string;
+  /** Observed credential generation; pass to disconnect to reject stale selections. */
+  version?: number;
+  label: string;
+  ownership: ConnectOwnership;
+  status: "connected" | "auth_needed" | "disabled";
+};
+export type ConnectResource = { id: string; label: string; kind: string };
+export type ConnectInstallationTarget = {
+  instanceKey: string;
+  displayName: string;
+  expectedInstanceVersion?: number;
+};
+export type ConnectNextAction =
+  | { type: "authorize"; url: string }
+  | {
+      type: "credentials";
+      fields: Array<{
+        name: string;
+        label: string;
+        required: boolean;
+        secret: boolean;
+        options?: Array<{ value: string; label: string }>;
+      }>;
+    }
+  | { type: "wait"; pollAfterMs: number; userCode?: string; verificationUrl?: string }
+  | { type: "select_account"; accounts: ConnectAccount[] }
+  | { type: "select_resources"; resources: ConnectResource[]; cursor?: string }
+  | { type: "preview"; previewId: string; contentHash: string; operations: ConnectResource[] }
+  | { type: "none" };
+export type ConnectAttempt = {
+  id: string;
+  workspaceId: string;
+  providerId: string;
+  ownership: ConnectOwnership;
+  revision: number;
+  state:
+    | "ready"
+    | "requires_user_action"
+    | "credential_input"
+    | "provider_wait"
+    | "account_selection"
+    | "resource_selection"
+    | "preview"
+    | "installing"
+    | "connected_but_incomplete"
+    | "complete"
+    | "cancelled"
+    | "expired"
+    | "failed"
+    | "uncertain";
+  credentialsCommitted: boolean;
+  integrationInstalled: boolean;
+  completionRequirement: "connection" | "integration" | "provider_setup";
+  nextAction: ConnectNextAction;
+  expiresAt: string;
+  account?: ConnectAccount;
+  installationTarget?: ConnectInstallationTarget;
+  source?:
+    | { kind: "definition"; definitionId: string }
+    | { kind: "openapi" | "auto"; url: string; baseUrl?: string }
+    | { kind: "graphql"; endpoint: string; name?: string };
+  error?: { code: string; message: string; retryable: boolean };
+};
+export type ConnectAdvance =
+  | { type: "credentials"; values: Record<string, string> }
+  | { type: "account"; accountId: string }
+  | { type: "resources"; resourceIds: string[] }
+  | { type: "install"; previewId: string; contentHash: string; operationIds: string[] }
+  | { type: "retry" };
+export type ConnectCallOptions = { signal?: AbortSignal };
+
+/** Host backend transport; authenticated workspace and actor admission stays
+ * server-side. A controller never turns browser-supplied IDs into authority. */
+export interface ConnectTransport {
+  catalog(workspaceId: string, options?: ConnectCallOptions): Promise<ConnectProvider[]>;
+  accounts(workspaceId: string, options?: ConnectCallOptions): Promise<ConnectAccount[]>;
+  pending(workspaceId: string, options?: ConnectCallOptions): Promise<ConnectAttempt[]>;
+  begin(
+    workspaceId: string,
+    input: {
+      providerId: string;
+      ownership: ConnectOwnership;
+      returnUrl: string;
+      idempotencyKey: string;
+      reconnectAccountId?: string;
+      installationTarget?: ConnectInstallationTarget;
+    },
+    options?: ConnectCallOptions,
+  ): Promise<ConnectAttempt>;
+  get(
+    workspaceId: string,
+    attemptId: string,
+    options?: ConnectCallOptions,
+  ): Promise<ConnectAttempt>;
+  advance(
+    workspaceId: string,
+    attemptId: string,
+    input: {
+      expectedRevision: number;
+      idempotencyKey: string;
+      action: ConnectAdvance;
+    },
+    options?: ConnectCallOptions,
+  ): Promise<ConnectAttempt>;
+  cancel(
+    workspaceId: string,
+    attemptId: string,
+    input: {
+      expectedRevision: number;
+      idempotencyKey: string;
+    },
+    options?: ConnectCallOptions,
+  ): Promise<ConnectAttempt>;
+  disconnect(
+    workspaceId: string,
+    accountId: string,
+    options?: ConnectCallOptions & { expectedVersion?: number },
+  ): Promise<void>;
+}