@synap-core/sdk 1.3.0 → 1.4.0

package/src/testing/cloud.ts

@@ -0,0 +1,84 @@
+/**
+ * A mock Synap Cloud pod chooser (Control Plane `GET /connect/pod`, wave C1)
+ * for "Continue with Synap Cloud" tests and a kit's mock mode. No network:
+ * `choose()` stands in for the person signing in to the CP and picking a pod.
+ *
+ * Wire behaviour mirrors the CP route (doc 18 §1.1): it accepts only
+ * `client_id` (an https CIMD URL; http on loopback only with
+ * `allowInsecureLoopback`, for a kit's mock mode on http://localhost) and
+ * `state` (`^[A-Za-z0-9._~-]{16,256}$`),
+ * takes the return URL from the app's client metadata (`initiate_login_uri`),
+ * never from the query, and answers `<initiate_login_uri>?iss=<pod issuer>&state=<state>`.
+ * It never sees a code or a token.
+ *
+ *   const cloud = createMockCloud();
+ *   createPodAppAuth({ ...config, cloudUrl: cloud.url });
+ *   cloud.choose(location, { pod: mockPod.issuer, metadata: auth.metadata })  → the app's return URL
+ */
+import type { ClientMetadataDocument } from "../connect/types";
+
+/** A placeholder Control Plane origin; never contacted. */
+export const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
+
+const STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export interface MockCloud {
+  url: string;
+  /** The chooser URLs the app sent browsers to. */
+  requests: string[];
+  /**
+   * The person picks `pod` on the chooser: validates the request like the CP,
+   * returns where the CP redirects the browser. Throws on a request the CP
+   * refuses (shown as a page there, never redirected).
+   */
+  choose(location: string, opts: { pod: string; metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri"> }): string;
+  /** The person cancels on the chooser: `<initiate_login_uri>?state=…&error=access_denied`, no `iss`. */
+  cancel(location: string, opts: { metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri"> }): string;
+}
+
+export function createMockCloud(options: { url?: string; allowInsecureLoopback?: boolean } = {}): MockCloud {
+  const base = (options.url ?? MOCK_CLOUD_URL).replace(/\/+$/, "");
+  const requests: string[] = [];
+  return {
+    url: base,
+    requests,
+    choose(location, { pod, metadata }) {
+      const back = check(location, metadata);
+      back.searchParams.set("iss", pod);
+      back.searchParams.set("state", new URL(location).searchParams.get("state")!);
+      return back.href;
+    },
+    cancel(location, { metadata }) {
+      const back = check(location, metadata);
+      back.searchParams.set("state", new URL(location).searchParams.get("state")!);
+      back.searchParams.set("error", "access_denied");
+      return back.href;
+    },
+  };
+
+  /** Validates like the CP (an HTML error there, never a redirect); returns the app's initiate_login_uri. */
+  function check(location: string, metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">): URL {
+    requests.push(location);
+    const url = new URL(location);
+    if (`${url.origin}${url.pathname}` !== `${base}/connect/pod`) throw new Error(`Not this CP's /connect/pod: ${location}`);
+    const clientId = url.searchParams.get("client_id");
+    const state = url.searchParams.get("state");
+    if (!clientId || !cimdUrlAccepted(clientId)) throw new Error("Chooser refused: client_id must be an https CIMD URL");
+    if (!state || !STATE_RE.test(state)) throw new Error("Chooser refused: state is missing or malformed");
+    if (clientId !== metadata.client_id) throw new Error("Chooser refused: the client metadata is not this client_id's");
+    return new URL(metadata.initiate_login_uri);
+  }
+
+  /** https; http only on a loopback host, and only with `allowInsecureLoopback`. */
+  function cimdUrlAccepted(clientId: string): boolean {
+    let url: URL;
+    try {
+      url = new URL(clientId);
+    } catch {
+      return false;
+    }
+    if (url.protocol === "https:") return true;
+    return url.protocol === "http:" && options.allowInsecureLoopback === true && LOOPBACK_HOSTS.has(url.hostname);
+  }
+}

package/src/testing/index.ts

@@ -17,7 +17,7 @@
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts.
+ * ./auth-server.ts; Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 import type {
   PublicCollectionPage,
@@ -33,6 +33,8 @@ export { MOCK_FORM, MOCK_SHARE, MOCK_SITE };
 export type { MockCollection, MockSite } from "./fixtures";
 // Pod-app sign-in: a mock authorization server + Hub REST doors.
 export * from "./auth-server";
+// Synap Cloud: a mock Control Plane pod chooser.
+export * from "./cloud";
 
 /** A placeholder origin; never contacted. */
 export const MOCK_POD_URL = "https://mock.synap.invalid";