@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/webRenewal.js

@@ -0,0 +1,179 @@
+// The web session's renewal (owner decision of 27 October 2026). The refresh
+// credential is the provider's HttpOnly cookie, partitioned to the site the
+// application runs on, so a background call from the application carries it
+// and no navigation is needed, also after a reload or in a new tab. When the
+// browser sends no cookie the call is refused and the SDK raises
+// web_renewal_requires_navigation: the application then starts the top-level
+// restore (restoreSession) itself. The SDK never navigates on its own. The
+// restore sequence is here too, under the same lock.
+import { abortable, ClientFlowError, newHandoffBinding, opaqueId, parseAuthorizationError, record } from "./auth.js";
+import { restoreCallback } from "./redirects.js";
+/** The code of the typed error that asks the application to start the top-level restore. */
+export const webRenewalRequiresNavigation = "web_renewal_requires_navigation";
+/**
+ * The tabs of one application share the cookie, and the provider ends a
+ * session whose refresh value it is shown twice. Every renewal and every
+ * restore therefore runs under one Web Lock per client: each sends the value
+ * the previous one left. A restore holds it until the host's launcher
+ * settles or the restore's signal aborts it; the host gets the same signal
+ * and closes its window, so no abandoned navigation rotates the value later.
+ * A sign-in's exchange, which sets the cookie too, goes out under the same
+ * lock (client.ts), so a renewal's late answer never follows a newer
+ * sign-in's.
+ */
+export function underRenewalLock(target, work) {
+    const locks = globalThis.navigator?.locks;
+    if (!locks || typeof locks.request !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    const whenWaiting = target.whenWaiting;
+    if (!whenWaiting)
+        return locks.request(target.lockName, { signal: target.signal }, work);
+    // Told when the lock is not free at once, the caller learns it waits; the work still runs once it is.
+    return locks.request(target.lockName, { ifAvailable: true }, async (lock) => (lock ? { ran: await work() } : undefined)).then((done) => {
+        if (done)
+            return done.ran;
+        whenWaiting();
+        return locks.request(target.lockName, { signal: target.signal }, work);
+    });
+}
+/**
+ * renewWebSession is the background call: POST /v1/auth/renew with the cookie
+ * (credentials: "include"). A page that holds the session's CSRF token sends
+ * it; a page that holds none (a reload, a new tab), or whose token a renewal
+ * or restore in another tab replaced, renews from the cookie alone with the
+ * fixed X-Authorization-Renew header and gets a new token. It answers the
+ * session payload.
+ */
+export async function renewWebSession(request) {
+    return underRenewalLock(request, async () => {
+        if (request.csrfToken) {
+            request.current?.();
+            const renewed = await renewOnce(request, { "X-CSRF-Token": request.csrfToken });
+            if (renewed.ok)
+                return renewed.payload;
+            if (renewed.refusal.status !== 403 || renewed.refusal.code !== "ORIGIN_NOT_ALLOWED")
+                throw refusedRenewal(renewed.refusal);
+        }
+        request.current?.();
+        const renewed = await renewOnce(request, { "X-Authorization-Renew": "1" });
+        if (renewed.ok)
+            return renewed.payload;
+        throw refusedRenewal(renewed.refusal);
+    });
+}
+/**
+ * staleCsrfRefusal is the answer a web lifecycle call gets when a renewal or
+ * restore in another tab replaced the session's CSRF token since this page
+ * last renewed.
+ */
+export function staleCsrfRefusal(error) {
+    return error instanceof Error && error.status === 403 && error.code === "ORIGIN_NOT_ALLOWED";
+}
+/**
+ * revokeWithCurrentCredentials is logout's way past a CSRF token another tab
+ * replaced. Under the tabs' lock, held until the revocation answers, it
+ * renews from the cookie alone and revokes with the tokens that answer, but
+ * only when they belong to the session the logout was asked for: a cookie
+ * another sign-in replaced is left alone and the revocation is not confirmed.
+ */
+export async function revokeWithCurrentCredentials(request, revoke) {
+    return underRenewalLock(request, async () => {
+        const renewed = await renewOnce({ ...request, csrfToken: undefined }, { "X-Authorization-Renew": "1" });
+        if (!renewed.ok)
+            throw refusedRenewal(renewed.refusal);
+        const payload = renewed.payload;
+        if (!payload || typeof payload.access_token !== "string" || payload.access_token === "" || typeof payload.csrf_token !== "string" || payload.csrf_token === "") {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        if (payload.session_id !== request.sessionId)
+            throw new ClientFlowError("session_unavailable");
+        return revoke(payload.access_token, payload.csrf_token);
+    });
+}
+/** revokedAnswer says a logout answer confirms the revocation. */
+export function revokedAnswer(payload) {
+    try {
+        const result = record(payload, ["request_id", "server_disposition"]);
+        return opaqueId(result.request_id) && result.server_disposition === "server_revoked";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * revokeUnclaimedSession ends the session of a sign-in answer this page does
+ * not install, because a logout or a newer sign-in overtook it while it was
+ * asked for. The answer set the cookie, so without it a reload would take up
+ * a session nobody holds, one the person may have logged out of. The
+ * provider clears the cookie only while it holds that session. A CSRF token
+ * another tab replaced meanwhile (it renewed that session from the cookie) is
+ * followed by the logout's recovery: one renewal from the cookie under the
+ * tabs' lock, checked against the answer's session, and the revocation with
+ * its tokens. It answers true only for a confirmed revocation of exactly that
+ * session; a cookie that holds another session is left alone and answers
+ * false, as does any refusal or failure. whenWaiting is told when the
+ * recovery has to wait for the lock (a restore may hold it while its window
+ * is open): the revocation goes on, but nobody needs to wait for its verdict.
+ */
+export async function revokeUnclaimedSession(request, payload, revoke) {
+    const answer = payload;
+    if (!answer || typeof answer !== "object" || typeof answer.access_token !== "string" || answer.access_token === "" ||
+        typeof answer.csrf_token !== "string" || answer.csrf_token === "" || !opaqueId(answer.session_id))
+        return false;
+    const sessionId = answer.session_id;
+    try {
+        return revokedAnswer(await revoke(answer.access_token, answer.csrf_token));
+    }
+    catch (error) {
+        if (!staleCsrfRefusal(error))
+            return false;
+    }
+    try {
+        return revokedAnswer(await revokeWithCurrentCredentials({ ...request, sessionId }, revoke));
+    }
+    catch {
+        return false;
+    }
+}
+async function renewOnce(request, header) {
+    const response = await request.fetch(`${request.authorizationOrigin}/v1/auth/renew`, {
+        method: "POST",
+        headers: { Accept: "application/json", "Content-Type": "application/json", ...header },
+        body: JSON.stringify({ client_id: request.clientId }),
+        credentials: "include",
+        cache: "no-store",
+        signal: request.signal,
+    });
+    const payload = await response.json();
+    return response.ok ? { ok: true, payload } : { ok: false, refusal: parseAuthorizationError(payload, response.status) };
+}
+// 401: the browser sent no cookie (it keeps no partitioned cookie) or the
+// value is no longer live; the top-level restore is the way back. Any other
+// refusal is passed on as it came.
+function refusedRenewal(refusal) {
+    return refusal.status === 401 && refusal.code === "UNAUTHORIZED" ? new ClientFlowError(webRenewalRequiresNavigation) : refusal;
+}
+/**
+ * restoreWebSession is the top-level restore: a fresh state and S256 verifier
+ * in memory, the provider restore URL through the host's launcher, and the
+ * one-use handoff of the redirect it returns exchanged for the session.
+ */
+export async function restoreWebSession(request) {
+    return underRenewalLock(request, async () => {
+        const binding = await newHandoffBinding(request.crypto);
+        request.signal?.throwIfAborted();
+        const start = new URL("/v1/auth/restore", request.authorizationOrigin);
+        for (const [name, value] of [["client_id", request.clientId], ["redirect_uri", request.redirectUri], ["state", binding.state], ["code_challenge", binding.challenge], ["code_challenge_method", "S256"]]) {
+            start.searchParams.set(name, value);
+        }
+        request.current?.();
+        const returned = await abortable(request.launch(start.toString(), request.signal), request.signal);
+        if (typeof returned !== "string")
+            throw new ClientFlowError("restore_redirect_unavailable");
+        const handoff = restoreCallback(returned, request.redirectUri);
+        if (handoff.state !== binding.state)
+            throw new ClientFlowError("state_mismatch");
+        request.current?.();
+        return request.exchange(JSON.stringify({ client_id: request.clientId, restore_id: handoff.restoreId, code: handoff.code, verifier: binding.verifier, redirect_uri: request.redirectUri }));
+    });
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@shuttle.technology/authorization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Browser and mobile client of the Streams Authorization API: hosted sign-in, the account's wallets, service grants, limits, Mode B sends and Mode C signed requests.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./mode-c": {
+      "types": "./dist/modeC.d.ts",
+      "default": "./dist/modeC.js"
+    },
+    "./mode-c-linked": {
+      "types": "./dist/modeCLinked.d.ts",
+      "default": "./dist/modeCLinked.js"
+    },
+    "./streams": {
+      "types": "./dist/streams.d.ts",
+      "default": "./dist/streams.js"
+    },
+    "./linked-wallets": {
+      "types": "./dist/linkedWallets.d.ts",
+      "default": "./dist/linkedWallets.js"
+    },
+    "./debit-permissions": {
+      "types": "./dist/debitPermissions.d.ts",
+      "default": "./dist/debitPermissions.js"
+    },
+    "./device-key": {
+      "types": "./dist/deviceKey.d.ts",
+      "default": "./dist/deviceKey.js"
+    },
+    "./device-share": {
+      "types": "./dist/deviceShare.d.ts",
+      "default": "./dist/deviceShare.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types --check src/accountLists.ts && node --experimental-strip-types --check src/auth.ts && node --experimental-strip-types --check src/balances.ts && node --experimental-strip-types --check src/canonicalize.ts && node --experimental-strip-types --check src/client.ts && node --experimental-strip-types --check src/clientTypes.ts && node --experimental-strip-types --check src/deviceRecovery.ts && node --experimental-strip-types --check src/deviceShares.ts && node --experimental-strip-types --check src/linkedRecovery.ts && node --experimental-strip-types --check src/linkedRegistrations.ts && node --experimental-strip-types --check src/configuration.ts && node --experimental-strip-types --check src/consentDebit.ts && node --experimental-strip-types --check src/credentials.ts && node --experimental-strip-types --check src/debitPermissions.ts && node --experimental-strip-types --check src/debitPermissionWire.ts && node --experimental-strip-types --check src/aesGcmSiv.ts && node --experimental-strip-types --check src/deviceKey.ts && node --experimental-strip-types --check src/deviceShare.ts && node --experimental-strip-types --check src/deviceShareEnvelope.ts && node --experimental-strip-types --check src/errors.ts && node --experimental-strip-types --check src/linkedSendDisplay.ts && node --experimental-strip-types --check src/linkedChecks.ts && node --experimental-strip-types --check src/linkedWallets.ts && node --experimental-strip-types --check src/linkedWalletSignals.ts && node --experimental-strip-types --check src/me.ts && node --experimental-strip-types --check src/mediatedOperation.ts && node --experimental-strip-types --check src/mobile.ts && node --experimental-strip-types --check src/pages.ts && node --experimental-strip-types --check src/modeC.ts && node --experimental-strip-types --check src/modeCLinked.ts && node --experimental-strip-types --check src/poll.ts && node --experimental-strip-types --check src/redirects.ts && node --experimental-strip-types --check src/requestGrant.ts && node --experimental-strip-types --check src/sends.ts && node --experimental-strip-types --check src/serviceGrants.ts && node --experimental-strip-types --check src/slice4.ts && node --experimental-strip-types --check src/streams.ts && node --experimental-strip-types --check src/trackedWallets.ts && node --experimental-strip-types --check src/transferStatus.ts && node --experimental-strip-types --check src/walletCreateGrant.ts && node --experimental-strip-types --check src/walletDisplayParts.ts && node --experimental-strip-types --check src/walletEvents.ts && node --experimental-strip-types --check src/walletLimits.ts && node --experimental-strip-types --check src/walletOperations.ts && node --experimental-strip-types --check src/webRenewal.ts && node --check test/http-integration.mjs && node --check test/http-integration-slice4.mjs && node --check test/http-integration-slice6.mjs && node --check test/http-integration-slice7.mjs && node --check test/http-integration-contract.mjs && node --check test/http-integration-linked-send.mjs && node --check test/http-integration-limits.mjs && node --check test/http-integration-modec-linked.mjs && node --check test/http-integration-mode-a.mjs && node --check test/http-integration-mode-a-platform.mjs && node --check test/http-integration-demo.mjs && node --check test/http-integration-wallet-create.mjs && node --check test/http-integration-wallet-create-grant.mjs && node --check test/http-integration-wallet-create-debit.mjs",
+    "typecheck": "tsc --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "integration:http": "node test/http-integration.mjs",
+    "verify": "pnpm run check && pnpm run typecheck && pnpm run build && pnpm run test"
+  }
 }