@ikonai/sdk 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikonai/sdk",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/utils/embedded-oauth.d.ts

@@ -11,23 +11,48 @@
  * `ikon.client.login` client function. They used to build the same redirect URL separately, and
  * keeping two copies in step is exactly what failed once already.
  */
+/** What the frame asks its embedder for, and what the embedder answers to claim the request. */
+export declare const EMBEDDER_SIGN_IN_REQUEST = "ikon-oauth-embedder-request";
+export declare const EMBEDDER_SIGN_IN_ACCEPTED = "ikon-oauth-embedder-accepted";
+/**
+ * Carries the verifier back to the frame on its own URL, beside the code.
+ *
+ * It has to travel because the frame that minted it does not survive the embedder's navigation, and
+ * returns on a different origin whenever its address is assigned per session — so the sessionStorage
+ * it wrote to is not the one it can read. Same-origin, spent immediately, and stripped from the
+ * address bar with the rest of the callback params.
+ */
+export declare const PKCE_URL_PARAM = "ikon_pkce";
 /**
  * True when this document is nested in another. A cross-origin parent makes the property access
  * itself throw, which is the embedded case too.
  */
 export declare function isEmbedded(): boolean;
 /**
- * Sign in through a popup and land the result on this page's URL.
+ * Sign in from a framed app, and land the result on this page's URL.
+ *
+ * Asks the embedder first, because a host that is cross-origin isolated severs any popup this frame
+ * opens. Falls back to the popup for a host that is not.
+ *
+ * The popup is opened only once the embedder has declined, never speculatively. Opening it up front
+ * left a blank window stranded on screen in exactly the case the embedder path handles: a severed
+ * `window.open` returns null, so there is no handle left to close the window it nonetheless opened.
+ * The gesture survives the wait — {@link EMBEDDER_ACK_TIMEOUT_MS} is bounded well inside the
+ * browser's transient-activation window, so the popup is still attributable to the click.
  *
  * The code is handed over by reloading this document with `ikon_code` on it rather than by redeeming
  * it here: that is the exact shape the unframed redirect flow already produces, so the callback
  * consumer that reads it needs no second code path and no knowledge of how the code arrived. The
  * reload is same-origin, so nothing frames anything it may not.
  *
- * Returns false when the popup could not be opened or the sign-in did not complete; the caller
- * reports that to the person. Throws nothing — a failed sign-in is an outcome, not an exception.
+ * Returns false when the sign-in could not be started or did not complete; the caller reports that
+ * to the person. Throws nothing — a failed sign-in is an outcome, not an exception.
  */
-/** What the frame asks its embedder for, and what the embedder answers to claim the request. */
-export declare const EMBEDDER_SIGN_IN_REQUEST = "ikon-oauth-embedder-request";
-export declare const EMBEDDER_SIGN_IN_ACCEPTED = "ikon-oauth-embedder-accepted";
 export declare function startEmbeddedOAuthSignIn(provider: string, spaceId: string): Promise<boolean>;
+/**
+ * Take a verifier off this document's URL and put it back where the exchange looks for it.
+ *
+ * Called before redeeming a code that arrived from an embedder, which is the only case where the
+ * verifier could not simply have stayed in storage.
+ */
+export declare function adoptPkceVerifierFromUrl(): void;

package/utils/pkce.d.ts

@@ -6,6 +6,16 @@ export declare function isPkceSupported(): boolean;
  * flow rather than starting a sign-in it will not be able to finish.
  */
 export declare function createPkceChallenge(): Promise<string | null>;
+/**
+ * Put back a verifier that had to travel to finish its sign-in.
+ *
+ * The frame that minted one does not always survive to redeem it: an embedded app whose host runs
+ * the redirect is destroyed by that navigation, and comes back on a different origin whenever its
+ * address is assigned per session — a preview's relay port is. sessionStorage is keyed on that
+ * origin, so the verifier written before the navigation is unreachable after it, and the exchange
+ * fails as though the sign-in had started in another browser.
+ */
+export declare function restorePkceVerifier(verifier: string): void;
 /**
  * Returns the verifier for this browser's pending sign-in and forgets it. One-shot on purpose: a
  * verifier that outlived its redemption is only useful to whoever finds it later.