@estiva-app/identity 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @estiva-app/identity
 
+## 0.1.2 — 2026-09-07
+
+**No wire behaviour, no break.** `scheduleRenewal` is new and the guard on
+`refreshAccessToken` only prevents a call that should never have been made, so a
+consumer on `^0.1.0` needs no change — ADR 0002 §4b puts the break on MINOR
+within `0.x`.
+
+Two of SHA-4's five "hard-won behaviour that must survive" items did not, in
+fact, survive — and both for the same reason. They lived in
+`peek-app/src/auth/useEstivaIdAuth.ts`, the `ConvexProviderWithAuth` adapter,
+which is deliberately the one file kept *out* of this package. So Peek kept them
+and Ship, the second consumer whose entire purpose was to catch exactly this,
+silently did not get them. Wiring a second consumer proves a package is not
+shaped like the first app; it does not prove the first app handed everything
+over.
+
+- **`refreshAccessToken` now coalesces concurrent callers.** A refresh token is
+  single-use and Estiva ID reads a replay as theft, revoking the whole chain — so
+  two renewals in the air at once do not waste a round trip, they sign somebody
+  out of everything. Two callers is not hypothetical: Ship signs the NIP-98 auth
+  event and the content event as separate `POST /sign` calls, and a token that
+  expires between them answers `401` to both, each of which renews.
+
+  Peek has had this since PEEK-108 as a `refreshing` ref in its hook. Ship has
+  never had it. It belongs here, where every caller of every consumer gets it
+  without having thought about it. Coalescing, not caching: the promise is
+  dropped the moment it settles, and a test asserts the *next* expiry renews
+  again — a guard that held the promise forever would pass the first test and be
+  a worse bug than the one it fixed.
+
+- **`scheduleRenewal(handlers)` renews before expiry rather than reacting to
+  it.** `tokenFrom` has always stored an expiry 30 seconds early; nothing in the
+  package acted on it. Reacting to expiry means somebody's next action is what
+  discovers the session ended. Renewing early means they notice nothing, which
+  is the whole point of PEEK-108.
+
+  The timer is injected (`setTimer`/`clearTimer`) for the same reason `fetch` and
+  `navigate` are: "we scheduled it" and "we did nothing" are otherwise the same
+  observation. The handle type never reaches the published `.d.ts` — it is
+  `number` in a browser and an object in Node, and naming either fails
+  `check-identity.yml`, correctly.
+
+  **Known limitation, documented here rather than rediscovered per app:** a
+  `setTimeout` is throttled in a background tab — to once a minute in Chrome and
+  Safari, and frozen outright after five minutes hidden — so a backgrounded tab
+  can miss its window. It degrades safely, because the refresh token long
+  outlives the access token: a late renewal is still a renewal, and anything that
+  beats the timer takes the existing `401`-and-retry path. The guard above is
+  what stops the two racing.
+
 ## 0.1.1 — 2026-08-28
 
 **No wire behaviour**, and no break: `pendingStore` is optional and defaults to

package/README.md

@@ -42,6 +42,7 @@ package come out Peek-shaped, which is the whole risk SHA-4 names.
 | `pendingStore` — in-flight PKCE credentials | defaults to `storage` | `sessionStorage`, because the flow starts and ends in one tab |
 | `keyPrefix` | `peek.estivaId` | `ship.estiva-id` |
 | `navigate` | the one genuinely untestable act, so it is observable |  |
+| `setTimer` / `clearTimer` | the timers `scheduleRenewal` runs on, injected for the same reason |  |
 
 **Do not unify the two stores.** NIP-RS read-state slots (CRO-4) must survive a
 restart and belong in `localStorage`; an access token does not. Different
