@molecule/app-auth 1.3.1 → 1.3.2

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-17T07:07:31.667Z
+Generated: 2026-10-17T20:34:11.708Z
 -->
 
 # @molecule/app-auth
@@ -17,6 +17,43 @@ client; `setClient`/`getClient` bond it; `login`/`logout`/`register`/
 bindings (e.g. `AuthProvider`/`useAuth` in `@molecule/app-react`) wrap the
 same client.
 
+**In a scaffolded app, wire it by hand — the sandbox cannot run `mlcl add`.**
+The package is already installed; create the client once at startup with
+`setClient(createJWTAuthClient({ baseURL, authScheme: 'Token', storage:
+createBrowserStorageAdapter() }))`, or `createDefaultAuthClient(authConfig)`
+from `@molecule/app-bonds-default-react` (which also registers
+`whenRestored()` as the HTTP gate), call `initialize()`, and read the session
+through `MoleculeProvider`/`useAuth()` in a React app.
+
+**`initialize()` restores the session BEFORE the first render, and no
+hand-rolled token store may replace it.** With the token AND user in the
+store the restore is synchronous and costs no request; with an httpOnly
+session cookie the API sets at login it restores through
+`currentUserEndpoint` (default `/users/me`). `AuthClientConfig.storage` is
+the config field that decides which route a reload takes. A store written
+beside the client answers requests before its own restore settles: the first
+authenticated page renders signed-out, and its 401 signs the user out for
+good.
+
+**Never fetch viewer-dependent data before the restore settles.** A
+component effect that runs on mount fires while `initialize()` is still
+restoring, so its request leaves without the `Authorization` header and the
+server answers for an anonymous viewer — a followed user renders "Follow", a
+saved item renders unsaved. On localhost the restore usually wins this race;
+over the network it does not, so the bug appears only on the deployed URL.
+Gate the fetch on the auth state being settled (`state.initialized`), or let
+the HTTP client do it: `@molecule/app-bonds-default-react` registers
+`whenRestored()` as the gate so every request waits for the restore.
+
+**A store that registers its own gate must exempt the restore's own request.**
+This client restores with `fetch`, so the gate registered over it never holds
+the restore. A store that restores THROUGH the bonded HTTP client and
+registers that restore as the gate (`setAuthGate(() => store.whenSettled())`)
+waits on itself unless the restore's request passes `skipAuthGate: true` —
+otherwise the gate holds the very request it is waiting for, and every
+request it holds stalls until the gate times out. See
+`RequestConfig.skipAuthGate` in `@molecule/app-http`.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -648,6 +685,13 @@ type AuthEventListener = (event: AuthEvent) => void
 
 The auth client's `StorageAdapter` over the browser's Web Storage.
 
+**The restore it enables costs NO request — never block the first paint on one.** With the
+token AND the user in the store, `initialize()` restores the authenticated state synchronously
+(`whenRestored()` is already resolved on the first render); render from it, and validate the
+token as a background request — never in front of the first render. A page that waits on its
+own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
+window, eight `waitForURL` timeouts).
+
 Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
 the client's default (`'memory'`) is lost on reload, and re-establishing the
 session then needs a credential that survived — this adapter, or an httpOnly
