@pear-protocol/utils 0.5.1 → 0.5.2

package/dist/xauth/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The browser's half of an X sign-in.
+ *
+ * X returns the user by redirect, and a redirect cannot carry a credential up or a token
+ * pair back down. So the callback settles who the user is and leaves a single-use ticket on
+ * the return URL, which the frontend redeems over an XHR of its own.
+ *
+ * A ticket travelling in a URL is only safe if holding it is not enough. That is what these
+ * two functions are for: `startXHandoff` keeps a secret on this origin before the browser
+ * leaves, and `finishXHandoff` produces it again on the way back. A ticket lifted from
+ * someone else's URL matches no secret the lifting browser holds.
+ */
+/**
+ * Where the secret waits while the browser is away at X.
+ *
+ * The subset of `Storage` this needs, so a caller can pass `localStorage`, a test double,
+ * or something else entirely.
+ *
+ * `localStorage` is the sane choice over `sessionStorage`: the flow may return in a tab
+ * opened for it, and browsers disagree about whether a new tab inherits session storage.
+ * Sharing across tabs costs nothing, because a ticket is bound to a secret, not to a tab.
+ */
+export type XHandoffStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+};
+/**
+ * What an X flow left on the page it returned the browser to.
+ *
+ * A link is already done by the time the browser lands and only needs reporting. A sign-in
+ * is not: `login-settled` carries both halves needed to redeem it, so the caller never
+ * reaches into storage itself.
+ */
+export type XReturn = {
+    kind: 'link-succeeded';
+    status: 'connected' | 'reconnected';
+} | {
+    kind: 'link-failed';
+    reason: string | undefined;
+} | {
+    kind: 'login-settled';
+    ticket: string;
+    verifier: string;
+} | {
+    kind: 'login-failed';
+    reason: string | undefined;
+};
+/**
+ * Begin a sign-in: keep a secret here, and return what the server needs.
+ *
+ * Send both fields to `startXLogin`. The server holds the challenge against the flow and
+ * echoes the id back on the return URL, which is how a browser that started more than one
+ * sign-in knows which secret this outcome belongs to.
+ */
+export declare function startXHandoff(storage: XHandoffStorage): {
+    handoffId: string;
+    challenge: string;
+};
+/**
+ * Read the outcome this page is the end of, and retire the secret behind it.
+ *
+ * Returns undefined when the page is not the end of an X flow at all. Every sign-in outcome
+ * clears its stored secret, success or failure, so nothing spent is left behind.
+ *
+ * The ticket comes out of the fragment rather than the query, which is where the callback
+ * puts it: no browser sends a fragment to a server, so it stays out of the frontend's access
+ * logs and out of the `Referer` of anything the page loads.
+ */
+export declare function finishXHandoff(href: string, storage: XHandoffStorage): XReturn | undefined;
+/**
+ * The same page with every X parameter taken back off it.
+ *
+ * What the user reloads or shares should be where they were, never a spent ticket. The
+ * fragment goes entirely: the flow put the ticket there, and any fragment the page had was
+ * dropped when the return URL was recorded at start time.
+ */
+export declare function stripXReturn(href: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/utils",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",
@@ -27,7 +27,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.3.2",
-    "@pear-protocol/types": "^1.20.0",
+    "@pear-protocol/types": "^1.24.1",
+    "@scure/base": "^2.3.0",
     "bignumber.js": "9.3.1"
   },
   "devDependencies": {

package/dist/asset/compute.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/basket/derive-basket-key.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/fills/compute.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/math/decimal.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/position/compute.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/proxy.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/basket.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/exposure.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/fills.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/index.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/matching.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/position.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/applicables/synthetics.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/compute.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sync/cutoff.test.d.ts

@@ -1 +0,0 @@
-export {};