@@ -67,6 +68,44 @@ const client = createEstivaId({
 export const { validToken, beginSignIn, completeSignIn, beginSignOut } = client
 ```
 
+## Renewal is scheduled, not reactive
+
+```ts
+const schedule = client.scheduleRenewal({
+  onRenewed: (token) => setSignedIn(true),
+  onEnded: () => setSignedIn(false),   // drop to the shell
+})
+// later, on sign-out or unmount
+schedule.cancel()
+```
+
+`tokenFrom` stores an expiry 30 seconds early on purpose, and `scheduleRenewal`
+is what acts on it. Reacting to expiry instead means somebody's *next action* is
+what discovers the session is over — a failed publish, a blank list, at best a
+retry they can feel. Renewing early means they notice nothing, which is the whole
+point of PEEK-108.
+
+**Two renewals must never be in the air at once.** A refresh token is single-use
+and Estiva ID reads a replay as evidence of theft, revoking the whole chain — so
+a duplicate renewal does not waste a round trip, it signs somebody out of
+everything. `refreshAccessToken` coalesces concurrent callers into one request,
+and it does so for every caller, not only the scheduler: Ship signs the NIP-98
+auth event and the content event as two separate `POST /sign` calls, and a token
+that expires between them answers `401` to both.
+
+**Known limitation: `setTimeout` is throttled in a background tab.** Chrome and
+Safari clamp a hidden tab's timers to roughly once a minute, and may freeze them
+outright after five minutes hidden, so a backgrounded tab can miss its renewal
+window. This is recorded here rather than rediscovered once per app.
+
+It degrades safely. The refresh token outlives the access token by a long way, so
+a late renewal is still a renewal, and anything that beats the late timer takes
+the existing `401`-and-retry path — which is exactly why the coalescing guard
+above is not an optimisation. A `visibilitychange` listener that re-armed on
+foreground would tighten it and is deliberately absent: `document` is a global
+this package does not touch (ADR 0002 §4a). An app that wants it can `cancel()`
+and call `scheduleRenewal` again.
+
 ## The prediction this package falsified
 
 Before starting, the expectation on the ticket was that identity **could not**

package/dist/client.d.ts

@@ -102,6 +102,14 @@ export interface EstivaIdConfig {
     navigate?: (url: string) => void;
     now?: () => number;
     fetch?: FetchLike;
+    /**
+     * The timers `scheduleRenewal` runs on, injected for exactly the reason
+     * `fetch` and `navigate` are: a test cannot wait ten minutes to find out
+     * whether the renewal was scheduled, and "we scheduled it" and "we did
+     * nothing" are otherwise the same observation.
+     */
+    setTimer?: (run: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
 }
 export interface StoredToken {
     accessToken: string;
@@ -123,6 +131,25 @@ export interface StoredToken {
 }
 export declare class SignInError extends Error {
 }
+/** What a scheduled renewal reports back. Both optional; neither is required to be useful. */
+export interface RenewalHandlers {
+    /** A renewal succeeded. The session continues, on a later expiry. */
+    onRenewed?: (token: StoredToken) => void;
+    /**
+     * A renewal failed, and the session is over.
+     *
+     * The only honest thing an app can do here is drop to the shell. Note this
+     * fires on refusal *and* on an unreachable network — `refreshAccessToken`
+     * distinguishes them for the purpose of clearing the stored token, but from a
+     * scheduler's point of view a renewal that did not happen is a renewal that
+     * did not happen, and the shell's own probe is what sorts out which it was.
+     */
+    onEnded?: () => void;
+}
+export interface RenewalSchedule {
+    /** Stop renewing. Idempotent, and safe to call after the session has ended. */
+    cancel: () => void;
+}
 export interface EstivaIdClient {
     redirectUri: () => string;
     codeChallenge: (verifier: string) => Promise<string>;
@@ -134,6 +161,7 @@ export interface EstivaIdClient {
         returnTo: string;
     }>;
     refreshAccessToken: () => Promise<StoredToken | null>;
+    scheduleRenewal: (handlers?: RenewalHandlers) => RenewalSchedule;
     storedToken: () => StoredToken | null;
     validToken: (now?: number) => StoredToken | null;
     hasSession: () => boolean;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAyB,MAAM,YAAY,CAAA;AAuBxF,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAAA;AAIvE,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CAAA;IACnC;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,aAAa,GAAG,IAAI,CAAA;IACzC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AASzC,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChF,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACrF,kBAAkB,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;IACrD,WAAW,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;IACrC,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,CAAA;IAChD,UAAU,EAAE,MAAM,OAAO,CAAA;IACzB,kBAAkB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC5C,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,gBAAgB,EAAE,MAAM,OAAO,CAAA;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,gBAAgB,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;IAC/C,eAAe,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC1C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAiXrE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -51,6 +51,11 @@
  *   observe where the flow *would* go.
  */
 import { clearGuard, markGuard } from './shell.js';
+/**
+ * `setTimeout`'s ceiling. Above 2^31-1 ms the delay overflows to a negative
+ * int32 and the timer fires immediately.
+ */
+const MAX_TIMER_MS = 2_147_483_647;
 export class SignInError extends Error {
 }
 export function createEstivaId(config) {
@@ -177,6 +182,83 @@ export function createEstivaId(config) {
             s?.removeItem(RETURN_KEY);
         return raw ?? null;
     };
+    /**
+     * Renew the access token without leaving the page (PEEK-108).
+     *
+     * This is the whole reason the grant exists. Before it, an expired token
+     * could only be replaced by a top-level navigation through `/authorize`,
+     * which costs whatever the person had on screen.
+     *
+     * Returns `null` for every failure, and the failures are not worth
+     * distinguishing: Estiva ID answers `invalid_grant` for all of them by
+     * design, and the caller's only move either way is to fall back to the
+     * shell. The stored token is cleared on refusal so a spent refresh token is
+     * never presented twice — a replay is what Estiva ID treats as theft.
+     */
+    const performRefresh = async () => {
+        const s = config.storage();
+        const current = storedToken();
+        if (!s || !current?.refreshToken)
+            return null;
+        let response;
+        try {
+            response = await send()(new URL('/token', config.base).toString(), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    grantType: 'refresh_token',
+                    refreshToken: current.refreshToken,
+                    clientId: config.clientId,
+                }),
+            });
+        }
+        catch {
+            // Unreachable rather than refused. The token in hand may still be fine,
+            // so this deliberately does not clear the session — a flaky network must
+            // not sign somebody out.
+            return null;
+        }
+        if (!response.ok) {
+            clearSession();
+            return null;
+        }
+        const body = (await response.json());
+        if (!body.access_token) {
+            clearSession();
+            return null;
+        }
+        const next = tokenFrom(body, body.pubkey ?? current.pubkey);
+        s.setItem(TOKEN_KEY, JSON.stringify(next));
+        return next;
+    };
+    /**
+     * The renewal in flight, if there is one.
+     *
+     * **A refresh token is single-use and a replay is read as theft**, which
+     * revokes the whole chain — so two renewals must never be in the air at once.
+     * Two easily can be: Ship signs the NIP-98 auth event and the content event as
+     * separate `POST /sign` calls, and a token that expires between them answers
+     * `401` to both, each of which renews.
+     *
+     * Peek has guarded this since PEEK-108 with a `refreshing` ref in its Convex
+     * adapter, and SHA-4 lists the guard as one of the behaviours that must
+     * survive the extraction — but the guard is the one part that did not travel,
+     * because it lived in the hook rather than the client. So Peek kept it and
+     * Ship never had it. It belongs here, where every caller of every consumer
+     * gets it whether or not they thought about it.
+     *
+     * Coalescing rather than caching: the promise is dropped the moment it
+     * settles, so the *next* expiry renews again.
+     */
+    let refreshing = null;
+    const refreshAccessToken = () => {
+        if (refreshing)
+            return refreshing;
+        refreshing = performRefresh().finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
     return {
         redirectUri: config.redirectUri,
         codeChallenge,
@@ -327,54 +409,87 @@ export function createEstivaId(config) {
             clearGuard(s);
             return { token, returnTo };
         },
+        refreshAccessToken,
         /**
-         * Renew the access token without leaving the page (PEEK-108).
+         * Renew shortly **before** the token expires, rather than reacting to it
+         * having expired.
          *
-         * This is the whole reason the grant exists. Before it, an expired token
-         * could only be replaced by a top-level navigation through `/authorize`,
-         * which costs whatever the person had on screen.
+         * SHA-4 lists this as one of the behaviours that must survive the
+         * extraction, and it is the one that reads as an optimisation and is not.
+         * Reacting to expiry means somebody's next action is the thing that
+         * discovers the session is over — a failed publish, a blank list, or at best
+         * a retry they can feel. Renewing 30 seconds early (`tokenFrom` already
+         * subtracts them) means they notice nothing at all.
          *
-         * Returns `null` for every failure, and the failures are not worth
-         * distinguishing: Estiva ID answers `invalid_grant` for all of them by
-         * design, and the caller's only move either way is to fall back to the
-         * shell. The stored token is cleared on refusal so a spent refresh token is
-         * never presented twice — a replay is what Estiva ID treats as theft.
+         * It did not travel with the rest of SHA-4: the timer lived in Peek's Convex
+         * adapter, so Peek kept it and Ship, whose whole point was to be the second
+         * consumer, silently did not get it. Ship renews only when `POST /sign`
+         * answers `401`, which is precisely "on failure".
+         *
+         * ## The timer is a `setTimeout`, and browsers throttle those
+         *
+         * A background tab gets its timers clamped — to once a minute in Chrome and
+         * Safari, and after five minutes of being hidden they may be frozen outright.
+         * So a tab left in the background can miss its renewal window entirely.
+         *
+         * This is a known limitation rather than a bug, and it is recorded here so
+         * it is not rediscovered once per app. It degrades safely: a late renewal is
+         * still a valid renewal, because the refresh token outlives the access token
+         * by a long way, and a call that beats the late timer gets the existing
+         * `401`-and-retry path. What it must not do is renew *twice* in the scramble,
+         * which is what the guard on `refreshAccessToken` is for.
+         *
+         * A `visibilitychange` listener that re-arms on foreground would tighten
+         * this, and is deliberately not here: `document` is a global this package
+         * does not touch (ADR 0002 §4a), and an app that wants it can `cancel()` and
+         * call this again.
          */
-        async refreshAccessToken() {
-            const s = config.storage();
-            const current = storedToken();
-            if (!s || !current?.refreshToken)
-                return null;
-            let response;
-            try {
-                response = await send()(new URL('/token', config.base).toString(), {
-                    method: 'POST',
-                    headers: { 'content-type': 'application/json' },
-                    body: JSON.stringify({
-                        grantType: 'refresh_token',
-                        refreshToken: current.refreshToken,
-                        clientId: config.clientId,
-                    }),
-                });
-            }
-            catch {
-                // Unreachable rather than refused. The token in hand may still be fine,
-                // so this deliberately does not clear the session — a flaky network must
-                // not sign somebody out.
-                return null;
-            }
-            if (!response.ok) {
-                clearSession();
-                return null;
-            }
-            const body = (await response.json());
-            if (!body.access_token) {
-                clearSession();
-                return null;
-            }
-            const next = tokenFrom(body, body.pubkey ?? current.pubkey);
-            s.setItem(TOKEN_KEY, JSON.stringify(next));
-            return next;
+        scheduleRenewal(handlers = {}) {
+            const setTimer = config.setTimer ?? ((run, ms) => setTimeout(run, ms));
+            const clearTimer = config.clearTimer ?? ((handle) => clearTimeout(handle));
+            let handle = null;
+            let cancelled = false;
+            const arm = () => {
+                const token = storedToken();
+                // Nothing to renew. Not an ending — the caller is simply signed out, and
+                // an app that signs in later starts a new schedule.
+                if (!token)
+                    return;
+                /*
+                  Clamped at both ends. A negative delay is a token that already expired
+                  — renew now rather than never, since the refresh token almost certainly
+                  has not. The ceiling is `setTimeout`'s: a delay above 2^31-1 ms
+                  overflows to a negative int32 and fires immediately, so a nonsensical
+                  `expires_in` would otherwise become a hot loop against `/token` instead
+                  of one very distant timer.
+                */
+                const delay = Math.min(Math.max(0, token.expiresAt - now()), MAX_TIMER_MS);
+                handle = setTimer(() => {
+                    handle = null;
+                    void refreshAccessToken().then((next) => {
+                        if (cancelled)
+                            return;
+                        if (!next) {
+                            handlers.onEnded?.();
+                            return;
+                        }
+                        handlers.onRenewed?.(next);
+                        // Re-armed from the *new* expiry rather than a fixed interval, so
+                        // the schedule follows whatever lifetime Estiva ID actually issued.
+                        arm();
+                    });
+                }, delay);
+            };
+            arm();
+            return {
+                cancel() {
+                    cancelled = true;
+                    if (handle !== null) {
+                        clearTimer(handle);
+                        handle = null;
+                    }
+                },
+            };
         },
         /**
          * Leave for Estiva ID to end the session *there* (PEEK-122).

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -46,7 +46,7 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export declare const IDENTITY_VERSION = "0.1.1";
+export declare const IDENTITY_VERSION = "0.1.2";
 export { type KeyValueStore, type ShellPhase, type ShellReason, type ShellState, type BootObservation, type BootAction, type ShellEvent, isRecoverable, SHELL_COPY, CONTINUE_LABEL, RETRY_LABEL, PROBE_TIMEOUT_MS, GUARD_TTL_MS, GUARD_KEY, decideBoot, reasonForCallbackError, readGuard, markGuard, clearGuard, logShellEvent, } from './shell.js';
-export { type EstivaIdConfig, type EstivaIdClient, type StoredToken, type FetchLike, SignInError, createEstivaId, } from './client.js';
+export { type EstivaIdConfig, type EstivaIdClient, type StoredToken, type FetchLike, type RenewalHandlers, type RenewalSchedule, SignInError, createEstivaId, } from './client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -46,7 +46,7 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export const IDENTITY_VERSION = '0.1.1';
+export const IDENTITY_VERSION = '0.1.2';
 export { isRecoverable, SHELL_COPY, CONTINUE_LABEL, RETRY_LABEL, PROBE_TIMEOUT_MS, GUARD_TTL_MS, GUARD_KEY, decideBoot, reasonForCallbackError, readGuard, markGuard, clearGuard, logShellEvent, } from './shell.js';
 export { SignInError, createEstivaId, } from './client.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO,EAQL,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAKL,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO,EAQL,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAOL,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/identity",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Estiva ID sign-in: authorization code + PKCE, token storage, silent renewal, sign-out, and the auth-shell state machine. Knows nothing about any app's data layer.",
   "license": "MIT",
   "type": "module",

package/src/client.ts

@@ -73,6 +73,19 @@ declare const URL: {
 }
 declare const URLSearchParams: { new (init: string): { get(name: string): string | null } }
 
+/**
+ * The timer pair, for {@link EstivaIdClient.scheduleRenewal}.
+ *
+ * Declared here for the same reason as everything above, and returning
+ * `unknown` for one more: the handle's real type is `number` in a browser and an
+ * object in Node, and naming either would put an ambient type in the published
+ * `.d.ts` — which `check-identity.yml` fails the build over, correctly. Nothing
+ * outside this module ever sees a handle; `scheduleRenewal` hands back a
+ * `cancel` function instead.
+ */
+declare const setTimeout: (run: () => void, ms: number) => unknown
+declare const clearTimeout: (handle: unknown) => void
+
 /** Just enough of `fetch` to redeem a code. A parameter as well as a global. */
 export type FetchLike = (
   url: string,
@@ -122,6 +135,14 @@ export interface EstivaIdConfig {
   navigate?: (url: string) => void
   now?: () => number
   fetch?: FetchLike
+  /**
+   * The timers `scheduleRenewal` runs on, injected for exactly the reason
+   * `fetch` and `navigate` are: a test cannot wait ten minutes to find out
+   * whether the renewal was scheduled, and "we scheduled it" and "we did
+   * nothing" are otherwise the same observation.
+   */
+  setTimer?: (run: () => void, ms: number) => unknown
+  clearTimer?: (handle: unknown) => void
 }
 
 export interface StoredToken {
@@ -143,8 +164,35 @@ export interface StoredToken {
   refreshToken?: string
 }
 
+/**
+ * `setTimeout`'s ceiling. Above 2^31-1 ms the delay overflows to a negative
+ * int32 and the timer fires immediately.
+ */
+const MAX_TIMER_MS = 2_147_483_647
+
 export class SignInError extends Error {}
 
+/** What a scheduled renewal reports back. Both optional; neither is required to be useful. */
+export interface RenewalHandlers {
+  /** A renewal succeeded. The session continues, on a later expiry. */
+  onRenewed?: (token: StoredToken) => void
+  /**
+   * A renewal failed, and the session is over.
+   *
+   * The only honest thing an app can do here is drop to the shell. Note this
+   * fires on refusal *and* on an unreachable network — `refreshAccessToken`
+   * distinguishes them for the purpose of clearing the stored token, but from a
+   * scheduler's point of view a renewal that did not happen is a renewal that
+   * did not happen, and the shell's own probe is what sorts out which it was.
+   */
+  onEnded?: () => void
+}
+
+export interface RenewalSchedule {
+  /** Stop renewing. Idempotent, and safe to call after the session has ended. */
+  cancel: () => void
+}
+
 interface TokenResponse {
   access_token?: string
   expires_in?: number
@@ -158,6 +206,7 @@ export interface EstivaIdClient {
   beginSignIn: (returnTo: string, options?: { silent?: boolean }) => Promise<void>
   completeSignIn: (search: string) => Promise<{ token: StoredToken; returnTo: string }>
   refreshAccessToken: () => Promise<StoredToken | null>
+  scheduleRenewal: (handlers?: RenewalHandlers) => RenewalSchedule
   storedToken: () => StoredToken | null
   validToken: (now?: number) => StoredToken | null
   hasSession: () => boolean
@@ -300,6 +349,88 @@ export function createEstivaId(config: EstivaIdConfig): EstivaIdClient {
     return raw ?? null
   }
 
+  /**
+   * Renew the access token without leaving the page (PEEK-108).
+   *
+   * This is the whole reason the grant exists. Before it, an expired token
+   * could only be replaced by a top-level navigation through `/authorize`,
+   * which costs whatever the person had on screen.
+   *
+   * Returns `null` for every failure, and the failures are not worth
+   * distinguishing: Estiva ID answers `invalid_grant` for all of them by
+   * design, and the caller's only move either way is to fall back to the
+   * shell. The stored token is cleared on refusal so a spent refresh token is
+   * never presented twice — a replay is what Estiva ID treats as theft.
+   */
+  const performRefresh = async (): Promise<StoredToken | null> => {
+    const s = config.storage()
+    const current = storedToken()
+    if (!s || !current?.refreshToken) return null
+
+    let response: Awaited<ReturnType<FetchLike>>
+    try {
+      response = await send()(new URL('/token', config.base).toString(), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          grantType: 'refresh_token',
+          refreshToken: current.refreshToken,
+          clientId: config.clientId,
+        }),
+      })
+    } catch {
+      // Unreachable rather than refused. The token in hand may still be fine,
+      // so this deliberately does not clear the session — a flaky network must
+      // not sign somebody out.
+      return null
+    }
+
+    if (!response.ok) {
+      clearSession()
+      return null
+    }
+
+    const body = (await response.json()) as TokenResponse
+    if (!body.access_token) {
+      clearSession()
+      return null
+    }
+
+    const next = tokenFrom(body, body.pubkey ?? current.pubkey)
+    s.setItem(TOKEN_KEY, JSON.stringify(next))
+    return next
+  }
+
+  /**
+   * The renewal in flight, if there is one.
+   *
+   * **A refresh token is single-use and a replay is read as theft**, which
+   * revokes the whole chain — so two renewals must never be in the air at once.
+   * Two easily can be: Ship signs the NIP-98 auth event and the content event as
+   * separate `POST /sign` calls, and a token that expires between them answers
+   * `401` to both, each of which renews.
+   *
+   * Peek has guarded this since PEEK-108 with a `refreshing` ref in its Convex
+   * adapter, and SHA-4 lists the guard as one of the behaviours that must
+   * survive the extraction — but the guard is the one part that did not travel,
+   * because it lived in the hook rather than the client. So Peek kept it and
+   * Ship never had it. It belongs here, where every caller of every consumer
+   * gets it whether or not they thought about it.
+   *
+   * Coalescing rather than caching: the promise is dropped the moment it
+   * settles, so the *next* expiry renews again.
+   */
+  let refreshing: Promise<StoredToken | null> | null = null
+
+  const refreshAccessToken = (): Promise<StoredToken | null> => {
+    if (refreshing) return refreshing
+    refreshing = performRefresh().finally(() => {
+      refreshing = null
+    })
+    return refreshing
+  }
+
+
   return {
     redirectUri: config.redirectUri,
     codeChallenge,
@@ -464,58 +595,95 @@ export function createEstivaId(config: EstivaIdConfig): EstivaIdClient {
       return { token, returnTo }
     },
 
+    refreshAccessToken,
+
     /**
-     * Renew the access token without leaving the page (PEEK-108).
+     * Renew shortly **before** the token expires, rather than reacting to it
+     * having expired.
+     *
+     * SHA-4 lists this as one of the behaviours that must survive the
+     * extraction, and it is the one that reads as an optimisation and is not.
+     * Reacting to expiry means somebody's next action is the thing that
+     * discovers the session is over — a failed publish, a blank list, or at best
+     * a retry they can feel. Renewing 30 seconds early (`tokenFrom` already
+     * subtracts them) means they notice nothing at all.
+     *
+     * It did not travel with the rest of SHA-4: the timer lived in Peek's Convex
+     * adapter, so Peek kept it and Ship, whose whole point was to be the second
+     * consumer, silently did not get it. Ship renews only when `POST /sign`
+     * answers `401`, which is precisely "on failure".
      *
-     * This is the whole reason the grant exists. Before it, an expired token
-     * could only be replaced by a top-level navigation through `/authorize`,
-     * which costs whatever the person had on screen.
+     * ## The timer is a `setTimeout`, and browsers throttle those
      *
-     * Returns `null` for every failure, and the failures are not worth
-     * distinguishing: Estiva ID answers `invalid_grant` for all of them by
-     * design, and the caller's only move either way is to fall back to the
-     * shell. The stored token is cleared on refusal so a spent refresh token is
-     * never presented twice — a replay is what Estiva ID treats as theft.
+     * A background tab gets its timers clamped — to once a minute in Chrome and
+     * Safari, and after five minutes of being hidden they may be frozen outright.
+     * So a tab left in the background can miss its renewal window entirely.
+     *
+     * This is a known limitation rather than a bug, and it is recorded here so
+     * it is not rediscovered once per app. It degrades safely: a late renewal is
+     * still a valid renewal, because the refresh token outlives the access token
+     * by a long way, and a call that beats the late timer gets the existing
+     * `401`-and-retry path. What it must not do is renew *twice* in the scramble,
+     * which is what the guard on `refreshAccessToken` is for.
+     *
+     * A `visibilitychange` listener that re-arms on foreground would tighten
+     * this, and is deliberately not here: `document` is a global this package
+     * does not touch (ADR 0002 §4a), and an app that wants it can `cancel()` and
+     * call this again.
      */
-    async refreshAccessToken(): Promise<StoredToken | null> {
-      const s = config.storage()
-      const current = storedToken()
-      if (!s || !current?.refreshToken) return null
-
-      let response: Awaited<ReturnType<FetchLike>>
-      try {
-        response = await send()(new URL('/token', config.base).toString(), {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({
-            grantType: 'refresh_token',
-            refreshToken: current.refreshToken,
-            clientId: config.clientId,
-          }),
-        })
-      } catch {
-        // Unreachable rather than refused. The token in hand may still be fine,
-        // so this deliberately does not clear the session — a flaky network must
-        // not sign somebody out.
-        return null
+    scheduleRenewal(handlers: RenewalHandlers = {}): RenewalSchedule {
+      const setTimer = config.setTimer ?? ((run, ms) => setTimeout(run, ms))
+      const clearTimer = config.clearTimer ?? ((handle) => clearTimeout(handle))
+
+      let handle: unknown = null
+      let cancelled = false
+
+      const arm = (): void => {
+        const token = storedToken()
+        // Nothing to renew. Not an ending — the caller is simply signed out, and
+        // an app that signs in later starts a new schedule.
+        if (!token) return
+
+        /*
+          Clamped at both ends. A negative delay is a token that already expired
+          — renew now rather than never, since the refresh token almost certainly
+          has not. The ceiling is `setTimeout`'s: a delay above 2^31-1 ms
+          overflows to a negative int32 and fires immediately, so a nonsensical
+          `expires_in` would otherwise become a hot loop against `/token` instead
+          of one very distant timer.
+        */
+        const delay = Math.min(Math.max(0, token.expiresAt - now()), MAX_TIMER_MS)
+
+        handle = setTimer(() => {
+          handle = null
+          void refreshAccessToken().then((next) => {
+            if (cancelled) return
+            if (!next) {
+              handlers.onEnded?.()
+              return
+            }
+            handlers.onRenewed?.(next)
+            // Re-armed from the *new* expiry rather than a fixed interval, so
+            // the schedule follows whatever lifetime Estiva ID actually issued.
+            arm()
+          })
+        }, delay)
       }
 
-      if (!response.ok) {
-        clearSession()
-        return null
-      }
+      arm()
 
-      const body = (await response.json()) as TokenResponse
-      if (!body.access_token) {
-        clearSession()
-        return null
+      return {
+        cancel(): void {
+          cancelled = true
+          if (handle !== null) {
+            clearTimer(handle)
+            handle = null
+          }
+        },
       }
-
-      const next = tokenFrom(body, body.pubkey ?? current.pubkey)
-      s.setItem(TOKEN_KEY, JSON.stringify(next))
-      return next
     },
 
+
     /**
      * Leave for Estiva ID to end the session *there* (PEEK-122).
      *

package/src/index.ts

@@ -46,7 +46,7 @@
  * The thing that made it possible was not cleverness — it was that a browser API
  * an app must inject is also a browser API a test can observe.
  */
-export const IDENTITY_VERSION = '0.1.1'
+export const IDENTITY_VERSION = '0.1.2'
 
 export {
   type KeyValueStore,
@@ -76,6 +76,8 @@ export {
   type EstivaIdClient,
   type StoredToken,
   type FetchLike,
+  type RenewalHandlers,
+  type RenewalSchedule,
   SignInError,
   createEstivaId,
 } from './client.js'