@@ -665,15 +709,15 @@ const authClient = createJWTAuthClient({
 The scaffold's `authConfig` already passes it, so a scaffolded app survives a
 reload out of the box; each of these replaces that default:
 
-```ts
+````ts
 storage: 'memory' // memory only: pair it with an httpOnly cookie session
 storage: createBrowserStorageAdapter({ kind: 'session' }) // survives a reload, dies with the tab
-storage: { getItem: (k) => …, setItem: (k, v) => …, removeItem: (k) => … } // your own
-```
+
+*(description truncated — read the full text in `node_modules/@molecule/app-auth/dist/browser-storage.d.ts`.)*
 
 ```typescript
 function createBrowserStorageAdapter(options?: BrowserStorageAdapterOptions): StorageAdapter
-```
+````
 
 - `options` — Which Web Storage area to use, or a store to use directly.
 
@@ -855,38 +899,10 @@ Peer dependencies:
   (`setClient(createJWTAuthClient({ authScheme: 'Token', … }))` in the auth bond), not
   properties of a client that already exists. Do not hand-write an auth client for a spec
   like RealWorld.
-- **Whether a reload keeps the user signed in is `AuthClientConfig.storage`,
-  and one of the two routes must be wired.** The client's own default is
-  `'memory'`, which is lost on reload, so a session survives one only by
-  having a credential that survived: (1) `storage: createBrowserStorageAdapter()`
-  — the browser's `localStorage`, what a scaffolded app's `authConfig` passes
-  (see `@molecule/app-auth`'s `createBrowserStorageAdapter` for the trade: Web
-  Storage is script-readable, so an XSS can steal the token), or (2) an
-  httpOnly session cookie the API sets at login, which `initialize()` restores
-  through `currentUserEndpoint` (default `/users/me`) — the stronger option
-  wherever the API supports it, and what `@molecule/api-resource-user` issues.
-  Wire `initialize()` once at startup either way. Do NOT hand-roll a token
-  store beside the client for this: it is a config field.
 - **Endpoint defaults must match your API's real routes** (`/auth/login`,
   `/auth/register`, `/auth/refresh`, `/users/logout`, `/users/me`, …).
   Align them via `createJWTAuthClient({ baseURL, ...endpoints })` — never by
   hand-editing fetch calls in components.
-- **Do not fetch viewer-dependent data before the restore settles.** A component
-  effect that runs on mount fires while `initialize()` is still restoring, so its
-  request leaves without the `Authorization` header and the server answers for an
-  anonymous viewer — a followed user renders "Follow", a saved item renders unsaved.
-  On localhost the restore usually wins this race; over the network it does not, so
-  the bug appears only on the deployed URL. Two ways out: gate the fetch on the auth
-  state being settled (`state.initialized`), or let the HTTP client do it — bond the
-  auth client through `@molecule/app-bonds-default-react`, which registers
-  `whenRestored()` as the http gate so every request waits for the restore.
-- **Your own session store's gate must exempt its restore's own request.** This client
-  restores with `fetch`, so the gate registered over it never holds the restore. A store
-  that restores THROUGH the bonded HTTP client and registers that restore as the gate
-  (`setAuthGate(() => store.whenSettled())`) waits on itself unless the restore's request
-  passes `skipAuthGate: true` — otherwise the gate holds the very request it is waiting
-  for, and every request it holds stalls until the gate times out. See
-  `RequestConfig.skipAuthGate` in `@molecule/app-http`.
 - Client-side auth state is UX only — the server enforces authorization on
   every request; hiding a screen is not protection.
 

package/dist/browser-storage.d.ts

@@ -31,6 +31,13 @@ export interface BrowserStorageAdapterOptions {
 /**
  * The auth client's `StorageAdapter` over the browser's Web Storage.
  *
+ * **The restore it enables costs NO request — never block the first paint on one.** With the
+ * token AND the user in the store, `initialize()` restores the authenticated state synchronously
+ * (`whenRestored()` is already resolved on the first render); render from it, and validate the
+ * token as a background request — never in front of the first render. A page that waits on its
+ * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
+ * window, eight `waitForURL` timeouts).
+ *
  * Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
  * the client's default (`'memory'`) is lost on reload, and re-establishing the
  * session then needs a credential that survived — this adapter, or an httpOnly

package/dist/browser-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-storage.d.ts","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAA;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,4BAAiC,KACzC,cA6EF,CAAA"}
+{"version":3,"file":"browser-storage.d.ts","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAA;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAA;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAS,4BAAiC,KACzC,cA6EF,CAAA"}

package/dist/browser-storage.js

@@ -22,6 +22,13 @@ const warn = (message, error) => {
 /**
  * The auth client's `StorageAdapter` over the browser's Web Storage.
  *
+ * **The restore it enables costs NO request — never block the first paint on one.** With the
+ * token AND the user in the store, `initialize()` restores the authenticated state synchronously
+ * (`whenRestored()` is already resolved on the first render); render from it, and validate the
+ * token as a background request — never in front of the first render. A page that waits on its
+ * own `/me` call pays a round trip on EVERY navigation (xr-molecule-flash-m122: a 1–5 s restore
+ * window, eight `waitForURL` timeouts).
+ *
  * Pass it as `AuthClientConfig.storage` to keep the session across a page reload:
  * the client's default (`'memory'`) is lost on reload, and re-establishing the
  * session then needs a credential that survived — this adapter, or an httpOnly

package/dist/browser-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser-storage.js","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-storage.js","sourceRoot":"","sources":["../src/browser-storage.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -8,6 +8,43 @@
  * bindings (e.g. `AuthProvider`/`useAuth` in `@molecule/app-react`) wrap the
  * same client.
  *
+ * **In a scaffolded app, wire it by hand — the sandbox cannot run `mlcl add`.**
+ * The package is already installed; create the client once at startup with
+ * `setClient(createJWTAuthClient({ baseURL, authScheme: 'Token', storage:
+ * createBrowserStorageAdapter() }))`, or `createDefaultAuthClient(authConfig)`
+ * from `@molecule/app-bonds-default-react` (which also registers
+ * `whenRestored()` as the HTTP gate), call `initialize()`, and read the session
+ * through `MoleculeProvider`/`useAuth()` in a React app.
+ *
+ * **`initialize()` restores the session BEFORE the first render, and no
+ * hand-rolled token store may replace it.** With the token AND user in the
+ * store the restore is synchronous and costs no request; with an httpOnly
+ * session cookie the API sets at login it restores through
+ * `currentUserEndpoint` (default `/users/me`). `AuthClientConfig.storage` is
+ * the config field that decides which route a reload takes. A store written
+ * beside the client answers requests before its own restore settles: the first
+ * authenticated page renders signed-out, and its 401 signs the user out for
+ * good.
+ *
+ * **Never fetch viewer-dependent data before the restore settles.** A
+ * component effect that runs on mount fires while `initialize()` is still
+ * restoring, so its request leaves without the `Authorization` header and the
+ * server answers for an anonymous viewer — a followed user renders "Follow", a
+ * saved item renders unsaved. On localhost the restore usually wins this race;
+ * over the network it does not, so the bug appears only on the deployed URL.
+ * Gate the fetch on the auth state being settled (`state.initialized`), or let
+ * the HTTP client do it: `@molecule/app-bonds-default-react` registers
+ * `whenRestored()` as the gate so every request waits for the restore.
+ *
+ * **A store that registers its own gate must exempt the restore's own request.**
+ * This client restores with `fetch`, so the gate registered over it never holds
+ * the restore. A store that restores THROUGH the bonded HTTP client and
+ * registers that restore as the gate (`setAuthGate(() => store.whenSettled())`)
+ * waits on itself unless the restore's request passes `skipAuthGate: true` —
+ * otherwise the gate holds the very request it is waiting for, and every
+ * request it holds stalls until the gate times out. See
+ * `RequestConfig.skipAuthGate` in `@molecule/app-http`.
+ *
  * @remarks
  * - **An API with its own auth envelope keeps this client.** `requestBody` wraps the
  *   login/register payload (`(kind, p) => ({ user: p })`), `mapAuthResponse` reads the
@@ -17,38 +54,10 @@
  *   (`setClient(createJWTAuthClient({ authScheme: 'Token', … }))` in the auth bond), not
  *   properties of a client that already exists. Do not hand-write an auth client for a spec
  *   like RealWorld.
- * - **Whether a reload keeps the user signed in is `AuthClientConfig.storage`,
- *   and one of the two routes must be wired.** The client's own default is
- *   `'memory'`, which is lost on reload, so a session survives one only by
- *   having a credential that survived: (1) `storage: createBrowserStorageAdapter()`
- *   — the browser's `localStorage`, what a scaffolded app's `authConfig` passes
- *   (see `@molecule/app-auth`'s `createBrowserStorageAdapter` for the trade: Web
- *   Storage is script-readable, so an XSS can steal the token), or (2) an
- *   httpOnly session cookie the API sets at login, which `initialize()` restores
- *   through `currentUserEndpoint` (default `/users/me`) — the stronger option
- *   wherever the API supports it, and what `@molecule/api-resource-user` issues.
- *   Wire `initialize()` once at startup either way. Do NOT hand-roll a token
- *   store beside the client for this: it is a config field.
  * - **Endpoint defaults must match your API's real routes** (`/auth/login`,
  *   `/auth/register`, `/auth/refresh`, `/users/logout`, `/users/me`, …).
  *   Align them via `createJWTAuthClient({ baseURL, ...endpoints })` — never by
  *   hand-editing fetch calls in components.
- * - **Do not fetch viewer-dependent data before the restore settles.** A component
- *   effect that runs on mount fires while `initialize()` is still restoring, so its
- *   request leaves without the `Authorization` header and the server answers for an
- *   anonymous viewer — a followed user renders "Follow", a saved item renders unsaved.
- *   On localhost the restore usually wins this race; over the network it does not, so
- *   the bug appears only on the deployed URL. Two ways out: gate the fetch on the auth
- *   state being settled (`state.initialized`), or let the HTTP client do it — bond the
- *   auth client through `@molecule/app-bonds-default-react`, which registers
- *   `whenRestored()` as the http gate so every request waits for the restore.
- * - **Your own session store's gate must exempt its restore's own request.** This client
- *   restores with `fetch`, so the gate registered over it never holds the restore. A store
- *   that restores THROUGH the bonded HTTP client and registers that restore as the gate
- *   (`setAuthGate(() => store.whenSettled())`) waits on itself unless the restore's request
- *   passes `skipAuthGate: true` — otherwise the gate holds the very request it is waiting
- *   for, and every request it holds stalls until the gate times out. See
- *   `RequestConfig.skipAuthGate` in `@molecule/app-http`.
  * - Client-side auth state is UX only — the server enforces authorization on
  *   every request; hiding a screen is not protection.
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -8,6 +8,43 @@
  * bindings (e.g. `AuthProvider`/`useAuth` in `@molecule/app-react`) wrap the
  * same client.
  *
+ * **In a scaffolded app, wire it by hand — the sandbox cannot run `mlcl add`.**
+ * The package is already installed; create the client once at startup with
+ * `setClient(createJWTAuthClient({ baseURL, authScheme: 'Token', storage:
+ * createBrowserStorageAdapter() }))`, or `createDefaultAuthClient(authConfig)`
+ * from `@molecule/app-bonds-default-react` (which also registers
+ * `whenRestored()` as the HTTP gate), call `initialize()`, and read the session
+ * through `MoleculeProvider`/`useAuth()` in a React app.
+ *
+ * **`initialize()` restores the session BEFORE the first render, and no
+ * hand-rolled token store may replace it.** With the token AND user in the
+ * store the restore is synchronous and costs no request; with an httpOnly
+ * session cookie the API sets at login it restores through
+ * `currentUserEndpoint` (default `/users/me`). `AuthClientConfig.storage` is
+ * the config field that decides which route a reload takes. A store written
+ * beside the client answers requests before its own restore settles: the first
+ * authenticated page renders signed-out, and its 401 signs the user out for
+ * good.
+ *
+ * **Never fetch viewer-dependent data before the restore settles.** A
+ * component effect that runs on mount fires while `initialize()` is still
+ * restoring, so its request leaves without the `Authorization` header and the
+ * server answers for an anonymous viewer — a followed user renders "Follow", a
+ * saved item renders unsaved. On localhost the restore usually wins this race;
+ * over the network it does not, so the bug appears only on the deployed URL.
+ * Gate the fetch on the auth state being settled (`state.initialized`), or let
+ * the HTTP client do it: `@molecule/app-bonds-default-react` registers
+ * `whenRestored()` as the gate so every request waits for the restore.
+ *
+ * **A store that registers its own gate must exempt the restore's own request.**
+ * This client restores with `fetch`, so the gate registered over it never holds
+ * the restore. A store that restores THROUGH the bonded HTTP client and
+ * registers that restore as the gate (`setAuthGate(() => store.whenSettled())`)
+ * waits on itself unless the restore's request passes `skipAuthGate: true` —
+ * otherwise the gate holds the very request it is waiting for, and every
+ * request it holds stalls until the gate times out. See
+ * `RequestConfig.skipAuthGate` in `@molecule/app-http`.
+ *
  * @remarks
  * - **An API with its own auth envelope keeps this client.** `requestBody` wraps the
  *   login/register payload (`(kind, p) => ({ user: p })`), `mapAuthResponse` reads the
@@ -17,38 +54,10 @@
  *   (`setClient(createJWTAuthClient({ authScheme: 'Token', … }))` in the auth bond), not
  *   properties of a client that already exists. Do not hand-write an auth client for a spec
  *   like RealWorld.
- * - **Whether a reload keeps the user signed in is `AuthClientConfig.storage`,
- *   and one of the two routes must be wired.** The client's own default is
- *   `'memory'`, which is lost on reload, so a session survives one only by
- *   having a credential that survived: (1) `storage: createBrowserStorageAdapter()`
- *   — the browser's `localStorage`, what a scaffolded app's `authConfig` passes
- *   (see `@molecule/app-auth`'s `createBrowserStorageAdapter` for the trade: Web
- *   Storage is script-readable, so an XSS can steal the token), or (2) an
- *   httpOnly session cookie the API sets at login, which `initialize()` restores
- *   through `currentUserEndpoint` (default `/users/me`) — the stronger option
- *   wherever the API supports it, and what `@molecule/api-resource-user` issues.
- *   Wire `initialize()` once at startup either way. Do NOT hand-roll a token
- *   store beside the client for this: it is a config field.
  * - **Endpoint defaults must match your API's real routes** (`/auth/login`,
  *   `/auth/register`, `/auth/refresh`, `/users/logout`, `/users/me`, …).
  *   Align them via `createJWTAuthClient({ baseURL, ...endpoints })` — never by
  *   hand-editing fetch calls in components.
- * - **Do not fetch viewer-dependent data before the restore settles.** A component
- *   effect that runs on mount fires while `initialize()` is still restoring, so its
- *   request leaves without the `Authorization` header and the server answers for an
- *   anonymous viewer — a followed user renders "Follow", a saved item renders unsaved.
- *   On localhost the restore usually wins this race; over the network it does not, so
- *   the bug appears only on the deployed URL. Two ways out: gate the fetch on the auth
- *   state being settled (`state.initialized`), or let the HTTP client do it — bond the
- *   auth client through `@molecule/app-bonds-default-react`, which registers
- *   `whenRestored()` as the http gate so every request waits for the restore.
- * - **Your own session store's gate must exempt its restore's own request.** This client
- *   restores with `fetch`, so the gate registered over it never holds the restore. A store
- *   that restores THROUGH the bonded HTTP client and registers that restore as the gate
- *   (`setAuthGate(() => store.whenSettled())`) waits on itself unless the restore's request
- *   passes `skipAuthGate: true` — otherwise the gate holds the very request it is waiting
- *   for, and every request it holds stalls until the gate times out. See
- *   `RequestConfig.skipAuthGate` in `@molecule/app-http`.
  * - Client-side auth state is UX only — the server enforces authorization on
  *   every request; hiding a screen is not protection.
  *

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-auth",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Client-side authentication interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",